nnq 0.2.0 → 0.5.0

data/lib/nnq/routing/backtrace.rb

@@ -0,0 +1,39 @@
+# 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
+
+    end
+  end
+end

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
@@ -67,6 +69,13 @@ module NNQ
         super
         @recv_queue.enqueue(nil) # wake any waiter
       end
+
+
+      # Wake recv side without tearing down the send pump.
+      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,20 +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_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.
@@ -33,6 +33,15 @@ module NNQ
       def close
         @queue.enqueue(nil)
       end
+
+
+      # Wakes any waiters with nil, leaving the send side untouched
+      # (PULL has no send side — close_read is identical to close here,
+      # but kept separate for the `Socket#close_read` contract).
+      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
@@ -69,7 +73,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)
         btrace, payload = parse_backtrace(body)
         return unless btrace # malformed/over-TTL — drop
@@ -89,25 +93,11 @@ 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
+      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):
@@ -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/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(btrace + body)
+      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/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,15 +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
+
+        if @engine.verbose_monitor
+          batch.each { |body| @engine.emit_verbose_msg_sent(body) }
+        end
       end
+
     end
   end
 end

data/lib/nnq/routing/sub.rb

@@ -48,11 +48,20 @@ module NNQ
         @queue.enqueue(nil)
       end
 
+
+      def close_read
+        @queue.enqueue(nil)
+      end
+
+
       private
 
+
       def matches?(body)
+        # OPTIMIZE: use Patricia-trie
         @subscriptions.any? { |prefix| body.start_with?(prefix) }
       end
+
     end
   end
 end

data/lib/nnq/routing/surveyor.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require "async/limited_queue"
+require "securerandom"
+
+module NNQ
+  module Routing
+    # SURVEYOR: broadcast side of the survey0 pattern.
+    #
+    # Wire format: each survey is prepended with a 4-byte BE survey ID
+    # (high bit set — same terminal-marker convention as REQ). Replies
+    # carry the same ID back. Stale replies (wrong ID) are dropped.
+    #
+    # Send side: fan-out to all connected respondents (like PUB). Each
+    # peer gets its own bounded queue and pump.
+    #
+    # Recv side: replies are matched by survey ID. Only replies
+    # matching the current survey are delivered. After `survey_time`
+    # elapses, {#receive} raises {NNQ::TimedOut}.
+    #
+    class Surveyor
+      def initialize(engine)
+        @engine     = engine
+        @queues     = {} # conn => Async::LimitedQueue
+        @pump_tasks = {} # conn => Async::Task
+        @recv_queue = Async::Queue.new
+        @current_id = nil
+        @mutex      = Mutex.new
+      end
+
+
+      # Broadcasts +body+ as a survey to all connected respondents.
+      # Starts a new survey window; any previous survey is abandoned.
+      #
+      # @param body [String]
+      def send_survey(body)
+        id = SecureRandom.random_number(0x80000000) | 0x80000000
+
+        @mutex.synchronize do
+          @current_id = id
+        end
+
+        header = [id].pack("N")
+        wire   = header + body
+
+        @queues.each_value do |q|
+          q.enqueue(wire) unless q.limited?
+        end
+      end
+
+
+      # Receives the next reply within the survey window. Raises
+      # {NNQ::TimedOut} when the window expires.
+      #
+      # @return [String] reply body
+      def receive
+        survey_time = @engine.options.survey_time
+        Fiber.scheduler.with_timeout(survey_time) { @recv_queue.dequeue }
+      rescue Async::TimeoutError
+        raise NNQ::TimedOut, "survey timed out"
+      end
+
+
+      # Called by the engine recv loop with each received message.
+      def enqueue(body, _conn)
+        return if body.bytesize < 4
+
+        id      = body.unpack1("N")
+        payload = body.byteslice(4..)
+
+        @mutex.synchronize do
+          return unless @current_id == id
+        end
+
+        @recv_queue.enqueue(payload)
+      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 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