omq 0.22.1 → 0.23.0

data/lib/omq/routing/peer.rb

@@ -0,0 +1,95 @@
+# 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
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+
+      # @return [Hash{String => Connection}] routing_id → connection
+      #
+      attr_reader :connections_by_routing_id
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine                     = engine
+        @recv_queue                 = Routing.build_queue(engine.options.recv_hwm, :block)
+        @connections_by_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @conn_queues                = {}
+      end
+
+
+      # Dequeues the next received message. Blocks until one is available.
+      #
+      # @return [Array<String>, nil]
+      #
+      def dequeue_recv
+        @recv_queue.dequeue
+      end
+
+
+      # Wakes a blocked {#dequeue_recv} with a nil sentinel.
+      #
+      # @return [void]
+      #
+      def unblock_recv
+        @recv_queue.enqueue(nil)
+      end
+
+
+      # @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
+
+        @engine.start_recv_pump(connection, @recv_queue) { |msg| [routing_id, *msg] }
+
+        q = Routing.build_queue(@engine.options.send_hwm, :block)
+        @conn_queues[connection] = q
+        ConnSendPump.start(@engine, connection, q)
+      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
+        @conn_queues.delete(connection)
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        routing_id = parts.first
+        conn = @connections_by_routing_id[routing_id]
+        return unless conn
+        @conn_queues[conn]&.enqueue(parts[1..])
+      end
+
+
+      # True when all per-connection send queues are empty.
+      #
+      def send_queues_drained?
+        @conn_queues.values.all?(&:empty?)
+      end
+
+    end
+  end
+end

data/lib/omq/routing/pub.rb

@@ -15,7 +15,6 @@ module OMQ
       #
       def initialize(engine)
         @engine = engine
-        @tasks  = []
         init_fan_out(engine)
       end
 
@@ -62,16 +61,6 @@ module OMQ
         fan_out_enqueue(parts)
       end
 
-
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
     end
   end
 end

data/lib/omq/routing/pull.rb

@@ -10,7 +10,6 @@ module OMQ
       def initialize(engine)
         @engine     = engine
         @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
-        @tasks      = []
       end
 
 
@@ -42,8 +41,7 @@ module OMQ
       # @param connection [Connection]
       #
       def connection_added(connection)
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
       end
 
 
@@ -60,16 +58,6 @@ module OMQ
         raise "PULL sockets cannot send"
       end
 
-
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
     end
   end
 end

data/lib/omq/routing/push.rb

@@ -12,7 +12,6 @@ module OMQ
       #
       def initialize(engine)
         @engine = engine
-        @tasks  = []
         init_round_robin(engine)
       end
 
@@ -57,14 +56,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks (send pumps, reapers).
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 
@@ -74,7 +65,7 @@ module OMQ
       #
       def start_reaper(conn)
         return if conn.is_a?(Transport::Inproc::DirectPipe)
-        @tasks << @engine.spawn_conn_pump_task(conn, annotation: "reaper") do
+        @engine.spawn_conn_pump_task(conn, annotation: "reaper") do
           conn.receive_message # blocks until peer disconnects; then exits
         end
       end

data/lib/omq/routing/radio.rb

