zzq 0.1.0 → 0.2.0

data/lib/zzq/routing/topic_trie.rb

@@ -1,232 +0,0 @@
-# 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

@@ -1,146 +0,0 @@
-# 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

data/lib/zzq/subscription.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require "async/queue"
-require "async/limited_queue"
-
-module ZZQ
-  # Handle returned by {Client#subscribe} and {Broker#subscribe}. A
-  # thin wrapper around an +Async::LimitedQueue+ that also owns the
-  # UNSUBSCRIBE lifecycle.
-  #
-  # Callers consume with {#pop} or {#each}; {#close} sends UNSUBSCRIBE
-  # and wakes any blocked consumer with +nil+.
-  #
-  # Created internally — users should never call +.new+ directly.
-  class Subscription
-    # @return [Array<String>] topic filters this subscription matches.
-    attr_reader :filters
-
-    # @return [Integer] subscription identifier (v5) or nil (v3).
-    attr_reader :subscription_id
-
-
-    def initialize(filters:, hwm:, subscription_id: nil, on_close: nil)
-      @filters         = Array(filters).freeze
-      @subscription_id = subscription_id
-      @queue           = Async::LimitedQueue.new(hwm)
-      @on_close        = on_close
-      @closed          = false
-    end
-
-
-    # Blocks the fiber until a message arrives. Returns +nil+ when
-    # the subscription is closed.
-    def pop
-      return nil if @closed && @queue.empty?
-      @queue.dequeue
-    end
-
-
-    # Yields each message until the subscription is closed.
-    def each
-      return enum_for(:each) unless block_given?
-      while (msg = pop)
-        yield msg
-      end
-    end
-
-
-    # Sends UNSUBSCRIBE and wakes the consumer. Idempotent.
-    def close
-      return if @closed
-      @closed = true
-      @on_close&.call(self)
-      @queue.enqueue(nil)
-    end
-
-
-    def closed?
-      @closed
-    end
-
-
-    # Internal: deliver a message to the subscriber's queue. Blocks
-    # the caller if the queue is at high-water-mark.
-    def deliver(message)
-      return if @closed
-      @queue.enqueue(message)
-    end
-  end
-end

data/lib/zzq/transport/ipc.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-require "socket"
-require "io/stream"
-require_relative "../engine"
-
-module ZZQ
-  module Transport
-    # IPC transport using Unix domain sockets.
-    #
-    # Endpoint forms:
-    #   * `ipc:///var/run/zzq.sock` — filesystem path (portable).
-    #   * `ipc://@zzq-local`        — Linux abstract namespace (the
-    #     leading `@` becomes a NUL byte in sockaddr.sun_path).
-    module IPC
-      Engine.transports["ipc"] = self
-
-
-      class << self
-        def bind(endpoint, engine, **)
-          path      = parse_path(endpoint)
-          sock_path = to_socket_path(path)
-
-          File.delete(sock_path) if !abstract?(path) && File.exist?(sock_path)
-
-          server = UNIXServer.new(sock_path)
-          Listener.new(endpoint, server, path, engine)
-        end
-
-
-        def connect(endpoint, engine, **)
-          path      = parse_path(endpoint)
-          sock_path = to_socket_path(path)
-          sock      = UNIXSocket.new(sock_path)
-          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
-        end
-
-
-        def parse_path(endpoint)
-          endpoint.sub(%r{\Aipc://}, "")
-        end
-
-
-        # Linux abstract-namespace Unix sockets: leading `@` becomes a
-        # NUL byte in sun_path. Only supported on Linux.
-        def to_socket_path(path)
-          abstract?(path) ? "\0#{path[1..]}" : path
-        end
-
-
-        def abstract?(path)
-          path.start_with?("@")
-        end
-      end
-
-
-      class Listener
-        attr_reader :endpoint
-
-
-        def initialize(endpoint, server, path, engine)
-          @endpoint = endpoint
-          @server   = server
-          @path     = path
-          @engine   = engine
-          @task     = nil
-        end
-
-
-        def start_accept_loop(parent_task, &on_accepted)
-          @task = parent_task.async(annotation: "zzq ipc accept #{@endpoint}") do
-            loop do
-              client = @server.accept
-              on_accepted.call(IO::Stream::Buffered.wrap(client))
-            rescue Async::Stop, IOError
-              break
-            end
-          ensure
-            @server.close rescue nil
-          end
-        end
-
-
-        def stop
-          @task&.stop
-          @server.close rescue nil
-          File.delete(@path) rescue nil unless IPC.abstract?(@path)
-        end
-      end
-    end
-  end
-end

data/lib/zzq/transport/mqtt.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require "socket"
-require "uri"
-require "io/stream"
-require_relative "../engine"
-
-module ZZQ
-  module Transport
-    # Plain MQTT-over-TCP transport. Endpoint scheme: `mqtt://host:port`
-    # (default port 1883). One server per bind, blocking accept inside
-    # an Async fiber.
-    module MQTT
-      Engine.transports["mqtt"] = self
-
-
-      class << self
-        def bind(endpoint, engine, **)
-          host, port = parse_endpoint(endpoint)
-          host       = "0.0.0.0" if host == "*"
-          server     = TCPServer.new(host, port)
-          actual     = server.local_address.ip_port
-          host_part  = host.include?(":") ? "[#{host}]" : host
-          Listener.new("mqtt://#{host_part}:#{actual}", server, actual, engine)
-        end
-
-
-        def connect(endpoint, engine, **)
-          host, port = parse_endpoint(endpoint)
-          sock = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
-          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
-        end
-
-
-        def connect_timeout(options)
-          ri = options.reconnect_interval
-          ri = ri.end if ri.is_a?(Range)
-          [ri, 0.5].max
-        end
-
-
-        def parse_endpoint(endpoint)
-          uri = URI.parse(endpoint.sub("mqtt://", "tcp://"))
-          [uri.hostname, uri.port]
-        end
-      end
-
-
-      class Listener
-        attr_reader :endpoint, :port
-
-
-        def initialize(endpoint, server, port, engine)
-          @endpoint = endpoint
-          @server   = server
-          @port     = port
-          @engine   = engine
-          @task     = nil
-        end
-
-
-        def start_accept_loop(parent_task, &on_accepted)
-          @task = parent_task.async(annotation: "zzq mqtt accept #{@endpoint}") do
-            loop do
-              client = @server.accept
-              on_accepted.call(IO::Stream::Buffered.wrap(client))
-            rescue Async::Stop, IOError
-              break
-            end
-          ensure
-            @server.close rescue nil
-          end
-        end
-
-
-        def stop
-          @task&.stop
-          @server.close rescue nil
-        end
-      end
-    end
-  end
-end