Repository navigation
HMQ v4.0.0
This release adds an explicitly bounded MQTT 5.0 profile alongside MQTT 3.x,
including mixed-version delivery and embedded quorum-cluster forwarding.
Breaking Changes
- The Go module is now
github.com/fhmq/hmq/v4. Update imports from/v3. - Broker, session and topic APIs use
github.com/fhmq/hmq/v4/broker/packets.
Publications and forwarding callbacks now carry the broker's protocol-neutral
publish model, including properties, expiry and publisher identity. External
Paho MQTT 3 publish structs are no longer interchangeable with this model. - Initial CONNECT packets are bounded to 1 MiB for every protocol version.
Subsequent MQTT 3 wire behavior remains unchanged. - Go 1.27.3 or newer remains required. Existing tags are preserved.
MQTT 5
- Detect MQTT 5 CONNECT on the existing TCP, TLS and WebSocket listeners.
- Support QoS 0/1/2 in ordinary memory mode, mixed MQTT 3/5 publish-subscribe,
assigned client IDs, username/password authentication and negative ACKs. - Add No Local, Retain As Published, Retain Handling, subscription identifiers,
per-filter unsubscribe reasons and connection-scoped incoming topic aliases. - Preserve user properties, content type, payload format, response topic and
correlation data through routing, retained storage and cluster replication. - Enforce message expiry before new live, retained and queued deliveries;
persist metadata through retained and offline-session storage. - Respect Receive Maximum, with an additional 128-publication inflight cap and
a waiting queue bounded to 256 messages / 4 MiB per MQTT 5 connection. - Check exact outbound packet sizes before allocating an encoded packet or
writing bytes. An oversized subscriber delivery is discarded without leaking
credit or disconnecting an unrelated publisher. - Validate bounded framing, variable integers, property lengths and contexts,
duplicate singleton properties, UTF-8, reserved flags, identifiers and reason
direction before handing packets to Eclipse Paho's MQTT 5 codec.
Deliberate Limits
- This is not a claim of complete MQTT 5 feature conformance. Session Expiry is
explicitly negotiated to zero; MQTT 5 session resumption is not implemented.
Clean Start=false with an existing session is refused with CONNACK 0x83,
preserving the existing active or saved session instead of deleting it. - Enhanced AUTH is unavailable and rejected with CONNACK 0x8C. Existing
username/password authentication and ACLs remain available. - The server's MQTT 5 maximum packet size is 1 MiB and alias maximum is 32.
Outbound topics are sent in full. MQTT 5 has no same-connection timer retries. - Immediate session expiry bounds Will delay. Message expiry across replicas
assumes synchronized clocks. - Quorum remains experimental, single-partition and limited to clean online
QoS0/1 operation, without retained or shared subscriptions. The corresponding
MQTT 5 capability flags advertise these restrictions. Local session storage
also limits inbound MQTT 5 publications to QoS1.
See broker/MQTT5.md and the existing cluster operational documentation before
deployment. Sample mock authentication is not production authentication.
Verification
- Full uncached race-enabled regression,
go vet ./..., and diff checks. - Real-socket MQTT 3/5 interoperability, QoS exchanges, flow-control and queue
ordering, negative PUBREC, aliases, subscription options, packet-size boundaries,
Will properties, message expiry and session-preserving refusal tests. - Real three-node quorum test: follower publication, commit acknowledgment,
cross-node delivery and application-property preservation. - Decoder fuzzing and metadata isolation, expiry and restart-recovery tests.
govulncheckreports no reachable or imported-package vulnerabilities with
the required toolchain. The previously disclosed unusedx/crypto/openpgp
module-level advisory remains; this is not a zero-module-advisory claim.- Release automation validates container startup and produces five platform
archives with SHA256 checksums. Check the release workflow and assets for
their final publication status.
Install after publication with:
go install github.com/fhmq/hmq/v4@v4.0.0