nnq 0.7.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c55340c77dffd3e4fdbc8419fb463e608a6e635adc577582e295b8af20fdc3e0
-  data.tar.gz: 6bb76f07c3732a4e69ad9a8e93a6a852f5ca04aac40fedc0df346ec9a2d74297
+  metadata.gz: 559ecdf415aadfb477c89de0594cbaa5260a567664196c218c9315d2ad93e42c
+  data.tar.gz: a732f598f7558f0e174a30b2f146bed2a9287883bb0614418fdd9d60b0271df5
 SHA512:
-  metadata.gz: 1cb190f96ace0a94363ea6a0b24b9d8b563363fbb3fb84e0bb4927a8ef818949270f20dec984828405bd15068400ace40aa5a9017d52321e2f9e10aa5235d973
-  data.tar.gz: 036a2a8203a7a26afad8d67fd23d9606d4947561ec0d8d31893b6efb116b62f623560afc6a4293fdbbd8846c39fa76aa9885eb47c9ab11900d552f5bc4377ecd
+  metadata.gz: 511582392bd0d3a18b032158ab13215fe33f469e0b46d1d2ddc03b9f10cfdf433b37cb24dc1ba40a42721d34a774844a3a05e8eb68d463bfa9a8fde5204ae0ca
+  data.tar.gz: 9d40868d84ae3ccb1fd78aba9bf88c0f0fb3f4646a330b56a424e31d89d57358d686a3feb8df4e1f761519e80cd0c5ab3170a0c7e06019715e8ee817eb9d0b27

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.8.2 — 2026-04-20
+
+- **`:message_received` verbose events carry `wire_size:`.** The
+  engine recv loop now reads `conn.last_wire_size_in` (duck-typed,
+  nil-safe) and passes it through `emit_verbose_msg_received` into
+  the monitor event detail, so compression decorators like nnq-zstd
+  can surface the compressed on-the-wire byte count to `-vvv`
+  traces. Plain transports are unaffected (`wire_size: nil`).
+
+## 0.8.1 — 2026-04-19
+
+- **Fix close-race in `ConnectionLifecycle#tear_down!`.** The fd was
+  closed before sibling pumps were cancelled, which woke recv fibers
+  parked in `io_wait` with `IOError: stream closed in another thread`.
+  `@barrier.stop` now runs before `@conn.close`, so blocking reads
+  unwind via `Async::Stop` before the fd goes away.
+
+## 0.8.0 — 2026-04-19
+
+- **Uniform frozen + `BINARY` message contract across transports.**
+  `Socket#coerce_binary` replaces the old `frozen_binary` + `.b.freeze`
+  copy on the hot send path. Every send method runs its body through
+  `coerce_binary`, which:
+  - coerces non-String bodies via `#to_str` (nil / `42` / `:foo` raise
+    `NoMethodError` instead of producing a zero-byte frame);
+  - re-tags unfrozen non-BINARY bodies to `Encoding::BINARY` in place —
+    a flag flip, no copy;
+  - freezes the body.
+
+  Receivers always see a frozen BINARY-tagged body: TCP/IPC get it via
+  the recv-pump freeze, inproc gets it via `Pipe#send_message`, which
+  only allocates for the pathological case of a frozen non-BINARY body
+  (the typical `# frozen_string_literal: true` UTF-8 literal). Bodies
+  returned by REP/REQ/SURVEYOR/RESPONDENT (cooked and raw) are frozen
+  by `parse_backtrace` and the REQ/SURVEYOR id-parsing paths. Mutation
+  bugs surface as `FrozenError` instead of silently corrupting a shared
+  reference on the inproc fast path. Inproc throughput pays ~20-30%
+  for the contract; TCP/IPC unaffected.
+
+- **Benchmarks send fresh strings per iteration.** `BenchHelper.run`
+  passes an unfrozen `"x" * size` through to the burst closure; the
+  `measure` / `measure_roundtrip` bursts `.dup` it before each send.
+  More realistic than reusing one frozen payload and hitting every
+  fast path in `coerce_binary` + `Pipe#send_message`.
+
 ## 0.7.0 — 2026-04-18
 
 - **Inproc transport now uses a queue-based `Inproc::Pipe`** instead
@@ -20,15 +65,6 @@
   PAIR, SUB, REP, RESPONDENT, SURVEYOR, and the `*_raw` variants all
   implement the hook; REQ (promise-based) stays on the fiber path.
   Cuts three fiber hops to one on the steady-state recv path.
