zzq 0.1.0

data/lib/zzq/routing/packet_id_allocator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "async/condition"
+
+module ZZQ
+  module Routing
+    # u16 packet-id allocator with an optional receive-maximum cap.
+    # Thread-unsafe (designed to be owned by a single connection's
+    # writer fiber). Packet id 0 is reserved (MQTT-2.2.1-3); we wrap
+    # 1..65535.
+    #
+    # When the outstanding count reaches +receive_maximum+, +#acquire+
+    # blocks the caller fiber until a later +#release+ frees a slot.
+    class PacketIdAllocator
+      def initialize(receive_maximum: 65_535)
+        @receive_maximum = receive_maximum
+        @outstanding     = {}  # packet_id => true
+        @next            = 0
+        @free_cond       = Async::Condition.new
+      end
+
+
+      # Acquire a fresh packet id. Blocks the calling fiber if the
+      # receive-maximum quota is exhausted.
+      def acquire
+        while @outstanding.size >= @receive_maximum
+          @free_cond.wait
+        end
+        id = loop do
+          @next = (@next % 0xFFFF) + 1
+          break @next unless @outstanding.key?(@next)
+        end
+        @outstanding[id] = true
+        id
+      end
+
+
+      # Mark +id+ free. Wakes one waiter if any.
+      def release(id)
+        return false unless @outstanding.delete(id)
+        @free_cond.signal
+        true
+      end
+
+
+      def outstanding?(id)
+        @outstanding.key?(id)
+      end
+
+
+      def size = @outstanding.size
+    end
+  end
+end

data/lib/zzq/routing/qos_tracker.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "async/promise"
+
+module ZZQ
+  module Routing
+    # Outbound inflight tracking + inbound QoS 2 dedup for one
+    # session.
+    #
+    # Each side of a QoS 1/2 exchange owns one tracker. The publisher
+    # side records a {PendingPublish} per outbound packet id, awaiting
+    # a PUBACK (QoS 1) or completing via PUBREC/PUBREL/PUBCOMP
+    # (QoS 2). The subscriber side remembers which QoS 2 packet ids
+    # have been received-but-not-yet-released so duplicate PUBLISH
+    # packets with the same id are dropped.
+    class QosTracker
+      # One outbound publication awaiting ack.
+      #
+      # +stage+ is one of:
+      #   * :waiting_puback  — QoS 1, awaiting PUBACK
+      #   * :waiting_pubrec  — QoS 2, awaiting PUBREC
+      #   * :waiting_pubcomp — QoS 2, PUBREC received, PUBREL sent
+      PendingPublish = Struct.new(:packet_id, :packet, :stage, :promise, keyword_init: true)
+
+
+      def initialize
+        @outbound       = {}   # packet_id => PendingPublish
+        @inbound_qos2   = {}   # packet_id => true (received, awaiting PUBREL)
+      end
+
+
+      # Register an outbound QoS 1 publish. Returns the PendingPublish.
+      def track_qos1(packet_id, packet)
+        promise = Async::Promise.new
+        @outbound[packet_id] = PendingPublish.new(
+          packet_id: packet_id, packet: packet, stage: :waiting_puback,
+          promise: promise,
+        )
+      end
+
+
+      # Register an outbound QoS 2 publish (awaiting PUBREC).
+      def track_qos2(packet_id, packet)
+        promise = Async::Promise.new
+        @outbound[packet_id] = PendingPublish.new(
+          packet_id: packet_id, packet: packet, stage: :waiting_pubrec,
+          promise: promise,
+        )
+      end
+
+
+      # Called on inbound PUBACK. Returns the PendingPublish that
+      # completed, or nil if the id was unknown / stage mismatched.
+      def on_puback(packet_id)
+        pending = @outbound[packet_id]
+        return nil unless pending && pending.stage == :waiting_puback
+        @outbound.delete(packet_id)
+        pending.promise.resolve(:acked) unless pending.promise.resolved?
+        pending
+      end
+
+
+      # Called on inbound PUBREC. Transitions the entry to
+      # +:waiting_pubcomp+ and returns it so the caller can send
+      # PUBREL. Returns nil if unknown / stage mismatched.
+      def on_pubrec(packet_id)
+        pending = @outbound[packet_id]
+        return nil unless pending && pending.stage == :waiting_pubrec
+        pending.stage = :waiting_pubcomp
+        pending
+      end
+
+
+      # Called on inbound PUBCOMP. Completes a QoS 2 exchange.
+      def on_pubcomp(packet_id)
+        pending = @outbound[packet_id]
+        return nil unless pending && pending.stage == :waiting_pubcomp
+        @outbound.delete(packet_id)
+        pending.promise.resolve(:acked) unless pending.promise.resolved?
+        pending
+      end
+
+
+      # Inbound QoS 2 PUBLISH dedup. Returns true if this id is a new
+      # (non-duplicate) reception; false if it's a duplicate.
+      def on_qos2_publish(packet_id)
+        return false if @inbound_qos2.key?(packet_id)
+        @inbound_qos2[packet_id] = true
+        true
+      end
+
+
+      # Inbound PUBREL: peer tells us to release the held qos2 id.
+      def on_pubrel(packet_id)
+        @inbound_qos2.delete(packet_id)
+      end
+
+
+      # Snapshot of still-pending outbound publications, used on
+      # reconnect for retransmission.
+      def inflight_outbound = @outbound.values
+
+
+      def outbound_size = @outbound.size
+      def inbound_size  = @inbound_qos2.size
+    end
+  end
+end

