omq 0.9.0 → 0.11.0

data/lib/omq/routing/dealer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # DEALER socket routing: round-robin send, fair-queue receive.
+    #
+    # No envelope manipulation — messages pass through unchanged.
+    #
+    class Dealer
+      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
+        update_direct_pipe
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        update_direct_pipe
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+    end
+  end
+end

data/lib/omq/routing/dish.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # DISH socket routing: group-based receive from RADIO peers.
+    #
+    # Sends JOIN/LEAVE commands to connected RADIO peers.
+    # Receives two-frame messages (group + body) from RADIO.
+    #
+    class Dish
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine      = engine
+        @connections = []
+        @recv_queue  = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @groups      = Set.new
+        @tasks       = []
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        # Send existing group memberships to new peer
+        @groups.each do |group|
+          connection.send_command(Protocol::ZMTP::Codec::Command.join(group))
+        end
+        task = @engine.start_recv_pump(connection, @recv_queue)
+        @tasks << task if task
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+      end
+
+      # DISH is read-only.
+      #
+      def enqueue(_parts)
+        raise "DISH sockets cannot send"
+      end
+
+      # Joins a group.
+      #
+      # @param group [String]
+      #
+      def join(group)
+        @groups << group
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.join(group))
+        end
+      end
+
+      # Leaves a group.
+      #
+      # @param group [String]
+      #
+      def leave(group)
+        @groups.delete(group)
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.leave(group))
+        end
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end

data/lib/omq/routing/fan_out.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module OMQ
+  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
+      attr_reader :subscriber_joined
+
+      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
+        @send_pump_idle     = true
+        @conflate           = engine.options.conflate
+        @subscriber_joined  = Async::Promise.new
+        @written            = Set.new
+        @latest             = {} if @conflate
+      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.start_with?(prefix) }
+      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.b.freeze
+        @subscriber_joined.resolve(conn) unless @subscriber_joined.resolved?
+      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
+
+      # @return [Boolean] true when the send pump is idle (not sending a batch)
+      def send_pump_idle? = @send_pump_idle
+
+
+      def start_send_pump
+        @send_pump_started = true
+        @tasks << @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+
+            @written.clear
+
+            if @conflate
+              # Keep only the last matching message per connection.
+              @latest.clear
+              batch.each do |parts|
+                topic = parts.first || EMPTY_BINARY
+                @connections.each do |conn|
+                  next unless subscribed?(conn, topic)
+                  @latest[conn] = parts
+                end
+              end
+              @latest.each do |conn, parts|
+                begin
+                  conn.write_message(parts)
+                  @written << conn
+                rescue *CONNECTION_LOST
+                end
+              end
+            else
+              batch.each do |parts|
+                topic      = parts.first || EMPTY_BINARY
+                wire_bytes = nil
+
+                @connections.each do |conn|
+                  next unless subscribed?(conn, topic)
+                  begin
+                    if conn.respond_to?(:curve?) && conn.curve?
+                      conn.write_message(parts)
+                    elsif conn.respond_to?(:write_wire)
+                      wire_bytes ||= Protocol::ZMTP::Codec::Frame.encode_message(parts)
+                      conn.write_wire(wire_bytes)
+                    else
+                      conn.write_message(parts)
+                    end
+                    @written << conn
+                  rescue *CONNECTION_LOST
+                  end
+                end
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+            end
+          end
+        end
+      end
+
+      def start_subscription_listener(conn)
+        @tasks << @engine.spawn_pump_task(annotation: "subscription listener") do
+          loop do
+            frame = conn.read_frame
+            next unless frame.command?
+            cmd = Protocol::ZMTP::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 *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/gather.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # GATHER socket routing: fair-queue receive from SCATTER peers.
+    #
+    class Gather
+      # @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 CONNECTION_LOST
+      end
+
+      # GATHER is read-only.
+      #
+      def enqueue(_parts)
+        raise "GATHER sockets cannot send"
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end

data/lib/omq/routing/pair.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OMQ
+  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          = []
+        @send_pump_idle = true
+      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) unless connection.is_a?(Transport::Inproc::DirectPipe)
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        if @connection == connection
+          @connection = nil
+          @send_pump&.stop
+          @send_pump = nil
+        end
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        conn = @connection
+        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.direct_recv_queue
+          conn.send_message(parts)
+        else
+          @send_queue.enqueue(parts)
+        end
+      end
+
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump(conn)
+        @send_pump = @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+            batch.each { |parts| conn.write_message(parts) }
+            conn.flush
+          end
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+        @tasks << @send_pump
+      end
+    end
+  end
+end

data/lib/omq/routing/peer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # PEER socket routing: bidirectional multi-peer with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Peer
+      # @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_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @tasks                      = []
+        @send_pump_started          = false
+        @send_pump_idle             = true
+        @written                    = Set.new
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        routing_id = SecureRandom.bytes(4)
+        @connections_by_routing_id[routing_id] = connection
+        @routing_id_by_connection[connection]  = routing_id
+
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          [routing_id, *msg]
+        end
+        @tasks << task if task
+
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        routing_id = @routing_id_by_connection.delete(connection)
+        @connections_by_routing_id.delete(routing_id) if routing_id
+      end
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        @send_queue.enqueue(parts)
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      def send_pump_idle? = @send_pump_idle
+
+      private
+
+      def start_send_pump
+        @send_pump_started = true
+        @tasks << @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            @send_pump_idle = true
+            batch = [@send_queue.dequeue]
+            @send_pump_idle = false
+            Routing.drain_send_queue(@send_queue, batch)
+
+            @written.clear
+            batch.each do |parts|
+              routing_id = parts.first
+              conn       = @connections_by_routing_id[routing_id]
+              next unless conn # silently drop if peer gone
+              begin
+                conn.write_message(parts[1..])
+                @written << conn
+              rescue *CONNECTION_LOST
+                # will be cleaned up
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+              # will be cleaned up
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/pub.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OMQ
+  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

data/lib/omq/routing/pull.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OMQ
+  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

data/lib/omq/routing/push.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module OMQ
+  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
+        update_direct_pipe
+        start_send_pump unless @send_pump_started
+        start_reaper(connection)
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        update_direct_pipe
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+
+      # Stops all background tasks (send pump, reapers).
+      #
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+      private
+
+
+      # Detects peer disconnection on write-only sockets. Without
+      # this, a dead peer is only noticed on the next send — which
+      # may succeed if the kernel send buffer absorbs the data.
+      #
+      def start_reaper(conn)
+        return if conn.is_a?(Transport::Inproc::DirectPipe)
+        @tasks << @engine.spawn_pump_task(annotation: "reaper") do
+          conn.receive_message # blocks until peer disconnects
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+    end
+  end
+end