nnq 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d4408e132c91a9ebf74a96a8c14f6004c5e05c4b9abdc959a798b98f7adbf32
-  data.tar.gz: ebc0be58942030dcd326664ddde9286d948e074c953ec06f9c238a59b6f3b02a
+  metadata.gz: 68a6dd62dc097b93740827c44f95bbfa983d5c7d6072b4625257bd2350ba23fe
+  data.tar.gz: 376c1ef08eda16a8950ae703d1798256c8c5ba720cd1e5d0e988f1a87067c093
 SHA512:
-  metadata.gz: dc12b86758f90e1c36aba100962fc89d8cabbc93d72e9e28d4f7973a90cb1b9fab1ab38908cd3988f1b264f3bff2de34818043e5026cdc5ad655312e374fd150
-  data.tar.gz: 7679994454867fa4fcc35d3c16e7c49ffe275ba9cdaf66fbcd428e3fef8b0e89df440918232b0968e38448033198be6f91616aac678ed65bd9c5158a9cda4702
+  metadata.gz: f88c29c241ea5922930342a11c00181007cf698045b219c6e7cc111d2563e37e7e56c64efbb61b48efa608eaa6ab3e7104bc33983c6202410f1745a50a082012
+  data.tar.gz: e1e42983059b5a280495216a08b6e6ac6a9e6eff9385a2093ad62b9ac7698a80d24a2f36f14c4f4f9579962b7fde9c83a042f04e1819e5963ba2ae94b5cbed4f

