omq-cli 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baffaed1125c73842459b939d7be333d00bd9a56716f291951f952dd07140c76
-  data.tar.gz: 9065a49914bd1b035ca5cd9dfd65dd22fcb200484f5767c9ff196935d1a0731c
+  metadata.gz: 1bc589d81fe8cb43e0bef1743ff389b399ad62f5088215772239b05a1992859e
+  data.tar.gz: 4c1be278ef64044e2e6f525c5b0ca410d601c3f4711f50f87d2d669a4ab3f3fc
 SHA512:
-  metadata.gz: 1132c8e05c291fa46d58d9c4c31612519a4d598c85948910f3292d622580e72d4ad2af2ac64f5dbeba0e98e33571dc985885e39ddc567e5d468dcedb49b4ae43
-  data.tar.gz: e223a4c7ae5f495059463bdab4aa28f29d91cf6c106fbcd56ab1945a651f5c7ac018a2de5077fc8fd0bf5ef33360d5afebb6acee6d2612cd8679bd4ff22bb21a
+  metadata.gz: 4e50fbd35476b2db4139d16955a8a4249faffe4f1dfe196ee9faea76ab97304dfea9c217066c96dcaabce0b34331338649521f846ce7a7d760e3eefcc0573738
+  data.tar.gz: 2f96763515f5fee43718422ef42b0cedaba9f589c389f3a017cd170947ce6e5383d09a142e58d7596532aa382b0ab88b84c5ea6001b796d2a471bf558c520e57

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.11.0 — 2026-04-10
+
+### Added
+
+- **`-vvvv` adds ISO8601 µs-precision timestamps** to every log line
+  (endpoint attach, monitor events, message traces). Useful for
+  debugging time-sensitive reconnect and handshake races where
+  untimestamped `-vvv` output makes every event look instantaneous.
+  `-v`/`-vv`/`-vvv` are unchanged.
+
+- **YJIT enabled by default in `exe/omq`.** `RubyVM::YJIT.enable` is
+  called before loading the CLI. Skipped if `RUBYOPT` is set (so users
+  who pass `--disable-yjit` or similar keep their choice), if the
+  interpreter lacks YJIT, or if YJIT is already on.
+
+### Changed
+
+- **Universal default HWM is now 64** (was 100 for most sockets, 16
+  for pipe). 64 matches the recv pump's per-fairness-batch limit
+  (one batch exactly fills a full queue). Removed the special-case
+  `PipeRunner::PIPE_HWM = 16` override — pipe sockets now use the
+  same default as everything else, eliminating the documented-but-
+  surprising cliff.
+
+- **`pipe` no longer waits for peers unless `--timeout` is set.** The
+  previous unconditional `Barrier { pull.peer_connected + push.peer_connected }`
+  gate served no correctness purpose: `PULL#receive` blocks naturally
+  when no source is connected, and `PUSH` buffers up to `send_hwm` when
+  no sink is connected, so the loop can start immediately. Concretely,
+  `omq pipe -c ipc://@src -b ipc://@sink` started without a sink now
+  drains the source until both sides' HWMs are full (recv_queue +
+  send_queue = 2 × HWM) instead of silently blocking at 1 × HWM in the
+  recv pump while the worker loop sat idle at the wait. When
+  `--timeout` *is* set, the wait is preserved as a fail-fast starting
+  gate.
+
+- **Event formatting consolidated into `OMQ::CLI::Term`** — a new
+  stateless module (`module_function`) with `format_attach`,
+  `format_event`, `write_attach`, `write_event`, and `log_prefix`.
+  Replaces four duplicated copies across `BaseRunner`, `PipeRunner`,
+  `ParallelWorker`, and `PipeWorker` that had drifted apart — pipe-
+  mode event lines were missing the `-vvvv` timestamp prefix because
+  `PipeRunner` had its own copy of the formatter.
+
 ## 0.10.0 — 2026-04-09
 
 ### Changed

data/exe/omq

@@ -2,5 +2,12 @@
 # frozen_string_literal: true
 Warning[:experimental] = false
 
+# Enable YJIT by default. Skip if the user set RUBYOPT (they may have
+# --disable-yjit or similar in there), if the interpreter lacks YJIT
+# (TruffleRuby, older MRI), or if it's already on.
+if !ENV["RUBYOPT"] && defined?(RubyVM::YJIT) && !RubyVM::YJIT.enabled?
+  RubyVM::YJIT.enable
+end
+
 require "omq/cli"
 OMQ::CLI.run