data/lib/zzq/routing/retained_store.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "topic_match"
+
+module ZZQ
+  module Routing
+    # Exact-topic map of retained application messages.
+    #
+    # MQTT spec: the last PUBLISH with RETAIN=1 for a given topic is
+    # stored. A zero-length payload + RETAIN=1 deletes the retained
+    # message for that topic (MQTT-3.3.1-6).
+    #
+    # On SUBSCRIBE, the broker walks this store and delivers every
+    # retained message whose topic matches the new filter.
+    class RetainedStore
+      # +persistence+ is any {ZZQ::Persistence::Interface} subclass.
+      # Default is in-memory (no durability). On construction the
+      # in-process cache is warmed from the backend's load_retained.
+      def initialize(persistence: nil)
+        @store       = {}  # topic => ZZQ::Message
+        @persistence = persistence
+        @persistence&.load_retained { |msg| @store[msg.topic] = msg }
+      end
+
+
+      # Upsert or delete per RETAIN semantics. Returns the stored
+      # message (nil if the empty-payload rule deleted it).
+      def store(message)
+        if message.payload.empty?
+          @store.delete(message.topic)
+          @persistence&.delete_retained(message.topic)
+          nil
+        else
+          @store[message.topic] = message
+          @persistence&.save_retained(message)
+          message
+        end
+      end
+
+
+      def delete(topic)
+        @persistence&.delete_retained(topic)
+        @store.delete(topic)
+      end
+
+
+      # Enumerate retained messages matching +filter+.
+      def each_matching(filter)
+        return enum_for(:each_matching, filter) unless block_given?
+        @store.each_value do |msg|
+          yield msg if TopicMatch.match?(filter, msg.topic)
+        end
+      end
+
+
+      def size = @store.size
+      def empty? = @store.empty?
+
+
+      # Test helper: wipe everything.
+      def clear
+        @persistence&.clear_retained
+        @store.clear
+      end
+    end
+  end
+end