data/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 0.5.0 — 2026-04-15
+
+- **Send-path freezes the body** — every public send method (PUSH,
+  PUB, PAIR, BUS, REQ, REP, SURVEYOR, RESPONDENT) routes the body
+  through `Socket#frozen_binary`, which coerces to a frozen binary
+  string. Fast path: already frozen and binary → returned as-is, no
+  allocation. Slow path: `body.b.freeze` (one copy). Prevents a
+  caller from mutating the string after it has been enqueued (the
+  body can sit in a send queue or per-peer queue until a pump
+  writes it).
+- **Hot-path: no kwargs splat on verbose monitor emit** —
+  `emit_verbose_monitor_event(type, **detail)` replaced with dedicated
+  `emit_verbose_msg_sent(body)` / `emit_verbose_msg_received(body)`
+  helpers. Early-returns before allocating the detail hash, so the
+  send/recv loops pay nothing when `-vvv` is off. Send pump also
+  hoists the `verbose_monitor` check out of the batch `.each`.
+- **YJIT-friendly `all?` blocks** — `@queues.each_value.all?(&:empty?)`
+  → explicit `{ |q| q.empty? }` in pub/bus/surveyor `drained?`
+  (YJIT specializes explicit blocks, not `Symbol#to_proc`).
+- **`Reactor.run` uses `Async::Promise`** — replaces the
+  `Thread::Queue` + manual `[:ok,val]`/`[:error,exc]` tagging with a
+  single `result.fulfill { block.call }` + `result.wait` pair.
+- **`Engine#spawn_task(parent:)`** — renamed from `barrier:` to make it
+  clear any parent barrier is accepted, not just the socket-level one.
+- **`linger` default → `Float::INFINITY`** — matches libzmq parity.
+  `Socket#close` waits forever for the send queue to drain. Pass
+  `linger: 0` for the old drop-on-close behavior.
+- **`Socket.new` accepts a block** — File.open-style. The socket is
+  yielded to the block and `#close`d when the block returns (or
+  raises).
+- **`drain_send_queue` rescues `Async::Stop`** — parent-task
+  cancellation during close no longer propagates out of the ensure
+  path; the rest of teardown runs.
+- **Hot-path `Array#first`** — `send_pump` uses `Array#first` instead
+  of `[0]` for YJIT specialization.
+- **Barrier-based cascading teardown** — `SocketLifecycle` owns a
+  socket-level `Async::Barrier`; `ConnectionLifecycle` creates a nested
+  per-connection barrier. All pumps, accept loops, reconnect loops, and
+  supervisors live under these barriers. `Engine#close` calls
+  `barrier.stop` once and every descendant unwinds atomically. Replaces
+  the manual `@tasks` array.
+- **Per-connection supervisor** — each connection spawns a supervisor
+  task (on the socket barrier) that watches for the first pump exit and
+  runs `lost!` in `ensure`. Placing the supervisor outside the
+  per-connection barrier avoids the self-stop footgun.
+- **Connect timeout** — `Transport::TCP.connect` uses
+  `Socket.tcp(host, port, connect_timeout:)` instead of `TCPSocket.new`.
+  Timeout derived from `reconnect_interval` (floor 0.5s). Fixes macOS
+  hang where IPv6 `connect(2)` never delivers `ECONNREFUSED`.
+- **Handshake timeout** — SP greeting exchange wrapped in
+  `Async::Task#with_timeout(handshake_timeout)`. Prevents a hang when a
+  non-NNG service accepts the TCP connection but never sends a greeting.
+- **Reconnect after handshake failure** — `ConnectionLifecycle#handshake!`
+  now calls `tear_down!(reconnect: true)` on error instead of bare
+  `transition!(:closed)`, so the endpoint doesn't go dead when a peer
+  RSTs mid-handshake.
+- **Quantized reconnect sleeps** — `Reconnect#quantized_wait` aligns
+  retries to wall-clock grid boundaries. Multiple clients reconnecting
+  with the same interval wake at the same instant.
+- **Send pump fairness yield** — `Async::Task.current.yield` after each
+  batch write ensures peer pumps get a turn when the queue stays
+  non-empty.
+- Add `DESIGN.md` documenting the architecture.
+- **Versioned socket names** — `PUSH` → `PUSH0`, `PULL` → `PULL0`, etc.
+  Canonical names now include the SP protocol version. Unversioned
+  aliases (`NNQ::PUSH = NNQ::PUSH0`) are kept for backward compat.
+- **`raw:` kwarg** — `Socket#initialize` accepts `raw: false`. Plumbing
+  for raw-mode routing (device/proxy support). No functional raw
+  routing yet.
+- **`NNQ::BUS0`** — best-effort bidirectional mesh (bus0). Fan-out send
+  to all peers (drop when full), shared recv queue. Self-pairing.
+- **`NNQ::SURVEYOR0` / `NNQ::RESPONDENT0`** — survey/response pattern
+  (survey0). Surveyor broadcasts a survey with a timed reply window
+  (`options.survey_time`, default 1s). Respondent echoes the backtrace
+  like REP. Shared `Routing::Backtrace` module extracted from REP.
+- **`NNQ::TimedOut`** error raised when the survey window expires.
+
+## 0.4.0 — 2026-04-09
+
+- `Socket#all_peers_gone` — `Async::Promise` resolving the first time
+  the connection set becomes empty after at least one peer connected.
+  Edge-triggered, ported from OMQ.
+- `Socket#close_read` — closes the recv side only. Buffered messages
+  drain, then `#receive` returns `nil`. Send side stays operational.
+- `Socket#reconnect_enabled` / `#reconnect_enabled=` — flipped by
+  transient-mode consumers before draining to prevent the background
+  reconnect loop from revivifying a dying socket.
+- `Socket#monitor` / `NNQ::MonitorEvent` — lifecycle event stream
+  emitting `:listening`, `:connect_delayed`, `:connect_retried`,
+  `:connected`, `:handshake_succeeded`/`_failed`, `:disconnected`,
+  `:closed`, and (when `verbose: true`) `:message_sent` /
+  `:message_received`. Ported from OMQ, minus the heartbeat/mechanism
+  events nnq doesn't have.
+- Background reconnect — `NNQ::Engine::Reconnect` runs a `transient: true`
+  task per dialed endpoint, retrying with exponential back-off bounded
+  by `options.reconnect_interval` (Numeric or Range). `connect` becomes
+  non-blocking for `tcp://` and `ipc://`; `inproc://` stays synchronous.
+  `CONNECTION_FAILED` / `CONNECTION_LOST` mutable-at-load-time registries
+  let plugins append transport-specific error classes.
+- `NNQ::PULL#receive` honors `options.read_timeout` via
+  `Fiber.scheduler.with_timeout`. Previously the option was declared
+  but inert.
+- `NNQ.freeze_for_ractors!` — freezes `Engine::CONNECTION_FAILED`,
+  `Engine::CONNECTION_LOST`, and `Engine::TRANSPORTS` so NNQ sockets
+  can be used from non-main Ractors. Required for nnq-cli's `pipe -P N`
+  parallel worker mode.
+
+## 0.3.0 — 2026-04-09
+
+- `Socket#peer_connected` — `Async::Promise` that resolves with the
+  first connected peer (or `nil` on close without any peers). Ported
+  from OMQ. Held on `SocketLifecycle`, resolved by `ConnectionLifecycle`
+  on first `ready!`, and edge-triggered so callers don't need to poll.
+- `bench/` — main throughput suite ported from OMQ. Four patterns
+  (push/pull, req/rep, pair, pub/sub) across inproc, ipc, and tcp.
+  Calibration-driven burst sizing, fastest-of-3 reporting, regression
+  report with `--update-readme` to regenerate README tables.
+
 ## 0.2.0 — 2026-04-09
 
 - `NNQ::PUB` / `NNQ::SUB` with local prefix filtering (pub0/sub0).