data/lib/omq/cli/base_runner.rb

@@ -99,7 +99,7 @@ module OMQ
 
 
       def attach_endpoints
-        SocketSetup.attach(@sock, config, verbose: config.verbose >= 1)
+        SocketSetup.attach(@sock, config, verbose: config.verbose)
       end
 
 
@@ -464,19 +464,10 @@ module OMQ
 
       # -vv: log connect/disconnect/retry/timeout events via Socket#monitor
       # -vvv: also log message sent/received traces
+      # -vvvv: also prepend ISO8601 µs-precision timestamps
       def start_event_monitor
-        verbose = config.verbose >= 3
-        @sock.monitor(verbose: verbose) do |event|
-          case event.type
-          when :message_sent
-            $stderr.write("omq: >> #{Formatter.preview(event.detail[:parts])}\n")
-          when :message_received
-            $stderr.write("omq: << #{Formatter.preview(event.detail[:parts])}\n")
-          else
-            ep = event.endpoint ? " #{event.endpoint}" : ""
-            detail = event.detail ? " #{event.detail}" : ""
-            $stderr.write("omq: #{event.type}#{ep}#{detail}\n")
-          end
+        @sock.monitor(verbose: config.verbose >= 3) do |event|
+          Term.write_event(event, config.verbose)
         end
       end
     end

data/lib/omq/cli/cli_parser.rb

@@ -340,7 +340,7 @@ module OMQ
           }
           o.on("--heartbeat-ivl SECS", Float, "ZMTP heartbeat interval (detects dead peers)") { |v| opts[:heartbeat_ivl] = v }
           o.on("--recv-maxsz SIZE", "Max inbound message size, e.g. 4096, 64K, 1M, 2G (default 1M, 0=unlimited; larger messages drop the connection)") { |v| opts[:recv_maxsz] = parse_byte_size(v) }
-          o.on("--hwm N", Integer, "High water mark (default 100, 0=unbounded; modal with --in/--out)") do |v|
+          o.on("--hwm N", Integer, "High water mark (default 64, 0=unbounded; modal with --in/--out)") do |v|
             case pipe_side
             when :in
               opts[:recv_hwm] = v
@@ -390,7 +390,7 @@ module OMQ
           o.separator "            OMQ_CRYPTO (backend: rbnacl or nuckle)"
 
           o.separator "\nOther:"
-          o.on("-v", "--verbose",   "Verbosity: -v endpoints, -vv events, -vvv messages") { opts[:verbose] += 1 }
+          o.on("-v", "--verbose",   "Verbosity: -v endpoints, -vv events, -vvv messages, -vvvv timestamps") { opts[:verbose] += 1 }
           o.on("-q", "--quiet",     "Suppress message output")           { opts[:quiet] = true }
           o.on(      "--transient", "Exit when all peers disconnect")    { opts[:transient] = true }
           o.on(      "--ffi",       "Use libzmq FFI backend (requires omq-ffi gem + system libzmq 4.x)") do

data/lib/omq/cli/parallel_worker.rb

@@ -44,14 +44,14 @@ module OMQ
         @sock = @config.ffi ? OMQ.const_get(@socket_sym).new(backend: :ffi) : OMQ.const_get(@socket_sym).new
         OMQ::CLI::SocketSetup.apply_options(@sock, @config)
         @sock.identity = @config.identity if @config.identity
-        OMQ::CLI::SocketSetup.attach_endpoints(@sock, @endpoints, verbose: false)
+        OMQ::CLI::SocketSetup.attach_endpoints(@sock, @endpoints, verbose: 0)
       end
 
 
       def log_endpoints
         return unless @config.verbose >= 1
         @endpoints.each do |ep|
-          @log_port.send(ep.bind? ? "Bound to #{ep.url}" : "Connecting to #{ep.url}")
+          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.verbose))
         end
       end
 
@@ -60,21 +60,7 @@ module OMQ
         return unless @config.verbose >= 2
         trace = @config.verbose >= 3
         @sock.monitor(verbose: trace) do |event|
-          @log_port.send(format_event(event))
-        end
-      end
-
-
-      def format_event(event)
-        case event.type
-        when :message_sent
-          "omq: >> #{OMQ::CLI::Formatter.preview(event.detail[:parts])}"
-        when :message_received
-          "omq: << #{OMQ::CLI::Formatter.preview(event.detail[:parts])}"
-        else
-          ep = event.endpoint ? " #{event.endpoint}" : ""
-          detail = event.detail ? " #{event.detail}" : ""
-          "omq: #{event.type}#{ep}#{detail}"
+          @log_port.send(OMQ::CLI::Term.format_event(event, @config.verbose))
         end
       end
 

