zzq 0.1.0

data/lib/zzq/engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/clock"
+require "set"
+require_relative "error"
+require_relative "engine/socket_lifecycle"
+require_relative "engine/connection_lifecycle"
+
+module ZZQ
+  # Per-socket orchestrator. Owns listeners, the connection map, the
+  # transport registry, and the socket-level state machine. Adapted
+  # from NNQ::Engine minus reactor / inproc / SP-handshake concerns.
+  class Engine
+    # Scheme → transport module registry. Populated by each transport
+    # file on require.
+    @transports = {}
+
+
+    class << self
+      attr_reader :transports
+    end
+
+
+    attr_reader :options
+    attr_reader :routing
+    attr_reader :connections  # Hash{Protocol::MQTT::Connection => ConnectionLifecycle}
+    attr_reader :lifecycle
+    attr_reader :last_endpoint
+    attr_reader :dialed
+    attr_accessor :monitor_queue
+
+
+    # @yieldparam engine [Engine] build_routing hook; returns the
+    #   role-specific routing strategy.
+    def initialize(options:)
+      @options       = options
+      @connections   = {}
+      @listeners     = []
+      @lifecycle     = SocketLifecycle.new
+      @last_endpoint = nil
+      @monitor_queue = nil
+      @dialed        = Set.new
+      @dial_opts     = {}
+      @routing       = yield(self)
+    end
+
+
+    def emit_monitor_event(type, endpoint: nil, detail: nil)
+      return unless @monitor_queue
+      @monitor_queue.enqueue(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
+    rescue Async::Stop
+    end
+
+
+    def parent_task   = @lifecycle.parent_task
+    def barrier       = @lifecycle.barrier
+    def closed?       = @lifecycle.closed?
+    def peer_connected = @lifecycle.peer_connected
+    def all_peers_gone = @lifecycle.all_peers_gone
+
+
+    def resolve_all_peers_gone_if_empty
+      @lifecycle.resolve_all_peers_gone_if_empty(@connections)
+    end
+
+
+    # Must be called from inside an Async::Task.
+    def capture_parent_task
+      @lifecycle.capture_parent_task
+    end
+
+
+    # Bind (listener) — role-agnostic. The routing layer (on accept)
+    # drives the MQTT handshake.
+    def bind(endpoint, **opts)
+      transport = transport_for(endpoint)
+      listener  = transport.bind(endpoint, self, **opts)
+      listener.start_accept_loop(@lifecycle.barrier) do |io|
+        handle_accepted(io, endpoint: endpoint)
+      end
+      @listeners << listener
+      @last_endpoint = listener.endpoint
+      emit_monitor_event(:listening, endpoint: @last_endpoint)
+    end
+
+
+    # Connect (dialer).
+    def connect(endpoint, **opts)
+      @dialed << endpoint
+      @dial_opts[endpoint] = opts unless opts.empty?
+      @last_endpoint = endpoint
+      transport_for(endpoint).connect(endpoint, self, **opts)
+    end
+
+
+    def dial_opts_for(endpoint)
+      @dial_opts[endpoint] || {}
+    end
+
+
+    def maybe_reconnect(endpoint)
+      # Reconnect loop not wired up yet (M4 job).
+    end
+
+
+    def transport_for(endpoint)
+      scheme = endpoint[/\A([a-z+]+):\/\//i, 1] or raise Error, "no scheme: #{endpoint}"
+      Engine.transports[scheme] or raise Error, "unsupported transport: #{scheme}"
+    end
+
+
+    # Called by transports for each accepted connection. Hands off to
+    # routing so the broker can read CONNECT / write CONNACK.
+    def handle_accepted(io, endpoint:)
+      lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint)
+      mqtt = lifecycle.begin_handshake!(io)
+      @routing.handle_accepted(mqtt, lifecycle) if @routing.respond_to?(:handle_accepted)
+    rescue => e
+      lifecycle.handshake_failed!(error: e)
+      raise unless e.is_a?(ConnectionRejected) || CONNECTION_LOST.any? { |c| e.is_a?(c) }
+    end
+
+
+    # Called by transports for each dialed connection. Hands off to
+    # routing so the client can write CONNECT / read CONNACK.
+    def handle_connected(io, endpoint:)
+      lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint)
+      mqtt = lifecycle.begin_handshake!(io)
+      @routing.handle_connected(mqtt, lifecycle) if @routing.respond_to?(:handle_connected)
+    rescue => e
+      lifecycle.handshake_failed!(error: e)
+      raise unless e.is_a?(ConnectionRejected) || CONNECTION_LOST.any? { |c| e.is_a?(c) }
+    end
+
+
+    def spawn_task(annotation:, parent: @lifecycle.barrier, &block)
+      parent.async(annotation: annotation, &block)
+    end
+
+
+    def close
+      return unless @lifecycle.alive?
+
+      @lifecycle.start_closing!
+      @listeners.each(&:stop)
+      @routing.close if @routing.respond_to?(:close)
+      @connections.values.each(&:close!)
+
+      emit_monitor_event(:closed)
+      @monitor_queue&.enqueue(nil)
+
+      @lifecycle.barrier&.stop
+      @lifecycle.finish_closing!
+      @lifecycle.peer_connected.resolve(nil) unless @lifecycle.peer_connected.resolved?
+    end
+
+
+    def handle_connection_lost(conn)
+      @connections[conn]&.lost!
+    end
+  end
+end

