[feat] Tracking issue MQTTv5 #821

The features that doesn't require changes on persistences are:

• Reason code on all ACKs #822 — landed in feat: MQTT 5.0 reason codes & reason strings on ACKs (#822, #823, #1092) #1100
• Reason string on all ACKs #823 — partial (Reason String on PUBACK/PUBREC only; feat: MQTT 5.0 reason codes & reason strings on ACKs (#822, #823, #1092) #1100)
• Message expiry: the lifetime of the Will Message in seconds #824
• Server disconnect #825
• Payload format and content type (this should be already handled by mqtt-packet we just have to forward it) #826
• Request / Response #827
• Subscription id (persistence addSubscription stores the entire sub packet so we don't have to make edits on that side) #828 — partial
• Flow control #829 — partial
• User properties (this should be already handled by mqtt-packet we just have to forward it) #830
• Maximum Packet Size #831
• Optional Server feature availability #832
• Enhanced authentication #833
• Subscription options: I think this should already be implemented, expecially the noLocal flag but we should check this #834
• Will delay: checking the putWill we store the entire packet in persistence so no change is needed on that part #835
• Server Keep Alive #836
• Assigned ClientID #837
• Server reference #838 — Server Reference (landed in feat: MQTT 5.0 Server Reference / connect-time redirect (#838) [stacked on #1102] #1115)
• Request / Response Information (CONNECT 0x19 → CONNACK 0x1A) #1091 — Request / Response Information (landed in feat: MQTT 5.0 Request / Response Information (#1091) [stacked on #1100] #1102)
• Request Problem Information (CONNECT 0x17) #1092 — Request Problem Information (landed in feat: MQTT 5.0 reason codes & reason strings on ACKs (#822, #823, #1092) #1100; gates Reason string on all ACKs #823/User properties (this should be already handled by mqtt-packet we just have to forward it) #830)

The ones that require changes on persistences:

• Session expiry: we actually don't have storage support for this #839 — partial (in-memory only; no cross-restart durability)
• Shared subscriptions #841 — single-instance only (not cluster-safe)
• Topic alias #840 — inbound only (topic alias is per-connection; doesn't actually need persistence)

Development status — mqttv5 branch / PR #1088

Most of MQTT 5.0 has landed on the mqttv5 branch: #1088 (feat/mqtt5) was merged on 2026-06-30 (merge commit e7d0ce9) after eight rounds of review. MQTT 3.1/3.1.1 behaviour is unchanged. Tests live in test/mqtt5.js (40 tests, driving a real mqtt@5 client over TCP). Note: #1088 targeted mqttv5, not the default branch, so the per-feature issues it referenced are not auto-closed — the checklist above tracks their status until mqttv5 merges to release under #194.

Companion releases (resolved): the gating packages are published and package.json now points at published ranges — aedes-packet@^4.0.1 (moscajs/aedes-packet#192 — preserve properties/messageExpiry) and aedes-persistence@^10.3.1 (moscajs/aedes-persistence#108 — persist subscriptionIdentifier). The overrides shim has been removed; the scripts/check-no-git-deps.js release guard is no longer blocked (no git deps remain).

Update — PR #1100 (2026-07-03): granular ACK reason codes (#822), Reason Strings on ACKs (#823), and Request Problem Information gating (#1092) landed on mqttv5 (merge 0f59242). A denied v5 PUBLISH now returns 0x87 (Not authorized) on PUBACK/PUBREC with the handler's error.message as the Reason String — suppressed when the client connected with Request Problem Information = 0 ([MQTT-3.1.2-29]); a denied v5 SUBSCRIBE returns SUBACK 0x87; PUBREL/PUBCOMP carry a Success reason code; and a rejecting PUBREC (≥ 0x80) terminates the QoS 2 flow without a PUBREL, releasing the stored outgoing packet id ([MQTT-5.0 §4.3.3]). Reason Strings are wired on PUBACK/PUBREC only — SUBACK/UNSUBACK/PUBREL/PUBCOMP still omit them, so #823 remains partial. A pinned Eclipse Paho interoperability workflow (tools/mqtt-compat/) tracks the conformance % (MQTT 5.0 at 62%, MQTT 3.1.1 at 100%).

Update — PR #1102 (2026-07-06): Request / Response Information (#1091) landed on mqttv5 (merge a025504). When a client sets Request Response Information on CONNECT ([MQTT-3.1.2-28], §3.1.2.11.6), the broker returns Response Information in the CONNACK (§3.2.2.3.15, server MAY) — but only when the new broker option responseInformation is configured (a static string or a (client) => string | undefined function for a per-client base; null default = never returned). Returned only on a successful CONNACK; a resolver that throws degrades to omit + surfaces on the clientError event. Broker-core only — no persistence changes, cluster-safe.

Update — PR #1115 (2026-07-06): Server Reference / connect-time redirect (#838) landed on mqttv5 (merge 8fb6bdc). A preConnect/authenticate hook can redirect a v5 client by rejecting with an error carrying a serverReference (and an optional reasonCode): the rejection CONNACK then carries 0x9C (Use another server) — or 0x9D (Server moved) when the hook sets err.reasonCode — plus the serverReference property (§4.11). A serverReference paired with a non-redirect reason code is clamped to 0x9C, and the property is dropped for non-v5 clients. Mid-session redirect already worked via client.disconnect({ reasonCode, properties: { serverReference } }) — now covered by a test. Broker-core only — no persistence changes, cluster-safe.

Persistence & cluster classification

The features split three ways by what they touch beyond the broker core:

A. Need aedes-packet changes (the packet object that travels through the emitter + persistence must preserve the new fields): property pass-through — #826, #827, #830 — and Message Expiry #824 (messageExpiry must survive storage/forwarding). Covered by moscajs/aedes-packet#192.

B. Need aedes-persistence changes (and round-trip support in the mongodb / redis / level implementations):

• Subscription id (persistence addSubscription stores the entire sub packet so we don't have to make edits on that side) #828 Subscription Identifier — must be stored per-subscription and round-tripped by every backend (feat: persist MQTT 5.0 subscription identifier aedes-persistence#108; backends already store the whole packet, so a conformance test rather than backend code is expected).
• Session expiry: we actually don't have storage support for this #839 Session Expiry — needs a persisted expiry deadline + a restart-time reaper. Not done — currently in-memory timers only.
• Shared subscriptions #841 Shared Subscriptions — needs addSharedSubscription/group-membership storage; cluster-correct delivery additionally needs global group state in mongodb/redis.

C. No persistence change — broker core / per-connection: #822, #823, #825, #829, #831, #832, #833, #834, #836, #837, #838, #840.

Special cluster handling required:

• Shared subscriptions #841 Shared subscriptions — group membership is per-instance, so a shared message is delivered once per instance holding a group member instead of once cluster-wide. Cluster-correct delivery needs global membership + deterministic recipient selection coordinated via the persistence/emitter layer (mqemitter-redis/-mongodb).
• Session expiry: we actually don't have storage support for this #839 Session Expiry & Will delay: checking the putWill we store the entire packet in persistence so no change is needed on that part #835 Will Delay — enforced by per-instance in-memory timers; not durable across a broker restart or coordinated across the cluster (needs persisted deadlines + a reaper).
• Everything else is cluster-safe as-is: per-connection features (Maximum Packet Size #831/Server Keep Alive #836/Assigned ClientID #837/Topic alias #840/Server disconnect #825/Flow control #829/Enhanced authentication #833/Server reference #838, reason codes) are local to the owning instance; property forwarding (Payload format and content type (this should be already handled by mqtt-packet we just have to forward it) #826/Request / Response #827/User properties (this should be already handled by mqtt-packet we just have to forward it) #830), Subscription Identifiers (Subscription id (persistence addSubscription stores the entire sub packet so we don't have to make edits on that side) #828, attached at delivery by the subscribing instance) and message/retained expiry (Message expiry: the lifetime of the Will Message in seconds #824, absolute timestamps carried on the packet) ride the shared emitter + persistence correctly.

Conformance review (vs. OASIS MQTT 5.0)

Status: ✅ implemented & conformant · 🟡 partial · ❌ missing · ⚠️ non-conformant.
Persistence: pkt = needs aedes-packet · persist = needs aedes-persistence (+ mongodb/redis/level) · — = core only.
Cluster: ✅ cluster-safe · ⚠️ per-instance only / needs care · ❌ not cluster-safe.

Triage — complete in #1088 vs. defer

Principle: fix in #1088 anything where the PR already advertises or accepts a capability but then mishandles it (spec violation / misleading behavior). Defer net-new scope, persistence-schema, and cluster work. Legend: 🔧 #1088 · 🤔 judgment · ⏭️ defer.

✅ Completed in #1088 (landed in ceed520, verified against source):

1. Retain Handling 1/2 (Subscription options: I think this should already be implemented, expecially the noLocal flag but we should check this #834) — [MQTT-3.8.3-2]. rh=2 no longer sends retained on subscribe; rh=1 only for a brand-new subscription (subscribe.js).
2. $share → 0x9E rejection (Shared subscriptions #841) — [MQTT-3.2.2-23]. A v5 $share/... SUBSCRIBE is refused with 0x9E instead of becoming a dead literal subscription.
3. Inbound DISCONNECT Session-Expiry validation (Server disconnect #825/Session expiry: we actually don't have storage support for this #839) — [MQTT-3.14.4-3]. A non-zero Session Expiry on DISCONNECT is rejected when CONNECT declared 0.
4. Reject unsupported Authentication Method 0x8C (Enhanced authentication #833 guard) — §4.12. A CONNECT carrying authenticationMethod is rejected with 0x8C instead of a silent password downgrade.
5. Retained-on-subscribe SI echo (Subscription id (persistence addSubscription stores the entire sub packet so we don't have to make edits on that side) #828, part) — [MQTT-3.3.4]. Retained deliveries now carry the SUBSCRIBE Subscription Identifier.
6. Response Topic wildcard validation — [MQTT-3.3.2-14]. A PUBLISH with a wildcard Response Topic is rejected.

✅ Landed in #1100 (mqttv5, merge 0f59242):

7. Granular ACK reason codes (Reason code on all ACKs #822) — PUBACK/PUBREC 0x87, SUBACK 0x87 (v5), PUBREL/PUBCOMP Success, and rejecting-PUBREC QoS 2 termination with packet-id release ([MQTT-5.0 §4.3.3]).
8. Reason String on ACKs (Reason string on all ACKs #823, partial) — handler error.message surfaced on PUBACK/PUBREC.
9. Request Problem Information gating (Request Problem Information (CONNECT 0x17) #1092) — [MQTT-3.1.2-29]. Reason String suppressed on PUBACK/PUBREC when the client set RPI = 0.

✅ Landed in #1102 (mqttv5, merge a025504):

10. Request / Response Information (Request / Response Information (CONNECT 0x19 → CONNACK 0x1A) #1091) — [MQTT-3.1.2-28] / §3.2.2.3.15. CONNACK Response Information returned when the client requests it and the new broker responseInformation option is set (static string or per-client function; null default = never). A throwing resolver degrades to omit + clientError.

✅ Landed in #1115 (mqttv5, merge 8fb6bdc):

11. Server Reference / connect-time redirect (Server reference #838) — §4.11. preConnect/authenticate redirect via an error carrying serverReference → rejection CONNACK 0x9C (Use another server) / 0x9D (Server moved); a non-redirect reason code paired with a reference is clamped to 0x9C; property dropped for non-v5 clients. Mid-session redirect via client.disconnect({ reasonCode, properties: { serverReference } }).

🤔 Judgment call:

• Multiple matching SIs collapsed to one (Subscription id (persistence addSubscription stores the entire sub packet so we don't have to make edits on that side) #828) — [MQTT-3.3.4-4]. Strictly, one delivery should carry all matching subscription identifiers; dedupe() drops all but one. The fix reaches into the dedupe/delivery core (medium effort, real regression surface, low real-world hit rate). Lean: defer with a documented limitation + dedicated issue, unless strict conformance is wanted now.

⏭️ Defer to follow-ups (net-new scope / persistence / cluster / spec-optional):

• Shared subscriptions #841 full cluster-aware shared subscriptions — sharedsubs rewrite + global group state in mqemitter-redis/-mongodb.
• Session expiry: we actually don't have storage support for this #839 cross-restart session-expiry persistence — schema + mongodb/redis/level round-trip + reaper.
• Flow control #829 outbound Receive Maximum enforcement — invasive to the shared delivery hot path; advisory-only documented.
• Enhanced authentication #833 full enhanced auth (AUTH packet flow).
• Topic alias #840 outbound Topic Alias — spec-optional. (Reason code on all ACKs #822 granular ACK reason codes landed in feat: MQTT 5.0 reason codes & reason strings on ACKs (#822, #823, #1092) #1100; Reason string on all ACKs #823 Reason String on ACKs landed partial in feat: MQTT 5.0 reason codes & reason strings on ACKs (#822, #823, #1092) #1100 — PUBACK/PUBREC only, remaining ACK types outstanding.)

(#1091 Request / Response Information landed in #1102; #1092 Request Problem Information landed in #1100, now gating #823.)

Status generated from a spec-conformance audit of mqttv5 @ PR #1088 head (276cb2e), updated for #1100 (0f59242), #1102 (a025504) and #1115 (8fb6bdc). Shared-subscription code currently lives on the separate sharedsubs branch (single-instance, pre-v5). Items marked 🟡/❌/⚠️ are the remaining work toward full v5 conformance (#194).