omq 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4c49622de9b6972433ec90b148e0d20e68f69d5bb4939debd5abd5095d0396b
-  data.tar.gz: a70873e070a90ac7b804585231180926ef030e8ffeb9cf65fc44e889dc3619e2
+  metadata.gz: f01c18a7a887e0f2811abff2251f1b2c9b201091e800248fb852b92bedbcaf06
+  data.tar.gz: d32b3e07223d906a3bb25fc8542409bb5c05af36b509f7fe70c91419d0836cf9
 SHA512:
-  metadata.gz: a4c994245259282909189bcd44d69ef9153b52ef1dd2675b8cf8635b8970ed9c630048b55837cdc0fa20ecb04c00edd9b3bff17e5d9ad93d70107eb8701b08a3
-  data.tar.gz: d3f88cd73a8ea21fb572518a8f9b8128244f2bb10cfcf0e43b8ac73a797158ef1c2a59fe8fe75be407eac6277f8ebd05bd7ab554f6fa3a4d1e215ccaf3c034ab
+  metadata.gz: c0b26ad39e26fe586cec53371bc4b1beeaf357b51f32e90ad8d889a8413f62c08c13be2d8f787e3528d4fca6bccc1ceae21454474465aff25f9418c37460d957
+  data.tar.gz: b8d3acedee187c9c757268af173b55bd28daf502f8e054f92ef670c59a1781e2b2f73267425c239d27acc7cb036b0030ab562a12918c7db205dc34f4bcf8e38d

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 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/recv_pump.rb

@@ -94,8 +94,12 @@ 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
@@ -124,8 +128,8 @@ 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

data/lib/omq/engine.rb

@@ -461,6 +461,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

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.0"
 end

metadata

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