nnq 0.4.0 → 0.6.0

data/lib/nnq/routing/bus.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require "async/limited_queue"
+
+module NNQ
+  module Routing
+    # BUS0: best-effort bidirectional mesh.
+    #
+    # Send side: fan-out to all connected peers. Each peer gets its own
+    # bounded send queue and pump fiber — a slow peer drops messages
+    # instead of blocking fast ones (same as PUB). Send never blocks.
+    #
+    # Recv side: all incoming messages are pushed into a shared
+    # unbounded queue (same as PULL).
+    #
+    # No SP headers in cooked mode — body on the wire is the user
+    # payload.
+    #
+    class Bus
+      def initialize(engine)
+        @engine     = engine
+        @queues     = {} # conn => Async::LimitedQueue
+        @pump_tasks = {} # conn => Async::Task
+        @recv_queue = Async::Queue.new
+      end
+
+
+      # Broadcasts +body+ to every connected peer. Non-blocking per
+      # peer: drops when a peer's queue is at HWM.
+      #
+      # @param body [String]
+      def send(body)
+        @queues.each_value do |queue|
+          queue.enqueue(body) unless queue.limited?
+        end
+      end
+
+
+      # Called by the engine recv loop with each received message.
+      def enqueue(body, _conn = nil)
+        @recv_queue.enqueue(body)
+      end
+
+
+      # @return [String, nil] message body, or nil once the socket is closed
+      def receive
+        @recv_queue.dequeue
+      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 bus pump #{conn.endpoint}"
+        parent     = @engine.connections[conn]&.barrier || @engine.barrier
+
+        @engine.spawn_task(annotation:, parent:) do
+          loop do
+            body = queue.dequeue
+            conn.send_message(body)
+            @engine.emit_verbose_msg_sent(body)
+          rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
+            break
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/nnq/routing/pair.rb

@@ -22,6 +22,7 @@ module NNQ
     class Pair
       include SendPump
 
+
       def initialize(engine)
         init_send_pump(engine)
         @recv_queue = Async::Queue.new
@@ -41,7 +42,7 @@ module NNQ
       end
 
 
-      # Called by the recv loop with each frame off the wire.
+      # Called by the recv loop with each message off the wire.
       def enqueue(body, _conn = nil)
         @recv_queue.enqueue(body)
       end
@@ -52,6 +53,7 @@ module NNQ
       # without ever exposing it to pumps.
       def connection_added(conn)
         raise ConnectionRejected, "PAIR socket already has a peer" if @peer
+
         @peer = conn
         spawn_send_pump_for(conn)
       end
@@ -73,6 +75,7 @@ module NNQ
       def close_read
         @recv_queue.enqueue(nil)
       end
+
     end
   end
 end

data/lib/nnq/routing/pub.rb

@@ -60,7 +60,7 @@ module NNQ
 
       # True once every peer's queue is empty. Engine linger polls this.
       def send_queue_drained?
-        @queues.each_value.all?(&:empty?)
+        @queues.each_value.all? { |q| q.empty? }
       end
 
 
@@ -70,21 +70,25 @@ module NNQ
         @queues.clear
       end
 
+
       private
 
+
       def spawn_pump(conn, queue)
-        @engine.spawn_task(annotation: "nnq pub pump #{conn.endpoint}") do
+        annotation = "nnq pub pump #{conn.endpoint}"
+        parent     = @engine.connections[conn]&.barrier || @engine.barrier
+
+        @engine.spawn_task(annotation:, parent:) do
           loop do
             body = queue.dequeue
             conn.send_message(body)
-            @engine.emit_verbose_monitor_event(:message_sent, body: body)
+            @engine.emit_verbose_msg_sent(body)
           rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
             break
           end
-        ensure
-          @engine.handle_connection_lost(conn)
         end
       end
+
     end
   end
 end

data/lib/nnq/routing/pull.rb

@@ -6,7 +6,7 @@ module NNQ
   module Routing
     # PULL side: an unbounded queue of received messages. Per-connection
     # recv fibers (spawned by the Engine when each pipe is established)
