Sessions and message delivery

Start with non-retained QoS 1 messages from the quickstart. Then test the behaviors your application depends on using a private RunMQTT Broker and the same SDK, plan and transport as production.

Connection identity and reconnects

A Client ID identifies a connection and its session; it is not an authorization boundary. Credentials and template policies determine access. Concurrent clients must use different IDs. A persistent client must reuse its own stable ID when reconnecting, rather than generate a new ID on every restart.

Use a keepalive such as 60 seconds for the first test. Reconnect a lost transport with exponential backoff and random jitter, for example increasing the delay from one second up to 30 seconds. Limit queued application work while offline. Stop blind retries on authentication or policy errors and repair the credentials or permissions first.

Persistent sessions and offline delivery

In MQTT.js with MQTT 5, the expiry option is properties: { sessionExpiryInterval: 3600 }. This is a requested session lifetime, not a promise of unlimited storage. Inspect sessionPresent on CONNACK. If false, establish subscriptions again and handle any data gap; the old session was not resumed.

Verify recovery in this order:

1. Connect a subscriber with the persistent settings and subscribe to demo/hello at QoS 1. Wait for SUBACK and subscription activation.
2. Disconnect it without resetting the session or setting its expiry to zero.
3. From a separate authorized client, publish a uniquely identified QoS 1 message to demo/hello.
4. Reconnect with the same ID and settings before expiry. Record sessionPresent and whether the queued message arrives.
5. Repeat beyond the requested expiry and confirm your application can recover when no session is present.

Offline queues are not a database or a replay service. Do not promise a retention duration or queue size without validating the target Broker. QoS 0 is unsuitable when queued offline delivery is required. An MQTT acknowledgement confirms a protocol exchange, not completion of your subscriber's business operation.

Retained state

Retained messages are available on Growth and Scale. Use them for a latest state snapshot, not an event history or a one-time command. With publish and subscribe permissions on demo/state, use the TLS environment from the quickstart:

mosquitto_pub -h "$MQTT_HOST" -p 8883 --tls-use-os-certs \
  -u "$MQTT_USERNAME" -P "$MQTT_PASSWORD" -i state-publisher \
  -q 1 -t 'demo/state' -m '{"status":"online"}' -r

Start a fresh ordinary subscriber to demo/state after the publisher exits. It should receive the saved payload without a new publish. Clear the retained value by repeating the publish command with -n -r instead of -m '{"status":"online"}' -r, then verify with another fresh subscriber that the old payload is gone.

A RunMQTT validation run observed retained payload replay with an unexpected false retain packet flag. Validate both replay and the flag if your application relies on it. Keep event timestamps or versions in the payload to identify stale state.

Last Will

Authorize the connecting device to publish demo/status, and authorize an observer to subscribe to it. Connect the device with Will topic demo/status, payload offline, QoS 1 and retain false. For Mosquitto, add --will-topic 'demo/status' --will-payload 'offline' --will-qos 1 to a long-running subscriber command from the quickstart.

Start the observer first. Force-stop only your test client's process without a graceful MQTT DISCONNECT, then wait for network failure or keepalive detection. The observer should receive offline. Repeat with a normal MQTT disconnect: it should not produce that Will. Network detection is not instantaneous. Retaining a Will also requires retained-message support.

Production acceptance

Test duplicate delivery, process crashes after receipt, session expiry, temporary network loss and credential revocation. Include event IDs, timestamps and an idempotency key in business payloads; validate JSON and handle malformed messages. Keep durable business work in your own storage. For parallel consumers, also test the boundaries in shared subscriptions.