omq 0.1.0

data/lib/omq/zmtp/routing/fan_out.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # Mixin for routing strategies that fan-out to subscribers.
+      #
+      # Manages per-connection subscription sets, subscription command
+      # listeners, and a send pump that delivers to all matching peers.
+      #
+      # Including classes must call `init_fan_out(engine)` from
+      # their #initialize.
+      #
+      module FanOut
+        private
+
+        def init_fan_out(engine)
+          @connections        = []
+          @subscriptions      = {} # connection => Set of prefixes
+          @send_queue         = Async::LimitedQueue.new(engine.options.send_hwm)
+          @send_pump_started  = false
+        end
+
+        # @return [Boolean] whether the connection is subscribed to the topic
+        #
+        def subscribed?(conn, topic)
+          subs = @subscriptions[conn]
+          return false unless subs
+          subs.any? { |prefix| topic.b.start_with?(prefix.b) }
+        end
+
+        # Called when a subscription command is received from a peer.
+        # Override in subclasses to expose subscriptions to the
+        # application (e.g. XPUB enqueues to recv_queue).
+        #
+        # @param conn [Connection]
+        # @param prefix [String]
+        #
+        def on_subscribe(conn, prefix)
+          @subscriptions[conn] << prefix
+        end
+
+        # Called when a cancel command is received from a peer.
+        # Override in subclasses (e.g. XPUB enqueues to recv_queue).
+        #
+        # @param conn [Connection]
+        # @param prefix [String]
+        #
+        def on_cancel(conn, prefix)
+          @subscriptions[conn]&.delete(prefix)
+        end
+
+        def start_send_pump
+          @send_pump_started = true
+          @tasks << Reactor.spawn_pump do
+            loop do
+              parts = @send_queue.dequeue
+              topic = parts.first || "".b
+              @connections.each do |conn|
+                next unless subscribed?(conn, topic)
+                begin
+                  conn.send_message(parts)
+                rescue IOError, EOFError
+                  # connection dead — will be cleaned up
+                end
+              end
+            end
+          end
+        end
+
+        def start_subscription_listener(conn)
+          @tasks << Reactor.spawn_pump do
+            loop do
+              frame = conn.read_frame
+              next unless frame.command?
+              cmd = Codec::Command.from_body(frame.body)
+              case cmd.name
+              when "SUBSCRIBE" then on_subscribe(conn, cmd.data)
+              when "CANCEL"    then on_cancel(conn, cmd.data)
+              end
+            end
+          rescue EOFError
+            @engine.connection_lost(conn)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/pair.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # PAIR socket routing: exclusive 1-to-1 bidirectional.
+      #
+      # Only one peer connection is allowed. Messages flow through
+      # internal send/recv queues backed by Async::LimitedQueue.
+      #
+      class Pair
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @connection = nil
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @send_queue = Async::LimitedQueue.new(engine.options.send_hwm)
+          @tasks      = []
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        # @raise [RuntimeError] if a connection already exists
+        #
+        def connection_added(connection)
+          raise "PAIR allows only one peer" if @connection
+          @connection = connection
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+          start_send_pump(connection)
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connection = nil if @connection == connection
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        def start_send_pump(conn)
+          @tasks << Reactor.spawn_pump do
+            loop { conn.send_message(@send_queue.dequeue) }
+          rescue EOFError, IOError
+            @engine.connection_lost(conn)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/pub.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # PUB socket routing: fan-out to all subscribers.
+      #
+      # Listens for SUBSCRIBE/CANCEL commands from peers.
+      # Drops messages if a subscriber's connection write fails.
+      #
+      class Pub
+        include FanOut
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine = engine
+          @tasks  = []
+          init_fan_out(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :send_queue
+
+        # PUB is write-only.
+        #
+        def recv_queue
+          raise "PUB sockets cannot receive"
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          @subscriptions[connection] = Set.new
+          start_subscription_listener(connection)
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+          @subscriptions.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/pull.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # PULL socket routing: fair-queue receive from PUSH peers.
+      #
+      class Pull
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @tasks      = []
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          task = @engine.start_recv_pump(connection, @recv_queue)
+          @tasks << task if task
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          # recv pump stops on EOFError
+        end
+
+        # PULL is read-only.
+        #
+        def enqueue(_parts)
+          raise "PULL sockets cannot send"
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/push.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # PUSH socket routing: round-robin send to PULL peers.
+      #
+      class Push
+        include RoundRobin
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine = engine
+          @tasks  = []
+          init_round_robin(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :send_queue
+
+        # PUSH is write-only.
+        #
+        def recv_queue
+          raise "PUSH sockets cannot receive"
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          signal_connection_available
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/rep.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # REP socket routing: fair-queue receive, reply routed back to sender.
+      #
+      # REP strips the routing envelope (everything up to and including the
+      # empty delimiter) on receive, saves it internally, and restores it
+      # on send.
+      #
+      class Rep
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine            = engine
+          @recv_queue        = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
+          @pending_replies   = []
+          @tasks             = []
+          @send_pump_started = false
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          transform = ->(msg) {
+            envelope = []
+            while msg.first && !msg.first.empty?
+              envelope << msg.shift
+            end
+            msg.shift # remove empty delimiter
+            @pending_replies << { conn: connection, envelope: envelope }
+            msg
+          }
+          task = @engine.start_recv_pump(connection, @recv_queue, transform: transform)
+          @tasks << task if task
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          # Remove any pending replies for this connection
+          @pending_replies.reject! { |r| r[:conn] == connection }
+        end
+
+        # Enqueues a reply for sending.
+        #
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        def start_send_pump
+          @send_pump_started = true
+          @tasks << Reactor.spawn_pump do
+            loop do
+              parts = @send_queue.dequeue
+              reply_info = @pending_replies.shift
+              next unless reply_info
+              reply_info[:conn].send_message([*reply_info[:envelope], "".b, *parts])
+            end
+          rescue EOFError
+            # connection lost mid-write
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/req.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # REQ socket routing: round-robin send with strict send/recv alternation.
+      #
+      # REQ prepends an empty delimiter frame on send and strips it on receive.
+      #
+      class Req
+        include RoundRobin
+
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine     = engine
+          @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @tasks      = []
+          init_round_robin(engine)
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          @connections << connection
+          signal_connection_available
+          task = @engine.start_recv_pump(connection, @recv_queue,
+                   transform: method(:transform_recv))
+          @tasks << task if task
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections.delete(connection)
+        end
+
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        #
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        # REQ prepends empty delimiter frame on the wire.
+        #
+        def transform_send(parts) = ["".b, *parts]
+
+        # REQ strips the leading empty delimiter frame on receive.
+        #
+        def transform_recv(msg)
+          msg.shift if msg.first&.empty?
+          msg
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/round_robin.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Routing
+      # Mixin for routing strategies that send via round-robin.
+      #
+      # Provides reactive connection management: Async::Promise waits
+      # for the first connection, Array#cycle handles round-robin,
+      # and a new Promise is created when all connections drop.
+      #
+      # Including classes must call `init_round_robin(engine)` from
+      # their #initialize.
+      #
+      module RoundRobin
+        private
+
+        def init_round_robin(engine)
+          @connections          = []
+          @cycle                = @connections.cycle
+          @connection_available = Async::Promise.new
+          @send_queue           = Async::LimitedQueue.new(engine.options.send_hwm)
+          @send_pump_started    = false
+        end
+
+        def signal_connection_available
+          unless @connection_available.resolved?
+            @connection_available.resolve(true)
+          end
+        end
+
+        # Blocks until a connection is available, then returns
+        # the next one in round-robin order.
+        #
+        # @return [Connection]
+        #
+        def next_connection
+          @cycle.next
+        rescue StopIteration
+          @connection_available = Async::Promise.new
+          @connection_available.wait
+          @cycle = @connections.cycle
+          retry
+        end
+
+        # Transforms parts before sending. Override in subclasses
+        # (e.g. REQ prepends an empty delimiter frame).
+        #
+        # @param parts [Array<String>]
+        # @return [Array<String>]
+        #
+        def transform_send(parts) = parts
+
+        def start_send_pump
+          @send_pump_started = true
+          @tasks << Reactor.spawn_pump do
+            loop do
+              parts = @send_queue.dequeue
+              conn  = next_connection
+              conn.send_message(transform_send(parts))
+            end
+          rescue EOFError, IOError
+            # connection lost mid-write
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/zmtp/routing/router.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+
+module OMQ
+  module ZMTP
+    module Routing
+      # ROUTER socket routing: identity-based routing.
+      #
+      # Prepends peer identity frame on receive. Uses first frame as
+      # routing identity on send.
+      #
+      class Router
+        # @param engine [Engine]
+        #
+        def initialize(engine)
+          @engine                  = engine
+          @recv_queue              = Async::LimitedQueue.new(engine.options.recv_hwm)
+          @send_queue              = Async::LimitedQueue.new(engine.options.send_hwm)
+          @connections_by_identity = {}
+          @tasks                   = []
+          @send_pump_started       = false
+        end
+
+        # @return [Async::LimitedQueue]
+        #
+        attr_reader :recv_queue, :send_queue
+
+        # @param connection [Connection]
+        #
+        def connection_added(connection)
+          identity = connection.peer_identity
+          identity = SecureRandom.bytes(5) if identity.nil? || identity.empty?
+          @connections_by_identity[identity] = connection
+
+          task = @engine.start_recv_pump(connection, @recv_queue,
+                   transform: ->(msg) { [identity, *msg] })
+          @tasks << task if task
+
+          start_send_pump unless @send_pump_started
+        end
+
+        # @param connection [Connection]
+        #
+        def connection_removed(connection)
+          @connections_by_identity.reject! { |_, c| c == connection }
+        end
+
+        # Enqueues a message for sending.
+        #
+        # @param parts [Array<String>]
+        #
+        def enqueue(parts)
+          @send_queue.enqueue(parts)
+        end
+
+        def stop
+          @tasks.each(&:stop)
+          @tasks.clear
+        end
+
+        private
+
+        def start_send_pump
+          @send_pump_started = true
+          @tasks << Reactor.spawn_pump do
+            loop do
+              parts = @send_queue.dequeue
+              identity = parts.first
+              conn = @connections_by_identity[identity]
+
+              unless conn
+                if @engine.options.router_mandatory?
+                  raise SocketError, "no route to identity #{identity.inspect}"
+                end
+                next # silently drop
+              end
+
+              # Send everything after the identity frame
+              conn.send_message(parts[1..])
+            end
+          end
+        end
+      end
+    end
+  end
+end