data/lib/zzq/routing/topic_match.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ZZQ
+  module Routing
+    # Tiny topic-filter matcher (MQTT §4.7). `+` matches exactly one
+    # topic level; `#` must be the last segment and matches zero or
+    # more remaining levels. Shared-subscription prefixes
+    # (`$share/<group>/<filter>`) are stripped before matching.
+    #
+    # Superseded by a proper trie in M7; this linear matcher is fine
+    # for MVP broker traffic.
+    module TopicMatch
+      module_function
+
+
+      # @param filter [String] topic filter with `+` / `#` wildcards.
+      # @param topic  [String] concrete topic name.
+      # @return [Boolean]
+      def match?(filter, topic)
+        filter = strip_share(filter)
+        return false if topic.start_with?("$") && filter.start_with?("+", "#")
+
+        f_parts = filter.split("/", -1)
+        t_parts = topic.split("/", -1)
+
+        i = 0
+        while i < f_parts.length
+          f = f_parts[i]
+          if f == "#"
+            # Must be last; matches zero or more remaining levels.
+            return i == f_parts.length - 1
+          end
+          return false if i >= t_parts.length
+          return false unless f == "+" || f == t_parts[i]
+          i += 1
+        end
+        i == t_parts.length
+      end
+
+
+      def strip_share(filter)
+        return filter unless filter.start_with?("$share/")
+        # $share/<group>/<filter> — drop first two segments.
+        parts = filter.split("/", 3)
+        parts.length == 3 ? parts[2] : filter
+      end
+    end
+  end
+end

