omq 0.22.1 → 0.23.0

data/lib/omq/routing/server.rb

@@ -0,0 +1,90 @@
+# 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
+      # @return [Async::LimitedQueue]
+      #
+      attr_reader :recv_queue
+
+
+      # @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/sub.rb

@@ -20,7 +20,6 @@ module OMQ
         @connections   = Set.new
         @recv_queue    = Routing.build_queue(engine.options.recv_hwm, :block)
         @subscriptions = Set.new
-        @tasks         = []
       end
 
 
@@ -51,8 +50,7 @@ module OMQ
           send_subscribe(connection, prefix)
         end
 
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
       end
 
 
@@ -90,16 +88,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 

data/lib/omq/routing/xpub.rb

@@ -24,7 +24,6 @@ module OMQ
       def initialize(engine)
         @engine     = engine
         @recv_queue = Routing.build_queue(engine.options.recv_hwm, :block)
-        @tasks      = []
 
         init_fan_out(engine)
       end
@@ -68,16 +67,6 @@ module OMQ
       end
 
 
-      # Stops all background tasks.
-      #
-      # @return [void]
-      #
-      def stop
-        @tasks.each(&:stop)
-        @tasks.clear
-      end
-
-
       private
 
 

data/lib/omq/routing/xsub.rb

@@ -18,12 +18,10 @@ module OMQ
       # @param engine [Engine]
       #
       def initialize(engine)
-        @engine          = engine
-        @connections     = Set.new
-        @recv_queue      = Routing.build_queue(engine.options.recv_hwm, :block)
-        @conn_queues     = {}  # connection => per-connection send queue
-        @conn_send_tasks = {}  # connection => send pump task
-        @tasks           = []
+        @engine      = engine
+        @connections = Set.new
+        @recv_queue  = Routing.build_queue(engine.options.recv_hwm, :block)
+        @conn_queues = {}
       end
 
 
@@ -50,8 +48,7 @@ module OMQ
       def connection_added(connection)
         @connections << connection
 
-        task = @engine.start_recv_pump(connection, @recv_queue)
-        @tasks << task if task
+        @engine.start_recv_pump(connection, @recv_queue)
 
         q = Routing.build_queue(@engine.options.send_hwm, :block)
         @conn_queues[connection] = q
@@ -64,7 +61,6 @@ module OMQ
       def connection_removed(connection)
         @connections.delete(connection)
         @conn_queues.delete(connection)
-        @conn_send_tasks.delete(connection)&.stop
       end
 
 
@@ -79,16 +75,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?
@@ -100,7 +86,7 @@ module OMQ
 
 
       def start_conn_send_pump(conn, q)
-        task = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
+        @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             parts = q.dequeue
             frame = parts.first&.b
@@ -128,9 +114,6 @@ module OMQ
             end
           end
         end
-
-        @conn_send_tasks[conn] = task
-        @tasks << task
       end
 
     end

data/lib/omq/scatter_gather.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# OMQ SCATTER/GATHER socket types (ZeroMQ RFC 49).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/scatter_gather"
+
+require "omq"
+require_relative "routing/scatter"
+require_relative "routing/gather"
+
+module OMQ
+  # Pipeline sender socket that round-robins to GATHER peers (ZeroMQ RFC 49).
+  class SCATTER < Socket
+    include Writable
+    include SingleFrame
+
+    # Creates a new SCATTER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to connect to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param send_hwm [Integer, nil] send high-water mark
+    # @param send_timeout [Integer, nil] send timeout in seconds
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, send_hwm: nil, send_timeout: nil, backend: nil)
+      init_engine(:SCATTER, send_hwm: send_hwm, send_timeout: send_timeout, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+    end
+  end
+
+
+  # Pipeline receiver socket that fair-queues from SCATTER peers (ZeroMQ RFC 49).
+  class GATHER < Socket
+    include Readable
+    include SingleFrame
+
+    # Creates a new GATHER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to bind to
+    # @param linger [Numeric] linger period in seconds (Float::INFINITY = wait forever, 0 = drop)
+    # @param recv_hwm [Integer, nil] receive high-water mark
+    # @param recv_timeout [Integer, nil] receive timeout in seconds
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, recv_hwm: nil, recv_timeout: nil, backend: nil)
+      init_engine(:GATHER, recv_hwm: recv_hwm, recv_timeout: recv_timeout, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :bind)
+    end
+  end
+
+
+  Routing.register(:SCATTER, Routing::Scatter)
+  Routing.register(:GATHER,  Routing::Gather)
+end

