omq 0.19.0 → 0.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f01c18a7a887e0f2811abff2251f1b2c9b201091e800248fb852b92bedbcaf06
-  data.tar.gz: d32b3e07223d906a3bb25fc8542409bb5c05af36b509f7fe70c91419d0836cf9
+  metadata.gz: 77ae2b0a529e29f7c7c48478db4b9b0d81955b28dca48cd17c4f5dfb1dbfd118
+  data.tar.gz: 2ec4f56b9893527d6458e366835878902d3ec254893de2fa0e7579d52be73438
 SHA512:
-  metadata.gz: c0b26ad39e26fe586cec53371bc4b1beeaf357b51f32e90ad8d889a8413f62c08c13be2d8f787e3528d4fca6bccc1ceae21454474465aff25f9418c37460d957
-  data.tar.gz: b8d3acedee187c9c757268af173b55bd28daf502f8e054f92ef670c59a1781e2b2f73267425c239d27acc7cb036b0030ab562a12918c7db205dc34f4bcf8e38d
+  metadata.gz: af73f9a2031c776167a616fe2e63775cd036c6f02f24cdb65059a4ffb81572e2747a9a4f662b96bd7574ecac3d48114f7ea3569bfbc1f6f3bc0f571a523df1ca
+  data.tar.gz: e919e6bce582848096c692a76e63081b038fb77a9796e914f2265c1825d36017278d46b014b639bbc100935be3ae82af1ac1bfde29951e49e2643ac942d6c251

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.19.3 — 2026-04-13
+
+### Changed
+
+- Engine no longer reaches into `routing.recv_queue` directly.
+  Routing strategies now expose `#dequeue_recv` and `#unblock_recv`
+  as the engine-facing recv contract. `FairRecv` provides the
+  shared implementation for fair-queued sockets; sub/xsub/xpub
+  delegate inline; write-only push/pub raise on dequeue and no-op
+  on unblock. Sharpens the routing interface and keeps Engine out
+  of queue internals.
+- `Writable#freeze_message` collapsed: single `all?` predicate
+  check drives three outcomes (already-frozen-array fast path,
+  freeze-in-place, convert-via-map/map!) instead of mirrored
+  fast/slow branches that each repeated the predicate.
+- Hot-path optimized. Avoid the overhead of `parts.sum(&:bytesize)`
+  and use `parts.sum { |p| p.bytesize }` instead.
+
+## 0.19.2 — 2026-04-13
+
+### Added
+
+- **`:disconnected` monitor events carry the underlying error.** When
+  a connection drops due to a `Protocol::ZMTP::Error` (oversized
+  frame, bad framing, zstd bytebomb, nonce exhaustion, …) or a
+  `CONNECTION_LOST` error, the `:disconnected` event's `detail` hash
+  now includes `error:` (the exception instance) and `reason:` (its
+  message). Peer tooling can match on `detail[:error].is_a?(...)` to
+  enforce its own policy — e.g. `omq-cli` terminates the command on
+  `Protocol::ZMTP::Error`, while the library keeps the libzmq-parity
+  behavior of silently dropping the offending connection and
+  reconnecting.
+- **`OMQ::Socket#engine` public reader.** The socket's engine is now
+  a documented (if low-level) accessor for peer tooling that needs
+  to reach into internals — notably so `omq-cli`'s monitor callback
+  can call `sock.engine.signal_fatal_error(error)` without
+  `instance_variable_get`. Not part of the stable user API.
+
+### Fixed
+
+- **`signal_fatal_error` preserves the underlying cause.** The
+  resulting `SocketDeadError` now chains back to the original error
+  via `Exception#cause` regardless of whether `signal_fatal_error`
+  is called from inside a rescue block or from a monitor callback
+  (where `$!` is `nil`). Uses a raise-in-rescue helper to force the
+  cause chain. The wrapped error's message also includes the
+  original reason so tooling that only logs the top-level message
+  still shows what happened.
+
+## 0.19.1 — 2026-04-13
+
+### Fixed
+
+- **Send-queue batch accounting tolerates non-string parts.**
+  `Routing::RoundRobin#drain_send_queue_capped` previously called
+  `#bytesize` directly on each message part for the fairness cap, which
+  crashed when a connection wrapper enqueued structured parts for later
+  transformation (notably `OMQ::Ractor`'s `MarshalConnection`, which
+  hands off live Ruby objects and marshals them in `#write_messages`).
+  The fairness cap now skips parts that don't respond to `#bytesize`.
+
 ## 0.19.0 — 2026-04-12
 
 ### Added

