nnq-cli 0.2.0

data/lib/nnq/cli/req_rep.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    # Runner for REQ sockets (synchronous request-reply client).
+    #
+    # nnq's REQ is cooked: #send_request takes the request body and
+    # blocks until the matching reply arrives, returning the reply body.
+    class ReqRunner < BaseRunner
+      private
+
+
+      def run_loop(task)
+        n = config.count
+        i = 0
+        sleep(config.delay) if config.delay
+        loop do
+          msg = read_next
+          break unless msg
+          msg = eval_send_expr(msg)
+          next unless msg
+          reply = request_and_receive(msg)
+          break if reply.nil?
+          output(eval_recv_expr(reply))
+          i += 1
+          break if n && n > 0 && i >= n
+          break if !config.interval && (config.data || config.file)
+          wait_for_interval if config.interval
+        end
+      end
+
+
+      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)
+        transient_ready!
+        return nil if reply_body.nil?
+        reply = @fmt.decompress([reply_body])
+        reply = [Marshal.load(reply.first)] if config.format == :marshal
+        reply
+      end
+
+
+      def wait_for_interval
+        wait = config.interval - (Time.now.to_f % config.interval)
+        sleep(wait) if wait > 0
+      end
+    end
+
+
+    # Runner for REP sockets (synchronous request-reply server).
+    #
+    # nnq's REP enforces strict alternation: #receive then #send_reply.
+    # There is no #send at all, so we bypass BaseRunner's send helpers.
+    class RepRunner < BaseRunner
+      private
+
+
+      def run_loop(task)
+        n = config.count
+        i = 0
+        loop do
+          msg = recv_msg
+          break if msg.nil?
+          break unless handle_rep_request(msg)
+          i += 1
+          break if n && n > 0 && i >= n
+        end
+      end
+
+
+      def handle_rep_request(msg)
+        if config.recv_expr || @recv_eval_proc
+          reply = eval_recv_expr(msg)
+          unless reply.equal?(SENT)
+            output(reply)
+            send_reply(reply || [""])
+          end
+        elsif config.echo
+          output(msg)
+          send_reply(msg)
+        elsif config.data || config.file || !config.stdin_is_tty
+          reply = read_next
+          return false unless reply
+          output(msg)
+          send_reply(reply)
+        else
+          abort "REP needs a reply source: --echo, --data, --file, -e, or stdin pipe"
+        end
+        true
+      end
+
+
+      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)
+        transient_ready!
+      end
+    end
+  end
+end

data/lib/nnq/cli/socket_setup.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    # Stateless helper for socket construction and configuration.
+    # All methods are module-level so callers compose rather than inherit.
+    module SocketSetup
+      # Default high water mark applied when the user does not pass
+      # --hwm. 64 matches the send pump's per-fairness-batch limit
+      # (one batch exactly fills a full queue).
+      DEFAULT_HWM = 64
+
+      # Default max inbound message size (1 MiB) so a misconfigured or
+      # malicious peer can't 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 post-construction socket options from +config+ to +sock+.
+      # send_hwm and linger are construction-time kwargs (see {.build});
+      # the rest of the options are set here and read later by the
+      # engine/transports.
+      def self.apply_options(sock, config)
+        sock.options.read_timeout       = config.timeout       if config.timeout
+        sock.options.write_timeout      = config.timeout       if config.timeout
+        sock.options.reconnect_interval = config.reconnect_ivl if config.reconnect_ivl
+        sock.options.max_message_size =
+          case config.recv_maxsz
+          when nil then DEFAULT_RECV_MAXSZ
+          when 0   then nil
+          else          config.recv_maxsz
+          end
+      end
+
+
+      # Create and fully configure a socket from +klass+ and +config+.
+      # nnq's Socket constructor takes linger + send_hwm directly
+      # (send_hwm is captured during routing init and can't be changed
+      # after the fact), so we pass them there.
+      def self.build(klass, config)
+        sock = klass.new(
+          linger:   config.linger,
+          send_hwm: config.send_hwm || DEFAULT_HWM,
+        )
+        apply_options(sock, config)
+        sock
+      end
+
+
+      # Bind/connect +sock+ using URL strings from +config.binds+ / +config.connects+.
+      # +verbose+ is the integer verbosity level (0 = silent).
+      def self.attach(sock, config, verbose: 0)
+        config.binds.each do |url|
+          sock.bind(url)
+          CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
+        end
+        config.connects.each do |url|
+          sock.connect(url)
+          CLI::Term.write_attach(:connect, url, verbose) if verbose >= 1
+        end
+      end
+
+
+      # Bind/connect +sock+ from an Array of Endpoint objects.
+      # Used by PipeRunner, which works with structured endpoint lists.
+      # +verbose+ is the integer verbosity level (0 = silent).
+      def self.attach_endpoints(sock, endpoints, verbose: 0)
+        endpoints.each do |ep|
+          if ep.bind?
+            sock.bind(ep.url)
+            CLI::Term.write_attach(:bind, sock.last_endpoint, verbose) if verbose >= 1
+          else
+            sock.connect(ep.url)
+            CLI::Term.write_attach(:connect, ep.url, verbose) if verbose >= 1
+          end
+        end
+      end
+
+
+      # Subscribe to prefixes on a SUB socket.
+      #
+      # Unlike ZeroMQ, nng's sub0 starts with an empty subscription set,
+      # meaning *no* messages match. If the user passed no `--subscribe`
+      # flags, default to subscribing to the empty prefix so the CLI
+      # feels like `nngcat` / `omq sub`: receive everything by default.
+      def self.setup_subscriptions(sock, config)
+        return unless config.type_name == "sub"
+        prefixes = config.subscribes.empty? ? [""] : config.subscribes
+        prefixes.each { |p| sock.subscribe(p) }
+      end
+    end
+  end
+end

