omq 0.18.0 → 0.19.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4c49622de9b6972433ec90b148e0d20e68f69d5bb4939debd5abd5095d0396b
-  data.tar.gz: a70873e070a90ac7b804585231180926ef030e8ffeb9cf65fc44e889dc3619e2
+  metadata.gz: 19b283aa20e543617cd7be9c899d2954c219631fd57417536be4fb26798e6e85
+  data.tar.gz: a39d1c870e6171726a00a5f1809556e3ce7c3a8c0e4b0e84722eae15f83f93b6
 SHA512:
-  metadata.gz: a4c994245259282909189bcd44d69ef9153b52ef1dd2675b8cf8635b8970ed9c630048b55837cdc0fa20ecb04c00edd9b3bff17e5d9ad93d70107eb8701b08a3
-  data.tar.gz: d3f88cd73a8ea21fb572518a8f9b8128244f2bb10cfcf0e43b8ac73a797158ef1c2a59fe8fe75be407eac6277f8ebd05bd7ab554f6fa3a4d1e215ccaf3c034ab
+  metadata.gz: 7a020d02b2a1da25dd37f6ff92836348985fb7bcd7b8c17392bacb4c23d0ee443b2dd294f8e30d5df5724e11049462d428efb6d2b5a3313b479ab7a3e7e71388
+  data.tar.gz: 3b9724342594f22aabe00d1b13d7aa71bfe652ca21954c6b4789556e95743fd03d1c62214a164be8cad717405766a5d0acdbb4c3fd73a0f95aa14738cfb17d81

data/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 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
+
+- **Verbose-monitor helpers `Engine#emit_verbose_msg_sent` and
+  `#emit_verbose_msg_received`.** Used by `RecvPump` and every
+  send-pump routing strategy (`conn_send_pump`, `round_robin`,
+  `pair`, `fan_out`) to emit `:message_sent` / `:message_received`
+  monitor events with a connection reference. When the connection
+  exposes `#last_wire_size_out` / `#last_wire_size_in` (as the
+  `omq-rfc-zstd` `CompressionConnection` wrapper does), the event
+  detail includes `wire_size:` so verbose traces can annotate
+  compressed message previews with the post-compression byte count.
+  `RecvPump` now emits the trace *before* enqueueing the message
+  so the monitor fiber runs before the application fiber, which
+  preserves log-before-body ordering at `-vvv`.
+
+### Changed
+
+- **`OMQ::Transport::TCP` normalizes host shorthands.** `tcp://*:PORT`
+  now binds *dual-stack* (both `0.0.0.0` and `::` on the same port,
+  with `IPV6_V6ONLY` set) rather than IPv4-only `0.0.0.0`, matching
+  [Puma v8.0.0's behavior](https://github.com/puma/puma/releases/tag/v8.0.0).
+  `tcp://:PORT`, `tcp://localhost:PORT`, and `tcp://*:PORT` on the
+  connect side all normalize to the loopback host — `::1` on
+  IPv6-capable machines (at least one non-loopback, non-link-local
+  IPv6 address), otherwise `127.0.0.1`. Explicit addresses
+  (`0.0.0.0`, `::`, `127.0.0.1`, `::1`) pass through unchanged.
+  Documented in `GETTING_STARTED.md` under "TCP host shorthands".
+  This normalization previously lived in `omq-cli` and is now
+  shared by all callers.
+
+- **TCP accept loop uses `Socket.tcp_server_sockets`** instead of
+  manually iterating `Addrinfo.getaddrinfo` + `TCPServer.new`.
+  `tcp_server_sockets` handles dual-stack port coordination and
+  `IPV6_V6ONLY` automatically. `Listener#servers` now holds
+  `Socket` instances rather than `TCPServer`; `#accept` returns
+  `[client, addrinfo]` pairs, which the accept loop destructures.
+
+- **`Listener#start_accept_loops` uses `yield`** instead of capturing
+  the block as an explicit `&on_accepted` proc. The block is bound
+  to the enclosing method even when invoked from inside a spawned
+  `Async::Task`, so the explicit capture was unnecessary. Applies
+  to both TCP and IPC transports.
+
 ## 0.18.0 — 2026-04-12
 
 ### Changed

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

@@ -94,18 +94,24 @@ module OMQ
             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)