data/lib/omq/engine/connection_lifecycle.rb

@@ -133,8 +133,18 @@ module OMQ
       # routing removal, monitor event, reconnect scheduling.
       # Idempotent: a no-op if already :closed.
       #
-      def lost!
-        tear_down!(reconnect: true)
+      def lost!(reason: nil)
+        tear_down!(reconnect: true, reason: reason || @disconnect_reason)
+      end
+
+
+      # Records the exception that took down a pump task so that the
+      # supervisor can surface it in the :disconnected monitor event.
+      # First writer wins — subsequent pumps unwinding on the same
+      # teardown don't overwrite the original cause.
+      #
+      def record_disconnect_reason(error)
+        @disconnect_reason ||= error
       end
 
 
@@ -187,21 +197,20 @@ module OMQ
           end
         rescue Async::Stop, Async::Cancel
           # socket or supervisor cancelled externally (socket closing)
-        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-          # expected pump exit on disconnect
         ensure
           lost!
         end
       end
 
 
-      def tear_down!(reconnect:)
+      def tear_down!(reconnect:, reason: nil)
         return if @state == :closed
         transition!(:closed)
         @engine.connections.delete(@conn)
         @engine.routing.connection_removed(@conn) if @conn
         @conn&.close rescue nil
-        @engine.emit_monitor_event(:disconnected, endpoint: @endpoint)
+        detail = reason ? { error: reason, reason: reason.message } : nil
+        @engine.emit_monitor_event(:disconnected, endpoint: @endpoint, detail: detail)
         @done&.resolve(true)
         @engine.resolve_all_peers_gone_if_empty
         @engine.maybe_reconnect(@endpoint) if reconnect

data/lib/omq/engine/recv_pump.rb

@@ -91,25 +91,31 @@ module OMQ
           loop do
             count = 0
             bytes = 0
+
             while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
               msg = conn.receive_message
               msg = transform.call(msg).freeze
+
               # Emit the verbose trace BEFORE enqueueing so the monitor
               # fiber is woken before the application fiber -- the
               # async scheduler is FIFO on the ready list, so this
               # preserves log-before-stdout ordering for -vvv traces.
               engine.emit_verbose_msg_received(conn, msg)
               recv_queue.enqueue(msg)
+
               count += 1
-              bytes += msg.sum(&:bytesize) if count_bytes
+              bytes += msg.sum { |part| part.bytesize } if count_bytes
             end
+
             task.yield
           end
         rescue Async::Stop, Async::Cancel
-        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-          # expected disconnect — supervisor will trigger teardown
+        rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
+          # expected disconnect — stash reason for the :disconnected
+          # monitor event, let the lifecycle reconnect as usual
+          engine.connections[conn]&.record_disconnect_reason(error)
         rescue => error
-          @engine.signal_fatal_error(error)
+          engine.signal_fatal_error(error)
         end
       end
 
@@ -131,15 +137,17 @@ module OMQ
               engine.emit_verbose_msg_received(conn, msg)
               recv_queue.enqueue(msg)
               count += 1
-              bytes += msg.sum(&:bytesize) if count_bytes
+              bytes += msg.sum { |part| part.bytesize } if count_bytes
             end
             task.yield
           end
         rescue Async::Stop, Async::Cancel
