Delivery guarantees

Quality of Service is the delivery contract for a single message: how hard the sender works to be certain the receiver got it, and what the receiver may have to tolerate in return. MQTT defines three levels, and the choice trades certainty against round trips.

QoS is agreed per hop, not end to end. A publisher agrees a level with the broker, and the broker agrees a level with each subscriber separately; a publisher cannot dictate how its message is delivered onward. Exactly-once semantics from one application to another therefore require QoS 2 on both hops. For a walkthrough of each handshake, see the MQTT QoS guide.

QoS 1 is the pragmatic default for most deployments: one extra packet buys guaranteed arrival, but a retransmission after a lost acknowledgement means the receiver may see the same message twice — so consumers on QoS 1 have to be idempotent. QoS 2 removes that possibility through a four-packet handshake, and earns its overhead only where processing a duplicate does real damage: a billing event, an actuation command. QoS 0 is the right answer wherever the next value supersedes the last one anyway, and it is the cheapest by a wide margin.

TBMQ stores an incoming PUBLISH durably before acknowledging it. A publisher’s PUBACK (QoS 1) or PUBREC (QoS 2) therefore means the message has been safely recorded — not that any subscriber has received it. Everything after that point (matching subscriptions, queueing per subscriber, writing to the network) happens once the publisher has already moved on, so a broker node that fails mid-delivery does not lose an acknowledged message.

That guarantee is only as strong as the durability of the store behind it, which ships configured to keep a single copy; a deployment that must survive losing a node of that store has to run it replicated. QoS 0 has no acknowledgement at all, so a QoS 0 message lost on the network before it reaches the broker is simply gone.

When the publisher’s level and the subscriber’s level differ, delivery happens at the lower of the two. A QoS 2 subscription does not upgrade a QoS 0 publish, and a QoS 2 publish is delivered at QoS 0 to a subscriber that asked for QoS 0 — so design against the level actually delivered, not the level subscribed with.

This has a direct consequence for offline delivery: since a QoS 0 publish is delivered at QoS 0 to everyone, nothing is queued for it even for subscribers holding a persistent session. Offline queuing needs QoS 1 or QoS 2 on both sides plus a persistent session; without one, undelivered messages are discarded when the client disconnects regardless of QoS.

For the packet-by-packet flows, per-level use cases, and how TBMQ tracks in-flight messages, see Quality of Service and the architecture overview.