data/lib/nnq/cli/surveyor_respondent.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    # Runner for SURVEYOR sockets (broadcast survey, collect replies).
+    #
+    # Sends each input line as a survey, then collects replies until
+    # the survey window expires.
+    class SurveyorRunner < BaseRunner
+      private
+
+
+      def run_loop(task)
+        n = config.count
+        i = 0
+        sleep(config.delay) if config.delay
+        loop do
+          msg = read_next
+          break unless msg
+          msg = eval_send_expr(msg)
+          next unless msg
+          survey_and_collect(msg)
+          i += 1
+          break if n && n > 0 && i >= n
+          break if !config.interval && (config.data || config.file)
+          wait_for_interval if config.interval
+        end
+      end
+
+
+      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)
+        transient_ready!
+        collect_replies
+      end
+
+
+      def collect_replies
+        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))
+        rescue NNQ::TimedOut
+          break
+        end
+      end
+
+
+      def wait_for_interval
+        wait = config.interval - (Time.now.to_f % config.interval)
+        sleep(wait) if wait > 0
+      end
+    end
+
+
+    # Runner for RESPONDENT sockets (receive surveys, send replies).
+    #
+    # Mirrors REP: strict alternation of #receive then #send_reply.
+    class RespondentRunner < BaseRunner
+      private
+
+
+      def run_loop(task)
+        n = config.count
+        i = 0
+        loop do
+          msg = recv_msg
+          break if msg.nil?
+          break unless handle_survey(msg)
+          i += 1
+          break if n && n > 0 && i >= n
+        end
+      end
+
+
+      def handle_survey(msg)
+        if config.recv_expr || @recv_eval_proc
+          reply = eval_recv_expr(msg)
+          unless reply.equal?(SENT)
+            output(reply)
+            send_reply(reply || [""])
+          end
+        elsif config.echo
+          output(msg)
+          send_reply(msg)
+        elsif config.data || config.file || !config.stdin_is_tty
+          reply = read_next
+          return false unless reply
+          output(msg)
+          send_reply(reply)
+        else
+          abort "RESPONDENT needs a reply source: --echo, --data, --file, -e, or stdin pipe"
+        end
+        true
+      end
+
+
+      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)
+        transient_ready!
+      end
+    end
+  end
+end