-        rescue Protocol::ZMTP::Error, *CONNECTION_LOST
-          # expected disconnect — supervisor will trigger teardown
+        rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
+          # expected disconnect — stash reason for the :disconnected
+          # monitor event, let the lifecycle reconnect as usual
+          engine.connections[conn]&.record_disconnect_reason(error)
         rescue => error
-          @engine.signal_fatal_error(error)
+          engine.signal_fatal_error(error)
         end
       end
 

data/lib/omq/engine.rb

@@ -80,6 +80,7 @@ module OMQ
     #
     attr_reader :connections, :tasks, :lifecycle
 
+
     # @!attribute [w] monitor_queue
     #   @param value [Async::Queue, nil] queue for monitor events
     #
@@ -116,7 +117,9 @@ module OMQ
     def spawn_inproc_retry(endpoint)
       ri  = @options.reconnect_interval
       ivl = ri.is_a?(Range) ? ri.begin : ri
-      @tasks << @lifecycle.barrier.async(transient: true, annotation: "inproc reconnect #{endpoint}") do
+      ann = "inproc reconnect #{endpoint}"
+
+      @tasks << @lifecycle.barrier.async(transient: true, annotation: ann) do
         yield ivl
       rescue Async::Stop, Async::Cancel
       end
@@ -134,7 +137,9 @@ module OMQ
       capture_parent_task(parent: parent)
       transport = transport_for(endpoint)
       listener  = transport.bind(endpoint, self)
+
       start_accept_loops(listener)
+
       @listeners << listener
       @last_endpoint = listener.endpoint
       @last_tcp_port = listener.respond_to?(:port) ? listener.port : nil
@@ -155,6 +160,7 @@ module OMQ
       capture_parent_task(parent: parent)
       validate_endpoint!(endpoint)
       @dialed.add(endpoint)
+
       if endpoint.start_with?("inproc://")
         # Inproc connect is synchronous and instant
         transport = transport_for(endpoint)
@@ -188,6 +194,7 @@ module OMQ
     def unbind(endpoint)
       listener = @listeners.find { |l| l.endpoint == endpoint }
       return unless listener
+
       listener.stop
       @listeners.delete(listener)
       close_connections_at(endpoint)
@@ -235,8 +242,10 @@ module OMQ
     #
     def dequeue_recv
       raise @fatal_error if @fatal_error
-      msg = routing.recv_queue.dequeue
+
+      msg = routing.dequeue_recv
       raise @fatal_error if msg.nil? && @fatal_error
+
       msg
     end
 
@@ -245,7 +254,7 @@ module OMQ
     # pending {#dequeue_recv} with a nil return value.
     #
     def dequeue_recv_sentinel
-      routing.recv_queue.push(nil)
+      routing.unblock_recv
     end
 
 
@@ -274,6 +283,7 @@ module OMQ
       # pumps when the connection is lost.
       parent = @connections[conn]&.barrier || @lifecycle.barrier
       task   = RecvPump.start(parent, conn, recv_queue, self, transform)
+
       @tasks << task if task
       task
     end
@@ -316,11 +326,20 @@ module OMQ
     #
     def close
       return unless @lifecycle.open?
+
       @lifecycle.start_closing!
       stop_listeners unless @connections.empty?
-      drain_send_queues(@options.linger) if @options.linger.nil? || @options.linger > 0
+
+      if @options.linger.nil? || @options.linger > 0
+        drain_send_queues(@options.linger)
+      end
+
       @lifecycle.finish_closing!
-      Reactor.untrack_linger(@options.linger) if @lifecycle.on_io_thread
+
+      if @lifecycle.on_io_thread
+        Reactor.untrack_linger(@options.linger)
+      end
+
       stop_listeners
       tear_down_barrier
       routing.stop rescue nil
@@ -337,9 +356,14 @@ module OMQ
     #
     def stop
       return unless @lifecycle.alive?
+
       @lifecycle.start_closing! if @lifecycle.open?
       @lifecycle.finish_closing!
