leopard 0.2.8 → 0.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e28fb312a603ba19a413cdc3c9b62e702ec70daa6870bd833b182dd82a96b147
-  data.tar.gz: 5dcb6ade2032068fd4daaf15b7953ae8ad3e81d352d72a6945e3452fb16b762a
+  metadata.gz: 61ef512c45c7a77049bcb82926d8f77f30986d3e63cad9f500f6bfc729968448
+  data.tar.gz: b27aeba2b9a28e286420dfe5a32be1cfc22792cd7d68c317178b7b463adbf9d9
 SHA512:
-  metadata.gz: a85035745ea9c0470764ea48c9127a60ae8459ba88d01158c33f22fab74aba81d5781d1c44bbbc09a2bcb53f0ae8787b2434c2ecf16063a0300ecfb3ce63bf7b
-  data.tar.gz: bcb763a8fc34511e78e9764b648ac75e24cf6370075550a958eeb69fb2cd0a738232c488fc5f06cf7ffe97b004a5d499f70e4a972c8e3aef5c09475d58135535
+  metadata.gz: b49256564d284e559c04e52bc689eeb5113d9ddc7d3fa4279c5d6bcca19501bc297595ab2f7481eb12a47b3cf7dffbe5a98fa7e7fc57f32357023ebc1296bc8c
+  data.tar.gz: dd3a974237972a781b51aa24ba3295e4be1ac49a56d2a9e5f3dc678db716cb7ec3f7813ce5a41e3eb224129ea7b795c7c01efa863ca991a050e69c026dd920c4

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.8"
+  ".": "0.2.10"
 }

data/.version.txt