data/lib/nnq/bus.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+require_relative "routing/bus"
+
+module NNQ
+  # BUS (nng bus0): best-effort bidirectional mesh. Every message sent
+  # goes to all directly connected peers. Every message received from
+  # any peer is delivered to the application. Self-pairing (BUS ↔ BUS).
+  #
+  # Send never blocks — if a peer's queue is full, the message is
+  # dropped for that peer (matching nng's best-effort semantics).
+  #
+  class BUS0 < Socket
+    def send(body)
+      body = frozen_binary(body)
+      Reactor.run { @engine.routing.send(body) }
+    end
+
+
+    def receive
+      Reactor.run { @engine.routing.receive }
+    end
+
+
+    private
+
+    def protocol
+      Protocol::SP::Protocols::BUS_V0
+    end
+
+
+    def build_routing(engine)
+      Routing::Bus.new(engine)
+    end
+  end
+end

data/lib/nnq/connection.rb

@@ -12,9 +12,11 @@ module NNQ
     # @return [Protocol::SP::Connection]
     attr_reader :sp
 
+
     # @return [String, nil] endpoint URI we connected to / accepted from
     attr_reader :endpoint
 
+
     # @param sp [Protocol::SP::Connection] handshake-completed SP connection
     # @param endpoint [String, nil]
     def initialize(sp, endpoint: nil)
@@ -25,7 +27,9 @@ module NNQ
 
 
     # @return [Integer] peer protocol id (e.g. Protocols::PULL_V0)
-    def peer_protocol = @sp.peer_protocol
+    def peer_protocol
+      @sp.peer_protocol
+    end
 
 
     # Writes one message into the SP connection's send buffer (no flush).
@@ -77,7 +81,9 @@ module NNQ
 
 
     # @return [Boolean]
-    def closed? = @closed
+    def closed?
+      @closed
+    end
 
 
     # Closes the underlying SP connection. Safe to call twice.
@@ -86,5 +92,6 @@ module NNQ
       @closed = true
       @sp.close
     end
+
   end
 end

data/lib/nnq/engine/connection_lifecycle.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "async/barrier"
 require "protocol/sp"
 require_relative "../connection"
 
@@ -42,6 +43,12 @@ module NNQ
       # @return [Symbol]
       attr_reader :state
 
+      # @return [Async::Barrier] holds all per-connection pump tasks
+      #   (send pump, recv pump). When the connection is torn down,
+      #   {#tear_down!} calls `@barrier.stop` to cancel every sibling
+      #   task atomically.
+      attr_reader :barrier
+
 
       # @param engine [Engine]
       # @param endpoint [String, nil]
@@ -52,6 +59,7 @@ module NNQ
         @framing  = framing
         @state    = :new
         @conn     = nil
+        @barrier  = Async::Barrier.new(parent: engine.barrier)
       end
 
 
@@ -68,28 +76,45 @@ module NNQ
           max_message_size: @engine.options.max_message_size,
           framing:          @framing,
         )
-        sp.handshake!
+        Async::Task.current.with_timeout(handshake_timeout) { sp.handshake! }
         ready!(NNQ::Connection.new(sp, endpoint: @endpoint))
         @conn
-      rescue
+      rescue Protocol::SP::Error, *CONNECTION_LOST, Async::TimeoutError => error
+        @engine.emit_monitor_event(:handshake_failed, endpoint: @endpoint, detail: { error: error })
         io.close rescue nil
-        transition!(:closed) unless @state == :closed
+        # Full tear-down with reconnect: without this, the endpoint
+        # goes dead when a peer RSTs mid-handshake.
+        tear_down!(reconnect: true)
         raise
       end
 
 
-      # Transitions to :closed, removing the connection from the engine
-      # and notifying the routing strategy. Idempotent.
+      # Unexpected loss of an established connection. Tears down and
+      # asks the engine to schedule a reconnect (if the endpoint is in
+      # the dialed set and reconnect is still enabled).
       def lost!
-        tear_down!
+        tear_down!(reconnect: true)
       end
 
 