data/lib/zzq/error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ZZQ
+  class Error < StandardError; end
+
+  # Raised when sending on or interacting with a closed socket.
+  class ClosedError < Error; end
+
+  # Raised when the routing layer refuses to accept a peer (e.g. a
+  # duplicate client id collision on the broker).
+  class ConnectionRejected < Error; end
+
+  # Raised when a socket method is called outside an Async::Task. ZZQ
+  # is fiber-first: wrap calls in `Async do ... end` or use the block
+  # form of #connect / #bind.
+  class NotInAsyncContext < Error
+    def initialize(msg = "ZZQ socket methods must run inside an Async task. " \
+                         "Wrap in `Async do ... end`, or use the block form " \
+                         "of #connect/#bind.")
+      super
+    end
+  end
+
+  # Server responded with a non-success CONNACK.
+  class ConnectionRefused < Error
+    attr_reader :reason_code
+
+    def initialize(reason_code, message = nil)
+      @reason_code = reason_code
+      super(message || "broker refused connect: reason=0x#{reason_code.to_s(16)}")
+    end
+  end
+
+  # Authentication failed.
+  class AuthFailed < Error; end
+
+  # Network errors that indicate the connection is gone.
+  CONNECTION_LOST = [
+    Errno::ECONNRESET, Errno::EPIPE, Errno::ENOTCONN, Errno::ECONNABORTED,
+    Errno::EBADF, EOFError, IOError
+  ].freeze
+end

data/lib/zzq/message.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "protocol/mqtt"
+
+module ZZQ
+  # One MQTT application message as delivered to a subscriber or
+  # accepted by {Client#publish} / {Broker#ingest}.
+  #
+  # `Message` is independent of any particular connection: it carries
+  # every wire-level field that a PUBLISH packet does, so it can be
+  # shipped across non-MQTT transports (OMQ, NNQ, a file, a queue) via
+  # {#to_wire} / {.from_wire} and re-injected at the other end.
+  #
+  # `#ack!` is only meaningful for QoS 1/2 messages received with
+  # `auto_ack: false` — it sends the appropriate PUBACK/PUBCOMP.
+  class Message
+    attr_reader :topic, :payload, :qos, :retain, :dup, :packet_id, :properties
+
+
+    def initialize(topic:, payload:, qos: 0, retain: false, dup: false,
+                   packet_id: nil, properties: {}, on_ack: nil)
+      @topic      = topic
+      @payload    = payload.b.freeze
+      @qos        = qos
+      @retain     = retain
+      @dup        = dup
+      @packet_id  = packet_id
+      @properties = properties
+      @on_ack     = on_ack
+      @acked      = false
+    end
+
+
+    def ack!
+      return if @qos.zero? || @acked
+      @acked = true
+      @on_ack&.call(self)
+    end
+
+
+    def acked?
+      @acked
+    end
+
+
+    # Encode this message as a self-describing byte string using the
+    # PUBLISH packet codec. The output can be cross-shipped over a
+    # non-MQTT transport and reconstructed via {.from_wire}. v5 wire
+    # format is used so the full property block round-trips.
+    def to_wire
+      packet = to_publish
+      packet.encode(version: 5)
+    end
+
+
+    # Inverse of {#to_wire}. Raises +Protocol::MQTT::MalformedPacket+
+    # if the bytes don't decode as a PUBLISH packet.
+    def self.from_wire(bytes)
+      pkt, consumed = Protocol::MQTT::Packet.decode(bytes, version: 5)
+      raise Protocol::MQTT::MalformedPacket, "expected PUBLISH, got #{pkt.class}" unless pkt.is_a?(Protocol::MQTT::Packet::Publish)
+      raise Protocol::MQTT::MalformedPacket, "trailing bytes after PUBLISH" if consumed != bytes.bytesize
+      from_publish(pkt)
+    end
+
+
+    # Build a PUBLISH packet that represents this message. Used both
+    # internally (for over-the-wire transmission) and by {#to_wire}.
+    def to_publish
+      Protocol::MQTT::Packet::Publish.new(
+        topic:      @topic,
+        payload:    @payload,
+        qos:        @qos,
+        retain:     @retain,
+        dup:        @dup,
+        packet_id:  @packet_id,
+        properties: @properties,
+      )
+    end
+
+
+    # Build a Message from a decoded PUBLISH packet.
+    def self.from_publish(pkt, on_ack: nil)
+      new(
+        topic:      pkt.topic,
+        payload:    pkt.payload,
+        qos:        pkt.qos,
+        retain:     pkt.retain,
+        dup:        pkt.dup,
+        packet_id:  pkt.packet_id,
+        properties: pkt.properties,
+        on_ack:     on_ack,
+      )
+    end
+
+
+    def ==(other)
+      other.is_a?(Message) &&
+        other.topic == @topic &&
+        other.payload == @payload &&
+        other.qos == @qos &&
+        other.retain == @retain &&
+        other.dup == @dup &&
+        other.packet_id == @packet_id &&
+        other.properties == @properties
+    end
+    alias eql? ==
+
+
+    def hash
+      [self.class, @topic, @payload, @qos, @retain, @dup, @packet_id, @properties].hash
+    end
+  end
+end

