omq-cli 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5a558fd06799fcf4bee5d5036a4cac86c8482554df3998e5f42171d04e520db
-  data.tar.gz: e53bb5236bb5bc660e04ad00c10aa0f3b1e4a848ed9d74363c3943f877bf210f
+  metadata.gz: 5352d1d8bdbab1b64aa1e7a36afcc1c70619eb0ae8373d78e95c77669d6a4fec
+  data.tar.gz: 38172d3bbff810e3be322e3b8aa4e6d9e09520976d76b34e6721606dd8a15c95
 SHA512:
-  metadata.gz: 5841f42d980388be4ce4d0feea88b76a358e86f6ba6e64f6b1775dfdcad16dc349ba3866c824fa74ffb88005876e64c027de9fd93fa21417c8a5a53be3180861
-  data.tar.gz: 4b68d2c56882c87a06e75fa348eff4f9df75d5cd0c3a85c26e20e6676780c61c0413e329dff7bdbb082b861795cdf09bb30aa4b61c7279c88bbd2e29373d1552
+  metadata.gz: 158eb775b0ccea84275a69dc39e8279f41fab5f9bfeb94e8ca0c9e5dd7342b6472980e925850b7d82eceb509981942c42cd80abcb52a9e871b335075898a05b6
+  data.tar.gz: 8885731e2d99e87038bb6cffe9f4dc7edd480d285d4b2ac5b5f2244772433f70123e1ed49e9da7a9aa55944aab938bbbf10d7acc98975a04df6b45fd0a1d6b7c

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.14.1 — 2026-04-13
+
+### Changed
+
+- **`-M` (Marshal) now carries raw Ruby objects, not array-wrapped
+  frames.** Under `-M`, each wire frame is one Marshal-dumped Ruby
+  object; inside `-e` / `-E`, `it` is that object directly (not
+  `[object]`). Enables natural scalar/hash/custom-class flows:
+
+  ```sh
+  omq push -b tcp://:5557 -ME '"foo"'
+  omq pull -c tcp://:5557 -M -e '{it => it.encoding}'
+  # => {"foo" => #<Encoding:UTF-8>}
+  ```
+
+  The previous one-element-Array wrap was cosmetic — it always
+  produced exactly one wire frame anyway — so no multipart
+  semantics are lost.
+
+### Fixed
+
+- **`-vvv` trace lines now precede stdout side-effects from
+  `-e` / `-E`.** A `<<` / `>>` line is emitted from the app fiber
+  *before* the eval expression runs, so sequences like
+  `-e 'p it'` read strictly as `trace → eval output → body` on a
+  shared tty. Previous design emitted traces from the monitor
+  fiber and raced with stdout.
+- **`-vvv` under `-M` now shows the app-level object, not wire
+  bytes.** Preview header switches to `(marshal) <inspect>` with
+  sanitization and 60-byte truncation, e.g.
+  `<< (marshal) [nil, :foo, "bar"]`.
+- **`-vvv` trace preview sanitizes control characters.** Tabs,
+  newlines, CR, and backslash render as `\t`, `\n`, `\r`, `\\`;
+  other non-printables collapse to `.`. Previously raw LF inside
+  a binary frame could leak and break the single-line guarantee.
+- Test suite runs cleanly without protocol-error stderr noise.
+
 ## 0.14.0 — 2026-04-13
 
 ### Added

data/README.md

@@ -312,7 +312,7 @@ OMQ.outgoing { |msg| [*msg, Time.now.iso8601] }
 | `--raw` | Raw ZMTP binary (pipe to `hexdump -C` for debugging) |
 | `-J` / `--jsonl` | JSON Lines — `["frame1","frame2"]` per line |
 | `--msgpack` | MessagePack arrays (binary stream) |
-| `-M` / `--marshal` | Ruby Marshal (binary stream of `Array<String>` objects) |
+| `-M` / `--marshal` | Ruby Marshal — one arbitrary Ruby object per message |
 
 Multipart messages: in ASCII/quoted mode, frames are tab-separated. In JSONL mode,
 each message is a JSON array.