-      # Alias for lost!. Kept as a separate method for parity with OMQ,
-      # where the distinction drives reconnect scheduling. nnq has no
-      # reconnect yet, so the two behave identically.
+      # Deliberate close (engine shutdown or routing eviction). Does
+      # not trigger reconnect.
       def close!
-        tear_down!
+        tear_down!(reconnect: false)
+      end
+
+
+      # Starts a supervisor for this connection. Must be called after
+      # all per-connection pumps (recv loop, send pump) have been
+      # spawned on the connection barrier. The supervisor blocks until
+      # the first pump exits, then runs tear_down! via lost!.
+      #
+      # Called by Engine#handle_accepted / Engine#handle_connected after
+      # spawning the recv loop — routing's connection_added may have
+      # already spawned send pumps during ready!, so the barrier is
+      # guaranteed non-empty by then.
+      def start_supervisor!
+        start_supervisor unless @barrier.empty?
       end
 
 
@@ -102,24 +127,59 @@ module NNQ
         begin
           @engine.routing.connection_added(conn) if @engine.routing.respond_to?(:connection_added)
         rescue ConnectionRejected
-          tear_down!
+          @engine.emit_monitor_event(:connection_rejected, endpoint: @endpoint)
+          tear_down!(reconnect: false)
           raise
         end
+        @engine.lifecycle.peer_connected.resolve(conn) unless @engine.lifecycle.peer_connected.resolved?
+        @engine.emit_monitor_event(:handshake_succeeded, endpoint: @endpoint)
+        @engine.emit_monitor_event(:connected, endpoint: @endpoint)
         @engine.new_pipe.signal
       end
 
 
-      def tear_down!
+      def tear_down!(reconnect: false)
         return if @state == :closed
         transition!(:closed)
         if @conn
           @engine.connections.delete(@conn)
           @engine.routing.connection_removed(@conn) if @engine.routing.respond_to?(:connection_removed)
           @conn.close rescue nil
+          @engine.emit_monitor_event(:disconnected, endpoint: @endpoint)
+          @engine.resolve_all_peers_gone_if_empty
+        end
+        @engine.maybe_reconnect(@endpoint) if reconnect
+        # Cancel every sibling pump of this connection. The caller is
+        # the supervisor task, which is NOT in the barrier — so there
+        # is no self-stop risk.
+        @barrier.stop
+      end
+
+
+      # Spawns a supervisor task on the *socket-level* barrier (not the
+      # per-connection barrier) that blocks on the first pump to finish
+      # and then triggers teardown.
+      def start_supervisor
+        @engine.barrier.async(transient: true, annotation: "conn supervisor") do
+          @barrier.wait { |task| task.wait; break }
+        rescue Async::Stop, Async::Cancel
+        rescue *CONNECTION_LOST
+        ensure
+          lost!
         end
       end
 
 
+      # Handshake timeout: same logic as TCP.connect_timeout — derived
+      # from reconnect_interval (floor 0.5s). Prevents a hang when the
+      # peer accepts the TCP connection but never sends an SP greeting.
+      def handshake_timeout
+        ri = @engine.options.reconnect_interval
+        ri = ri.end if ri.is_a?(Range)
+        [ri, 0.5].max
+      end
+
+
       def transition!(new_state)
         allowed = TRANSITIONS[@state]
         unless allowed&.include?(new_state)

