nnq 0.2.0 → 0.5.0

data/lib/nnq/engine.rb

@@ -2,12 +2,15 @@
 
 require "async"
 require "async/clock"
+require "set"
 require "protocol/sp"
 require_relative "error"
 require_relative "connection"
+require_relative "monitor_event"
 require_relative "reactor"
 require_relative "engine/socket_lifecycle"
 require_relative "engine/connection_lifecycle"
+require_relative "engine/reconnect"
 require_relative "transport/tcp"
 require_relative "transport/ipc"
 require_relative "transport/inproc"
@@ -32,54 +35,153 @@ module NNQ
     # @return [Integer] our SP protocol id (e.g. Protocols::PUSH_V0)
     attr_reader :protocol
 
+
     # @return [Options]
     attr_reader :options
 
+
+    # @return [Routing strategy]
+    attr_reader :routing
+
+
     # @return [Hash{NNQ::Connection => ConnectionLifecycle}]
     attr_reader :connections
 
+
     # @return [SocketLifecycle]
     attr_reader :lifecycle
 
+
     # @return [String, nil]
     attr_reader :last_endpoint
 
+
     # @return [Async::Condition] signaled when a new pipe is registered
     attr_reader :new_pipe
 
 
+    # @return [Set<String>] endpoints we have called #connect on; used
+    #   to decide whether to schedule a reconnect after a connection
+    #   is lost.
+    attr_reader :dialed
+
+
+    # @return [Async::Queue, nil] monitor event queue (set by Socket#monitor)
+    attr_accessor :monitor_queue
+
+
+    # @return [Boolean] when true, {#emit_verbose_monitor_event} forwards
+    #   per-message traces (:message_sent / :message_received) to the
+    #   monitor queue. Set by {Socket#monitor} via its +verbose:+ kwarg.
+    attr_accessor :verbose_monitor
+
+
     # @param protocol [Integer] our SP protocol id (e.g. Protocols::PUSH_V0)
     # @param options [Options]
     # @yieldparam engine [Engine] used by the caller to build a routing
     #   strategy with access to the engine's connection map
     def initialize(protocol:, options:)
-      @protocol      = protocol
-      @options       = options
-      @connections   = {}
-      @listeners     = []
-      @lifecycle     = SocketLifecycle.new
-      @last_endpoint = nil
-      @new_pipe      = Async::Condition.new
-      @routing       = yield(self)
+      @protocol        = protocol
+      @options         = options
+      @connections     = {}
+      @listeners       = []
+      @lifecycle       = SocketLifecycle.new
+      @last_endpoint   = nil
+      @new_pipe        = Async::Condition.new
+      @monitor_queue   = nil
+      @verbose_monitor = false
+      @dialed          = Set.new
+      @routing         = yield(self)
     end
 
 
-    # @return [Routing strategy]
-    attr_reader :routing
+    # Emits a monitor event to the attached queue (if any).
+    def emit_monitor_event(type, endpoint: nil, detail: nil)
+      return unless @monitor_queue
+      @monitor_queue.enqueue(MonitorEvent.new(type: type, endpoint: endpoint, detail: detail))
+    rescue Async::Stop
+    end
+
+
+    # Emits a :message_sent verbose event. Early-returns before
+    # allocating the detail hash so the hot send path pays nothing
+    # when verbose monitoring is off.
+    def emit_verbose_msg_sent(body)
+      return unless @verbose_monitor
+      emit_monitor_event(:message_sent, detail: { body: body })
+    end
+
+
+    # Emits a :message_received verbose event. Same early-return
+    # discipline as {#emit_verbose_msg_sent}.
+    def emit_verbose_msg_received(body)
+      return unless @verbose_monitor
+      emit_monitor_event(:message_received, detail: { body: body })
+    end
 
 
     # @return [Async::Task, nil]