data/lib/omq/socket.rb

@@ -35,11 +35,6 @@ module OMQ
     attr_reader :options
 
 
-    # @return [Integer, nil] last auto-selected TCP port
-    #
-    attr_reader :last_tcp_port
-
-
     # @return [Engine] the socket's engine. Exposed for peer tooling
     #   (omq-cli, omq-ffi, omq-ractor) that needs to reach into the
     #   socket's internals — not part of the stable user API.
@@ -109,14 +104,11 @@ module OMQ
     #   can coordinate teardown with their own Async tree. Only the
     #   *first* bind/connect call captures the parent — subsequent
     #   calls ignore the kwarg.
-    # @return [void]
+    # @return [URI::Generic] resolved endpoint URI (with auto-selected port for "tcp://host:0")
     #
-    def bind(endpoint, parent: nil)
+    def bind(endpoint, parent: nil, **opts)
       ensure_parent_task(parent: parent)
-      Reactor.run do
-        @engine.bind(endpoint) # TODO: use timeout?
-        @last_tcp_port = @engine.last_tcp_port
-      end
+      Reactor.run { @engine.bind(endpoint, **opts) } # TODO: use timeout?
     end
 
 
@@ -124,11 +116,11 @@ module OMQ
     #
     # @param endpoint [String]
     # @param parent [#async, nil] see {#bind}.
-    # @return [void]
+    # @return [URI::Generic] parsed endpoint URI
     #
-    def connect(endpoint, parent: nil)
+    def connect(endpoint, parent: nil, **opts)
       ensure_parent_task(parent: parent)
-      Reactor.run { @engine.connect(endpoint) } # TODO: use timeout?
+      Reactor.run { @engine.connect(endpoint, **opts) } # TODO: use timeout?
     end
 
 
@@ -152,13 +144,6 @@ module OMQ
     end
 
 
-    # @return [String, nil] last bound endpoint
-    #
-    def last_endpoint
-      @engine.last_endpoint
-    end
-
-
     # @return [Async::Promise] resolves when first peer completes handshake
     def peer_connected
       @engine.peer_connected
@@ -167,7 +152,7 @@ module OMQ
 
     # @return [Async::Promise] resolves when first subscriber joins (PUB/XPUB only)
     def subscriber_joined
-      @engine.routing.subscriber_joined
+      @engine.subscriber_joined
     end
 
 
@@ -285,7 +270,7 @@ module OMQ
     # @return [String]
     #
     def inspect
-      format("#<%s last_endpoint=%p>", self.class, last_endpoint)
+      format("#<%s bound=%p>", self.class, @engine.listeners.keys)
     end
 
 

data/lib/omq/transport/inproc/direct_pipe.rb

@@ -50,12 +50,6 @@ module OMQ
         attr_reader :direct_recv_queue
 
 
-        # @return [Proc, nil] optional transform applied before
-        #   enqueuing into {#direct_recv_queue}
-        #
-        attr_accessor :direct_recv_transform
-
-
         # @param send_queue [Async::Queue, nil] outgoing command queue
         #   (nil for non-PUB/SUB types that don't exchange commands)
         # @param receive_queue [Async::Queue, nil] incoming command queue
@@ -75,18 +69,26 @@ module OMQ
         end
 
 
-        # Sets the direct recv queue. Drains any messages that were
-        # buffered before the queue was available.
+        # Wires up the direct recv fast-path. Called once by the recv
+        # pump when the receiving side of an inproc pipe pair is set up.
+        # After this, peer-side {#send_message} calls enqueue straight
+        # into +queue+ instead of hopping through the intermediate pipe
+        # queue and a recv pump fiber.
         #
-        # @param queue [Async::LimitedQueue, nil]
+        # Drains any messages the peer buffered into +@pending_direct+
+        # before the queue was available.
+        #
+        # @param queue [Async::LimitedQueue]
+        # @param transform [Proc, nil] optional per-message transform
         # @return [void]
         #
