omq 0.22.1 → 0.23.0

data/lib/omq/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "async"
+require "uri"
 require_relative "engine/recv_pump"
 require_relative "engine/heartbeat"
 require_relative "engine/reconnect"
@@ -37,48 +38,25 @@ module OMQ
     attr_reader :options
 
 
-    # @return [Routing] routing strategy (created lazily on first access)
-    #
-    def routing
-      @routing ||= Routing.for(@socket_type).new(self)
-    end
-
-
-    # @return [String, nil] last bound endpoint
+    # @return [Hash{String => Listener}] active listeners keyed by resolved endpoint
     #
-    attr_reader :last_endpoint
+    attr_reader :listeners
 
 
-    # @return [Integer, nil] last auto-selected TCP port
+    # @return [Hash{Connection => ConnectionLifecycle}] active connections
     #
-    attr_reader :last_tcp_port
+    attr_reader :connections
 
 
-    # @param socket_type [Symbol] e.g. :REQ, :REP, :PAIR
-    # @param options [Options]
+    # Optional proc that wraps new connections (e.g. for serialization).
+    # Called with the raw connection; must return the (possibly wrapped) connection.
     #
-    def initialize(socket_type, options)
-      @socket_type     = socket_type
-      @options         = options
-      @routing         = nil
-      @connections     = {} # connection => ConnectionLifecycle
-      @dialed          = Set.new # endpoints we called connect() on (reconnect intent)
-      @listeners       = []
-      @tasks           = []
-      @lifecycle       = SocketLifecycle.new
-      @last_endpoint   = nil
-      @last_tcp_port   = nil
-      @fatal_error     = nil
-      @monitor_queue   = nil
-      @verbose_monitor = false
-    end
+    attr_accessor :connection_wrapper
 
 
-    # @return [Hash{Connection => ConnectionLifecycle}] active connections
-    # @return [Array<Async::Task>] background tasks (pumps, heartbeat, reconnect)
     # @return [SocketLifecycle] socket-level state + signaling
     #
-    attr_reader :connections, :tasks, :lifecycle
+    attr_reader :lifecycle
 
 
     # @!attribute [w] monitor_queue
@@ -92,21 +70,99 @@ module OMQ
     attr_accessor :verbose_monitor
 
 
+    # @return [Routing] routing strategy (created lazily on first access)
+    #
+    def routing
+      @routing ||= Routing.for(@socket_type).new(self)
+    end
+
+
+    # @param socket_type [Symbol] e.g. :REQ, :REP, :PAIR
+    # @param options [Options]
+    #
+    def initialize(socket_type, options)
+      @socket_type     = socket_type
+      @options         = options
+      @routing         = nil
+      @connections     = {} # connection => ConnectionLifecycle
+      @dialers         = {} # endpoint => Dialer (reconnect intent + connect logic)
+      @listeners       = {} # endpoint => Listener
+      @lifecycle       = SocketLifecycle.new
+      @fatal_error     = nil
+      @monitor_queue   = nil
+      @verbose_monitor = false
+    end
+
+
     # Delegated to {SocketLifecycle}.
     def peer_connected    = @lifecycle.peer_connected
     def all_peers_gone    = @lifecycle.all_peers_gone
     def parent_task       = @lifecycle.parent_task
     def barrier           = @lifecycle.barrier
     def closed?           = @lifecycle.closed?
+
+
+    # Enables or disables auto-reconnect for dropped connections.
+    # Delegated to {SocketLifecycle}. Close paths flip this to +false+
+    # so a lost connection doesn't schedule a new retry after linger.
+    #
+    # @param value [Boolean]
+    #
     def reconnect_enabled=(value)
       @lifecycle.reconnect_enabled = value
     end
 
 
-    # Optional proc that wraps new connections (e.g. for serialization).
-    # Called with the raw connection; must return the (possibly wrapped) connection.
+    # Delegated to the routing strategy. Forwards the PUB/XPUB/SUB/XSUB
+    # subscription surface so callers don't have to chain through
+    # `engine.routing`.
     #
