feat: MQTT 5.0 support

[BenjaminDobler]

What

Adds MQTT 5.0 support to the broker (closes #194, addresses tracking issue #821). MQTT 3.1/3.1.1 behaviour is unchanged throughout. Implemented incrementally; each feature is exercised end-to-end against a real mqtt@5 client over TCP in test/mqtt5.js.

Implemented

• Handshake & framing — accept protocolVersion: 5; protocol-version-aware write path so v5 reason codes and properties are serialized; CONNACK uses a reason code (mapped from the legacy return codes)
• Property pass-through — v5 PUBLISH properties (user properties, content type, response topic, correlation data, payload format) forwarded to subscribers
• Topic Alias (inbound) + CONNACK topicAliasMaximum advertisement
• Subscription Identifiers — echoed on matching PUBLISHes; persisted for non-clean sessions
• Session Expiry Interval — cleanStart vs persistence decoupled; broker timers keep / wipe / expire sessions; reconnect cancels expiry
• Server-initiated DISCONNECT — reason code 0x8E on session takeover, 0x8B on broker shutdown
• Will Delay Interval — will published after the delay (capped by session expiry); cancelled if the client reconnects
• DISCONNECT with Will (reason 0x04)
• UNSUBACK reason codes (0x00 / 0x11)
• Message Expiry Interval — expired queued/retained messages dropped; remaining lifetime recomputed on delivery
• Retained-message expiry + retained messages now carry their v5 properties
• Shared Subscriptions ($share/{group}/{filter}) — one-of-group round-robin delivery; normal subscribers of the same filter unaffected (⚠️ single-instance only — see cluster note below)
• Maximum Packet Size — broker option advertised in CONNACK; oversized inbound packets rejected with DISCONNECT 0x95
• Receive Maximum — advertised in CONNACK
• Not-authorized acks — unauthorized v5 QoS > 0 publishes answered with 0x87 PUBACK/PUBREC instead of dropping the connection
• Assigned Client Identifier — returned in the CONNACK when the broker generates an id for a client that connects with an empty client id
• Server Keep Alive — a v5 client whose keepalive is unset or above keepaliveLimit is not rejected; the broker imposes its limit via the CONNACK serverKeepAlive property
• Types & docs — new broker options (topicAliasMaximum, maximumPacketSize, receiveMaximum) added to the AedesOptions type and documented in docs/Aedes.md

Deliberately out of scope (follow-ups)

• Shared subscriptions in clusters — the current implementation is single-instance only (see cluster note); cluster-correct delivery needs global group membership + deterministic recipient selection coordinated via the persistence layer
• Receive Maximum enforcement (outbound in-flight window) — invasive to the shared delivery hot path; advertised only, with existing drainTimeout providing transport backpressure
• Enhanced authentication (AUTH packet) — Enhanced authentication #833
• Reason string on ACKs (Reason string on all ACKs #823); broader ACK reason codes such as 0x10 no-matching-subscribers (Reason code on all ACKs #822)
• Server reference (Server reference #838)
• Cross-restart / clustered durability of session-expiry & will-delay timers (needs persisted timestamps + reaper, touching the persistence backends)

Note on clusters

@robertsLando flagged that shared subscriptions aren't cluster-compatible — correct. Group state is per-instance, so in a clustered deployment a shared message is delivered once per instance holding a group member instead of once across the cluster. The rest of the v5 work is cluster-safe (subscription identifiers and message/retained expiry are persistence-backed; topic alias and max-packet-size are per-connection; session-expiry and will-delay use per-instance timers, same durability caveat as today's sessions but not incorrect per instance). Open question in the thread on whether to split shared subscriptions into a cluster-aware follow-up PR.

⚠️ Dependencies — needs companion releases before merge

This depends on:

• feat: preserve MQTT 5.0 properties and message-expiry on packet wrapping aedes-packet#192 — preserve properties + messageExpiry
• feat: persist MQTT 5.0 subscription identifier aedes-persistence#108 — persist subscriptionIdentifier (+ a conformance test confirming all backends already round-trip it, so no backend code change is required)

package.json currently points aedes-packet / aedes-persistence at the fork branches (with an overrides shim) so this branch installs and runs standalone for review. Before merge, once the two companion packages are released, this flips to published ranges and the shim is removed:

• aedes-packet: github:…#feat/mqtt5-properties → ^<new version>
• aedes-persistence: github:…#feat/mqtt5 → ^<new version>
• remove the overrides: { "aedes-packet": "$aedes-packet" } block

Opened as a draft until the above are resolved.

Tests

test/mqtt5.js (24 tests) drives a real mqtt@5 client over TCP. Full suite green (lint + tsd + unit), 0 failures / 0 cancelled.

🤖 Generated with Claude Code

[robertsLando]

Hi @BenjaminDobler and thanks for looking at this long awaited feature! Let me know when you need a review of this, This may require also changes on mongofb and redis persistences

[robertsLando]

The issue with current implementation is that it's not compatible with clusters, aedes can also be run in clusters and the whole shared topics logics is single instance right now

[BenjaminDobler]

Thanks @robertsLando! A couple of things:

Status / dependencies. This is a draft because it depends on two companion PRs — moscajs/aedes-packet#192 (preserve properties + messageExpiry) and moscajs/aedes-persistence#108 (persist subscriptionIdentifier). Once those are released I'll flip aedes's package.json from the fork branches to published ranges, drop the overrides shim, and mark this ready for review.

Persistence backends. I checked redis, mongodb and level — they actually need no code changes: they serialize the whole subscription object (so subscriptionIdentifier round-trips) and preserve the internal messageExpiry via aedes-packet's Packet wrapper. I added a subscriptionIdentifier round-trip test to aedes-persistence/abstract.js (in #108) so the shared conformance suite verifies this on every backend.

Clusters / shared subscriptions. You're right, and thanks for catching it. The shared-subscription group state is per-instance (a local mq.on listener + local round-robin), so in a clustered setup a shared message gets delivered once per instance holding a group member instead of once across the whole cluster. The rest of the v5 work is cluster-safe (sub identifiers and message/retained expiry are persistence-backed; topic alias and max-packet-size are per-connection; session-expiry and will-delay use per-instance timers, so same restart/cluster durability caveat as today's sessions, but not incorrect per instance). Cluster-correct shared subs need global group membership + deterministic recipient selection coordinated through the persistence layer, which is a larger design.

How would you prefer to handle it? Options I see:

1. Split shared subscriptions into a separate follow-up PR so the cluster-safe v5 core can land now, and design cluster-aware shared subs separately (with your input on the coordination approach). I'd flip sharedSubscriptionAvailable back to false here until then.
2. Keep it here, scoped/documented as single-instance-only.
3. Tackle the cluster-aware design as part of this PR.

My lean is (1), but happy to go whichever way you prefer.