nnq 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68a6dd62dc097b93740827c44f95bbfa983d5c7d6072b4625257bd2350ba23fe
-  data.tar.gz: 376c1ef08eda16a8950ae703d1798256c8c5ba720cd1e5d0e988f1a87067c093
+  metadata.gz: 19bceda0339689e8850efe39120590002821f5c859eaf33e4ea1065af317bcaa
+  data.tar.gz: 2a15dd79b5cf4f8a41c564e89cf40af7296de8765e8e070de12057b4bc0dedf9
 SHA512:
-  metadata.gz: f88c29c241ea5922930342a11c00181007cf698045b219c6e7cc111d2563e37e7e56c64efbb61b48efa608eaa6ab3e7104bc33983c6202410f1745a50a082012
-  data.tar.gz: e1e42983059b5a280495216a08b6e6ac6a9e6eff9385a2093ad62b9ac7698a80d24a2f36f14c4f4f9579962b7fde9c83a042f04e1819e5963ba2ae94b5cbed4f
+  metadata.gz: 1e14a21e6d620df7770c27868f5fdb8ed945fb04137b8817c12fdaa2fdfca1e36a952e6fc4afc5be60562dfd1ff8f43d9d1781ce9a4fb6a1c3a8963cd3738233
+  data.tar.gz: 13aae01f03df0b0eca53aa0329d0f2d35b036b4f52744f83033cc46297eae39a60b2c639ad144c9ee3af63cee7d3780c3fff036d30f418e078ccb89253f70761

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.6.1 — 2026-04-15
+
+- **Verbose trace (`-vvv`) now fires for cooked REQ/REP/RESPONDENT
+  sends.** Cooked `Req#send_request`, `Rep#send_reply`, and
+  `Respondent#send_reply` bypass `send_pump` and write to the
+  connection directly, so they were never emitting `:message_sent`
+  monitor events — `-vvv` only ever showed the `<<` recv side. Each
+  now calls `emit_verbose_msg_sent(body)` after the write. Raw
+  REQ/REP/RESPONDENT sends get the same treatment (raw surveyor
+  already emitted via its per-peer send pump).
+- **Verbose recv previews strip the SP backtrace header.** The recv
+  loop used to emit the raw wire body, so `-vvv` traces for
+  REQ/REP/SURVEYOR/RESPONDENT showed the 4-byte request/survey id
+  (or a multi-word backtrace stack) in front of the payload. Routing
+  strategies now expose an optional `preview_body(wire)` hook; the
+  engine calls it before emitting `:message_received` so the trace
+  shows just the payload.
+- **`Engine#close` drains the monitor queue before cancelling
+  tasks.** The monitor consumer fiber lives under the socket-level
+  barrier, so `barrier.stop` used to `Async::Stop` it before it had
+  a chance to drain trailing events. `close` now emits `:closed`,
+  enqueues the nil sentinel, and awaits the stored `monitor_task`
+  before stopping the barrier. Fixes flaky `-vvv` traces on
+  short-lived sockets where the last `:message_received` event
+  would occasionally be lost.
+
+## 0.6.0 — 2026-04-15
+
+- **NNG-style raw mode for REQ/REP and SURVEYOR/RESPONDENT.** Constructing
+  any of the four with `raw: true` bypasses the cooked state machine
+  (request-id tracking, pending-reply slot, survey window) and exposes
+  the full SP backtrace header as an opaque, caller-supplied handle.
+  - `#receive` returns `[pipe, header, body]` where `pipe` is the live
+    `NNQ::Connection` that delivered the message (idiomatic Ruby handle
+    — no opaque pipe_id token, no lookup registry), `header` is the
+    parsed backtrace bytes, and `body` is the payload.
+  - Raw REQ/SURVEYOR send: `send(body, header:)` — fans round-robin /
+    fans out.
+  - Raw REP/RESPONDENT send: `send(body, to:, header:)` — routes
+    directly to a prior `pipe` with the stored `header` written
+    verbatim, so the cooked peer matches the reply. Closed peer or
+    over-TTL header → silent drop (matches NNG behavior).
+  - Cooked-mode methods (`send_request`, `send_reply`, `send_survey`)
+    raise `NNQ::Error` in raw mode and vice versa.
+  - Unblocks proxy/device-style use cases (forwarders, request routers)
+    without touching the cooked code paths. `lib/nnq/routing/{req,rep,
+    surveyor,respondent}_raw.rb` live alongside their cooked siblings;
+    `build_routing` branches on `@raw` inside REQ0/REP0/SURVEYOR0/
+    RESPONDENT0. PUB/SUB and PUSH/PULL raw are still out of scope.
+- **Zero-alloc cooked send paths via protocol-sp `header:` kwarg.**
+  `Connection#send_message` / `#write_message` grow an optional
+  `header:` kwarg that protocol-sp writes between the SP length prefix
+  and the body as a third buffered write (coalesced into a single
+  `writev`). Cooked `Req#send_request`, `Rep#send_reply`, and
+  `Respondent#send_reply` no longer allocate the `header + body`
+  intermediate String on every send — the savings apply to every
+  REQ/REP round trip regardless of whether raw mode is used.
+  Requires `protocol-sp >= 0.3`.
+- **`Options#recv_hwm`** — new option, defaults to `Options::DEFAULT_HWM`
+  (same as `send_hwm`). Bounds the raw routing strategies' receive
+  queues; the cooked paths still use their existing (unbounded) state
+  and are unaffected.
+
 ## 0.5.0 — 2026-04-15
 
 - **Send-path freezes the body** — every public send method (PUSH,

data/lib/nnq/connection.rb

@@ -35,10 +35,12 @@ module NNQ
     # Writes one message into the SP connection's send buffer (no flush).
     #
     # @param body [String]
+    # @param header [String, nil] optional binary prefix written between
+    #   the SP length prefix and body (see Protocol::SP::Connection)
     # @return [void]
-    def write_message(body)
+    def write_message(body, header: nil)
       raise ClosedError, "connection closed" if @closed
-      @sp.write_message(body)
+      @sp.write_message(body, header: header)
     end
 
 
@@ -57,10 +59,11 @@ module NNQ
     # each call is request-paced and there's nothing to batch.
     #
     # @param body [String]
+    # @param header [String, nil] optional binary prefix
     # @return [void]
-    def send_message(body)
+    def send_message(body, header: nil)
       raise ClosedError, "connection closed" if @closed
-      @sp.send_message(body)
+      @sp.send_message(body, header: header)
     end
 
 

data/lib/nnq/engine.rb

@@ -70,6 +70,10 @@ module NNQ
     attr_accessor :monitor_queue
 
 
+    # @return [Async::Task, nil] the monitor consumer task, if any
+    attr_accessor :monitor_task
+
+
     # @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.
@@ -286,6 +290,15 @@ module NNQ
       # collection mutates during iteration, so snapshot the values.
       @connections.values.each(&:close!)
 
+      # Emit :closed, seal the monitor queue, and wait for the monitor
+      # fiber to drain it before cancelling tasks. Without this join,
+      # trailing :message_received events that the recv pump enqueued
+      # just before close would be lost when the barrier.stop below
+      # Async::Stops the monitor fiber mid-dequeue.
+      emit_monitor_event(:closed)
+      close_monitor_queue
+      @monitor_task&.wait
+
       # Cascade-cancel every remaining task (reconnect loops, accept
       # loops, supervisors) in one shot.
       @lifecycle.barrier&.stop
@@ -295,8 +308,6 @@ module NNQ
       # 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
 
 
@@ -337,7 +348,10 @@ module NNQ
       @connections[conn].barrier.async(annotation: "nnq recv #{conn.endpoint}") do
         loop do
           body = conn.receive_message
-          emit_verbose_msg_received(body)
+          if @verbose_monitor
+            preview = @routing.respond_to?(:preview_body) ? @routing.preview_body(body) : body
+            emit_verbose_msg_received(preview)
+          end
           @routing.enqueue(body, conn)
         rescue *CONNECTION_LOST, Async::Stop
           break

data/lib/nnq/options.rb

@@ -18,19 +18,21 @@ module NNQ
     attr_accessor :reconnect_interval
     attr_accessor :max_message_size
     attr_accessor :send_hwm
+    attr_accessor :recv_hwm
     attr_accessor :survey_time
 
 
     # @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)
+    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
 

data/lib/nnq/req_rep.rb

@@ -3,21 +3,45 @@
 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 REQ0 < Socket
-    # Sends +body+ as a request, blocks until the matching reply
-    # arrives. Returns the reply body (without the id header).
+    # 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
 
 
@@ -27,28 +51,44 @@ module NNQ
 
 
     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 REP0 < Socket
-    # Blocks until the next request arrives. Returns the request body.
+    # 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
 
 
@@ -58,7 +98,7 @@ module NNQ
 
 
     def build_routing(engine)
-      Routing::Rep.new(engine)
+      raw? ? Routing::RepRaw.new(engine) : Routing::Rep.new(engine)
     end
   end
 

data/lib/nnq/routing/backtrace.rb

@@ -34,6 +34,14 @@ module NNQ
         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

data/lib/nnq/routing/rep.rb

@@ -69,7 +69,15 @@ module NNQ
         end
 
         return if conn.closed?
-        conn.send_message(btrace + body)
+        conn.send_message(body, header: btrace)
+        @engine.emit_verbose_msg_sent(body)
+      end
+
+
+      # Strips the backtrace header for verbose trace previews.
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
       end
 
 

data/lib/nnq/routing/rep_raw.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "async/limited_queue"
+require_relative "backtrace"
+
+module NNQ
+  module Routing
+    # Raw REP: bypasses the cooked state machine. The incoming
+    # backtrace header is split off once at parse time and handed to
+    # the caller alongside the live Connection as `[pipe, header, body]`.
+    # Replies go back via `send(body, to:, header:)` which writes the
+    # caller-supplied header verbatim — no cooked pending/echo logic,
+    # no single-in-flight constraint.
+    #
+    class RepRaw
+      include Backtrace
+
+
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+      end
+
+
+      # @return [Array, nil] [pipe, header, body] or nil on close
+      def receive
+        @recv_queue.dequeue
+      end
+
+
+      # Sends +body+ with the caller-supplied +header+ back to +to+
+      # (a Connection handed out by a prior #receive). Silent drop
+      # if the target is closed or the header would push total hops
+      # over MAX_HOPS.
+      def send(body, to:, header:)
+        return if to.closed?
+        return if Backtrace.too_many_hops?(header)
+        to.send_message(body, header: header)
+        @engine.emit_verbose_msg_sent(body)
+      rescue ClosedError
+        # peer went away between receive and send — drop
+      end
+
+
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
+      end
+
+
+      # Called by the engine recv loop.
+      def enqueue(wire_bytes, conn)
+        header, payload = parse_backtrace(wire_bytes)
+        return unless header # malformed / over-TTL — drop
+        @recv_queue.enqueue([conn, header, payload])
+      end
+
+
+      def close
+        @recv_queue.enqueue(nil)
+      end
+
+
+      def close_read
+        @recv_queue.enqueue(nil)
+      end
+
+    end
+  end
+end

data/lib/nnq/routing/req.rb

@@ -55,7 +55,8 @@ module NNQ
 
         conn   = pick_peer
         header = [id].pack("N")
-        conn.send_message(header + body)
+        conn.send_message(body, header: header)
+        @engine.emit_verbose_msg_sent(body)
         promise.wait
       ensure
         @mutex.synchronize do
@@ -81,6 +82,12 @@ module NNQ
       end
 
 
+      # Strips the 4-byte request id for verbose trace previews.
+      def preview_body(wire)
+        wire.byteslice(4..) || wire
+      end
+
+
       def close
         @mutex.synchronize do
           @outstanding&.last&.reject(NNQ::Error.new("REQ socket closed"))

data/lib/nnq/routing/req_raw.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "async/limited_queue"
+require_relative "backtrace"
+
+module NNQ
+  module Routing
+    # Raw REQ: bypasses the cooked single-in-flight request-id
+    # state machine. Sends are fire-and-forget round-robin with a
+    # caller-supplied header (typically `[id | 0x80000000].pack("N")`);
+    # replies land in a bounded queue and are delivered as
+    # `[pipe, header, body]` tuples so the app can correlate by
+    # header verbatim without ever parsing or slicing bytes.
+    #
+    class ReqRaw
+      include Backtrace
+
+
+      def initialize(engine)
+        @engine     = engine
+        @next_idx   = 0
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+      end
+
+
+      def send(body, header:)
+        conn = pick_peer
+        conn.send_message(body, header: header)
+        @engine.emit_verbose_msg_sent(body)
+      end
+
+
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
+      end
+
+
+      def receive
+        @recv_queue.dequeue
+      end
+
+
+      def enqueue(wire_bytes, conn)
+        header, payload = parse_backtrace(wire_bytes)
+        return unless header
+        @recv_queue.enqueue([conn, header, payload])
+      end
+
+
+      def close
+        @recv_queue.enqueue(nil)
+      end
+
+
+      def close_read
+        @recv_queue.enqueue(nil)
+      end
+
+
+      private
+
+
+      def pick_peer
+        loop do
+          conns = @engine.connections.keys
+
+          if conns.empty?
+            @engine.new_pipe.wait
+            next
+          end
+
+          @next_idx = (@next_idx + 1) % conns.size
+          return conns[@next_idx]
+        end
+      end
+
+    end
+  end
+end

data/lib/nnq/routing/respondent.rb

@@ -51,7 +51,15 @@ module NNQ
         end
 
         return if conn.closed?
-        conn.send_message(btrace + body)
+        conn.send_message(body, header: btrace)
+        @engine.emit_verbose_msg_sent(body)
+      end
+
+
+      # Strips the backtrace header for verbose trace previews.
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
       end
 
 

data/lib/nnq/routing/respondent_raw.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "async/limited_queue"
+require_relative "backtrace"
+
+module NNQ
+  module Routing
+    # Raw RESPONDENT: mirror of {RepRaw} for the survey pattern.
+    # No survey-window state, no pending slot — the app receives
+    # `[pipe, header, body]` tuples and chooses whether (and when)
+    # to reply via `send(body, to:, header:)`.
+    #
+    class RespondentRaw
+      include Backtrace
+
+
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+      end
+
+
+      def receive
+        @recv_queue.dequeue
+      end
+
+
+      def send(body, to:, header:)
+        return if to.closed?
+        return if Backtrace.too_many_hops?(header)
+        to.send_message(body, header: header)
+        @engine.emit_verbose_msg_sent(body)
+      rescue ClosedError
+      end
+
+
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
+      end
+
+
+      def enqueue(wire_bytes, conn)
+        header, payload = parse_backtrace(wire_bytes)
+        return unless header
+        @recv_queue.enqueue([conn, header, payload])
+      end
+
+
+      def close
+        @recv_queue.enqueue(nil)
+      end
+
+
+      def close_read
+        @recv_queue.enqueue(nil)
+      end
+
+    end
+  end
+end

data/lib/nnq/routing/surveyor.rb

@@ -78,6 +78,12 @@ module NNQ
       end
 
 
+      # Strips the 4-byte survey id for verbose trace previews.
+      def preview_body(wire)
+        wire.byteslice(4..) || wire
+      end
+
+
       def connection_added(conn)
         queue             = Async::LimitedQueue.new(@engine.options.send_hwm)
         @queues[conn]     = queue

data/lib/nnq/routing/surveyor_raw.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/limited_queue"
+require_relative "backtrace"
+
+module NNQ
+  module Routing
+    # Raw SURVEYOR: fans out surveys to all peers like cooked
+    # {Surveyor}, but without a survey window, survey-id matching,
+    # or timeout. Replies are delivered as `[pipe, header, body]`
+    # tuples so the app can correlate by header verbatim.
+    #
+    # Each per-conn send queue holds `[header, body]` pairs and the
+    # pump calls `conn.write_message(body, header: header)` so the
+    # protocol-sp header kwarg is threaded through the fan-out —
+    # zero concat even on the broadcast path.
+    #
+    class SurveyorRaw
+      include Backtrace
+
+
+      def initialize(engine)
+        @engine     = engine
+        @queues     = {} # conn => Async::LimitedQueue
+        @pump_tasks = {} # conn => Async::Task
+        @recv_queue = Async::LimitedQueue.new(engine.options.recv_hwm)
+      end
+
+
+      def send(body, header:)
+        @queues.each_value do |q|
+          q.enqueue([header, body]) unless q.limited?
+        end
+      end
+
+
+      def receive
+        @recv_queue.dequeue
+      end
+
+
+      def enqueue(wire_bytes, conn)
+        header, payload = parse_backtrace(wire_bytes)
+        return unless header
+        @recv_queue.enqueue([conn, header, payload])
+      end
+
+
+      def preview_body(wire)
+        _, payload = parse_backtrace(wire)
+        payload || wire
+      end
+
+
+      def connection_added(conn)
+        queue             = Async::LimitedQueue.new(@engine.options.send_hwm)
+        @queues[conn]     = queue
+        @pump_tasks[conn] = spawn_pump(conn, queue)
+      end
+
+
+      def connection_removed(conn)
+        @queues.delete(conn)
+        task = @pump_tasks.delete(conn)
+
+        return unless task
+        return if task == Async::Task.current
+
+        task.stop
+      rescue IOError, Errno::EPIPE
+      end
+
+
+      def send_queue_drained?
+        @queues.each_value.all? { |q| q.empty? }
+      end
+
+
+      def close
+        @pump_tasks.each_value(&:stop)
+        @pump_tasks.clear
+        @queues.clear
+        @recv_queue.enqueue(nil)
+      end
+
+
+      def close_read
+        @recv_queue.enqueue(nil)
+      end
+
+
+      private
+
+
+      def spawn_pump(conn, queue)
+        annotation = "nnq surveyor_raw pump #{conn.endpoint}"
+        parent     = @engine.connections[conn]&.barrier || @engine.barrier
+
+        @engine.spawn_task(annotation:, parent:) do
+          loop do
+            header, body = queue.dequeue
+            conn.send_message(body, header: header)
+            @engine.emit_verbose_msg_sent(body)
+          rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
+            break
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/nnq/socket.rb

@@ -32,9 +32,9 @@ module NNQ
 
     # @yieldparam [self] the socket; when a block is passed the socket
     #   is {#close}d when the block returns (or raises), File.open-style.
-    def initialize(raw: false, linger: Float::INFINITY, send_hwm: Options::DEFAULT_HWM)
+    def initialize(raw: false, linger: Float::INFINITY, send_hwm: Options::DEFAULT_HWM, recv_hwm: Options::DEFAULT_HWM)
       @raw     = raw
-      @options = Options.new(linger: linger, send_hwm: send_hwm)
+      @options = Options.new(linger: linger, send_hwm: send_hwm, recv_hwm: recv_hwm)
       @engine  = Engine.new(protocol: protocol, options: @options) { |engine| build_routing(engine) }
 
       begin
@@ -126,13 +126,14 @@ module NNQ
       @engine.verbose_monitor = verbose
 
       Reactor.run do
-        @engine.spawn_task(annotation: "nnq monitor") do
+        @engine.monitor_task = @engine.spawn_task(annotation: "nnq monitor") do
           while (event = queue.dequeue)
             block.call(event)
           end
         rescue Async::Stop
         ensure
           @engine.monitor_queue = nil
+          @engine.monitor_task  = nil
           block.call(MonitorEvent.new(type: :monitor_stopped))
         end
       end

data/lib/nnq/surveyor_respondent.rb

@@ -3,27 +3,37 @@
 require_relative "socket"
 require_relative "routing/surveyor"
 require_relative "routing/respondent"
+require_relative "routing/surveyor_raw"
+require_relative "routing/respondent_raw"
 
 module NNQ
   # SURVEYOR (nng surveyor0): broadcast side of the survey pattern.
-  # Sends a survey to all connected respondents, then collects replies
-  # within a timed window (`options.survey_time`, default 1s).
-  #
-  # Only one outstanding survey at a time — sending a new survey
-  # abandons the previous one. Respondents are not obliged to reply.
+  # Cooked mode enforces a timed survey window and matches replies by
+  # survey id; raw mode fans out with a caller-supplied +header+ and
+  # delivers replies as `[pipe, header, body]` with no timer.
   #
   class SURVEYOR0 < Socket
-    # Broadcasts +body+ as a survey to all connected respondents.
+    # Cooked: broadcasts +body+ as a survey to all connected respondents.
     def send_survey(body)
+      raise Error, "SURVEYOR#send_survey not available in raw mode" if raw?
       body = frozen_binary(body)
       Reactor.run { @engine.routing.send_survey(body) }
     end
 
 
-    # Receives the next reply. Raises {NNQ::TimedOut} when the survey
-    # window expires.
-    #
-    # @return [String] reply body
+    # Raw: broadcasts +body+ with +header+ to all connected respondents
+    # via per-conn send pumps (header is threaded through the
+    # protocol-sp header kwarg — no concat). Raises in cooked mode.
+    def send(body, header:)
+      raise Error, "SURVEYOR#send not available in cooked mode" unless raw?
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send(body, header: header) }
+    end
+
+
+    # Cooked: receives the next reply within the survey window, raises
+    # {NNQ::TimedOut} on window expiry. Raw: returns `[pipe, header, body]`
+    # and blocks indefinitely (no survey window).
     def receive
       Reactor.run { @engine.routing.receive }
     end
@@ -38,31 +48,41 @@ module NNQ
 
 
     def build_routing(engine)
-      Routing::Surveyor.new(engine)
+      raw? ? Routing::SurveyorRaw.new(engine) : Routing::Surveyor.new(engine)
     end
   end
 
 
   # RESPONDENT (nng respondent0): reply side of the survey pattern.
-  # Receives surveys, processes them, and optionally sends replies.
-  # Strict alternation: #receive then #send_reply.
+  # Cooked mode strictly alternates #receive / #send_reply; raw mode
+  # exposes the backtrace as an opaque +header+ and the originating
+  # surveyor pipe as a live Connection.
   #
   class RESPONDENT0 < Socket
-    # Blocks until the next survey arrives.
-    #
-    # @return [String, nil] survey body, or nil if the socket was closed
+    # Cooked: blocks until the next survey arrives. Raw: returns
+    # `[pipe, header, body]`.
     def receive
       Reactor.run { @engine.routing.receive }
     end
 
 
-    # Routes +body+ back to the surveyor that sent the most recent survey.
+    # Cooked: routes +body+ back to the surveyor that sent the most
+    # recent survey. Raises in raw mode.
     def send_reply(body)
+      raise Error, "RESPONDENT#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+ back to +to+. Raises in cooked mode.
+    def send(body, to:, header:)
+      raise Error, "RESPONDENT#send not available in cooked mode" unless raw?
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send(body, to: to, header: header) }
+    end
+
+
     private
 
 
@@ -72,7 +92,7 @@ module NNQ
 
 
     def build_routing(engine)
-      Routing::Respondent.new(engine)
+      raw? ? Routing::RespondentRaw.new(engine) : Routing::Respondent.new(engine)
     end
   end
 end

data/lib/nnq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NNQ
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nnq
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Patrik Wenger
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.3'
 description: Pure Ruby implementation of nanomsg's Scalability Protocols (SP) on top
   of async + io-stream. Per-socket HWM, opportunistic batching, wire-compatible with
   libnng over inproc/ipc/tcp.
@@ -85,11 +85,15 @@ files:
 - lib/nnq/routing/pull.rb
 - lib/nnq/routing/push.rb
 - lib/nnq/routing/rep.rb
+- lib/nnq/routing/rep_raw.rb
 - lib/nnq/routing/req.rb
+- lib/nnq/routing/req_raw.rb
 - lib/nnq/routing/respondent.rb
+- lib/nnq/routing/respondent_raw.rb
 - lib/nnq/routing/send_pump.rb
 - lib/nnq/routing/sub.rb
 - lib/nnq/routing/surveyor.rb
+- lib/nnq/routing/surveyor_raw.rb
 - lib/nnq/socket.rb
 - lib/nnq/surveyor_respondent.rb
 - lib/nnq/transport/inproc.rb