-    attr_accessor :connection_wrapper
+    def subscriber_joined
+      routing.subscriber_joined
+    end
+
+
+    # Subscribes to a topic prefix on SUB/XSUB sockets. Delegates to the
+    # routing strategy so callers don't have to chain through
+    # `engine.routing`.
+    #
+    # @param prefix [String]
+    #
+    def subscribe(prefix)
+      routing.subscribe(prefix)
+    end
+
+
+    # Unsubscribes from a topic prefix on SUB/XSUB sockets. Delegates to
+    # the routing strategy so callers don't have to chain through
+    # `engine.routing`.
+    #
+    # @param prefix [String]
+    #
+    def unsubscribe(prefix)
+      routing.unsubscribe(prefix)
+    end
+
+
+    # Records the disconnect reason on the {ConnectionLifecycle} for
+    # +conn+, if any. Called by the recv pump rescue so the upcoming
+    # `:disconnected` monitor event carries an error reason, without
+    # exposing the internal connection map.
+    #
+    def record_disconnect_reason(conn, error)
+      @connections[conn]&.record_disconnect_reason(error)
+    end
+
+
+    # Returns the transport object (Dialer or Listener) for an endpoint.
+    # Used by {ConnectionLifecycle#ready!} to call +#wrap_connection+.
+    #
+    # @param endpoint [String]
+    # @return [Dialer, Listener, nil]
+    #
+    def transport_object_for(endpoint)
+      @dialers[endpoint] || @listeners[endpoint]
+    end
 
 
     # Spawns an inproc reconnect retry task under the socket's parent task.
@@ -119,7 +175,7 @@ module OMQ
       ivl = ri.is_a?(Range) ? ri.begin : ri
       ann = "inproc reconnect #{endpoint}"
 
-      @tasks << @lifecycle.barrier.async(transient: true, annotation: ann) do
+      @lifecycle.barrier.async(transient: true, annotation: ann) do
         yield ivl
       rescue Async::Stop, Async::Cancel
       end
@@ -129,21 +185,20 @@ module OMQ
     # Binds to an endpoint.
     #
     # @param endpoint [String] e.g. "tcp://127.0.0.1:5555", "inproc://foo"
-    # @return [void]
+    # @return [URI::Generic] resolved endpoint URI (with auto-selected port for "tcp://host:0")
     # @raise [ArgumentError] on unsupported transport
     #
-    def bind(endpoint, parent: nil)
+    def bind(endpoint, parent: nil, **opts)
       OMQ.freeze_for_ractors!
       capture_parent_task(parent: parent)
       transport = transport_for(endpoint)
-      listener  = transport.bind(endpoint, self)
+      listener  = transport.listener(endpoint, self, **opts)
 
       start_accept_loops(listener)
 
-      @listeners << listener
-      @last_endpoint = listener.endpoint
-      @last_tcp_port = listener.respond_to?(:port) ? listener.port : nil
+      @listeners[listener.endpoint] = listener
       emit_monitor_event(:listening, endpoint: listener.endpoint)
+      URI.parse(listener.endpoint)
     rescue => error
       emit_monitor_event(:bind_failed, endpoint: endpoint, detail: { error: error })
       raise
@@ -153,23 +208,26 @@ module OMQ
     # Connects to an endpoint.
     #
     # @param endpoint [String]
-    # @return [void]
+    # @return [URI::Generic] parsed endpoint URI
     #
-    def connect(endpoint, parent: nil)
+    def connect(endpoint, parent: nil, **opts)
       OMQ.freeze_for_ractors!
       capture_parent_task(parent: parent)
       validate_endpoint!(endpoint)
-      @dialed.add(endpoint)
 
       if endpoint.start_with?("inproc://")
-        # Inproc connect is synchronous and instant
+        # Inproc connect is synchronous and instant — no Dialer
         transport = transport_for(endpoint)
-        transport.connect(endpoint, self)
+        transport.connect(endpoint, self, **opts)
+        @dialers[endpoint] = :inproc  # sentinel for reconnect intent
       else
-        # TCP/IPC connect in background — never blocks the caller
+        transport = transport_for(endpoint)
+        @dialers[endpoint] = transport.dialer(endpoint, self, **opts)
         emit_monitor_event(:connect_delayed, endpoint: endpoint)
         schedule_reconnect(endpoint, delay: 0)
       end
+
+      URI.parse(endpoint)
     end
 
 