-
-  Inproc PUSH/PULL single-peer throughput (Ruby 4.0.2):
-
-  | Size   | Before (no JIT) | After (no JIT) | After (+YJIT) |
-  |---|---|---|---|
-  | 128 B  |  122k msg/s |  350k msg/s | 1,226k msg/s |
-  | 2 KiB  |   87k msg/s |  360k msg/s | 1,458k msg/s |
-  | 32 KiB |   21k msg/s |  261k msg/s |   887k msg/s |
-
 - **Routing pumps shed their `@pump_tasks` bookkeeping.** `bus`, `pub`,
   `surveyor`, and `surveyor_raw` no longer track per-connection pump
   tasks in a hash. Pumps are spawned under

data/lib/nnq/bus.rb

@@ -13,7 +13,7 @@ module NNQ
   #
   class BUS0 < Socket
     def send(body)
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 

data/lib/nnq/engine/connection_lifecycle.rb

@@ -151,6 +151,11 @@ module NNQ
       def tear_down!(reconnect: false)
         return if @state == :closed
         transition!(:closed)
+        # Cancel sibling pumps BEFORE closing the fd. If we close first,
+        # any pump still parked in io_wait wakes up with
+        # `IOError: stream closed in another thread`. The caller is the
+        # supervisor task, which is NOT in the barrier — no self-stop.
+        @barrier.stop
         if @conn
           @engine.connections.delete(@conn)
           @engine.routing.connection_removed(@conn) if @engine.routing.respond_to?(:connection_removed)
@@ -159,10 +164,6 @@ module NNQ
           @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
 
 

data/lib/nnq/engine.rb

@@ -118,10 +118,12 @@ module NNQ
 
 
     # Emits a :message_received verbose event. Same early-return
-    # discipline as {#emit_verbose_msg_sent}.
-    def emit_verbose_msg_received(body)
+    # discipline as {#emit_verbose_msg_sent}. +wire_size+ is the
+    # on-the-wire byte count when the connection is wrapped by a
+    # compression decorator (nnq-zstd); nil for plain transports.
+    def emit_verbose_msg_received(body, wire_size: nil)
       return unless @verbose_monitor
-      emit_monitor_event(:message_received, detail: { body: body })
+      emit_monitor_event(:message_received, detail: { body: body, wire_size: wire_size })
     end
 
 
@@ -382,10 +384,11 @@ module NNQ
 
       @connections[conn].barrier.async(annotation: "nnq recv #{conn.endpoint}") do
         loop do
-          body = conn.receive_message
+          body = conn.receive_message.freeze
           if @verbose_monitor
-            preview = @routing.respond_to?(:preview_body) ? @routing.preview_body(body) : body
-            emit_verbose_msg_received(preview)
+            preview   = @routing.respond_to?(:preview_body) ? @routing.preview_body(body) : body
+            wire_size = conn.respond_to?(:last_wire_size_in) ? conn.last_wire_size_in : nil
+            emit_verbose_msg_received(preview, wire_size: wire_size)
           end
           @routing.enqueue(body, conn)
         rescue *CONNECTION_LOST, Async::Stop

data/lib/nnq/pair.rb

@@ -10,7 +10,7 @@ module NNQ
   #
   class PAIR0 < Socket
     def send(body)
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 

data/lib/nnq/pub_sub.rb

@@ -12,7 +12,7 @@ module NNQ
   #
   class PUB0 < Socket
     def send(body)
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 

data/lib/nnq/push_pull.rb

@@ -11,7 +11,7 @@ module NNQ
   #
   class PUSH0 < Socket
     def send(body)
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body) }
     end
 

data/lib/nnq/req_rep.rb

@@ -18,7 +18,7 @@ module NNQ
     # raw mode — use {#send} / {#receive} there.
     def send_request(body)
       raise Error, "REQ#send_request not available in raw mode" if raw?
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send_request(body) }
     end
 
@@ -29,7 +29,7 @@ module NNQ
     # cooked mode.
     def send(body, header:)
       raise Error, "REQ#send not available in cooked mode" unless raw?
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body, header: header) }
     end
 
@@ -74,7 +74,7 @@ module NNQ
     # came from. Raises in raw mode.
     def send_reply(body)
       raise Error, "REP#send_reply not available in raw mode" if raw?
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send_reply(body) }
     end
 
@@ -84,7 +84,7 @@ module NNQ
     # tuple). Silent drop if +to+ is closed. Raises in cooked mode.
     def send(body, to:, header:)
       raise Error, "REP#send not available in cooked mode" unless raw?
-      body = frozen_binary(body)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body, to: to, header: header) }
     end
 