data/lib/zzq/monitor_event.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ZZQ
+  # A single event emitted by a Socket's #monitor task. Event types
+  # cover both infrastructure lifecycle (:listening, :connected,
+  # :disconnected, :closed) and MQTT semantics (:session_resumed,
+  # :session_expired, :retained_updated, :publish_delivered,
+  # :will_published).
+  MonitorEvent = Data.define(:type, :endpoint, :detail) do
+    def initialize(type:, endpoint: nil, detail: nil)
+      super
+    end
+  end
+end

data/lib/zzq/options.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ZZQ
+  # Per-socket configuration. Holds both infrastructure options (linger,
+  # HWMs, reconnect) lifted from NNQ::Options, and MQTT-specific ones
+  # (keepalive, session_expiry, receive_maximum, etc.) that shape the
+  # wire behaviour.
+  #
+  # Clients and brokers share this class; role-irrelevant fields are
+  # simply ignored by the other side.
+  class Options
+    DEFAULT_HWM = 1000
+
+    # --- infrastructure -------------------------------------------------
+    attr_accessor :linger
+    attr_accessor :read_timeout
+    attr_accessor :write_timeout
+    attr_accessor :reconnect_interval
+    attr_accessor :send_hwm
+    attr_accessor :recv_hwm
+
+    # --- MQTT wire ------------------------------------------------------
+    # 3 = MQTT v3.1.1, 5 = MQTT v5.0
+    attr_accessor :version
+
+    # Client identifier. Client-only; required unless empty-id + v5 is
+    # used (server assigns it).
+    attr_accessor :client_id
+
+    # Clean Start (v5) / Clean Session (v3.1.1). When true, any prior
+    # session state for this client id is discarded on CONNECT.
+    attr_accessor :clean_start
+
+    # Keep-alive interval in seconds. The broker will close the
+    # connection after 1.5× this period with no traffic. 0 disables.
+    attr_accessor :keep_alive
+
+    # Session expiry interval (v5 only), in seconds. Only meaningful
+    # when clean_start is false.
+    attr_accessor :session_expiry_interval
+
+    # Maximum outstanding unacknowledged QoS 1/2 messages (v5).
+    attr_accessor :receive_maximum
+
+    # Maximum packet size this peer is willing to accept (v5). nil =
+    # unlimited.
+    attr_accessor :max_packet_size
+
+    # Topic Alias Maximum we advertise (v5).
+    attr_accessor :topic_alias_maximum
+
+    # MQTT username / password (both optional).
+    attr_accessor :username
+    attr_accessor :password
+
+    # Last Will and Testament, client-side. Nil or a Hash of
+    # { topic:, payload:, qos:, retain:, properties: }.
+    attr_accessor :will
+
+    # Broker-side persistence backend. Nil = ephemeral (no durability).
+    # Pass an instance of a {ZZQ::Persistence::Interface} subclass
+    # (e.g. {ZZQ::Persistence::PStore}) to survive process restarts.
+    attr_accessor :persistence
+
+
+    def initialize(
+      linger: Float::INFINITY, send_hwm: DEFAULT_HWM, recv_hwm: DEFAULT_HWM,
+      version: 5, client_id: nil, clean_start: true, keep_alive: 60,
+      session_expiry_interval: 0, receive_maximum: 65_535,
+      max_packet_size: nil, topic_alias_maximum: 0,
+      username: nil, password: nil, will: nil,
+      persistence: nil
+    )
+      @linger                  = linger
+      @read_timeout            = nil
+      @write_timeout           = nil
+      @reconnect_interval      = 0.1
+      @send_hwm                = send_hwm
+      @recv_hwm                = recv_hwm
+      @version                 = version
+      @client_id               = client_id
+      @clean_start             = clean_start
+      @keep_alive              = keep_alive
+      @session_expiry_interval = session_expiry_interval
+      @receive_maximum         = receive_maximum
+      @max_packet_size         = max_packet_size
+      @topic_alias_maximum     = topic_alias_maximum
+      @username                = username
+      @password                = password
+      @will                    = will
+      @persistence             = persistence
+    end
+  end
+end