-      Reactor.untrack_linger(@options.linger) if @lifecycle.on_io_thread
+
+      if @lifecycle.on_io_thread
+        Reactor.untrack_linger(@options.linger)
+      end
+
       stop_listeners
       tear_down_barrier
       routing.stop rescue nil
@@ -386,8 +410,12 @@ module OMQ
 
       lifecycle.barrier.async(transient: true, annotation: annotation) do
         yield
-      rescue Async::Stop, Async::Cancel, Protocol::ZMTP::Error, *CONNECTION_LOST
-        # normal shutdown / expected disconnect / sibling tore us down
+      rescue Async::Stop, Async::Cancel
+        # normal shutdown / sibling tore us down
+      rescue Protocol::ZMTP::Error, *CONNECTION_LOST => error
+        # expected disconnect — stash reason for the :disconnected
+        # monitor event, then let the lifecycle reconnect as usual
+        lifecycle.record_disconnect_reason(error)
       rescue => error
         signal_fatal_error(error)
       end
@@ -395,22 +423,33 @@ module OMQ
 
 
     # Wraps an unexpected pump error as {OMQ::SocketDeadError} and
-    # unblocks any callers waiting on the recv queue.
-    #
-    # Must be called from inside a rescue block so that +error+ is
-    # +$!+ and Ruby sets it as +#cause+ on the new exception.
+    # unblocks any callers waiting on the recv queue. The original
+    # error is preserved as +#cause+ so callers can surface the real
+    # reason.
     #
     # @param error [Exception]
     #
     def signal_fatal_error(error)
       return unless @lifecycle.open?
-      @fatal_error = begin
-        raise SocketDeadError, "internal error killed #{@socket_type} socket"
-      rescue => wrapped
+
+      @fatal_error = build_fatal_error(error)
+      routing.unblock_recv rescue nil
+      @lifecycle.peer_connected.resolve(nil) rescue nil
+    end
+
+
+    # Constructs a SocketDeadError whose +cause+ is +error+. Uses the
+    # raise-in-rescue idiom because Ruby only sets +cause+ on an
+    # exception when it is raised from inside a rescue block -- works
+    # regardless of the original caller's +$!+ state.
+    def build_fatal_error(error)
+      raise error
+    rescue
+      begin
+        raise SocketDeadError, "#{@socket_type} socket killed: #{error.message}"
+      rescue SocketDeadError => wrapped
         wrapped
       end
-      routing.recv_queue.push(nil) rescue nil
-      @lifecycle.peer_connected.resolve(nil) rescue nil
     end
 
 
@@ -428,7 +467,10 @@ module OMQ
     # @param parent [#async, nil] optional Async parent
     #
     def capture_parent_task(parent: nil)
-      return unless @lifecycle.capture_parent_task(parent: parent, linger: @options.linger)
+      task = @lifecycle.capture_parent_task(parent: parent, linger: @options.linger)
+
+      return unless task
+
       Maintenance.start(@lifecycle.barrier, @options.mechanism, @tasks)
     end
 
@@ -477,8 +519,13 @@ module OMQ
     # +last_wire_size_in+.
     def emit_verbose_msg_received(conn, parts)
       return unless @verbose_monitor
+
       detail = { parts: parts }
-      detail[:wire_size] = conn.last_wire_size_in if conn.respond_to?(:last_wire_size_in)
+
+      if conn.respond_to?(:last_wire_size_in)
+        detail[:wire_size] = conn.last_wire_size_in
+      end
+
       emit_monitor_event(:message_received, detail: detail)
     end
 
@@ -490,9 +537,14 @@ module OMQ
     # @raise [ArgumentError] if the scheme is not registered
     #
     def transport_for(endpoint)