-    def parent_task = @lifecycle.parent_task
+    def parent_task
+      @lifecycle.parent_task
+    end
+
+
+    # @return [Async::Barrier, nil]
+    def barrier
+      @lifecycle.barrier
+    end
+
+
+    def closed?
+      @lifecycle.closed?
+    end
+
+
+    # @return [Async::Promise] resolves with the first connected peer
+    def peer_connected
+      @lifecycle.peer_connected
+    end
+
+
+    # @return [Async::Promise] resolves when all peers have disconnected
+    #   (edge-triggered, after at least one peer connected)
+    def all_peers_gone
+      @lifecycle.all_peers_gone
+    end
 
 
-    def closed? = @lifecycle.closed?
+    # Called by ConnectionLifecycle teardown. Resolves `all_peers_gone`
+    # if the connection set is now empty and we had peers.
+    def resolve_all_peers_gone_if_empty
+      @lifecycle.resolve_all_peers_gone_if_empty(@connections)
+    end
+
+
+    # @return [Boolean]
+    def reconnect_enabled
+      @lifecycle.reconnect_enabled
+    end
+
+
+    # Disables or re-enables automatic reconnect. nnq has no reconnect
+    # loop yet, so this is forward-looking — {TransientMonitor} flips
+    # it before draining.
+    def reconnect_enabled=(value)
+      @lifecycle.reconnect_enabled = value
+    end
+
+
+    # Closes only the recv side. Buffered messages drain, then
+    # {Socket#receive} returns nil. Send side remains operational.
+    def close_read
+      @routing.close_read if @routing.respond_to?(:close_read)
+    end
 
 
     # Stores the parent Async task that long-lived NNQ fibers will
     # attach to. The caller (Socket) is responsible for picking the
     # right one (the user's current task, or Reactor.root_task).
-    def capture_parent_task(task)
-      on_io_thread = task.equal?(Reactor.root_task)
+    def capture_parent_task(task, on_io_thread:)
       @lifecycle.capture_parent_task(task, on_io_thread: on_io_thread)
     end
 
@@ -88,22 +190,48 @@ module NNQ
     def bind(endpoint)
       transport = transport_for(endpoint)
       listener  = transport.bind(endpoint, self)
-      listener.start_accept_loop(@lifecycle.parent_task) do |io, framing = :tcp|
+      listener.start_accept_loop(@lifecycle.barrier) do |io, framing = :tcp|
         handle_accepted(io, endpoint: endpoint, framing: framing)
       end
       @listeners << listener
       @last_endpoint = listener.endpoint
+      emit_monitor_event(:listening, endpoint: @last_endpoint)
     end
 
 
-    # Connects to +endpoint+. Synchronous on first attempt; reconnect
-    # is wired in Phase 1.1.
+    # Connects to +endpoint+. Non-blocking for tcp:// and ipc:// — the
+    # actual dial happens inside a background reconnect task that
+    # retries with exponential back-off until the peer becomes
+    # reachable. Inproc connect is synchronous and instant.
     def connect(endpoint)
-      transport = transport_for(endpoint)
-      transport.connect(endpoint, self)
+      @dialed << endpoint
       @last_endpoint = endpoint
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
-      raise Error, "could not connect to #{endpoint}: #{e.class}: #{e.message}"
+
+      if endpoint.start_with?("inproc://")
+        transport_for(endpoint).connect(endpoint, self)
+      else
+        emit_monitor_event(:connect_delayed, endpoint: endpoint)
+        Reconnect.schedule(endpoint, @options, @lifecycle.barrier, self, delay: 0)
+      end
+    end
+
+
+    # Schedules a reconnect for +endpoint+ if auto-reconnect is enabled
+    # and the endpoint is still in the dialed set. Called from the
+    # connection lifecycle's `lost!` path.
+    def maybe_reconnect(endpoint)
+      return unless endpoint && @dialed.include?(endpoint)
+      return unless @lifecycle.alive? && @lifecycle.reconnect_enabled
+      return if endpoint.start_with?("inproc://")
+      Reconnect.schedule(endpoint, @options, @lifecycle.barrier, self)
+    end
+
+
+    # Public so {Reconnect} can dial directly without re-deriving the
+    # transport from the URL each iteration.
+    def transport_for(endpoint)
+      scheme = endpoint[/\A([a-z+]+):\/\//i, 1] or raise Error, "no scheme: #{endpoint}"
+      TRANSPORTS[scheme] or raise Error, "unsupported transport: #{scheme}"
     end
 
 
@@ -112,6 +240,7 @@ module NNQ
       lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, framing: framing)
       lifecycle.handshake!(io)
       spawn_recv_loop(lifecycle.conn) if @routing.respond_to?(:enqueue) && @connections.key?(lifecycle.conn)