@@ -0,0 +1,187 @@
+# 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
+      # Sentinel used for UDP connections that have no group filter:
+      # any group is considered a match.
+      #
+      ANY_GROUPS = Object.new.tap { |o| o.define_singleton_method(:include?) { |_| true } }.freeze
+
+
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :send_queue
+
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine            = engine
+        @connections       = []
+        @groups            = {} # connection => Set of joined groups (or ANY_GROUPS for UDP)
+        @send_queue        = Routing.build_queue(engine.options.send_hwm, :block)
+        @on_mute           = engine.options.on_mute
+        @send_pump_started = false
+        @conflate          = engine.options.conflate
+        @written           = Set.new
+        @latest            = {} if @conflate
+      end
+
+
+      # RADIO is write-only.
+      #
+      def recv_queue
+        raise "RADIO sockets cannot receive"
+      end
+
+
+      # No-op; RADIO has no recv queue to unblock.
+      #
+      def unblock_recv
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        if connection.respond_to?(:read_frame)
+          @groups[connection] = Set.new
+          start_group_listener(connection)
+        else
+          @groups[connection] = ANY_GROUPS  # UDP: fan-out to all groups
+        end
+        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
+
+
+      # True when the send queue is empty.
+      #
+      def send_queues_drained?
+        @send_queue.empty?
+      end
+
+
+      private
+
+
+      def muted?(conn)
+        return false if @on_mute == :block
+        q = conn.direct_recv_queue if conn.respond_to?(:direct_recv_queue)
+        q&.respond_to?(:limited?) && q.limited?
+      end
+
+
+      def start_send_pump
+        @send_pump_started = true
+        @engine.spawn_pump_task(annotation: "send pump", parent: @engine.barrier) do
+          batch = []
+
+          loop do
+            @send_pump_idle = true
+            Routing.dequeue_batch(@send_queue, batch)
+            @send_pump_idle = false
+
+            @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|
+                next if muted?(conn)
+                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)
+                  next if muted?(conn)
+                  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
+
+            batch.clear
+          end
+        end
+      end
+
+
+      def start_group_listener(conn)
+        @engine.spawn_conn_pump_task(conn, 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"
+              @groups[conn]&.add(cmd.data)
+            when "LEAVE"
+              @groups[conn]&.delete(cmd.data)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/omq/routing/rep.rb

@@ -23,9 +23,7 @@ module OMQ
         @engine          = engine
         @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
         @pending_replies = []
-        @conn_queues     = {}  # connection => per-connection send queue
-        @conn_send_tasks = {}  # connection => send pump task
-        @tasks           = []
+        @conn_queues     = {}
       end
 
 
@@ -50,7 +48,7 @@ module OMQ
       # @param connection [Connection]
       #
       def connection_added(connection)
-        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+        @engine.start_recv_pump(connection, @recv_queue) do |msg|
           delimiter = msg.index { |p| p.empty? } || msg.size
           envelope  = msg[0, delimiter]
           body      = msg[(delimiter + 1)..] || []
@@ -58,11 +56,10 @@ module OMQ
           @pending_replies << [connection, envelope]
           body
         end
-        @tasks << task if task
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
-        @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
+        ConnSendPump.start(@engine, connection, q)
       end
 
 
@@ -71,7 +68,6 @@ module OMQ
       def connection_removed(connection)
         @pending_replies.reject! { |r| r[0] == connection }
         @conn_queues.delete(connection)
-        @conn_send_tasks.delete(connection)&.stop
       end
 
 
@@ -92,16 +88,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?

data/lib/omq/routing/req.rb

@@ -21,10 +21,9 @@ module OMQ
       # @param engine [Engine]
       #
       def initialize(engine)
-        @engine          = engine
-        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
-        @tasks           = []
-        @state           = :ready        # :ready or :waiting_reply
+        @engine     = engine
+        @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
+        @state      = :ready        # :ready or :waiting_reply
         init_round_robin(engine)
       end
 
@@ -50,12 +49,11 @@ module OMQ
       # @param connection [Connection]
       #
       def connection_added(connection)
-        task = @engine.start_recv_pump(connection, @recv_queue) do |msg|
+        @engine.start_recv_pump(connection, @recv_queue) do |msg|
           @state = :ready
           msg.first&.empty? ? msg[1..] : msg
         end
 
-        @tasks << task if task
         add_round_robin_send_connection(connection)
       end
 
@@ -77,16 +75,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 

data/lib/omq/routing/round_robin.rb

@@ -12,7 +12,7 @@ module OMQ
     # which is strictly better than libzmq's strict per-pipe round-robin
     # for PUSH-style patterns.
     #
-    # See DESIGN.md "Per-socket HWM (not per-connection)" for the
+    # See doc/DESIGN.md "Per-socket HWM (not per-connection)" for the
     # full reasoning.
     #
     # Including classes must call `init_round_robin(engine)` from
@@ -38,11 +38,10 @@ module OMQ
       # @param engine [Engine]
       #
       def init_round_robin(engine)
-        @connections     = []
-        @send_queue      = Routing.build_queue(engine.options.send_hwm, :block)
-        @direct_pipe     = nil
-        @conn_send_tasks = {}  # conn => send pump task
-        @in_flight       = 0   # messages dequeued but not yet written
+        @connections = []
+        @send_queue  = Routing.build_queue(engine.options.send_hwm, :block)
+        @direct_pipe = nil
+        @in_flight   = 0   # messages dequeued but not yet written
       end
 
 
@@ -58,16 +57,16 @@ module OMQ
       end
 
 
-      # Removes the connection and stops its send pump. Any message
-      # the pump had already dequeued but not yet written is dropped --
-      # matching libzmq's behavior on `pipe_terminated`. PUSH has no
-      # cross-peer ordering guarantee, so this is safe.
+      # Removes the connection. Any message the pump had already
+      # dequeued but not yet written is dropped — matching libzmq's
+      # behavior on `pipe_terminated`. PUSH has no cross-peer ordering
+      # guarantee, so this is safe. The pump itself is torn down by
+      # the per-connection lifecycle barrier.
       #
       # @param conn [Connection]
       #
       def remove_round_robin_send_connection(conn)
         update_direct_pipe
-        @conn_send_tasks.delete(conn)
       end
 
 
@@ -132,7 +131,7 @@ module OMQ
       # @param conn [Connection]
       #
       def start_conn_send_pump(conn)
-        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           batch = []
 
           loop do
@@ -153,9 +152,6 @@ module OMQ
             Async::Task.current.yield
           end
         end
-
-        @conn_send_tasks[conn] = task
-        @tasks << task
       end
 
 

data/lib/omq/routing/router.rb

@@ -23,9 +23,7 @@ module OMQ
         @recv_queue              = Routing.build_queue(engine.options.recv_hwm, :block)
         @connections_by_identity = {}
         @identity_by_connection  = {}
-        @conn_queues             = {}  # connection => per-connection send queue
-        @conn_send_tasks         = {}  # connection => send pump task
-        @tasks                   = []
+        @conn_queues             = {}
       end
 
 
@@ -55,12 +53,11 @@ module OMQ
         @connections_by_identity[identity] = connection
         @identity_by_connection[connection] = identity
 
-        task = @engine.start_recv_pump(connection, @recv_queue) { |msg| [identity, *msg] }
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue) { |msg| [identity, *msg] }
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
-        @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
+        ConnSendPump.start(@engine, connection, q)
       end
 
 
@@ -70,7 +67,6 @@ module OMQ
         identity = @identity_by_connection.delete(connection)
         @connections_by_identity.delete(identity) if identity
         @conn_queues.delete(connection)
-        @conn_send_tasks.delete(connection)&.stop
       end
 
 
@@ -91,16 +87,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       # @return [Boolean] true when all per-connection send queues are empty
       #
       def send_queues_drained?

data/lib/omq/routing/scatter.rb

@@ -0,0 +1,77 @@
+# 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
+        init_round_robin(engine)
+      end
+
+
+      # SCATTER is write-only.
+      #
+      def recv_queue
+        raise "SCATTER sockets cannot receive"
+      end
+
+
+      def dequeue_recv
+        raise "SCATTER sockets cannot receive"
+      end
+
+
+      # No-op; SCATTER has no recv queue to unblock.
+      #
+      def unblock_recv
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        add_round_robin_send_connection(connection)
+        start_reaper(connection)
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        remove_round_robin_send_connection(connection)
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      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)
+        @engine.spawn_conn_pump_task(conn, annotation: "reaper") do
+          conn.receive_message # blocks until peer disconnects; then exits
+        end
+      end
+
+    end
+  end
+end