omq-cli 0.12.3 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf29033480f27f1a249d6f22b85a2f569687e79ed6ddde06a0ef74eacafa0863
-  data.tar.gz: 4d51ae13241f047758223a2b4f055721d2b1a8809c5ba7c1154868141b1e22e8
+  metadata.gz: 0135d1ab507a4e82186cae115a477ccbd4b231e12a7450cb8989a5c0c1479e50
+  data.tar.gz: efc832159dc103ec4b18ba5f65acb5976a09c7530b246e5e433795357ca21181
 SHA512:
-  metadata.gz: 254ca00deef4d9bd9e4bbafd3cd44f785c27f63446437367b178e76711cdeda33ab779f7880e71181d3d60198458bd1f5741f1890e0d9125d797282dbef96189
-  data.tar.gz: 642c4eebaedc3d3b606693e40c3cf6112ee4c06b60432c60831bd75b0d3be171d81a2f4232c27a49fbed9c287a061e490dc3a62ebdfd618cf0f7fa3ea9624fff
+  metadata.gz: a8093420e5209f9e4672dd15a343c60167959532d90fda0fce7f108042807a65d27f033eb39a3abfee80059e8832d2e90680a624f36575c8b608f2da5095865c
+  data.tar.gz: 30dc24c50221b726130e638764d891d2736044b358b364f2bd987a21eceac85bea44ed0821ab601d1070d2e60bc10492a61ffd8baa8129588a0dce06b72ec192

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.13.0 — 2026-04-12
+
+### Added
+
+- **`--timestamps[=PRECISION]` flag.** Prefix log lines with UTC
+  timestamps. Accepts `s`, `ms` (default), or `us`. Replaces the
+  former `-vvvv` special meaning, which has been removed.
+- **`-M` / `--marshal` preserves arbitrary objects on the wire.**
+  Eval results in `--format marshal` mode (e.g. `Time.now`, hashes,
+  UTF-16LE strings) are now passed through unchanged instead of
+  being coerced via `#to_s`. Affects both the main runner and
+  Ractor workers (`-P`).
+- **`-P0` ⇒ `nproc`.** `-P0` (or bare `-P`) spawns one Ractor worker
+  per CPU, capped at 16. Short-option clustering works: `-P0zvv`
+  expands to `-P 0 -z -v -v`.
+
+### Changed
+
+- **`-vvv` shows decompressed message previews.** When `--compress`
+  is active, message traces now log the decompressed parts and
+  include the on-wire size: `(5B wire=21B) hello`. Engine-level
+  message events are suppressed in compressed mode to avoid
+  double-logging compressed bytes.
+- **Truncation marker uses `…` (U+2026).** `Formatter.preview`
+  truncation now uses the real horizontal ellipsis character
+  instead of three ASCII dots.
+
+### Fixed
+
+- **`FrozenError` in eval handlers returning received parts.**
+  `ExpressionEvaluator` no longer mutates the result array with
+  `#map!`, which crashed when a script handler returned the frozen
+  parts array received from the socket.
+- **README:** fixed broken `if /regex/` examples (no implicit `$_`
+  match in `instance_exec`), broken `OMQ.incoming`/`OMQ.outgoing`
+  handler table, and `-P` examples that no longer parsed.
+
 ## 0.12.3 — 2026-04-10
 
 ### Fixed

data/README.md

@@ -127,8 +127,8 @@ Pipe creates an internal PULL → eval → PUSH pipeline:
 ```sh
 omq pipe -c@work -c@sink -e 'it.map(&:upcase)'
 
-# with Ractor workers for CPU parallelism
-omq pipe -c@work -c@sink -P 4 -r./fib.rb -e 'fib(Integer(it.first)).to_s'
+# with Ractor workers for CPU parallelism (-P0 = nproc)
+omq pipe -c@work -c@sink -P0 -r./fib.rb -e 'fib(Integer(it.first)).to_s'
 ```
 
 The first endpoint is the pull-side (input), the second is the push-side (output).