-              engine.emit_verbose_monitor_event(:message_received, parts: msg)
               count += 1
               bytes += msg.sum(&: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
 
@@ -124,18 +130,20 @@ module OMQ
             bytes = 0
             while count < FAIRNESS_MESSAGES && bytes < FAIRNESS_BYTES
               msg = conn.receive_message
+              engine.emit_verbose_msg_received(conn, msg)
               recv_queue.enqueue(msg)
-              engine.emit_verbose_monitor_event(:message_received, parts: msg)
               count += 1
               bytes += msg.sum(&: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

@@ -386,8 +386,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,25 +399,35 @@ 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
-        wrapped
-      end
+      @fatal_error = build_fatal_error(error)
       routing.recv_queue.push(nil) 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
+    end
+
+
     # Captures the socket's task tree root and starts the socket-level
     # maintenance task. If +parent+ is given, it is used as the parent
     # for every task spawned under this socket (connection supervisors,
@@ -461,6 +475,28 @@ module OMQ
     end
 
 
+    # Emits a :message_sent verbose event and enriches it with the
+    # on-wire (post-compression) byte size if +conn+ exposes
+    # +last_wire_size_out+ (installed by ZMTP-Zstd etc.).
+    def emit_verbose_msg_sent(conn, parts)
+      return unless @verbose_monitor
+      detail = { parts: parts }
+      detail[:wire_size] = conn.last_wire_size_out if conn.respond_to?(:last_wire_size_out)
+      emit_monitor_event(:message_sent, detail: detail)
+    end
+
+
+    # Emits a :message_received verbose event and enriches it with the
+    # on-wire (pre-decompression) byte size if +conn+ exposes
+    # +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)
+      emit_monitor_event(:message_received, detail: detail)
+    end
+
+
     # Looks up the transport module for an endpoint URI.
     #
     # @param endpoint [String] endpoint URI (e.g. "tcp://...", "inproc://...")

data/lib/omq/routing/conn_send_pump.rb

@@ -30,9 +30,7 @@ module OMQ
 
             conn.flush
 
-            batch.each do |parts|
-              engine.emit_verbose_monitor_event :message_sent, parts: parts
-            end
+            batch.each { |parts| engine.emit_verbose_msg_sent(conn, parts) }
           end
         end
 

data/lib/omq/routing/fan_out.rb

@@ -179,7 +179,7 @@ module OMQ
             Routing.drain_send_queue(q, batch)
             if write_matching_batch(conn, batch, use_wire)
               conn.flush
-              batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+              batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
             end
           end
         end
@@ -227,7 +227,7 @@ module OMQ
 
             conn.write_message(latest)
             conn.flush
-            @engine.emit_verbose_monitor_event(:message_sent, parts: latest)
+            @engine.emit_verbose_msg_sent(conn, latest)
           end
         end
       end

data/lib/omq/routing/pair.rb

@@ -96,7 +96,7 @@ module OMQ
               conn.write_messages(batch)
             end
             conn.flush
-            batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+            batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
           end
         end
         @tasks << @send_pump

data/lib/omq/routing/round_robin.rb

@@ -134,7 +134,7 @@ module OMQ
             ensure
               @in_flight -= batch.size
             end
-            batch.each { |parts| @engine.emit_verbose_monitor_event(:message_sent, parts: parts) }
+            batch.each { |parts| @engine.emit_verbose_msg_sent(conn, parts) }
             Async::Task.current.yield
           end
         end
@@ -147,16 +147,26 @@ module OMQ
       BATCH_BYTE_CAP = 512 * 1024
 
       def drain_send_queue_capped(batch)
-        bytes = batch[0].sum(&:bytesize)
+        bytes = batch_bytes(batch[0])
         while batch.size < BATCH_MSG_CAP && bytes < BATCH_BYTE_CAP
           msg = @send_queue.dequeue(timeout: 0)
           break unless msg
           batch << msg
-          bytes += msg.sum(&:bytesize)
+          bytes += batch_bytes(msg)
         end
       end
 
 
+      # Byte accounting for send-queue batching. Connection wrappers
+      # (e.g. OMQ::Ractor's MarshalConnection) may enqueue non-string
+      # parts that get transformed at write time — skip those for the
+      # fairness cap rather than crashing on #bytesize.
+      #
+      def batch_bytes(parts)
+        parts.sum { |p| p.respond_to?(:bytesize) ? p.bytesize : 0 }
+      end
+
+
       def write_batch(conn, batch)
         if batch.size == 1
           conn.send_message(transform_send(batch[0]))

data/lib/omq/socket.rb

@@ -16,6 +16,13 @@ module OMQ
     attr_reader :last_tcp_port
 
 
+    # @return [Engine] the socket's engine. Exposed for peer tooling
+    #   (omq-cli, omq-ffi, omq-ractor) that needs to reach into the
+    #   socket's internals — not part of the stable user API.
+    #
+    attr_reader :engine
+
+
     # Delegate socket option accessors to @options.
     #
     extend Forwardable

data/lib/omq/transport/ipc.rb

@@ -79,7 +79,7 @@ module OMQ
           if abstract?(path)
             "\0#{path[1..]}"
           else
-            path # TODO: return Pathname
+            path
           end
         end
 
@@ -106,7 +106,7 @@ module OMQ
 
         # @param endpoint [String] the IPC endpoint URI
         # @param server [UNIXServer]
-        # @param path [String] filesystem or abstract namespace path # TODO: Pathname
+        # @param path [String] filesystem or abstract namespace path
         # @param engine [Engine]
         #
         def initialize(endpoint, server, path, engine)
@@ -124,15 +124,14 @@ module OMQ
         # @param parent_task [Async::Task]
         # @yieldparam io [IO::Stream::Buffered]
         #
-        def start_accept_loops(parent_task, &on_accepted)
+        def start_accept_loops(parent_task)
           annotation = "ipc accept #{@endpoint}"
           @task = parent_task.async(transient: true, annotation:) do
             loop do
               client = @server.accept
               IPC.apply_buffer_sizes(client, @engine.options)
               Async::Task.current.defer_stop do
-                # TODO use yield
-                on_accepted.call(IO::Stream::Buffered.wrap(client))
+                yield IO::Stream::Buffered.wrap(client)
               end
             end
           rescue Async::Stop
@@ -155,7 +154,7 @@ module OMQ
           @server.close rescue nil
 
           # Clean up socket file for file-based paths
-          unless @path.start_with?("@") # TODO: check if it's a Pathname instead
+          unless @path.start_with?("@")
             File.delete(@path) rescue nil
           end
         end

data/lib/omq/transport/tcp.rb

@@ -17,23 +17,19 @@ module OMQ
         # @return [Listener]
         #
         def bind(endpoint, engine)
-          host, port = self.parse_endpoint(endpoint)
-          host = "0.0.0.0" if host == "*" # FIXME: support IPv6, see omq-cli v0.11.2
-
-          addrs = Addrinfo.getaddrinfo(host, port, nil, :STREAM, nil, ::Socket::AI_PASSIVE)
-          raise ::Socket::ResolutionError, "no addresses for #{host}" if addrs.empty?
-
-          servers     = []
-          actual_port = nil
-
-          addrs.each do |addr|
-            server = TCPServer.new(addr.ip_address, actual_port || port)
-            actual_port ||= server.local_address.ip_port
-            servers << server
-          end
-
-          host_part = host.include?(":") ? "[#{host}]" : host
-          resolved  = "tcp://#{host_part}:#{actual_port}"
+          host, port  = self.parse_endpoint(endpoint)
+          lookup_host = normalize_bind_host(host)
+
+          # Socket.tcp_server_sockets coordinates ephemeral ports across
+          # address families and sets IPV6_V6ONLY so IPv4 and IPv6
+          # wildcards don't collide on Linux.
+          servers = ::Socket.tcp_server_sockets(lookup_host, port)
+          raise ::Socket::ResolutionError, "no addresses for #{host.inspect}" if servers.empty?
+
+          actual_port  = servers.first.local_address.ip_port
+          display_host = host == "*" ? "*" : (lookup_host || "*")
+          host_part    = display_host.include?(":") ? "[#{display_host}]" : display_host
+          resolved     = "tcp://#{host_part}:#{actual_port}"
           Listener.new(resolved, servers, actual_port, engine)
         end
 
@@ -45,7 +41,8 @@ module OMQ
         #
         def validate_endpoint!(endpoint)
           host, _port = parse_endpoint(endpoint)
-          Addrinfo.getaddrinfo(host, nil, nil, :STREAM) if host
+          lookup_host = normalize_bind_host(host)
+          Addrinfo.getaddrinfo(lookup_host, nil, nil, :STREAM) if lookup_host
         end
 
 
@@ -57,12 +54,54 @@ module OMQ
         #
         def connect(endpoint, engine)
           host, port = self.parse_endpoint(endpoint)
-          sock = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
+          host       = normalize_connect_host(host)
+          sock       = ::Socket.tcp(host, port, connect_timeout: connect_timeout(engine.options))
           apply_buffer_sizes(sock, engine.options)
           engine.handle_connected(IO::Stream::Buffered.wrap(sock), endpoint: endpoint)
         end
 
 
+        # Normalizes the bind host:
+        #   "*"                    → nil (dual-stack wildcard via AI_PASSIVE)
+        #   "" / nil / "localhost" → loopback_host (::1 on IPv6-capable hosts, else 127.0.0.1)
+        #   else                   → unchanged
+        #
+        def normalize_bind_host(host)
+          case host
+          when "*" then nil
+          when nil, "", "localhost" then loopback_host
+          else host
+          end
+        end
+
+
+        # Normalizes the connect host: "", nil, "*", and "localhost" all
+        # map to the loopback host. Everything else is passed through so
+        # real hostnames still go through the resolver + Happy Eyeballs.
+        #
+        def normalize_connect_host(host)
+          case host
+          when nil, "", "*", "localhost" then loopback_host
+          else host
+          end
+        end
+
+
+        # Loopback address preference for bind/connect normalization.
+        # Returns "::1" when the host has at least one non-loopback,
+        # non-link-local IPv6 address, otherwise "127.0.0.1".
+        #
+        def loopback_host
+          @loopback_host ||= begin
+            has_ipv6 = ::Socket.getifaddrs.any? do |ifa|
+              addr = ifa.addr
+              addr&.ipv6? && !addr.ipv6_loopback? && !addr.ipv6_linklocal?
+            end
+            has_ipv6 ? "::1" : "127.0.0.1"
+          end
+        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.
@@ -114,13 +153,13 @@ module OMQ
         #
         attr_reader :port
 
-        # @return [Array<TCPServer>] bound server sockets
+        # @return [Array<Socket>] bound server sockets
         #
         attr_reader :servers
 
 
         # @param endpoint [String] resolved endpoint URI
-        # @param servers [Array<TCPServer>]
+        # @param servers [Array<Socket>]
         # @param port [Integer] bound port number
         # @param engine [Engine]
         #
@@ -139,17 +178,16 @@ module OMQ
         # @param parent_task [Async::Task]
         # @yieldparam io [IO::Stream::Buffered]
         #
-        def start_accept_loops(parent_task, &on_accepted)
+        def start_accept_loops(parent_task)
           @tasks = @servers.map do |server|
             # TODO: use this server's exact host:port (@endpoint might not be unique)
             annotation = "tcp accept #{@endpoint}"
             parent_task.async(transient: true, annotation:) do
               loop do
-                client = server.accept
+                client, _addr = server.accept
                 TCP.apply_buffer_sizes(client, @engine.options)
                 Async::Task.current.defer_stop do
-                  # TODO: why not yield?
-                  on_accepted.call(IO::Stream::Buffered.wrap(client))
+                  yield IO::Stream::Buffered.wrap(client)
                 end
               end
             rescue Async::Stop

data/lib/omq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OMQ
-  VERSION = "0.18.0"
+  VERSION = "0.19.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.2
 platform: ruby
 authors:
 - Patrik Wenger