data/lib/omq/cli/pipe.rb

@@ -5,11 +5,6 @@ module OMQ
     # Runner for the virtual "pipe" socket type (PULL -> eval -> PUSH).
     # Supports sequential and parallel (Ractor-based) processing modes.
     class PipeRunner
-      # Default HWM for pipe sockets when the user hasn't set one.
-      # Much lower than the socket default (1000) to bound memory
-      # with large messages in pipeline stages.
-      PIPE_HWM = 16
-
       # @return [Config] frozen CLI configuration
       attr_reader :config
 
@@ -57,18 +52,7 @@ module OMQ
         compile_expr
         @sock = @pull  # for eval instance_exec
         start_event_monitors if config.verbose >= 2
-        wait_body = proc do
-          Barrier do |barrier|
-            barrier.async(annotation: "wait push peer") { @push.peer_connected.wait }
-            barrier.async(annotation: "wait pull peer") { @pull.peer_connected.wait }
-          end
-        end
-
-        if config.timeout
-          Fiber.scheduler.with_timeout(config.timeout, &wait_body)
-        else
-          wait_body.call
-        end
+        wait_for_peers_with_timeout if config.timeout
         setup_sequential_transient(task)
         @sock.instance_exec(&@recv_begin_proc) if @recv_begin_proc
         sequential_message_loop
@@ -79,16 +63,27 @@ module OMQ
       end
 
 
+      # With --timeout set, fail fast if peers never show up. Without
+      # it, there's no point waiting: PULL#receive blocks naturally
+      # and PUSH buffers up to send_hwm when no peer is present.
+      def wait_for_peers_with_timeout
+        Fiber.scheduler.with_timeout(config.timeout) do
+          Barrier do |barrier|
+            barrier.async(annotation: "wait push peer") { @push.peer_connected.wait }
+            barrier.async(annotation: "wait pull peer") { @pull.peer_connected.wait }
+          end
+        end
+      end
+
+
       def build_pull_push(in_eps, out_eps)
         kwargs = config.ffi ? { backend: :ffi } : {}
         pull = OMQ::PULL.new(**kwargs)
         push = OMQ::PUSH.new(**kwargs)
         SocketSetup.apply_options(pull, config)
         SocketSetup.apply_options(push, config)
-        pull.recv_hwm = PIPE_HWM unless config.recv_hwm
-        push.send_hwm = PIPE_HWM unless config.send_hwm
-        SocketSetup.attach_endpoints(pull, in_eps, verbose: config.verbose >= 1)
-        SocketSetup.attach_endpoints(push, out_eps, verbose: config.verbose >= 1)
+        SocketSetup.attach_endpoints(pull, in_eps, verbose: config.verbose)
+        SocketSetup.attach_endpoints(push, out_eps, verbose: config.verbose)
         [pull, push]
       end
 
@@ -189,19 +184,10 @@ module OMQ
 
 
       def start_event_monitors
-        verbose = config.verbose >= 3
+        trace = config.verbose >= 3
         [@pull, @push].each do |sock|
-          sock.monitor(verbose: verbose) do |event|
-            case event.type
-            when :message_sent
-              $stderr.write("omq: >> #{Formatter.preview(event.detail[:parts])}\n")
-            when :message_received
-              $stderr.write("omq: << #{Formatter.preview(event.detail[:parts])}\n")
-            else
-              ep = event.endpoint ? " #{event.endpoint}" : ""
-              detail = event.detail ? " #{event.detail}" : ""
-              $stderr.write("omq: #{event.type}#{ep}#{detail}\n")
-            end
+          sock.monitor(verbose: trace) do |event|
+            Term.write_event(event, config.verbose)
           end
         end
       end

data/lib/omq/cli/pipe_worker.rb

@@ -20,7 +20,7 @@ module OMQ
           setup_sockets
           log_endpoints if @config.verbose >= 1
           start_monitors if @config.verbose >= 2
-          wait_for_peers
+          wait_for_peers_with_timeout if @config.timeout
           compile_expr
           run_message_loop
           run_end_block
@@ -42,16 +42,15 @@ module OMQ
         @push = OMQ::PUSH.new(**kwargs)
         OMQ::CLI::SocketSetup.apply_options(@pull, @config)
         OMQ::CLI::SocketSetup.apply_options(@push, @config)
