nnq 0.2.0 → 0.5.0

data/lib/nnq/socket.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+require "async/queue"
+
 require_relative "options"
 require_relative "engine"
+require_relative "monitor_event"
 require_relative "reactor"
 
 module NNQ
@@ -27,9 +30,23 @@ module NNQ
     end
 
 
-    def initialize(linger: nil, send_hwm: Options::DEFAULT_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)
+      @raw     = raw
       @options = Options.new(linger: linger, send_hwm: send_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
 
 
@@ -51,23 +68,102 @@ module NNQ
     end
 
 
-    def last_endpoint = @engine.last_endpoint
+    def last_endpoint
+      @engine.last_endpoint
+    end
+
+
+    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
+    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
+    end
+
+
+    def reconnect_enabled
+      @engine.reconnect_enabled
+    end
+
+
+    def reconnect_enabled=(value)
+      @engine.reconnect_enabled = value
+    end
+
+
+    # Closes the recv side only. Buffered messages drain, then
+    # {#receive} returns nil. Send side stays open.
+    def close_read
+      Reactor.run { @engine.close_read }
+      nil
+    end
+
+
+    # Yields lifecycle events for this socket until it's closed or
+    # the returned task is stopped.
+    #
+    # @param verbose [Boolean] when true, also emits :message_sent /
+    #   :message_received events
+    # @yield [event]
+    # @yieldparam event [MonitorEvent]
+    # @return [Async::Task]
+    def monitor(verbose: false, &block)
+      ensure_parent_task
+
+      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)
+            block.call(event)
+          end
+        rescue Async::Stop
+        ensure
+          @engine.monitor_queue = nil
+          block.call(MonitorEvent.new(type: :monitor_stopped))
+        end
+      end
+    end
 
 
-    def connection_count = @engine.connections.size
+    # 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
       # that Reactor wraps each dispatched block in. Inside an Async
       # reactor, the current task is the right parent.
       if Async::Task.current?
-        @engine.capture_parent_task(Async::Task.current)
+        @engine.capture_parent_task(Async::Task.current, on_io_thread: false)
       else
-        @engine.capture_parent_task(Reactor.root_task)
+        @engine.capture_parent_task(Reactor.root_task, on_io_thread: true)
       end
     end
 
@@ -82,5 +178,6 @@ module NNQ
     def build_routing(_engine)
       raise NotImplementedError
     end
+
   end
 end

data/lib/nnq/surveyor_respondent.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+require_relative "routing/surveyor"
+require_relative "routing/respondent"
+
+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.
+  #
+  class SURVEYOR0 < Socket
+    # Broadcasts +body+ as a survey to all connected respondents.
+    def send_survey(body)
+      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
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    private
+
+
+    def protocol
+      Protocol::SP::Protocols::SURVEYOR_V0
+    end
+
+
+    def build_routing(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.
+  #
+  class RESPONDENT0 < Socket
+    # Blocks until the next survey arrives.
+    #
+    # @return [String, nil] survey body, or nil if the socket was closed
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    # Routes +body+ back to the surveyor that sent the most recent survey.
+    def send_reply(body)
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send_reply(body) }
+    end
+
+
+    private
+
+
+    def protocol
+      Protocol::SP::Protocols::RESPONDENT_V0
+    end
+
+
+    def build_routing(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.2.0"
+  VERSION = "0.5.0"
 end

data/lib/nnq.rb

@@ -3,6 +3,14 @@
 require "protocol/sp"
 
 module NNQ
+  # Freezes module-level state so NNQ sockets can be used inside Ractors.
+  # Call this once before spawning any Ractors that create NNQ sockets.
+  #
+  def self.freeze_for_ractors!
+    Engine::CONNECTION_FAILED.freeze
+    Engine::CONNECTION_LOST.freeze
+    Engine::TRANSPORTS.freeze
+  end
 end
 
 require_relative "nnq/version"
@@ -15,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.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -52,8 +52,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.1'
 description: Pure Ruby implementation of nanomsg's Scalability Protocols (SP) on top
-  of async + io-stream. No HWM, opportunistic batching, wire-compatible with libnng
-  over inproc/ipc/tcp.
+  of async + io-stream. Per-socket HWM, opportunistic batching, wire-compatible with
+  libnng over inproc/ipc/tcp.
 email:
 - paddor@gmail.com
 executables: []
@@ -64,26 +64,34 @@ 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
+- lib/nnq/engine/reconnect.rb
 - lib/nnq/engine/socket_lifecycle.rb
 - lib/nnq/error.rb
+- lib/nnq/monitor_event.rb
 - lib/nnq/options.rb
 - lib/nnq/pair.rb
 - lib/nnq/pub_sub.rb
 - 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/req.rb
+- lib/nnq/routing/respondent.rb
 - lib/nnq/routing/send_pump.rb
 - lib/nnq/routing/sub.rb
+- lib/nnq/routing/surveyor.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