@@ -326,6 +326,20 @@ echo '["key","value"]' | omq push -c tcp://localhost:5557 -J
 omq pull -b tcp://:5557 -J
 ```
 
+Under `-M`, each wire frame is one Marshal-dumped Ruby object. Inside `-e` / `-E`,
+`it` is that raw object — not an Array of frames — so scalars, hashes, custom
+classes, or any Marshal-safe value flow through transparently:
+
+```sh
+# send a bare String, receive a { string => encoding } Hash
+omq push -b tcp://:5557 -ME '"foo"'
+omq pull -c tcp://:5557 -M -e '{it => it.encoding}'
+# => {"foo" => #<Encoding:UTF-8>}
+```
+
+At `-vvv`, trace lines for `-M` render the app-level object instead of wire
+bytes: `omq: >> (marshal) [nil, :foo, "bar"]`.
+
 ## Timing
 
 | Flag | Effect |

data/lib/omq/cli/base_runner.rb

@@ -266,6 +266,7 @@ module OMQ
           loop do
             parts = recv_msg
             break if parts.nil?
+            trace_recv(parts)
             parts = eval_recv_expr(parts)
             output(parts)
             i += 1
@@ -292,12 +293,24 @@ module OMQ
           @recv_tick_eof = true
           return 0
         end
+        trace_recv(parts)
         parts = eval_recv_expr(parts)
         output(parts)
         1
       end
 
 
+      # At -vvv, log the received message *before* eval runs. Eval
+      # may write to stdout (e.g. `-e 'p it'`), and we want the
+      # trace line to precede any such output so the sequence on the
+      # terminal reads as: trace → eval side-effects → body.
+      def trace_recv(parts)
+        return unless config.verbose >= 3
+        $stderr.write("#{Term.log_prefix(config.timestamps)}omq: << #{Formatter.preview(parts, format: config.format)}\n")
+        $stderr.flush
+      end
+
+
       def wait_for_loops(receiver, sender)
         if config.data || config.file || config.send_expr || config.recv_expr || config.target
           sender.wait
@@ -316,13 +329,29 @@ module OMQ
 
 
       def send_msg(parts)
-        return if parts.empty?
-        parts = [Marshal.dump(parts)] if config.format == :marshal
-        @sock.send(parts)
+        case config.format
+        when :marshal
+          trace_send(parts)
+          @sock.send([Marshal.dump(parts)])
+        else
+          return if parts.empty?
+          trace_send(parts)
+          @sock.send(parts)
+        end
         transient_ready!
       end
 
 
+      # Symmetric to #trace_recv — log the outgoing message *before*
+      # Marshal.dump runs, so -M traces show the app-level object
+      # (`[nil, :foo, "bar"]`) instead of the wire-side dump bytes.
+      def trace_send(parts)
+        return unless config.verbose >= 3
+        $stderr.write("#{Term.log_prefix(config.timestamps)}omq: >> #{Formatter.preview(parts, format: config.format)}\n")
+        $stderr.flush
+      end
+
+
       def recv_msg
         parts = @sock.receive
         return nil if parts.nil?
@@ -392,10 +421,6 @@ module OMQ
 
       def output(parts)
         return if config.quiet || parts.nil?
-        # At -vvv, the monitor fiber owns both the trace and the body
-        # output (see start_event_monitor). Skipping the app-side write
-        # avoids interleaving between the two fibers on a shared tty.
-        return if config.verbose >= 3
         $stdout.write(@fmt.encode(parts))
         $stdout.flush
       end
@@ -473,15 +498,20 @@ module OMQ
       #   -vv  log connect/disconnect/retry/timeout events
       #   -vvv also log message sent/received traces
       # --timestamps[=s|ms|us]: prepend UTC timestamps to log lines
+      #
+      # :message_received and :message_sent are intentionally skipped
+      # here and traced from BaseRunner#trace_recv / #trace_send
+      # instead — same fiber as the body write, so trace-then-body
+      # ordering is strict on a shared tty. The monitor-fiber path
+      # suffered from $stderr/$stdout buffer races and from dumping
+      # wire-side bytes (pre-Marshal.load on recv, post-Marshal.dump
+      # on send) instead of app-level parts.
+      SKIP_MONITOR_EVENTS = %i[message_received message_sent].freeze
       def start_event_monitor
-        trace        = config.verbose >= 3
-        log_events   = config.verbose >= 2
+        trace      = config.verbose >= 3
+        log_events = config.verbose >= 2
         @sock.monitor(verbose: trace) do |event|
-          Term.write_event(event, config.timestamps) if log_events
-          if trace && event.type == :message_received && !config.quiet
-            $stdout.write(@fmt.encode(event.detail[:parts]))
-            $stdout.flush
-          end
+          Term.write_event(event, config.timestamps) if log_events && !SKIP_MONITOR_EVENTS.include?(event.type)
           kill_on_protocol_error(event)
         end
       end

data/lib/omq/cli/cli_parser.rb

@@ -123,6 +123,22 @@ module OMQ
           # multipart via tabs
           printf "routing-key\tpayload" | omq push --connect tcp://localhost:5557
 
+        -- Marshal (arbitrary Ruby objects) -------------------------
+
+          # With -M, each message on the wire is one Marshal-dumped
+          # Ruby object. Inside -e/-E, `it` is that raw object — not
+          # an Array of frames — so you can send/receive scalars,
+          # hashes, custom classes, whatever Marshal handles.
+
+          # send a bare string, receive a { string => encoding } hash
+          omq push -b tcp://:5557 -ME '"foo"'
+          omq pull -c tcp://:5557 -Mvvv -e '{it => it.encoding}'
+          # output: {"foo" => #<Encoding:UTF-8>}
+
+          # -vvv traces render the app object, not wire bytes
+          omq push -b tcp://:5557 -ME '{now: Time.now, pid: Process.pid}' -vvv
+          # >> (marshal) {now: 2026-04-13 ..., pid: 12345}
+
         -- Compression ----------------------------------------------
 
           # ZMTP-Zstd is negotiated transparently during the handshake.
@@ -344,7 +360,7 @@ module OMQ
           o.on(      "--raw",     "Raw binary, no framing")                     { opts[:format] = :raw }
           o.on("-J", "--jsonl",   "JSON Lines (array of strings per line)")     { opts[:format] = :jsonl }
           o.on(      "--msgpack",  "MessagePack arrays (binary stream)")         { require "msgpack"; opts[:format] = :msgpack }
-          o.on("-M", "--marshal", "Ruby Marshal stream (binary, Array<String>)") { opts[:format] = :marshal }
+          o.on("-M", "--marshal", "Ruby Marshal stream (one arbitrary object per message)") { opts[:format] = :marshal }
 
           o.separator "\nSubscription/groups:"
           o.on("-s", "--subscribe PREFIX", "Subscribe prefix (SUB, default all)")     { |v| opts[:subscribes] << v }

data/lib/omq/cli/expression_evaluator.rb

@@ -46,7 +46,7 @@ module OMQ
         result = context.instance_exec(parts, &@eval_proc)
         return nil  if result.nil?
         return SENT if result.equal?(context)
-        return [result] if @format == :marshal
+        return result if @format == :marshal
 
         result = result.is_a?(Array) ? result : [result]
         result.map(&:to_s)
@@ -56,14 +56,16 @@ module OMQ
       end
 
 
-      # Normalises an eval result to nil (skip) or an Array.
+      # Normalises an eval result to nil (skip), an Array (text formats),
+      # or an arbitrary Ruby object (+:marshal+).
+      #
       # 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).
+      # When +format+ is :marshal, the raw result is passed through — the
+      # wire path will Marshal.dump it into a single frame.
       #
       def self.normalize_result(result, format: nil)
         return nil if result.nil?
-        return [result] if format == :marshal
+        return result if format == :marshal
         result = result.is_a?(Array) ? result : [result]
         result.map(&:to_s)
       end

data/lib/omq/cli/formatter.rb

@@ -32,7 +32,8 @@ module OMQ
         when :msgpack
           MessagePack.pack(parts)
         when :marshal
-          parts.map(&:inspect).join("\t") + "\n"
+          # Under -M, `parts` is a single Ruby object (not a frame array).
+          parts.inspect + "\n"
         end
       end
 
@@ -80,26 +81,74 @@ module OMQ
       end
 
 
+      # Whitespace/backslash → visible escape sequence used by
+      # {Formatter.sanitize}. Everything else outside printable ASCII
+      # collapses to '.' via a single String#tr call.
+      LINE_ESCAPES = {
+        "\t" => '\\t',
+        "\n" => '\\n',
+        "\r" => '\\r',
+        "\\" => '\\\\',
+      }.freeze
+
+
       # Formats message parts for human-readable preview (logging).
       # When +wire_size+ is given (ZMTP-Zstd negotiated), the header
       # also shows the compressed on-the-wire size: "(29B wire=12B)".
+      # Accepts either wire-side Array<String> (monitor events) or
+      # post-decode app parts that may contain non-String objects
+      # (e.g. -M Marshal.load output).
+      #
+      # When +format+ is +:marshal+, +parts+ is the raw Ruby object
+      # itself (not an Array of frames); the preview inspects it so
+      # the reader sees the actual payload structure (e.g.
+      # `[nil, :foo, "bar"]`) instead of a meaningless "1obj" header.
       #
-      # @param parts [Array<String>] plaintext message frames
+      # @param parts [Array<String, Object>, Object] message frames, or raw object when +format+ is :marshal
+      # @param format [Symbol, nil] active CLI format (:marshal enables object-inspect mode)
       # @param wire_size [Integer, nil] compressed bytes on the wire
       # @return [String] truncated preview of each frame joined by |
-      def self.preview(parts, wire_size: nil)
-        total  = parts.sum(&:bytesize)
+      def self.preview(parts, format: nil, wire_size: nil)
+        if format == :marshal
+          inspected = parts.inspect
+          truncated = inspected.bytesize > 60
+          inspected = inspected.byteslice(0, 60) if truncated
+          out = +"(marshal) #{sanitize(inspected)}"
+          out << "…" if truncated
+          return out
+        end
+
         nparts = parts.size
         shown  = parts.first(3).map { |p| preview_frame(p) }
         tail   = nparts > 3 ? "|…" : ""
-        size   = wire_size ? "#{total}B wire=#{wire_size}B" : "#{total}B"
+        total  = parts.all?(String) ? parts.sum(&:bytesize) : nil
+        size   =
+          if wire_size && total
+            "#{total}B wire=#{wire_size}B"
+          elsif total
+            "#{total}B"
+          else
+            "#{nparts}obj"
+          end
         header = nparts > 1 ? "(#{size} #{nparts}F)" : "(#{size})"
 
         "#{header} #{shown.join("|")}#{tail}"
       end
 
 
+      # Renders one frame or decoded object for {Formatter.preview}.
+      # Strings are sanitized byte-wise (first 12 bytes); non-String
+      # objects fall back to #inspect (always single-line) truncated
+      # at 24 bytes.
+      #
+      # @param part [String, Object]
+      # @return [String]
       def self.preview_frame(part)
+        unless part.is_a?(String)
+          s = part.inspect
+          return s.bytesize > 24 ? "#{s.byteslice(0, 24)}…" : s
+        end
+
         bytes = part.b
         # Empty frames must render as a visible marker, not as the empty
         # string — otherwise joining with "|" would produce misleading
@@ -113,11 +162,24 @@ module OMQ
         if printable < sample.bytesize / 2
           "[#{bytes.bytesize}B]"
         elsif bytes.bytesize > 12
-          "#{sample.gsub(/[^[:print:]]/, ".")}…"
+          "#{sanitize(sample)}…"
         else
-          sample.gsub(/[^[:print:]]/, ".")
+          sanitize(sample)
         end
       end
+
+
+      # Escapes bytes so a preview/body line is guaranteed single-line
+      # on a shared tty. Tab/newline/CR/backslash render as literal
+      # \t/\n/\r/\\; other non-printables collapse to '.'. Forced to
+      # binary encoding first to prevent UTF-8 quirks from rendering
+      # raw LF bytes.
+      #
+      # @param bytes [String]
+      # @return [String]
+      def self.sanitize(bytes)
+        bytes.b.gsub(/[\t\n\r\\]/, LINE_ESCAPES).tr("^ -~", ".")
+      end
     end
   end
 end

data/lib/omq/cli/radio_dish.rb

@@ -11,10 +11,16 @@ module OMQ
 
 
       def send_msg(parts)
-        return if parts.empty?
-        parts = [Marshal.dump(parts)] if config.format == :marshal
-        group = config.group || parts.shift
-        @sock.publish(group, parts.first || "")
+        case config.format
+        when :marshal
+          trace_send(parts)
+          @sock.publish(config.group || "", Marshal.dump(parts))
+        else
+          return if parts.empty?
+          trace_send(parts)
+          group = config.group || parts.shift
+          @sock.publish(group, parts.first || "")
+        end
         transient_ready!
       end
     end

data/lib/omq/cli/version.rb

@@ -2,6 +2,6 @@
 
 module OMQ
   module CLI
-    VERSION = "0.14.0"
+    VERSION = "0.14.1"
   end
 end

metadata

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