@@ -180,7 +238,7 @@ module OMQ
     # @return [void]
     #
     def disconnect(endpoint)
-      @dialed.delete(endpoint)
+      @dialers.delete(endpoint)
       close_connections_at(endpoint)
     end
 
@@ -192,11 +250,9 @@ module OMQ
     # @return [void]
     #
     def unbind(endpoint)
-      listener = @listeners.find { |l| l.endpoint == endpoint }
-      return unless listener
+      listener = @listeners.delete(endpoint) or return
 
       listener.stop
-      @listeners.delete(listener)
       close_connections_at(endpoint)
     end
 
@@ -282,10 +338,8 @@ module OMQ
       # torn down together with the rest of its sibling per-connection
       # pumps when the connection is lost.
       parent = @connections[conn]&.barrier || @lifecycle.barrier
-      task   = RecvPump.start(parent, conn, recv_queue, self, transform)
 
-      @tasks << task if task
-      task
+      RecvPump.start(parent, conn, recv_queue, self, transform)
     end
 
 
@@ -302,8 +356,8 @@ module OMQ
     # Resolves `all_peers_gone` if we had peers and now have none.
     # Called by ConnectionLifecycle during teardown.
     #
-    def resolve_all_peers_gone_if_empty
-      @lifecycle.resolve_all_peers_gone_if_empty(@connections)
+    def maybe_resolve_all_peers_gone
+      @lifecycle.maybe_resolve_all_peers_gone(@connections)
     end
 
 
@@ -311,9 +365,12 @@ module OMQ
     # and the endpoint is still dialed.
     #
     def maybe_reconnect(endpoint)
-      return unless endpoint && @dialed.include?(endpoint)
+      return unless endpoint && @dialers.key?(endpoint)
       return unless @lifecycle.open? && @lifecycle.reconnect_enabled
-      Reconnect.schedule(endpoint, @options, @lifecycle.parent_task, self)
+
+      dialer = @dialers[endpoint]
+
+      Reconnect.schedule(dialer, @options, @lifecycle.parent_task, self)
     end
 
 
@@ -342,7 +399,6 @@ module OMQ
 
       stop_listeners
       tear_down_barrier
-      routing.stop rescue nil
       emit_monitor_event(:closed)
       close_monitor_queue
     end
@@ -357,8 +413,7 @@ module OMQ
     def stop
       return unless @lifecycle.alive?
 
-      @lifecycle.start_closing! if @lifecycle.open?
-      @lifecycle.finish_closing!
+      @lifecycle.force_close!
 
       if @lifecycle.on_io_thread
         Reactor.untrack_linger(@options.linger)
@@ -366,7 +421,6 @@ module OMQ
 
       stop_listeners
       tear_down_barrier
-      routing.stop rescue nil
       emit_monitor_event(:closed)
       close_monitor_queue
     end
@@ -379,11 +433,16 @@ module OMQ
     # see the real error instead of deadlocking.
     #
     # @param annotation [String] task annotation for debugging
+    # @param parent [Async::Task, Async::Barrier] parent for the spawned
+    #   task. Defaults to the current task. Routing strategies that own
+    #   loose pump tasks (Radio, Channel) pass their own +Async::Barrier+
+    #   so a single +barrier.stop+ tears the lot down at strategy
+    #   shutdown without per-task bookkeeping.
     # @yield the pump loop body
     # @return [Async::Task]
     #
-    def spawn_pump_task(annotation:, &block)
-      Async::Task.current.async(transient: true, annotation: annotation) do
+    def spawn_pump_task(annotation:, parent: Async::Task.current, &block)
+      parent.async(transient: true, annotation: annotation) do
         yield
       rescue Async::Stop, Async::Cancel, Protocol::ZMTP::Error, *CONNECTION_LOST
         # normal shutdown / expected disconnect
@@ -406,7 +465,10 @@ module OMQ
     #
     def spawn_conn_pump_task(conn, annotation:, &block)
       lifecycle = @connections[conn]
-      return spawn_pump_task(annotation: annotation, &block) unless lifecycle
+
+      unless lifecycle
+        return spawn_pump_task(annotation: annotation, &block)
+      end
 
       lifecycle.barrier.async(transient: true, annotation: annotation) do
         yield
@@ -471,7 +533,7 @@ module OMQ
 
       return unless task
 
