omq 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e18ec192a40dba5a208b0548d7c4f45091a95909ee9a56eb17782bccb85855c7
-  data.tar.gz: 343a94d01152a9f76b8876b2a85f29b4adebaed2dd0fcdee958d01877f9970da
+  metadata.gz: 2cda9b6329a0fdeef3ad3f7bf23522de62917ed6652209c2f39169cb62366b9e
+  data.tar.gz: 2e86fe3f178c7959e2cc79488770c20a72522bb279909f2f85189ae56d0fe4c9
 SHA512:
-  metadata.gz: 581b7119d33deedca75f3dd4d2701a0955ad4b4434d258ce368f1b61f5c25c3b4891e210007f331e0a051043cdf0936f1f1f7d1d9dabc5b25d4d4b79deb823f6
-  data.tar.gz: 999d27f8c87edb499219d3d2927d0d67bea4a6171231e40a251348839343eca17ff9ab335735ec1585e04baa96f0ee5ff3f481128c113bb3a8f03d900f5cbfd0
+  metadata.gz: 7b3287cc83b47ec7721011aa08cfb5dbc11c1e58affd9c75b708cfd6112f7d78870aa3831f017811bdd06c98e8969283e598b4ad2f62ecb6356675a61b2b124e
+  data.tar.gz: 2d2c118209e4a4d8306359aa76eb33e3d1512a02736c2a57b484139afa3c5de726abc770280321fa5f42e02b1900d4bdc0c48cd4f5792eb48c9221cd77694d17

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.3.0 — 2026-03-26
+
+### Added
+
+- `omqcat` CLI tool — nngcat-like Swiss army knife for OMQ sockets
+  - Socket types: req, rep, pub, sub, push, pull, pair, dealer, router
+  - Formats: ascii (default, tab-separated), quoted, raw, jsonl, msgpack
+  - `-e` / `--eval` — Ruby code runs inside the socket instance
+    (`$F` = message parts, full socket API available: `self <<`, `send`,
+    `subscribe`, etc.). REP auto-replies with the return value;
+    PAIR/DEALER use `self <<` explicitly
+  - `-r` / `--require` to load gems for use in `-e`
+  - `-z` / `--compress` Zstandard compression per frame (requires `zstd-ruby`)
+  - `-D` / `-F` data sources, `-i` interval, `-n` count, `-d` delay
+  - CURVE encryption via `SERVER_KEY` / `SERVER_PUBLIC` + `SERVER_SECRET`
+    env vars (requires `omq-curve`)
+  - `--identity` / `--target` for DEALER/ROUTER patterns
+  - `tcp://:PORT` shorthand for `tcp://*:PORT` (no shell glob issues)
+  - 22 system tests via `rake test:cli`
+
+## 0.2.2 — 2026-03-26
+
+### Added
+
+- `ØMQ` alias for `OMQ` — because Ruby can
+
 ## 0.2.1 — 2026-03-26
 
 ### Improved

data/README.md