-        @pull.recv_hwm = PipeRunner::PIPE_HWM unless @config.recv_hwm
-        @push.send_hwm = PipeRunner::PIPE_HWM unless @config.send_hwm
-        OMQ::CLI::SocketSetup.attach_endpoints(@pull, @in_eps, verbose: false)
-        OMQ::CLI::SocketSetup.attach_endpoints(@push, @out_eps, verbose: false)
+        OMQ::CLI::SocketSetup.attach_endpoints(@pull, @in_eps, verbose: 0)
+        OMQ::CLI::SocketSetup.attach_endpoints(@push, @out_eps, verbose: 0)
       end
 
 
       def log_endpoints
-        @in_eps.each { |ep| @log_port.send(ep.bind? ? "Bound to #{ep.url}" : "Connecting to #{ep.url}") }
-        @out_eps.each { |ep| @log_port.send(ep.bind? ? "Bound to #{ep.url}" : "Connecting to #{ep.url}") }
+        (@in_eps + @out_eps).each do |ep|
+          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.verbose))
+        end
       end
 
 
@@ -59,30 +58,21 @@ module OMQ
         trace = @config.verbose >= 3
         [@pull, @push].each do |sock|
           sock.monitor(verbose: trace) do |event|
-            @log_port.send(format_event(event))
+            @log_port.send(OMQ::CLI::Term.format_event(event, @config.verbose))
           end
         end
       end
 
 
-      def format_event(event)
-        case event.type
-        when :message_sent
-          "omq: >> #{OMQ::CLI::Formatter.preview(event.detail[:parts])}"
-        when :message_received
-          "omq: << #{OMQ::CLI::Formatter.preview(event.detail[:parts])}"
-        else
-          ep     = event.endpoint ? " #{event.endpoint}" : ""
-          detail = event.detail ? " #{event.detail}" : ""
-          "omq: #{event.type}#{ep}#{detail}"
-        end
-      end
-
-
-      def wait_for_peers
-        Barrier do |barrier|
-          barrier.async { @pull.peer_connected.wait }
-          barrier.async { @push.peer_connected.wait }
+      # With --timeout set, fail fast if peers never show up. Without
+      # it, there's no point waiting: PULL#receive blocks naturally
+      # and PUSH buffers up to send_hwm when no peer is present.
+      def wait_for_peers_with_timeout
+        Fiber.scheduler.with_timeout(@config.timeout) do
+          Barrier do |barrier|
+            barrier.async { @pull.peer_connected.wait }
+            barrier.async { @push.peer_connected.wait }
+          end
         end
       end
 

data/lib/omq/cli/socket_setup.rb

@@ -7,11 +7,12 @@ module OMQ
     #
     module SocketSetup
       # Default high water mark applied when the user does not pass
-      # --hwm. Lower than libzmq's default (1000) to keep
-      # memory footprint small for the typical CLI use cases (interactive
-      # debugging, short-lived pipelines). Pipe worker sockets override this
-      # with a still-smaller value for tighter backpressure.
-      DEFAULT_HWM = 100
+      # --hwm. Lower than libzmq's default (1000) to keep memory
+      # footprint bounded for the typical CLI use cases (interactive
+      # debugging, short-lived pipelines). 64 matches the recv pump's
+      # per-fairness-batch limit (one batch exactly fills a full
+      # queue).
+      DEFAULT_HWM = 64
 
       # Default max inbound message size applied when the user does not
       # pass --recv-maxsz. The omq library itself is unlimited by default;
@@ -57,30 +58,32 @@ module OMQ
 
 
       # Bind/connect +sock+ using URL strings from +config.binds+ / +config.connects+.
+      # +verbose+ is the integer verbosity level (0 = silent).
       #
-      def self.attach(sock, config, verbose: false)
+      def self.attach(sock, config, verbose: 0)
         config.binds.each do |url|
           sock.bind(url)
-          $stderr.puts "Bound to #{sock.last_endpoint}" if verbose
+          CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
         end
         config.connects.each do |url|
           sock.connect(url)
-          $stderr.puts "Connecting to #{url}" if verbose
+          CLI::Term.write_attach(:connect, url, verbose) if verbose >= 1
         end
       end
 
 
       # Bind/connect +sock+ from an Array of Endpoint objects.
       # Used by PipeRunner, which works with structured endpoint lists.
+      # +verbose+ is the integer verbosity level (0 = silent).
       #