+      lifecycle.start_supervisor!
     rescue ConnectionRejected
       # routing rejected this peer (e.g. PAIR already bonded) — lifecycle cleaned up
     rescue => e
@@ -124,16 +253,19 @@ module NNQ
       lifecycle = ConnectionLifecycle.new(self, endpoint: endpoint, framing: framing)
       lifecycle.handshake!(io)
       spawn_recv_loop(lifecycle.conn) if @routing.respond_to?(:enqueue) && @connections.key?(lifecycle.conn)
+      lifecycle.start_supervisor!
     rescue ConnectionRejected
       # unusual on connect side, but handled identically
     end
 
 
-    # Spawns a task under the socket's parent task. Used by routing
-    # strategies (e.g. PUSH send pump) to attach long-lived fibers to
-    # the engine's lifecycle without going through transient: true.
-    def spawn_task(annotation:, &block)
-      @lifecycle.parent_task.async(annotation: annotation, &block)
+    # Spawns a task under the given parent barrier (defaults to the
+    # socket-level barrier). Used by routing strategies (e.g. PUSH send
+    # pump) to attach long-lived fibers to the engine's lifecycle. The
+    # parent barrier tracks every spawned task so teardown is a single
+    # barrier.stop call.
+    def spawn_task(annotation:, parent: @lifecycle.barrier, &block)
+      parent.async(annotation: annotation, &block)
     end
 
 
@@ -144,15 +276,27 @@ module NNQ
     # to abort with IOError.
     def close
       return unless @lifecycle.alive?
+
       @lifecycle.start_closing!
       @listeners.each(&:stop)
       drain_send_queue(@options.linger)
       @routing.close if @routing.respond_to?(:close)
+
       # Tear down each remaining connection via its lifecycle. The
       # collection mutates during iteration, so snapshot the values.
       @connections.values.each(&:close!)
+
+      # Cascade-cancel every remaining task (reconnect loops, accept
+      # loops, supervisors) in one shot.
+      @lifecycle.barrier&.stop
       @lifecycle.finish_closing!
       @new_pipe.signal
+
+      # Unblock anyone waiting on peer_connected when the socket is
+      # closed before a peer ever arrived.
+      @lifecycle.peer_connected.resolve(nil) unless @lifecycle.peer_connected.resolved?
+      emit_monitor_event(:closed)
+      close_monitor_queue
     end
 
 
@@ -165,34 +309,41 @@ module NNQ
 
     private
 
+
+    def close_monitor_queue
+      return unless @monitor_queue
+      @monitor_queue.enqueue(nil)
+    end
+
+
     def drain_send_queue(timeout)
       return unless @routing.respond_to?(:send_queue_drained?)
       return if @connections.empty?
+
       deadline = timeout ? Async::Clock.now + timeout : nil
+
       until @routing.send_queue_drained?
         break if deadline && (deadline - Async::Clock.now) <= 0
         sleep 0.001
       end
+    rescue Async::Stop
+      # Parent task is being cancelled — stop draining and let close
+      # proceed with the rest of teardown instead of propagating the
+      # cancellation out of the ensure path.
     end
 
 
     def spawn_recv_loop(conn)
-      @lifecycle.parent_task.async(annotation: "nnq recv #{conn.endpoint}") do
+      @connections[conn].barrier.async(annotation: "nnq recv #{conn.endpoint}") do
         loop do
           body = conn.receive_message
+          emit_verbose_msg_received(body)
           @routing.enqueue(body, conn)
-        rescue EOFError, IOError, Errno::ECONNRESET, Async::Stop
+        rescue *CONNECTION_LOST, Async::Stop
           break
         end
-      ensure
-        handle_connection_lost(conn)
       end
     end
 
-
-    def transport_for(endpoint)
-      scheme = endpoint[/\A([a-z+]+):\/\//i, 1] or raise Error, "no scheme: #{endpoint}"
-      TRANSPORTS[scheme] or raise Error, "unsupported transport: #{scheme}"
-    end
   end
 end

data/lib/nnq/error.rb

@@ -1,10 +1,30 @@
 # frozen_string_literal: true
 
 module NNQ
-  class Error           < RuntimeError; end
-  class ClosedError     < Error; end
-  class ProtocolError   < Error; end
-  class TimeoutError    < Error; end
-  class RequestCancelled < Error; end
-  class ConnectionRejected < Error; end
+  class Error < RuntimeError
+  end
+
+
+  class ClosedError < Error
+  end
+
+
+  class ProtocolError < Error
+  end
+
+
+  class TimeoutError < Error
+  end
+
+
+  class RequestCancelled < Error
+  end
+
+
+  class ConnectionRejected < Error
+  end
+
+
+  class TimedOut < Error
+  end
 end

data/lib/nnq/monitor_event.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module NNQ
+  # Lifecycle event emitted by {Socket#monitor}.
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] event type (:listening, :connected, :disconnected, ...)
+  # @!attribute [r] endpoint
+  #   @return [String, nil] the endpoint involved
+  # @!attribute [r] detail
+  #   @return [Hash, nil] extra context
+  #
+  MonitorEvent = Data.define(:type, :endpoint, :detail) do
+    def initialize(type:, endpoint: nil, detail: nil)
+      super
+    end
+  end
+end

data/lib/nnq/options.rb

@@ -18,14 +18,21 @@ module NNQ
     attr_accessor :reconnect_interval
     attr_accessor :max_message_size
     attr_accessor :send_hwm
+    attr_accessor :survey_time
 
-    def initialize(linger: nil, send_hwm: DEFAULT_HWM)
+
+    # @param linger [Numeric] linger period in seconds on close
+    #   (default Float::INFINITY = wait forever, matching libzmq).
+    #   Pass 0 for immediate drop-on-close.
+    def initialize(linger: Float::INFINITY, send_hwm: DEFAULT_HWM)
       @linger             = linger
       @read_timeout       = nil
       @write_timeout      = nil
       @reconnect_interval = 0.1
       @max_message_size   = nil
       @send_hwm           = send_hwm
+      @survey_time        = 1.0
     end
+
   end
 end

data/lib/nnq/pair.rb

@@ -8,8 +8,9 @@ module NNQ
   # peer. First peer to connect wins; subsequent peers are dropped
   # until the current one disconnects. No SP header on the wire.
   #
-  class PAIR < Socket
+  class PAIR0 < Socket
     def send(body)
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 
@@ -21,6 +22,7 @@ module NNQ
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::PAIR_V0
     end
@@ -30,4 +32,7 @@ module NNQ
       Routing::Pair.new(engine)
     end
   end
+
+
+  PAIR = PAIR0
 end

data/lib/nnq/pub_sub.rb

@@ -10,14 +10,16 @@ module NNQ
   # a slow peer drops messages instead of blocking fast peers.
   # Defaults to listening.
   #
-  class PUB < Socket
+  class PUB0 < Socket
     def send(body)
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::PUB_V0
     end
@@ -34,7 +36,7 @@ module NNQ
   # are delivered — matching nng (unlike pre-4.x ZeroMQ). Defaults
   # to dialing.
   #
-  class SUB < Socket
+  class SUB0 < Socket
     # Subscribes to +prefix+. Bytes-level match. The empty string
     # matches everything.
     #
@@ -60,6 +62,7 @@ module NNQ
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::SUB_V0
     end
@@ -69,4 +72,8 @@ module NNQ
       Routing::Sub.new
     end
   end
+
+
+  PUB = PUB0
+  SUB = SUB0
 end

data/lib/nnq/push_pull.rb

@@ -9,14 +9,16 @@ module NNQ
   # bounded send queue (`send_hwm`); per-peer send pumps work-steal from
   # it. Defaults to dialing.
   #
-  class PUSH < Socket
+  class PUSH0 < Socket
     def send(body)
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::PUSH_V0
     end
@@ -32,14 +34,21 @@ module NNQ
   # from all live PUSH peers into one unbounded receive queue. Defaults
   # to listening.
   #
-  class PULL < Socket
+  class PULL0 < Socket
     def receive
-      Reactor.run { @engine.routing.receive }
+      Reactor.run do
+        if (timeout = @engine.options.read_timeout)
+          Fiber.scheduler.with_timeout(timeout) { @engine.routing.receive }
+        else
+          @engine.routing.receive
+        end
+      end
     end
 
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::PULL_V0
     end
@@ -49,4 +58,8 @@ module NNQ
       Routing::Pull.new
     end
   end
+
+
+  PUSH = PUSH0
+  PULL = PULL0
 end

data/lib/nnq/reactor.rb

@@ -22,11 +22,14 @@ module NNQ
     @root_task  = nil
     @work_queue = nil
 
+
     class << self
       def root_task
         return @root_task if @root_task
+
         @mutex.synchronize do
           return @root_task if @root_task
+
           ready       = Thread::Queue.new
           @work_queue = Async::Queue.new
           @thread     = Thread.new { run_reactor(ready) }
@@ -34,6 +37,7 @@ module NNQ
           @root_task  = ready.pop
           at_exit { stop! }
         end
+
         @root_task
       end
 
@@ -42,12 +46,10 @@ module NNQ
         if Async::Task.current?
           yield
         else
-          result = Thread::Queue.new
+          result = Async::Promise.new
           root_task # ensure started
           @work_queue.push([block, result])
-          status, value = result.pop
-          raise value if status == :error
-          value
+          result.wait
         end
       end
 
@@ -61,23 +63,22 @@ module NNQ
         @work_queue = nil
       end
 
+
       private
 
+
       def run_reactor(ready)
         Async do |task|
           ready.push(task)
+
           loop do
-            item = @work_queue.dequeue
-            break if item.nil?
+            item = @work_queue.dequeue or break
             block, result = item
-            task.async do
-              result.push([:ok, block.call])
-            rescue => e
-              result.push([:error, e])
-            end
+            task.async { result.fulfill { block.call } }
           end
         end
       end
+
     end
   end
 end

data/lib/nnq/req_rep.rb

@@ -9,16 +9,18 @@ module NNQ
   # request per socket. #send_request blocks until the matching reply
   # comes back.
   #
-  class REQ < Socket
+  class REQ0 < Socket
     # Sends +body+ as a request, blocks until the matching reply
     # arrives. Returns the reply body (without the id header).
     def send_request(body)
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send_request(body) }
     end
 
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::REQ_V0
     end
@@ -33,7 +35,7 @@ module NNQ
   # REP (nng rep0): server side of request/reply. Strict alternation
   # of #receive then #send_reply, per request.
   #
-  class REP < Socket
+  class REP0 < Socket
     # Blocks until the next request arrives. Returns the request body.
     def receive
       Reactor.run { @engine.routing.receive }
@@ -42,12 +44,14 @@ module NNQ
 
     # Routes +body+ back to the pipe the most recent #receive came from.
     def send_reply(body)
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send_reply(body) }
     end
 
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::REP_V0
     end
@@ -57,4 +61,8 @@ module NNQ
       Routing::Rep.new(engine)
     end
   end
+
+
+  REQ = REQ0
+  REP = REP0
 end