-      Maintenance.start(@lifecycle.barrier, @options.mechanism, @tasks)
+      Maintenance.start(@lifecycle.barrier, @options.mechanism)
     end
 
 
@@ -484,7 +546,10 @@ module OMQ
     #
     def emit_monitor_event(type, endpoint: nil, detail: nil)
       return unless @monitor_queue
-      @monitor_queue.push(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
+
+      event = MonitorEvent.new type: type, endpoint: endpoint, detail: detail
+
+      @monitor_queue << event
     rescue Async::Stop, ClosedQueueError
     end
 
@@ -508,9 +573,14 @@ module OMQ
     # +last_wire_size_out+ (installed by ZMTP-Zstd etc.).
     def emit_verbose_msg_sent(conn, parts)
       return unless @verbose_monitor
+
       detail = { parts: parts }
-      detail[:wire_size] = conn.last_wire_size_out if conn.respond_to?(:last_wire_size_out)
-      emit_monitor_event(:message_sent, detail: detail)
+
+      if conn.respond_to? :last_wire_size_out
+        detail[:wire_size] = conn.last_wire_size_out
+      end
+
+      emit_monitor_event :message_sent, detail: detail
     end
 
 
@@ -522,11 +592,11 @@ module OMQ
 
       detail = { parts: parts }
 
-      if conn.respond_to?(:last_wire_size_in)
+      if conn.respond_to? :last_wire_size_in
         detail[:wire_size] = conn.last_wire_size_in
       end
 
-      emit_monitor_event(:message_received, detail: detail)
+      emit_monitor_event :message_received, detail: detail
     end
 
 
@@ -551,8 +621,18 @@ module OMQ
     private
 
 
+    # Spawns a per-connection task on the socket-level barrier that runs
+    # the handshake and then blocks on +done+ until the connection is
+    # torn down. The +ensure+ path runs {ConnectionLifecycle#close!} so
+    # side effects (routing removal, monitor event, reconnect) always
+    # fire exactly once, regardless of how the task unwinds.
+    #
+    # @param io [#read, #write, #close] accepted or dialed socket
+    # @param as_server [Boolean] true for accepted connections
+    # @param endpoint [String, nil] the endpoint URI, for monitor events
+    #
     def spawn_connection(io, as_server:, endpoint: nil)
-      task = @lifecycle.barrier&.async(transient: true, annotation: "conn #{endpoint}") do
+      @lifecycle.barrier&.async(transient: true, annotation: "conn #{endpoint}") do
         done      = Async::Promise.new
         lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, done: done)
         lifecycle.handshake!(io, as_server: as_server)
@@ -566,16 +646,21 @@ module OMQ
       ensure
         lifecycle&.close!
       end
-
-      @tasks << task if task
     end
 
 
+    # Blocks until the routing strategy reports all send queues drained
+    # or +timeout+ seconds have elapsed. Called from the linger path on
+    # close so pending outgoing messages get a chance to flush.
+    #
+    # @param timeout [Numeric, nil] max seconds to wait; nil = no limit
+    #
     # TODO: replace the 1 ms busy-poll with a promise/condition that
     # the send pump resolves when its queue hits empty. The loop exists
     # because there is currently no signal for "send queue fully
     # drained"; fixing it cleanly requires plumbing a notifier through
     # every routing strategy, so it is flagged rather than fixed here.
+    #
     def drain_send_queues(timeout)
       return unless @routing.respond_to?(:send_queues_drained?)
 
@@ -594,11 +679,26 @@ module OMQ
     end
 
 
+    # Schedules a reconnect attempt for +endpoint+ using its dialer.
+    # Called on initial connect (with +delay: 0+) and after a lost
+    # connection (with the dialer's backoff delay).
+    #
+    # @param endpoint [String]
+    # @param delay [Numeric, nil] initial delay override in seconds
+    #
     def schedule_reconnect(endpoint, delay: nil)
-      Reconnect.schedule(endpoint, @options, @lifecycle.parent_task, self, delay: delay)
+      dialer = @dialers[endpoint]
+      Reconnect.schedule(dialer, @options, @lifecycle.parent_task, self, delay: delay)
     end
 
 
