omq-cli 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a03141c60a8af670aa4de42bc5b5d286fbf3a975c5a455e9276bc2d4b87a0fb8
-  data.tar.gz: 2755cb1054df95a64b5faebe481e93ac2e3f391e878f54b5a30a17514dde399a
+  metadata.gz: e9d13a0ffe0dbde54709fe0489385447cf61913d8a0b7d9abc2caa67e64fd7a5
+  data.tar.gz: 6987e6aa0569b9e2bc41d6265adf7ea6bc05458086764df0e3c6ca501f08849d
 SHA512:
-  metadata.gz: f245e7f524d745382074347852f1d34e5e1f46e633fe024b7888c05942a399639e69e876ae92c5ace5172800b0dc6a3bd8cd088d3b52f389ea0fb212e0f8da58
-  data.tar.gz: 34992fe5962fd2639b0c3e92597e3d2d6a134f3ac4fecadfa3d64b1d566994cf9f8ef36ce08fc929ab97bfcf7a7b4dd7f9c1de241b8c87e2a207ce17a838c7d2
+  metadata.gz: 71c929c48a622fe318a531b03a6a7ab3f15c418dcf5b7662f000be0865423c660beb5967536d9ff30d26cd601648638cfdaa63f535a2da0e3dcc076c5bb36ed3
+  data.tar.gz: a3e937b036c55ae4072ddccb38b9acf278e22f8e60ee957b9441611d2a256f34b02cde3c3c847b53811e7365e498fcdeeab5aa512bf2f22c05fa309ce6c997e0

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.8.0 — 2026-04-08
+
+### Added
+
+- **`-P` for pull, gather, and rep** — parallel Ractor workers for recv-only
+  and request-reply socket types. Output serialized through `Ractor::Port`
+  to avoid scrambled stdout.
+- **`RactorHelpers` module** — shared Ractor infrastructure: `preresolve_tcp`,
+  `start_log_consumer`, `start_output_consumer` with `SHUTDOWN` sentinel for
+  clean consumer shutdown.
+- **`ParallelWorker` class** — general Ractor worker for parallel socket modes.
+- **Process titles** — all runners set descriptive `proctitle`
+  (`omq TYPE [-z] [-PN] ENDPOINTS`). Pipe shows `omq pipe [-z] [-PN] IN -> OUT`.
+  Bare script mode shows `omq script`.
+
+### Changed
+
+- **ASCII-only source** — replaced all Unicode special characters (em-dashes,
+  box-drawing, arrows) with ASCII equivalents in lib/ and test/.
+- **Pipe default HWM** — pipe sockets now default to HWM of 64 (instead of
+  the socket default 1000) to bound memory with large messages in pipeline
+  stages. Override with `--send-hwm` / `--recv-hwm`.
+- **Message preview** — total byte count first, 12 chars per part, max 3 parts
+  shown (`(1234B) frame1|frame2|frame3|...(5 parts)`).
+- **`SocketSetup.apply_options`** — extracted shared socket option setup,
+  used by `BaseRunner`, `PipeRunner`, `PipeWorker`, and `ParallelWorker`.
+- **`Formatter.preview`** — extracted from duplicated `msg_preview` methods.
+- **Pipe/PipeWorker** — use bare `.new` for sockets, `SocketSetup.apply_options`
+  for configuration, `RactorHelpers` for Ractor infrastructure.
+
+## 0.7.2 — 2026-04-07
+
+### Changed
+
+- **Cleaned up pipe.rb** — removed unused `@fmt` formatters, dead `log` method,
+  and `with_timeout` wrapper. Moved `preresolve_tcp` and `start_log_consumer` to
+  `PipeWorker` class methods.
+- **Guard `with_timeout(nil)`** — `Fiber.scheduler.with_timeout(nil)` fires
+  immediately in Async; peer-wait and pipe sequential mode now skip the timeout
+  wrapper when `config.timeout` is nil.
+
 ## 0.7.1 — 2026-04-07
 
 ### Fixed

data/lib/omq/cli/base_runner.rb

@@ -24,6 +24,7 @@ module OMQ
       # @param task [Async::Task] the parent async task
       # @return [void]
       def call(task)
+        set_process_title
         setup_socket
         start_event_monitor if config.verbose >= 2
         maybe_start_transient_monitor(task)
@@ -46,7 +47,33 @@ module OMQ
       end
 
 