@@ -171,10 +171,10 @@ omq pull -b tcp://:5557 -e '|(key, value)| "#{key}=#{value}"'
 
 ```sh
 # skip messages matching a pattern
-omq pull -b tcp://:5557 -e 'next if /^#/; it'
+omq pull -b tcp://:5557 -e 'next if it.first.start_with?("#"); it'
 
 # stop on "quit"
-omq pull -b tcp://:5557 -e 'break if /quit/; it'
+omq pull -b tcp://:5557 -e 'break if it.first == "quit"; it'
 ```
 
 ### BEGIN/END blocks
@@ -244,8 +244,8 @@ omq req -c tcp://localhost:5555 -r./handler.rb
 
 | Method | Effect |
 |--------|--------|
-| `OMQ.outgoing { |msg| ... }` | Register outgoing message transform |
-| `OMQ.incoming { |msg| ... }` | Register incoming message transform |
+| `OMQ.outgoing { \|msg\| ... }` | Register outgoing message transform |
+| `OMQ.incoming { \|msg\| ... }` | Register incoming message transform |
 
 - use explicit block variable (like `msg`) or `it`
 - Setup: use local variables and closures at the top of the script
@@ -441,11 +441,11 @@ Pipe creates an in-process PULL → eval → PUSH pipeline:
 # basic pipe (positional: first = input, second = output)
 omq pipe -c@work -c@sink -e 'it.map(&:upcase)'
 
-# parallel Ractor workers (default: all CPUs)
-omq pipe -c@work -c@sink -P -r./fib.rb -e 'fib(Integer(it.first)).to_s'
+# parallel Ractor workers (-P0 = nproc, also combinable: -P0zvv)
+omq pipe -c@work -c@sink -P0 -r./fib.rb -e 'fib(Integer(it.first)).to_s'
 
 # fixed number of workers
-omq pipe -c@work -c@sink -P 4 -e 'it.map(&:upcase)'
+omq pipe -c@work -c@sink -P4 -e 'it.map(&:upcase)'
 
 # exit when producer disconnects
 omq pipe -c@work -c@sink --transient -e 'it.map(&:upcase)'
@@ -467,7 +467,7 @@ omq pipe --in -b tcp://:5555 --out -c@sink1 -c@sink2 -e 'it'
 omq pipe --in -b tcp://:5555 -b tcp://:5556 --out -c tcp://sink:5557 -e 'it'
 
 # parallel workers with fan-in (all must be -c)