data/lib/nnq/cli/term.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    # Stateless terminal formatting and stderr writing helpers shared
+    # by every code path that emits verbose-driven log lines (event
+    # monitor callbacks in BaseRunner / PipeRunner, SocketSetup attach
+    # helpers, parallel/pipe Ractor workers).
+    #
+    # Pure module functions: no state, no instance, safe to call from
+    # any thread or Ractor.
+    #
+    module Term
+      module_function
+
+
+      # Returns a stderr log line prefix. At verbose >= 4, prepends an
+      # ISO8601 UTC timestamp with µs precision so log traces become
+      # time-correlatable. Otherwise returns the empty string.
+      #
+      # @param verbose [Integer]
+      # @return [String]
+      def log_prefix(verbose)
+        return "" unless verbose && verbose >= 4
+        "#{Time.now.utc.strftime("%FT%T.%6N")}Z "
+      end
+
+
+      # Formats one NNQ::MonitorEvent into a single log line (no
+      # trailing newline).
+      #
+      # @param event [NNQ::MonitorEvent]
+      # @param verbose [Integer]
+      # @return [String]
+      def format_event(event, verbose)
+        prefix = log_prefix(verbose)
+        case event.type
+        when :message_sent
+          "#{prefix}nnq: >> #{Formatter.preview([event.detail[:body]])}"
+        when :message_received
+          "#{prefix}nnq: << #{Formatter.preview([event.detail[:body]])}"
+        else
+          ep     = event.endpoint ? " #{event.endpoint}" : ""
+          detail = event.detail ? " #{event.detail}" : ""
+          "#{prefix}nnq: #{event.type}#{ep}#{detail}"
+        end
+      end
+
+
+      # Formats an "attached endpoint" log line (Bound to / Connecting to).
+      #
+      # @param kind [:bind, :connect]
+      # @param url [String]
+      # @param verbose [Integer]
+      # @return [String]
+      def format_attach(kind, url, verbose)
+        verb = kind == :bind ? "Bound to" : "Connecting to"
+        "#{log_prefix(verbose)}nnq: #{verb} #{url}"
+      end
+
+
+      # Writes one formatted event line to +io+ (default $stderr).
+      #
+      # @param event [NNQ::MonitorEvent]
+      # @param verbose [Integer]
+      # @param io [#write] writable sink, default $stderr
+      # @return [void]
+      def write_event(event, verbose, io: $stderr)
+        io.write("#{format_event(event, verbose)}\n")
+      end
+
+
+      # Writes one "Bound to / Connecting to" line to +io+
+      # (default $stderr).
+      #
+      # @param kind [:bind, :connect]
+      # @param url [String]
+      # @param verbose [Integer]
+      # @param io [#write]
+      # @return [void]
+      def write_attach(kind, url, verbose, io: $stderr)
+        io.write("#{format_attach(kind, url, verbose)}\n")
+      end
+    end
+  end
+end

data/lib/nnq/cli/transient_monitor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    # Monitors peer-disconnect events for --transient mode.
+    #
+    # Starts an async task that waits until #ready! is called (signalling
+    # that at least one message has been exchanged), then waits for all
+    # peers to disconnect, disables reconnection, and either stops the
+    # task (send-only) or closes the read side of the socket (recv side).
+    #
+    class TransientMonitor
+      # @param sock [Object] the NNQ socket to monitor
+      # @param config [Config] frozen CLI configuration
+      # @param task [Async::Task] parent async task
+      # @param log_fn [Method] callable for verbose logging
+      def initialize(sock, config, task, log_fn)
+        @barrier = Async::Promise.new
+        task.async do
+          @barrier.wait
+          sock.all_peers_gone.wait unless sock.connection_count == 0
+          log_fn.call("All peers disconnected, exiting")
+          sock.reconnect_enabled = false
+          if config.send_only?
+            task.stop
+          else
+            sock.close_read
+          end
+        end
+      end
+
+
+      # Signal that the first message has been sent or received.
+      # Idempotent -- safe to call multiple times.
+      #
+      def ready!
+        @barrier.resolve(true) unless @barrier.resolved?
+      end
+    end
+  end
+end

data/lib/nnq/cli/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module NNQ
+  module CLI
+    VERSION = "0.2.0"
+  end
+end