-      def self.attach_endpoints(sock, endpoints, verbose: false)
+      def self.attach_endpoints(sock, endpoints, verbose: 0)
         endpoints.each do |ep|
           if ep.bind?
             sock.bind(ep.url)
-            $stderr.puts "Bound to #{sock.last_endpoint}" if verbose
+            CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
           else
             sock.connect(ep.url)
-            $stderr.puts "Connecting to #{ep.url}" if verbose
+            CLI::Term.write_attach(:connect, ep.url, verbose) if verbose >= 1
           end
         end
       end

data/lib/omq/cli/term.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OMQ
+  module CLI
+    # Stateless terminal formatting and stderr writing helpers shared
+    # by every code path that emits verbose-driven log lines (event
+    # monitor callbacks in BaseRunner / PipeRunner, SocketSetup attach
+    # helpers, parallel/pipe Ractor workers).
+    #
+    # Pure module functions: no state, no instance, safe to call from
+    # any thread or Ractor. Errors and abort messages do *not* go
+    # through this module — they aren't logs.
+    #
+    module Term
+      module_function
+
+
+      # Returns a stderr log line prefix. At verbose >= 4, prepends an
+      # ISO8601 UTC timestamp with µs precision so log traces become
+      # time-correlatable. Otherwise returns the empty string.
+      #
+      # @param verbose [Integer]
+      # @return [String]
+      def log_prefix(verbose)
+        return "" unless verbose && verbose >= 4
+        "#{Time.now.utc.strftime("%FT%T.%6N")}Z "
+      end
+
+
+      # Formats one OMQ::MonitorEvent into a single log line (no
+      # trailing newline).
+      #
+      # @param event [OMQ::MonitorEvent]
+      # @param verbose [Integer]
+      # @return [String]
+      def format_event(event, verbose)
+        prefix = log_prefix(verbose)
+        case event.type
+        when :message_sent
+          "#{prefix}omq: >> #{Formatter.preview(event.detail[:parts])}"
+        when :message_received
+          "#{prefix}omq: << #{Formatter.preview(event.detail[:parts])}"
+        else
+          ep     = event.endpoint ? " #{event.endpoint}" : ""
+          detail = event.detail ? " #{event.detail}" : ""
+          "#{prefix}omq: #{event.type}#{ep}#{detail}"
+        end
+      end
+
+
+      # Formats an "attached endpoint" log line (Bound to / Connecting to).
+      #
+      # @param kind [:bind, :connect]
+      # @param url [String]
+      # @param verbose [Integer]
+      # @return [String]
+      def format_attach(kind, url, verbose)
+        verb = kind == :bind ? "Bound to" : "Connecting to"
+        "#{log_prefix(verbose)}#{verb} #{url}"
+      end
+
+
+      # Writes one formatted event line to +io+ (default $stderr).
+      #
+      # @param event [OMQ::MonitorEvent]
+      # @param verbose [Integer]
+      # @param io [#write] writable sink, default $stderr
+      # @return [void]
+      def write_event(event, verbose, io: $stderr)
+        io.write("#{format_event(event, verbose)}\n")
+      end
+
+
+      # Writes one "Bound to / Connecting to" line to +io+
+      # (default $stderr).
+      #
+      # @param kind [:bind, :connect]
+      # @param url [String]
+      # @param verbose [Integer]
+      # @param io [#write]
+      # @return [void]
+      def write_attach(kind, url, verbose, io: $stderr)
+        io.write("#{format_attach(kind, url, verbose)}\n")
+      end
+    end
+  end
+end

data/lib/omq/cli/version.rb

@@ -2,6 +2,6 @@
 
 module OMQ
   module CLI
-    VERSION = "0.10.1"
+    VERSION = "0.11.0"
   end
 end

data/lib/omq/cli.rb

@@ -5,6 +5,7 @@ require_relative "cli/version"
 require_relative "cli/config"
 require_relative "cli/cli_parser"
 require_relative "cli/formatter"
+require_relative "cli/term"
 require_relative "cli/expression_evaluator"
 require_relative "cli/socket_setup"
 require_relative "cli/routing_helper"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-cli
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: omq-ffi
   requirement: !ruby/object:Gem::Requirement
@@ -185,6 +185,7 @@ files:
 - lib/omq/cli/routing_helper.rb
 - lib/omq/cli/scatter_gather.rb
 - lib/omq/cli/socket_setup.rb
+- lib/omq/cli/term.rb
 - lib/omq/cli/transient_monitor.rb
 - lib/omq/cli/version.rb
 homepage: https://github.com/paddor/omq-cli