-      # ── Socket creation ─────────────────────────────────────────────
+      # -- Parallel Ractor workers -----------------------------------------
+
+
+      def run_parallel_workers(socket_sym)
+        OMQ.freeze_for_ractors!
+        eps = RactorHelpers.preresolve_tcp(config.endpoints)
+        output_port, output_thread = RactorHelpers.start_output_consumer
+        log_port, log_thread = RactorHelpers.start_log_consumer
+
+        workers = config.parallel.times.map do
+          ::Ractor.new(config, socket_sym, eps, output_port, log_port) do |cfg, sym, e, oport, lport|
+            ParallelWorker.new(cfg, sym, e, oport, lport).call
+          end
+        end
+
+        workers.each do |w|
+          w.join
+        rescue ::Ractor::RemoteError => e
+          $stderr.write("omq: Ractor error: #{e.cause&.message || e.message}\n")
+        end
+      ensure
+        RactorHelpers.stop_consumer(output_port, output_thread) if output_port
+        RactorHelpers.stop_consumer(log_port, log_thread) if log_port
+      end
+
+
+      # -- Socket creation ---------------------------------------------
 
 
       def setup_socket
@@ -68,7 +95,7 @@ module OMQ
       end
 
 
-      # ── Transient disconnect monitor ────────────────────────────────
+      # -- Transient disconnect monitor --------------------------------
 
 
       def maybe_start_transient_monitor(task)
@@ -83,7 +110,7 @@ module OMQ
       end
 
 
-      # ── BEGIN / END blocks ──────────────────────────────────────────
+      # -- BEGIN / END blocks ------------------------------------------
 
 
       def run_begin_blocks
@@ -98,7 +125,7 @@ module OMQ
       end
 
 
-      # ── Peer wait with grace period ─────────────────────────────────
+      # -- Peer wait with grace period ---------------------------------
 
 
       def needs_peer_wait?
@@ -107,12 +134,18 @@ module OMQ
 
 
       def wait_for_peer
-        with_timeout(config.timeout) do
+        wait_body = proc do
           @sock.peer_connected.wait
           log "Peer connected"
           wait_for_subscriber
           apply_grace_period
         end
+
+        if config.timeout
+          Fiber.scheduler.with_timeout(config.timeout, &wait_body)
+        else
+          wait_body.call
+        end
       end
 
 
@@ -133,19 +166,7 @@ module OMQ
       end
 
 
-      # ── Timeout helper ──────────────────────────────────────────────
-
-
-      def with_timeout(seconds)
-        if seconds
-          Async::Task.current.with_timeout(seconds) { yield }
-        else
-          yield
-        end
-      end
-
-
-      # ── Socket setup ────────────────────────────────────────────────
+      # -- Socket setup ------------------------------------------------
 
 
       def setup_subscriptions
@@ -163,7 +184,7 @@ module OMQ
       end
 
 
-      # ── Shared loop bodies ──────────────────────────────────────────
+      # -- Shared loop bodies ------------------------------------------
 
 
       def run_send_logic
@@ -279,7 +300,7 @@ module OMQ
       end
 
 
-      # ── Message I/O ─────────────────────────────────────────────────
+      # -- Message I/O -------------------------------------------------
 
 
       def send_msg(parts)
@@ -366,7 +387,7 @@ module OMQ
       end
 
 
-      # ── Eval ────────────────────────────────────────────────────────
+      # -- Eval --------------------------------------------------------
 
 
       def compile_expr
@@ -383,7 +404,7 @@ module OMQ
 
 
       def assign_send_aliases
-        # Keep ivar aliases — subclasses check these directly
+        # Keep ivar aliases -- subclasses check these directly
         @send_begin_proc = @send_evaluator.begin_proc
         @send_eval_proc  = @send_evaluator.eval_proc
         @send_end_proc   = @send_evaluator.end_proc
@@ -410,7 +431,22 @@ module OMQ
       SENT = ExpressionEvaluator::SENT
 
 
-      # ── Logging ─────────────────────────────────────────────────────
+      # -- Process title -------------------------------------------------
+
+
+      def set_process_title(endpoints: nil)
+        eps = endpoints || config.endpoints
+        title = ["omq", config.type_name]
+        title << "-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)
+        end
+        Process.setproctitle(title.join(" "))
+      end
+
+
+      # -- Logging -----------------------------------------------------
 
 
       def log(msg)
@@ -425,9 +461,9 @@ module OMQ
         @sock.monitor(verbose: verbose) do |event|
           case event.type
           when :message_sent
-            $stderr.write("omq: >> #{msg_preview(event.detail[:parts])}\n")
+            $stderr.write("omq: >> #{Formatter.preview(event.detail[:parts])}\n")
           when :message_received