data/lib/zzq/routing/topic_trie.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "topic_match"
+
+module ZZQ
+  module Routing
+    # Per-level topic-filter trie. Each node holds literal children,
+    # one +wildcard ("+") child, and one hash-wildcard ("#") child.
+    # Subscriptions are stored at the terminal node of their filter.
+    #
+    # Matches are collected by walking a topic down the trie, traversing
+    # literal + '+' branches in parallel and collecting '#' subtree
+    # entries at every step. Honours the $SYS-vs-bare-wildcard rule
+    # (MQTT-4.7.2-1): filters starting with `+` or `#` at the root do
+    # not match topics starting with `$SYS`.
+    #
+    # Shared-subscription filters ("$share/<group>/<filter>") are
+    # stored with their group stripped off but tagged with the group
+    # name on each SubscriberEntry; fan-out chooses exactly one entry
+    # per group (MVP: round-robin).
+    #
+    # Not thread-safe — a broker-owned trie is mutated from the broker
+    # fibers only.
+    class TopicTrie
+      SubscriberEntry = Struct.new(:session, :entry, :share_group, keyword_init: true) do
+        # Forward-compat shorthand for fan-out.
+        def filter = entry[:filter]
+      end
+
+
+      class Node
+        attr_accessor :plus_child, :hash_child
+        attr_reader :children, :entries
+
+
+        def initialize
+          @children   = {}
+          @plus_child = nil
+          @hash_child = nil
+          @entries    = []
+        end
+
+
+        def empty?
+          @children.empty? && @plus_child.nil? && @hash_child.nil? && @entries.empty?
+        end
+      end
+
+
+      def initialize
+        @root = Node.new
+        # Round-robin cursor for shared groups: group_key => index.
+        @share_cursor = Hash.new(0)
+      end
+
+
+      # Insert a subscription. +filter+ may be a plain MQTT filter
+      # ("a/+/c", "#", "$SYS/b/+") or a shared-subscription filter
+      # ("$share/group/a/+/c").
+      def add(filter, session, entry)
+        real_filter, group = strip_share(filter)
+        node, _segs = walk_or_create(real_filter)
+        node.entries << SubscriberEntry.new(session: session, entry: entry, share_group: group)
+      end
+
+
+      # Remove the entry for (session, filter). Returns true if found.
+      def remove(filter, session)
+        real_filter, _group = strip_share(filter)
+        segs = real_filter.split("/", -1)
+        path = [@root]
+        segs.each do |seg|
+          node = path.last
+          nxt =
+            case seg
+            when "+" then node.plus_child
+            when "#" then node.hash_child
+            else node.children[seg]
+            end
+          return false unless nxt
+          path << nxt
+        end
+        leaf = path.last
+        before = leaf.entries.size
+        leaf.entries.reject! { |e| e.session.equal?(session) && e.entry[:filter] == filter }
+        return false if leaf.entries.size == before
+        prune(path, segs)
+        true
+      end
+
+
+      # Drop every entry belonging to +session+, pruning empty nodes.
+      def remove_session(session)
+        walk_prune(@root, []) { |e| e.session.equal?(session) }
+      end
+
+
+      # Return the matching subscriber entries for +topic+. One entry
+      # per (session, filter); shared-group collapse is performed here
+      # so fan-out sees exactly one delivery per $share group.
+      def match(topic)
+        segs = topic.split("/", -1)
+        collected = []
+        traverse(@root, segs, 0, topic.start_with?("$"), collected)
+        collapse_shared(collected)
+      end
+
+
+      def empty? = @root.empty?
+
+
+      private
+
+
+      SHARE_PREFIX = "$share/"
+
+
+      def strip_share(filter)
+        return [filter, nil] unless filter.start_with?(SHARE_PREFIX)
+        rest = filter[SHARE_PREFIX.length..]
+        slash = rest.index("/") or raise ArgumentError, "malformed $share filter: #{filter}"
+        group = rest[0, slash]
+        real  = rest[(slash + 1)..]
+        raise ArgumentError, "$share filter has empty group: #{filter}" if group.empty?
+        raise ArgumentError, "$share filter has empty inner filter: #{filter}" if real.empty?
+        [real, group]
+      end
+
+
+      def walk_or_create(filter)
+        segs = filter.split("/", -1)
+        node = @root
+        segs.each do |seg|
+          node =
+            case seg
+            when "+"
+              node.plus_child ||= Node.new
+            when "#"
+              node.hash_child ||= Node.new
+            else
+              node.children[seg] ||= Node.new
+            end
+        end
+        [node, segs]
+      end
+
+
+      def prune(path, segs)
+        # path[i] is the node reached after segs[0..i-1]; path[0] = root.
+        (segs.length - 1).downto(0) do |i|
+          parent = path[i]
+          child  = path[i + 1]
+          next unless child.empty?
+          seg = segs[i]
+          case seg
+          when "+" then parent.plus_child = nil
+          when "#" then parent.hash_child = nil
+          else parent.children.delete(seg)
+          end
+        end
+      end
+
+
+      def walk_prune(node, path_segs, &block)
+        node.entries.reject!(&block)
+        node.children.each do |seg, child|
+          walk_prune(child, path_segs + [seg], &block)
+          node.children.delete(seg) if child.empty?
+        end
+        if node.plus_child
+          walk_prune(node.plus_child, path_segs + ["+"], &block)
+          node.plus_child = nil if node.plus_child.empty?
+        end
+        if node.hash_child
+          walk_prune(node.hash_child, path_segs + ["#"], &block)
+          node.hash_child = nil if node.hash_child.empty?
+        end
+      end
+
+
+      # Walk all trie branches compatible with segs[i..]. Collect
+      # entries at every node that marks a terminal filter. Rules:
+      #   * +#+ at a node matches the rest of the topic (including zero
+      #     more segments).
+      #   * MQTT-4.7.2-1: filters starting with +/# at the root don't
+      #     match topics starting with $.
+      def traverse(node, segs, i, sys_topic, out)
+        at_root = i.zero?
+
+        if node.hash_child && !(at_root && sys_topic)
+          out.concat(node.hash_child.entries)
+        end
+
+        if i == segs.length
+          out.concat(node.entries)
+          return
+        end
+
+        seg = segs[i]
+
+        if (lit = node.children[seg])
+          traverse(lit, segs, i + 1, sys_topic, out)
+        end
+
+        if (plus = node.plus_child) && !(at_root && sys_topic)
+          traverse(plus, segs, i + 1, sys_topic, out)
+        end
+      end
+
+
+      # For shared subscriptions: group matches by (group, filter),
+      # pick one member round-robin; unshared entries pass through.
+      def collapse_shared(entries)
+        return entries if entries.all? { |e| e.share_group.nil? }
+        out = []
+        grouped = Hash.new { |h, k| h[k] = [] }
+        entries.each do |e|
+          if e.share_group
+            grouped[[e.share_group, e.entry[:filter]]] << e
+          else
+            out << e
+          end
+        end
+        grouped.each do |key, members|
+          idx = (@share_cursor[key] += 1) % members.size
+          out << members[idx]
+        end
+        out
+      end
+    end
+  end
+end