data/lib/nnq/routing/backtrace.rb

@@ -27,7 +27,7 @@ module NNQ
           hops   += 1
 
           if word.getbyte(0) & 0x80 != 0
-            return [body.byteslice(0, offset), body.byteslice(offset..)]
+            return [body.byteslice(0, offset).freeze, body.byteslice(offset..).freeze]
           end
         end
 

data/lib/nnq/routing/req.rb

@@ -71,7 +71,7 @@ module NNQ
       def enqueue(body, _conn)
         return if body.bytesize < 4
         id      = body.unpack1("N")
-        payload = body.byteslice(4..)
+        payload = body.byteslice(4..).freeze
 
         @mutex.synchronize do
           if @outstanding && @outstanding[0] == id

data/lib/nnq/routing/surveyor.rb

@@ -67,7 +67,7 @@ module NNQ
         return if body.bytesize < 4
 
         id      = body.unpack1("N")
-        payload = body.byteslice(4..)
+        payload = body.byteslice(4..).freeze
 
         @mutex.synchronize do
           return unless @current_id == id
@@ -84,7 +84,7 @@ module NNQ
         transform = lambda do |body|
           next nil if body.bytesize < 4
           id      = body.unpack1("N")
-          payload = body.byteslice(4..)
+          payload = body.byteslice(4..).freeze
           match   = mutex.synchronize { @current_id == id }
           match ? payload : nil
         end

data/lib/nnq/socket.rb

@@ -135,16 +135,21 @@ 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).
+    # Coerces +body+ to a frozen `Encoding::BINARY`-tagged String and
+    # returns it. Every send method runs its body through this so the
+    # receiver sees a uniform frozen+BINARY contract across transports
+    # (mutation bugs raise `FrozenError` instead of silently corrupting
+    # a shared reference on the inproc fast path).
     #
-    # Fast-path: already frozen + binary → returned as-is.
-    def frozen_binary(body)
-      return body if body.frozen? && body.encoding == Encoding::BINARY
-      body.b.freeze
+    # Fast-path: unfrozen non-BINARY strings are re-tagged in place
+    # (force_encoding is a flag flip, no copy). The pathological case
+    # of a frozen non-BINARY body (e.g. a `# frozen_string_literal: true`
+    # literal) can't be re-tagged in place — the inproc {Pipe} handles
+    # that with a copy so the receive contract stays uniform.
+    def coerce_binary(body)
+      body = body.to_str unless body.is_a?(String)
+      body.force_encoding(Encoding::BINARY) unless body.frozen? || body.encoding == Encoding::BINARY
+      body.freeze
     end
 
 

data/lib/nnq/surveyor_respondent.rb

@@ -16,7 +16,7 @@ module NNQ
     # 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)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send_survey(body) }
     end
 
@@ -26,7 +26,7 @@ module NNQ
     # 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)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body, header: header) }
     end
 
@@ -70,7 +70,7 @@ module NNQ
     # 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)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send_reply(body) }
     end
 
@@ -78,7 +78,7 @@ module NNQ
     # 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)
+      body = coerce_binary(body)
       Reactor.run { @engine.routing.send(body, to: to, header: header) }
     end
 

data/lib/nnq/transport/inproc/pipe.rb

@@ -69,7 +69,14 @@ module NNQ
 
         def send_message(body, header: nil)
           raise ClosedError, "connection closed" if @closed
-          wire = header ? header + body : body
+
+          # Socket#coerce_binary tags mutable bodies BINARY in place;
+          # the pathological case of a frozen non-BINARY body (e.g. a
+          # `# frozen_string_literal: true` literal) can't be re-tagged
+          # in place, so copy it here to keep the receiver contract
+          # uniform with TCP/IPC.
+          body = body.b.freeze if body.encoding != Encoding::BINARY
+          wire = header ? (header + body).freeze : body
 
           if (q = @direct_recv_queue)
             item = @direct_recv_transform ? @direct_recv_transform.call(wire) : wire
@@ -86,6 +93,10 @@ module NNQ
         def write_messages(bodies)
           raise ClosedError, "connection closed" if @closed
 
+          if bodies.any? { |b| b.encoding != Encoding::BINARY }
+            bodies = bodies.map { |b| b.encoding == Encoding::BINARY ? b : b.b.freeze }
+          end
+
           if (q = @direct_recv_queue)
             transform = @direct_recv_transform
             bodies.each do |body|

data/lib/nnq/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nnq
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Patrik Wenger
@@ -41,16 +41,16 @@ dependencies:
   name: protocol-sp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 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.