-            $stderr.write("omq: << #{msg_preview(event.detail[:parts])}\n")
+            $stderr.write("omq: << #{Formatter.preview(event.detail[:parts])}\n")
           else
             ep = event.endpoint ? " #{event.endpoint}" : ""
             detail = event.detail ? " #{event.detail}" : ""
@@ -435,22 +471,6 @@ module OMQ
           end
         end
       end
-
-
-      def msg_preview(parts)
-        parts.map { |p| preview_bytes(p) }.join(" | ")
-      end
-
-
-      def preview_bytes(str)
-        bytes = str.b
-        preview = bytes[0, 10].gsub(/[^[:print:]]/, ".")
-        if bytes.bytesize > 10
-          "#{preview}... (#{bytes.bytesize}B)"
-        else
-          preview
-        end
-      end
     end
   end
 end

data/lib/omq/cli/cli_parser.rb

@@ -6,12 +6,12 @@ module OMQ
     #
     class CliParser
       EXAMPLES = <<~'TEXT'
-        ── Request / Reply ──────────────────────────────────────────
+        -- Request / Reply ------------------------------------------
 
-          ┌─────┐  "hello"    ┌─────┐
-          │ REQ │────────────→│ REP │
-          │     │←────────────│     │
-          └─────┘  "HELLO"    └─────┘
+          +-----+  "hello"    +-----+
+          | REQ |------------->| REP |
+          |     |<-------------|     |
+          +-----+  "HELLO"    +-----+
 
           # terminal 1: echo server
           omq rep --bind tcp://:5555 --recv-eval '$F.map(&:upcase)'
@@ -23,11 +23,11 @@ module OMQ
           omq rep --bind ipc:///tmp/echo.sock --echo &
           echo "hello" | omq req --connect ipc:///tmp/echo.sock
 
-        ── Publish / Subscribe ──────────────────────────────────────
+        -- Publish / Subscribe --------------------------------------
 
-          ┌─────┐  "weather.nyc 72F"  ┌─────┐
-          │ PUB │────────────────────→│ SUB │ --subscribe "weather."
-          └─────┘                     └─────┘
+          +-----+  "weather.nyc 72F"  +-----+
+          | PUB |--------------------->| SUB | --subscribe "weather."
+          +-----+                     +-----+
 
           # terminal 1: subscriber (all topics by default)
           omq sub --bind tcp://:5556
@@ -35,11 +35,11 @@ module OMQ
           # terminal 2: publisher (needs --delay for subscription to propagate)
           echo "weather.nyc 72F" | omq pub --connect tcp://localhost:5556 --delay 1
 
-        ── Periodic Publish ───────────────────────────────────────────
+        -- Periodic Publish -------------------------------------------
 
-          ┌─────┐  "tick 1"    ┌─────┐
-          │ PUB │──(every 1s)─→│ SUB │
-          └─────┘              └─────┘
+          +-----+  "tick 1"    +-----+
+          | PUB |--(every 1s)-->| SUB |
+          +-----+              +-----+
 
           # terminal 1: subscriber
           omq sub --bind tcp://:5556
@@ -52,11 +52,11 @@ module OMQ
           omq pub --connect tcp://localhost:5556 --delay 1 \
             --data "tick" --interval 1 --count 5
 
-        ── Pipeline ─────────────────────────────────────────────────
+        -- Pipeline -------------------------------------------------
 
-          ┌──────┐           ┌──────┐
-          │ PUSH │──────────→│ PULL │
-          └──────┘           └──────┘
+          +------+           +------+
+          | PUSH |----------->| PULL |
+          +------+           +------+
 
           # terminal 1: worker
           omq pull --bind tcp://:5557
@@ -68,16 +68,16 @@ module OMQ
           omq pull --bind ipc:///tmp/pipeline.sock &
           echo "task 1" | omq push --connect ipc:///tmp/pipeline.sock
 
-        ── Pipe (PULL → eval → PUSH) ────────────────────────────────
+        -- Pipe (PULL -> eval -> PUSH) --------------------------------
 
-          ┌──────┐         ┌──────┐         ┌──────┐
-          │ PUSH │────────→│ pipe │────────→│ PULL │
-          └──────┘         └──────┘         └──────┘
+          +------+         +------+         +------+
+          | PUSH |--------->| pipe |--------->| PULL |
+          +------+         +------+         +------+
 
           # terminal 1: producer
           echo -e "hello\nworld" | omq push --bind ipc://@work
 
-          # terminal 2: worker — uppercase each message
+          # terminal 2: worker -- uppercase each message
           omq pipe -c ipc://@work -c ipc://@sink -e '$F.map(&:upcase)'
           # terminal 3: collector
           omq pull --bind ipc://@sink
