nnq 0.4.0 → 0.6.0

data/lib/nnq/engine.rb

@@ -35,33 +35,44 @@ 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 [Array<Async::Task>] transient tasks owned by the engine
-    #   (currently just background reconnect loops). Stopped at #close.
-    attr_reader :tasks
-
 
     # @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
 
 
@@ -80,7 +91,6 @@ module NNQ
       @monitor_queue   = nil
       @verbose_monitor = false
       @dialed          = Set.new
-      @tasks           = []
       @routing         = yield(self)
     end
 
@@ -93,32 +103,51 @@ module NNQ
     end
 
 
-    # Emits a verbose-only monitor event. Only forwarded when
-    # {Socket#monitor} was called with +verbose: true+.
-    def emit_verbose_monitor_event(type, **detail)
+    # 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(type, detail: detail)
+      emit_monitor_event(:message_sent, detail: { body: body })
     end
 
 
-    # @return [Routing strategy]
-    attr_reader :routing
+    # 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
 
 
-    def closed? = @lifecycle.closed?
+    # @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
+    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
+    def all_peers_gone
+      @lifecycle.all_peers_gone
+    end
 
 
     # Called by ConnectionLifecycle teardown. Resolves `all_peers_gone`
@@ -129,7 +158,9 @@ module NNQ
 
 
     # @return [Boolean]
-    def reconnect_enabled = @lifecycle.reconnect_enabled
+    def reconnect_enabled
+      @lifecycle.reconnect_enabled
+    end
 
 
     # Disables or re-enables automatic reconnect. nnq has no reconnect
@@ -159,7 +190,7 @@ 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
@@ -175,11 +206,12 @@ module NNQ
     def connect(endpoint)
       @dialed << endpoint
       @last_endpoint = endpoint
+
       if endpoint.start_with?("inproc://")
         transport_for(endpoint).connect(endpoint, self)
       else
         emit_monitor_event(:connect_delayed, endpoint: endpoint)
-        Reconnect.schedule(endpoint, @options, @lifecycle.parent_task, self, delay: 0)
+        Reconnect.schedule(endpoint, @options, @lifecycle.barrier, self, delay: 0)
       end
     end
 
@@ -191,7 +223,7 @@ module NNQ
       return unless endpoint && @dialed.include?(endpoint)
       return unless @lifecycle.alive? && @lifecycle.reconnect_enabled
       return if endpoint.start_with?("inproc://")
-      Reconnect.schedule(endpoint, @options, @lifecycle.parent_task, self)
+      Reconnect.schedule(endpoint, @options, @lifecycle.barrier, self)
     end
 
 
@@ -208,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
@@ -220,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
 
 
@@ -240,17 +276,22 @@ module NNQ
     # to abort with IOError.
     def close
       return unless @lifecycle.alive?
+
       @lifecycle.start_closing!
       @listeners.each(&:stop)
-      @tasks.each { |t| t.stop rescue nil }
-      @tasks.clear
       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?
@@ -268,6 +309,7 @@ module NNQ
 
     private
 
+
     def close_monitor_queue
       return unless @monitor_queue
       @monitor_queue.enqueue(nil)
@@ -277,26 +319,31 @@ module NNQ
     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_monitor_event(:message_received, body: body)
+          emit_verbose_msg_received(body)
           @routing.enqueue(body, conn)
         rescue *CONNECTION_LOST, Async::Stop
           break
         end
-      ensure
-        handle_connection_lost(conn)
       end
     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

@@ -11,6 +11,8 @@ module NNQ
   #   @return [Hash, nil] extra context
   #
   MonitorEvent = Data.define(:type, :endpoint, :detail) do
-    def initialize(type:, endpoint: nil, detail: nil) = super
+    def initialize(type:, endpoint: nil, detail: nil)
+      super
+    end
   end
 end

data/lib/nnq/options.rb

@@ -18,14 +18,23 @@ module NNQ
     attr_accessor :reconnect_interval
     attr_accessor :max_message_size
     attr_accessor :send_hwm
+    attr_accessor :recv_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, recv_hwm: DEFAULT_HWM)
       @linger             = linger
       @read_timeout       = nil
       @write_timeout      = nil
       @reconnect_interval = 0.1
       @max_message_size   = nil
       @send_hwm           = send_hwm
+      @recv_hwm           = recv_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,7 +34,7 @@ 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 do
         if (timeout = @engine.options.read_timeout)
@@ -46,6 +48,7 @@ module NNQ
 
     private
 
+
     def protocol
       Protocol::SP::Protocols::PULL_V0
     end
@@ -55,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

@@ -3,58 +3,106 @@
 require_relative "socket"
 require_relative "routing/req"
 require_relative "routing/rep"
+require_relative "routing/req_raw"
+require_relative "routing/rep_raw"
 
 module NNQ
-  # REQ (nng req0): client side of request/reply. Single in-flight
-  # request per socket. #send_request blocks until the matching reply
-  # comes back.
+  # REQ (nng req0): client side of request/reply. Cooked mode keeps a
+  # single in-flight request and matches replies by id; raw mode bypasses
+  # the state machine entirely and delivers replies as
+  # `[pipe, header, body]` tuples so the app can correlate verbatim.
   #
-  class REQ < Socket
-    # Sends +body+ as a request, blocks until the matching reply
-    # arrives. Returns the reply body (without the id header).
+  class REQ0 < Socket
+    # Cooked: sends +body+ as a request, blocks until the matching reply
+    # arrives. Returns the reply body (without the id header). Raises in
+    # raw mode — use {#send} / {#receive} there.
     def send_request(body)
+      raise Error, "REQ#send_request not available in raw mode" if raw?
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send_request(body) }
     end
 
 
+    # Raw: round-robins +body+ to the next connected peer with
+    # +header+ (typically `[id | 0x80000000].pack("N")`) written
+    # verbatim between the SP length prefix and the body. Raises in
+    # cooked mode.
+    def send(body, header:)
+      raise Error, "REQ#send not available in cooked mode" unless raw?
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send(body, header: header) }
+    end
+
+
+    # Raw: blocks until the next reply arrives, returns
+    # `[pipe, header, body]`. Raises in cooked mode.
+    def receive
+      raise Error, "REQ#receive not available in cooked mode" unless raw?
+      Reactor.run { @engine.routing.receive }
+    end
+
+
     private
 
+
     def protocol
       Protocol::SP::Protocols::REQ_V0
     end
 
 
     def build_routing(engine)
-      Routing::Req.new(engine)
+      raw? ? Routing::ReqRaw.new(engine) : Routing::Req.new(engine)
     end
   end
 
 
-  # REP (nng rep0): server side of request/reply. Strict alternation
-  # of #receive then #send_reply, per request.
+  # REP (nng rep0): server side of request/reply. Cooked mode strictly
+  # alternates #receive / #send_reply and stashes the backtrace
+  # internally; raw mode exposes the backtrace as an opaque +header+ and
+  # the originating pipe as a live Connection, so the app can drive the
+  # reply protocol itself (e.g. proxy/device use cases).
   #
-  class REP < Socket
-    # Blocks until the next request arrives. Returns the request body.
+  class REP0 < Socket
+    # Cooked: returns the next request body. Raw: returns
+    # `[pipe, header, body]`.
     def receive
       Reactor.run { @engine.routing.receive }
     end
 
 
-    # Routes +body+ back to the pipe the most recent #receive came from.
+    # Cooked: routes +body+ back to the pipe the most recent #receive
+    # came from. Raises in raw mode.
     def send_reply(body)
+      raise Error, "REP#send_reply not available in raw mode" if raw?
+      body = frozen_binary(body)
       Reactor.run { @engine.routing.send_reply(body) }
     end
 
 
+    # Raw: writes +body+ with +header+ (the opaque backtrace handed out
+    # by a prior #receive) back to +to+ (the Connection from the same
+    # tuple). Silent drop if +to+ is closed. Raises in cooked mode.
+    def send(body, to:, header:)
+      raise Error, "REP#send not available in cooked mode" unless raw?
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send(body, to: to, header: header) }
+    end
+
+
     private
 
+
     def protocol
       Protocol::SP::Protocols::REP_V0
     end
 
 
     def build_routing(engine)
-      Routing::Rep.new(engine)
+      raw? ? Routing::RepRaw.new(engine) : Routing::Rep.new(engine)
     end
   end
+
+
+  REQ = REQ0
+  REP = REP0
 end

data/lib/nnq/routing/backtrace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NNQ
+  module Routing
+    # Shared backtrace parsing for SP protocols that use the
+    # request-id / hop-stack wire format (REQ/REP, SURVEYOR/RESPONDENT).
+    #
+    # Wire format: one or more 4-byte big-endian words. The terminal
+    # word (request or survey id) has its high bit set (0x80). Preceding
+    # words (hop ids added by devices) have the high bit clear.
+    #
+    module Backtrace
+      MAX_HOPS = 8 # nng's default ttl
+
+      # Reads 4-byte BE words off the front of +body+, stopping at the
+      # first one whose top byte has its high bit set. Returns
+      # [backtrace_bytes, remaining_payload] or nil on malformed input.
+      def parse_backtrace(body)
+        offset = 0
+        hops   = 0
+
+        while hops < MAX_HOPS
+          return nil if body.bytesize - offset < 4
+
+          word    = body.byteslice(offset, 4)
+          offset += 4
+          hops   += 1
+
+          if word.getbyte(0) & 0x80 != 0
+            return [body.byteslice(0, offset), body.byteslice(offset..)]
+          end
+        end
+
+        nil # exceeded TTL without finding terminator
+      end
+
+
+      # Raw-mode TTL check: returns true if +header+ contains at least
+      # MAX_HOPS 4-byte words (i.e. forwarding it would push total hops
+      # over the cap). Cheap: just bytesize arithmetic.
+      def self.too_many_hops?(header)
+        header.bytesize >= MAX_HOPS * 4
+      end
+
+    end
+  end
+end