All notable changes to this project will be documented in this file.

[0.13.0] - 2026-11-04

Added

  • Clustering. Broker listeners started with the same :name on several nodes of an Erlang cluster act as one broker, via :pg (the mqttx application starts the scope; nothing to configure; MqttX.Server.Cluster):

    • MqttX.Server.deliver/3,4 reaches every node with a matching subscription (each node tells the others which filters it has; a node whose filters have not arrived yet gets everything); a persistent session away on another node gets it queued there.
    • A CONNECT on any node takes the client over from the others: an open connection for the same client id elsewhere is disconnected with 0x8E, its Will Delay and Session Expiry are cancelled, and its stored session (subscriptions, in-flight QoS 1/2, queue) moves to the new node; Clean Start 1 discards it everywhere. handle_connect/4 reports a session held on another node as session_present. Messages published while a session moves reach it once each and in each publisher's order: the old node forwards what it matches, the new node drops duplicates by message id and holds back what it matches itself until everything sent to the old node before the hand-over has been forwarded (at most five seconds, after which order is not guaranteed for the held messages).
    • Retained messages are replicated (later write wins) and sent to a node that joins. A clear is remembered for an hour, so a node that missed it while cut off cannot bring the message back.
    • A shared subscription with members on several nodes delivers each message once across the cluster. A member on another node is sent the message only if that node takes it: if its client is offline, its session is gone, or the node leaves before answering, the next member is picked, a connected one first (a message the leaving node took just before can then arrive twice).
    • After a network split heals, a client that connected on both sides keeps the session it began last; the other copy's connection is disconnected with 0x8E and the copy discarded. Retained messages converge on the later write.
  • Durable broker sessions. A :session_backend option (MqttX.Server.SessionBackend behaviour) saves sessions behind ETS every :session_flush_interval ms (default 1000) and loads them back when the listener starts. MqttX.Server.SessionBackend.DETS keeps them in a local file; MqttX.Server.SessionBackend.Replicated keeps them on every node of the cluster, in memory, so another node resumes a dead node's sessions (not across a restart of the whole cluster); a backend over a shared database does both — the server guide has a worked Ecto/Postgres one. A save that fails (the database is down) is retried at the next flush.

  • Topic Aliases from the broker. A PUBLISH to a v5 client that set a Topic Alias Maximum carries an alias (§3.3.2.3.4): the first message on a topic the topic and its alias, later ones the alias alone, up to the client's maximum. The alias is put on at send time only, so a stored or re-sent message always has its topic. outbound_topic_aliases: false in transport_opts turns it off. (#10, from @danielschnee's Paho run)

  • Caps on what one client can hold (from the security review). :max_subscriptions (default 10 000) refuses a session's filters past the cap with 0x97; :max_sessions (default none) refuses a CONNECT that needs a new session past the cap with 0x97. A topic or filter has at most 128 levels (MqttX.Topic.max_levels/0): a deeper one does not decode — the subscription index is walked level by level, so a 65 000-level topic was a way to burn CPU on every node with one publish.

  • WebSocket listener: :check_origin (a list of allowed origins; a browser from another origin gets 403) and a frame cap of the packet cap plus the frame header by default. The adapter's own default — unlimited on websock_adapter 0.5, 10 MB on 0.6 — let a frame far past the MQTT cap be buffered before MqttX saw the packet. scheme: :https starts from the same TLS baseline as the TCP listeners.

  • Connection rate limiting per peer address. max_connections_per_ip in :rate_limit caps the new connections per interval from one address, so one source cannot use up the shared :max_connections budget or hold the listener on its own. The transports pass the peer's address to the limiter.

  • The client tells the broker its limits. A v5 CONNECT advertises Receive Maximum 100 and the client's Maximum Packet Size unless the caller set them, so a broker drops an oversized message instead of sending one the client would tear the connection down for — and reconnect to receive again, forever.