data/lib/nnq/engine/reconnect.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module NNQ
+  class Engine
+    # Connection errors that should trigger a reconnect retry rather
+    # than propagate. Mutable at load time so plugins (e.g. a future
+    # TLS transport) can append their own error classes; frozen on
+    # first {Engine#connect}.
+    CONNECTION_FAILED = [
+      Errno::ECONNREFUSED,
+      Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH,
+      Errno::ENOENT,
+      Errno::EPIPE,
+      Errno::ETIMEDOUT,
+      Socket::ResolutionError,
+    ]
+
+    # Errors that indicate an established connection went away. Used
+    # by the recv loop and pumps to silently terminate (the connection
+    # lifecycle's #lost! handler decides whether to reconnect).
+    CONNECTION_LOST = [
+      EOFError,
+      IOError,
+      Errno::ECONNRESET,
+      Errno::EPIPE,
+    ]
+
+
+    # Schedules reconnect attempts with exponential back-off.
+    #
+    # Runs a background task that loops until a connection is
+    # established or the engine is closed. Caller is non-blocking:
+    # {Engine#connect} returns immediately and the actual dial happens
+    # inside the task.
+    #
+    class Reconnect
+      # @param endpoint [String]
+      # @param options [Options]
+      # @param parent_task [Async::Task]
+      # @param engine [Engine]
+      # @param delay [Numeric, nil] initial delay (defaults to reconnect_interval)
+      def self.schedule(endpoint, options, parent_task, engine, delay: nil)
+        new(engine, endpoint, options).run(parent_task, delay: delay)
+      end
+
+
+      def initialize(engine, endpoint, options)
+        @engine   = engine
+        @endpoint = endpoint
+        @options  = options
+      end
+
+
+      def run(parent_task, delay: nil)
+        delay, max_delay = init_delay(delay)
+
+        parent_task.async(transient: true, annotation: "nnq reconnect #{@endpoint}") do
+          loop do
+            break if @engine.closed?
+            sleep quantized_wait(delay) if delay > 0
+            break if @engine.closed?
+            begin
+              @engine.transport_for(@endpoint).connect(@endpoint, @engine)
+              break
+            rescue *CONNECTION_FAILED, *CONNECTION_LOST => e
+              delay = next_delay(delay, max_delay)
+              @engine.emit_monitor_event(:connect_retried, endpoint: @endpoint, detail: { interval: delay, error: e })
+            end
+          end
+        rescue Async::Stop
+        end
+      end
+
+
+      private
+
+
+      # Wall-clock quantized sleep: wait until the next +delay+-sized
+      # grid tick. Multiple clients reconnecting with the same interval
+      # wake up at the same instant, collapsing staggered retries into
+      # aligned waves.
+      def quantized_wait(delay, now = Time.now.to_f)
+        wait = delay - (now % delay)
+        wait.positive? ? wait : delay
+      end
+
+
+      def init_delay(delay)
+        ri = @options.reconnect_interval
+        if ri.is_a?(Range)
+          [delay || ri.begin, ri.end]
+        else
+          [delay || ri, nil]
+        end
+      end
+
+
+      def next_delay(delay, max_delay)
+        ri = @options.reconnect_interval
+        if ri.is_a?(Range)
+          delay = delay * 2
+          delay = [delay, max_delay].min if max_delay
+          delay = ri.begin if delay == 0
+          delay
+        else
+          ri
+        end
+      end
+    end
+  end
+end

data/lib/nnq/engine/socket_lifecycle.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "async/barrier"
+require "async/promise"
+
 module NNQ
   class Engine
     # Owns the socket-level state: `:new → :open → :closing → :closed`
@@ -31,11 +34,34 @@ module NNQ
       # @return [Boolean] true if parent_task is the shared Reactor thread
       attr_reader :on_io_thread
 
+      # @return [Async::Promise] resolves with the first connected peer
+      #   (or nil if the socket closes before anyone connects)
+      attr_reader :peer_connected
+
+      # @return [Async::Promise] resolves with true the first time the
+      #   connection set becomes empty after at least one peer connected.
+      #   Edge-triggered: does not re-arm on reconnect.
+      attr_reader :all_peers_gone
+
+      # @return [Async::Barrier, nil] holds every socket-scoped task
+      #   (connection supervisors, reconnect loops, accept loops).
+      #   {Engine#close} calls +barrier.stop+ to cascade teardown
+      #   through every per-connection barrier in one shot.
+      attr_reader :barrier
+
+      # @return [Boolean] when false, the engine must not schedule new
+      #   reconnect attempts. Default true.
+      attr_accessor :reconnect_enabled
+
 
       def initialize
-        @state        = :new
-        @parent_task  = nil
-        @on_io_thread = false
+        @state             = :new
+        @parent_task       = nil
+        @on_io_thread      = false
+        @peer_connected    = Async::Promise.new
+        @all_peers_gone    = Async::Promise.new
+        @reconnect_enabled = true
+        @barrier           = nil
       end
 
 
@@ -56,6 +82,7 @@ module NNQ
         return false if @parent_task
         @parent_task  = task
         @on_io_thread = on_io_thread
+        @barrier      = Async::Barrier.new(parent: @parent_task)
         transition!(:open)
         true
       end
@@ -74,6 +101,16 @@ module NNQ
       end
 
 
+      # Resolves `all_peers_gone` if we had peers and now have none.
+      # Idempotent.
+      # @param connections [Hash] current connection map
+      def resolve_all_peers_gone_if_empty(connections)
+        return unless @peer_connected.resolved? && connections.empty?
+        return if @all_peers_gone.resolved?
+        @all_peers_gone.resolve(true)
+      end
+
+
       private
 
       def transition!(new_state)