MQTT acknowledgements are ordered — hivemq-mqtt-client holds a PUBACK back until every earlier message has been acknowledged, for compliance with the protocol.

A message held through a MongoDB outage therefore blocks every acknowledgement behind it; the broker’s in-flight window fills (20 messages with Mosquitto’s defaults) and it stops delivering to this client at all, live SSE consumers included. Holding acknowledgements until the database takes the message puts MongoDB in the critical path of every consumer, which is the opposite of what this module is for.

MqttMongoOutageIT pins the behaviour: with MongoDB stopped, forty messages — twice that window — still reach an SSE client, and all forty are written once it is back.

The buffer is memory. A kill -9, an OOM or a power cut loses what is in it, and the broker will not redeliver because it was told the messages were taken.

That is the trade, stated plainly: this is telemetry-grade durability, not a transactional queue. Deployments that cannot lose a message at all need a queue in front of RESTHeart.

The writer retries the batch it is holding for as long as it runs, with an exponential backoff capped at 30 s, and the messages that keep arriving accumulate in the buffer. Nothing is dropped and nothing is dead-lettered: an unreachable database is not the documents' fault.

When the buffer reaches either of its ceilings — capacity, 10000 messages, or max-bytes, 64 MB — the writer stops taking messages from the router and the broker, which is backpressure working as intended.

Where the messages queue then is the broker. Mosquitto holds max_queued_messages per client, 1000 by default, and discards beyond that. So the reserve available during an outage is the buffer plus the broker’s queue, and sizing the broker is part of configuring persistence: without it, messages are lost in the broker while RESTHeart is still healthy.

It stops taking messages first — what arrives from then on is left unacknowledged, so the broker keeps it for the next instance — and then drains the buffer into MongoDB for up to drain.shutdown-timeout-ms (5 s by default, deliberately inside Docker’s 10 s SIGTERM grace).

What that budget does not cover is lost, and logged as such; in practice that means RESTHeart being stopped while MongoDB is also down.

RESTHeart has no plugin shutdown callback, so the client and the writer’s drain loop are stopped from JVM shutdown hooks. A kill -9 runs no hook at all and loses the buffer.

Three things are required for it to hold up to the buffer:

id-strategy settles what a redelivery does. At-least-once means the same message can be received twice — after a reconnect that resumes a session mid-flight, for instance — and payload-field keys the document on something the message itself carries, so the second reception overwrites the first instead of adding a copy. Leaving id-strategy at auto means every redelivery is a new document.

A broker redelivers everything a resumed session owes the moment it sends CONNACK. Anything not listening at that instant loses those messages.

The module registers consumers at three different moments — mqtt-client builds the client, mqtt-router registers the global publish consumer, mqtt-mongo-writer registers its durable listener at AFTER_STARTUP — so mqtt-connector exists purely to connect after all of them. It is enabled by default so nobody has to remember it; disabling it leaves a module that never reaches the broker, and mqtt-status reports that.

If publishers publish the latest state retained, the broker replays it on the SUBSCRIBE this module issues at every startup, and the cache is correct immediately.

Measured: with a retained value, GET /mqtt answers 200 straight after a restart with nothing republished; without one, 404.

A non-retained publish does not clear a retained value; an empty retained message does (mosquitto_pub -r -n -t <topic>), and it also removes the topic from this module’s cache at once.

Each is counted so it is visible rather than silent: the router’s global rate limit, the SSE per-connection queue, and a pipeline’s throttle stage. For a dashboard that is the right answer — you want the latest reading, not a backlog.

mqtt-mongo-writer’s buffer defaults to `blocking-queue, which applies backpressure instead; ring-buffer and drop-incoming are there for anyone who would rather drop than slow down, and must be chosen explicitly.

Backpressure is cheap here because the router dispatches each message on its own virtual thread, so a full buffer parks a virtual thread rather than a platform one.

MQTT 3.1.1 lets a broker deliver one copy of a message per matching subscription, and Mosquitto does exactly that. Since the router matches every incoming message against every registered filter locally, it subscribes on the broker only to filters no other registered filter already covers — so sensors/# in mqtt-router.subscriptions plus an SSE client on sensors/temp is one broker subscription, not two, and one delivery, not two.

A covering filter is subscribed at the highest QoS of anything it covers, so standing in for a durable QoS 1 subscription never quietly downgrades it to QoS 0.

Without this, the configuration these docs recommend duplicated every message: two SSE events, two callbacks into a custom plugin, two MongoDB documents under id-strategy: auto, and a doubled mqtt_router_messages_received.

It used to cut before the fan-out, so a number chosen to protect a dashboard silently governed what reached storage as well. It now applies to live listeners only — SSE connections and plugins' subscribe listeners.

The last-value cache behind mqtt-rest is updated before the limit is checked, and a message refused for live delivery is still handed to mqtt-mongo-writer and still persisted. mqtt_router_messages_dropped therefore counts live drops, and mqtt_router_messages_received counts everything the broker delivered — the two overlap deliberately, so their ratio is the live loss rate.

On MQTT 3.1.1 there are no shared subscriptions, so every RESTHeart node receives every message. For MongoDB persistence that means payload-field is the only strategy that converges: it is the one keyed on something the message itself carries, so all the nodes compute the same _id.

On MQTT 5.0, shared subscriptions are the cleaner answer — tracked in #602.

It is enforced end to end: a request for a topic filter granted by the ACL subscribes normally, and a request for an ungranted filter is rejected with 403 and a body of {"msg":"Not authorized for topic: <filter>"} before it ever reaches the router.