@@ -7,7 +7,11 @@
 
 Pure Ruby implementation of the [ZMTP 3.1](https://rfc.zeromq.org/spec/23/) wire protocol ([ZeroMQ](https://zeromq.org/)) using the [Async](https://github.com/socketry/async) gem. No native libraries required.
 
-> **186k msg/s** inproc throughput | **12 µs** req/rep roundtrip latency | pure Ruby + YJIT
+> **145k msg/s** inproc | **40k msg/s** ipc | **32k msg/s** tcp
+>
+> **15 µs** inproc latency | **62 µs** ipc | **88 µs** tcp
+>
+> Ruby 4.0 + YJIT on a Linux VM on a 2019 MacBook Pro (Intel) — [223k msg/s with io_uring](bench/README.md#io_uring)
 
 ---
 
@@ -25,7 +29,7 @@ Modern Ruby has closed the gap:
 
 - **YJIT** — JIT-compiled hot paths close the throughput gap with C extensions
 - **Fiber Scheduler** — non-blocking I/O without callbacks or threads (`Async` builds on this)
-- **`IO::Buffer`** — zero-copy binary reads/writes, no manual `String#b` packing
+- **`io-stream`** — buffered I/O with read-ahead, from the Async ecosystem
 
 When [CZTop](https://github.com/paddor/cztop) was written, none of this existed. Today, a pure Ruby ZMTP implementation is fast enough for production use — and you get `gem install` with no compiler toolchain, no system packages, and no segfaults.
 
@@ -109,7 +113,11 @@ end
 | Routing | `DEALER`, `ROUTER` | bidirectional |
 | Exclusive pair | `PAIR` | bidirectional |
 
-All classes live under `OMQ::`.
+All classes live under `OMQ::`. For the purists, `ØMQ` is an alias:
+
+```ruby
+req = ØMQ::REQ.new(">tcp://localhost:5555")
+```
 
 ## Performance
 

data/exe/omqcat

@@ -0,0 +1,502 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# omqcat — command-line access to OMQ (ZeroMQ) sockets.
+#
+# Usage: omqcat TYPE [options]
+#
+# Examples:
+#   omqcat rep -b tcp://:5555 -D "pong"
+#   echo "ping" | omqcat req -c tcp://localhost:5555
+#   omqcat sub -c tcp://localhost:5556 -s "weather."
+#
+
+require "omq"
+require "async"
+require "optparse"
+require "json"
+require "console"
+
+HAS_MSGPACK = begin; require "msgpack"; true; rescue LoadError; false; end
+HAS_ZSTD    = begin; require "zstd-ruby"; true; rescue LoadError; false; end
+
+SOCKET_TYPES = {
+  "req"    => OMQ::REQ,
+  "rep"    => OMQ::REP,
+  "pub"    => OMQ::PUB,
+  "sub"    => OMQ::SUB,
+  "push"   => OMQ::PUSH,
+  "pull"   => OMQ::PULL,
+  "pair"   => OMQ::PAIR,
+  "dealer" => OMQ::DEALER,
+  "router" => OMQ::ROUTER,
+}.freeze
+
+SEND_ONLY = [OMQ::PUB, OMQ::PUSH].freeze
+RECV_ONLY = [OMQ::SUB, OMQ::PULL].freeze
+
+
+# ── Option parsing ──────────────────────────────────────────────────
+
+opts = {
+  connects:     [],
+  binds:        [],
+  data:         nil,
+  file:         nil,
+  format:       :ascii,
+  subscribes:   [],
+  identity:     nil,
+  target:       nil,
+  interval:     nil,
+  count:        0,
+  delay:        nil,
+  recv_timeout: nil,
+  send_timeout: nil,
+  compress:     false,
+  expr:         nil,
+  verbose:      false,
+  quiet:        false,
+}
+
+parser = OptionParser.new do |o|
+  o.banner = "Usage: omqcat TYPE [options]\n\n" \
+             "Types: #{SOCKET_TYPES.keys.join(', ')}\n\n"
+
+  o.separator "Connection:"
+  o.on("-c", "--connect URL", "Connect to endpoint (repeatable)")   { |v| opts[:connects] << v }
+  o.on("-b", "--bind URL",    "Bind to endpoint (repeatable)")      { |v| opts[:binds] << v }
+
+  o.separator "\nData source:"
+  o.on("-D", "--data DATA",   "Message data (literal string)")      { |v| opts[:data] = v }
+  o.on("-F", "--file FILE",   "Read message from file (- = stdin)") { |v| opts[:file] = v }
+
+  o.separator "\nFormat (input + output):"
+  o.on("-A", "--ascii",   "Tab-separated frames, safe ASCII (default)") { opts[:format] = :ascii }
+  o.on("-Q", "--quoted",  "C-style quoted with escapes")                { opts[:format] = :quoted }
+  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)")         { opts[:format] = :msgpack }
+
+  o.separator "\nSubscription:"
+  o.on("-s", "--subscribe PREFIX", "Subscribe prefix (repeatable, SUB only)") { |v| opts[:subscribes] << v }
+
+  o.separator "\nIdentity/routing:"
+  o.on("--identity ID", "Set socket identity (DEALER/ROUTER)")  { |v| opts[:identity] = v }
+  o.on("--target ID",   "Target peer identity (ROUTER sending)") { |v| opts[:target] = v }
+
+  o.separator "\nTiming:"
+  o.on("-i", "--interval SECS", Float, "Repeat interval")          { |v| opts[:interval] = v }
+  o.on("-n", "--count COUNT",   Integer, "Max iterations (0=inf)") { |v| opts[:count] = v }
+  o.on("-d", "--delay SECS",    Float, "Delay before first send")  { |v| opts[:delay] = v }
+  o.on("-t", "--recv-timeout SECS", Float, "Receive timeout")      { |v| opts[:recv_timeout] = v }
+  o.on(      "--send-timeout SECS", Float, "Send timeout")         { |v| opts[:send_timeout] = v }
+
+  o.separator "\nCompression:"
+  o.on("-z", "--compress", "Zstandard compression per frame") { opts[:compress] = true }
+
+  o.separator "\nProcessing:"
+  o.on("-e", "--eval EXPR", "Eval Ruby for each message ($F = parts)") { |v| opts[:expr] = v }
+  o.on("-r", "--require LIB", "Require a Ruby library (repeatable)")   { |v| require v }
+
+  o.separator "\nOther:"
+  o.on("-v", "--verbose", "Print connection events to stderr") { opts[:verbose] = true }
+  o.on("-q", "--quiet",   "Suppress message output")           { opts[:quiet] = true }
+  o.on("-V", "--version")                                      { puts "omqcat #{OMQ::VERSION}"; exit }
+  o.on("-h", "--help")                                         { puts o; exit }
+end
+
+begin
+  parser.parse!
+rescue OptionParser::ParseError => e
+  abort e.message
+end
+
+type_name = ARGV.shift
+abort parser.to_s unless type_name
+klass = SOCKET_TYPES[type_name.downcase]
+abort "Unknown socket type: #{type_name}. Known: #{SOCKET_TYPES.keys.join(', ')}" unless klass
+
+# ── Validation ──────────────────────────────────────────────────────
+
+abort "At least one --connect or --bind is required"   if opts[:connects].empty? && opts[:binds].empty?
+abort "--data and --file are mutually exclusive"        if opts[:data] && opts[:file]
+abort "--subscribe is only valid for SUB"               if !opts[:subscribes].empty? && klass != OMQ::SUB
+abort "--identity is only valid for DEALER/ROUTER"      if opts[:identity] && ![OMQ::DEALER, OMQ::ROUTER].include?(klass)
+abort "--target is only valid for ROUTER"               if opts[:target] && klass != OMQ::ROUTER
+abort "--msgpack requires the msgpack gem"              if opts[:format] == :msgpack && !HAS_MSGPACK
+abort "--compress requires the zstd-ruby gem"           if opts[:compress] && !HAS_ZSTD
+
+(opts[:connects] + opts[:binds]).each do |url|
+  abort "inproc not supported, use tcp:// or ipc://" if url.include?("inproc://")
+end
+
+if RECV_ONLY.include?(klass) && (opts[:data] || opts[:file])
+  abort "--data/--file not valid for #{type_name} (receive-only)"
+end
+
+# ── URL normalization ───────────────────────────────────────────────
+
+normalize = ->(url) { url.sub(%r{\Atcp://:}, "tcp://*:") }
+opts[:connects].map!(&normalize)
+opts[:binds].map!(&normalize)
+
+# ── Format helpers ──────────────────────────────────────────────────
+
+def format_output(parts, fmt)
+  case fmt
+  when :ascii
+    parts.map { |p| p.b.gsub(/[^[:print:]\t]/, ".") }.join("\t") + "\n"
+  when :quoted
+    parts.map { |p|
+      p.b.gsub(/[^[:print:]]/) { |c|
+        case c
+        when "\n" then "\\n"
+        when "\r" then "\\r"
+        when "\t" then "\\t"
+        when "\\" then "\\\\"
+        else format("\\x%02x", c.ord)
+        end
+      }
+    }.join("\t") + "\n"
+  when :raw
+    parts.join
+  when :jsonl
+    JSON.generate(parts) + "\n"
+  when :msgpack
+    MessagePack.pack(parts)
+  end
+end
+
+def parse_input(line, fmt)
+  case fmt
+  when :ascii
+    line.chomp.split("\t")
+  when :quoted
+    line.chomp.split("\t").map { |p|
+      p.gsub(/\\(?:n|r|t|\\|x[0-9a-fA-F]{2})/) { |m|
+        case m
+        when "\\n" then "\n"
+        when "\\r" then "\r"
+        when "\\t" then "\t"
+        when "\\\\" then "\\"
+        else [m[2..].to_i(16)].pack("C")
+        end
+      }
+    }
+  when :raw
+    [line]
+  when :jsonl
+    arr = JSON.parse(line.chomp)
+    abort "JSON Lines input must be an array of strings" unless arr.is_a?(Array) && arr.all? { |e| e.is_a?(String) }
+    arr
+  end
+end
+
+def read_message_msgpack(io)
+  @msgpack_unpacker ||= MessagePack::Unpacker.new(io)
+  @msgpack_unpacker.read
+rescue EOFError
+  nil
+end
+
+# ── Compression helpers ─────────────────────────────────────────────
+
+def compress_frames(parts)
+  parts.map { |p| Zstd.compress(p) }
+end
+
+def decompress_frames(parts)
+  parts.map { |p| Zstd.decompress(p) }
+end
+
+# ── CURVE setup ─────────────────────────────────────────────────────
+
+def setup_curve(sock)
+  if ENV["SERVER_KEY"]
+    require "omq/curve"
+    server_key = OMQ::Z85.decode(ENV["SERVER_KEY"])
+    client_key = RbNaCl::PrivateKey.generate
+    sock.mechanism = OMQ::Curve.client(
+      client_key.public_key.to_s, client_key.to_s, server_key: server_key
+    )
+    $stderr.puts "CURVE client mode" if $VERBOSE
+  elsif ENV["SERVER_PUBLIC"] && ENV["SERVER_SECRET"]
+    require "omq/curve"
+    server_pub = OMQ::Z85.decode(ENV["SERVER_PUBLIC"])
+    server_sec = OMQ::Z85.decode(ENV["SERVER_SECRET"])
+    sock.mechanism = OMQ::Curve.server(server_pub, server_sec)
+    $stderr.puts "SERVER_KEY=#{ENV["SERVER_PUBLIC"]}"
+  end
+rescue LoadError
+  abort "omq-curve gem required for CURVE encryption: gem install omq-curve"
+end
+
+# ── I/O helpers ─────────────────────────────────────────────────────
+
+def read_next(opts)
+  if opts[:data]
+    parse_input(opts[:data] + "\n", opts[:format])
+  elsif opts[:file]
+    @file_data ||= (opts[:file] == "-" ? $stdin.read : File.read(opts[:file])).chomp
+    parse_input(@file_data + "\n", opts[:format])
+  elsif opts[:format] == :msgpack
+    read_message_msgpack($stdin)
+  elsif opts[:format] == :raw
+    data = $stdin.read
+    return nil if data.nil? || data.empty?
+    [data]
+  else
+    line = $stdin.gets
+    return nil if line.nil?
+    parse_input(line, opts[:format])
+  end
+end
+
+def send_msg(sock, parts, opts)
+  return if parts.empty?
+  parts = compress_frames(parts) if opts[:compress]
+  sock.send(parts)
+end
+
+def recv_msg(sock, opts)
+  parts = sock.receive
+  parts = decompress_frames(parts) if opts[:compress]
+  parts
+end
+
+def eval_expr(parts, sock, opts)
+  return parts unless opts[:expr]
+  $F = parts
+  result = sock.instance_eval(opts[:expr], "-e") # rubocop:disable Security/Eval
+  case result
+  when nil    then nil
+  when Array  then result
+  when String then [result]
+  else [result.to_s]
+  end
+end
+
+def output(parts, opts)
+  return if opts[:quiet]
+  parts = [""] if parts.nil?
+  $stdout.write(format_output(parts, opts[:format]))
+  $stdout.flush
+end
+
+def log(msg)
+  $stderr.puts(msg)
+end
+
+# ── Loop methods ────────────────────────────────────────────────────
+
+def send_loop(sock, opts)
+  i = 0
+  if opts[:data] || opts[:file]
+    loop do
+      parts = read_next(opts)
+      break unless parts
+      parts = eval_expr(parts, sock, opts)
+      sleep(opts[:delay]) if opts[:delay] && i == 0
+      send_msg(sock, parts, opts) if parts
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+      if opts[:interval]
+        sleep(opts[:interval])
+      else
+        break # single send without -i
+      end
+    end
+  else
+    loop do
+      parts = read_next(opts)
+      break unless parts
+      parts = eval_expr(parts, sock, opts)
+      sleep(opts[:delay]) if opts[:delay] && i == 0
+      send_msg(sock, parts, opts) if parts
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+      sleep(opts[:interval]) if opts[:interval]
+    end
+  end
+end
+
+def recv_loop(sock, opts)
+  i = 0
+  loop do
+    parts = recv_msg(sock, opts)
+    parts = eval_expr(parts, sock, opts)
+    output(parts, opts)
+    i += 1
+    break if opts[:count] > 0 && i >= opts[:count]
+  end
+end
+
+def req_loop(sock, opts)
+  i = 0
+  loop do
+    parts = read_next(opts)
+    break unless parts
+    sleep(opts[:delay]) if opts[:delay] && i == 0
+    send_msg(sock, parts, opts)
+    reply = recv_msg(sock, opts)
+    reply = eval_expr(reply, sock, opts)
+    output(reply, opts)
+    i += 1
+    break if opts[:count] > 0 && i >= opts[:count]
+    if opts[:interval]
+      sleep(opts[:interval])
+    elsif !opts[:data] && !opts[:file]
+      next # stdin mode: keep reading lines
+    else
+      break # single exchange with -D/-F and no -i
+    end
+  end
+end
+
+def rep_loop(sock, opts)
+  i = 0
+  loop do
+    msg = recv_msg(sock, opts)
+    if opts[:expr]
+      reply = eval_expr(msg, sock, opts)
+      output(reply, opts)
+      send_msg(sock, reply || [""], opts)
+    else
+      output(msg, opts)
+      reply = opts[:data] ? parse_input(opts[:data] + "\n", opts[:format]) : msg
+      send_msg(sock, reply, opts)
+    end
+    i += 1
+    break if opts[:count] > 0 && i >= opts[:count]
+  end
+end
+
+def pair_loop(sock, opts, task)
+  receiver = task.async do
+    i = 0
+    loop do
+      parts = recv_msg(sock, opts)
+      parts = eval_expr(parts, sock, opts)
+      output(parts, opts)
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+    end
+  end
+
+  sender = task.async do
+    i = 0
+    loop do
+      parts = read_next(opts)
+      break unless parts
+      parts = eval_expr(parts, sock, opts)
+      sleep(opts[:delay]) if opts[:delay] && i == 0
+      send_msg(sock, parts, opts) if parts
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+      break if (opts[:data] || opts[:file]) && !opts[:interval]
+      sleep(opts[:interval]) if opts[:interval]
+    end
+  end
+
+  if opts[:count] > 0
+    receiver.wait
+    sender.stop
+  else
+    sender.wait
+    receiver.stop
+  end
+end
+
+def router_loop(sock, opts, task)
+  receiver = task.async do
+    i = 0
+    loop do
+      parts = recv_msg(sock, opts)
+      # parts = [identity, "", ...payload]
+      identity = parts.shift
+      parts.shift if parts.first == "" # remove empty delimiter
+      # Z85-encode binary identities for display
+      id_display = identity.bytes.all? { |b| b >= 0x20 && b <= 0x7E } ? identity : OMQ::Z85.encode(identity.ljust(((identity.bytesize + 3) / 4) * 4, "\x00"))
+      result = eval_expr([id_display, *parts], sock, opts)
+      output(result, opts)
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+    end
+  end
+
+  sender = task.async do
+    i = 0
+    loop do
+      parts = read_next(opts)
+      break unless parts
+      sleep(opts[:delay]) if opts[:delay] && i == 0
+      if opts[:target]
+        parts = [opts[:target], "", *parts]
+      end
+      send_msg(sock, parts, opts)
+      i += 1
+      break if opts[:count] > 0 && i >= opts[:count]
+      break if (opts[:data] || opts[:file]) && !opts[:interval]
+      sleep(opts[:interval]) if opts[:interval]
+    end
+  end
+
+  # If count is set, the receiver will exit when count is reached.
+  # Otherwise, wait for Ctrl-C.
+  if opts[:count] > 0
+    receiver.wait
+    sender.stop
+  else
+    sender.wait
+    receiver.stop
+  end
+end
+
+# ── Signal handling ─────────────────────────────────────────────────
+
+trap("INT")  { Process.exit!(0) }
+trap("TERM") { Process.exit!(0) }
+
+# Silence Async's noisy task warnings unless verbose.
+Console.logger = Console::Logger.new(Console::Output::Null.new) unless opts[:verbose]
+
+# ── Main ────────────────────────────────────────────────────────────
+
+Async do |task|
+  sock = klass.new(nil, linger: 1)
+  sock.recv_timeout = opts[:recv_timeout] if opts[:recv_timeout]
+  sock.send_timeout = opts[:send_timeout] if opts[:send_timeout]
+  sock.identity     = opts[:identity]     if opts[:identity]
+
+  setup_curve(sock)
+
+  opts[:binds].each do |url|
+    sock.bind(url)
+    log "Bound to #{sock.last_endpoint}" if opts[:verbose]
+  end
+
+  opts[:connects].each do |url|
+    sock.connect(url)
+    log "Connecting to #{url}" if opts[:verbose]
+  end
+
+  if klass == OMQ::SUB
+    prefixes = opts[:subscribes].empty? ? [""] : opts[:subscribes]
+    prefixes.each { |p| sock.subscribe(p) }
+  end
+
+  sleep(opts[:delay]) if opts[:delay] && RECV_ONLY.include?(klass)
+
+  if    SEND_ONLY.include?(klass)  then send_loop(sock, opts)
+  elsif RECV_ONLY.include?(klass)  then recv_loop(sock, opts)
+  elsif klass == OMQ::REQ          then req_loop(sock, opts)
+  elsif klass == OMQ::REP          then rep_loop(sock, opts)
+  elsif klass == OMQ::ROUTER       then router_loop(sock, opts, task)
+  elsif opts[:data] || opts[:file] then send_loop(sock, opts)
+  else                                   pair_loop(sock, opts, task)
+  end
+
+ensure
+  sock&.close
+end

data/lib/omq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OMQ
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/omq.rb

@@ -17,3 +17,6 @@ require_relative "omq/router_dealer"
 require_relative "omq/pub_sub"
 require_relative "omq/push_pull"
 require_relative "omq/pair"
+
+# For the purists.
+ØMQ = OMQ

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: omq
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrik Wenger
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -41,13 +41,15 @@ description: Pure Ruby implementation of the ZMTP 3.1 wire protocol (ZeroMQ) usi
   the Async gem. No native libraries required.
 email:
 - paddor@gmail.com
-executables: []
+executables:
+- omqcat
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/omqcat
 - lib/omq.rb
 - lib/omq/pair.rb
 - lib/omq/pub_sub.rb