nnq-cli 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aac6e193d793225be560b51a32d4f3e713afbab8b25652be6cd76750f789e3e
-  data.tar.gz: a31568088dbc3ba5ad3df07f3e1f0f98543c1ad0c631718ae71f76d02b602c0a
+  metadata.gz: b3b69a427aa491a1d47cb1144cf96824469c9029658239250d0b98f9d69ae43a
+  data.tar.gz: 43e68cf5d450fa777e79dd8913d9381eb0b436fe08d6e193c90cb47ecc42e036
 SHA512:
-  metadata.gz: fe5db04b1ebb441274c4b182d3eabed59229c040593fe7f0388c123972a6059572c6a2dff3633e1f72abd0a6771b3b6e2812e6b00d07b9c4d75ad9bd831b8059
-  data.tar.gz: bba50ee147da4897cefce7297834584127183a04a6bb3a8c15525dabff70c04f865eaa8204dc69eebc991f72fc1cc1c01928ad5490be1ee164f656f39c70cc45
+  metadata.gz: afc90caf9d6ba1bdfe488af48991af91a73a95d88ce5d6fe156f0255c7faef85de7b6016bb9db36c41be94c504c9ac8562ebd28ba20544f280afa00a8fff2ee9
+  data.tar.gz: 4fe278dcb3f5cdfc9171c6ebbb6de1cf2a30b49c01d1597b6c359cdb1d8903290be7ed068c7c7e2dab98001c9fac5207b544b5c6b1c611a18ebac1585baceedf

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.0 — 2026-04-15
+
+- **Compression switched from LZ4 to Zstd** via the new
+  [nnq-zstd](https://github.com/paddor/nnq-zstd) gem. `-z`
+  (fast, level −3) and `-Z` (balanced, level 3) are mutually
+  exclusive and map to transparent `NNQ::Zstd.wrap` decorators
+  around each socket. Sender-side dictionary training and in-band
+  dict shipping mean compression ratios on streams of similar
+  small messages are now dramatically better than the old
+  stateless LZ4 path. Both peers still have to pass `-z`/`-Z`;
+  there is no negotiation.
+- **`-Z` / `--compress-high`** flag for balanced Zstd.
+- **Formatter no longer knows about compression.** All per-message
+  compression state and logic moved out of `Formatter`; compression
+  is applied transparently at the socket boundary via the new
+  wrapper. Fewer code paths in runners.
+- **`rlz4` dependency dropped** in favor of `nnq-zstd ~> 0.1`.
+- **Lazy loading.** `nnq/zstd` (and therefore `rzstd` and the Rust
+  extension) is only required when `-z`/`-Z` is actually used,
+  keeping startup cost unchanged for non-compressing runs.
+
 ## 0.2.0 — 2026-04-15
 
 - **Peer wait for bind-mode bounded senders** — `nnq push -b ... -d

data/lib/nnq/cli/base_runner.rb

@@ -20,7 +20,7 @@ module NNQ
       def initialize(config, socket_class)
         @config = config
         @klass  = socket_class
-        @fmt    = Formatter.new(config.format, compress: config.compress)
+        @fmt    = Formatter.new(config.format)
       end
 
 
@@ -64,7 +64,8 @@ module NNQ
 
 
       def create_socket
-        SocketSetup.build(@klass, config)
+        sock = SocketSetup.build(@klass, config)
+        SocketSetup.maybe_wrap_zstd(sock, config.compress)
       end
 
 
@@ -288,9 +289,8 @@ module NNQ
       # msg: 1-element Array. nnq sockets take a bare String body.
       def send_msg(msg)
         return if msg.empty?
-        msg = [Marshal.dump(msg.first)] if config.format == :marshal
-        msg = @fmt.compress(msg)
-        @sock.send(msg.first)
+        body = config.format == :marshal ? Marshal.dump(msg.first) : msg.first
+        @sock.send(body)
         transient_ready!
       end
 
@@ -299,10 +299,9 @@ module NNQ
       def recv_msg
         raw = @sock.receive
         return nil if raw.nil?
-        msg = @fmt.decompress([raw])
-        msg = [Marshal.load(msg.first)] if config.format == :marshal
+        body = config.format == :marshal ? Marshal.load(raw) : raw
         transient_ready!
-        msg
+        [body]
       end
 
 
@@ -415,7 +414,7 @@ module NNQ
       def set_process_title(endpoints: nil)
         eps = endpoints || config.endpoints
         title = ["nnq", config.type_name]
-        title << "-z" if config.compress
+        title << (config.compress == :balanced ? "-Z" : "-z") if config.compress
         title << "-P#{config.parallel}" if config.parallel
         eps.each do |ep|
           title << (ep.respond_to?(:url) ? ep.url : ep.to_s)

data/lib/nnq/cli/cli_parser.rb

@@ -178,9 +178,9 @@ module NNQ
         send_hwm:      nil,
         sndbuf:        nil,
         rcvbuf:        nil,
-        compress:      false,
-        compress_in:   false,
-        compress_out:  false,
+        compress:      nil,
+        compress_in:   nil,
+        compress_out:  nil,
         send_expr:     nil,
         recv_expr:     nil,
         parallel:      nil,
@@ -295,16 +295,24 @@ module NNQ
           o.on("--rcvbuf N", "SO_RCVBUF kernel buffer size (e.g. 4K, 1M)") { |v| opts[:rcvbuf] = parse_byte_size(v) }
 
           o.separator "\nCompression:"
-          o.on("-z", "--compress", "LZ4 compression per message (modal with --in/--out)") do
-            require "rlz4"
-            case pipe_side
-            when :in
-              opts[:compress_in] = true
-            when :out
-              opts[:compress_out] = true
-            else
-              opts[:compress] = true
+          load_zstd = -> { require "nnq/zstd" }
+          set_compress = lambda do |sym|
+            load_zstd.call
+            target = case pipe_side
+                     when :in  then :compress_in
+                     when :out then :compress_out
+                     else           :compress
+                     end
+            if opts[target] && opts[target] != sym
+              abort "nnq: -z and -Z are mutually exclusive"
             end
+            opts[target] = sym
+          end
+          o.on("-z", "--compress", "Zstd compression (fast, level -3; modal with --in/--out)") do
+            set_compress.call(:fast)
+          end
+          o.on("-Z", "--compress-high", "Zstd compression (balanced, level 3; modal with --in/--out)") do
+            set_compress.call(:balanced)
           end
 
           o.separator "\nProcessing (-e = incoming, -E = outgoing):"

data/lib/nnq/cli/formatter.rb

@@ -2,11 +2,9 @@
 
 module NNQ
   module CLI
-    # Raised when LZ4 decompression fails.
-    class DecompressError < RuntimeError; end
-
     # Handles encoding/decoding a single-body message in the configured
-    # format, plus optional LZ4 compression.
+    # format. Compression is handled by the NNQ::Zstd decorator around
+    # the socket, not by the formatter.
     #
     # Unlike omq-cli's Formatter, nnq messages are not multipart — one
     # `String` body per message. The API still accepts/returns a
@@ -14,10 +12,8 @@ module NNQ
     # way.
     class Formatter
       # @param format [Symbol] wire format (:ascii, :quoted, :raw, :jsonl, :msgpack, :marshal)
-      # @param compress [Boolean] whether to apply LZ4 compression
-      def initialize(format, compress: false)
-        @format   = format
-        @compress = compress
+      def initialize(format)
+        @format = format
       end
 
 
@@ -89,27 +85,6 @@ module NNQ
       end
 
 
-      # Compresses the body with LZ4 if compression is enabled.
-      #
-      # @param msg [Array<String>] single-element array
-      # @return [Array<String>] optionally compressed
-      def compress(msg)
-        @compress ? msg.map { |p| RLZ4.compress(p) if p } : msg
-      end
-
-
-      # Decompresses the body with LZ4 if compression is enabled.
-      # nil/empty bodies pass through.
-      #
-      # @param msg [Array<String>] possibly compressed single-element array
-      # @return [Array<String>] decompressed
-      def decompress(msg)
-        @compress ? msg.map { |p| p && !p.empty? ? RLZ4.decompress(p) : p } : msg
-      rescue RLZ4::DecompressError
-        raise DecompressError, "decompression failed (did the sender use --compress?)"
-      end
-
-
       # Formats a message body for human-readable preview (logging).
       #
       # @param msg [Array<String>] single-element array

data/lib/nnq/cli/pipe.rb

@@ -12,8 +12,8 @@ module NNQ
       # @param config [Config] frozen CLI configuration
       def initialize(config)
         @config  = config
-        @fmt_in  = Formatter.new(config.format, compress: config.compress_in || config.compress)
-        @fmt_out = Formatter.new(config.format, compress: config.compress_out || config.compress)
+        @fmt_in  = Formatter.new(config.format)
+        @fmt_out = Formatter.new(config.format)
       end
 
 
@@ -68,6 +68,8 @@ module NNQ
         push = SocketSetup.build(NNQ::PUSH0, config)
         SocketSetup.attach_endpoints(pull, in_eps, verbose: config.verbose)
         SocketSetup.attach_endpoints(push, out_eps, verbose: config.verbose)
+        pull = SocketSetup.maybe_wrap_zstd(pull, config.compress_in || config.compress)
+        push = SocketSetup.maybe_wrap_zstd(push, config.compress_out || config.compress)
         [pull, push]
       end
 
@@ -103,12 +105,10 @@ module NNQ
         loop do
           body = @pull.receive
           break if body.nil?
-          msg = @fmt_in.decompress([body])
-          msg = eval_recv_expr(msg)
+          msg = eval_recv_expr([body])
 
           if msg && !msg.empty?
-            out = @fmt_out.compress(msg)
-            @push.send(out.first)
+            @push.send(msg.first)
           end
 
           # Yield after send so send-pump fibers can drain the queue
@@ -163,7 +163,9 @@ module NNQ
       def set_pipe_process_title
         in_eps, out_eps = resolve_endpoints
         title = ["nnq pipe"]
-        title << "-z" if config.compress || config.compress_in || config.compress_out
+        if (m = config.compress || config.compress_in || config.compress_out)
+          title << (m == :balanced ? "-Z" : "-z")
+        end
         title << "-P#{config.parallel}" if config.parallel
         title.concat(in_eps.map(&:url))
         title << "->"

data/lib/nnq/cli/pipe_worker.rb

@@ -24,8 +24,8 @@ module NNQ
           compile_expr
           run_message_loop
           run_end_block
-        rescue NNQ::CLI::DecompressError => e
-          @error_port&.send(e.message)
+        rescue NNQ::Zstd::ProtocolError => e
+          @error_port&.send("zstd protocol error: #{e.message}")
         ensure
           @pull&.close
           @push&.close
@@ -41,6 +41,8 @@ module NNQ
         @push = NNQ::CLI::SocketSetup.build(NNQ::PUSH0, @config)
         NNQ::CLI::SocketSetup.attach_endpoints(@pull, @in_eps, verbose: 0)
         NNQ::CLI::SocketSetup.attach_endpoints(@push, @out_eps, verbose: 0)
+        @pull = NNQ::CLI::SocketSetup.maybe_wrap_zstd(@pull, @config.compress_in || @config.compress)
+        @push = NNQ::CLI::SocketSetup.maybe_wrap_zstd(@push, @config.compress_out || @config.compress)
       end
 
 
@@ -86,8 +88,6 @@ module NNQ
       def compile_expr
         @begin_proc, @end_proc, @eval_proc =
           NNQ::CLI::ExpressionEvaluator.compile_inside_ractor(@config.recv_expr)
-        @fmt_in  = NNQ::CLI::Formatter.new(@config.format, compress: @config.compress_in || @config.compress)
-        @fmt_out = NNQ::CLI::Formatter.new(@config.format, compress: @config.compress_out || @config.compress)
         @ctx = Object.new
         @ctx.instance_exec(&@begin_proc) if @begin_proc
       end
@@ -100,11 +100,10 @@ module NNQ
             body = @pull.receive
             break if body.nil?
             msg = NNQ::CLI::ExpressionEvaluator.normalize_result(
-              @ctx.instance_exec(@fmt_in.decompress([body]), &@eval_proc)
+              @ctx.instance_exec([body], &@eval_proc)
             )
             unless msg.nil? || msg.empty?
-              out = @fmt_out.compress(msg)
-              @push.send(out.first)
+              @push.send(msg.first)
             end
             n -= 1 if n && n > 0
             break if n == 0
@@ -113,8 +112,7 @@ module NNQ
           loop do
             body = @pull.receive
             break if body.nil?
-            out = @fmt_out.compress(@fmt_in.decompress([body]))
-            @push.send(out.first)
+            @push.send(body)
             n -= 1 if n && n > 0
             break if n == 0
           end
@@ -130,7 +128,7 @@ module NNQ
           @ctx.instance_exec(&@end_proc)
         )
         if out && !out.empty?
-          @push.send(@fmt_out.compress(out).first)
+          @push.send(out.first)
         end
       end
     end

data/lib/nnq/cli/req_rep.rb

@@ -32,14 +32,12 @@ module NNQ
 
       def request_and_receive(msg)
         return nil if msg.empty?
-        msg = [Marshal.dump(msg.first)] if config.format == :marshal
-        msg = @fmt.compress(msg)
-        reply_body = @sock.send_request(msg.first)
+        body = config.format == :marshal ? Marshal.dump(msg.first) : msg.first
+        reply_body = @sock.send_request(body)
         transient_ready!
         return nil if reply_body.nil?
-        reply = @fmt.decompress([reply_body])
-        reply = [Marshal.load(reply.first)] if config.format == :marshal
-        reply
+        reply = config.format == :marshal ? Marshal.load(reply_body) : reply_body
+        [reply]
       end
 
 
@@ -95,9 +93,8 @@ module NNQ
 
       def send_reply(msg)
         return if msg.empty?
-        msg = [Marshal.dump(msg.first)] if config.format == :marshal
-        msg = @fmt.compress(msg)
-        @sock.send_reply(msg.first)
+        body = config.format == :marshal ? Marshal.dump(msg.first) : msg.first
+        @sock.send_reply(body)
         transient_ready!
       end
     end

data/lib/nnq/cli/socket_setup.rb

@@ -77,6 +77,16 @@ module NNQ
       end
 
 
+      # Wrap +sock+ with NNQ::Zstd if +mode+ is :fast or :balanced.
+      # Returns the wrapper (decorator) or +sock+ unchanged.
+      def self.maybe_wrap_zstd(sock, mode)
+        return sock unless mode
+        require "nnq/zstd"
+        level = mode == :balanced ? 3 : -3
+        NNQ::Zstd.wrap(sock, level: level)
+      end
+
+
       # Subscribe to prefixes on a SUB socket.
       #
       # Unlike ZeroMQ, nng's sub0 starts with an empty subscription set,

data/lib/nnq/cli/surveyor_respondent.rb

@@ -30,9 +30,8 @@ module NNQ
 
       def survey_and_collect(msg)
         return if msg.empty?
-        msg = [Marshal.dump(msg.first)] if config.format == :marshal
-        msg = @fmt.compress(msg)
-        @sock.send_survey(msg.first)
+        body = config.format == :marshal ? Marshal.dump(msg.first) : msg.first
+        @sock.send_survey(body)
         transient_ready!
         collect_replies
       end
@@ -42,9 +41,8 @@ module NNQ
         loop do
           body = @sock.receive
           break if body.nil?
-          reply = @fmt.decompress([body])
-          reply = [Marshal.load(reply.first)] if config.format == :marshal
-          output(eval_recv_expr(reply))
+          reply = config.format == :marshal ? Marshal.load(body) : body
+          output(eval_recv_expr([reply]))
         rescue NNQ::TimedOut
           break
         end
@@ -102,9 +100,8 @@ module NNQ
 
       def send_reply(msg)
         return if msg.empty?
-        msg = [Marshal.dump(msg.first)] if config.format == :marshal
-        msg = @fmt.compress(msg)
-        @sock.send_reply(msg.first)
+        body = config.format == :marshal ? Marshal.dump(msg.first) : msg.first
+        @sock.send_reply(body)
         transient_ready!
       end
     end

data/lib/nnq/cli/version.rb

@@ -2,6 +2,6 @@
 
 module NNQ
   module CLI
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/nnq/cli.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 require "optparse"
+
+# Forward-declare NNQ::Zstd::ProtocolError so the rescue clause below
+# resolves even when compression wasn't requested and `nnq/zstd` was
+# never required. The real class is defined in nnq-zstd; re-opening it
+# here with the same StandardError superclass is benign.
+module NNQ
+  module Zstd
+    class ProtocolError < StandardError; end
+  end
+end
+
 require_relative "cli/version"
 require_relative "cli/config"
 require_relative "cli/cli_parser"
@@ -153,8 +164,8 @@ module NNQ
                    runner_class.new(config)
                  end
         runner.call(task)
-      rescue DecompressError => e
-        $stderr.puts "nnq: #{e.message}"
+      rescue NNQ::Zstd::ProtocolError => e
+        $stderr.puts "nnq: zstd protocol error: #{e.message}"
         exit 1
       rescue IO::TimeoutError, Async::TimeoutError
         $stderr.puts "nnq: timeout" unless config.quiet

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nnq-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -24,37 +24,37 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.5'
 - !ruby/object:Gem::Dependency
-  name: msgpack
+  name: nnq-zstd
   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'
 - !ruby/object:Gem::Dependency
-  name: rlz4
+  name: msgpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0'
 description: Command-line tool for sending and receiving nanomsg SP messages on any
   NNQ socket type (REQ/REP, PUB/SUB, PUSH/PULL, PAIR). Supports Ruby eval (-e/-E),
   script handlers (-r), the virtual `pipe` socket with optional Ractor parallelism,
-  multiple formats (ASCII, JSON Lines, msgpack, Marshal), and LZ4 compression. Like
+  multiple formats (ASCII, JSON Lines, msgpack, Marshal), and Zstd compression. Like
   nngcat from libnng, but with Ruby superpowers.
 email:
 - paddor@gmail.com