omq 0.8.0 → 0.10.0

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

data/lib/omq/routing/server.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # SERVER socket routing: identity-based routing with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Server
+      # @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/sub.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # SUB socket routing: subscription-based receive from PUB peers.
+    #
+    # Sends SUBSCRIBE/CANCEL commands to connected PUB peers.
+    #
+    class Sub
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine        = engine
+        @connections   = []
+        @recv_queue    = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @subscriptions = Set.new
+        @tasks         = []
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        # Send existing subscriptions to new peer
+        @subscriptions.each do |prefix|
+          connection.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
+        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
+
+      # SUB is read-only.
+      #
+      def enqueue(_parts)
+        raise "SUB sockets cannot send"
+      end
+
+      # Subscribes to a topic prefix.
+      #
+      # @param prefix [String]
+      #
+      def subscribe(prefix)
+        @subscriptions << prefix
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.subscribe(prefix))
+        end
+      end
+
+      # Unsubscribes from a topic prefix.
+      #
+      # @param prefix [String]
+      #
+      def unsubscribe(prefix)
+        @subscriptions.delete(prefix)
+        @connections.each do |conn|
+          conn.send_command(Protocol::ZMTP::Codec::Command.cancel(prefix))
+        end
+      end
+
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+    end
+  end
+end

data/lib/omq/routing/xpub.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # XPUB socket routing: like PUB but exposes subscription messages.
+    #
+    # Subscription/unsubscription messages from peers are delivered to
+    # the application as data frames: \x01 + prefix for subscribe,
+    # \x00 + prefix for unsubscribe.
+    #
+    class XPub
+      include FanOut
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+        @tasks      = []
+        init_fan_out(engine)
+      end
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue, :send_queue
+
+      # @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
+
+      private
+
+      # Expose subscription to application as data message.
+      #
+      def on_subscribe(conn, prefix)
+        super
+        @recv_queue.enqueue(["\x01#{prefix}".b])
+      end
+
+      # Expose unsubscription to application as data message.
+      #
+      def on_cancel(conn, prefix)
+        super
+        @recv_queue.enqueue(["\x00#{prefix}".b])
+      end
+    end
+  end
+end