MQTT protocol gateway
The MQTT protocol gateway gives Appwrite clients a live, authenticated path to receive project messages. It accepts MQTT connections over TCP or WebSocket, checks the project and user identity, controls topic access, and sends messages produced by the messaging system to local subscribers. The gateway also keeps enough state to resume QoS 1 messages after a client reconnects. For the wider platform model, see API platform and Messaging API.
Gateway role
The gateway separates MQTT protocol work from message production. The broker manages MQTT connection state and delivery rules, while Appwrite policy decides who may connect and subscribe. A shared pub/sub channel links messaging workers to every broker worker so a message can reach clients connected to any worker.
The gateway starts as a dedicated process through bin/mqtt, which runs the MQTT entrypoint at app/mqtt.php. The entrypoint exposes TCP on port 1883 and WebSocket access on the configured WebSocket port, then starts the broker with the Appwrite handler.
The main message path is:
flowchart LR
M[Messaging worker] --> A[MQTT messaging adapter]
A --> P[Shared mqtt channel]
P --> B[MQTT broker worker]
B --> H[Appwrite MQTT handler]
H --> C[Authenticated client]
References: bin/mqtt• L1-3 app/mqtt.php• L177-188 app/mqtt.php• L194-243 src/…/Mqtt.php• L11-18
Connection initialization
Connection initialization turns MQTT connection data into an Appwrite identity. The client supplies a project ID as a user property and a supported credential as MQTT authentication data. The gateway resolves the project and user before it accepts the connection, then keeps credential and session expiry data for later checks.
The initialization flow uses these checks:
- Resolve the project from the platform database. An empty project ID or the
consoleproject uses the platform project record. - Validate an
appwrite-jwtorappwrite-sessioncredential against the project user store. A JWT must belong to the selected project, unless it is an older session-bound token. - Reject missing, invalid, blocked, or inactive identities. The check also requires the session's factors when a session is present.
- Keep token expiry, session expiry, and the next session recheck time with the connection identity.
- Apply the connection rate limit when abuse protection is enabled.
- Set the client ID. A missing client ID receives a stable account-level fallback.
The resulting identity carries the project ID and user ID into later subscribe and delivery decisions. Later authorization checks reject expired credentials and re-check that the user remains enabled and that the session remains active with its required factors.
sequenceDiagram
participant Client
participant Broker as MQTT broker
participant Auth as Appwrite auth resources
participant DB as Project data
Client->>Broker: CONNECT with project and credential
Broker->>Auth: Resolve project and user
Auth->>DB: Read project and user state
DB-->>Auth: Project and user result
Auth-->>Broker: Identity or rejection
Broker-->>Client: CONNACK
References: app/…/connection.php• L15-190 src/…/Handler.php• L44-89 src/…/Handler.php• L91-116
Topic access
Topic access connects an authenticated identity to project topic policy. A client can request several topic filters, but the gateway grants only topics that pass both the connection-level authorizer and the topic's subscribe roles.
The gateway reads the user's roles and the topic records from the project database. It returns a per-topic grant with a QoS that does not exceed either the client's request or the topic policy. The broker then owns the active subscription index.
An accepted QoS 1 subscription can also start offline replay. The gateway uses the client identity and client ID as a session key, resumes from the stored topic cursor, and sends the available recent messages with the duplicate flag. A later PUBACK advances the cursor so the next connection can continue from the acknowledged point.
References: src/…/Handler.php• L118-179 src/…/Handler.php• L220-241 src/…/Handler.php• L253-333
Message delivery
Message delivery bridges the messaging system's project topics to MQTT subscribers. The MQTT adapter publishes one shared-channel event for each target topic, with the project, binary payload, QoS, and sequence. Each broker worker listens to that channel and delivers the event only to its own local subscribers.
The adapter does not create or remove MQTT subscriptions. The broker records subscriptions from successful SUBACK responses, while the adapter remains the producer side of the delivery contract. This keeps connection state local to the broker and lets any messaging worker reach all broker workers through the shared channel.
When a broker receives an event, the handler looks up matching subscribers and clamps message QoS to each granted subscription. It records a drop when no local subscriber exists. The handler ignores client PUBLISH packets because this gateway supports server-to-client push rather than client-to-server message publishing.
References: src/…/Mqtt.php• L30-89 app/mqtt.php• L183-188 app/mqtt.php• L194-243 src/…/Handler.php• L181-218
Push provider adapters
MQTT participates in the broader messaging adapter contract as a server-side delivery target. A messaging worker selects an adapter for a delivery channel, and the MQTT adapter turns that delivery into a broker event. This is different from external push providers, which send the same message intent through provider-specific delivery paths.
The shared messaging model lets provider adapters receive project, event, channel, role, and message data without making the MQTT broker aware of other providers. MQTT-specific data stays in the adapter options, where the binary payload, QoS, and delivery sequence travel with the event.
The relationship between the adapter types is:
| Adapter role | Delivery target | Gateway responsibility |
|---|---|---|
| MQTT adapter | Connected MQTT clients | Publish an event to the shared broker channel |
| External push adapter | A provider such as a mobile push service | Deliver through the provider's service contract |
| MQTT broker handler | Local MQTT connections | Authenticate, authorize, replay, and fan out |
References: src/…/Mqtt.php• L3-16 src/…/Mqtt.php• L43-85 src/…/Handler.php• L203-218
Resource scope
The MQTT entrypoint prepares request resources per coroutine so one connection does not reuse another connection's project data. It provides cache, platform database, project database, Redis, authentication, and topic authorization resources to the handler. The authentication and authorization resources use the selected project and current session state for each connection check.
The platform database resolves project records. The project database reads users, topics, and the push ledger. Cache stores replay cursors, and Redis supports connection abuse limits. These resources give protocol callbacks the project context they need without changing the broker's generic MQTT responsibilities.
References: app/mqtt.php• L39-172 app/…/connection.php• L16-190 src/…/Handler.php• L335-346
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the project ID carried by CONNECT, the authenticated identity, and the project database lookup aligned. A mismatch can authorize a user in one project and read topics from another.
- Keep the shared-channel event fields aligned between
Mqtt::send()and the broker listener. Payload encoding, QoS, and sequence are part of the delivery contract. - Keep topic grants, broker subscription state, and per-subscription QoS aligned. A change in one layer can silently widen access or change delivery guarantees.
- Keep replay cursor keys, client ID fallback rules, ledger sequence values, and PUBACK handling aligned. These values control whether reconnecting clients receive duplicate or missed messages.
- Keep MQTT listener startup and pub/sub reconnect behavior aligned. A broker can accept clients while delivery events are unavailable if the shared subscription cannot recover.
- Keep JWT project binding, token expiry, session expiry, and session recheck timing aligned. A change can allow a credential to outlive its project or session state.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Invalid project ID or credential | CONNECT is refused as not authorized | Project and user resolution must return a valid identity, and JWTs must match the selected project |
| Blocked user, expired credential, or inactive session | The client cannot connect or re-authenticate | User status, credential expiry, session state, and required factors are checked during authentication and later authorization |
| CONNECT abuse limit exceeded | The connection is refused with a quota error | Redis-backed per-user rate limiting protects the CONNECT path |
| Topic authorizer or role check fails | The requested topic is denied in SUBACK | Both topic access policy and user roles must allow the filter |
Shared mqtt channel is unavailable | Connected clients do not receive produced messages | The broker retries its pub/sub connection and reports failure |
| No local subscriber matches a produced topic | The event is dropped by that broker worker | The shared channel fans out to every broker worker |
| PUBACK does not advance the replay cursor | Reconnects can replay already delivered messages | The cursor advances only for a known delivery and higher sequence |
Key files
| File | Why to read it |
|---|---|
| app/mqtt.php | Shows the MQTT process, resource setup, broker construction, and shared-channel listener. |
| app/…/connection.php | Defines project and user authentication plus topic authorization resources. |
| src/…/Handler.php | Defines Appwrite's connection, subscription, replay, acknowledgment, and delivery policy. |
| src/…/Mqtt.php | Defines how messaging workers publish MQTT delivery events. |
bin/mqtt | Shows the process entry command for the MQTT gateway. |