data/lib/zzq/socket.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require_relative "error"
+require_relative "monitor_event"
+require_relative "options"
+require_relative "engine"
+
+module ZZQ
+  # Abstract base class for {ZZQ::Client} and {ZZQ::Broker}. Owns the
+  # Engine and exposes the infrastructure API (bind / connect / close /
+  # monitor / peer_connected / all_peers_gone). The role-specific API
+  # (subscribe / publish / ingest) lives on the subclasses.
+  #
+  # ZZQ is pure-Async: every public method that performs I/O must run
+  # inside an Async::Task. Either wrap calls in `Async do … end`, or
+  # use the block form of #connect / #bind which enters `Async{}` for
+  # you and closes the socket on block exit.
+  class Socket
+    attr_reader :options
+
+
+    def self.bind(endpoint, **opts, &block)
+      sock = new(**opts)
+      if block
+        sock.bind(endpoint, &block)
+      else
+        sock.bind(endpoint)
+        sock
+      end
+    end
+
+
+    def self.connect(endpoint, **opts, &block)
+      sock = new(**opts)
+      if block
+        sock.connect(endpoint, &block)
+      else
+        sock.connect(endpoint)
+        sock
+      end
+    end
+
+
+    def initialize(**opts)
+      @options = Options.new(**opts)
+      @engine  = Engine.new(options: @options) { |engine| build_routing(engine) }
+    end
+
+
+    # Binds to +endpoint+. If a block is given, wraps the call in
+    # `Async do … end` (if not already inside one), yields the owning
+    # Async::Task to the block, and closes the socket on block exit.
+    def bind(endpoint, **opts, &block)
+      block ? run_in_async(endpoint, :bind, opts, &block) : run_sync(:bind, endpoint, **opts)
+    end
+
+
+    # Connects to +endpoint+. Block form yields the owning Async::Task
+    # and auto-closes on block exit, same as {#bind}.
+    def connect(endpoint, **opts, &block)
+      block ? run_in_async(endpoint, :connect, opts, &block) : run_sync(:connect, endpoint, **opts)
+    end
+
+
+    def close
+      if Async::Task.current?
+        @engine.close
+      else
+        Async { @engine.close }.wait
+      end
+      nil
+    end
+
+
+    def last_endpoint        = @engine.last_endpoint
+    def connection_count     = @engine.connections.size
+    def peer_connected       = @engine.peer_connected
+    def all_peers_gone       = @engine.all_peers_gone
+
+
+    # Yields lifecycle events for this socket until it's closed. Must
+    # be called from within an Async::Task.
+    def monitor(&block)
+      raise NotInAsyncContext unless Async::Task.current?
+      queue = Async::Queue.new
+      @engine.monitor_queue = queue
+      @engine.spawn_task(annotation: "zzq monitor") do
+        while (event = queue.dequeue)
+          block.call(event)
+        end
+      rescue Async::Stop
+      ensure
+        @engine.monitor_queue = nil
+        block.call(MonitorEvent.new(type: :monitor_stopped))
+      end
+    end
+
+
+    # Coerces +body+ to a frozen BINARY String. MQTT payloads are
+    # opaque bytes — uniform frozen+BINARY contract mirrors NNQ.
+    def coerce_binary(body)
+      body = body.to_str unless body.is_a?(String)
+      body.force_encoding(Encoding::BINARY) unless body.frozen? || body.encoding == Encoding::BINARY
+      body.freeze
+    end
+
+
+    private
+
+
+    def run_sync(op, endpoint, **opts)
+      raise NotInAsyncContext unless Async::Task.current?
+      @engine.capture_parent_task
+      @engine.public_send(op, endpoint, **opts)
+    end
+
+
+    def run_in_async(endpoint, op, opts, &block)
+      if (task = Async::Task.current?)
+        run_sync(op, endpoint, **opts)
+        begin
+          block.call(task)
+        ensure
+          close
+        end
+      else
+        Async do |task|
+          run_sync(op, endpoint, **opts)
+          begin
+            block.call(task)
+          ensure
+            close
+          end
+        end.wait
+      end
+    end
+
+
+    # Subclass hook — return a role-specific routing strategy instance.
+    def build_routing(_engine)
+      raise NotImplementedError, "#{self.class} must implement #build_routing"
+    end
+  end
+end