-    # call {#enqueue} on each frame; user code calls {#receive}.
+    # call {#enqueue} on each message; user code calls {#receive}.
     #
     # No HWM, no prefetch buffer — TCP throttles the senders directly
     # via the kernel buffer.
@@ -41,6 +41,7 @@ module NNQ
       def close_read
         @queue.enqueue(nil)
       end
+
     end
   end
 end

data/lib/nnq/routing/push.rb

@@ -17,6 +17,7 @@ module NNQ
     class Push
       include SendPump
 
+
       def initialize(engine)
         init_send_pump(engine)
       end
@@ -38,6 +39,7 @@ module NNQ
       def connection_removed(conn)
         remove_send_pump_for(conn)
       end
+
     end
   end
 end

data/lib/nnq/routing/rep.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "async/queue"
+require_relative "backtrace"
 
 module NNQ
   module Routing
@@ -27,7 +28,8 @@ module NNQ
     # - TTL cap on the backtrace stack: 8 hops, matching nng's default.
     #
     class Rep
-      MAX_HOPS = 8 # nng's default ttl
+      include Backtrace
+
 
       def initialize(engine)
         @engine     = engine
@@ -46,7 +48,9 @@ module NNQ
         # again without replying is how users drop unwanted requests.
         @mutex.synchronize { @pending = nil }
         item = @recv_queue.dequeue
+
         return nil if item.nil?
+
         conn, btrace, body = item
         @mutex.synchronize { @pending = [conn, btrace] }
         body
@@ -65,11 +69,11 @@ module NNQ
         end
 
         return if conn.closed?
-        conn.send_message(btrace + body)
+        conn.send_message(body, header: btrace)
       end
 
 
-      # Called by the engine recv loop with each received frame.
+      # Called by the engine recv loop with each received message.
       def enqueue(body, conn)
         btrace, payload = parse_backtrace(body)
         return unless btrace # malformed/over-TTL — drop
@@ -94,25 +98,6 @@ module NNQ
       end
 
 
-      private
-
-      # 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
     end
   end
 end

data/lib/nnq/routing/rep_raw.rb

@@ -0,0 +1,63 @@
+# 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)
+      rescue ClosedError
+        # peer went away between receive and send — drop
+      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

@@ -10,7 +10,7 @@ module NNQ
     # Wire format: each message body on the wire is `[4-byte BE
     # request_id][user_payload]`. The request id has the high bit set
     # (`0x80000000..0xFFFFFFFF`) — that's nng's marker for "this is the
-    # last (deepest) frame on the backtrace stack". Direct REQ→REP has
+    # last (deepest) word on the backtrace stack". Direct REQ→REP has
     # exactly one id.
     #
     # Semantics (cooked mode, what this implements):
@@ -55,7 +55,7 @@ module NNQ
 
         conn   = pick_peer
         header = [id].pack("N")
-        conn.send_message(header + body)
+        conn.send_message(body, header: header)
         promise.wait
       ensure
         @mutex.synchronize do
@@ -66,7 +66,7 @@ module NNQ
       end
 
 
-      # Called by the engine recv loop with each received frame.
+      # Called by the engine recv loop with each received message.
       def enqueue(body, _conn)
         return if body.bytesize < 4
         id      = body.unpack1("N")
@@ -91,17 +91,21 @@ module NNQ
 
       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/req_raw.rb

