omq-cli 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca06571b7529ab16630ce2f769a2320607baf67b87888218ada7a1aa6f05f52a
-  data.tar.gz: c46c9b2a8b358ac16d295ea15031da901859c0130295f4508cf3422eac083a24
+  metadata.gz: a4acc7ab47167da27247f7b45b82729da6302868879f1a003727ff2b359d42d5
+  data.tar.gz: 4a667cab2f594ade3cdc7b4234dc97562bbee043707992935d566dd563530795
 SHA512:
-  metadata.gz: bcaa20a52a55171a61098296f0a0a9d8e653bbc6758cf0b21c692c54baa483b3d0d07d96e8c1c9095853984e7c4fe64a2efee60934c193a583892651afa896d8
-  data.tar.gz: 93f70eb26ca6e182486fb2280dedf1b780fa084e9d810c5d9eaeeb3842cdcbe968e22b9ec6517ce69d395c095350f59c94aff142c2ce75f9ecc31a925b1ff73b
+  metadata.gz: 41f4141def92292e2a35412af5ddd9d1a567af2b150b59e805452cde24f9a17279e162d47f44bcb84c9d1e7fb3ad8dad2971162ffad2f38814f753c17db95ab7
+  data.tar.gz: 340c7f417266cbeb7020cd19a3a0161de78310b78cf554443c71ba22cef05c69611e38f9d4ef9370ae37b2c27bed2b59241c15ff88e7e077663ae0d0503d6f9b

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.9.0 — 2026-04-08
+
+### Changed
+
+- **`--recv-maxsz` defaults to 1 MiB in the CLI** — the underlying `omq`
+  library no longer imposes a default (it's `nil`/unlimited as of this
+  release), but the CLI keeps a conservative 1 MiB cap for safety when
+  connecting to untrusted peers from a terminal. Pass `--recv-maxsz 0`
+  to disable the cap explicitly, or `--recv-maxsz N` to raise it.
+- **Default HWM lowered to 100** (from libzmq's 1000) for both send and
+  recv. The CLI is typically used interactively or for short pipelines
+  where a smaller in-flight queue keeps memory bounded and surfaces
+  backpressure earlier. Users who want the old behavior can pass
+  `--send-hwm 1000 --recv-hwm 1000` (or `0` for unbounded). Pipe worker
+  sockets are unaffected — they still override to `PIPE_HWM` internally.
+- **Compression codec: Zstandard → LZ4 frame format (BREAKING on the wire).**
+  `--compress` now uses the new [`rlz4`](../rlz4) gem (Rust extension over
+  `lz4_flex`) instead of `zstd-ruby`. Motivation: `zstd-ruby` is the only
+  existing Ractor-safe compressor gem, but LZ4 is a better fit for the
+  per-message-part workload (smaller frames, lower CPU). `rlz4` is
+  Ractor-safe by construction, so parallel `-P` workers now use the same
+  codec as the sequential path. **Wire format is incompatible** with prior
+  omq-cli versions when `--compress` is in use — both ends must upgrade.
+
+### Added
+
+- **`--ffi` flag** — opt-in libzmq backend for any socket runner. Builds
+  sockets with `backend: :ffi`, so the CLI can drive native libzmq instead
+  of the pure-Ruby engine. Requires the optional `omq-ffi` gem and a
+  system libzmq 4.x; missing dependencies abort with a clear error.
+  Propagated through all socket construction sites: `BaseRunner`,
+  `PipeRunner`, `PipeWorker`, and `ParallelWorker`.
+
+### Fixed
+
+- **`--send-eval` / `-E` on REP** — now rejected at validation time. REP
+  derives its reply from `--recv-eval` / `-e`, so `-E` was silently
+  ignored and the runner fell through to reading stdin, hanging the
+  request-reply cycle.
+- **`-vvv` preview of REP/REQ envelopes** — empty delimiter frames now
+  render as `[0B]` instead of an empty string, so a REP reply with wire
+  parts `["", "1"]` previews as `(1B) [0B]|1` instead of the misleading
+  `(1B) |1` with a dangling leading pipe.
+
 ## 0.8.2 — 2026-04-08
 
 ### Fixed

data/README.md

@@ -336,7 +336,8 @@ omq pull -b tcp://:5557 -t 5
 
 ## Compression
 
-Both sides must use `--compress` (`-z`). Requires the `zstd-ruby` gem.
+Both sides must use `--compress` (`-z`). Uses LZ4 frame format, provided
+by the `rlz4` gem (Ractor-safe, Rust extension via `lz4_flex`).
 
 ```sh
 omq push -c tcp://remote:5557 -z < data.txt

data/lib/omq/cli/cli_parser.rb

@@ -233,6 +233,7 @@ module OMQ
         curve_server:     false,
         curve_server_key: nil,
         crypto:     nil,
+        ffi:              false,
       }.freeze
 
 
@@ -338,9 +339,9 @@ module OMQ
                                    end
           }
           o.on("--heartbeat-ivl SECS", Float, "ZMTP heartbeat interval (detects dead peers)") { |v| opts[:heartbeat_ivl] = v }
-          o.on("--recv-maxsz COUNT", Integer, "Max inbound message size in bytes (larger messages dropped)") { |v| opts[:recv_maxsz] = v }
-          o.on("--send-hwm N", Integer, "Send high water mark (default 1000, 0=unbounded)") { |v| opts[:send_hwm] = v }
-          o.on("--recv-hwm N", Integer, "Recv high water mark (default 1000, 0=unbounded)") { |v| opts[:recv_hwm] = 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("--send-hwm N", Integer, "Send high water mark (default 100, 0=unbounded)") { |v| opts[:send_hwm] = v }
+          o.on("--recv-hwm N", Integer, "Recv high water mark (default 100, 0=unbounded)") { |v| opts[:recv_hwm] = v }
           o.on("--sndbuf N", "SO_SNDBUF kernel buffer size (e.g. 4K, 1M)") { |v| opts[:sndbuf] = parse_byte_size(v) }
           o.on("--rcvbuf N", "SO_RCVBUF kernel buffer size (e.g. 4K, 1M)") { |v| opts[:rcvbuf] = parse_byte_size(v) }
 
@@ -348,8 +349,8 @@ module OMQ
           o.on("--conflate", "Keep only last message per subscriber (PUB/RADIO)") { opts[:conflate] = true }
 
           o.separator "\nCompression:"
-          o.on("-z", "--compress", "Zstandard compression per frame (modal with --in/--out)") do
-            require "zstd-ruby"
+          o.on("-z", "--compress", "LZ4 compression per frame (modal with --in/--out)") do
+            require "rlz4"
             case pipe_side
             when :in
               opts[:compress_in] = true
@@ -383,6 +384,14 @@ module OMQ
           o.on("-v", "--verbose",   "Verbosity: -v endpoints, -vv events, -vvv messages") { 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
+            begin
+              require "omq/ffi"
+            rescue LoadError => e
+              abort "omq: --ffi requires the omq-ffi gem and system libzmq 4.x (#{e.message})"
+            end
+            opts[:ffi] = true
+          end
           o.on("-V", "--version") {
             if ENV["OMQ_DEV"]
               require_relative "../../../../omq/lib/omq/version"
@@ -430,21 +439,20 @@ module OMQ
       end
 
 
-      # Parses a byte size string with optional K/M suffix.
+      # Parses a byte size string with an optional K/M/G suffix (binary,
+      # i.e. 1K = 1024 bytes).
       #
-      # @param str [String] e.g. "4096", "4K", "1M"
+      # @param str [String] e.g. "4096", "4K", "1M", "2G"
       # @return [Integer] size in bytes
       #
       def parse_byte_size(str)
         case str
-        when /\A(\d+)[kK]\z/
-          $1.to_i * 1024
-        when /\A(\d+)[mM]\z/
-          $1.to_i * 1024 * 1024
-        when /\A\d+\z/
-          str.to_i
+        when /\A(\d+)[kK]\z/ then $1.to_i * 1024
+        when /\A(\d+)[mM]\z/ then $1.to_i * 1024 * 1024
+        when /\A(\d+)[gG]\z/ then $1.to_i * 1024 * 1024 * 1024
+        when /\A\d+\z/       then str.to_i
         else
-          abort "invalid byte size: #{str} (use e.g. 4096, 4K, 1M)"
+          abort "invalid byte size: #{str} (use e.g. 4096, 4K, 1M, 2G)"
         end
       end
 
@@ -482,6 +490,7 @@ module OMQ
         abort "--conflate is only valid for PUB/RADIO"          if opts[:conflate] && !%w[pub radio].include?(type_name)
         abort "--recv-eval is not valid for send-only sockets (use --send-eval / -E)" if opts[:recv_expr] && SEND_ONLY.include?(type_name)
         abort "--send-eval is not valid for recv-only sockets (use --recv-eval / -e)" if opts[:send_expr] && RECV_ONLY.include?(type_name)
+        abort "--send-eval is not valid for REP (the reply is the result of --recv-eval / -e)" if opts[:send_expr] && type_name == "rep"
         abort "--send-eval and --target are mutually exclusive"  if opts[:send_expr] && opts[:target]
 
         if opts[:parallel]

data/lib/omq/cli/config.rb

@@ -58,6 +58,7 @@ module OMQ
       :curve_server,
       :curve_server_key,
       :crypto,
+      :ffi,
       :stdin_is_tty,
     ) do
       # @return [Boolean] true if this socket type only sends

data/lib/omq/cli/formatter.rb

@@ -2,14 +2,14 @@
 
 module OMQ
   module CLI
-    # Raised when Zstandard decompression fails.
+    # Raised when LZ4 decompression fails.
     class DecompressError < RuntimeError; end
 
     # Handles encoding/decoding messages in the configured format,
-    # plus optional Zstandard compression.
+    # plus optional LZ4 compression.
     class Formatter
       # @param format [Symbol] wire format (:ascii, :quoted, :raw, :jsonl, :msgpack, :marshal)
-      # @param compress [Boolean] whether to apply Zstandard compression per frame
+      # @param compress [Boolean] whether to apply LZ4 compression per frame
       def initialize(format, compress: false)
         @format   = format
         @compress = compress
@@ -83,22 +83,22 @@ module OMQ
       end
 
 
-      # Compresses each frame with Zstandard if compression is enabled.
+      # Compresses each frame with LZ4 if compression is enabled.
       #
       # @param parts [Array<String>] message frames
       # @return [Array<String>] optionally compressed frames
       def compress(parts)
-        @compress ? parts.map { |p| Zstd.compress(p) } : parts
+        @compress ? parts.map { |p| RLZ4.compress(p) } : parts
       end
 
 
-      # Decompresses each frame with Zstandard if compression is enabled.
+      # Decompresses each frame with LZ4 if compression is enabled.
       #
       # @param parts [Array<String>] possibly compressed message frames
       # @return [Array<String>] decompressed frames
       def decompress(parts)
-        @compress ? parts.map { |p| Zstd.decompress(p) } : parts
-      rescue
+        @compress ? parts.map { |p| RLZ4.decompress(p) } : parts
+      rescue RLZ4::DecompressError
         raise DecompressError, "decompression failed (did the sender use --compress?)"
       end
 
@@ -110,15 +110,23 @@ module OMQ
       def self.preview(parts)
         total = parts.sum(&:bytesize)
         shown = parts.first(3).map { |p| preview_frame(p) }
-        tail = parts.size > 3 ? "|...(#{parts.size} parts)" : ""
+        tail  = parts.size > 3 ? "|...(#{parts.size} parts)" : ""
+
         "(#{total}B) #{shown.join("|")}#{tail}"
       end
 
 
       def self.preview_frame(part)
         bytes = part.b
-        sample = bytes[0, 12]
+        # Empty frames must render as a visible marker, not as the empty
+        # string — otherwise joining with "|" would produce misleading
+        # output like "|body" for REP/REQ-style envelopes where the first
+        # wire frame is an empty delimiter.
+        return "[0B]" if bytes.empty?
+
+        sample    = bytes[0, 12]
         printable = sample.count("\x20-\x7e")
+
         if printable < sample.bytesize / 2
           "[#{bytes.bytesize}B]"
         elsif bytes.bytesize > 12

data/lib/omq/cli/parallel_worker.rb

@@ -41,7 +41,7 @@ module OMQ
 
 
       def setup_socket
-        @sock = OMQ.const_get(@socket_sym).new
+        @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)

data/lib/omq/cli/pipe.rb

@@ -80,8 +80,9 @@ module OMQ
 
 
       def build_pull_push(in_eps, out_eps)
-        pull = OMQ::PULL.new
-        push = OMQ::PUSH.new
+        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

data/lib/omq/cli/pipe_worker.rb

@@ -37,8 +37,9 @@ module OMQ
 
 
       def setup_sockets
-        @pull = OMQ::PULL.new
-        @push = OMQ::PUSH.new
+        kwargs = @config.ffi ? { backend: :ffi } : {}
+        @pull = OMQ::PULL.new(**kwargs)
+        @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
@@ -71,7 +72,7 @@ module OMQ
         when :message_received
           "omq: << #{OMQ::CLI::Formatter.preview(event.detail[:parts])}"
         else
-          ep = event.endpoint ? " #{event.endpoint}" : ""
+          ep     = event.endpoint ? " #{event.endpoint}" : ""
           detail = event.detail ? " #{event.detail}" : ""
           "omq: #{event.type}#{ep}#{detail}"
         end

data/lib/omq/cli/socket_setup.rb

@@ -6,6 +6,21 @@ module OMQ
     # All methods are module-level so callers compose rather than inherit.
     #
     module SocketSetup
+      # Default high water mark applied when the user does not pass
+      # --send-hwm / --recv-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
+
+      # Default max inbound message size applied when the user does not
+      # pass --recv-maxsz. The omq library itself is unlimited by default;
+      # the CLI caps inbound messages at 1 MiB so that a misconfigured or
+      # malicious peer cannot force arbitrary memory allocation on a
+      # terminal user. Users can raise it with --recv-maxsz N, or disable
+      # it entirely with --recv-maxsz 0.
+      DEFAULT_RECV_MAXSZ = 1 << 20
+
       # Apply common socket options from +config+ to +sock+.
       #
       def self.apply_options(sock, config)
@@ -14,8 +29,9 @@ module OMQ
         sock.send_timeout       = config.timeout       if config.timeout
         sock.reconnect_interval = config.reconnect_ivl if config.reconnect_ivl
         sock.heartbeat_interval = config.heartbeat_ivl if config.heartbeat_ivl
-        sock.send_hwm           = config.send_hwm      if config.send_hwm
-        sock.recv_hwm           = config.recv_hwm      if config.recv_hwm
+        # nil → default; 0 stays 0 (unbounded), any other integer is taken as-is.
+        sock.send_hwm           = config.send_hwm || DEFAULT_HWM
+        sock.recv_hwm           = config.recv_hwm || DEFAULT_HWM
         sock.sndbuf             = config.sndbuf        if config.sndbuf
         sock.rcvbuf             = config.rcvbuf        if config.rcvbuf
       end
@@ -24,10 +40,16 @@ module OMQ
       # Create and fully configure a socket from +klass+ and +config+.
       #
       def self.build(klass, config)
-        sock = klass.new
+        sock = config.ffi ? klass.new(backend: :ffi) : klass.new
         sock.conflate = true if config.conflate && %w[pub radio].include?(config.type_name)
         apply_options(sock, config)
-        sock.max_message_size = config.recv_maxsz if config.recv_maxsz
+        # --recv-maxsz: nil → 1 MiB default; 0 → explicitly unlimited; else → as-is.
+        sock.max_message_size =
+          case config.recv_maxsz
+          when nil then DEFAULT_RECV_MAXSZ
+          when 0   then nil
+          else          config.recv_maxsz
+          end
         sock.identity         = config.identity   if config.identity
         sock.router_mandatory = true if config.type_name == "router"
         sock

data/lib/omq/cli/version.rb

@@ -2,6 +2,6 @@
 
 module OMQ
   module CLI
-    VERSION = "0.8.2"
+    VERSION = "0.9.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-cli
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -128,24 +128,24 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency
-  name: zstd-ruby
+  name: rlz4
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
 description: Command-line tool for sending and receiving ZeroMQ messages on any socket
   type (REQ/REP, PUB/SUB, PUSH/PULL, DEALER/ROUTER, and all draft types). Supports
   Ruby eval (-e/-E), script handlers (-r), pipe virtual socket with Ractor parallelism,
-  multiple formats (ASCII, JSON Lines, msgpack, Marshal), Zstandard compression, and
-  CURVE encryption. Like nngcat from libnng, but with Ruby superpowers.
+  multiple formats (ASCII, JSON Lines, msgpack, Marshal), LZ4 compression, and CURVE
+  encryption. Like nngcat from libnng, but with Ruby superpowers.
 email:
 - paddor@gmail.com
 executables: