omq 0.9.0 → 0.11.0

data/lib/omq/routing/radio.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # RADIO socket routing: group-based fan-out to DISH peers.
+    #
+    # Like PUB/FanOut but with exact group matching and JOIN/LEAVE
+    # commands instead of SUBSCRIBE/CANCEL.
+    #
+    # Messages are sent as two frames on the wire:
+    #   group (MORE=1) + body (MORE=0)
+    #
+    class Radio
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine            = engine
+        @connections       = []
+        @groups            = {} # connection => Set of joined groups
+        @send_queue        = Async::LimitedQueue.new(engine.options.send_hwm)
+        @send_pump_started = false
+        @conflate          = engine.options.conflate
+        @tasks             = []
+        @written           = Set.new
+        @latest            = {} if @conflate
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :send_queue
+
+      # RADIO is write-only.
+      #
+      def recv_queue
+        raise "RADIO sockets cannot receive"
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        @groups[connection] = Set.new
+        start_group_listener(connection)
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        @groups.delete(connection)
+      end
+
+      # Enqueues a message for sending.
+      #
+      # @param parts [Array<String>] [group, body]
+      #
+      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 << @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|
+                group = parts[0]
+                body  = parts[1] || EMPTY_BINARY
+                @connections.each do |conn|
+                  next unless @groups[conn]&.include?(group)
+                  @latest[conn] = [group, body]
+                end
+              end
+              @latest.each do |conn, msg|
+                begin
+                  conn.write_message(msg)
+                  @written << conn
+                rescue *CONNECTION_LOST
+                end
+              end
+            else
+              batch.each do |parts|
+                group      = parts[0]
+                body       = parts[1] || EMPTY_BINARY
+                msg        = [group, body]
+                wire_bytes = nil
+
+                @connections.each do |conn|
+                  next unless @groups[conn]&.include?(group)
+                  begin
+                    if conn.respond_to?(:curve?) && conn.curve?
+                      conn.write_message(msg)
+                    elsif conn.respond_to?(:write_wire)
+                      wire_bytes ||= Protocol::ZMTP::Codec::Frame.encode_message(msg)
+                      conn.write_wire(wire_bytes)
+                    else
+                      conn.write_message(msg)
+                    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_group_listener(conn)
+        @tasks << @engine.spawn_pump_task(annotation: "group 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 "JOIN"  then @groups[conn]&.add(cmd.data)
+            when "LEAVE" then @groups[conn]&.delete(cmd.data)
+            end
+          end
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/rep.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module OMQ
+  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]
+      #
+      EMPTY_FRAME = "".b.freeze
+
+      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
+        @send_pump_idle    = true
+        @written           = Set.new
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          delimiter = msg.index(&:empty?) || msg.size
+          envelope  = msg[0, delimiter]
+          body      = msg[(delimiter + 1)..] || []
+          @pending_replies << { conn: connection, envelope: envelope }
+          body
+        end
+        @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
+
+      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|
+              reply_info = @pending_replies.shift
+              next unless reply_info
+              conn = reply_info[:conn]
+              begin
+                conn.write_message([*reply_info[:envelope], EMPTY_FRAME, *parts])
+                @written << conn
+              rescue *CONNECTION_LOST
+                # connection lost mid-write
+              end
+            end
+
+            @written.each do |conn|
+              conn.flush
+            rescue *CONNECTION_LOST
+              # connection lost mid-flush
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/req.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module OMQ
+  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
+        update_direct_pipe
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          msg.first&.empty? ? msg[1..] : msg
+        end
+        @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
+
+      private
+
+      # REQ prepends empty delimiter frame on the wire.
+      #
+      def transform_send(parts) = [EMPTY_BINARY, *parts]
+
+    end
+  end
+end

data/lib/omq/routing/round_robin.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module OMQ
+  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
+
+
+      # Initializes round-robin state for the including class.
+      #
+      # @param engine [Engine]
+      #
+      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
+        @send_pump_idle       = true
+        @direct_pipe          = nil
+        @written              = Set.new
+      end
+
+
+      # Resolves the connection-available promise so blocked
+      # senders can proceed.
+      #
+      def signal_connection_available
+        unless @connection_available.resolved?
+          @connection_available.resolve(true)
+        end
+      end
+
+
+      # Updates the direct-pipe shortcut for inproc single-peer bypass.
+      # Call from connection_added after @connections is updated.
+      #
+      def update_direct_pipe
+        if @connections.size == 1 && @connections.first.is_a?(Transport::Inproc::DirectPipe)
+          @direct_pipe = @connections.first
+        else
+          @direct_pipe = nil
+        end
+      end
+
+
+      # Enqueues directly to the inproc peer's recv queue if possible,
+      # otherwise falls back to the send queue for the send pump.
+      #
+      def enqueue_round_robin(parts)
+        pipe = @direct_pipe
+        if pipe&.direct_recv_queue
+          pipe.send_message(transform_send(parts))
+        else
+          @send_queue.enqueue(parts)
+        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
+
+
+      # Starts the background send pump that dequeues messages
+      # and dispatches them round-robin across connections.
+      #
+      # @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)
+
+            if batch.size == 1
+              send_with_retry(batch[0])
+            else
+              send_batch(batch)
+            end
+          end
+        end
+      end
+
+
+      # Sends a single message, retrying on a new connection if
+      # the current one is lost.
+      #
+      # @param parts [Array<String>]
+      #
+      def send_with_retry(parts)
+        conn = next_connection
+        conn.send_message(transform_send(parts))
+      rescue *CONNECTION_LOST
+        @engine.connection_lost(conn)
+        retry
+      end
+
+
+      # Sends a batch of messages, writing without flushing for
+      # throughput. Falls back to #send_with_retry on failure.
+      #
+      # @param batch [Array<Array<String>>]
+      #
+      def send_batch(batch)
+        @written.clear
+        batch.each_with_index do |parts, i|
+          conn = next_connection
+          begin
+            conn.write_message(transform_send(parts))
+            @written << conn
+          rescue *CONNECTION_LOST
+            @engine.connection_lost(conn)
+            # Flush what we've written so far
+            @written.each do |c|
+              c.flush
+            rescue *CONNECTION_LOST
+              # will be cleaned up
+            end
+            @written.clear
+            # Fall back to send_with_retry for this and remaining
+            send_with_retry(parts)
+            batch[(i + 1)..].each { |p| send_with_retry(p) }
+            return
+          end
+        end
+        @written.each do |conn|
+          conn.flush
+        rescue *CONNECTION_LOST
+          # will be cleaned up
+        end
+      end
+    end
+  end
+end

data/lib/omq/routing/router.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+
+module OMQ
+  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 = {}
+        @identity_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)
+        identity = connection.peer_identity
+        identity = SecureRandom.bytes(5) if identity.nil? || identity.empty?
+        @connections_by_identity[identity] = connection
+        @identity_by_connection[connection] = identity
+
+        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+          [identity, *msg]
+        end
+        @tasks << task if task
+
+        start_send_pump unless @send_pump_started
+      end
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        identity = @identity_by_connection.delete(connection)
+        @connections_by_identity.delete(identity) if identity
+      end
+
+      # Enqueues a message for sending.
+      #
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        if @engine.options.router_mandatory?
+          identity = parts.first
+          unless @connections_by_identity[identity]
+            raise SocketError, "no route to identity #{identity.inspect}"
+          end
+        end
+        @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|
+              identity = parts.first
+              conn     = @connections_by_identity[identity]
+              next unless conn # silently drop (peer may have disconnected)
+              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/scatter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # SCATTER socket routing: round-robin send to GATHER peers.
+    #
+    class Scatter
+      include RoundRobin
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine = engine
+        @tasks  = []
+        init_round_robin(engine)
+      end
+
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :send_queue
+
+
+      # SCATTER is write-only.
+      #
+      def recv_queue
+        raise "SCATTER 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 by
+      # blocking on a receive that only returns on disconnect.
+      #
+      # @param conn [Connection]
+      #
+      def start_reaper(conn)
+        return if conn.is_a?(Transport::Inproc::DirectPipe)
+        @tasks << @engine.spawn_pump_task(annotation: "reaper") do
+          conn.receive_message
+        rescue *CONNECTION_LOST
+          @engine.connection_lost(conn)
+        end
+      end
+    end
+  end
+end