@@ -0,0 +1,73 @@
+# 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)
+      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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "async/queue"
+require_relative "backtrace"
+
+module NNQ
+  module Routing
+    # RESPONDENT: reply side of the survey0 pattern.
+    #
+    # Semantics mirror REP: strict alternation of #receive then
+    # #send_reply. The backtrace (survey ID + any hop IDs) is stripped
+    # on receive and echoed verbatim on reply.
+    #
+    class Respondent
+      include Backtrace
+
+
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = Async::Queue.new
+        @pending    = nil
+        @mutex      = Mutex.new
+      end
+
+
+      # Receives the next survey body. Stashes the backtrace +
+      # originating connection for the subsequent #send_reply.
+      #
+      # @return [String, nil] survey body, or nil if the socket was closed
+      def receive
+        @mutex.synchronize { @pending = nil }
+        item = @recv_queue.dequeue
+
+        return nil if item.nil?
+
+        conn, btrace, body = item
+        @mutex.synchronize { @pending = [conn, btrace] }
+        body
+      end
+
+
+      # Sends +body+ as the reply to the most recently received survey.
+      #
+      # @param body [String]
+      def send_reply(body)
+        conn, btrace = @mutex.synchronize do
+          raise Error, "RESPONDENT socket has no pending survey to reply to" unless @pending
+          taken    = @pending
+          @pending = nil
+          taken
+        end
+
+        return if conn.closed?
+        conn.send_message(body, header: btrace)
+      end
+
+
+      # Called by the engine recv loop with each received message.
+      def enqueue(body, conn)
+        btrace, payload = parse_backtrace(body)
+        return unless btrace # malformed/over-TTL — drop
+        @recv_queue.enqueue([conn, btrace, payload])
+      end
+
+
+      def connection_removed(conn)
+        @mutex.synchronize do
+          @pending = nil if @pending && @pending[0] == conn
+        end
+      end
+
+
+      def close
+        @recv_queue.enqueue(nil)
+      end
+
+
+      def close_read
+        @recv_queue.enqueue(nil)
+      end
+
+    end
+  end
+end

data/lib/nnq/routing/respondent_raw.rb

@@ -0,0 +1,54 @@
+# 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)
+      rescue ClosedError
+      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/send_pump.rb

@@ -21,7 +21,13 @@ module NNQ
     # {#spawn_send_pump_for} from their #connection_added hook.
     #
     module SendPump
+      # Max messages a single pump will drain from the shared queue in
+      # one batch before yielding. Bounds the worst-case latency other
+      # pumps wait when the queue is under sustained pressure.
       BATCH_MSG_CAP  = 256
+
+      # Max cumulative body bytes in one batch. Keeps a single pump
+      # from monopolising the writer mutex on huge payloads.
       BATCH_BYTE_CAP = 256 * 1024
 
 
@@ -56,6 +62,7 @@ module NNQ
 
       private
 
+
       # @param engine [Engine]
       def init_send_pump(engine)
         @engine     = engine
@@ -79,11 +86,16 @@ module NNQ
       #
       # @param conn [Connection]
       def spawn_send_pump_for(conn)
-        task = @engine.spawn_task(annotation: "nnq send pump #{conn.endpoint}") do
+        annotation = "nnq send pump #{conn.endpoint}"
+        parent     = @engine.connections[conn]&.barrier || @engine.barrier
+
+        task = @engine.spawn_task(annotation:, parent:) do
           loop do
             first = @send_queue.dequeue
             break if first.nil? # queue closed
+
             @in_flight += 1
+
             begin
               batch = [first]
               drain_capped(batch)
@@ -91,22 +103,26 @@ module NNQ
             ensure
               @in_flight -= 1
             end
+
+            Async::Task.current.yield
           rescue EOFError, IOError, Errno::EPIPE, Errno::ECONNRESET
             # Peer died mid-flush. In-flight batch dropped.
             break
           end
-        ensure
-          @engine.handle_connection_lost(conn)
         end
+
         @pumps[conn] = task
       end
 
 
       def drain_capped(batch)
-        bytes = batch[0].bytesize
+        bytes = batch.first.bytesize
+
         while batch.size < BATCH_MSG_CAP && bytes < BATCH_BYTE_CAP
           msg = @send_queue.dequeue(timeout: 0)
+
           break unless msg
+
           batch << msg
           bytes += msg.bytesize
         end
@@ -115,16 +131,21 @@ module NNQ
 
       def write_batch(conn, batch)
         if batch.size == 1
-          conn.write_message(batch[0])
+          conn.write_message(batch.first)
         else
           # Single mutex acquisition for the whole batch (batches run
           # up to BATCH_MSG_CAP messages). The per-message pump loop
           # would otherwise lock/unlock the SP mutex N times.
           conn.write_messages(batch)
         end
+
         conn.flush
-        batch.each { |body| @engine.emit_verbose_monitor_event(:message_sent, body: body) }
+
+        if @engine.verbose_monitor
+          batch.each { |body| @engine.emit_verbose_msg_sent(body) }
+        end
       end
+
     end
   end
 end