nnq 0.4.0 → 0.6.0

data/lib/nnq/routing/sub.rb

@@ -53,11 +53,15 @@ module NNQ
         @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

data/lib/nnq/routing/surveyor_raw.rb

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

@@ -30,9 +30,23 @@ module NNQ
     end
 
 
-    def initialize(linger: nil, send_hwm: Options::DEFAULT_HWM)
-      @options = Options.new(linger: linger, send_hwm: send_hwm)
+    # @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, recv_hwm: Options::DEFAULT_HWM)
+      @raw     = raw
+      @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
+        yield self
+      ensure
+        close
+      end if block_given?
+    end
+
+
+    def raw?
+      @raw
     end
 
 
@@ -54,23 +68,35 @@ module NNQ
     end
 
 
-    def last_endpoint = @engine.last_endpoint
+    def last_endpoint
+      @engine.last_endpoint
+    end
 
 
-    def connection_count = @engine.connections.size
+    def connection_count
+      @engine.connections.size
+    end
 
 
     # Resolves with the first connected peer (or nil on close without
     # any peers). Block on `.wait` to wait until a connection is ready.
-    def peer_connected = @engine.peer_connected
+    def peer_connected
+      @engine.peer_connected
+    end
 
 
     # Resolves with `true` the first time all peers have disconnected
     # (after at least one peer was connected). Edge-triggered.
-    def all_peers_gone = @engine.all_peers_gone
+    def all_peers_gone
+      @engine.all_peers_gone
+    end
+
+
+    def reconnect_enabled
+      @engine.reconnect_enabled
+    end
 
 
-    def reconnect_enabled  = @engine.reconnect_enabled
     def reconnect_enabled=(value)
       @engine.reconnect_enabled = value
     end
@@ -94,9 +120,11 @@ module NNQ
     # @return [Async::Task]
     def monitor(verbose: false, &block)
       ensure_parent_task
-      queue = Async::Queue.new
+
+      queue                   = Async::Queue.new
       @engine.monitor_queue   = queue
       @engine.verbose_monitor = verbose
+
       Reactor.run do
         @engine.spawn_task(annotation: "nnq monitor") do
           while (event = queue.dequeue)
@@ -111,8 +139,22 @@ module NNQ
     end
 
 
+    # Coerces +body+ to a frozen binary string. Called by every send
+    # method so a caller can't mutate the string after it's been
+    # enqueued (the body sits in a send queue or per-peer queue until
+    # the pump writes it, and an unfrozen caller-owned buffer could be
+    # appended to mid-flight).
+    #
+    # Fast-path: already frozen + binary → returned as-is.
+    def frozen_binary(body)
+      return body if body.frozen? && body.encoding == Encoding::BINARY
+      body.b.freeze
+    end
+
+
     private
 
+
     def ensure_parent_task
       # Must run OUTSIDE Reactor.run so that non-Async callers capture
       # the IO thread's root task, not the ephemeral work-item task
@@ -136,5 +178,6 @@ module NNQ
     def build_routing(_engine)
       raise NotImplementedError
     end
+
   end
 end

data/lib/nnq/surveyor_respondent.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+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.
+  # 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
+    # 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
+
+
+    # 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
+
+
+    private
+
+
+    def protocol
+      Protocol::SP::Protocols::SURVEYOR_V0
+    end
+
+
+    def build_routing(engine)
+      raw? ? Routing::SurveyorRaw.new(engine) : Routing::Surveyor.new(engine)
+    end
+  end
+
+
+  # RESPONDENT (nng respondent0): reply side of the survey pattern.
+  # 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
+    # Cooked: blocks until the next survey arrives. Raw: returns
+    # `[pipe, header, body]`.
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    # 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
+
+
+    def protocol
+      Protocol::SP::Protocols::RESPONDENT_V0
+    end
+
+
+    def build_routing(engine)
+      raw? ? Routing::RespondentRaw.new(engine) : Routing::Respondent.new(engine)
+    end
+  end
+end

data/lib/nnq/transport/inproc.rb

@@ -31,6 +31,7 @@ module NNQ
             raise Error, "inproc endpoint already bound: #{endpoint}" if @registry.key?(endpoint)
             @registry[endpoint] = engine
           end
+
           Listener.new(endpoint)
         end
 
@@ -46,7 +47,9 @@ module NNQ
         def connect(endpoint, engine)
           bound = @mutex.synchronize { @registry[endpoint] }
           raise Error, "inproc endpoint not bound: #{endpoint}" unless bound