@@ -88,19 +88,19 @@ module OMQ
           # exit when producer disconnects (--transient)
           omq pipe -c ipc://@work -c ipc://@sink --transient -e '$F.map(&:upcase)'
 
-          # fan-in: multiple sources → one sink
+          # fan-in: multiple sources -> one sink
           omq pipe --in -c ipc://@work1 -c ipc://@work2 \
             --out -c ipc://@sink -e '$F.map(&:upcase)'
 
-          # fan-out: one source → multiple sinks (round-robin)
+          # fan-out: one source -> multiple sinks (round-robin)
           omq pipe --in -b tcp://:5555 --out -c ipc://@sink1 -c ipc://@sink2 -e '$F'
 
-        ── CLIENT / SERVER (draft) ──────────────────────────────────
+        -- CLIENT / SERVER (draft) ----------------------------------
 
-          ┌────────┐  "hello"   ┌────────┐
-          │ CLIENT │───────────→│ SERVER │ --recv-eval '$F.map(&:upcase)'
-          │        │←───────────│        │
-          └────────┘  "HELLO"   └────────┘
+          +--------+  "hello"   +--------+
+          | CLIENT |------------>| SERVER | --recv-eval '$F.map(&:upcase)'
+          |        |<------------|        |
+          +--------+  "HELLO"   +--------+
 
           # terminal 1: upcasing server
           omq server --bind tcp://:5555 --recv-eval '$F.map(&:upcase)'
@@ -108,28 +108,28 @@ module OMQ
           # terminal 2: client
           echo "hello" | omq client --connect tcp://localhost:5555
 
-        ── Formats ──────────────────────────────────────────────────
+        -- Formats --------------------------------------------------
 
-          # ascii (default) — non-printable replaced with dots
+          # ascii (default) -- non-printable replaced with dots
           omq pull --bind tcp://:5557 --ascii
 
-          # quoted — lossless, round-trippable (uses String#dump escaping)
+          # quoted -- lossless, round-trippable (uses String#dump escaping)
           omq pull --bind tcp://:5557 --quoted
 
-          # JSON Lines — structured, multipart as arrays
+          # JSON Lines -- structured, multipart as arrays
           echo '["key","value"]' | omq push --connect tcp://localhost:5557 --jsonl
           omq pull --bind tcp://:5557 --jsonl
 
           # multipart via tabs
           printf "routing-key\tpayload" | omq push --connect tcp://localhost:5557
 
-        ── Compression ──────────────────────────────────────────────
+        -- Compression ----------------------------------------------
 
           # both sides must use --compress
           omq pull --bind tcp://:5557 --compress &
           echo "compressible data" | omq push --connect tcp://localhost:5557 --compress
 
-        ── CURVE Encryption ─────────────────────────────────────────
+        -- CURVE Encryption -----------------------------------------
 
           # server (prints OMQ_SERVER_KEY=...)
           omq rep --bind tcp://:5555 --echo --curve-server
@@ -138,12 +138,12 @@ module OMQ
           echo "secret" | omq req --connect tcp://localhost:5555 \
             --curve-server-key '<key from server>'
 
-        ── ROUTER / DEALER ──────────────────────────────────────────
+        -- ROUTER / DEALER ------------------------------------------
 
-          ┌────────┐          ┌────────┐
-          │ DEALER │─────────→│ ROUTER │
-          │ id=w1  │          │        │
-          └────────┘          └────────┘
+          +--------+          +--------+
+          | DEALER |---------->| ROUTER |
+          | id=w1  |          |        |
+          +--------+          +--------+
 
           # terminal 1: router shows identity + message
           omq router --bind tcp://:5555
@@ -151,7 +151,7 @@ module OMQ
           # terminal 2: dealer with identity
           echo "hello" | omq dealer --connect tcp://localhost:5555 --identity worker-1
 
-        ── Ruby Eval ────────────────────────────────────────────────
+        -- Ruby Eval ------------------------------------------------
 
           # filter incoming: only pass messages containing "error"
           omq pull -b tcp://:5557 --recv-eval '$F.first.include?("error") ? $F : nil'
@@ -162,10 +162,10 @@ module OMQ
           # require a local file, use its methods
           omq rep --bind tcp://:5555 --require ./transform.rb -e 'upcase_all($F)'
 
-          # next skips, break stops — regexps match against $_
+          # next skips, break stops -- regexps match against $_
           omq pull -b tcp://:5557 -e 'next if /^#/; break if /quit/; $F'
 