-omq pipe --in -c@a -c@b --out -c@sink -P 4 -e 'it'
+omq pipe --in -c@a -c@b --out -c@sink -P4 -e 'it'
 ```
 
 `-P`/`--parallel` requires all endpoints to be `--connect`. In parallel mode, each Ractor worker

data/lib/omq/cli/base_runner.rb

@@ -99,7 +99,7 @@ module OMQ
 
 
       def attach_endpoints
-        SocketSetup.attach(@sock, config, verbose: config.verbose)
+        SocketSetup.attach(@sock, config, verbose: config.verbose, timestamps: config.timestamps)
       end
 
 
@@ -313,9 +313,15 @@ module OMQ
 
       def send_msg(parts)
         return if parts.empty?
+        log_parts = parts
         parts = [Marshal.dump(parts)] if config.format == :marshal
-        parts = @fmt.compress(parts)
-        @sock.send(parts)
+        if config.compress
+          wire = @fmt.compress(parts)
+          trace_msg(">>", log_parts, wire)
+          @sock.send(wire)
+        else
+          @sock.send(parts)
+        end
         transient_ready!
       end
 
@@ -324,12 +330,24 @@ module OMQ
         raw = @sock.receive
         return nil if raw.nil?
         parts = @fmt.decompress(raw)
+        trace_msg("<<", parts, raw) if config.compress
         parts = Marshal.load(parts.first) if config.format == :marshal
         transient_ready!
         parts
       end
 
 
+      # Writes an explicit -vvv message trace line. Used when compression
+      # is active: the engine-level monitor would see compressed bytes,
+      # so we log post-decompression (recv) / pre-compression (send)
+      # and annotate the compressed wire size.
+      def trace_msg(marker, parts, wire)
+        return unless config.verbose >= 3
+        wire_size = wire.sum(&:bytesize)
+        $stderr.write("#{Term.log_prefix(config.timestamps)}omq: #{marker} #{Formatter.preview(parts, wire_size: wire_size)}\n")
+      end
+
+
       def recv_msg_raw
         msg = @sock.receive
         msg&.dup
@@ -464,10 +482,13 @@ 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
+      # --timestamps[=s|ms|us]: prepend UTC timestamps to log lines
       def start_event_monitor
-        @sock.monitor(verbose: config.verbose >= 3) do |event|
-          Term.write_event(event, config.verbose)
+        # When compress is on, BaseRunner#trace_msg logs post-
+        # decompression, so we suppress the engine-level message trace.
+        trace = config.verbose >= 3 && !config.compress
+        @sock.monitor(verbose: trace) do |event|
+          Term.write_event(event, config.timestamps)
         end
       end
     end

data/lib/omq/cli/cli_parser.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "socket"
+require "etc"
 
 module OMQ
   module CLI
@@ -231,6 +232,7 @@ module OMQ
         parallel:         nil,
         transient:        false,
         verbose:          0,
+        timestamps:       nil,
         quiet:            false,
         echo:             false,
         scripts:          [],
@@ -249,6 +251,25 @@ module OMQ
       end
 
 
+      # Splits short-option clusters of the form `-P[digits][letters]`
+      # so OptionParser sees `-P[digits]` followed by `-[letters]`.
+      # Lets `-P0zvv` mean `-P0 -z -v -v` (portable & combinable).
+      # Also rewrites bare `--timestamps` to `--timestamps=ms` so
+      # OptionParser doesn't consume the next positional token as its
+      # argument.
+      #
+      def split_parallel_cluster(argv)
+        argv.flat_map { |a|
+          if a =~ /\A-P(\d*)([a-zA-Z].*)\z/
+            n, rest = $1, $2
+            n.empty? ? ["-P", "-#{rest}"] : ["-P#{n}", "-#{rest}"]
+          else
+            a
+          end
+        }.map { |a| a == "--timestamps" ? "--timestamps=ms" : a }
+      end
+
+
       # Validates option combinations, aborting on bad combos.
       #
       def self.validate!(opts)
@@ -384,8 +405,9 @@ module OMQ
             require "omq" unless defined?(OMQ::VERSION)
             opts[:scripts] << (v == "-" ? :stdin : (v.start_with?("./", "../") ? File.expand_path(v) : v))
           }
-          o.on("-P", "--parallel N", Integer, "Parallel Ractor workers (max 16)") { |v|
-            opts[:parallel] = [v, 16].min
+          o.on("-P", "--parallel [N]", Integer, "Parallel Ractor workers (0 = nproc, max 16)") { |v|
+            n = v.nil? || v.zero? ? Etc.nprocessors : v
+            opts[:parallel] = [n, 16].min
           }
 
           o.separator "\nCURVE encryption (requires system libsodium):"
@@ -397,7 +419,10 @@ module OMQ
           o.separator "            OMQ_CRYPTO (backend: rbnacl or nuckle)"
 
           o.separator "\nOther:"
-          o.on("-v", "--verbose",   "Verbosity: -v endpoints, -vv events, -vvv messages, -vvvv timestamps") { opts[:verbose] += 1 }
+          o.on("-v", "--verbose",   "Verbosity: -v endpoints, -vv events, -vvv messages") { opts[:verbose] += 1 }
+          o.on(      "--timestamps PRECISION", %w[s ms us], "Prefix log lines with UTC timestamp (s/ms/us, default ms)") { |v|
+            opts[:timestamps] = v.to_sym
+          }
           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
@@ -427,6 +452,8 @@ module OMQ
           o.separator "\nExit codes: 0 = success, 1 = error, 2 = timeout"
         end
 
+        argv = split_parallel_cluster(argv)
+
         begin
           parser.parse!(argv)
         rescue OptionParser::ParseError => e

data/lib/omq/cli/config.rb

@@ -51,6 +51,7 @@ module OMQ
       :parallel,
       :transient,
       :verbose,
+      :timestamps,
       :quiet,
       :echo,
       :scripts,

data/lib/omq/cli/expression_evaluator.rb

@@ -49,20 +49,23 @@ module OMQ
         return [result] if @format == :marshal
 
         result = result.is_a?(Array) ? result : [result]
-        result.map!(&:to_s)
+        result.map(&:to_s)
       rescue => e
         $stderr.puts "omq: eval error: #{e.message} (#{e.class})"
         exit 3
       end
 
 
-      # Normalises an eval result to nil (skip) or an Array of strings.
+      # Normalises an eval result to nil (skip) or an Array.
       # Used inside Ractor worker blocks where instance methods are unavailable.
+      # When +format+ is :marshal, arbitrary objects are preserved (wrapped
+      # in a one-element Array so the wire path can Marshal.dump them).
       #
-      def self.normalize_result(result)
+      def self.normalize_result(result, format: nil)
         return nil if result.nil?
+        return [result] if format == :marshal
         result = result.is_a?(Array) ? result : [result]
-        result.map!(&:to_s)
+        result.map(&:to_s)
       end
 
 

data/lib/omq/cli/formatter.rb

@@ -105,15 +105,19 @@ module OMQ
 
 
       # Formats message parts for human-readable preview (logging).
+      # When +wire_size+ is given, the header also shows the
+      # compressed on-the-wire size: "(29B wire=12B)".
       #
-      # @param parts [Array<String>] message frames
+      # @param parts [Array<String>] message frames (decompressed)
+      # @param wire_size [Integer, nil] compressed bytes on the wire
       # @return [String] truncated preview of each frame joined by |
-      def self.preview(parts)
+      def self.preview(parts, wire_size: nil)
         total  = parts.sum(&:bytesize)
         nparts = parts.size
         shown  = parts.first(3).map { |p| preview_frame(p) }
-        tail   = nparts > 3 ? "|..." : ""
-        header = nparts > 1 ? "(#{total}B #{nparts}F)" : "(#{total}B)"
+        tail   = nparts > 3 ? "|…" : ""
+        size   = wire_size ? "#{total}B wire=#{wire_size}B" : "#{total}B"
+        header = nparts > 1 ? "(#{size} #{nparts}F)" : "(#{size})"
 
         "#{header} #{shown.join("|")}#{tail}"
       end
@@ -133,7 +137,7 @@ module OMQ
         if printable < sample.bytesize / 2
           "[#{bytes.bytesize}B]"
         elsif bytes.bytesize > 12
-          "#{sample.gsub(/[^[:print:]]/, ".")}..."
+          "#{sample.gsub(/[^[:print:]]/, ".")}…"
         else
           sample.gsub(/[^[:print:]]/, ".")
         end

data/lib/omq/cli/parallel_worker.rb

@@ -51,20 +51,35 @@ module OMQ
       def log_endpoints
         return unless @config.verbose >= 1
         @endpoints.each do |ep|
-          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.verbose))
+          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.timestamps))
         end
       end
 
 
       def start_monitors
         return unless @config.verbose >= 2
-        trace = @config.verbose >= 3
+        # When compress is on, messages are traced explicitly post-
+        # decompression; suppress engine-level message trace to avoid
+        # showing compressed bytes.
+        trace = @config.verbose >= 3 && !@config.compress
         @sock.monitor(verbose: trace) do |event|
-          @log_port.send(OMQ::CLI::Term.format_event(event, @config.verbose))
+          @log_port.send(OMQ::CLI::Term.format_event(event, @config.timestamps))
         end
       end
 
 
+      def trace_in(parts, wire)
+        return unless @config.verbose >= 3 && @config.compress
+        @log_port.send("#{OMQ::CLI::Term.log_prefix(@config.timestamps)}omq: << #{OMQ::CLI::Formatter.preview(parts, wire_size: wire.sum(&:bytesize))}")
+      end
+
+
+      def trace_out(parts, wire)
+        return unless @config.verbose >= 3 && @config.compress
+        @log_port.send("#{OMQ::CLI::Term.log_prefix(@config.timestamps)}omq: >> #{OMQ::CLI::Formatter.preview(parts, wire_size: wire.sum(&:bytesize))}")
+      end
+
+
       def wait_for_peer
         if @config.timeout
           Fiber.scheduler.with_timeout(@config.timeout) do
@@ -104,9 +119,10 @@ module OMQ
         n = @config.count
         i = 0
         loop do
-          parts = @sock.receive
-          break if parts.nil?
-          parts = @fmt.decompress(parts)
+          wire = @sock.receive
+          break if wire.nil?
+          parts = @fmt.decompress(wire)
+          trace_in(parts, wire)
           if @eval_proc
             parts = normalize(
               @ctx.instance_exec(parts, &@eval_proc)
@@ -129,12 +145,15 @@ module OMQ
         n = @config.count
         i = 0
         loop do
-          parts = @sock.receive
-          break if parts.nil?
-          parts = @fmt.decompress(parts)
+          wire = @sock.receive
+          break if wire.nil?
+          parts = @fmt.decompress(wire)
+          trace_in(parts, wire)
           reply = compute_reply(parts)
           output(reply)
-          @sock.send(@fmt.compress(reply))
+          reply_wire = @fmt.compress(reply)
+          trace_out(reply, reply_wire)
+          @sock.send(reply_wire)
           i += 1
           break if n && n > 0 && i >= n
         end
@@ -166,7 +185,7 @@ module OMQ
 
 
       def normalize(result)
-        OMQ::CLI::ExpressionEvaluator.normalize_result(result)
+        OMQ::CLI::ExpressionEvaluator.normalize_result(result, format: @config.format)
       end
 
 

data/lib/omq/cli/pipe.rb

@@ -85,8 +85,8 @@ module OMQ
         push = OMQ::PUSH.new(**kwargs)
         SocketSetup.apply_options(pull, config)
         SocketSetup.apply_options(push, config)
-        SocketSetup.attach_endpoints(pull, in_eps, verbose: config.verbose)
-        SocketSetup.attach_endpoints(push, out_eps, verbose: config.verbose)
+        SocketSetup.attach_endpoints(pull, in_eps, verbose: config.verbose, timestamps: config.timestamps)
+        SocketSetup.attach_endpoints(push, out_eps, verbose: config.verbose, timestamps: config.timestamps)
         [pull, push]
       end
 
@@ -196,7 +196,7 @@ module OMQ
         trace = config.verbose >= 3
         [@pull, @push].each do |sock|
           sock.monitor(verbose: trace) do |event|
-            Term.write_event(event, config.verbose)
+            Term.write_event(event, config.timestamps)
           end
         end
       end

data/lib/omq/cli/pipe_worker.rb

@@ -49,21 +49,37 @@ module OMQ
 
       def log_endpoints
         (@in_eps + @out_eps).each do |ep|
-          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.verbose))
+          @log_port.send(OMQ::CLI::Term.format_attach(ep.bind? ? :bind : :connect, ep.url, @config.timestamps))
         end
       end
 
 
       def start_monitors
-        trace = @config.verbose >= 3
+        # When compress is on, messages are traced explicitly in
+        # run_message_loop post-decompression; keep engine-level
+        # traces off to avoid showing compressed bytes.
+        compress = @config.compress || @config.compress_in || @config.compress_out
+        trace    = @config.verbose >= 3 && !compress
         [@pull, @push].each do |sock|
           sock.monitor(verbose: trace) do |event|
-            @log_port.send(OMQ::CLI::Term.format_event(event, @config.verbose))
+            @log_port.send(OMQ::CLI::Term.format_event(event, @config.timestamps))
           end
         end
       end
 
 
+      def trace_in(parts, wire)
+        return unless @config.verbose >= 3 && (@config.compress || @config.compress_in)
+        @log_port.send("#{OMQ::CLI::Term.log_prefix(@config.timestamps)}omq: << #{OMQ::CLI::Formatter.preview(parts, wire_size: wire.sum(&:bytesize))}")
+      end
+
+
+      def trace_out(parts, wire)
+        return unless @config.verbose >= 3 && (@config.compress || @config.compress_out)
+        @log_port.send("#{OMQ::CLI::Term.log_prefix(@config.timestamps)}omq: >> #{OMQ::CLI::Formatter.preview(parts, wire_size: wire.sum(&:bytesize))}")
+      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.
@@ -91,39 +107,15 @@ module OMQ
         n = @config.count
         if @eval_proc
           if n && n > 0
-            n.times do
-              parts = @pull.receive
-              break if parts.nil?
-              parts = OMQ::CLI::ExpressionEvaluator.normalize_result(
-                @ctx.instance_exec(@fmt_in.decompress(parts), &@eval_proc)
-              )
-              next if parts.nil?
-              @push << @fmt_out.compress(parts) unless parts.empty?
-            end
+            n.times { break unless process_one_eval }
           else
-            loop do
-              parts = @pull.receive
-              break if parts.nil?
-              parts = OMQ::CLI::ExpressionEvaluator.normalize_result(
-                @ctx.instance_exec(@fmt_in.decompress(parts), &@eval_proc)
-              )
-              next if parts.nil?
-              @push << @fmt_out.compress(parts) unless parts.empty?
-            end
+            loop { break unless process_one_eval }
           end
         else
           if n && n > 0
-            n.times do
-              parts = @pull.receive
-              break if parts.nil?
-              @push << @fmt_out.compress(@fmt_in.decompress(parts))
-            end
+            n.times { break unless process_one_passthrough }
           else
-            loop do
-              parts = @pull.receive
-              break if parts.nil?
-              @push << @fmt_out.compress(@fmt_in.decompress(parts))
-            end
+            loop { break unless process_one_passthrough }
           end
         end
       rescue IO::TimeoutError, Async::TimeoutError
@@ -131,10 +123,38 @@ module OMQ
       end
 
 
+      def process_one_eval
+        wire_in = @pull.receive
+        return false if wire_in.nil?
+        parts_in = @fmt_in.decompress(wire_in)
+        trace_in(parts_in, wire_in)
+        parts_out = OMQ::CLI::ExpressionEvaluator.normalize_result(
+          @ctx.instance_exec(parts_in, &@eval_proc), format: @config.format
+        )
+        return true if parts_out.nil? || parts_out.empty?
+        wire_out = @fmt_out.compress(parts_out)
+        trace_out(parts_out, wire_out)
+        @push << wire_out
+        true
+      end
+
+
+      def process_one_passthrough
+        wire_in = @pull.receive
+        return false if wire_in.nil?
+        parts_in = @fmt_in.decompress(wire_in)
+        trace_in(parts_in, wire_in)
+        wire_out = @fmt_out.compress(parts_in)
+        trace_out(parts_in, wire_out)
+        @push << wire_out
+        true
+      end
+
+
       def run_end_block
         return unless @end_proc
         out = OMQ::CLI::ExpressionEvaluator.normalize_result(
-          @ctx.instance_exec(&@end_proc)
+          @ctx.instance_exec(&@end_proc), format: @config.format
         )
         @push << @fmt_out.compress(out) if out && !out.empty?
       end

data/lib/omq/cli/socket_setup.rb

@@ -58,32 +58,32 @@ module OMQ
 
 
       # Bind/connect +sock+ using URL strings from +config.binds+ / +config.connects+.
-      # +verbose+ is the integer verbosity level (0 = silent).
+      # +verbose+ gates logging (>= 1), +timestamps+ controls prefix.
       #
-      def self.attach(sock, config, verbose: 0)
+      def self.attach(sock, config, verbose: 0, timestamps: nil)
         config.binds.each do |url|
           sock.bind(url)
-          CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
+          CLI::Term.write_attach(:bind, sock.last_endpoint, timestamps) if verbose >= 1
         end
         config.connects.each do |url|
           sock.connect(url)
-          CLI::Term.write_attach(:connect, url, verbose) if verbose >= 1
+          CLI::Term.write_attach(:connect, url, timestamps) 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).
+      # +verbose+ gates logging (>= 1), +timestamps+ controls prefix.
       #
-      def self.attach_endpoints(sock, endpoints, verbose: 0)
+      def self.attach_endpoints(sock, endpoints, verbose: 0, timestamps: nil)
         endpoints.each do |ep|
           if ep.bind?
             sock.bind(ep.url)
-            CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
+            CLI::Term.write_attach(:bind, sock.last_endpoint, timestamps) if verbose >= 1
           else
             sock.connect(ep.url)
-            CLI::Term.write_attach(:connect, ep.url, verbose) if verbose >= 1
+            CLI::Term.write_attach(:connect, ep.url, timestamps) if verbose >= 1
           end
         end
       end

data/lib/omq/cli/term.rb

@@ -15,15 +15,18 @@ module OMQ
       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.
+      # Returns a stderr log line prefix with a UTC ISO8601 timestamp
+      # at the requested precision (:s/:ms/:us), or "" when nil.
       #
-      # @param verbose [Integer]
+      # @param timestamps [Symbol, nil] :s, :ms, :us, or nil (disabled)
       # @return [String]
-      def log_prefix(verbose)
-        return "" unless verbose && verbose >= 4
-        "#{Time.now.utc.strftime("%FT%T.%6N")}Z "
+      def log_prefix(timestamps)
+        case timestamps
+        when nil then ""
+        when :s  then "#{Time.now.utc.strftime("%FT%T")}Z "
+        when :ms then "#{Time.now.utc.strftime("%FT%T.%3N")}Z "
+        when :us then "#{Time.now.utc.strftime("%FT%T.%6N")}Z "
+        end
       end
 
 
@@ -31,10 +34,10 @@ module OMQ
       # trailing newline).
       #
       # @param event [OMQ::MonitorEvent]
-      # @param verbose [Integer]
+      # @param timestamps [Symbol, nil]
       # @return [String]
-      def format_event(event, verbose)
-        prefix = log_prefix(verbose)
+      def format_event(event, timestamps)
+        prefix = log_prefix(timestamps)
         case event.type
         when :message_sent
           "#{prefix}omq: >> #{Formatter.preview(event.detail[:parts])}"
@@ -52,22 +55,22 @@ module OMQ
       #
       # @param kind [:bind, :connect]
       # @param url [String]
-      # @param verbose [Integer]
+      # @param timestamps [Symbol, nil]
       # @return [String]
-      def format_attach(kind, url, verbose)
+      def format_attach(kind, url, timestamps)
         verb = kind == :bind ? "Bound to" : "Connecting to"
-        "#{log_prefix(verbose)}omq: #{verb} #{url}"
+        "#{log_prefix(timestamps)}omq: #{verb} #{url}"
       end
 
 
       # Writes one formatted event line to +io+ (default $stderr).
       #
       # @param event [OMQ::MonitorEvent]
-      # @param verbose [Integer]
+      # @param timestamps [Symbol, nil]
       # @param io [#write] writable sink, default $stderr
       # @return [void]
-      def write_event(event, verbose, io: $stderr)
-        io.write("#{format_event(event, verbose)}\n")
+      def write_event(event, timestamps, io: $stderr)
+        io.write("#{format_event(event, timestamps)}\n")
       end
 
 
@@ -76,11 +79,11 @@ module OMQ
       #
       # @param kind [:bind, :connect]
       # @param url [String]
-      # @param verbose [Integer]
+      # @param timestamps [Symbol, nil]
       # @param io [#write]
       # @return [void]
-      def write_attach(kind, url, verbose, io: $stderr)
-        io.write("#{format_attach(kind, url, verbose)}\n")
+      def write_attach(kind, url, timestamps, io: $stderr)
+        io.write("#{format_attach(kind, url, timestamps)}\n")
       end
     end
   end

data/lib/omq/cli/version.rb

@@ -2,6 +2,6 @@
 
 module OMQ
   module CLI
-    VERSION = "0.12.3"
+    VERSION = "0.13.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-cli
 version: !ruby/object:Gem::Version
-  version: 0.12.3
+  version: 0.13.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.17.8
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.17.8
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: omq-ffi
   requirement: !ruby/object:Gem::Requirement