Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / mqtt-protocol-gateway

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:

  1. Resolve the project from the platform database. An empty project ID or the console project uses the platform project record.
  2. Validate an appwrite-jwt or appwrite-session credential against the project user store. A JWT must belong to the selected project, unless it is an older session-bound token.
  3. Reject missing, invalid, blocked, or inactive identities. The check also requires the session's factors when a session is present.
  4. Keep token expiry, session expiry, and the next session recheck time with the connection identity.
  5. Apply the connection rate limit when abuse protection is enabled.
  6. 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 roleDelivery targetGateway responsibility
MQTT adapterConnected MQTT clientsPublish an event to the shared broker channel
External push adapterA provider such as a mobile push serviceDeliver through the provider's service contract
MQTT broker handlerLocal MQTT connectionsAuthenticate, 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

TriggerConsequenceGuard
Invalid project ID or credentialCONNECT is refused as not authorizedProject and user resolution must return a valid identity, and JWTs must match the selected project
Blocked user, expired credential, or inactive sessionThe client cannot connect or re-authenticateUser status, credential expiry, session state, and required factors are checked during authentication and later authorization
CONNECT abuse limit exceededThe connection is refused with a quota errorRedis-backed per-user rate limiting protects the CONNECT path
Topic authorizer or role check failsThe requested topic is denied in SUBACKBoth topic access policy and user roles must allow the filter
Shared mqtt channel is unavailableConnected clients do not receive produced messagesThe broker retries its pub/sub connection and reports failure
No local subscriber matches a produced topicThe event is dropped by that broker workerThe shared channel fans out to every broker worker
PUBACK does not advance the replay cursorReconnects can replay already delivered messagesThe cursor advances only for a known delivery and higher sequence

Key files

FileWhy to read it
app/mqtt.phpShows the MQTT process, resource setup, broker construction, and shared-channel listener.
app/…/connection.phpDefines project and user authentication plus topic authorization resources.
src/…/Handler.phpDefines Appwrite's connection, subscription, replay, acknowledgment, and delivery policy.
src/…/Mqtt.phpDefines how messaging workers publish MQTT delivery events.
bin/mqttShows the process entry command for the MQTT gateway.