-          # BEGIN/END blocks (like awk) — accumulate and summarize
+          # BEGIN/END blocks (like awk) -- accumulate and summarize
           omq pull -b tcp://:5557 -e 'BEGIN{@sum = 0} @sum += Integer($_); nil END{puts @sum}'
 
           # transform outgoing messages
@@ -174,9 +174,9 @@ module OMQ
           # REQ: transform request and reply independently
           echo hello | omq req -c tcp://localhost:5555 -E '$F.map(&:upcase)' -e '$_'
 
-        ── Script Handlers (-r) ────────────────────────────────────
+        -- Script Handlers (-r) ------------------------------------
 
-          # handler.rb — register transforms from a file
+          # handler.rb -- register transforms from a file
           #   db = PG.connect("dbname=app")
           #   OMQ.incoming { |first_part, _| db.exec(first_part).values.flatten }
           #   at_exit { db.close }
@@ -185,8 +185,8 @@ module OMQ
           # combine script handlers with inline eval
           omq req -c tcp://localhost:5555 -r./handler.rb -E '$F.map(&:upcase)'
 
-          # OMQ.outgoing { |msg| ... }   — registered outgoing transform
-          # OMQ.incoming { |msg| ... }   — registered incoming transform
+          # OMQ.outgoing { |msg| ... }   -- registered outgoing transform
+          # OMQ.incoming { |msg| ... }   -- registered incoming transform
           # CLI flags (-e/-E) override registered handlers
       TEXT
 
@@ -271,7 +271,7 @@ module OMQ
           o.banner = "Usage: omq TYPE [options]\n\n" \
                      "Types:    req, rep, pub, sub, push, pull, pair, dealer, router\n" \
                      "Draft:    client, server, radio, dish, scatter, gather, channel, peer\n" \
-                     "Virtual:  pipe (PULL → eval → PUSH)\n\n"
+                     "Virtual:  pipe (PULL -> eval -> PUSH)\n\n"
 
           o.separator "Connection:"
           o.on("-c", "--connect URL", "Connect to endpoint (repeatable)") { |v|
@@ -412,7 +412,7 @@ module OMQ
         type_name = argv.shift
         if type_name.nil?
           abort parser.to_s if opts[:scripts].empty?
-          # bare script mode — type_name stays nil
+          # bare script mode -- type_name stays nil
         elsif !SOCKET_TYPE_NAMES.include?(type_name.downcase)
           abort "Unknown socket type: #{type_name}. Known: #{SOCKET_TYPE_NAMES.join(', ')}"
         else
@@ -486,10 +486,15 @@ module OMQ
         abort "--send-eval and --target are mutually exclusive"  if opts[:send_expr] && opts[:target]
 
         if opts[:parallel]
-          abort "-P/--parallel is only valid for pipe" unless type_name == "pipe"
+          parallel_types = %w[pipe pull gather rep]
+          abort "-P/--parallel is only valid for #{parallel_types.join(", ")}" unless parallel_types.include?(type_name)
           abort "-P/--parallel must be 1..16" unless (1..16).include?(opts[:parallel])
-          all_pipe_eps = opts[:in_endpoints] + opts[:out_endpoints] + opts[:endpoints]
-          abort "-P/--parallel requires all endpoints to use --connect (not --bind)" if all_pipe_eps.any?(&:bind?)
+          if type_name == "pipe"
+            all_eps = opts[:in_endpoints] + opts[:out_endpoints] + opts[:endpoints]
+          else
+            all_eps = opts[:endpoints]
+          end
+          abort "-P/--parallel requires all endpoints to use --connect (not --bind)" if all_eps.any?(&:bind?)
         end
 
         (opts[:connects] + opts[:binds]).each do |url|

data/lib/omq/cli/formatter.rb

@@ -98,6 +98,22 @@ module OMQ
       rescue
         abort "omq: decompression failed (did the sender use --compress?)"
       end
+
+
+      # Formats message parts for human-readable preview (logging).
+      #
+      # @param parts [Array<String>] message frames
+      # @return [String] truncated preview of each frame joined by |
+      def self.preview(parts)
+        total = parts.sum(&:bytesize)
+        shown = parts.first(3).map do |p|
+          bytes = p.b
+          preview = bytes[0, 12].gsub(/[^[:print:]]/, ".")
+          bytes.bytesize > 12 ? "#{preview}..." : preview
+        end
+        tail = parts.size > 3 ? "|...(#{parts.size} parts)" : ""
+        "(#{total}B) #{shown.join("|")}#{tail}"
+      end
     end
   end
 end