-      scheme = endpoint[/\A([^:]+):\/\//, 1]
-      self.class.transports[scheme] or
+      scheme    = endpoint[/\A([^:]+):\/\//, 1]
+      transport = self.class.transports[scheme]
+
+      unless transport
         raise ArgumentError, "unsupported transport: #{endpoint}"
+      end
+
+      transport
     end
 
 
@@ -514,6 +566,7 @@ module OMQ
       ensure
         lifecycle&.close!
       end
+
       @tasks << task if task
     end
 
@@ -525,7 +578,11 @@ module OMQ
     # every routing strategy, so it is flagged rather than fixed here.
     def drain_send_queues(timeout)
       return unless @routing.respond_to?(:send_queues_drained?)
-      deadline = timeout ? Async::Clock.now + timeout : nil
+
+      if timeout
+        deadline = Async::Clock.now + timeout
+      end
+
       until @routing.send_queues_drained?
         break if deadline && (deadline - Async::Clock.now) <= 0
         sleep 0.001
@@ -540,12 +597,16 @@ module OMQ
 
     def validate_endpoint!(endpoint)
       transport = transport_for(endpoint)
-      transport.validate_endpoint!(endpoint) if transport.respond_to?(:validate_endpoint!)
+
+      if transport.respond_to?(:validate_endpoint!)
+        transport.validate_endpoint!(endpoint)
+      end
     end
 
 
     def start_accept_loops(listener)
       return unless listener.respond_to?(:start_accept_loops)
+
       listener.start_accept_loops(@lifecycle.barrier) do |io|
         handle_accepted(io, endpoint: listener.endpoint)
       end

data/lib/omq/routing/conn_send_pump.rb

@@ -37,6 +37,7 @@ module OMQ
         tasks << task
         task
       end
+
     end
   end
 end

data/lib/omq/routing/dealer.rb

@@ -11,6 +11,11 @@ module OMQ
       include FairRecv
 
 
+      # @return [FairQueue]
+      #
+      attr_reader :recv_queue
+
+
       # @param engine [Engine]
       #
       def initialize(engine)
@@ -21,11 +26,6 @@ module OMQ
       end
 
 
-      # @return [FairQueue]
-      #
-      attr_reader :recv_queue
-
-
       # @param connection [Connection]
       #
       def connection_added(connection)
@@ -58,6 +58,7 @@ module OMQ
         @tasks.each(&:stop)
         @tasks.clear
       end
+
     end
   end
 end

data/lib/omq/routing/fair_queue.rb

@@ -74,7 +74,9 @@ module OMQ
         return try_dequeue if timeout == 0
 
         loop do
-          return nil if @closed && @drain.empty? && @queues.all?(&:empty?)
+          if @closed && @drain.empty? && @queues.all? { |q| q.empty? }
+            return nil
+          end
 
           msg = try_dequeue
           return msg if msg
@@ -101,7 +103,7 @@ module OMQ
       # @return [Boolean]
       #
       def empty?
-        @drain.empty? && @queues.all?(&:empty?)
+        @drain.empty? && @queues.all? { |q| q.empty? }
       end
 
 
@@ -132,6 +134,7 @@ module OMQ
           msg = q.dequeue(timeout: 0)
           return msg if msg
         end
+
         nil
       end
     end

data/lib/omq/routing/fair_recv.rb

@@ -7,6 +7,26 @@ module OMQ
     # Including classes must have @engine, @recv_queue (FairQueue), and @tasks.
     #
     module FairRecv
+      # Dequeues the next received message. Blocks until one is available.
+      # Engine-facing contract — Engine must not touch @recv_queue directly.
+      #
+      # @return [Array<String>, nil]
+      #
+      def dequeue_recv
+        @recv_queue.dequeue
+      end
+
+
+      # Wakes a blocked {#dequeue_recv} with a nil sentinel. Called by
+      # Engine on close (close_read) or fatal-error propagation.
+      #
+      # @return [void]
+      #
+      def unblock_recv
+        @recv_queue.push(nil)
+      end
+
+
       private
 
       # Creates a per-connection recv queue, registers it with @recv_queue,
@@ -18,10 +38,16 @@ module OMQ
       def add_fair_recv_connection(conn, &transform)
         conn_q    = Routing.build_queue(@engine.options.recv_hwm, :block)
         signaling = SignalingQueue.new(conn_q, @recv_queue)
+
         @recv_queue.add_queue(conn, conn_q)
-        task      = @engine.start_recv_pump(conn, signaling, &transform)
-        @tasks << task if task
+
+        task = @engine.start_recv_pump(conn, signaling, &transform)
+
+        if task
+          @tasks << task
+        end
       end
+
     end
   end
 end

data/lib/omq/routing/fan_out.rb

@@ -134,7 +134,9 @@ module OMQ
           loop do
             frame = conn.read_frame
             next unless frame.command?
+
             cmd = Protocol::ZMTP::Codec::Command.from_body(frame.body)
+
             case cmd.name
             when "SUBSCRIBE"
               on_subscribe(conn, cmd.data)
@@ -157,7 +159,13 @@ module OMQ
       #
       def start_conn_send_pump(conn, q)
         use_wire = conn.respond_to?(:write_wire) && !conn.encrypted?
-        task     = @conflate ? start_conn_send_pump_conflate(conn, q) : start_conn_send_pump_normal(conn, q, use_wire)
+
+        if @conflate
+          task = start_conn_send_pump_conflate(conn, q)
+        else
+          task = start_conn_send_pump_normal(conn, q, use_wire)
+        end
+
         @conn_send_tasks[conn] = task
         @tasks << task
       end
@@ -177,6 +185,7 @@ module OMQ
           loop do
             batch = [q.dequeue]
             Routing.drain_send_queue(q, batch)
+
             if write_matching_batch(conn, batch, use_wire)
               conn.flush
               batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
@@ -193,15 +202,19 @@ module OMQ
       #
       def write_matching_batch(conn, batch, use_wire)
         sent = false
+
         batch.each do |parts|
           next unless subscribed?(conn, parts.first || EMPTY_BINARY)
+
           if use_wire
             conn.write_wire(Protocol::ZMTP::Codec::Frame.encode_message(parts))
           else
             conn.write_message(parts)
           end
+
           sent = true
         end
+
         sent
       end
 

data/lib/omq/routing/pair.rb

@@ -12,6 +12,12 @@ module OMQ
     class Pair
       include FairRecv
 
+
+      # @return [FairQueue]
+      #
+      attr_reader :recv_queue
+
+
       # @param engine [Engine]
       #
       def initialize(engine)
@@ -24,10 +30,6 @@ module OMQ
       end
 
 
-      # @return [FairQueue]
-      #
-      attr_reader :recv_queue
-
       # @param connection [Connection]
       # @raise [RuntimeError] if a connection already exists
       #
@@ -83,24 +85,32 @@ module OMQ
         @send_queue.empty?
       end
 
+
       private
 
+
       def start_send_pump(conn)
         @send_pump = @engine.spawn_conn_pump_task(conn, annotation: "send pump") do
           loop do
             batch = [@send_queue.dequeue]
             Routing.drain_send_queue(@send_queue, batch)
+
             if batch.size == 1
               conn.write_message(batch[0])
             else
               conn.write_messages(batch)
             end
+
             conn.flush
-            batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
+            batch.each do |parts|
+              @engine.emit_verbose_msg_sent(conn, parts)
+            end
           end
         end
+
         @tasks << @send_pump
       end
+
     end
   end
 end

data/lib/omq/routing/pub.rb

@@ -20,13 +20,23 @@ module OMQ
       end
 
 
-      # PUB is write-only.
+      # PUB is write-only. Engine-facing recv contract: dequeue raises,
+      # unblock is a no-op (fatal-error propagation still calls it).
       #
       def recv_queue
         raise "PUB sockets cannot receive"
       end
 
 
+      def dequeue_recv
+        raise "PUB sockets cannot receive"
+      end
+
+
+      def unblock_recv
+      end
+
+
       # @param connection [Connection]
       #
       def connection_added(connection)
@@ -61,6 +71,7 @@ module OMQ
         @tasks.each(&:stop)
         @tasks.clear
       end
+
     end
   end
 end