+
           a, b = UNIXSocket.pair
+
           # Handshake on the bound side must run concurrently with
           # ours — if we called bound.handle_accepted synchronously
           # it would block on reading our greeting before we've had
@@ -75,6 +78,7 @@ module NNQ
       class Listener
         attr_reader :endpoint
 
+
         def initialize(endpoint)
           @endpoint = endpoint
         end
@@ -88,6 +92,7 @@ module NNQ
         def stop
           Inproc.unbind(@endpoint)
         end
+
       end
     end
   end

data/lib/nnq/transport/ipc.rb

@@ -22,7 +22,9 @@ module NNQ
         def bind(endpoint, engine)
           path      = parse_path(endpoint)
           sock_path = to_socket_path(path)
+
           File.delete(sock_path) if !abstract?(path) && File.exist?(sock_path)
+
           server = UNIXServer.new(sock_path)
           Listener.new(endpoint, server, path, engine)
         end
@@ -91,6 +93,7 @@ module NNQ
           @server.close rescue nil
           File.delete(@path) rescue nil unless IPC.abstract?(@path)
         end
+
       end
     end
   end

data/lib/nnq/transport/tcp.rb

@@ -19,10 +19,11 @@ module NNQ
         # @return [Listener]
         def bind(endpoint, engine)
           host, port = parse_endpoint(endpoint)
-          host = "0.0.0.0" if host == "*"
-          server = TCPServer.new(host, port)
-          actual = server.local_address.ip_port
-          host_part = host.include?(":") ? "[#{host}]" : host
+          host       = "0.0.0.0" if host == "*"
+          server     = TCPServer.new(host, port)
+          actual     = server.local_address.ip_port
+          host_part  = host.include?(":") ? "[#{host}]" : host
+
           Listener.new("tcp://#{host_part}:#{actual}", server, actual, engine)
         end
 
@@ -35,11 +36,23 @@ module NNQ
         # @return [void]
         def connect(endpoint, engine)
           host, port = parse_endpoint(endpoint)
-          sock = TCPSocket.new(host, port)
+          sock       = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
+
           engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
         end
 
 
+        # Connect timeout: cap each attempt at the reconnect interval so
+        # a hung connect(2) (e.g. macOS kqueue + IPv6 ECONNREFUSED not
+        # delivered) doesn't block the retry loop. Floor at 0.5s for
+        # real-network latency.
+        def connect_timeout(options)
+          ri = options.reconnect_interval
+          ri = ri.end if ri.is_a?(Range)
+          [ri, 0.5].max
+        end
+
+
         def parse_endpoint(endpoint)
           uri = URI.parse(endpoint)
           [uri.hostname, uri.port]
@@ -50,9 +63,17 @@ module NNQ
       # A bound TCP listener.
       #
       class Listener
+        # @return [String] the normalised endpoint URL this listener is
+        #   bound to (with the resolved port substituted when the user
+        #   bound to port 0).
         attr_reader :endpoint
+
+        # @return [Integer] the actual TCP port the listener is bound
+        #   to. Equals the requested port unless 0 was requested, in
+        #   which case it reflects the kernel-assigned ephemeral port.
         attr_reader :port
 
+
         def initialize(endpoint, server, port, engine)
           @endpoint = endpoint
           @server   = server
@@ -84,6 +105,7 @@ module NNQ
           @task&.stop
           @server.close rescue nil
         end
+
       end
     end
   end

data/lib/nnq/version.rb

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

data/lib/nnq.rb

@@ -23,3 +23,5 @@ require_relative "nnq/push_pull"
 require_relative "nnq/pair"
 require_relative "nnq/req_rep"
 require_relative "nnq/pub_sub"
+require_relative "nnq/bus"
+require_relative "nnq/surveyor_respondent"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nnq
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 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.
@@ -64,6 +64,7 @@ files:
 - LICENSE
 - README.md
 - lib/nnq.rb
+- lib/nnq/bus.rb
 - lib/nnq/connection.rb
 - lib/nnq/engine.rb
 - lib/nnq/engine/connection_lifecycle.rb
@@ -77,15 +78,24 @@ files:
 - lib/nnq/push_pull.rb
 - lib/nnq/reactor.rb
 - lib/nnq/req_rep.rb
+- lib/nnq/routing/backtrace.rb
+- lib/nnq/routing/bus.rb
 - lib/nnq/routing/pair.rb
 - lib/nnq/routing/pub.rb
 - 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
 - lib/nnq/transport/ipc.rb
 - lib/nnq/transport/tcp.rb