+    # Delegates endpoint validation to the transport if it defines one.
+    # Called from {#connect} so a bad URI fails fast instead of landing
+    # in a reconnect loop.
+    #
+    # @param endpoint [String]
+    # @raise [ArgumentError] if the transport rejects the endpoint
+    #
     def validate_endpoint!(endpoint)
       transport = transport_for(endpoint)
 
@@ -608,6 +708,11 @@ module OMQ
     end
 
 
+    # Starts the listener's accept loops on the socket-level barrier
+    # and routes accepted IOs through {#handle_accepted}.
+    #
+    # @param listener [#start_accept_loops, #endpoint]
+    #
     def start_accept_loops(listener)
       return unless listener.respond_to?(:start_accept_loops)
 
@@ -617,12 +722,21 @@ module OMQ
     end
 
 
+    # Stops every active listener and clears the registry. Called from
+    # close paths; connection teardown is handled separately via the
+    # socket-level barrier.
+    #
     def stop_listeners
-      @listeners.each(&:stop)
+      @listeners.each_value(&:stop)
       @listeners.clear
     end
 
 
+    # Closes all connections currently bound to or connected from
+    # +endpoint+. Used by {#disconnect} and {#unbind}.
+    #
+    # @param endpoint [String]
+    #
     def close_connections_at(endpoint)
       @connections.values.select { |lc| lc.endpoint == endpoint }.each(&:close!)
     end
@@ -631,24 +745,21 @@ module OMQ
     # Cascades teardown through the socket-level barrier. Stopping the
     # barrier cancels every tracked task: connection supervisors (whose
     # `ensure lost!` runs the ordered disconnect side effects), accept
-    # loops, reconnect loops, heartbeat, maintenance. After the cascade,
-    # clears the legacy +@tasks+ list.
+    # loops, heartbeat, maintenance. Reconnect loops live on the user's
+    # parent task and self-exit via `@engine.closed?`.
     #
     def tear_down_barrier
       @lifecycle.barrier&.stop
-      @tasks.clear
     end
 
 
+    # Signals end-of-stream on the monitor queue (if any) by pushing a
+    # +nil+ sentinel, so consumers iterating with {Socket#each_event}
+    # can exit cleanly.
+    #
     def close_monitor_queue
       return unless @monitor_queue
       @monitor_queue.push(nil)
     end
   end
-
-
-  # Register built-in transports.
-  Engine.transports["tcp"]    = Transport::TCP
-  Engine.transports["ipc"]    = Transport::IPC
-  Engine.transports["inproc"] = Transport::Inproc
 end

data/lib/omq/peer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# OMQ PEER socket type (ZeroMQ RFC 51).
+#
+# Not loaded by +require "omq"+; opt in with:
+#
+#   require "omq/peer"
+
+require "omq"
+require_relative "routing/peer"
+
+module OMQ
+  # Bidirectional multi-peer socket with routing IDs (ZeroMQ RFC 51).
+  #
+  # Each connected peer is assigned a 4-byte routing ID. Supports
+  # directed sends via #send_to and fair-queued receives.
+  class PEER < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new PEER 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 backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: Float::INFINITY, backend: nil)
+      init_engine(:PEER, backend: backend)
+      @options.linger = linger
+      attach_endpoints(endpoints, default: :connect)
+    end
+
+
+    # Sends a message to a specific peer by routing ID.
+    #
+    # @param routing_id [String] 4-byte routing ID
+    # @param message [String] message body
+    # @return [self]
+    #
+    def send_to(routing_id, message)
+      parts = [routing_id.b.freeze, message.b.freeze]
+      Reactor.run(timeout: @options.write_timeout) { @engine.enqueue_send(parts) }
+      self
+    end
+  end
+
+
+  Routing.register(:PEER, Routing::Peer)
+end

data/lib/omq/pub_sub.rb

@@ -61,7 +61,7 @@ module OMQ
     # @return [void]
     #
     def subscribe(prefix = EVERYTHING)
-      @engine.routing.subscribe(prefix)
+      @engine.subscribe(prefix)
     end
 
 
@@ -71,7 +71,7 @@ module OMQ
     # @return [void]
     #
     def unsubscribe(prefix)
-      @engine.routing.unsubscribe(prefix)
+      @engine.unsubscribe(prefix)
     end
 
   end