Changed

  • Receive Maximum defaults to 100 on both sides (was 65 535, the protocol's "no limit"). A QoS 2 message is held whole until PUBREL, so the window times the packet cap is what a peer can make the other side hold: 64 GiB before, 100 MiB now with the default packet cap. receive_maximum in transport_opts (broker) and connect_properties (client) set it.
  • The client's reconnect backoff starts over only after a connection that held for 30 s. A broker dropping the client right after CONNACK, or a message the client refuses on every delivery, got a retry every second; the delay now keeps growing to the 30 s maximum.
  • Decode errors are logged at debug level. Anyone with a socket can produce them.
  • :server_keep_alive is a cap, not an override. It lowers a v5 client's Keep Alive to the value when the client asked for more, or for none (0); a client asking for less keeps its own, and CONNACK carries Server Keep Alive only when the value changed. Before, every v5 client was told the configured value, so one that asked for 20 s was made to use 60. Mosquitto's max_keepalive behaves the same way. (#9, from @danielschnee's Paho run)
  • MqttX.Server.Router keeps a client's filters in a MapSet. Subscribing, unsubscribing and the duplicate check no longer walk a list of the client's filters; the public functions are unchanged.
  • websock_adapter 0.7 is accepted (requirement ~> 0.5 or ~> 0.6 or ~> 0.7). The WebSocket listener is tested with Bandit 1.14 and websock_adapter 0.7; the development lock file moves to them and to Thousand Island 1.6.
  • Performance (from a review of the whole library; each item measured before and after, nothing on the wire changed):
    • Acknowledgements go out one write per read, not one per packet. The PUBACKs, PUBRECs and PUBCOMPs for the packets of one read are written together after it (at most sixteen at a time, so none waits on a long read), on the broker and on the client, behind nothing and ahead of anything else sent during the read. A client taking in QoS 1 messages that arrive several to a read went from 315k to over a million messages a second over TCP; over TLS the write was nearly the whole cost.
    • A PUBLISH's Topic Name is checked in one pass over its bytes (MqttX.Topic.valid_name?/1; validate_publish/1 splits the levels in the same pass) instead of being split, checked level by level, and then validated again as a UTF-8 string. Encoding a small PUBLISH is 3× faster, decoding one 2.6×; the broker paid the old cost once per recipient. A properties map that is empty is encoded and decoded without a pass over it, Codec.encode/2 builds the packet in one copy instead of two, and ASCII strings are UTF-8-checked a word at a time.
    • Messages queued or in flight on the broker are ordered by :erlang.unique_integer/1 rather than one counter row in ETS, which every enqueue on the node serialized on: 0.2 M enqueues a second with 14 processes contending became 8 M.
    • A filter's subscribers are read with one bounded :ets.select/2 instead of a next/lookup pair per subscriber: a fan-out to a thousand subscribers of one filter takes a fifth of the time it did.
    • The broker's keep-alive timer is re-armed once per read rather than once per packet; a read with only part of a packet does not re-arm it.
    • A session that ends with its connection is never saved to a :session_backend (it was saved on every change and deleted on disconnect, each a message to every node with the Replicated backend), and the :max_sessions check no longer scans the session table on every CONNECT: it keeps a count for a second, adds each session it admits, and recounts before refusing.
    • The cluster member no longer sweeps the whole session table on every flush tick (every second); the 30 s sweep does that, and an expired session is discarded on access meanwhile.
    • A payload kept by the broker (retained, queued for a session, held for one on its way, a QoS 2 message until PUBREL) or by the client (a QoS 2 message until PUBREL) gets memory of its own when it is small next to the read it arrived in: as decoded it was a reference into the whole read, so a hundred-byte retained message could hold tens of kilobytes.
    • The client's QoS 2 in-flight count is kept, not recounted over every pending acknowledgement on each QoS 2 message.
    • The WebSocket client masks a frame a word at a time; a 64 KiB frame took 86 µs, now 20.

Fixed

  • A broker that stops reading can no longer freeze the client. A write into a full send buffer blocked the connection process, and with it the keep-alive that would have noticed. Client sockets now have a :send_timeout (default 30 seconds), past which the connection closes and the usual disconnect and reconnect follow.

  • A saved session whose client connected again before the listener's restore ran stayed in the backend. The restore leaves a session that is already there alone, and did not touch its record: if the client had come back with Clean Start 1 (or a Session Expiry Interval of 0), the old persistent record sat in the backend and came back at the next restart. The next flush now brings the record in line with the session that began — saved if it is persistent, deleted if it ends with its connection.

  • Ranch: a raising handler callback left the session alive forever and dropped the Will. The adapter neither trapped exits nor had a terminate/2, so an exception in handle_publish killed the connection with none of its close work: the session kept expires_at: :infinity and was never swept, and the Will — the device-offline signal — was lost. On every transport, a handle_disconnect or a Will's handle_publish that raises no longer stops the session from ending.

  • A client reconnecting while its previous connection was being drained lost its session. The adapters dropped the takeover message; the old connection ended the session after the new one had resumed it, and its expiry timer later deleted the live session. Takeovers are answered during the drain, a connection registers itself before taking over (so a concurrent CONNECT for the same id, here or on another node, finds it), and the timers are cancelled again after the takeover.

  • Clears of retained topics no longer grow the retained table without bound. An empty retained publish inserted its marker row before the cap check, and markers replicated to every node uncapped: an authorized publisher could fill the table cluster-wide for an hour. Markers count toward the cap like messages.

  • Before CONNECT, anything but CONNECT or AUTH closes the connection unread. The packet was decoded first; a 1 MiB SUBSCRIBE from an unauthenticated peer cost tens of MB of heap.

  • Crash reports show no credentials. format_status/1 on the broker's TCP connection processes (ThousandIsland and Ranch — the CONNECT, password included, is kept during enhanced authentication; the receive buffer) and on the client (password, proxy credentials, TLS key material, buffer); a socket message shows as its size. A client handler that throws or exits is caught like one that raises, and the failure log no longer prints the message.

  • The client's WebSocket upgrade and proxy CONNECT have one deadline for the whole response (5 s), and the upgrade response is capped at 8 KiB; a server dripping bytes held the client process forever.

  • Cluster housekeeping. A shared group's round-robin counter goes with its last member (it was kept for the VM's life); a member starting again lowers the fences it finds and releases the messages held for them (a member crash left them held until the session expired); a fence answer for a fence already down keeps no state; a corrupt backend record is logged and dropped instead of stopping the listener's start; a member too busy to import a moved session in time no longer fails the CONNECT; sessions whose expiry passed are swept with or without a backend.

  • A WebSocket connection idle for 60 s was cut. The listener's default socket read timeout (ThousandIsland's 60 s) applied to the WebSocket transport, so a client with a Keep Alive of 60 s or more, or none, was disconnected between messages. It is :infinity now (:read_timeout sets it); the Keep Alive and :max_idle_timeout close idle connections.

  • SessionBackend.Replicated survives a listener restart. Its process was unnamed, so a listener starting again under the same name (a restart by its supervisor, two listeners sharing a :name) started a second one that crashed on the table the first owns, taking the listener's start with it; and a node starting again inside a live cluster restored none of its sessions, because the other nodes' copies arrive after the listener's start looked at the (empty) table. The process is named per listener, and sessions of this node arriving from the others are restored when they arrive.

  • A session claimed by a connection that died mid-claim was lost cluster-wide. The node it was on exported it, let it go after the forwarding window and deleted the backend record, while the claiming node only ever held a placeholder. The old node now asks the new one whether the session arrived before letting go, and keeps it otherwise.

  • Two CONNECTs for one client id at the same time, on two nodes, both ended and left two sessions nobody owned. Each node's connection was mid-claim when the other's takeover reached it, neither answered until the takeover deadline, and both were then disconnected with 0x8E and their sessions kept without expiry. A connection answers a takeover while it waits, and of the two the one on the lower node (or, on one node, with the lower pid) gives way before its CONNACK; a session handed to it meanwhile stays on its node for the other to claim.

  • The WebSocket client's Host header carries the port unless it is the scheme's default (RFC 7230 §5.4); a gateway routing on it refused the upgrade.

  • A second client with the same client id in one VM is logged instead of registering silently (MqttX.Client.whereis/1 keeps finding the first; the broker disconnects one of the two).

  • A Remaining Length that is not the shortest encoding is malformed (MQTT-1.5.5-1).

  • A broker's strings cannot forge log lines: reason strings and server references are logged with inspect/1.

  • Docs: the custom-codec example in MqttX.Payload decodes with binary_to_term/2 and [:safe].

  • Properties are checked against the packet that carries them (§2.2.2.2). A packet carrying a property its type does not define — a Session Expiry Interval on a PUBLISH, a Will Delay Interval on a CONNACK — is now a Malformed Packet on decode, as the spec requires, and MqttX.Packet.Codec.encode/2 refuses to build one, returning {:error, {:property_not_allowed, name, packet_type}} instead of putting it on the wire for the peer to reject. User Properties remain valid everywhere. MqttX.Packet.Properties.encode/3 and decode/3 take the packet type; the two-argument forms stay unrestricted.

  • The client checks the Authentication Method it is answering. An AUTH packet naming a method other than the one the CONNECT asked for, or none, is a Protocol Error (§3.15.2.2.2, MQTT-4.12.0-5): during the handshake the connect fails with {:protocol_error, :authentication_method_mismatch}, on a live connection the client sends DISCONNECT 0x82 and tears the connection down. A successful CONNACK naming a different method is refused the same way; one that leaves the method out is still accepted. Previously the client handed any method to handle_auth/3.

  • A v5 Will with Will Properties reaches its subscribers. The broker copied the Will Delay Interval into the Will's PUBLISH, which the encoder now refuses (§2.2.2.2), so a Will that set a Will Delay Interval (even 0) was dropped at every subscriber with "Failed to encode publish". The other Will Properties are sent as before, User Properties in their order (MQTT-3.1.3-10).

  • A delayed Will can be delivered with MqttX.Server.deliver/3. A Will with a Will Delay Interval is published from MqttX.Server.WillDelay, where deliver/3 found no listener and returned {:error, :no_listener}, so a handler routing as the server guide shows never delivered it. The connection's listener is now set for that handle_publish/4 call.

  • SUBACK and UNSUBACK are sent once the change is live. The broker acknowledged a SUBSCRIBE before adding the subscriptions to the index deliver/3 routes through (and an UNSUBSCRIBE before removing them), so a message published right after the SUBACK could miss the new subscription. Retained messages still follow the SUBACK.

  • A DISCONNECT from the broker reaches the client. The ThousandIsland and Ranch transports closed the socket right after writing it; with data from the client still unread, Linux turns that close into a TCP reset, and the client could lose the packet and its reason code (0x8E on a takeover, 0x93 on a Receive Maximum overrun). The transports now shut down their write side first, read and drop what the client still sends for up to 100 ms, and close then. (#7, found by @danielschnee with the Paho suite)

  • mqttx compiles as a dependency without its optional packages. A project without thousand_island could not compile mqttx at all (use ThousandIsland.Handler), and one without ranch or protox got undefined-function warnings from it. The ThousandIsland and Ranch transports, and the Protox calls of MqttX.Payload.Protobuf, are now compiled only when their package is present; starting a transport whose package is missing still fails with an undefined-module error naming it, and the codec still answers :protox_not_available. A handler defining handle_connect/4 no longer gets a "required callback handle_connect/3" warning: both arities are optional callbacks of the behaviour, and use MqttX.Server warns when a module defines neither. CI compiles mqttx as a bare dependency (scripts/check_bare_dependency.sh). (#8, reported by @danielschnee)

  • Retained messages keep their properties. Only the Message Expiry Interval was stored; a retained message sent on SUBSCRIBE now carries the Payload Format Indicator, Content Type, Response Topic, Correlation Data and User Properties it was published with (MQTT-3.3.2-4, -15, -16, -17, -20). Retained rows (and the rows replicated between cluster nodes) gain a properties field before version.

  • Encoding an invalid packet returns an error instead of raising. MqttX.Packet.Codec.encode/2 answers {:error, :invalid_packet} for a term it cannot encode — a topic segment that is not a binary, a missing client id, a reason code or property value out of range (Receive Maximum, Topic Alias and Maximum Packet Size must be at least 1), a user property that is not a pair of binaries, more than one Subscription Identifier on a SUBSCRIBE — and {:error, :empty_acks} or {:error, :invalid_ack} for a SUBACK/UNSUBACK with no or invalid acks, where a FunctionClauseError or ArgumentError escaped before. A v5 CONNACK in the 3.1.1 shape decodes with its return code mapped to the matching reason code; a pre-5 DISCONNECT with a body is malformed; a pre-5 DISCONNECT encodes as its two bytes.

  • Broker: the Will on the way out, once. A takeover publishes the old connection's immediate Will before releasing the session; a Will Delay still pending when the client returns with Clean Start 1 fires (MQTT-3.1.2-10) and is cancelled on Clean Start 0; a v5 DISCONNECT with reason code 0x04 publishes the Will (§3.14.2.1); handle_disconnect/2 is called once per connection; a handle_session_expired/2 or a Will's handle_publish/4 that raises is logged and does not take the sweeper with it. A duplicate QoS 2 PUBLISH is answered with PUBREC again instead of counting against the Receive Maximum.

  • Broker: session accounting. SessionStore.count/1 — the :max_sessions check — no longer counts placeholders and moved stubs; a remote shared subscriber or a node leaving drops its round-robin counter; a session exported for a move keeps its expiry; a node that moved a session out cannot take it back on a stale unmove once the new node has imported it, and leaves the stub to expire when that node cannot be asked; a backend record that fails to restore is deleted locally as well.

  • Client: the connection process is never held by its socket. The TCP connect, proxy CONNECT, TLS handshake and WebSocket upgrade run in a helper process; publish, subscribe and :sys calls are answered ({:error, :not_connected}) while an attempt is under way.

  • Client: a resumed session re-sends within the broker's Receive Maximum (§4.9). In-flight messages beyond the window follow as acknowledgements come in, in order, instead of all at once; new publishes wait behind them with {:error, :flow_control}.

  • Client: smaller fixes. A handler that throws or exits is logged (the failure log itself raised); a payload that is neither a binary nor iodata returns {:error, :invalid_payload} instead of crashing the connection; a topic alias is kept only once the PUBLISH carrying it went out; a WebSocket closed during the handshake ends the attempt at once rather than at the CONNACK deadline; an UNSUBACK refusing a filter returns {:error, {:unsubscribe_failed, codes}}; a handle_auth/3 that raises ends the connection with a protocol error instead of the process; disconnect/2 answers callers waiting for a SUBACK, and a server DISCONNECT saves the session like every other way out; the HTTP proxy socket is closed when the tunnel is refused; connect/1 with await_connect: true no longer exits when the client already stopped itself on a non-retryable CONNACK; the advertised maximum_packet_size never exceeds the enforced :max_packet_size; MqttX.SimpleClient.disconnect/2 works from inside a callback.

[0.12.0] - 2026-10-19

Added

  • Session records expire. MqttX.Client now tracks the negotiated Session Expiry Interval (CONNECT property, overridden by CONNACK per §3.2.2.3.2, revisable on DISCONNECT per §3.14.2.2.2) and writes expires_at and saved_at into the persisted session (additive — older records and custom stores are unaffected). An expired record is discarded on load instead of replaying stale in-flight QoS 1/2 state against a broker that already dropped the session, and MqttX.Session.ETSStore sweeps expired records on an interval (sweep_expired/2 to run one on demand; config :mqttx, session_sweep_interval: ms to tune). MQTT 3.1.1 sessions and 0xFFFFFFFF never expire. Note the MQTT 5.0 default interval is 0, so a v5 client that wants its session to outlive a disconnect must send connect_properties: %{session_expiry_interval: n} — this was always true broker-side; the local record now agrees.
  • clean_session: true deletes the stored session. The MqttX.Session.Store docs promised delete/2 on a clean start (§3.1.2.4) but the client never called it, leaving stale records behind.
  • Publish with a payload codec. MqttX.Client.publish/4 and a broker handler's {:publish, topic, payload, opts, state} take codec: MqttX.Payload.JSON (or .Protobuf, or your own MqttX.Payload module) with the payload given as a term: the codec encodes it, and the codec's new optional metadata/0 callback supplies the MQTT 5.0 payload_format_indicator and content_type properties (explicit properties win). JSON declares UTF-8 text + application/json, Protobuf application/protobuf. Additive: codecs without metadata/0 keep working and declare nothing.
  • Benchmarks and an end-to-end load test. bench/ holds Benchee suites for the codec, the router / retained store / receive buffer, and client-to-broker throughput over loopback (TCP or WebSocket); mix test --include load runs a many-client completeness check. The Performance guide now carries measured end-to-end numbers instead of estimates.
  • Subscription Identifiers are now supported server-side (MQTT 5.0 §3.3.2.3.8). CONNACK advertises subscription_identifier_available: 1; identifiers arriving in SUBSCRIBE are attached to matching outbound publishes — merged into one list when several of the client's subscriptions match a delivery — and to retained messages delivered on subscribe.
  • handle_subscribe/2 can reject individual topics by returning a reason code >= 0x80 (e.g. 0x87 Not authorized) in place of a granted QoS. The rejected filter is answered with that code in the SUBACK (collapsed to 0x80 for pre-5 clients, whose only failure return code is 0x80), receives no retained delivery, and is not added to the routing index — an existing subscription for the same filter is left intact per §3.8.4. Previously a reason-code grant crashed the SUBACK encoder and took the connection down. A grant list whose length differs from the requested topic list is now also normalized (missing grants reject with 0x80) instead of producing a protocol-invalid SUBACK.
  • no_local subscriptions are honored for broker-initiated publishes. Pass publisher: originating_client_id in the opts of a {:publish, topic, payload, opts, state} return from handle_info and delivery is suppressed on subscriptions the client made with no_local: true when it is itself the publisher (§3.8.3.1).
  • Enhanced authentication now works on the broker. A CONNECT carrying an Authentication Method (MQTT 5.0 §4.12) used to be answered with a CONNACK at once — the exchange never ran, so the paths that completed it were unreachable. The broker now calls handle_auth/3 with the CONNECT's Authentication Data after handle_connect accepts and holds the CONNACK until the exchange ends: {:continue, challenge, state} sends AUTH 0x18 and feeds the client's answer back through handle_auth/3; {:ok, state} — or the new {:ok, server_final, state}, for mechanisms like SCRAM whose server has a last word — sends CONNACK 0x00 repeating the method (MQTT-4.12.0-5) and carrying server_final; {:error, reason_code, state} sends that CONNACK and closes. An AUTH mid-exchange naming another method or not carrying 0x18, or any other packet, fails the CONNECT (0x8C / 0x82); a stalled exchange is ended by the CONNECT deadline; a drop before CONNACK fires neither the Will nor handle_disconnect/2. Re-authentication must name the CONNECT's method (MQTT-4.12.1-1), so an AUTH on a connection that never used enhanced authentication is refused with 0x8C without consulting the handler. handle_connect/4's connect_info gains an authentication_method key (nil unless requested). The default handle_auth/3 still returns {:error, 0x8C, state}.
  • wss:// on the WebSocket broker transport. MqttX.Transport.WebSocket takes scheme: :https plus transport_options: [certfile:, keyfile:, …] (the same shape as ThousandIsland's SSL transport) and serves MQTT over TLS WebSockets through Bandit. Previously it was HTTP-only.
  • Server-side sessions. The broker now keeps Session State (MQTT §4.1) per listener, in ETS. A client that connects with Clean Start 0 and a non-zero Session Expiry Interval — or, for MQTT 3.1.1, CleanSession 0 — gets session_present: true on reconnect and its subscriptions back without re-subscribing; unacknowledged QoS 1/2 PUBLISHes are re-sent with DUP set, a PUBREL awaiting PUBCOMP is re-sent, and an inbound QoS 2 message awaiting PUBREL is completed. Clean Start 1 discards the stored session; the expiry timer discards it when the interval elapses (and still calls handle_session_expired/2). A connection taking over a client id (§3.1.4) inherits the session. The new :max_session_expiry_interval transport option (default 86 400 s) caps how long a session is kept: a v5 client asking for more is told the cap in CONNACK (§3.2.2.3.2), and it is the lifetime of a 3.1.1 CleanSession 0 session, which would otherwise never end. handle_connect/4's connect_info gains session_present and subscriptions. State is in memory on one node and does not survive a BEAM restart. Previously the broker answered session_present: false to every CONNECT and kept nothing across connections.
  • MqttX.Server.deliver/3, the broker's own fan-out. Call it from handle_publish/4 — or from anywhere by listener name with deliver/4 — and the broker matches the topic against every session's subscriptions on the listener, applies each subscription's options (granted QoS cap, Retain As Published, Subscription Identifiers, no_local via :publisher, one member per shared subscription, preferring a connected one) and sends. A session that is not connected gets QoS 1/2 messages queued, bounded by :max_outbound_queue, with Message Expiry counting down (MQTT-3.3.2-6), and receives them in order on reconnect; a persistent session is served through that queue even while connected, so a dropped connection cannot lose a message mid-delivery, and a session that ends with its connection is sent to directly. The handler keeps deciding whether a message is delivered; {:publish, ...} returns from handle_info/2 keep working for brokers that route through their own PubSub. MqttX.Server.start_link/3 now honors :name as the handle deliver/4 finds the listener by (it used to be dropped).

Changed

  • Outbound publishes from handle_info are routed through the client's subscriptions. Each {:publish, ...} return is matched against what the client actually subscribed to, and the per-subscription options — granted QoS cap (§3.8.4), Retain As Published (§3.3.1.3), Subscription Identifiers — are applied to the delivery instead of being computed and discarded. Two behavior changes when a matching subscription exists: QoS is capped at the granted QoS, and the retain flag reaches the client only if the subscription set retain_as_published (previously it was forwarded verbatim). A publish matching none of the client's subscriptions is still sent as-is, so brokers that make delivery decisions themselves are unaffected.

  • Wildcard retained-message delivery no longer scans the whole store. A +/# subscription used to fold every retained entry through an Elixir-side match. The retained store is now an :ordered_set keyed by topic segments, and each filter compiles to a single ETS match spec whose literal prefix bounds the traversal — on a 100k-topic store, matching tenant42/+/temp drops from ~11 ms to well under 0.1 ms. Behavior (retain_handling, $-topic exclusion, expiry, the :max_retained_messages cap) is unchanged. Note for hot-upgraded nodes only: the in-memory table format changed, so retained messages stored by an older version in a still-running BEAM are not visible to the new code; a normal restart is unaffected (the store has never survived restarts).

  • QoS 1/2 packets are no longer re-sent on a live connection. Both the client and the broker ran a timer that re-sent an unacknowledged PUBLISH (with DUP) or PUBREL every 5 s and silently discarded the message after three attempts; the broker also re-sent PUBREC on its own and dropped an incoming QoS 2 message that was still waiting for its PUBREL. MQTT 5.0 §4.4 forbids re-sending except when a session is resumed [MQTT-4.4.0-1], and 3.1.1 tolerates it only as a concession to "older TCP networks". On a live socket a missing acknowledgement means the peer is slow or gone — which the keep-alive detects — not that bytes were lost, and the timed drop lost QoS 1/2 messages without any :publish_error. In-flight packets are now held until acknowledged or until the connection ends; the client's re-send on session resumption (session_present: true) is unchanged, and backpressure comes from :max_inflight and the peer's Receive Maximum as before. One visible consequence: a client that never completes a QoS 2 flow now holds one Receive Maximum slot on the broker until it disconnects, where previously the message was dropped after ~15 s and its eventual PUBREL answered as if it had been delivered.

Deprecated

  • :retry_interval on MqttX.Client, and :qos2_retry_interval / :qos2_max_retries in the broker's transport_opts, are accepted but ignored and log a warning at start; they will be removed in a later release. There is no replacement — in-session retransmission is not part of the protocol (see Changed).

Fixed

  • Conformance audit. Every normative statement of MQTT 5.0 (251) and MQTT 3.1.1 (138) was traced to the code that enforces it, and what did not hold up was fixed:

    • Broker. A QoS 1 PUBLISH that handle_publish refused got no PUBACK, so the publisher held the Packet Identifier in flight forever (MQTT-3.3.4-1); it is now acknowledged with a refusal code — see handle_publish/4. Receive Maximum overruns were answered with PUBACK/PUBREC 0x93 and rate-limit overruns with 0x96, both DISCONNECT-only codes; the former is now DISCONNECT 0x93 and close (§4.9), the latter PUBACK/PUBREC 0x97 Quota exceeded with the session kept. Will Delay was scheduled under one key and cancelled under another, so a reconnect never cancelled a delayed Will (MQTT-3.1.3-9). Every broker-initiated close — a handler's {:disconnect, ...}, MqttX.Server.disconnect/3, a protocol error, session takeover — suppressed the Will, which the spec publishes unless the client itself sent DISCONNECT 0x00 (§3.1.2.5); a taken-over connection now drops only a delayed Will and no longer arms session expiry for a session the new connection owns. A zero-length v5 Client Identifier ran as ""; the broker now assigns one, hands it to handle_connect and returns it as Assigned Client Identifier (MQTT-3.1.3-6/-7). Handler reason codes reached 3.1.1 clients unmapped in CONNACK (0x86 → return code 4, 0x87 → 5, …), and a v5 CONNACK or SUBACK could carry codes those packets do not define (now 0x80). Outbound Packet Identifiers could be reused while still in flight once the counter wrapped (MQTT-2.2.1-4). UNSUBSCRIBE of a filter never subscribed answered 0x00 instead of 0x11. A SUBACK could grant a QoS above the one requested. A client PUBLISH carrying a Subscription Identifier is refused (MQTT-3.3.4-6). Application-supplied topic_alias / subscription_identifier properties are stripped from outbound publishes (MQTT-3.1.2-26). A server DISCONNECT never carries Session Expiry Interval (MQTT-3.14.2-2). A live AUTH must be 0x18/0x19 and name its method. An oversized packet during the enhanced-auth exchange gets CONNACK 0x95, not a DISCONNECT (MQTT-3.14.0-1). A WebSocket text frame closes the connection (MQTT-6.0.0-1). The Receive Maximum queue is bounded by the new :max_outbound_queue option (default 10 000, previously hard-coded) and ages Message Expiry Interval while a message waits, dropping one that expired (MQTT-3.3.2-6).
    • Codec. A v3.1.1 UNSUBACK carried one payload byte per filter — it has none, and strict clients dropped the connection on every unsubscribe. A v5 PUBACK/PUBREC/PUBREL/PUBCOMP with a Reason Code but no Property Length, the legal short form, was rejected as malformed, tearing down the client connection whenever a broker answered e.g. PUBACK 0x10. Packet Identifier 0 is a Malformed Packet on PUBLISH/SUBSCRIBE/UNSUBSCRIBE (MQTT-2.2.1-3). Property strings are UTF-8-validated on encode as they were on decode (MQTT-1.5.4-1/-2). Malformed $share filters ($share//t, $share/g, $share/g/, wildcards in the ShareName) are rejected (MQTT-4.8.2-1/-2), as are No Local on a shared subscription (MQTT-3.8.3-4), a repeated Subscription Identifier in SUBSCRIBE, a Will Topic with wildcards, non-zero reserved CONNACK flag bits and — on encode — Will QoS 3, SUBSCRIBE QoS 3, Retain Handling 3, DUP at QoS 0, and a 3.1.1 password without a user name.
    • Client. publish/4 returns {:error, :qos_not_supported} / {:error, :retain_not_supported} when the broker's Maximum QoS or Retain Available forbids the publish (MQTT-3.2.2-11/-14) — previously the broker disconnected the client (0x9B/0x9A) and it reconnect-looped. subscribe/3 returns {:error, :invalid_qos}, {:error, :invalid_retain_handling} or {:error, :no_local_on_shared_subscription} instead of putting an invalid SUBSCRIBE on the wire, and a :will_qos outside 0..2 raises at start. A server AUTH arriving when the CONNECT asked for no Authentication Method is a Protocol Error (MQTT-4.12.0-7) instead of being answered. A WebSocket text frame closes the connection. pending_seq is restored with a persisted session, so a second resumption re-sends in the original order (MQTT-4.6.0-1). A PUBREC for an unknown id is answered with PUBREL 0x92 on v5 (§3.6.2.1), and acks for ids not in flight no longer drift the send window.
  • The broker sent DISCONNECT before any CONNACK. A packet other than CONNECT arriving first — or an AUTH with no CONNECT behind it — was answered with DISCONNECT 0x82 and the socket closed. MQTT 5.0 forbids a DISCONNECT until a successful CONNACK has been sent (MQTT-3.14.0-1); the connection is now simply closed (§4.13).

  • Receiving a large packet across many reads was quadratic. Both the broker and the client appended each read to the buffer and re-attempted a decode, which re-copied everything buffered so far on every read. A packet now waits for the length its fixed header declares and is assembled once: measured on the broker, a 1 MiB packet (the default limit) arriving in 1460-byte segments drops from ~22 ms of CPU to ~0.3 ms, and a 16 MiB one — reachable with a raised max_packet_size — from ~7 s to ~5 ms. The same change applies to the client over TCP/TLS and to its WebSocket frame buffer.

  • An over-limit packet during the client handshake stalled connect. The connection was torn down but left marked as connecting, so await_connect: true waited out the 5 s handshake deadline and reported :timeout. It now fails at once with {:error, :packet_too_large} — or {:error, :frame_too_large} for an oversized WebSocket frame — and retries with the usual backoff.

  • Exit signals no longer reach a broker handler's handle_info/2. The ThousandIsland transport traps exits, so when a process the handler had linked to went down — a Registry or Phoenix.PubSub partition (both link to registrants), a Task — the {:EXIT, pid, reason} message was passed to handle_info/2, and a handler without a catch-all clause (such as the README's PubSub-bridge example) crashed with a FunctionClauseError. The connection now does what a non-trapping process would: a :normal exit is ignored and any other closes the connection, with handle_disconnect/2 receiving {:linked_process_exit, reason}. Found by the new load test.

Security

  • A fragmented WebSocket message had no size limit in the client. A single frame was capped at 16 MiB, but continuation frames were appended to the message being reassembled without bound. A broker — or anyone on the path of a plain ws:// connection — could start a message and send non-final fragments forever, growing the client's memory until the VM ran out. :max_packet_size could not stop it, because nothing reaches the MQTT layer until the final fragment arrives. A reassembled message is now held to the same 16 MiB ceiling as a single frame; exceeding it closes the connection with {:protocol_error, :message_too_large}. One consequence: an MQTT packet over 16 MiB could previously arrive over WebSocket if the broker fragmented it, and is now refused — as it already was when sent as a single frame.
  • The client enforced :max_packet_size only on the first packet of each read. A packet over the limit that arrived behind another one in the same read was decoded and delivered to the handler, and an over-limit header in that position was kept until more data arrived instead of closing the connection. The declared length of every packet is now checked.

[0.11.2] - 2026-08-02

Added

  • MqttX.Packet.ReasonCodes — named constants for the MQTT 5.0 reason codes and MQTT 3.1.1 CONNACK return codes this library sends, plus an is_error_code/1 guard for the §2.4 rule that 0x80 and above means failure. Handler callbacks can return {:error, ReasonCodes.bad_authentication_method(), state} instead of a bare 0x8C. It covers the codes the library itself uses, not the full spec table.

Security

Findings from a multi-agent security review of the whole repository at a8f28fe. Each fix carries a regression test that was confirmed to fail against the previous code.

  • A Will message bypassed publish authorization. An ordinary PUBLISH stores its retained entry only after handle_publish/4 accepts it, but both Will paths — immediate (MqttX.Transport.Handler) and delayed (MqttX.Server.WillDelay) — wrote to the retained store first and then discarded the handler's answer. A peer that got past handle_connect could therefore plant, or with an empty payload delete, a retained message on any topic its ACL forbids; deliver_retained_messages/2 later handed it to subscribers without consulting the handler again. Both paths now publish through the handler first and store only on {:ok, _}. A Will's topic and payload never reach handle_connect, so handle_publish/4 is the only callback that can authorize them — brokers relying on it for per-topic authorization were affected.
  • A broker could choose which session record the client overwrote. The client adopted the CONNACK assigned_client_identifier unconditionally and used the resulting client_id as the session_store key, so a malicious or MITM'd broker could rename the connection to another client's id and clobber that client's persisted session in the shared table — the victim would then replay the attacker-influenced subscriptions and in-flight publishes against its own broker. The store is now keyed by an immutable session_key captured in init/1, and the assigned identifier is honoured only when the client actually sent a zero-length one, per §3.2.2.3.7 (a broker that sends one anyway is ignored with a warning). Affects session_store + clean_session: false deployments sharing a session table.
  • Log-record forgery via client_id. The keepalive-timeout log line interpolated the client-supplied identifier raw; the codec permits CR, LF and ANSI escapes, so a client could forge additional log records or corrupt an operator's console. It now uses inspect/1, as every other log site in that module already did.

[0.11.1] - 2026-07-31

Fixed

  • README links render correctly on hex.pm's package page. The page shows the README from the package tarball and rewrites relative links to the raw file server (repo.hex.pm/preview/...), which serves guide pages as plain text. All relative documentation links in the README are now absolute hexdocs.pm URLs, which work on hexdocs, GitHub, and hex.pm alike; a documentation test resolves each one back to its source file and verifies the page and heading anchor exist.

[0.11.0] - 2026-07-31

A security and correctness release. Every Critical and High finding from a full-codebase audit is fixed, several features that were silently broken now work (the Ranch transport, inbound topic aliases, reconnect resubscription, dead-link detection), and two long-requested features land: use MqttX and HTTP CONNECT proxy support.

Upgrading: some defaults change deliberately — read Changed first. The most likely surprise is TLS certificate verification, which is now on by default.

Changed (breaking defaults)

  • Client TLS verifies certificates by default. :ssl and :wss use verify: :verify_peer with the OS trust store (:public_key.cacerts_get/0), SNI, HTTPS-style hostname checking, and TLS 1.2/1.3 only. Your :ssl_opts are merged over that baseline, so verify: :verify_none still works — explicitly, and with a logged warning. Setups that silently relied on no verification will now fail until certificates are configured; that is the point.
  • Server TLS baseline. When a TLS transport is selected, the ThousandIsland and Ranch adapters inject versions: [:"tlsv1.3", :"tlsv1.2"], secure_renegotiate: true, and honor_cipher_order: true beneath your :transport_options.
  • Server max_packet_size defaults to 1 MiB (was unlimited) and is enforced on the declared remaining length before the body is buffered, closing a pre-auth memory-exhaustion vector. max_packet_size: :infinity restores the old behavior.
  • Client max_packet_size defaults to 1 MiB, applying the same check to data from the broker.
  • Socket liveness no longer depends on Keep Alive alone. ThousandIsland's 60 s read_timeout was disconnecting spec-compliant clients whose keepalive exceeded it, so it now defaults to :infinity; in its place the protocol handler enforces :max_idle_timeout (default 15 min, :infinity disables), which resets on any inbound data and therefore also covers clients that negotiate keep_alive: 0. A separate :connect_timeout (default 10 s) closes sockets that never complete CONNECT.
  • Ranch transport selection renamed to :ranch_transport (:ranch_tcp | :ranch_ssl). The old :transport key collided with MqttX.Server's own :transport option (the adapter module) — a collision that made the documented Ranch setup fail at startup. :transport is still honored when it holds a valid ranch atom.
  • The client discards in-flight QoS 1/2 state when the broker starts a fresh session (session_present: false, MQTT-3.2.2-4), with a warning, instead of retaining state it can never deliver.
  • MqttX.Client.connect/1 no longer waits for CONNACK. The handshake is now event-driven, so connect/1 returns before the session is live and a subscribe/publish issued immediately after it returns {:error, :not_connected}. Previously the blocking handshake made such calls queue in the mailbox until CONNACK, so they appeared to succeed. Either act on the handler's :connected event, or pass the new await_connect: true option to block until the first attempt resolves — that form returns {:error, reason} (e.g. :econnrefused or {:connack_error, code, info}) and stops the client if the attempt failed. The asynchronous default is deliberate: a client can now be started before its broker is reachable and keep retrying with backoff, which a blocking connect cannot do.
  • Malformed packets close the client connection (§4.13) instead of being logged and left at the head of the buffer, which wedged all further decoding and grew the buffer without bound. Handlers see (:disconnected, {:protocol_error, reason}) and the client reconnects.

Added

  • use MqttX — module-based client (GitHub #1). Define a client as one module with init/1, handle_message/4, handle_connected/2, handle_disconnected/2, handle_publish_error/4, and handle_info/2 (all defaulted), add it to a supervision tree as {MyClient, connect_opts}, and use the injected publish/subscribe/… helpers — including from inside callbacks, which run in the module's own process and so cannot deadlock the connection. See MqttX.SimpleClient.
  • HTTP CONNECT proxy support (GitHub #2). Pass proxy: [host: "proxy.corp", port: 3128, auth: {"user", "pass"}] to tunnel any transport (:tcp/:ssl/:ws/:wss) through a forward proxy (RFC 9110 §9.3.6). TLS and the WebSocket upgrade layer over the established tunnel, so certificate verification and SNI target the broker, not the proxy. Basic auth is supported; a non-200 response fails the attempt with {:proxy, {:proxy_status, code}} and backs off normally.
  • Automatic resubscription. Granted subscriptions are recorded on SUBACK and replayed after any reconnect reporting session_present: false. Previously they were never tracked, so a transient disconnect left the client connected but deaf. Tracked subscriptions persist via :session_store.
  • Prompt in-flight resend on session resumption (§4.4/§4.6). On CONNACK with session_present: true, unacknowledged QoS 1/2 PUBLISHes (dup=1) and PUBRELs are resent immediately in original submission order — not up to retry_interval later in arbitrary map order.
  • MqttX.Packet — public façade for the codec (encode/2, decode/2, encode_iodata/2, declared_length/1). The landing-page docs referenced this module before it existed.
  • MqttX.Packet.Codec.declared_length/1 — the wire size a buffered packet declares, readable from its first bytes; used for early size enforcement.
  • New handler event (:publish_error, {topic, packet_id, reason_code}) and telemetry event [:mqttx, :client, :publish, :exception] for broker-rejected QoS 1/2 publishes.
  • Server options :max_idle_timeout, :connect_timeout, :max_retained_messages, ThousandIsland :read_timeout, and WebSocket :max_frame_size; client options :max_packet_size and :await_connect.
  • :ssl and :public_key added to extra_applications, so TLS transports work inside Mix releases without the host app listing them.

Fixed — remote crashes and DoS

  • Codec crashes reachable from the network. CONNACK / v5 PUBACK / PUBREC / PUBCOMP / PUBREL / DISCONNECT / AUTH packets with trailing bytes after their properties raised CaseClauseError; v3/v4 acks with bytes after the packet id raised FunctionClauseError. Both now return {:error, :malformed_packet}. Truncated content inside a complete packet (property-length overrun, truncated UTF-8) was misreported as :incomplete, wedging client and server buffers — now :malformed_packet.
  • A truncated varint inside a property slice crashed the decoder. Varint.decode/1 returns a bare :incomplete, and the Subscription Identifier decoder's with had no else, so that atom escaped into Properties.decode/2 and raised CaseClauseError. Eight bytes were enough to kill a connection process, on client and server alike. Found by the new property-based fuzzing (1 failure in ~80 000 bit-flipped packets), now returns {:error, :malformed_packet}; the property-decode boundary also rejects any unexpected shape defensively rather than raising.
  • Unauthenticated peers could suppress another client's Last Will. WillDelay.cancel/1 and SessionExpiry.cancel/1 ran at the top of CONNECT, before authorization; they now run only after the handler accepts the connection, alongside session takeover.
  • Unbounded buffering from a hostile broker. The client now enforces a declared-length packet cap, and the WebSocket client caps a single frame's declared payload (a 64-bit length field previously had no ceiling).
  • Proxy hardening. CR/LF, whitespace, and NUL in :host are rejected before they can inject headers into the CONNECT request, and a non-numeric proxy status no longer raises inside the connection process.
  • Retained storage is bounded by :max_retained_messages (default 100 000 topics) and written only after the handler accepts the publish, so unauthorized publishers cannot fill it. A delayed Will's retained write respects the same cap.
  • The client honors the Topic Alias Maximum it advertised, rejecting larger aliases from the broker.
  • WillDelay / SessionExpiry timers are keyed by {listener, client_id}, matching session takeover's scope, so two brokers in one VM cannot cancel each other's timers.

Fixed — client

  • The blocking CONNECT handshake is gone. The client no longer sits in a bare receive between CONNECT and CONNACK: the handshake runs through the normal GenServer loop in a :connecting state. Calls answer immediately during a (re)connect; one total handshake deadline applies, so a broker trickling AUTH packets can no longer hold the client open indefinitely; and a CONNACK split across TCP segments now reassembles correctly. The deadline is generation-tagged so a late timeout cannot abort a later handshake.
  • Dead-link detection works. The PINGRESP deadline was cancelled and re-armed by every keepalive tick (1.0×K tick vs 1.5×K deadline), so it could never fire and a black-holed connection was never detected. An unanswered PINGREQ's deadline now stands, and stale pingresp/keepalive/retry timers are cancelled on every teardown path so they cannot kill the next connection.
  • Supervised clients can be disconnected. Connection ships a restart: :transient child spec, so disconnect/2's normal stop is no longer resurrected by the DynamicSupervisor into an immediate reconnect. Calling disconnect/2 while offline no longer crashes on :gen_tcp.send(nil, _).
  • Non-retryable CONNACK rejections stop the client rather than reconnecting forever: bad credentials (0x86/0x04), not authorized (0x87/0x05), invalid client id (0x85/0x02), unsupported version (0x84/0x01), banned (0x8A), bad auth method (0x8C). Handlers receive (:disconnected, {:connack_error, code, info}) and the process exits normally; transient failures still retry with backoff.
  • Inbound topic aliases never resolved — a type mismatch delivered every aliased PUBLISH with topic "". Aliased messages now carry the real topic, alias maps reset per connection in both directions, and an unknown alias is a protocol error (§3.3.2.3.4).
  • QoS retries no longer replay stale topic-alias state across reconnects: pending entries store the original topic with no alias property, so a retry cannot trigger a broker protocol error or rebind an alias to another topic.
  • PUBACK/PUBREC error reason codes (>= 0x80) are surfaced — warning log, :publish_error handler event, exception telemetry — instead of counted as success, and an error PUBREC no longer triggers a spec-violating PUBREL.
  • A PUBREL for an id the client no longer tracks is answered with PUBCOMP (0x92 in v5) instead of ignored, so a lost PUBCOMP no longer leaves the broker retrying forever.
  • Inbound QoS 2 messages are bounded by the client's advertised Receive Maximum (DISCONNECT 0x93 if the broker exceeds it).
  • Packet-id allocation skips ids held by in-flight SUBSCRIBE/UNSUBSCRIBE (shared id space, §2.2.1) and returns {:error, :packet_ids_exhausted} rather than reusing a live id; callers blocked in subscribe get {:error, :not_connected} immediately on disconnect instead of a timeout.
  • The client traps exits and implements terminate/2, so supervisor/VM shutdown sends a clean DISCONNECT (no spurious will) and saves the session.
  • Session-store failures (init/load/save) are logged instead of silently disabling requested persistence; custom ETSStore tables are created via the supervised ETSOwner (they used to be owned by the connection process and died in the very crash they existed to survive).
  • The WebSocket client honors control frames: Pings get matching Pongs (proxies liveness-check this way), a Close triggers a proper reply and teardown, and fragmentation state resets per connection.
  • Handler callbacks are isolated — a raising handle_mqtt_event/3 is logged instead of taking down the connection (which could poison-loop on QoS 1 redelivery) — and Code.ensure_loaded? runs before the callback check, so a not-yet-loaded handler module in dev/iex no longer discards every event.
  • publish(client, topic, payload, qos: 3) returns {:error, :invalid_qos} instead of sending a malformed packet and crashing the connection.
  • MqttX.Client.connect/1 returns {:error, {:missing_option, :host | :client_id}} instead of raising KeyError; its @spec is widened to GenServer.on_start() | {:error, term()}.
  • Reconnect backoff state was discarded on several failure paths (the timer fired but the delay never grew); :jitter is clamped to [0, 0.9], since values >= 1 could produce a negative delay and crash Process.send_after.

Fixed — broker / server

  • The Ranch adapter was non-functional. :ranch.handshake/1 ran inside GenServer.init/1, deadlocking ranch's connection supervisor on the first inbound connection; it now uses the documented :proc_lib.spawn_link + enter_loop pattern. Also fixed there: TLS ({:ssl, ...}) messages were handed to the user handler instead of the MQTT decoder, and close/stop paths skipped handle_close, so wills, handle_disconnect, and session expiry never ran on Ranch.
  • Session takeover (§3.1.4-3): a CONNECT reusing a live client_id now disconnects the incumbent (0x8E) and takes over, via a per-listener registry. Two connections could previously share a client_id indefinitely.
  • Session expiry is supervised and cancellable — the Task.start + Process.sleep timers were uncancellable and fired even for clients that had reconnected, wiping live sessions. Replaced by MqttX.Server.SessionExpiry, mirroring WillDelay; a fresh CONNECT for the same client_id cancels the pending expiry.
  • A second CONNECT on a live connection is a protocol error (0x82, §3.1.0-2) instead of re-running auth, sending a second CONNACK, and leaking a keepalive timer that would later tear down the session and spuriously publish the will.
  • Client Receive Maximum is enforced on outbound QoS > 0 (§3.3.4): sends beyond the advertised window queue and drain as acks arrive, instead of flooding constrained clients into a DISCONNECT 0x93.
  • Retained deliveries at QoS > 0 are tracked in flight, routed through the normal send path — a QoS 2 retained delivery now completes its PUBREC/PUBREL/PUBCOMP handshake (the PUBREC used to be ignored and the flow hung forever) and QoS 1 retained deliveries retransmit on loss.
  • Shared subscriptions are keyed by the (ShareName, TopicFilter) pair (§4.8.2). One group name across several filters previously collapsed into a single group, and the second filter's traffic reached nobody.
  • Idle timeouts publish the will and start session expiry like any other abnormal close.
  • WebSocket stop paths deliver queued frames: rejection CONNACKs and DISCONNECT packets are sent before the close frame instead of being discarded, so WS clients can distinguish auth failure from a network blip. The rate-limited upgrade path returns its 1008 close code correctly.
  • handle_disconnect/2 fires exactly once per connection (it previously ran twice, sometimes three times, across the inline and terminate paths).
  • v5 DISCONNECT properties are honored: a revised session_expiry_interval (e.g. 0 for "drop my session now") takes effect, and a 0 → non-zero revision is rejected as a Protocol Error (§3.14.2.2.2).
  • Will Delay honors session end (§3.1.2.5): with session expiry 0 the will publishes immediately on abnormal disconnect, otherwise at min(delay, session expiry).
  • Enhanced re-authentication (§4.12.1) answers with AUTH 0x00 on success and DISCONNECT on failure — never a second CONNACK.
  • PUBREC with an error reason aborts the QoS 2 flow without PUBREL; an unknown packet id is answered with PUBREL 0x92 (v5).
  • retain_handling: 1 is honored (retained messages only for new subscriptions), and retained delivery is capped at the granted QoS rather than the requested one.
  • v3.1.1 CONNECT with a zero-byte ClientID and CleanSession=0 is rejected with 0x02 (MQTT-3.1.3-8).
  • Router.match/2,3 delivers at the maximum QoS across a client's overlapping subscriptions (§3.3.4) instead of an arbitrary one; only match_and_advance/3 advances shared-group round-robin, now documented.

Removed

  • MqttX.Packet.Types — 93 constant-accessor functions (packet type numbers, reason codes, property identifiers) with no callers anywhere in the library, tests, or documentation; the codec carries its own constants. Codec users are unaffected: the public entry points are MqttX.Packet / MqttX.Packet.Codec, which speak maps and atoms — the numeric wire constants were never part of the API surface.

Fixed — codec

  • Malformed SUBACK/UNSUBACK reason bytes fail the whole decode; previously the packet decoded "successfully" with the error buried in the acks list. Empty SUBACK (and v5 UNSUBACK) ack lists are rejected.
  • Strings and binaries over 65 535 bytes return {:error, :string_too_long} on encode instead of silently wrapping the 16-bit length prefix and corrupting the wire (topics, client_id, credentials, will data, and every string/binary property). Topic.validate/1 applies the same cap to list-form topics.
  • Packet ids are validated on encode — {:error, :missing_packet_id} for absent or zero ids on QoS > 0 PUBLISH, acks, and (un)subscribe packets, which previously encoded as 0x0000 and had to be rejected by every receiver.
  • PUBLISH encode validates QoS (0-2) and the topic (no wildcards, non-empty unless a topic alias is set); SUBSCRIBE/UNSUBSCRIBE reject empty topic lists; CONNECT rejects an out-of-range keepalive.
  • Property values are range-checked on encode (32/16-bit integers, varint subscription identifiers), and unknown or mistyped properties return {:error, {:invalid_property, name}} instead of vanishing from the wire.
  • UTF-8 validity (no U+0000, no surrogates) is enforced on encode, matching decode. The Will payload and password are correctly treated as binary data rather than UTF-8 strings.
  • v3.1.1 SUBSCRIBE: v5-only subscription option bits (nl/rap/rh) are rejected on decode (§3.8.3-4) and never emitted on encode.
  • MqttX.Payload.JSON is always defined; on runtimes without the native JSON module it returns {:error, :json_not_available} instead of the module simply not existing.

Tooling, docs, and tests

  • CI matrix extended to Elixir 1.20 / OTP 29 (released since 0.10.0): the test job now covers 1.18/27 (the mix.exs floor), 1.19/28, 1.20/28, and 1.20/29; the dialyzer and publish jobs run on 1.20/29. The README's quoted range is pinned to the workflow file by a test.
  • All compiler warnings cleared — mix compile --warnings-as-errors, which CI runs and which gates the release job, now passes. Twelve were unreachable atom_to_type/1 clauses; three were unpinned bitstring size variables.
  • Dialyzer configured (plt_add_apps for the optional transports); stream_data added for property-based tests. mix dialyzer now passes cleanly, which matters because the release job declares needs: [test, dialyzer] — two errors were failing it:
    • MqttX.Server.WillDelay's ctx() type omitted :max_retained_messages, a key the module itself reads when republishing a delayed Will. The type and the code had disagreed since the retained-message cap was added.
    • The Will delay passed to WillDelay.schedule/4 was only inferred as integer(), not the non_neg_integer() the contract requires. The values do come from 32-bit unsigned properties, but nothing enforced it; a float or negative reaching Process.send_after/3 would crash the supervised WillDelay process and silently drop the Will. The invariant is now enforced at the boundary by a guarded will_delay_ms/1.
  • Removed a defensive _other clause in MqttX.Packet.Properties.decode/2 that dialyzer proved unreachable: it guarded against a property decoder leaking a bare atom, which is now prevented at its source by the explicit else on the Varint.decode/1 with. decode_utf8/1 and decode_binary/1 were confirmed to return proper {:error, _} tuples.
  • Dependencies refreshed: thousand_island 1.5.0, bandit 1.12.4, telemetry 1.4.2, ranch 2.2.1, protox 2.0.9, ex_doc 0.40.3.
  • websock_adapter requirement widened to ~> 0.5 or ~> 0.6. 0.6.0 makes no API change — its only change is a default max_frame_size of 10 MB (previously :infinity) — but the old ~> 0.5 requirement excluded it and would have blocked installation for any app already on 0.6. The WebSocket transport gained a :max_frame_size option so this limit can be set explicitly rather than varying with the resolved adapter version.
  • Documentation overhaul. Installation and Quick Start moved to the top of the README, with the cellular-IoT analysis extracted to a new Why MQTT for IoT guide. use MqttX, the proxy option, the secure-TLS default, the :publish_error event, and the new server options are documented across the README, guides, AGENTS.md, and moduledocs. Telemetry docs now state the real topic shape (inbound events carry decoded segment lists, not binaries) and list the new exception event.
  • Documentation examples are now tested (documentation_test.exs): every fenced elixir block in the README, guides, and AGENTS.md must parse, every MqttX.* function it calls must exist at that arity, transport: values must name real modules, and the declared {:mqttx, "~> x.y"} version must match mix.exs. This caught a landing-page example that raised UndefinedFunctionError and a guide pinning an outdated version.
  • Fixed the websock_adapter requirement in the install instructions. The README, AGENTS.md, and the getting-started and server guides all told users to add {:websock_adapter, "~> 0.5"} — the very requirement that was widened to "~> 0.5 or ~> 0.6" in mix.exs, so anyone copying the snippet re-created the resolution failure the widening was meant to fix. All four now match, and a test pins every documented dependency requirement to mix.exs.
  • guides/server.md now documents every server callback. handle_puback/2 and handle_auth/3 were missing from the "Callback Summary" table, so a broker author could not discover MQTT 5.0 enhanced authentication or QoS 1 delivery confirmation from the guide. The table is now pinned to MqttX.Server.behaviour_info(:callbacks) by a test.
  • The clean-session limitation is no longer buried. The note that session_present is always false sat as an H3 inside "MQTT 5.0 Protocol Features", though it applies to every protocol version; it is now a top-level Session State section next to Session Expiry.
  • Duplicated examples consolidated to one canonical copy. The handler example, the use MqttX example, and the codec benchmark table each existed in three to five places and had already drifted apart. The guides are now canonical for how-to material and the README links to them; the copies that must stay (AGENTS.md, which is meant to be self-contained, and moduledocs, which must stand alone on their hexdocs page) are pinned by tests that fail when the benchmark figures, the handler event list, or the use MqttX callback set diverge.
  • New regression suites: malformed-packet decoding, Ranch adapter integration (previously zero Ranch tests), inbound topic aliases, resubscribe on reconnect, in-flight resend/discard, the non-blocking connect FSM, declared-length enforcement, SUBACK/UNSUBACK validation, encode length guards, multi-filter shared subscriptions, session takeover, session-expiry cancellation, DISCONNECT expiry revision, retain_handling: 1, the outbound Receive Maximum queue, and idle/handshake timeouts.
  • Property-based codec tests: round-trips for PUBLISH/SUBSCRIBE/acks/CONNECT/ properties/varints, plus "decode never raises" over arbitrary bytes and bit-flipped valid packets.
  • Client unit tests use guaranteed-closed ephemeral ports instead of assuming nothing listens on localhost:1883.

[0.10.0] - 2026-05-07

Spec-compliance and correctness sweep against MQTT 5.0 (OASIS), plus server/ client robustness fixes. EMQX interop suite (49 tests against a live broker) remains 100% green. No changes to the function API surface, but note the behavioral/wire default change below: the default protocol_version flipped from 4 to 5, which is observable by brokers and dependents.

Changed (potentially breaking at the wire level — stricter spec compliance)

  • Default protocol_version is now 5 (was 4). Library is marketed "MQTT 5.0" and v5 features (topic aliases, AUTH, properties, reason codes) were silently dropped under the v3.1.1 default. MqttX.Client.connect(protocol_version: 4) to opt in to v3.1.1.
  • Server now rejects unsupported protocol versions with CONNACK 0x84 (v5) / 0x01 (v3.x). Default allowlist [3, 4, 5] configurable via :supported_versions in transport_opts.

Fixed (codec — MqttX.Packet.Codec / MqttX.Packet.Properties)

  • PUBLISH with QoS=3 rejected as Malformed Packet (§3.3.1.2)
  • PUBLISH with DUP=1 + QoS=0 rejected (§3.3.1.1)
  • CONNECT reserved bit must be 0 (§3.1.2.3); non-zero fixed-header flags rejected (§3.1.1)
  • Will Flag=0 with non-zero Will QoS or Will Retain rejected (§3.1.2.6/7)
  • Will QoS=3 rejected (§3.1.2.6)
  • v3.x username flag=0 with password flag=1 rejected (§3.1.2.9)
  • Empty SUBSCRIBE / UNSUBSCRIBE payload rejected as Protocol Error (§3.8.3 / §3.10.3)
  • Subscription Options reserved bits non-zero, QoS=3, RH=3 rejected (§3.8.3.1)
  • DISCONNECT and AUTH 1-byte forms (reason code only, no property length) accepted per §3.14.2.2.1 / §3.15.2.2.1
  • UTF-8 strings now reject U+0000 (null) and U+D800–U+DFFF (surrogates) per §1.5.4
  • Malformed CONNECT no longer crashes the codec with MatchError; surfaces :malformed_packet
  • Invalid SUBACK/UNSUBACK reason bytes return :malformed_packet instead of crashing
  • Properties — duplicate non-User-Property properties rejected as Protocol Error (§2.2.2.2)
  • Property value-0 rejection: Subscription Identifier (§3.8.2.1.2), Receive Maximum (§3.1.2.11.3), Maximum Packet Size (§3.1.2.11.4)
  • Boolean properties (Payload Format Indicator, Request Problem Information, Retain Available, etc.) reject non-0/1 byte values
  • Maximum QoS rejects values > 2
  • User-Property accumulation switched from O(n²) ++ [val] to prepend + reverse-once
  • Subscription-Identifier list switched from O(n²) ++ [val] to prepend + reverse-once

Fixed (topic — MqttX.Topic)

  • +/# filters at the first level no longer match $SYS/...-style topics (§4.7.2)
  • Topic length capped at 65535 bytes (§1.5.4)
  • Shared subscription $share/<group>/... rejects + or # in ShareName (§4.8.2)
  • flatten/1 switched from O(n²) binary concat to iolist + Enum.intersperse

Fixed (server — MqttX.Transport.Handler / MqttX.Server.Router / MqttX.Server.RateLimiter)

  • Outgoing QoS 1 retransmission on the server (§4.4). Outbound QoS 1 PUBLISHes are now tracked in pending_qos1_tx; the existing periodic retry timer re-sends with DUP=true after qos2_retry_interval ms, dropping after qos2_max_retries attempts. PUBACK arrival clears the entry. Previously QoS 1 outbound was fire-and-forget — a lost PUBACK silently dropped the message.

  • Receive Maximum applies to QoS 1 inbound as well as QoS 2 (§3.1.2.11.3). Previously the limit was only checked for QoS 2; a client could fill the flow-control window with un-PUBCOMP'd QoS 2 messages and then push QoS 1 publishes through unbounded. The handler now responds to a QoS 1 PUBLISH exceeding the limit with PUBACK reason 0x93 (Receive Maximum exceeded). QoS 2 excess continues to receive PUBREC 0x93 (spec permits either per-message ack or DISCONNECT).

  • Critical: retained-publish packet IDs now come from next_packet_id instead of :rand.uniform/1 — was colliding with the QoS sequence allocator and breaking ack matching

  • Will message published exactly once on keepalive timeout / handle_close / handle_error (was double-publishing through two paths)

  • DISCONNECT reason code 0x04 publishes the Will; other reason codes suppress it (§3.14.4) — previously the reason code was ignored

  • Empty topic with un-mapped Topic Alias triggers DISCONNECT 0x94 (§3.3.4) — previously dispatched an empty-topic PUBLISH to the user handler

  • Outbound oversize-drop rolls back the packet_id allocation (was leaking)

  • Duplicate PUBREC after PUBREL no longer re-sends PUBREL (§4.3.3 fig 4.4)

  • AUTH-before-CONNECT now sends DISCONNECT 0x82 instead of leaving the handler in a broken state (CONNACK with protocol_version: nil)

  • Will Delay Interval timers (§3.1.3.2.2) now owned by a supervised MqttX.Server.WillDelay GenServer under the application supervisor; cancelled on same-client_id reconnect

  • Rate-limiter ETS table now created with read_concurrency: true

Fixed (client — MqttX.Client.Connection)

  • Critical: retry-loop reducer arity bug fixed — was crashing with MatchError once both {:rx, _} and {:tx, _} pending_acks entries coexisted on the same connection
  • keepalive == 0 correctly disables the keepalive timer (was scheduling a zero-millisecond tight loop)
  • PINGRESP timeout: client now arms a deadline at keepalive*1500ms on every PINGREQ; if PINGRESP doesn't arrive, the socket is torn down and reconnect is scheduled. Half-dead brokers no longer require TCP teardown to detect.
  • session_present from CONNACK now surfaced to the handler in the :connected event; warns on MQTT-3.2.2-2 violation (clean_session=true but session_present=true)
  • Server-initiated DISCONNECT now closes the socket immediately and schedules reconnect (was waiting for :tcp_closed to land separately)
  • AUTH continuation in wait_for_connack re-arms set_socket_active/1 so multi-step AUTH doesn't hang after the first packet
  • AUTH packet property names corrected: :auth_method / :auth_data → :authentication_method / :authentication_data
  • next_packet_id skips IDs currently in pending_acks (§2.2.1)
  • schedule_reconnect cancels any existing reconnect timer (no more stacked timers when several disconnect events fire)
  • set_socket_active guards against nil socket (server-disconnect race)
  • Pending SUBACK/UNSUBACK callers monitored via Process.monitor; entry dropped on :DOWN (was leaking after GenServer.call timeouts)

Fixed (WebSocket client — MqttX.Client.WebSocket)

  • Sec-WebSocket-Accept now validated as Base64(SHA1(client_key + magic GUID)) per RFC 6455 §4.1; status line strictly matched as HTTP/1.x 101 …
  • Sec-WebSocket-Protocol echo checked (warn-only on missing — common with MQTT brokers that nonetheless speak it correctly)
  • FIN-bit fragmentation: opaque frag_state threaded across decode_frames/2 calls so multi-frame messages split across TCP reads reassemble correctly
  • Frame masking switched from byte-by-byte recursion to :crypto.exor/2 against a pre-padded mask buffer (orders-of-magnitude faster on large payloads)

Added

  • MqttX.Session.ETSOwner — a long-lived owner of the default :mqttx_sessions ETS table under the application supervisor. Previously the table was owned by whichever client first called MqttX.Session.ETSStore.init/1, so all sessions were lost when that process exited. The table is now created with read_concurrency: true, write_concurrency: true.
  • MqttX.Server.WillDelay — supervised GenServer that owns Will Delay Interval timers across connection lifecycles, with per-client_id cancellation.
  • :supported_versions server transport option (default [3, 4, 5]).

Documentation

  • AGENTS.md — usage guide for AI coding assistants integrating MqttX into projects: mental model (client vs broker), transport selection, idiomatic patterns (receive-on-client, broker↔PubSub bridge, persistent sessions, custom auth), and a curated list of mistakes commonly made (publishing wildcards, confusing handle_publish with handle_mqtt_event, random client_id per connect, default-to-QoS-2, $SYS exclusion). Shipped in the hex package and rendered on hexdocs.
  • CONTRIBUTING.md — repo orientation for contributors: layout, test commands, known test-environment couplings, and the deferred TODO carried over from the v0.9.0 spec sweep. CLAUDE.md is now a symlink to AGENTS.md for tool compatibility.
  • README "Common Patterns" section with worked examples for receiving messages on the client (handle_mqtt_event/3), broadcasting from the server via handle_info/2, and resuming MQTT 5.0 sessions with session_expiry_interval.
  • README "Common Pitfalls" section covering session-store / clean_session interaction, server keepalive override, max-packet-size enforcement, publish-vs-subscribe wildcard rules, and $SYS topic exclusion.

[0.9.0] - 2026-03-30

Added

  • Server keepalive override (MQTT 5.0): Configurable server_keep_alive in transport_opts — server sends keepalive override in CONNACK and uses it for the keepalive timer when protocol version >= 5
  • handle_connect/4 callback (optional): New handle_connect(client_id, credentials, connect_info, state) callback that receives connection metadata (protocol_version, keep_alive) separately from credentials. Existing handle_connect/3 continues to work unchanged — handle_connect/4 takes precedence when defined

[0.8.0] - 2026-03-11

Added

  • Complete MQTT 5.0 Client Compliance: Closed all remaining client-side spec gaps
    • server_keep_alive: Client applies server's keepalive override from CONNACK (§3.2.2.3.14)
    • assigned_client_identifier: Client adopts server-assigned client ID from CONNACK (§3.2.2.3.7)
    • maximum_packet_size: Client enforces server's maximum packet size from CONNACK; oversized outgoing packets return {:error, :packet_too_large} (§3.2.2.3.6)
    • server_reference: Client parses and logs server redirect on CONNACK rejection and server DISCONNECT (§3.2.2.3.18)
    • Enhanced AUTH: Client handles multi-step AUTH exchange during and after CONNECT via handle_auth/3 callback (§4.12)
  • EMQX Cloud Interop: 49 automated interop tests against EMQX Cloud broker
  • SUBACK Reason Code Checking: subscribe/3 now returns {:ok, [granted_qos]} or {:error, {:subscription_refused, acks}} based on actual SUBACK response
  • Outgoing Topic Aliases (MQTT 5.0): Client automatically assigns and reuses topic aliases for repeated publish topics, reducing bandwidth
  • DISCONNECT with Reason Code: disconnect/2 accepts :reason_code and :properties options for MQTT 5.0 graceful disconnect
  • WebSocket Client Transport: Connect to brokers over WebSocket with transport: :ws or transport: :wss (RFC 6455 binary framing)
  • Reason String Surfacing: Server reason strings from SUBACK, UNSUBACK, PUBACK, DISCONNECT are logged automatically

Fixed

  • Formatting issues across multiple files (CI compliance)
  • Dialyzer callback_type_mismatch in WebSocket transport close/1 (now returns :ok per behaviour spec)
  • WebSocket frame decoder byte-alignment bug in decode_one_frame (mask_bit extraction)

[0.7.0] - 2026-03-05

Added

  • Full MQTT 3.1/3.1.1/5.0 Compliance: Closed all remaining spec compliance gaps
    • Pre-CONNECT packet rejection: Non-CONNECT/AUTH packets before CONNECT now trigger DISCONNECT 0x82 (Protocol Error) per spec
    • Topic alias validation: Incoming topic aliases are validated against topic_alias_maximum; out-of-range aliases trigger DISCONNECT 0x94
    • MQTT 5.0 property forwarding: Outgoing PUBLISH packets now forward properties (user_properties, content_type, correlation_data, etc.) from handler callbacks
    • CONNACK capability properties: Server advertises retain_available, wildcard_subscription_available, and subscription_identifier_available in CONNACK for MQTT 5.0 connections
    • retain_handling support: Subscription option retain_handling: 2 suppresses retained message delivery on subscribe
    • no_local support: Router.match/3 and Router.match_and_advance/3 accept optional publisher parameter to filter out subscriptions with no_local: true
    • Client server DISCONNECT handling: Client now handles server-initiated DISCONNECT packets, notifying the handler with {:server_disconnect, reason_code}
  • QoS 2 Retransmission & DUP Handling (Server): Periodic retry timer re-sends PUBREC/PUBLISH(dup)/PUBREL for stale in-flight QoS 2 messages; drops after configurable max retries. DUP incoming PUBLISH re-sends PUBREC without re-delivering.
  • Topic Aliases (MQTT 5.0 Server): Incoming PUBLISH with topic_alias property resolved automatically. Server advertises topic_alias_maximum in CONNACK. Alias-only publishes (empty topic) look up stored mapping.
  • Flow Control / Receive Maximum (MQTT 5.0 Server): Server enforces receive_maximum for incoming QoS 2 messages. Excess publishes receive PUBREC with reason code 0x93 (Receive Maximum exceeded). Server advertises receive_maximum in CONNACK.
  • Maximum Packet Size (MQTT 5.0 Server): Configurable max_packet_size option. Oversized incoming packets trigger DISCONNECT with reason code 0x95 (Packet too large). Outgoing publishes exceeding client's maximum_packet_size are silently dropped. Server advertises maximum_packet_size in CONNACK when configured.
  • WebSocket Transport: MQTT over WebSocket via Bandit, supporting all MQTT protocol features over ws:// and wss:// connections.
  • Mosquitto Validation Suite: 104 automated tests against Mosquitto clients across TCP and WebSocket transports, covering all protocol versions and MQTT 5.0 features.
  • Handler tests: 30+ new tests covering compliance features, QoS 2 full flow, DUP handling, retry timer, CONNACK properties, topic aliases, flow control, max packet size, and server-initiated DISCONNECT.

Changed

  • Codec: MQTT 5.0 PUBLISH with empty topic is now valid when topic_alias property is present (per MQTT 5.0 spec section 3.3.2.1)
  • QoS 2 pending entries: pending_qos2_rx entries now include timestamps and retry counts; pending_qos2_tx entries are enriched maps with phase, packet, timestamp, and retry info
  • Router API: match/2 → match/3 and match_and_advance/2 → match_and_advance/3 with optional publisher parameter (backward compatible, defaults to nil)

Fixed

  • Server PUBREL handler now correctly extracts packet/opts from both legacy 2-tuple and new 4-tuple pending_qos2_rx entries

[0.6.1] - 2026-03-02

Fixed

  • Logo rendering on hexdocs.pm (use absolute URL for README image)
  • CI: increased GenServer.stop timeout in client tests for slower runners
  • CI: skip JSON payload tests on OTP < 27
  • Removed accidentally committed mqttx-0.1.0 directory

[0.6.0] - 2026-03-02

Added

  • Connection Supervision: MqttX.Client.Supervisor DynamicSupervisor for managed client connections
  • Rate Limiting: Per-client connection and message rate limiting for MQTT servers
    • MqttX.Server.RateLimiter module with ETS-based atomic counters
    • Connection rate limiting (configurable max connections per interval)
    • Per-client message rate limiting (configurable max messages per client per interval)
    • MQTT 5.0 reason code 0x96 (message_rate_too_high) sent for rate-limited QoS 1+ publishes
    • Integrated into both ThousandIsland and Ranch transport adapters
    • Configured via :rate_limit option in MqttX.Server.start_link/3
  • Capacity Planning guide: Device-per-vCPU sizing tables for IoT workloads (sleepy sensors through real-time streaming), instance sizing recommendations
  • Performance & Scaling guide: Architecture decisions, trie router internals, VM/OS tuning, and deployment guidelines
  • Project Branding: MqttX logo in README and hexdocs
  • EMQX interop test suite: 49 tests against live EMQX broker covering MQTT 5.0 features
  • Server Keepalive Timeout: Disconnects clients that stop sending packets within 1.5x keep_alive seconds (MQTT spec compliance)
    • Automatic timer start after CONNACK, reset on every received packet
    • Will message published on keepalive timeout (ungraceful disconnect)
  • Will Delay Interval (MQTT 5.0): Delays will message publication by will_delay_interval seconds after ungraceful disconnect
    • will_delay_interval: 0 (or MQTT 3.1.1) publishes immediately (backward compatible)
    • Will properties forwarded to handler
  • Session Expiry Timer (MQTT 5.0): Fires handle_session_expired/2 callback after session_expiry_interval seconds post-disconnect
    • 0 = expire immediately, 0xFFFFFFFF = never expire
    • New optional handle_session_expired/2 callback in MqttX.Server behaviour
  • Server-Initiated Disconnect: Kick clients with MQTT 5.0 reason codes
    • MqttX.Server.disconnect/3 sends DISCONNECT and closes connection
    • {:disconnect, reason_code, state} return type from handle_publish, handle_subscribe, handle_unsubscribe, handle_info
    • Ranch transport now properly forwards handle_info messages to handler (was silently dropping them)

Changed

  • Trie-based Topic Router: Replaced O(N) linear scan with a trie data structure for O(L+K) topic matching — independent of total subscription count. Same public API.
  • iodata Encoding: Socket sends use Codec.encode_iodata/2 in all transports, avoiding binary copies on every packet
  • Empty-buffer fast path: Skips binary concatenation when the TCP buffer is empty (common case)
  • Cached callback dispatch: function_exported? computed once at connection init, not per message
  • Direct inflight counter: O(1) flow control check instead of scanning pending_acks
  • Retained message delivery: Exact topic subscriptions use O(1) ETS lookup instead of full table scan

Fixed

  • Handler state lost on callbacks: notify_handler now correctly returns updated handler state (was silently discarding it)
  • Missing retries field in pending_acks: QoS 1/2 pending_acks entries now include retries: 0 (prevented retry tracking)
  • Session not saved on socket close: Session data now persists on unexpected TCP close/error, not just clean disconnect
  • Queued messages not delivered on reconnect: Buffer is now processed after CONNACK for persistent sessions
  • Protobuf codec crash on non-protobuf structs: Now returns {:error, {:protobuf_encode_error, _}} instead of raising
  • Protobuf codec crash on unknown module: Now returns {:error, {:unknown_message_module, module}} instead of raising
  • Removed dead outgoing topic alias code (topic_to_alias, next_alias) that was never functional
  • MqttX.version/0 now returns correct version string
  • Guides now included in hex.pm docs

[0.5.0] - 2026-01-15

Added

  • Telemetry Integration: Comprehensive :telemetry events for observability
    • Client events: connect, disconnect, publish, subscribe, message
    • Server events: client_connect, client_disconnect, publish, subscribe
    • New MqttX.Telemetry module with helper functions
  • Shared Subscriptions (MQTT 5.0): $share/group/topic pattern for load balancing
    • Round-robin distribution across group members
    • Router.match_and_advance/2 for stateful distribution
    • Automatic group cleanup when last member leaves
  • Topic Alias (MQTT 5.0): Bandwidth reduction for repeated topics
    • Client stores topic_alias_maximum from CONNACK
    • Resolves incoming topic aliases automatically
    • alias_to_topic map in connection state
  • Message Expiry (MQTT 5.0): Respects message_expiry_interval property
    • Retained messages stored with timestamp
    • Expired messages skipped on delivery
    • Remaining expiry sent in delivered messages
  • Flow Control (MQTT 5.0): Enforces receive_maximum for backpressure
    • Client tracks inflight QoS 1/2 message count
    • Returns {:error, :flow_control} when limit reached
    • Stores receive_maximum from CONNACK
  • Enhanced Auth (MQTT 5.0): SASL-style authentication callback
    • New handle_auth/3 callback in MqttX.Server behaviour
    • Default implementation returns error (not supported)
  • Request/Response (MQTT 5.0): Helper for request/response pattern
    • MqttX.Client.request/4 function
    • Passes response_topic and correlation_data properties
    • :properties option in publish/4

Changed

  • Transport adapters store retained messages with expiry metadata (5-tuple ETS format)
  • Client connection state includes topic alias and receive_maximum fields

[0.4.0] - 2026-01-15

Added

  • TLS/SSL Client Support: Optional TLS via :transport option (:tcp or :ssl)
    • :ssl_opts for SSL configuration (verify, cacerts, etc.)
    • Default port 8883 for SSL connections
  • QoS 2 Complete Flow: Full PUBREC/PUBREL/PUBCOMP handshake implementation
    • Client tracks outgoing QoS 2 messages through all phases
    • Client handles incoming QoS 2 messages correctly
  • Message Inflight Tracking: Timer-based retry for unacknowledged QoS 1/2 messages
    • Configurable :retry_interval option (default: 5000ms)
    • Automatic retry with dup: true flag
    • Max 3 retries before dropping message
  • Retained Messages: Server stores and delivers retained messages
    • ETS-based storage per server instance
    • Delivered to new subscribers on SUBSCRIBE
    • Empty payload clears retained message
  • Will Message Delivery: Server publishes will message on ungraceful disconnect
    • Stored from CONNECT packet
    • Published when connection closes without DISCONNECT
    • Supports retained will messages
  • Session Persistence: Configurable session storage for clean_session: false

Changed

  • Client connection state now tracks subscriptions for session persistence
  • Transport adapters create ETS tables for retained messages

[0.3.0] - 2026-01-15

Added

  • MQTT vs WebSocket JSON performance comparison in README
  • Comprehensive API reference documentation in README
  • New test files for improved coverage:
    • backoff_test.exs - exponential backoff logic tests
    • properties_test.exs - MQTT 5.0 properties encode/decode tests
    • client_test.exs - client API tests
    • server_test.exs - server behaviour and callback tests
  • MQTT 5.0 packet tests (AUTH, DISCONNECT with reason codes, properties)
  • MQTT 3.1 packet tests
  • Edge case tests (empty payload, large payload, max packet ID, unicode topics)

Changed

  • Updated ThousandIsland dependency to ~> 1.4 (was ~> 1.0)
  • Updated Ranch dependency to ~> 2.2 (was ~> 2.1)
  • Updated Protox dependency to ~> 2.0 (was >= 1.7.0)

Fixed

  • Formatting issues in thousand_island.ex
  • Protobuf payload codec updated for Protox 2.0 API changes (encode returns 3-tuple)

[0.2.0] - 2026-01-15

Added

  • handle_info/2 callback for MqttX.Server to handle custom messages (e.g., PubSub)
  • Support for outgoing PUBLISH via {:publish, topic, payload, state} return value
  • Enables bidirectional communication (server can push messages to connected clients)

[0.1.6] - 2026-01-15

Changed

  • Broadened protox dependency to support both 1.x and 2.x (>= 1.7.0)

[0.1.5] - 2026-01-15

Added

  • GitHub Actions CI workflow (tests on Elixir 1.18-1.19, OTP 27-28, dialyzer)
  • Roadmap section in README
  • Username/password example in client documentation
  • Changelog link on hex.pm package page
  • Hex.pm, Docs, and CI badges to README

Changed

  • Documentation landing page now shows README instead of module docs

Fixed

  • JSON payload codec now conditionally compiles only on OTP 27+
  • Code formatting issues
  • Version test no longer hardcodes version string
  • Dialyzer false positives for defensive pattern matching

[0.1.1] - 2026-01-15

Added

  • GitHub Actions CI workflow (tests, formatting, dialyzer)
  • Roadmap section in README
  • Username/password example in client documentation
  • Changelog link on hex.pm package page

Fixed

  • JSON codec description now correctly references built-in Erlang/OTP 27+ module

[0.1.0] - 2026-01-14

Added

  • Initial release
  • MQTT packet codec supporting MQTT 3.1, 3.1.1, and 5.0
  • All 15 MQTT packet types
  • MQTT 5.0 properties support
  • ThousandIsland transport adapter
  • Ranch transport adapter
  • MQTT Server behaviour with handler callbacks
  • Topic router with wildcard support (+, #)
  • MQTT Client with automatic reconnection
  • JSON payload codec (via built-in Erlang/OTP 27+ JSON module)
  • Protobuf payload codec (via Protox)
  • Raw binary payload codec
  • Comprehensive test suite