-        def direct_recv_queue=(queue)
-          @direct_recv_queue = queue
-          if queue && @pending_direct
-            @pending_direct.each { |msg| queue.enqueue(msg) }
-            @pending_direct = nil
-          end
+        def wire_direct_recv(queue, transform)
+          @direct_recv_transform = transform
+          @direct_recv_queue     = queue
+          return unless @pending_direct
+
+          @pending_direct.each { |msg| queue.enqueue(msg) }
+          @pending_direct = nil
         end
 
 

data/lib/omq/transport/inproc.rb

@@ -15,6 +15,9 @@ module OMQ
     # prevent shared mutable state without copying.
     #
     module Inproc
+      Engine.transports["inproc"] = self
+
+
       # Socket types that exchange commands (SUBSCRIBE/CANCEL) over inproc.
       #
       COMMAND_TYPES = %i[PUB SUB XPUB XSUB RADIO DISH].freeze
@@ -28,14 +31,19 @@ module OMQ
 
 
       class << self
-        # Binds an engine to an inproc endpoint.
+        # @return [Hash{String => Engine}] bound inproc endpoints
+        #
+        attr_reader :registry
+
+
+        # Creates a bound inproc listener.
         #
         # @param endpoint [String] e.g. "inproc://my-endpoint"
         # @param engine [Engine] the owning engine
         # @return [Listener]
         # @raise [ArgumentError] if endpoint is already bound
         #
-        def bind(endpoint, engine)
+        def listener(endpoint, engine, **)
           @mutex.synchronize do
             if @registry.key?(endpoint)
               raise ArgumentError, "endpoint already bound: #{endpoint}"
@@ -57,7 +65,7 @@ module OMQ
         # @param engine [Engine] the connecting engine
         # @return [void]
         #
-        def connect(endpoint, engine)
+        def connect(endpoint, engine, **)
           bound_engine = @mutex.synchronize { @registry[endpoint] }
           bound_engine ||= await_bind(endpoint, engine) or return
           establish_link(engine, bound_engine, endpoint)

data/lib/omq/transport/ipc.rb

@@ -11,14 +11,17 @@ module OMQ
     # (paths starting with @).
     #
     module IPC
+      Engine.transports["ipc"] = self
+
+
       class << self
-        # Binds an IPC server.
+        # Creates a bound IPC listener.
         #
         # @param endpoint [String] e.g. "ipc:///tmp/my.sock" or "ipc://@abstract"
         # @param engine [Engine]
         # @return [Listener]
         #
-        def bind(endpoint, engine)
+        def listener(endpoint, engine, **)
           path      = parse_path(endpoint)
           sock_path = to_socket_path(path)
 
@@ -31,18 +34,14 @@ module OMQ
         end
 
 
-        # Connects to an IPC endpoint.
+        # Creates an IPC dialer for an endpoint.
         #
         # @param endpoint [String]
         # @param engine [Engine]
-        # @return [void]
+        # @return [Dialer]
         #
-        def connect(endpoint, engine)
-          path = parse_path(endpoint)
-          sock_path = to_socket_path(path)
-          sock = UNIXSocket.new(sock_path)
-          apply_buffer_sizes(sock, engine.options)
-          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
+        def dialer(endpoint, engine, **)
+          Dialer.new(endpoint, engine)
         end
 
 
@@ -63,9 +62,6 @@ module OMQ
         end
 
 
-        private
-
-
         # Extracts path from "ipc://path".
         #
         def parse_path(endpoint)
@@ -92,6 +88,38 @@ module OMQ
       end
 
 
+      # An IPC dialer — stateful factory for outgoing connections.
+      #
+      class Dialer
+        # @return [String] the endpoint this dialer connects to
+        #
+        attr_reader :endpoint
+
+
+        # @param endpoint [String]
+        # @param engine [Engine]
+        #
+        def initialize(endpoint, engine)
+          @endpoint = endpoint
+          @engine   = engine
+        end
+
+
+        # Establishes a Unix socket connection to the endpoint.
+        #
+        # @return [void]
+        #
+        def connect
+          path      = IPC.parse_path(@endpoint)
+          sock_path = IPC.to_socket_path(path)
+          sock      = UNIXSocket.new(sock_path)
+          IPC.apply_buffer_sizes(sock, @engine.options)
+          @engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: @endpoint)
+        end
+
+      end
+
+
       # A bound IPC listener.
       #
       class Listener