data/lib/zzq/persistence/interface.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ZZQ
+  module Persistence
+    # Abstract base for persistence backends.
+    #
+    # Concrete backends (Memory, PStore, future Redis/SQLite) implement
+    # the methods below. Broker state calls through this interface; the
+    # in-memory runtime state in {Routing::Broker} is the source of
+    # truth during a session, and the backend is the durable record
+    # that survives restarts.
+    #
+    # v1 scope: retained messages only. Session persistence will land
+    # alongside session-expiry (M8's deferred piece).
+    class Interface
+      # Yields each persisted {ZZQ::Message} (retained). Called once at
+      # broker start to warm the in-memory RetainedStore.
+      def load_retained
+        raise NotImplementedError
+      end
+
+
+      # Persist a retained message under +message.topic+. Replaces any
+      # existing retained message for that topic.
+      def save_retained(_message)
+        raise NotImplementedError
+      end
+
+
+      # Remove the retained message for +topic+ (zero-length-payload
+      # rule, MQTT-3.3.1-6).
+      def delete_retained(_topic)
+        raise NotImplementedError
+      end
+
+
+      # Wipe all retained state. Mostly for tests and operator tooling.
+      def clear_retained
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/zzq/persistence/memory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "interface"
+
+module ZZQ
+  module Persistence
+    # In-process persistence backend. Default for ephemeral brokers and
+    # tests. State is lost on process exit.
+    class Memory < Interface
+      def initialize
+        super()
+        @retained = {}  # topic => ZZQ::Message
+      end
+
+
+      def load_retained
+        return enum_for(:load_retained) unless block_given?
+        @retained.each_value { |msg| yield msg }
+      end
+
+
+      def save_retained(message)
+        @retained[message.topic] = message
+      end
+
+
+      def delete_retained(topic)
+        @retained.delete(topic)
+      end
+
+
+      def clear_retained
+        @retained.clear
+      end
+    end
+  end
+end

data/lib/zzq/persistence/pstore.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pstore"
+require "protocol/mqtt"
+require_relative "interface"
+require_relative "../message"
+
+module ZZQ
+  module Persistence
+    # PStore-backed durable persistence. Single-process deployments
+    # only — PStore uses file locking but doesn't coordinate well
+    # across processes.
+    #
+    # `ultra_safe` is enabled by default: each commit does a full fsync
+    # of the data file AND its parent directory, surviving power loss
+    # (not just clean crashes). Fits a broker where "I told the
+    # publisher QoS 1 ack" must survive a kernel panic.
+    #
+    # Messages are serialized via {ZZQ::Message#to_wire}, so the
+    # on-disk format is the PUBLISH wire encoding — self-describing
+    # and version-tagged.
+    class PStore < Interface
+      DEFAULT_FILENAME = "retained.pstore"
+
+
+      def initialize(data_dir:, filename: DEFAULT_FILENAME, ultra_safe: true)
+        super()
+        FileUtils.mkdir_p(data_dir)
+        @store = ::PStore.new(File.join(data_dir, filename))
+        @store.ultra_safe = ultra_safe
+      end
+
+
+      def load_retained
+        return enum_for(:load_retained) unless block_given?
+        @store.transaction(true) do
+          (@store[:retained] || {}).each_value do |bytes|
+            yield ZZQ::Message.from_wire(bytes)
+          end
+        end
+      end
+
+
+      def save_retained(message)
+        bytes = message.to_wire
+        @store.transaction do
+          @store[:retained] ||= {}
+          @store[:retained][message.topic] = bytes
+        end
+      end
+
+
+      def delete_retained(topic)
+        @store.transaction do
+          (@store[:retained] || {}).delete(topic)
+        end
+      end
+
+
+      def clear_retained
+        @store.transaction { @store[:retained] = {} }
+      end
+    end
+  end
+end