zzq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ecbbe3094e3570604ee7b7b1b69d45d4a088c4da2dffb9c04a79d8b07475ac8
+  data.tar.gz: 9daf51c7c1b2c7e30c33b306b5e4aad5440ef0af129f261951a13b74e30163af
+SHA512:
+  metadata.gz: be9e2fa7e9159f333122b40b8776dfc659527d3c37153f7b94bc88eb3732e4fd11d4093e5cfb4366b105032a97bf9cda76334d019126d537dbb767b490586bd5
+  data.tar.gz: c1d8ae054e97e5e9a5ec90c3a403933e59b5ae55e67b29a5bc65bd3df126719c990770e8f8563e29a76fe728ae14c27b0c2b7a6c6311a885ee2dc4d82a713b53

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## v0.1.0 — 2026-04-20
+
+- First release. Async-native MQTT 3.1.1 + 5.0 client and broker in
+  one gem, built on `async`, `io-stream`, and `protocol-mqtt`.
+- Transports: `mqtt://` (plain TCP, port 1883), `mqtts://` (TLS,
+  port 8883), `ipc://` (Unix-domain sockets, filesystem and Linux
+  abstract namespace).
+- `mqtts://` accepts any `OpenSSL::SSL::SSLContext` and drops the
+  connection at 128 GiB of application data so reconnects force
+  fresh keys before AEAD nonce counters approach their unsafe
+  range.
+- Retained-message persistence: in-memory (default) or stdlib
+  `PStore` with `ultra_safe = true` for fsync-on-commit durability.
+- Broker-to-broker bridging via `Client` + `Broker` composition;
+  MQTT v5 `no_local` loop guard supported.

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026, Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# ZZQ — async-native MQTT for Ruby
+
+> Codename **Zanzara** — Italian for "mosquito", in the same spirit as
+> the Mosquitto broker that popularised MQTT. `zzq` keeps the
+> three-letter gem-name symmetry with its siblings `omq` and `nnq`.
+
+[![CI](https://github.com/paddor/zzq/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/zzq/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/zzq?color=e9573f)](https://rubygems.org/gems/zzq)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%204.0-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
+ZZQ is a pure-Ruby MQTT 3.1.1 + 5.0 implementation — **client and
+broker in one gem** — built on [async](https://github.com/socketry/async),
+[io-stream](https://github.com/socketry/io-stream), and
+[protocol-mqtt](https://github.com/paddor/protocol-mqtt). It applies
+the [omq](https://github.com/paddor/omq) / [nnq](https://github.com/paddor/nnq)
+architecture to MQTT.
+
+Status: pre-alpha. See [the design plan](../../.claude/plans/omq-and-nnq-s-design-robust-dolphin.md) for scope and roadmap.
+
+## Quickstart
+
+```ruby
+require "zzq"
+require "async"
+
+# Client
+Async do
+  client = ZZQ::Client.new(client_id: "sensor-42", version: 5, keepalive: 30)
+  client.connect("mqtt://broker.example:1883") do |task|
+    sub = client.subscribe("cmd/#", qos: 1)
+    task.async do
+      sub.each { |msg| puts "#{msg.topic}: #{msg.payload}" }
+    end
+    client.publish("status/sensor-42", "online", qos: 1, retain: true)
+  end
+end
+
+# Broker
+Async do
+  ctx = OpenSSL::SSL::SSLContext.new
+  ctx.cert = OpenSSL::X509::Certificate.new(File.read("server.crt"))
+  ctx.key  = OpenSSL::PKey.read(File.read("server.key"))
+  # Recommended: TLS 1.3 with DJB-family AEAD.
+  ctx.min_version  = OpenSSL::SSL::TLS1_3_VERSION
+  ctx.max_version  = OpenSSL::SSL::TLS1_3_VERSION
+  ctx.ciphersuites = "TLS_CHACHA20_POLY1305_SHA256"
+
+  broker = ZZQ::Broker.new
+  broker.bind("mqtt://0.0.0.0:1883")
+  broker.bind("mqtts://0.0.0.0:8883", tls_context: ctx)
+  # ... bind more transports on the same broker
+end
+```
+
+## Transports
+
+- `mqtt://` — plain MQTT over TCP (default port 1883).
+- `mqtts://` — MQTT over TLS (default port 8883). Takes any
+  `OpenSSL::SSL::SSLContext` via `tls_context:`; the recommended
+  configuration is TLS 1.3 pinned to `TLS_CHACHA20_POLY1305_SHA256`
+  as shown above. The transport drops the connection at 128 GiB
+  of application data — well below ChaCha20-Poly1305's ~256 GiB
+  per-key integrity bound — so reconnects force fresh keys before
+  AEAD nonce counters approach their unsafe range.
+- `ws://` / `wss://` — MQTT over WebSockets.
+- `ipc:///path` — Unix-domain socket, filesystem path.
+- `ipc://@abstract` — Linux abstract-namespace Unix socket.
+
+## Persistence
+
+By default the broker keeps retained messages in process memory — fast,
+zero-config, and lost when the process exits. That's the right choice
+for tests and ephemeral workloads.
+
+For durability across restarts, pass a `PStore`-backed persistence
+object. It uses stdlib [`PStore`](https://docs.ruby-lang.org/en/master/PStore.html)
+with `ultra_safe = true` so every commit fsyncs the data file and its
+parent directory — retained state survives power loss, not just clean
+shutdowns.
+
+```ruby
+# Default: in-memory, ephemeral
+broker = ZZQ::Broker.new
+
+# Explicit in-memory (same as default)
+broker = ZZQ::Broker.new persistence: ZZQ::Persistence::Memory.new
+
+# Durable: retained messages persist to ./zzq-data/
+persistence = ZZQ::Persistence::PStore.new data_dir: "./zzq-data"
+broker = ZZQ::Broker.new persistence: persistence
+```
+
+PStore is single-process only — file locking doesn't coordinate across
+processes. For HA deployments, a future external adapter (Redis,
+SQLite) will ship as a separate gem.
+
+## Bridging two brokers
+
+ZZQ does not ship a `Bridge` class — broker-to-broker forwarding is a
+short composition of a `Client` and a local `Broker`. Subscribe on one
+side, publish to the other:
+
+```ruby
+require "zzq"
+require "async"
+
+Async do |task|
+  upstream = ZZQ::Client.new(client_id: "site-42-bridge", version: 5)
+  local    = ZZQ::Broker.new
+
+  upstream.connect("mqtts://cloud.example:8883")
+  local.bind("mqtt://0.0.0.0:1883")
+
+  # local → upstream: forward telemetry out.
+  task.async do
+    local.subscribe("telemetry/#", qos: 1).each do |m|
+      upstream.publish(m.topic, m.payload, qos: m.qos, retain: m.retain)
+    end
+  end
+
+  # upstream → local: pull commands in. `Broker#<<` fans the Message
+  # straight into the local broker's delivery path — no need to pick
+  # apart and re-pack fields (alias of `#ingest`).
+  task.async do
+    upstream.subscribe("cmd/#", qos: 1, no_local: true).each do |m|
+      local << m
+    end
+  end
+end
+```
+
+Loop guard for two-way routes:
+
+* MQTT v5: pass `no_local: true` on the subscribe call — the spec
+  forbids the broker from echoing back to the publisher of the
+  subscription, so messages originating on one side don't bounce.
+* MQTT v3.1.1: no `no_local`. Use non-overlapping filters on each
+  direction, or tag topics with a side-specific prefix.
+
+## When MQTT, when OMQ/NNQ
+
+MQTT bridging makes sense only when the remote speaks MQTT and nothing
+else (AWS IoT Core, HiveMQ Cloud, partner Mosquitto). For inter-service
+comm where both ends are under your control, reach for
+[omq](https://github.com/paddor/omq) or [nnq](https://github.com/paddor/nnq)
+— cleaner wire format, no protocol overhead. ZZQ exposes
+`ZZQ::Message#to_wire` / `.from_wire` so you can ship MQTT messages
+across an OMQ/NNQ socket without re-encoding.
+
+## License
+
+ISC. See [LICENSE](LICENSE).

data/lib/zzq/broker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+
+module ZZQ
+  # MQTT broker. Owns the session map (by client id), retained-message
+  # store, topic trie, and shared-subscription groups.
+  #
+  # M3 stub: constructor + {#build_routing}. CONNECT handling,
+  # subscription matching, and retained store come in M7.
+  class Broker < Socket
+    def build_routing(engine)
+      Routing::Broker.new(engine)
+    end
+
+
+    # Number of currently-connected MQTT sessions.
+    def session_count = @engine.routing.session_count
+
+
+    # Inject a {ZZQ::Message} into the broker's delivery path as if it
+    # had arrived via a PUBLISH packet. Fans out to every matching
+    # subscriber. Use this to bridge non-MQTT inputs (NNQ, OMQ, a
+    # file) into broker topics.
+    def ingest(message)
+      raise NotInAsyncContext unless Async::Task.current?
+      @engine.routing.dispatch_message(message)
+      nil
+    end
+    alias_method :<<, :ingest
+  end
+end
+
+require_relative "routing/broker"

data/lib/zzq/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+
+module ZZQ
+  # MQTT client. Owns exactly one MQTT session at a time (possibly
+  # persisted across reconnects), subscriptions, and a QoS tracker for
+  # inflight PUB flows.
+  #
+  # M3 stub: only the constructor and {#build_routing} stand. The
+  # CONNECT/CONNACK handshake and publish/subscribe plumbing come in
+  # M4 / M5.
+  class Client < Socket
+    def build_routing(engine)
+      Routing::Client.new(engine)
+    end
+
+
+    # Most recent CONNACK received from the broker, or nil before the
+    # first successful connect.
+    def last_connack     = @engine.routing.last_connack
+    def session_present? = @engine.routing.session_present?
+
+
+    # Publish a message. For QoS 0 returns once the packet is
+    # written. For QoS 1 blocks until PUBACK; for QoS 2 blocks until
+    # PUBCOMP.
+    def publish(topic, payload, qos: 0, retain: false, properties: {})
+      raise NotInAsyncContext unless Async::Task.current?
+      @engine.routing.publish(
+        topic: topic, payload: coerce_binary(payload),
+        qos: qos, retain: retain, properties: properties,
+      )
+    end
+
+
+    # Subscribe to a topic filter. Returns a {ZZQ::Subscription} whose
+    # queue receives matching messages until it is closed.
+    def subscribe(filter, qos: 0, no_local: false, retain_as_published: false,
+                  retain_handling: 0)
+      raise NotInAsyncContext unless Async::Task.current?
+      @engine.routing.subscribe(
+        filter, qos: qos, no_local: no_local,
+        retain_as_published: retain_as_published,
+        retain_handling: retain_handling,
+      )
+    end
+  end
+end
+
+require_relative "routing/client"

data/lib/zzq/engine/connection_lifecycle.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "async/barrier"
+require "protocol/mqtt"
+
+module ZZQ
+  class Engine
+    # Owns the full arc of one connection: new → handshaking → ready →
+    # closed. Centralises side-effect ordering so routing doesn't have
+    # to.
+    #
+    # The MQTT CONNECT/CONNACK exchange itself is NOT performed here —
+    # it's role-asymmetric (client writes CONNECT first, broker reads
+    # it first) and so lives in the role's routing layer, which calls
+    # +handshake_succeeded!+ once the exchange is done.
+    #
+    #   new → handshaking → ready → closed
+    #
+    # #lost! / #close! are idempotent.
+    class ConnectionLifecycle
+      class InvalidTransition < RuntimeError; end
+
+      STATES = %i[new handshaking ready closed].freeze
+
+      TRANSITIONS = {
+        new:         %i[handshaking ready closed].freeze,
+        handshaking: %i[ready closed].freeze,
+        ready:       %i[closed].freeze,
+        closed:      [].freeze,
+      }.freeze
+
+
+      attr_reader :conn       # Protocol::MQTT::Connection
+      attr_reader :endpoint
+      attr_reader :state
+      attr_reader :barrier
+
+
+      def initialize(engine, endpoint:)
+        @engine   = engine
+        @endpoint = endpoint
+        @state    = :new
+        @conn     = nil
+        @barrier  = Async::Barrier.new(parent: engine.barrier)
+      end
+
+
+      # Wraps the accepted/connected IO in a Protocol::MQTT::Connection
+      # and returns it. The handshake itself (CONNECT/CONNACK exchange)
+      # is driven by the routing layer — this is "transport ready,
+      # MQTT handshake pending".
+      def begin_handshake!(io)
+        transition!(:handshaking)
+        mqtt = Protocol::MQTT::Connection.new(
+          io,
+          version: @engine.options.version,
+          max_packet_size: @engine.options.max_packet_size,
+        )
+        @conn = mqtt
+        mqtt
+      end
+
+
+      # Called by the routing layer after CONNECT/CONNACK succeeds.
+      def handshake_succeeded!
+        @engine.connections[@conn] = self
+        transition!(:ready)
+        begin
+          @engine.routing.connection_added(@conn) if @engine.routing.respond_to?(:connection_added)
+        rescue ConnectionRejected
+          @engine.emit_monitor_event(:connection_rejected, endpoint: @endpoint)
+          tear_down!(reconnect: false)
+          raise
+        end
+        @engine.lifecycle.peer_connected.resolve(@conn) unless @engine.lifecycle.peer_connected.resolved?
+        @engine.emit_monitor_event(:connected, endpoint: @endpoint)
+      end
+
+
+      # Called on handshake failure — e.g. refused CONNACK, RST mid-
+      # CONNECT. Tears down and requests a reconnect if eligible.
+      def handshake_failed!(error:)
+        @engine.emit_monitor_event(:handshake_failed, endpoint: @endpoint, detail: { error: error })
+        @conn&.close rescue nil
+        tear_down!(reconnect: true)
+      end
+
+
+      # Unexpected loss of an established connection.
+      def lost!
+        tear_down!(reconnect: true)
+      end
+
+
+      # Deliberate close (engine shutdown, kicked by broker, …).
+      def close!
+        tear_down!(reconnect: false)
+      end
+
+
+      # Starts a supervisor task that tears down when any pump exits.
+      def start_supervisor!
+        return if @barrier.empty?
+        @engine.barrier.async(transient: true, annotation: "zzq conn supervisor") do
+          @barrier.wait { |task| task.wait; break }
+        rescue Async::Stop, Async::Cancel
+        rescue *CONNECTION_LOST
+        ensure
+          lost!
+        end
+      end
+
+
+      private def tear_down!(reconnect: false)
+        return if @state == :closed
+        transition!(:closed)
+        if @conn
+          @engine.connections.delete(@conn)
+          @engine.routing.connection_removed(@conn) if @engine.routing.respond_to?(:connection_removed)
+          @conn.close rescue nil
+          @engine.emit_monitor_event(:disconnected, endpoint: @endpoint)
+          @engine.resolve_all_peers_gone_if_empty
+        end
+        @engine.maybe_reconnect(@endpoint) if reconnect
+        # Stop after cleanup: when tear_down! is called from a task on
+        # this barrier (e.g. the read-loop's ensure), stopping earlier
+        # would cancel the current fiber mid-cleanup.
+        @barrier.stop
+      end
+
+
+      private def transition!(new_state)
+        allowed = TRANSITIONS[@state]
+        raise InvalidTransition, "#{@state} → #{new_state}" unless allowed&.include?(new_state)
+        @state = new_state
+      end
+    end
+  end
+end

data/lib/zzq/engine/keepalive.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/clock"
+require "protocol/mqtt"
+
+module ZZQ
+  class Engine
+    # Keepalive driver for a single connection.
+    #
+    # +role+:
+    #   * +:sender+ (client default) — sends PINGREQ if locally idle
+    #     for keep_alive/2; closes if nothing received for 1.5 × keep_alive.
+    #   * +:watcher+ (broker default) — does not send; just closes if
+    #     nothing received for 1.5 × keep_alive. MQTT-3.1.2-22 is
+    #     enforced by the broker.
+    #
+    # One fiber per connection, attached to the connection's barrier
+    # so it tears down with the connection.
+    class Keepalive
+      attr_accessor :last_sent_at, :last_received_at
+
+
+      def initialize(conn, keep_alive:, on_timeout:, role: :sender)
+        @conn = conn
+        @keep_alive = keep_alive
+        @on_timeout = on_timeout
+        @role = role
+        now = Async::Clock.now
+        @last_sent_at = now
+        @last_received_at = now
+      end
+
+
+      # Call this every time a packet is written, to reset the send-idle
+      # timer.
+      def note_sent
+        @last_sent_at = Async::Clock.now
+      end
+
+
+      # Call this every time a packet is read, to reset the recv-idle
+      # timer.
+      def note_received
+        @last_received_at = Async::Clock.now
+      end
+
+
+      def run
+        return if @keep_alive.zero?  # 0 disables keepalive
+        loop do
+          sleep(@keep_alive / 2.0)
+          now = Async::Clock.now
+
+          if (now - @last_received_at) > (@keep_alive * 1.5)
+            @on_timeout.call
+            break
+          end
+
+          next unless @role == :sender
+
+          if (now - @last_sent_at) >= (@keep_alive / 2.0)
+            begin
+              @conn.write_packet(Protocol::MQTT::Packet::Pingreq.new)
+              note_sent
+            rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+              break
+            end
+          end
+        end
+      rescue Async::Stop
+      end
+    end
+  end
+end

data/lib/zzq/engine/socket_lifecycle.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "async/barrier"
+require "async/promise"
+
+module ZZQ
+  class Engine
+    # Owns the socket-level state: `:new → :open → :closing → :closed`.
+    #
+    # Adapted from NNQ::Engine::SocketLifecycle, minus the shared-IO-
+    # thread fallback (ZZQ is pure-Async).
+    class SocketLifecycle
+      class InvalidTransition < RuntimeError; end
+
+      STATES = %i[new open closing closed].freeze
+
+      TRANSITIONS = {
+        new:     %i[open closed].freeze,
+        open:    %i[closing closed].freeze,
+        closing: %i[closed].freeze,
+        closed:  [].freeze,
+      }.freeze
+
+
+      attr_reader :state
+      attr_reader :parent_task
+      attr_reader :peer_connected
+      attr_reader :all_peers_gone
+      attr_reader :barrier
+      attr_accessor :reconnect_enabled
+
+
+      def initialize
+        @state             = :new
+        @parent_task       = nil
+        @peer_connected    = Async::Promise.new
+        @all_peers_gone    = Async::Promise.new
+        @reconnect_enabled = true
+        @barrier           = nil
+      end
+
+
+      def open?    = @state == :open
+      def closing? = @state == :closing
+      def closed?  = @state == :closed
+      def alive?   = @state == :new || @state == :open
+
+
+      # Must be called from within an Async::Task. Raises
+      # NotInAsyncContext otherwise.
+      def capture_parent_task
+        return false if @parent_task
+        task = Async::Task.current? or raise NotInAsyncContext
+        @parent_task = task
+        @barrier = Async::Barrier.new(parent: @parent_task)
+        transition!(:open)
+        true
+      end
+
+
+      def start_closing!  = transition!(:closing)
+      def finish_closing! = transition!(:closed)
+
+
+      def resolve_all_peers_gone_if_empty(connections)
+        return unless @peer_connected.resolved? && connections.empty?
+        return if @all_peers_gone.resolved?
+        @all_peers_gone.resolve(true)
+      end
+
+
+      private def transition!(new_state)
+        allowed = TRANSITIONS[@state]
+        raise InvalidTransition, "#{@state} → #{new_state}" unless allowed&.include?(new_state)
+        @state = new_state
+      end
+    end
+  end
+end