data/lib/omq/transport/tcp.rb

@@ -9,14 +9,17 @@ module OMQ
     # TCP transport using Ruby sockets with Async.
     #
     module TCP
+      Engine.transports["tcp"] = self
+
+
       class << self
-        # Binds a TCP server.
+        # Creates a bound TCP listener.
         #
         # @param endpoint [String] e.g. "tcp://127.0.0.1:5555" or "tcp://*:0"
         # @param engine [Engine]
         # @return [Listener]
         #
-        def bind(endpoint, engine)
+        def listener(endpoint, engine, **)
           host, port  = self.parse_endpoint(endpoint)
           lookup_host = normalize_bind_host(host)
 
@@ -34,6 +37,17 @@ module OMQ
         end
 
 
+        # Creates a TCP dialer for an endpoint.
+        #
+        # @param endpoint [String] e.g. "tcp://127.0.0.1:5555"
+        # @param engine [Engine]
+        # @return [Dialer]
+        #
+        def dialer(endpoint, engine, **)
+          Dialer.new(endpoint, engine)
+        end
+
+
         # Validates that the endpoint's host can be resolved.
         #
         # @param endpoint [String]
@@ -46,21 +60,6 @@ module OMQ
         end
 
 
-        # Connects to a TCP endpoint.
-        #
-        # @param endpoint [String] e.g. "tcp://127.0.0.1:5555"
-        # @param engine [Engine]
-        # @return [void]
-        #
-        def connect(endpoint, engine)
-          host, port = self.parse_endpoint(endpoint)
-          host       = normalize_connect_host(host)
-          sock       = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
-          apply_buffer_sizes(sock, engine.options)
-          engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
-        end
-
-
         # Normalizes the bind host:
         #   "*"                    → nil (dual-stack wildcard via AI_PASSIVE)
         #   "" / nil / "localhost" → loopback_host (::1 on IPv6-capable hosts, else 127.0.0.1)
@@ -142,6 +141,42 @@ module OMQ
       end
 
 
+      # A TCP dialer — stateful factory for outgoing connections.
+      #
+      # Created once per {Engine#connect}, stored in +@dialers[endpoint]+.
+      # Reconnect calls {#connect} directly — no transport lookup or opts
+      # replay needed.
+      #
+      class Dialer
+        # @return [String] the endpoint this dialer connects to
+        #
+        attr_reader :endpoint
+
+
+        # @param endpoint [String] e.g. "tcp://127.0.0.1:5555"
+        # @param engine [Engine]
+        #
+        def initialize(endpoint, engine)
+          @endpoint = endpoint
+          @engine   = engine
+        end
+
+
+        # Establishes a TCP connection to the endpoint.
+        #
+        # @return [void]
+        #
+        def connect
+          host, port = TCP.parse_endpoint(@endpoint)
+          host       = TCP.normalize_connect_host(host)
+          sock       = ::Socket.tcp(host, port, connect_timeout: TCP.connect_timeout(@engine.options))
+          TCP.apply_buffer_sizes(sock, @engine.options)
+          @engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: @endpoint)
+        end
+
+      end
+
+
       # A bound TCP listener.
       #
       class Listener
@@ -168,7 +203,7 @@ module OMQ
           @servers  = servers
           @port     = port
           @engine   = engine
-          @tasks    = []
+          @barrier  = nil
         end
 
 
@@ -179,10 +214,11 @@ module OMQ
         # @yieldparam io [IO::Stream::Buffered]
         #
         def start_accept_loops(parent_task)
-          @tasks = @servers.map do |server|
-            # TODO: use this server's exact host:port (@endpoint might not be unique)
-            annotation = "tcp accept #{@endpoint}"
-            parent_task.async(transient: true, annotation:) do
+          @barrier = Async::Barrier.new(parent: parent_task)
+
+          @servers.each do |server|
+            annotation = "tcp accept #{server.local_address.inspect_sockaddr}"
+            @barrier.async(transient: true, annotation:) do
               loop do
                 client, _addr = server.accept
                 TCP.apply_buffer_sizes(client, @engine.options)
@@ -207,7 +243,7 @@ module OMQ
         # @return [void]
         #
         def stop
-          @tasks.each(&:stop)
+          @barrier&.stop
           @servers.each { |s| s.close rescue nil }
         end