omq-cli 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b1d3b2b127f70f0c59d6e008de4b4f94a0886012819953a3028ca346ecc1feb
-  data.tar.gz: a1e912d9aec54b22e4467cb7b2e24c3765333feb5b5fd83cbfc2fa27e0b6a3b9
+  metadata.gz: 7962982bfc0731a3f52ef7de818d9b479f60ec3046002592f92d9aed601f3047
+  data.tar.gz: 961aea9c3ecb30189672dff9bb3c29539f001a615813c9b132529034201b9681
 SHA512:
-  metadata.gz: e773ac7df2e7aab7212491ded8c85fe7b6591ec5c4f3553efcac5f23786f54db9fc20b25af5df835e4b0ae17e1117ad63178e3429e616fc18bf00a43f2ca8eee
-  data.tar.gz: 6ef6c64204c54e18f8f3fced595ac4b0b3f36299f528cca981dc34876fa654a73c744be1324318a5fd0f2308f002d594779654facc143f5c19096d18534a39cf
+  metadata.gz: 3e0fe43bba8360dce4daf5c8c8d46ba05010afc8a9c6958c013f3769508ea7123936b4092ff81f42d0371cf385bffc0329995ffd3f55839047135021a750cdca
+  data.tar.gz: 3fe10d13fa4c7f079d99a89423e6d7fa6ac5fab7c121ddd3518ba021ff8668bea1a65473363cf5708b8921a7712741d923713d6c982e149efe24e564315b87c6

data/CHANGELOG.md

@@ -1,5 +1,163 @@
 # Changelog
 
+## 0.3.0 — 2026-04-07
+
+### Fixed
+
+- **Fix broken Gemfile** — remove deleted `omq-draft`, add all RFC gems
+  with `OMQ_DEV` path resolution.
+- **Fix CURVE API calls** — `Curve.server` and `Curve.client` now use
+  keyword arguments to match the updated protocol-zmtp API.
+- **Replace `require "omq/draft/all"`** with explicit RFC requires
+  (`omq/rfc/clientserver`, `radiodish`, `scattergather`, `channel`, `p2p`).
+
+### Changed
+
+- YARD documentation on all public methods and classes.
+- Code style: two blank lines between methods and constants.
+
+### Refactored
+
+- **`req_rep.rb` + `pair.rb` method extraction** — `ReqRunner#run_loop` (23 lines)
+  gains `wait_for_interval`; `RepRunner#run_loop` (27 lines) gains
+  `handle_rep_request`; `PairRunner#run_loop` (20 lines) gains `recv_async`.
+  Each `run_loop` shrinks to ~10 lines.
+
+- **`BaseRunner` method extraction** — `call` (23 lines), `wait_for_peer` (18),
+  `read_next` (20), `run_send_logic` (29), and `compile_expr` (13) each
+  decomposed into focused helpers: `setup_socket`, `maybe_start_transient_monitor`,
+  `run_begin_blocks`, `run_end_blocks`, `wait_for_subscriber`, `apply_grace_period`,
+  `read_inline_data`, `read_stdin_input`, `run_interval_send`, `run_stdin_send`,
+  `compile_evaluator`, `assign_send_aliases`, `assign_recv_aliases`.
+  Every public-facing method is now ≤10 lines.
+
+- **`RoutingHelper`: extract `async_send_loop`, `interval_send_loop`, `stdin_send_loop`** —
+  the sender `task.async` block was identical in `RouterRunner#run_loop` and
+  `ServerRunner#monitor_loop`. Moved to `RoutingHelper` and split into three
+  focused helpers. Both callers reduced to a 3-line orchestration.
+  `ServerRunner#reply_loop` gained `handle_server_request` to hold the 3-branch
+  dispatch, leaving the loop itself at ~8 lines.
+
+- **`pipe.rb` method extraction** — `run_sequential` (50 lines) and `run_parallel`
+  (105 lines) decomposed into focused helpers: `build_pull_push`,
+  `apply_socket_intervals`, `setup_sequential_transient`, `sequential_message_loop`,
+  `build_socket_pairs`, `wait_for_pairs`, `setup_parallel_transient`,
+  `build_worker_data`, `spawn_workers`, `join_workers`. Each caller shrinks to
+  ~8 lines.
+
+- **Hoist `eval_proc` + `Integer#times` in Ractor worker loops** — in both
+  `ParallelRecvRunner` and `pipe.rb#spawn_workers`, `if eval_proc` was checked
+  on every message despite being invariant. Now a pre-loop branch splits into
+  two (or four, combined with `n_count`) separate loops. Count limits use
+  `n.times` instead of a manual `i` counter, eliminating the `n && n > 0`
+  check from every iteration.
+
+- **`ExpressionEvaluator.normalize_result`** — the `case result when nil/Array/String/else`
+  block appeared in both Ractor worker bodies (`ParallelRecvRunner` and `pipe.rb`).
+  Extracted to a class method and both callers updated to use it.
+
+- **Extract `ParallelRecvRunner`** — `BaseRunner#run_parallel_recv` (107 lines
+  of Ractor worker management) moved into `OMQ::CLI::ParallelRecvRunner` in
+  `lib/omq/cli/parallel_recv_runner.rb`. Constructor takes `klass, config, fmt,
+  output_fn`; `BaseRunner#run_parallel_recv` becomes a 4-line delegator.
+  `BaseRunner` shrinks from 426 to ~325 lines.
+
+- **Extract `CliParser`** — `parse_options` (178 lines), `validate!` (48 lines),
+  `validate_gems!`, `DEFAULT_OPTS`, and the `EXAMPLES` heredoc (184 lines) moved
+  from the `OMQ::CLI` module into a dedicated `OMQ::CLI::CliParser` class in
+  `lib/omq/cli/cli_parser.rb`. `CLI.build_config` now calls `CliParser.parse`
+  and `CliParser.validate!`; `CLI.run_socket` calls `CliParser.validate_gems!`.
+  `cli.rb` shrinks from 674 to ~200 lines.
+
+- **`ReqRunner#run_loop` deduplication** — the interval and non-interval
+  branches were identical loops; merged into one with a trailing
+  `sleep(wait)` gated on `config.interval`.
+- **Remove empty runner subclasses** — `DealerRunner`, `ChannelRunner`,
+  `ClientRunner`, and `PeerRunner` were empty class bodies that added no
+  behaviour. `RUNNER_MAP` now points directly at `PairRunner`, `ReqRunner`,
+  and `ServerRunner` for those socket types. `channel.rb` and `peer.rb`
+  deleted; empty bodies removed from `router_dealer.rb` and
+  `client_server.rb`.
+- **Extract `TransientMonitor`** — `start_disconnect_monitor`,
+  `transient_ready!`, and `@transient_barrier` removed from `BaseRunner`
+  into `OMQ::CLI::TransientMonitor`. `BaseRunner` holds a single
+  `@transient_monitor` collaborator; `transient_ready!` delegates to
+  `monitor.ready!`.
+- **Extract `RoutingHelper` module** — `display_routing_id`, `resolve_target`,
+  and a `send_targeted_or_eval` template method (calling a `send_to_peer` hook)
+  extracted from `RouterRunner` and `ServerRunner` into a shared module.
+  `display_routing_id` and `resolve_target` removed from `BaseRunner`, which
+  never used them directly.
+- **Extract `SocketSetup`** — socket construction (`SocketSetup.build`),
+  endpoint attachment (`SocketSetup.attach` for URL lists,
+  `SocketSetup.attach_endpoints` for `Endpoint` objects), subscription/group
+  setup (`SocketSetup.setup_subscriptions`), and CURVE configuration
+  (`SocketSetup.setup_curve`) extracted from `BaseRunner` into a stateless
+  module. `PipeRunner#attach_endpoints` now delegates to the shared module.
+- **Extract `ExpressionEvaluator`** — expression compilation (`extract_block`,
+  `extract_blocks`, BEGIN/END parsing, proc wrapping) and result normalisation
+  live in `OMQ::CLI::ExpressionEvaluator`. Removes duplicate code from
+  `BaseRunner`, `PipeRunner`, and both Ractor worker blocks. A shared
+  `ExpressionEvaluator.compile_inside_ractor` class method replaces the
+  identical inline parse lambdas that previously appeared in each Ractor block.
+
+### Added (OMQ::Ractor integration)
+
+- **`-P` extended to recv-only socket types** (`pull`, `sub`, `gather`,
+  `dish`) when combined with `--recv-eval`. Each worker gets its own
+  socket connecting to the external endpoint; ZMQ distributes work
+  naturally. Results are collected via an inproc PULL back to main for
+  output. Requires all endpoints to use `--connect`.
+- **`omq-ractor` dependency** — `OMQ::Ractor` is now used for all
+  parallel worker management.
+
+### Changed
+
+- **`pipe -P` rewritten using `OMQ::Ractor`** — workers no longer
+  create their own Async reactor internally. Sockets are created and
+  peer-waited in the main Async context, then passed to
+  `OMQ::Ractor.new`; worker blocks contain only pure computation.
+  Semantics are unchanged.
+
+### Fixed
+
+- **`-P` recv-only: stale round-robin entry** — the initial socket
+  created by `call()` was connecting to the upstream endpoint before
+  `run_parallel_recv` closed it, leaving a dead entry in the PUSH
+  peer's round-robin cycle and silently dropping 1 in every N+1
+  messages. Fixed by skipping `attach_endpoints` when `config.parallel`
+  is set.
+- **`-P` BEGIN/END blocks in Ractor workers** — `@ivar` expressions in
+  BEGIN/END/eval blocks raised `Ractor::IsolationError` because `self`
+  inside a Ractor is a shareable object. All three procs now execute via
+  `instance_exec` on a per-worker `Object.new` context.
+- **`-P` END block result forwarded** — the return value of an END block
+  was discarded rather than forwarded to the output socket. Now captured
+  and pushed to `push_p`, enabling patterns like
+  `BEGIN{@s=0} @s+=Integer($F.first);nil END{[@s.to_s]}` to emit once
+  per worker on exit.
+
+---
+
+### Added
+
+- **`-r` defers loading to inside the Async reactor** — scripts now run
+  within the event loop and may use async APIs, OMQ sockets, etc.
+- **Bare script mode (`omq -r FILE`)** — omitting the socket type runs the
+  script directly inside `Async{}` with free reign. The `OMQ` module is
+  included into the top-level namespace so scripts can write `PUSH.new`
+  instead of `OMQ::PUSH.new`.
+- **`-r -` / `-r-`** — reads and evals the script from stdin, useful for
+  quick copy-paste invocations. Cannot be combined with `-F -`.
+- **`--recv-maxsz COUNT`** — sets the ZMQ `max_message_size` socket option;
+  the socket discards incoming messages exceeding `COUNT` bytes and drops
+  the peer connection before allocation.
+
+### Fixed
+
+- `Protocol::ZMTP::Codec::Frame` was referenced as bare `ZMTP::Codec::Frame`
+  in the formatter (`--raw` format). Fixed the constant path.
+
 ## 0.2.0 — 2026-03-31
 
 ### Added

data/README.md

@@ -4,7 +4,8 @@
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
 
-Command-line tool for sending and receiving ZeroMQ messages on any socket type. Like `nngcat` from libnng, but with Ruby eval, Ractor parallelism, and message handlers.
+Command-line tool for sending and receiving ZeroMQ messages on any socket type.
+Like `nngcat` from libnng, but with Ruby eval, Ractor parallelism, and message handlers.
 
 Built on [omq](https://github.com/zeromq/omq) — pure Ruby ZeroMQ, no C dependencies.
 
@@ -46,7 +47,8 @@ omq pull -b ipc:///tmp/feed.sock     # IPC (unix socket)
 omq push -c ipc://@abstract          # IPC (abstract namespace, Linux)
 ```
 
-Multiple endpoints are allowed — `omq pull -b tcp://:5557 -b tcp://:5558` binds both. Pipe requires exactly two (`-c` for pull-side, `-c` for push-side).
+Multiple endpoints are allowed — `omq pull -b tcp://:5557 -b tcp://:5558` binds both.
+Pipe takes two positional endpoints (input, output) or uses `--in`/`--out` for multiple per side.
 
 ## Socket types
 
@@ -94,7 +96,8 @@ echo "hello" | omq req -c tcp://localhost:5555
 | `dealer` | Like `pair` but round-robin send to multiple peers |
 | `channel` | Like `pair` (draft, single-frame) |
 
-These spawn two concurrent tasks: a receiver (prints incoming) and a sender (reads stdin). `-e` transforms incoming, `-E` transforms outgoing.
+These spawn two concurrent tasks: a receiver (prints incoming) and a sender (reads stdin).
+`-e` transforms incoming, `-E` transforms outgoing.
 
 ### Routing sockets
 
@@ -128,7 +131,8 @@ omq pipe -c ipc://@work -c ipc://@sink -e '$F.map(&:upcase)'
 omq pipe -c ipc://@work -c ipc://@sink -P 4 -r./fib.rb -e 'fib(Integer($_)).to_s'
 ```
 
-The first endpoint is the pull-side (input), the second is the push-side (output). Both must use `-c`.
+The first endpoint is the pull-side (input), the second is the push-side (output).
+Both must use `-c`.
 
 ## Eval: -e and -E
 
@@ -298,7 +302,8 @@ OMQ.outgoing { |msg| [*msg, Time.now.iso8601] }
 | `--msgpack` | MessagePack arrays (binary stream) |
 | `-M` / `--marshal` | Ruby Marshal (binary stream of `Array<String>` objects) |
 
-Multipart messages: in ASCII/quoted mode, frames are tab-separated. In JSONL mode, each message is a JSON array.
+Multipart messages: in ASCII/quoted mode, frames are tab-separated. In JSONL mode,
+each message is a JSON array.
 
 ```sh
 # send multipart via tabs
@@ -432,7 +437,8 @@ omq pipe -c ipc://@work -c ipc://@sink --transient -e '$F.map(&:upcase)'
 
 ### Multi-peer pipe with `--in`/`--out`
 
-Use `--in` and `--out` to attach multiple endpoints per side. These are modal switches — subsequent `-b`/`-c` flags attach to the current side:
+Use `--in` and `--out` to attach multiple endpoints per side. These are modal switches — subsequent
+`-b`/`-c` flags attach to the current side:
 
 ```sh
 # fan-in: 2 producers → 1 consumer
@@ -448,9 +454,8 @@ omq pipe --in -b tcp://:5555 -b tcp://:5556 --out -c tcp://sink:5557 -e '$F'
 omq pipe --in -c ipc://@a -c ipc://@b --out -c ipc://@sink -P 4 -e '$F'
 ```
 
-`-P`/`--parallel` requires all endpoints to be `--connect`. In parallel mode, each Ractor worker gets its own PULL/PUSH pair connecting to all endpoints.
-
-Note: in Ractor workers, use `__F` instead of `$F` (global variables aren't shared across Ractors).
+`-P`/`--parallel` requires all endpoints to be `--connect`. In parallel mode, each Ractor worker
+gets its own PULL/PUSH pair connecting to all endpoints.
 
 ## Transient mode