Skip to content

MQTT5_DESIGN.md

Latest commit

 

History

History
197 lines (146 loc) · 7.63 KB

MQTT5_DESIGN.md

File metadata and controls

197 lines (146 loc) · 7.63 KB
Raw

MQTT 5.0 Support Design (Proposed)

This document outlines a practical path to add MQTT 5.0 support alongside existing 3.1.1 support, with interoperability as the primary goal. It is a design/reference guide and does not reflect current code behavior unless explicitly stated.

Goals

  • Support MQTT 3.1.1 and 5.0 on the same listener using the CONNECT protocol version byte.
  • Preserve current behavior for 3.1.1 clients.
  • Be interoperable with common clients and brokers (Mosquitto as behavioral reference).
  • Expose broker configuration to constrain or enable MQTT 5.0 features.

Current Status (Implemented)

  • CONNECT/CONNACK reason codes + properties for 5.0.
  • PUB*/SUB*/UNSUB* reason codes/properties handling.
  • Session expiry, message expiry, will delay, topic alias, receive maximum, maximum packet size.
  • Response topic / correlation data / content type / payload format indicator parsing and propagation.
  • User properties for PUBLISH/SUBSCRIBE/DISCONNECT.
  • AUTH packet parsing/encoding with optional enhanced auth hooks (IEnhancedAuthenticator).

Version Detection and Policy

Detection is based on the CONNECT Protocol Level / Version byte:

  • 3.1.1 uses level 4.
  • 5.0 uses level 5.

Policy:

  • Allow a per-broker list of supported versions.
  • If CONNECT uses an unsupported version, respond with the correct return code/reason code and disconnect.

Class-Level Impact Map

Protocol codec and messages:

  • org.red5.server.mqtt.codec.MQTTDecoder
    • Must become version-aware after parsing CONNECT.
    • Must parse MQTT 5.0 properties and variable byte integer property lengths.
    • Must enforce Maximum Packet Size per connection.
  • org.red5.server.mqtt.codec.MQTTEncoder
    • Must include reason codes and properties on outgoing packets for 5.0 clients.
  • org.red5.server.mqtt.codec.parser.*
    • All *Decoder/*Encoder classes need to be updated for 5.0 property blocks and reason codes.
    • ConnectDecoder / ConnAckEncoder are first to change.
  • org.eclipse.moquette.proto.messages.*
    • Add 5.0 fields and property containers to message types.
    • Introduce reason code enums where required.

Broker logic and session:

  • org.eclipse.moquette.spi.impl.ProtocolProcessor
    • Must handle 5.0 features: session expiry, message expiry, will delay, reason codes.
  • org.eclipse.moquette.spi.impl.SimpleMessaging
    • Maintain per-session constraints (max packet size, receive maximum, topic alias max).
  • org.red5.server.mqtt.net.MQTTHandler
    • Must store negotiated protocol version + limits on session attributes.

Persistence:

  • org.eclipse.moquette.spi.persistence.MapDBPersistentStore
    • Persist new session fields and message properties.
    • Extend StoredPublishEvent to carry message expiry, content type, response topic, correlation data, user properties, payload format indicator.

Data Model Extensions (Proposal)

New session state (persisted):

  • protocolVersion (3.1.1 or 5.0)
  • sessionExpiryInterval
  • receiveMaximum
  • maximumPacketSize
  • topicAliasMaximum
  • clientId (possibly assigned)
  • willDelayInterval
  • userProperties (if used for will or session)

New message fields (persisted for queued/inflight/retained):

  • messageExpiryInterval
  • payloadFormatIndicator
  • responseTopic
  • correlationData
  • contentType
  • userProperties

Protocol Feature Coverage

Minimum interoperability set (Phase 1/2):

  • CONNECT/CONNACK with properties and reason codes.
  • PUBLISH + PUBACK/PUBREC/PUBREL/PUBCOMP reason codes.
  • SUBSCRIBE/SUBACK and UNSUBSCRIBE/UNSUBACK reason codes.
  • DISCONNECT reason codes.

Advanced features (Phase 3):

  • Session Expiry Interval
  • Message Expiry Interval
  • Will Delay Interval
  • Topic Alias
  • Receive Maximum
  • Maximum Packet Size
  • Subscription Identifiers
  • User Properties
  • Response Topic / Correlation Data
  • AUTH (enhanced auth)

Configuration Additions (Proposed)

These are intended as new MQTTBroker properties:

  • supportedProtocolVersions (list, default: 3.1.1,5.0)
  • defaultProtocolVersion (optional, for tests)
  • maximumPacketSize (broker-side limit; per-connection override by client)
  • receiveMaximumDefault (limit QoS 1/2 inflight)
  • topicAliasMaximum
  • sessionExpiryIntervalDefault
  • messageExpiryIntervalDefault
  • maximumQoS (CONNACK Maximum QoS)
  • retainAvailable (CONNACK Retain Available)
  • wildcardSubscriptionAvailable (CONNACK Wildcard Subscription Available)
  • subscriptionIdentifierAvailable (CONNACK Subscription Identifier Available)
  • sharedSubscriptionAvailable (CONNACK Shared Subscription Available)
  • serverKeepAlive (CONNACK Server Keep Alive)
  • allowAnonymous or authMode (if auth gets expanded)

Staged Rollout Plan

Phase 0: Prep

  • Add protocol version tracking to session attributes in MQTTHandler.
  • Add configuration plumbing for supported versions and defaults.

Implementation Status Snapshot (Jan 30, 2026)

Implemented:

  • CONNECT/CONNACK MQTT 5.0 reason codes + property length parsing.
  • CONNACK properties: session expiry, receive maximum, maximum QoS, retain available, maximum packet size, topic alias max, wildcard/subscription-id/shared availability, server keep alive, reason string, user properties.
  • Enhanced AUTH exchange (AUTH/CONNACK handling with an IEnhancedAuthenticator).
  • PUBLISH properties: expiry interval, payload format indicator, content type, response topic, correlation data, topic alias, user properties.
  • PUBACK/PUBREC/PUBREL/PUBCOMP: reason code/string + user properties.
  • SUBSCRIBE: user properties + subscription identifier.
  • SUBACK: reason string + user properties.
  • UNSUBSCRIBE: user properties.
  • UNSUBACK: reason string + user properties.
  • DISCONNECT: reason string + user properties.
  • Topic alias enforcement (max + alias map).
  • Receive maximum (inflight gating) and maximum packet size (outbound size check).
  • Subscription identifiers forwarded in outbound PUBLISH (per-subscriber).

Planned / Partially Implemented:

  • Will properties beyond will delay (payload format indicator, content type, response topic, correlation data, user properties).
  • Server-side enforcement of subscription identifier availability flag (currently just advertised via CONNACK).
  • Shared subscriptions behavior (flag exposed, routing not implemented).
  • Assigned client identifier + response information generation (properties encoded/decoded but not set by broker).
  • Response information and server reference usage (encoded/decoded only).

Phase 1: CONNECT/CONNACK

  • Parse 5.0 CONNECT properties; encode CONNACK with reason codes.
  • Enforce supportedProtocolVersions policy.
  • Add parsing for property length (variable byte integer).

Phase 2: Core publish/subscribe flow

  • Support 5.0 reason codes + properties in PUB*/SUB* flows.
  • Enforce receiveMaximum and maximumPacketSize.

Phase 3: Persistence-aware features

  • Persist session expiry, message expiry.
  • Implement will delay, message expiry.
  • Implement topic alias, response topic/correlation data.

Phase 4: Interop testing and tuning

  • Validate with Mosquitto clients (pub/sub, properties, reason codes).
  • Validate interoperability against common 5.0 clients.

Interoperability Checklist (Partial)

  • Correct handling of protocol version byte in CONNECT.
  • Reason codes included for 5.0 clients.
  • Properties parsed and ignored safely when not used.
  • Session expiry and message expiry enforced.
  • Max packet size and receive maximum enforced.

Notes for Implementers

  • Keep 3.1.1 code paths isolated to avoid regressions.
  • Reject unsupported 5.0 features explicitly when required by the spec.
  • Consider adding a compatibility shim to map 5.0 fields into existing data structures where possible.

See mqtt/IMPLEMENTERS.md for the version negotiation overview and implementation notes.