MQTT support
The gateway serves MQTT 3.1.1 and 5.0. Compatibility lists the clients and test suites that we test the gateway with.
Supported
| Feature | 3.1.1 | 5.0 | Notes |
|---|---|---|---|
| QoS 0 | yes | yes | Core NATS |
| QoS 1 and 2 | yes | yes | Only on topics that a binding stores |
Wildcard subscriptions (+, #) | yes | yes | |
Shared subscriptions ($share/) | yes | yes | The gateway grants QoS 1 at most |
| Retained messages | yes | yes | Needs a retained bucket |
| Persistent sessions | yes | yes | Needs a sessions bucket |
| Session takeover | yes | yes | Works across gateways that share the sessions bucket |
| Wills | yes | yes | A QoS 1 or 2 will needs a bound topic |
| Will Delay Interval | yes | ||
| Server-assigned client ID | yes | yes | |
| Username and password | yes | yes | The listener maps them to a NATS user |
| TLS and mutual TLS | yes | yes | |
| WebSocket | yes | yes | |
| Message Expiry Interval | yes | ||
| User Properties | yes | The gateway sends them as NATS headers | |
| Content Type, Response Topic, Correlation Data | yes | The gateway sends them as NATS headers | |
| Payload Format Indicator | yes | ||
| Subscription Identifiers | yes | ||
| No Local | yes | ||
| Retain Handling, Retain As Published | yes | ||
| Topic aliases | yes | ||
| Receive Maximum | yes | ||
| Maximum Packet Size | yes | ||
| Server Keep Alive | yes | Set it with mqtt.server-keepalive | |
| Server Reference on shutdown | yes | Set it with mqtt.server-reference | |
| Reason codes and reason strings | yes | See Errors | |
| Sparkplug B 3.0 | yes | yes | See Run Sparkplug B clients |
Not supported
- Enhanced authentication (the v5 AUTH packet)
- Request/Response Information (v5)
- QoS 2 shared subscriptions. The gateway grants QoS 1 instead.
- The
$SYS/broker statistics topics - A queue of QoS 0 messages for an offline client
Things to know
- QoS 1 and 2 need a binding. The gateway refuses a QoS 1 or 2 publish to a topic that no binding stores. It does not change the publish to QoS 0.
- One consumer per session per stream. Each session with a QoS 1 or
2 subscription holds one JetStream consumer on each stream that it
reads. The
max_consumerslimit of a stream sets how many of these sessions the stream can serve. The default is 1,000. Past that limit, the gateway refuses the subscription. - Duplicates after a failure. After a lost connection or a failed gateway, a QoS 1 or 2 message can arrive again. The second copy can arrive after later messages. If a client must not process a message twice, the client should discard duplicates.
- Topics are subjects. The topic
a/b/cis the NATS subjecta.b.c.+is*, and#is>. See MQTT mapping.