data/lib/nnq/cli.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "cli/version"
+require_relative "cli/config"
+require_relative "cli/cli_parser"
+require_relative "cli/formatter"
+require_relative "cli/expression_evaluator"
+require_relative "cli/socket_setup"
+require_relative "cli/term"
+require_relative "cli/transient_monitor"
+require_relative "cli/base_runner"
+require_relative "cli/push_pull"
+require_relative "cli/pub_sub"
+require_relative "cli/req_rep"
+require_relative "cli/pair"
+require_relative "cli/bus"
+require_relative "cli/surveyor_respondent"
+require_relative "cli/ractor_helpers"
+require_relative "cli/pipe_worker"
+require_relative "cli/pipe"
+
+module NNQ
+
+  class << self
+    # @return [Proc, nil] registered outgoing message transform
+    attr_reader :outgoing_proc
+    # @return [Proc, nil] registered incoming message transform
+    attr_reader :incoming_proc
+
+    # Registers an outgoing message transform (used by -r scripts).
+    #
+    # @yield [Array<String>] 1-element message array before sending
+    # @return [Proc]
+    def outgoing(&block) = @outgoing_proc = block
+
+    # Registers an incoming message transform (used by -r scripts).
+    #
+    # @yield [Array<String>] 1-element message array after receiving
+    # @return [Proc]
+    def incoming(&block) = @incoming_proc = block
+  end
+
+
+  # Command-line interface for NNQ socket operations.
+  module CLI
+    SOCKET_TYPE_NAMES = %w[req rep pub sub push pull pair bus surveyor respondent pipe].freeze
+
+
+    RUNNER_MAP = {
+      "push"       => [PushRunner,       :PUSH0],
+      "pull"       => [PullRunner,       :PULL0],
+      "pub"        => [PubRunner,        :PUB0],
+      "sub"        => [SubRunner,        :SUB0],
+      "req"        => [ReqRunner,        :REQ0],
+      "rep"        => [RepRunner,        :REP0],
+      "pair"       => [PairRunner,       :PAIR0],
+      "bus"        => [BusRunner,        :BUS0],
+      "surveyor"   => [SurveyorRunner,   :SURVEYOR0],
+      "respondent" => [RespondentRunner, :RESPONDENT0],
+      "pipe"       => [PipeRunner,       nil],
+    }.freeze
+
+
+    module_function
+
+
+    # Displays text through the system pager, or prints directly
+    # when stdout is not a terminal.
+    #
+    def page(text)
+      if $stdout.tty?
+        if ENV["PAGER"]
+          pager = ENV["PAGER"]
+        else
+          ENV["LESS"] ||= "-FR"
+          pager = "less"
+        end
+        IO.popen(pager, "w") { |io| io.puts text }
+      else
+        puts text
+      end
+    rescue Errno::ENOENT
+      puts text
+    rescue Errno::EPIPE
+      # user quit pager early
+    end
+
+
+    # Main entry point.
+    #
+    # @param argv [Array<String>] command-line arguments
+    # @return [void]
+    def run(argv = ARGV)
+      run_socket(argv)
+    end
+
+
+    # Parses CLI arguments, validates options, and runs the main
+    # event loop inside an Async reactor.
+    #
+    def run_socket(argv)
+      config = build_config(argv)
+
+      require "nnq"
+      require "async"
+      require "json"
+      require "console"
+
+      CliParser.validate_gems!(config)
+      trap("INT")  { Process.exit!(0) }
+      trap("TERM") { Process.exit!(0) }
+
+      Console.logger = Console::Logger.new(Console::Output::Null.new) unless config.verbose >= 1
+
+      debug_ep = nil
+
+      if ENV["NNQ_DEBUG_URI"]
+        begin
+          require "async/debug"
+          debug_ep = Async::HTTP::Endpoint.parse(ENV["NNQ_DEBUG_URI"])
+          if debug_ep.scheme == "https"
+            require "localhost"
+            debug_ep = Async::HTTP::Endpoint.parse(ENV["NNQ_DEBUG_URI"],
+              ssl_context: Localhost::Authority.fetch.server_context)
+          end
+        rescue LoadError
+          abort "NNQ_DEBUG_URI requires the async-debug gem: gem install async-debug"
+        end
+      end
+
+      if config.type_name.nil?
+        Process.setproctitle("nnq script")
+        Object.include(NNQ) unless Object.include?(NNQ)
+        Async annotation: 'nnq' do
+          Async::Debug.serve(endpoint: debug_ep) if debug_ep
+          config.scripts.each { |s| load_script(s) }
+        rescue => e
+          $stderr.puts "nnq: #{e.message}"
+          exit 1
+        end
+        return
+      end
+
+      runner_class, socket_sym = RUNNER_MAP.fetch(config.type_name)
+
+      Async annotation: "nnq #{config.type_name}" do |task|
+        Async::Debug.serve(endpoint: debug_ep) if debug_ep
+        config.scripts.each { |s| load_script(s) }
+        runner = if socket_sym
+                   runner_class.new(config, NNQ.const_get(socket_sym))
+                 else
+                   runner_class.new(config)
+                 end
+        runner.call(task)
+      rescue DecompressError => e
+        $stderr.puts "nnq: #{e.message}"
+        exit 1
+      rescue IO::TimeoutError, Async::TimeoutError
+        $stderr.puts "nnq: timeout" unless config.quiet
+        exit 2
+      rescue ::Socket::ResolutionError => e
+        $stderr.puts "nnq: #{e.message}"
+        exit 1
+      end
+    end
+
+
+    def load_script(s)
+      if s == :stdin
+        eval($stdin.read, TOPLEVEL_BINDING, "(stdin)", 1) # rubocop:disable Security/Eval
+      else
+        require s
+      end
+    end
+    private_class_method :load_script
+
+
+    # Builds a frozen Config from command-line arguments.
+    #
+    def build_config(argv)
+      opts = CliParser.parse(argv)
+      CliParser.validate!(opts)
+
+      opts[:stdin_is_tty] = $stdin.tty?
+
+      Ractor.make_shareable(Config.new(**opts))
+    end
+  end
+end