@@ -1 +1 @@
-0.2.8
+0.2.10

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.10](https://github.com/rubyists/leopard/compare/v0.2.9...v0.2.10) (2026-09-16)
+
+
+### Features
+
+* add NATS service discovery tools ([#58](https://github.com/rubyists/leopard/issues/58)) ([#59](https://github.com/rubyists/leopard/issues/59)) ([382d5e7](https://github.com/rubyists/leopard/commit/382d5e7e19367796145bec07e4bda686268905ae))
+
+## [0.2.9](https://github.com/rubyists/leopard/compare/v0.2.8...v0.2.9) (2026-07-23)
+
+
+### Bug Fixes
+
+* **deps:** remove upper bound from semantic_logger dependency ([#54](https://github.com/rubyists/leopard/issues/54)) ([0b9f154](https://github.com/rubyists/leopard/commit/0b9f154f1b2ec1961dbb176954551b6f9caf16f0))
+
 ## [0.2.8](https://github.com/rubyists/leopard/compare/v0.2.7...v0.2.8) (2026-05-19)
 
 

data/Readme.adoc

@@ -4,6 +4,7 @@ bougyman <me@bougyman.com>
 :conventional-commits: https://www.conventionalcommits.org/en/v1.0.0/[Conventional Commits]
 :dry-configurable: https://github.com/dry-rb/dry-configurable[Dry::Configurable]
 :dry-monads: https://github.com/dry-rb/dry-monads[Dry::Monads]
+:jetstream-consumer-config: https://docs.nats.io/nats-concepts/jetstream/consumers#configuration[Jetstream Consumer Configuration]
 
 Leopard is a small framework for building concurrent {service-api} workers.
 It uses `Concurrent::FixedThreadPool` to manage multiple workers in a single process and provides a
@@ -91,6 +92,24 @@ end
 EchoService.use LoggerMiddleware
 ----
 
+== Request/Reply Failure Logging
+
+Request/reply endpoints log failed handler results at error level by default.
+To change only that decision while keeping Leopard's existing callbacks and
+error responses, configure a policy that accepts the failure payload:
+
+[source,ruby]
+----
+EchoService.config.request_reply_failure_log_policy = lambda do |failure|
+  next if failure.status.between?(400, 499)
+
+  EchoService.logger.error 'Error processing message: ', failure
+end
+----
+
+The policy is called before Leopard responds with the failure payload. It must
+not change the response: every failure still uses `respond_with_error`.
+
 == JetStream Pull Consumers
 
 Leopard can also bind JetStream pull consumers through the same middleware and `Dry::Monads::Result`
@@ -116,6 +135,13 @@ class EventConsumer
 end
 ----
 
+Any configuration options available for JetStream consumers can be passed via snakeified keys
+in the `consumer` hash, with the exception of `durable_name`, `filter_subject` and `ack_policy`.
+`durable_name` and `filter_subject` are both derived from the endpoint, and `ack_policy` is always
+set to `explicit`.
+
+{jetstream-consumer-config}
+
 JetStream handlers receive the same `Rubyists::Leopard::MessageWrapper` as service endpoints.
 Leopard will:
 

data/documents/enable-injectable-request-reply-callbacks.adoc

@@ -0,0 +1,52 @@
+= Enable Injectable Request/Reply Failure Logging
+
+== Goal
+
+Allow a service to change failure logging without replacing Leopard's
+request/reply callbacks. Applications can treat expected client failures, such
+as failures with particular statuses, differently from operational failures
+while preserving the existing response behavior.
+
+== Current behavior
+
+Every `Dry::Monads::Failure` is currently logged at error level before its
+payload is returned through `MessageWrapper#respond_with_error`. An application
+cannot change that logging policy without overriding Leopard internals.
+
+== Plan
+
+. Add a `:request_reply_failure_log_policy` service setting. When present, the
+  policy receives each failure payload before Leopard returns it to the client.
+. Keep `NatsRequestReplyCallbacks` as the callback owner. Its default policy
+  logs at error level, preserving current behavior when no policy is configured.
+. Pass the configured policy to `NatsRequestReplyCallbacks` when the worker
+  constructs its memoized callback helper.
+. Document that policies must leave `respond_with_error` behavior unchanged.
+
+== Suggested application policy
+
+Configure a policy directly. Leopard owns the callback mapping and invokes the
+policy only for failed handler results.
+
+[source,ruby]
+----
+MyService.config.request_reply_failure_log_policy = lambda do |failure|
+  next if failure.status.between?(400, 499)
+
+  MyService.logger.error 'Error processing message: ', failure
+end
+----
+
+Use the status accessor provided by the application's failure type (or another
+application-specific classifier). The policy must not change the response:
+Leopard still calls `wrapper.respond_with_error(failure)` for every failure.
+
+== Acceptance criteria
+
+* Existing request/reply services log and respond exactly as before without
+  configuration.
+* A service can configure failure logging without monkey-patching, inheriting
+  from, or replacing Leopard's callbacks.
+* A configured policy can select a log level, or no log entry, for any failure
+  status while returning the same error payload to the requester.
+* Successes and exceptions continue to follow their existing callback paths.

data/examples/groups.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/leopard/nats_api_server'
+
+# Example to echo the given message
+class ServiceGroups
+  include Rubyists::Leopard::NatsApiServer
+
+  def initialize(a_var: 1)
+    logger.info "ServiceGroups initialized with a_var: #{a_var}"
+  end
+
+  group :mammal
+  group :feline, group: :mammal, queue: :meow
+  endpoint(:sound, group: :feline) { |msg| Success("Meow! #{msg.data}") }
+  endpoint(:fail, group: :feline) { |msg| Failure({ reason: 'cat nap', data: msg.data }) }
+end
+
+if __FILE__ == $PROGRAM_NAME
+  SemanticLogger.default_level = :info
+  SemanticLogger.add_appender(io: $stdout, formatter: :color)
+  ServiceGroups.run(
+    nats_url: 'nats://localhost:4222',
+    service_opts: {
+      name: 'example.groups',
+      version: '1.0.0',
+      instance_args: { a_var: 2 },
+    },
+    instances: 1,
+  )
+end

data/exe/leopard-service-info

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'leopard/nats_service_discovery/cli'
+
+cli = Rubyists::Leopard::NatsServiceDiscovery::CLI
+opts = cli.parse(
+  ARGV,
+  banner: 'Usage: leopard-service-info [options]',
+  description: 'Prints raw $SRV.INFO responses as JSON.',
+)
+
+cli.with_client(opts) do |client|
+  result = cli.operation_result!(
+    Rubyists::Leopard::NatsServiceDiscovery::Operation::Info.call(**cli.discovery_options(opts, client)),
+  )
+  cli.print_json(result[:responses])
+end

data/exe/leopard-service-map

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'leopard/nats_service_discovery/cli'
+
+cli = Rubyists::Leopard::NatsServiceDiscovery::CLI
+opts = cli.parse(
+  ARGV,
+  banner: 'Usage: leopard-service-map [options]',
+  description: 'Builds a subject-to-endpoint map from $SRV.INFO responses.',
+  json: true,
+)
+
+cli.with_client(opts) do |client|
+  result = cli.operation_result!(
+    Rubyists::Leopard::NatsServiceDiscovery::Operation::SubjectMap.call(**cli.discovery_options(opts, client)),
+  )
+
+  if opts[:json]
+    cli.print_json(result[:subject_map])
+  else
+    rows = result[:subject_map].flat_map do |subject, listeners|
+      listeners.map { |listener| [subject, *listener.values_at('service', 'service_id', 'version', 'endpoint', 'queue_group')] }
+    end
+    cli.print_table(%w[SUBJECT SERVICE SERVICE_ID VERSION ENDPOINT QUEUE], rows)
+  end
+end

data/exe/leopard-service-stats

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'leopard/nats_service_discovery/cli'
+
+cli = Rubyists::Leopard::NatsServiceDiscovery::CLI
+opts = cli.parse(
+  ARGV,
+  banner: 'Usage: leopard-service-stats [options]',
+  description: 'Prints service endpoint stats from $SRV.STATS responses.',
+  json: true,
+)
+
+cli.with_client(opts) do |client|
+  result = cli.operation_result!(
+    Rubyists::Leopard::NatsServiceDiscovery::Operation::Stats.call(**cli.discovery_options(opts, client)),
+  )
+
+  if opts[:json]
+    cli.print_json(result[:responses])
+  else
+    rows = result[:responses].flat_map do |service|
+      Array(service['endpoints']).map do |endpoint|
+        [
+          service['name'], service['id'], endpoint['subject'], endpoint['name'], endpoint['queue_group'],
+          endpoint['num_requests'], endpoint['num_errors'], endpoint['average_processing_time'], endpoint['last_error']
+        ]
+      end
+    end
+    cli.print_table(%w[SERVICE SERVICE_ID SUBJECT ENDPOINT QUEUE REQUESTS ERRORS AVG_NS LAST_ERROR], rows)
+  end
+end

data/exe/leopard-services

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'leopard/nats_service_discovery/cli'
+
+cli = Rubyists::Leopard::NatsServiceDiscovery::CLI
+opts = cli.parse(
+  ARGV,
+  banner: 'Usage: leopard-services [options]',
+  description: 'Lists NATS Service API services and their endpoint counts.',
+  json: true,
+)
+
+cli.with_client(opts) do |client|
+  result = cli.operation_result!(
+    Rubyists::Leopard::NatsServiceDiscovery::Operation::Services.call(**cli.discovery_options(opts, client)),
+  )
+
+  if opts[:json]
+    cli.print_json(result[:services])
+  else
+    rows = result[:services].map { |service| service.values_at('name', 'id', 'version', 'endpoints') }
+    cli.print_table(%w[SERVICE ID VERSION ENDPOINTS], rows)
+  end
+end

data/lib/leopard/nats_api_server.rb

@@ -31,6 +31,7 @@ module Rubyists
         base.extend(Dry::Monads[:result])
         base.extend(Dry::Configurable)
         base.setting :logger, default: Rubyists::Leopard.logger, reader: true
+        base.setting :request_reply_failure_log_policy, default: nil, reader: true
       end
 
       # Configuration for a request/reply endpoint declared with {.endpoint}.
@@ -472,7 +473,10 @@ module Rubyists
         #
         # @return [NatsRequestReplyCallbacks] The request/reply callback helper.
         def request_reply_callbacks
-          @request_reply_callbacks ||= NatsRequestReplyCallbacks.new(logger:)
+          @request_reply_callbacks ||= NatsRequestReplyCallbacks.new(
+            logger:,
+            failure_log_policy: self.class.request_reply_failure_log_policy,
+          )
         end
 
         # Returns the memoized message processor for this worker instance.

data/lib/leopard/nats_request_reply_callbacks.rb

@@ -6,11 +6,15 @@ module Rubyists
     class NatsRequestReplyCallbacks
       # Builds a callback set for request/reply endpoint outcomes.
       #
-      # @param logger [#error] Logger used for failure payloads.
+      # @param logger [#error] Logger used by the default failure log policy.
+      # @param failure_log_policy [#call, nil] Optional policy called with a
+      #   failure payload before it is returned to the requester.
       #
       # @return [void]
-      def initialize(logger:)
-        @logger = logger
+      def initialize(logger:, failure_log_policy: nil)
+        @failure_log_policy = failure_log_policy || lambda do |failure|
+          logger.error 'Error processing message: ', failure
+        end
       end
 
       # Returns transport callbacks for request/reply endpoints.
@@ -43,7 +47,7 @@ module Rubyists
       #
       # @return [void]
       def respond_with_failure(wrapper, result)
-        log_failure(result.failure)
+        @failure_log_policy.call(result.failure)
         wrapper.respond_with_error(result.failure)
       end
 
@@ -56,15 +60,6 @@ module Rubyists
       def respond_with_error(wrapper, error)
         wrapper.respond_with_error(error)
       end
-
-      # Logs the failure payload returned by a handler.
-      #
-      # @param failure [Object] The failure payload from the handler.
-      #
-      # @return [void]
-      def log_failure(failure)
-        @logger.error 'Error processing message: ', failure
-      end
     end
   end
 end

data/lib/leopard/nats_service_discovery/cli.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+require_relative 'operation'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      # Shared command-line helpers for NATS service discovery executables.
+      #
+      # @api private
+      module CLI
+        module_function
+
+        # Parses common NATS discovery CLI options.
+        #
+        # @param argv [Array<String>] Command-line arguments.
+        # @param banner [String] OptionParser banner.
+        # @param description [String] Command description.
+        # @param json [Boolean] Whether the command supports `--json`.
+        #
+        # @return [Hash] Parsed options.
+        def parse(argv, banner:, description:, json: false)
+          opts = default_options(json:)
+          OptionParser.new do |parser|
+            parser.banner = banner
+            parser.separator ''
+            parser.separator description
+            parser.separator ''
+            add_common_options(parser, opts)
+          end.parse!(argv)
+          validate!(opts)
+          opts
+        end
+
+        # Opens a NATS client for the duration of the provided block.
+        #
+        # @param opts [Hash] Parsed CLI options.
+        # @yieldparam client [NATS::Client] Connected NATS client.
+        #
+        # @return [Object] The block return value.
+        def with_client(opts)
+          result = Operation::Connect.call(
+            server: opts[:server],
+            creds: opts[:creds],
+            connect_options: { reconnect: false, connect_timeout: opts[:timeout] },
+          )
+          abort_with(result[:error]) unless result.success?
+
+          yield result[:client]
+        ensure
+          result&.[](:client)&.close
+        end
+
+        # Prints a value as pretty JSON.
+        #
+        # @param value [Object] JSON-serializable value.
+        #
+        # @return [void]
+        def print_json(value)
+          puts JSON.pretty_generate(value)
+        end
+
+        # Prints rows as a simple aligned table.
+        #
+        # @param headers [Array<String>] Column headers.
+        # @param rows [Array<Array>] Table rows.
+        #
+        # @return [void]
+        def print_table(headers, rows)
+          widths = column_widths(headers, rows)
+          format = widths.map { |width| "%-#{width}s" }.join('  ')
+          puts format % headers
+          puts widths.map { |width| '-' * width }.join('  ')
+          rows.each { |row| puts format % row }
+        end
+
+        # Prints an error and exits with a non-zero status.
+        #
+        # @param error [Exception] Error to report.
+        #
+        # @return [void]
+        def abort_with(error)
+          warn "error: #{error.message}"
+          exit 1
+        end
+
+        # Returns a successful operation result or aborts the process.
+        #
+        # @param result [Trailblazer::Operation::Railway::Result] Operation result.
+        #
+        # @return [Trailblazer::Operation::Railway::Result]
+        def operation_result!(result)
+          abort_with(result[:error]) unless result.success?
+
+          result
+        end
+
+        # Builds discovery operation options from CLI options and a client.
+        #
+        # @param opts [Hash] Parsed CLI options.
+        # @param client [NATS::Client] Connected NATS client.
+        #
+        # @return [Hash] Arguments for discovery operations.
+        def discovery_options(opts, client)
+          {
+            client:,
+            name: opts[:name],
+            id: opts[:id],
+            prefix: opts[:prefix],
+            timeout: opts[:timeout],
+          }
+        end
+
+        # Builds default CLI options.
+        #
+        # @param json [Boolean] Whether the command supports `--json`.
+        #
+        # @return [Hash] Default options.
+        def default_options(json:)
+          {
+            server: ENV.fetch('NATS_URL', 'nats://127.0.0.1:4222'),
+            timeout: DEFAULT_TIMEOUT,
+            prefix: DEFAULT_PREFIX,
+            json: json ? false : nil,
+          }
+        end
+
+        # Adds all common options to an OptionParser.
+        #
+        # @param parser [OptionParser] Parser to configure.
+        # @param opts [Hash] Mutable parsed option accumulator.
+        #
+        # @return [void]
+        def add_common_options(parser, opts)
+          add_connection_options(parser, opts)
+          add_filter_options(parser, opts)
+          add_output_options(parser, opts)
+        end
+
+        # Adds NATS connection options to an OptionParser.
+        #
+        # @param parser [OptionParser] Parser to configure.
+        # @param opts [Hash] Mutable parsed option accumulator.
+        #
+        # @return [void]
+        def add_connection_options(parser, opts)
+          parser.on('-s', '--server URL', 'NATS server URL. Defaults to ENV[NATS_URL] or local NATS') do |url|
+            opts[:server] = url
+          end
+          parser.on('--creds FILE', 'NATS user credentials file') { |file| opts[:creds] = file }
+        end
+
+        # Adds service filter options to an OptionParser.
+        #
+        # @param parser [OptionParser] Parser to configure.
+        # @param opts [Hash] Mutable parsed option accumulator.
+        #
+        # @return [void]
+        def add_filter_options(parser, opts)
+          parser.on('--name NAME', 'Only query services with this name') { |name| opts[:name] = name }
+          parser.on('--id ID', 'Only query this service id. Requires --name') { |id| opts[:id] = id }
+          parser.on('--prefix PREFIX', 'Service API prefix. Defaults to $SRV') { |prefix| opts[:prefix] = prefix }
+          parser.on('-t', '--timeout SECONDS', Float, 'Reply collection idle timeout') { |timeout| opts[:timeout] = timeout }
+        end
+
+        # Adds output and help options to an OptionParser.
+        #
+        # @param parser [OptionParser] Parser to configure.
+        # @param opts [Hash] Mutable parsed option accumulator.
+        #
+        # @return [void]
+        def add_output_options(parser, opts)
+          parser.on('--json', 'Print JSON output') { opts[:json] = true } unless opts[:json].nil?
+          parser.on('-h', '--help', 'Show this help') do
+            puts parser
+            exit
+          end
+        end
+
+        # Validates parsed CLI options.
+        #
+        # @param opts [Hash] Parsed CLI options.
+        #
+        # @return [void]
+        def validate!(opts)
+          return unless opts[:id] && opts[:name].to_s.empty?
+
+          warn 'error: --id requires --name'
+          exit 1
+        end
+
+        # Computes table column widths.
+        #
+        # @param headers [Array<String>] Column headers.
+        # @param rows [Array<Array>] Table rows.
+        #
+        # @return [Array<Integer>] Width for each column.
+        def column_widths(headers, rows)
+          headers.each_index.map do |index|
+            ([headers[index]] + rows.map { |row| row[index].to_s }).map(&:length).max
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/collect.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'trailblazer/operation'
+require_relative '../../nats_service_discovery'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Collects and parses JSON replies for an arbitrary Service API subject.
+        #
+        # On success, the result exposes `:responses`.
+        # On failure, the result exposes `:error`.
+        class Collect < Trailblazer::Operation
+          step :collect
+
+          # Collects JSON replies from `subject`.
+          #
+          # @param ctx [Hash] Operation context.
+          # @param client [NATS::Client] Connected NATS client.
+          # @param subject [String] Service API subject to query.
+          # @param timeout [Numeric] Idle timeout while waiting for replies.
+          #
+          # @return [Boolean] Whether replies were collected successfully.
+          def collect(ctx, client:, subject:, timeout: DEFAULT_TIMEOUT, **)
+            ctx[:responses] = NatsServiceDiscovery.new(client:).send(:collect_json, subject, timeout:)
+          rescue StandardError => e
+            ctx[:error] = e
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/connect.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'nats/client'
+require 'trailblazer/operation'
+require_relative '../../nats_service_discovery'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Opens a NATS client connection for discovery operations.
+        #
+        # On success, the result exposes `:client`.
+        # On failure, the result exposes `:error`.
+        class Connect < Trailblazer::Operation
+          step :connect
+
+          # Connects to NATS using `:server` or `:nats_url`.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [Boolean] Whether the connection was opened.
+          def connect(ctx, **)
+            opts = (ctx[:connect_options] || {}).dup
+            opts[:user_credentials] = ctx[:creds] if ctx[:creds]
+            ctx[:client] = NATS.connect(connection_url(ctx), opts)
+          rescue StandardError => e
+            ctx[:error] = e
+            false
+          end
+
+          private
+
+          # Default NATS URL used when no URL is provided.
+          #
+          # @return [String]
+          def default_url
+            ENV.fetch('NATS_URL', 'nats://127.0.0.1:4222')
+          end
+
+          # Resolves the NATS URL from the operation context.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [String]
+          def connection_url(ctx)
+            ctx[:nats_url] || ctx[:server] || default_url
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/discovery_options.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../nats_service_discovery'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Shared option extraction for operations that compose other discovery operations.
+        module DiscoveryOptions
+          private
+
+          # Extracts the common discovery options from a Trailblazer context.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [Hash] Arguments suitable for another discovery operation.
+          def operation_options(ctx)
+            {
+              client: ctx[:client],
+              prefix: ctx[:prefix],
+              timeout: ctx[:timeout],
+              name: ctx[:name],
+              id: ctx[:id],
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/info.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'verb'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Collects `$SRV.INFO` responses.
+        #
+        # On success, the result exposes `:responses`.
+        class Info < Verb
+          # Invokes {NatsServiceDiscovery#info}.
+          #
+          # @param discovery [NatsServiceDiscovery] Discovery helper.
+          #
+          # @return [Array<Hash>] Parsed info responses.
+          def public_send_verb(discovery, **)
+            discovery.info(**)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/ping.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'verb'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Collects `$SRV.PING` responses.
+        #
+        # On success, the result exposes `:responses`.
+        class Ping < Verb
+          # Invokes {NatsServiceDiscovery#ping}.
+          #
+          # @param discovery [NatsServiceDiscovery] Discovery helper.
+          #
+          # @return [Array<Hash>] Parsed ping responses.
+          def public_send_verb(discovery, **)
+            discovery.ping(**)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/services.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'trailblazer/operation'
+require_relative 'discovery_options'
+require_relative 'info'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Builds service-list summaries from `$SRV.INFO` responses.
+        #
+        # On success, the result exposes `:responses` and `:services`.
+        class Services < Trailblazer::Operation
+          include DiscoveryOptions
+
+          step :load_info?
+          step :summarize
+
+          # Loads raw service info responses for summarization.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [Boolean] Whether service info was loaded.
+          def load_info?(ctx, **)
+            result = Info.call(**operation_options(ctx))
+            ctx[:error] = result[:error] unless result.success?
+            ctx[:responses] = result[:responses]
+            result.success?
+          end
+
+          # Builds compact service summaries from raw info responses.
+          #
+          # @param ctx [Hash] Operation context.
+          # @param responses [Array<Hash>] Parsed `$SRV.INFO` responses.
+          #
+          # @return [Array<Hash>] Service summary rows.
+          def summarize(ctx, responses:, **)
+            ctx[:services] = responses.map do |service|
+              {
+                'name' => service['name'],
+                'id' => service['id'],
+                'version' => service['version'],
+                'endpoints' => Array(service['endpoints']).size,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/stats.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'verb'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Collects `$SRV.STATS` responses.
+        #
+        # On success, the result exposes `:responses`.
+        class Stats < Verb
+          # Invokes {NatsServiceDiscovery#stats}.
+          #
+          # @param discovery [NatsServiceDiscovery] Discovery helper.
+          #
+          # @return [Array<Hash>] Parsed stats responses.
+          def public_send_verb(discovery, **)
+            discovery.stats(**)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/subject_map.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'trailblazer/operation'
+require_relative 'discovery_options'
+require_relative 'info'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Builds a subject-to-endpoint listener map from `$SRV.INFO` responses.
+        #
+        # On success, the result exposes `:responses` and `:subject_map`.
+        class SubjectMap < Trailblazer::Operation
+          include DiscoveryOptions
+
+          step :load_info?
+          step :map_subjects
+
+          # Loads raw service info responses for mapping.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [Boolean] Whether service info was loaded.
+          def load_info?(ctx, **)
+            result = Info.call(**operation_options(ctx))
+            ctx[:error] = result[:error] unless result.success?
+            ctx[:responses] = result[:responses]
+            result.success?
+          end
+
+          # Builds a subject-to-listeners map from info responses.
+          #
+          # @param ctx [Hash] Operation context.
+          # @param responses [Array<Hash>] Parsed `$SRV.INFO` responses.
+          #
+          # @return [Hash] Listener entries keyed by NATS subject.
+          def map_subjects(ctx, responses:, **)
+            ctx[:subject_map] = responses.each_with_object({}) do |service, subjects|
+              Array(service['endpoints']).each do |endpoint|
+                add_listener(subjects, service, endpoint)
+              end
+            end
+          end
+
+          private
+
+          # Adds an endpoint listener to the subject map.
+          #
+          # @param subjects [Hash] Subject map accumulator.
+          # @param service [Hash] Parsed `$SRV.INFO` service response.
+          # @param endpoint [Hash] Endpoint payload from the service response.
+          #
+          # @return [void]
+          def add_listener(subjects, service, endpoint)
+            subject = endpoint['subject']
+            return if subject.to_s.empty?
+
+            subjects[subject] ||= []
+            subjects[subject] << listener_entry(service, endpoint)
+          end
+
+          # Builds a subject-map listener entry.
+          #
+          # @param service [Hash] Parsed `$SRV.INFO` service response.
+          # @param endpoint [Hash] Endpoint payload from the service response.
+          #
+          # @return [Hash] Listener entry suitable for subject maps.
+          def listener_entry(service, endpoint)
+            {
+              'service' => service['name'],
+              'service_id' => service['id'],
+              'version' => service['version'],
+              'endpoint' => endpoint['name'],
+              'queue_group' => endpoint['queue_group'],
+              'metadata' => endpoint['metadata'],
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation/verb.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'trailblazer/operation'
+require_relative '../../nats_service_discovery'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      module Operation
+        # Base class for `$SRV.<VERB>` operations.
+        #
+        # Subclasses choose which Service API verb to invoke.
+        class Verb < Trailblazer::Operation
+          step :collect
+
+          # Collects responses for the subclass Service API verb.
+          #
+          # @param ctx [Hash] Operation context.
+          #
+          # @return [Boolean] Whether responses were collected successfully.
+          def collect(ctx, **)
+            discovery = NatsServiceDiscovery.new(client: ctx[:client], prefix: ctx[:prefix] || DEFAULT_PREFIX)
+            ctx[:responses] = public_send_verb(
+              discovery,
+              name: ctx[:name],
+              id: ctx[:id],
+              timeout: ctx[:timeout] || DEFAULT_TIMEOUT,
+            )
+          rescue StandardError => e
+            ctx[:error] = e
+            false
+          end
+
+          private
+
+          # Invokes the subclass-specific discovery method.
+          #
+          # @raise [NotImplementedError] when a subclass does not implement this.
+          def public_send_verb(_discovery, **)
+            raise NotImplementedError, "#{self.class} must define #public_send_verb"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/leopard/nats_service_discovery/operation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../nats_service_discovery'
+
+module Rubyists
+  module Leopard
+    class NatsServiceDiscovery
+      # Trailblazer operations for NATS Service API discovery workflows.
+      module Operation
+      end
+    end
+  end
+end
+
+require_relative 'operation/discovery_options'
+require_relative 'operation/connect'
+require_relative 'operation/collect'
+require_relative 'operation/verb'
+require_relative 'operation/ping'
+require_relative 'operation/info'
+require_relative 'operation/stats'
+require_relative 'operation/services'
+require_relative 'operation/subject_map'

data/lib/leopard/nats_service_discovery.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'nats/client'
+
+module Rubyists
+  module Leopard
+    # Collects NATS Service API monitoring responses from a cluster.
+    #
+    # The NATS Service API uses request/reply subjects such as `$SRV.INFO`.
+    # Cluster-wide requests can receive multiple replies, so this helper creates
+    # an inbox subscription, publishes the request, and collects replies until a
+    # short timeout elapses.
+    class NatsServiceDiscovery
+      # Default NATS Service API monitoring prefix.
+      DEFAULT_PREFIX = '$SRV'
+      # Default idle timeout used to decide that all service replies arrived.
+      DEFAULT_TIMEOUT = 0.25
+
+      attr_reader :client, :prefix
+
+      # @param client [NATS::Client] Connected NATS client.
+      # @param prefix [String] Service API monitoring prefix.
+      def initialize(client:, prefix: DEFAULT_PREFIX)
+        @client = client
+        @prefix = prefix
+      end
+
+      # Collects `$SRV.PING` responses.
+      #
+      # @param name [String, nil] Optional service name filter.
+      # @param id [String, nil] Optional service id filter; requires `name`.
+      # @param timeout [Numeric] Idle timeout while collecting replies.
+      #
+      # @return [Array<Hash>] Parsed ping responses.
+      def ping(name: nil, id: nil, timeout: DEFAULT_TIMEOUT)
+        collect_json(service_subject('PING', name:, id:), timeout:)
+      end
+
+      # Collects `$SRV.INFO` responses.
+      #
+      # @param name [String, nil] Optional service name filter.
+      # @param id [String, nil] Optional service id filter; requires `name`.
+      # @param timeout [Numeric] Idle timeout while collecting replies.
+      #
+      # @return [Array<Hash>] Parsed info responses.
+      def info(name: nil, id: nil, timeout: DEFAULT_TIMEOUT)
+        collect_json(service_subject('INFO', name:, id:), timeout:)
+      end
+
+      # Collects `$SRV.STATS` responses.
+      #
+      # @param name [String, nil] Optional service name filter.
+      # @param id [String, nil] Optional service id filter; requires `name`.
+      # @param timeout [Numeric] Idle timeout while collecting replies.
+      #
+      # @return [Array<Hash>] Parsed stats responses.
+      def stats(name: nil, id: nil, timeout: DEFAULT_TIMEOUT)
+        collect_json(service_subject('STATS', name:, id:), timeout:)
+      end
+
+      # Builds a subject-to-listener map from service info responses.
+      #
+      # @param name [String, nil] Optional service name filter.
+      # @param id [String, nil] Optional service id filter; requires `name`.
+      # @param timeout [Numeric] Idle timeout while collecting replies.
+      #
+      # @return [Hash{String => Array<Hash>}] Endpoint listeners keyed by subject.
+      def endpoint_subject_map(name: nil, id: nil, timeout: DEFAULT_TIMEOUT)
+        info(name:, id:, timeout:).each_with_object({}) do |service, subjects|
+          Array(service['endpoints']).each do |endpoint|
+            subject = endpoint['subject']
+            next if subject.to_s.empty?
+
+            subjects[subject] ||= []
+            subjects[subject] << listener_entry(service, endpoint)
+          end
+        end
+      end
+
+      # Builds a Service API monitoring subject.
+      #
+      # @param verb [String, Symbol] Monitoring verb such as `INFO`.
+      # @param name [String, nil] Optional service name filter.
+      # @param id [String, nil] Optional service id filter; requires `name`.
+      #
+      # @return [String] Monitoring subject.
+      def service_subject(verb, name: nil, id: nil)
+        raise ArgumentError, 'service id requires a service name' if present?(id) && !present?(name)
+
+        parts = [prefix, verb.to_s.upcase]
+        parts << name.to_s if present?(name)
+        parts << id.to_s if present?(id)
+        parts.join('.')
+      end
+
+      private
+
+      # Collects JSON replies for a Service API subject until `timeout` elapses.
+      #
+      # @param subject [String] Service API subject to publish.
+      # @param timeout [Numeric] Idle timeout while waiting for replies.
+      #
+      # @return [Array<Hash>] Parsed response payloads.
+      def collect_json(subject, timeout:)
+        replies = []
+        sub = subscribe_to_inbox
+        client.publish(subject, '', sub.subject)
+        begin
+          collect_replies(sub, replies, timeout)
+        rescue NATS::Timeout
+          replies
+        end
+      ensure
+        sub&.unsubscribe
+      end
+
+      # Subscribes to an ephemeral reply inbox and flushes the subscription.
+      #
+      # @return [NATS::Subscription] Subscription bound to the reply inbox.
+      def subscribe_to_inbox
+        sub = client.subscribe(client.new_inbox)
+        client.flush
+        sub
+      end
+
+      # Appends parsed replies to the provided accumulator until timeout.
+      #
+      # @param sub [NATS::Subscription] Reply subscription.
+      # @param replies [Array<Hash>] Response accumulator.
+      # @param timeout [Numeric] Idle timeout while waiting for replies.
+      #
+      # @return [void]
+      def collect_replies(sub, replies, timeout)
+        loop do
+          msg = sub.next_msg(timeout:)
+          next if no_responders?(msg)
+
+          replies << JSON.parse(msg.data)
+        end
+      end
+
+      # Reports whether a reply is the server no-responders status message.
+      #
+      # @param msg [NATS::Msg] Reply message.
+      #
+      # @return [Boolean]
+      def no_responders?(msg)
+        msg.header && msg.header['Status'] == '503'
+      end
+
+      # Builds a subject-map listener entry from a service and endpoint payload.
+      #
+      # @param service [Hash] Parsed `$SRV.INFO` service response.
+      # @param endpoint [Hash] Endpoint payload from the service response.
+      #
+      # @return [Hash] Listener entry suitable for subject maps.
+      def listener_entry(service, endpoint)
+        {
+          'service' => service['name'],
+          'service_id' => service['id'],
+          'version' => service['version'],
+          'endpoint' => endpoint['name'],
+          'queue_group' => endpoint['queue_group'],
+          'metadata' => endpoint['metadata'],
+        }
+      end
+
+      # Reports whether a value is present for subject construction.
+      #
+      # @param value [Object] Value to check.
+      #
+      # @return [Boolean]
+      def present?(value)
+        !value.nil? && !value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/leopard/version.rb

@@ -3,7 +3,7 @@
 module Rubyists
   module Leopard
     # x-release-please-start-version
-    VERSION = '0.2.8'
+    VERSION = '0.2.10'
     # x-release-please-end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leopard
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.10
 platform: ruby
 authors:
 - bougyman
@@ -69,21 +69,39 @@ dependencies:
   name: semantic_logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4'
+- !ruby/object:Gem::Dependency
+  name: trailblazer-operation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
 description: Leopard is a puma-like server for managing concurrent NATS ServiceApi
   endpoint workers
 email:
 - bougyman@users.noreply.github.com
-executables: []
+executables:
+- leopard-service-info
+- leopard-service-map
+- leopard-service-stats
+- leopard-services
 extensions: []
 extra_rdoc_files: []
 files:
@@ -100,8 +118,14 @@ files:
 - ci/nats/start.sh
 - ci/publish-gem.sh
 - doc/service-api-vs-rest.adoc
+- documents/enable-injectable-request-reply-callbacks.adoc
 - examples/echo_endpoint.rb
+- examples/groups.rb
 - examples/jetstream_endpoint.rb
+- exe/leopard-service-info
+- exe/leopard-service-map
+- exe/leopard-service-stats
+- exe/leopard-services
 - lib/leopard.rb
 - lib/leopard/errors.rb
 - lib/leopard/message_processor.rb
@@ -112,6 +136,18 @@ files:
 - lib/leopard/nats_jetstream_consumer.rb
 - lib/leopard/nats_jetstream_endpoint.rb
 - lib/leopard/nats_request_reply_callbacks.rb
+- lib/leopard/nats_service_discovery.rb
+- lib/leopard/nats_service_discovery/cli.rb
+- lib/leopard/nats_service_discovery/operation.rb
+- lib/leopard/nats_service_discovery/operation/collect.rb
+- lib/leopard/nats_service_discovery/operation/connect.rb
+- lib/leopard/nats_service_discovery/operation/discovery_options.rb
+- lib/leopard/nats_service_discovery/operation/info.rb
+- lib/leopard/nats_service_discovery/operation/ping.rb
+- lib/leopard/nats_service_discovery/operation/services.rb
+- lib/leopard/nats_service_discovery/operation/stats.rb
+- lib/leopard/nats_service_discovery/operation/subject_map.rb
+- lib/leopard/nats_service_discovery/operation/verb.rb
 - lib/leopard/settings.rb
 - lib/leopard/templates/prometheus_metrics.erb
 - lib/leopard/version.rb