leopard 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb81d09b4b0709f3f290009e42e9fa1080e6b33e1fa578473b789875cfa44054
-  data.tar.gz: 0f1d6d756f9a60cb9cd9f6a7072e6c9e2fcd1060faed0121ad6a3d27496a3ea6
+  metadata.gz: 42beb75a4668c0874385a6d0cc8deead97def34d08a45e4c7a314ffb75697bcf
+  data.tar.gz: 3d69bfcf8942d34695514c9b70d25ccc68024ca4027ce3cd4cc3f22bee3b6986
 SHA512:
-  metadata.gz: c584384a406f264f2e3bb20c0a40fd75506e7f407985f7b4fb42166899fce3b233f99df795e6e75a4c973f6369c93cb10a9eb29f4453a4cd88c19680d9839ed2
-  data.tar.gz: 4bdbdfc0debc18a1bbd7ef8e636e4ad2019fa593fd083a47683f48bfb099302552e528eac530f99e464f5347c0475d1c49a874aa4021aaf5dcb2c4a4e321fe68
+  metadata.gz: 6f0b1e3f0d13fbfdee1614f5a3af3f8ba0758d5afec9cee415c7d36fc448a11e5d8c4df4895119c87ce909ff3b0b7ab61aa0956f774565930521f946f6b27053
+  data.tar.gz: 9cbf821b916e89d469d05abfb29ba92a337c1a08394d1a66cef39e6613426d8a2f893fbe27d55e4ebaa329f8d4ae7b50c8fa1a657df8af7fec11d9c8bec8b871

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.5"
+  ".": "0.2.6"
 }

data/.version.txt

@@ -1 +1 @@
-0.2.5
+0.2.6

data/.yardopts

@@ -0,0 +1,5 @@
+--readme Readme.adoc
+--protected
+--private
+--output-dir doc/yard
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.6](https://github.com/rubyists/leopard/compare/v0.2.5...v0.2.6) (2026-04-21)
+
+
+### Features
+
+* add nats_jetstream_consumer to provide the feature requested in issue [#44](https://github.com/rubyists/leopard/issues/44) ([#45](https://github.com/rubyists/leopard/issues/45)) ([9372aa4](https://github.com/rubyists/leopard/commit/9372aa4ce59b130e7143905ce5e8065519778861))
+
 ## [0.2.5](https://github.com/rubyists/leopard/compare/v0.2.4...v0.2.5) (2026-04-16)
 
 

data/Rakefile

@@ -4,8 +4,15 @@ require 'rake'
 require 'minitest/test_task'
 require 'bundler/gem_tasks'
 require 'rubocop/rake_task'
+require 'net/http'
+require 'open3'
+require 'shellwords'
+require 'timeout'
+require 'yard'
+require 'yard/rake/yardoc_task'
 
 RuboCop::RakeTask.new
+YARD::Rake::YardocTask.new(:yard)
 
 Minitest::TestTask.create(:test) do |task|
   task.libs << 'lib'
@@ -14,4 +21,106 @@ Minitest::TestTask.create(:test) do |task|
   task.warning = true
 end
 
-task default: %i[rubocop test]
+QUICK_TEST_FILES = Dir['test/*/**/*.rb'].reject { |file| file.start_with?('test/integration/') }.sort.freeze
+
+# Returns the local NATS JetStream health endpoint used by the CI helpers.
+#
+# @return [URI::HTTP] The health endpoint URI.
+def nats_health_uri = URI('http://127.0.0.1:8222/healthz')
+
+# Reports whether the local NATS JetStream health endpoint is currently reachable.
+#
+# @return [Boolean] `true` when the broker responds successfully, otherwise `false`.
+def nats_ready?
+  Net::HTTP.get_response(nats_health_uri).is_a?(Net::HTTPSuccess)
+rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ECONNRESET
+  false
+end
+
+# Waits for the local NATS JetStream broker to report healthy.
+#
+# @return [void]
+# @raise [RuntimeError] If the broker does not become healthy within 30 seconds.
+def wait_for_nats!
+  Timeout.timeout(30) do
+    sleep 1 until nats_ready?
+  end
+rescue Timeout::Error
+  raise 'Timed out waiting for NATS JetStream health endpoint on http://127.0.0.1:8222/healthz'
+end
+
+# Detects the container runtime used to manage the local NATS broker.
+#
+# @return [String] `podman` when available, otherwise `docker`.
+def container_runtime
+  File.executable?('/usr/bin/podman') || system('command -v podman > /dev/null 2>&1', exception: false) ? 'podman' : 'docker'
+end
+
+# Runs the non-integration test files directly for a fast local feedback loop.
+#
+# @return [void]
+def run_quick_tests!
+  sh "ruby -w -Ilib -Itest #{QUICK_TEST_FILES.shelljoin}"
+end
+
+# Verifies that the current YARD coverage is complete.
+#
+# @return [void]
+# @raise [RuntimeError] If YARD reports anything less than 100% documentation coverage.
+def verify_yard_coverage!
+  output, status = Open3.capture2e('bundle', 'exec', 'yard', 'stats', '--list-undoc')
+  puts output
+  raise 'yard stats failed' unless status.success?
+  return if output.include?('100.00% documented')
+
+  raise 'YARD documentation coverage is incomplete'
+end
+
+namespace :nats do
+  desc 'Start the local NATS JetStream broker via ./ci/nats/start.sh'
+  task :start do
+    sh({ 'NATS_DETACH' => '1' }, './ci/nats/start.sh')
+  end
+
+  desc 'Wait for the local NATS JetStream broker health endpoint'
+  task :wait do
+    wait_for_nats!
+  end
+
+  desc 'Stop the local NATS JetStream broker container'
+  task :stop do
+    name = ENV.fetch('NATS_NAME', 'leopard-nats')
+    sh(container_runtime, 'rm', '-f', name, verbose: false)
+  rescue RuntimeError
+    nil
+  end
+end
+
+namespace :ci do
+  desc 'Run RuboCop, YARD verification, and the non-integration test suite without managing NATS'
+  task quick: %i[rubocop yard:verify] do
+    run_quick_tests!
+  end
+
+  desc 'Run the full test suite against a managed local NATS JetStream broker'
+  task :test do
+    Rake::Task['nats:start'].invoke
+    Rake::Task['nats:wait'].invoke
+    Rake::Task['test'].invoke
+  ensure
+    Rake::Task['nats:stop'].reenable
+    Rake::Task['nats:stop'].invoke
+  end
+end
+
+desc 'Run RuboCop and the full test suite against a managed local NATS JetStream broker'
+task ci: %w[rubocop yard:verify ci:test]
+
+namespace :yard do
+  desc 'Fail if YARD reports incomplete documentation coverage'
+  task :verify do
+    verify_yard_coverage!
+  end
+end
+
+task default: :ci

data/Readme.adoc

@@ -12,6 +12,7 @@ minimal DSL for defining endpoints and middleware.
 == Features
 
 * Declarative endpoint definitions with `#endpoint`.
+* Declarative JetStream pull consumers with `#jetstream_endpoint`.
 * Grouping of endpoints with `#group`
 * Simple concurrency via `#run` with a configurable number of instances.
 * JSON aware message wrapper that gracefully handles parse errors.
@@ -90,13 +91,72 @@ end
 EchoService.use LoggerMiddleware
 ----
 
+== JetStream Pull Consumers
+
+Leopard can also bind JetStream pull consumers through the same middleware and `Dry::Monads::Result`
+handler contract used by request/reply endpoints.
+
+[source,ruby]
+----
+class EventConsumer
+  include Rubyists::Leopard::NatsApiServer
+
+  jetstream_endpoint(
+    :events,
+    stream: 'EVENTS',
+    subject: 'events.created',
+    durable: 'events-created-worker',
+    consumer: { max_deliver: 5 },
+    batch: 5,
+    fetch_timeout: 1,
+    nak_delay: 2,
+  ) do |msg|
+    Success(msg.data)
+  end
+end
+----
+
+JetStream handlers receive the same `Rubyists::Leopard::MessageWrapper` as service endpoints.
+Leopard will:
+
+* `ack` on `Success`
+* `nak` on `Failure` (`nak_delay:` is optional)
+* `term` on unhandled exceptions
+
+Each Leopard `instances:` worker creates its own pull subscription loop, so JetStream consumers
+scale with the same process-local concurrency model as the rest of the framework.
+
 == Development
 
 The project uses Minitest and RuboCop. Run tests with Rake:
 
 [source,bash]
 ----
-$ bundle exec rake
+$ bundle exec rake ci
+----
+
+This task starts NATS JetStream through `./ci/nats/start.sh`, waits for broker health,
+runs RuboCop and the test suite, and then stops the broker.
+
+API documentation can be generated with:
+
+[source,bash]
+----
+$ bundle exec rake yard
+----
+
+Documentation coverage is enforced with:
+
+[source,bash]
+----
+$ bundle exec rake yard:verify
+----
+
+If you want to run the broker yourself, the same script can still be used directly:
+
+[source,bash]
+----
+$ ./ci/nats/start.sh
 ----
 
 === Conventional Commits (semantic commit messages)

data/ci/nats/start.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 
 NATS_VERSION=2
+NATS_NAME=${NATS_NAME:-leopard-nats}
+NATS_DETACH=${NATS_DETACH:-0}
 
 if readlink -f . >/dev/null 2>&1 # {{{ makes readlink work on mac
 then
@@ -29,5 +31,28 @@ else
     runtime=docker
 fi
 
+args=(
+  run
+  --rm
+  --name "$NATS_NAME"
+  -p 4222:4222
+  -p 6222:6222
+  -p 8222:8222
+  -v ./accounts.txt:/accounts.txt
+)
+
+if [ "$NATS_DETACH" = "1" ]
+then
+    args+=(-d)
+else
+    args+=(-it)
+fi
+
+args+=(
+  "nats:$NATS_VERSION"
+  -js
+  -c /accounts.txt
+)
+
 set -x
-exec "$runtime" run --rm -it -p 4222:4222 -p 6222:6222 -p 8222:8222 -v ./accounts.txt:/accounts.txt nats:"$NATS_VERSION" -js -c /accounts.txt "$@"
+exec "$runtime" "${args[@]}" "$@"

data/examples/echo_endpoint.rb

@@ -8,6 +8,12 @@ class EchoService
   include Rubyists::Leopard::NatsApiServer
 
   config.logger = SemanticLogger[:EchoService]
+
+  # Builds the example service instance.
+  #
+  # @param a_var [Integer] Example initializer state passed through `instance_args`.
+  #
+  # @return [void]
   def initialize(a_var: 1)
     logger.info "EchoService initialized with a_var: #{a_var}"
   end

data/examples/jetstream_endpoint.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/leopard/nats_api_server'
+
+# Example JetStream worker for async event processing.
+class EventConsumer
+  include Rubyists::Leopard::NatsApiServer
+
+  config.logger = SemanticLogger[:EventConsumer]
+
+  jetstream_endpoint(
+    :events,
+    stream: 'EVENTS',
+    subject: 'events.created',
+    durable: 'events-created-worker',
+    consumer: {
+      ack_wait: 30,
+      max_deliver: 5,
+    },
+    batch: 5,
+    fetch_timeout: 1,
+    nak_delay: 2,
+  ) do |msg|
+    logger.info 'Processing event', data: msg.data
+    Success(msg.data)
+  rescue StandardError => e
+    Failure(error: e.message, data: msg.data)
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  SemanticLogger.default_level = :info
+  SemanticLogger.add_signal_handler
+  SemanticLogger.add_appender(io: $stdout, formatter: :color)
+  EventConsumer.run(
+    nats_url: 'nats://localhost:4222',
+    service_opts: {
+      name: 'example.event_consumer',
+      version: '1.0.0',
+    },
+    instances: ENV.fetch('EVENT_CONSUMER_INSTANCES', '1').to_i,
+  )
+end

data/lib/leopard/errors.rb

@@ -2,12 +2,19 @@
 
 module Rubyists
   module Leopard
+    # Base Leopard exception that truncates backtraces for cleaner logs.
     class LeopardError < StandardError
+      # Captures the original exception state while replacing the backtrace with the current call stack.
+      #
+      # @return [void]
       def initialize(...)
         super
         set_backtrace(caller)
       end
 
+      # Returns a Leopard-truncated backtrace.
+      #
+      # @return [Array<String>] Up to the first four backtrace entries, plus a truncation marker when applicable.
       def backtrace
         # If the backtrace is nil, return an empty array
         orig = (super || [])[0..3]
@@ -19,8 +26,11 @@ module Rubyists
       end
     end
 
+    # Generic Leopard error superclass.
     class Error < LeopardError; end
+    # Raised when Leopard configuration is invalid.
     class ConfigurationError < Error; end
+    # Raised when a handler returns an unsupported object instead of a result monad.
     class ResultError < Error; end
   end
 end

data/lib/leopard/message_processor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rubyists
+  module Leopard
+    # Composes middleware around Leopard handlers and routes their results to transport callbacks.
+    class MessageProcessor
+      private attr_reader :execute_handler, :logger, :middleware, :wrapper_factory
+
+      # Builds a reusable processor for request/reply and JetStream transports.
+      #
+      # @param wrapper_factory [#call] Callable that wraps a raw transport message in a {MessageWrapper}-compatible object.
+      # @param middleware [#call] Callable returning the current middleware stack.
+      # @param execute_handler [#call] Callable that executes the endpoint handler with the wrapped message.
+      # @param logger [#error] Logger used for processing failures.
+      #
+      # @return [void]
+      def initialize(wrapper_factory:, middleware:, execute_handler:, logger:)
+        @wrapper_factory = wrapper_factory
+        @middleware = middleware
+        @execute_handler = execute_handler
+        @logger = logger
+      end
+
+      # Processes a raw transport message through middleware and terminal callbacks.
+      #
+      # @param raw_msg [Object] The raw transport message from NATS.
+      # @param handler [Proc] The endpoint handler to execute.
+      # @param callbacks [Hash{Symbol => #call}] Success, failure, and error callbacks for the transport.
+      #
+      # @return [Object] The transport-specific callback result.
+      def process(raw_msg, handler, callbacks)
+        app(callbacks, handler).call(wrapper_factory.call(raw_msg))
+      end
+
+      private
+
+      # Builds the middleware stack around the terminal application.
+      #
+      # @param callbacks [Hash{Symbol => #call}] Transport callbacks keyed by outcome.
+      # @param handler [Proc] The endpoint handler to execute at the core of the stack.
+      #
+      # @return [#call] The composed middleware application.
+      def app(callbacks, handler)
+        middleware.call.reverse_each.reduce(base_app(handler, callbacks)) do |current, (klass, args, blk)|
+          klass.new(current, *args, &blk)
+        end
+      end
+
+      # Builds the terminal application that runs the handler and dispatches transport callbacks.
+      #
+      # @param handler [Proc] The endpoint handler to execute.
+      # @param callbacks [Hash{Symbol => #call}] Transport callbacks keyed by outcome.
+      #
+      # @return [Proc] The terminal application for the middleware chain.
+      def base_app(handler, callbacks)
+        lambda do |wrapper|
+          result = execute_handler.call(wrapper, handler)
+          process_result(wrapper, result, callbacks)
+        rescue StandardError => e
+          logger.error 'Error processing message: ', e
+          callbacks[:on_error].call(wrapper, e)
+        end
+      end
+
+      # Routes a {Dry::Monads::Result} to the appropriate transport callback.
+      #
+      # @param wrapper [MessageWrapper] The wrapped transport message.
+      # @param result [Dry::Monads::Result] The handler result to route.
+      # @param callbacks [Hash{Symbol => #call}] Transport callbacks keyed by outcome.
+      #
+      # @return [Object] The callback return value for the routed result.
+      # @raise [ResultError] If the handler returned a non-result object.
+      def process_result(wrapper, result, callbacks)
+        case result
+        in Dry::Monads::Success
+          callbacks[:on_success].call(wrapper, result)
+        in Dry::Monads::Failure
+          callbacks[:on_failure].call(wrapper, result)
+        else
+          logger.error('Unexpected result: ', result:)
+          raise ResultError, "Unexpected Response from Handler, must respond with a Success or Failure monad: #{result}"
+        end
+      end
+    end
+  end
+end

data/lib/leopard/message_wrapper.rb

@@ -4,15 +4,19 @@ require 'json'
 
 module Rubyists
   module Leopard
+    # Wraps a raw NATS message with parsed payload and convenience response helpers.
     class MessageWrapper
       # @!attribute [r] raw
+      #
       # @return [NATS::Message] The original NATS message.
       #
       # @!attribute [r] data
+      #
       # @return [Object] The parsed data from the NATS message.
       attr_reader :raw, :data
       #
       # @!attribute [w] headers
+      #
       # @return [Hash] The headers from the NATS message.
       attr_accessor :headers
 

data/lib/leopard/metrics_server.rb

@@ -5,9 +5,15 @@ require 'erb'
 
 module Rubyists
   module Leopard
+    # Adds a minimal Prometheus HTTP endpoint for Leopard worker metrics.
     module MetricsServer
       private
 
+      # Starts a lightweight HTTP server that exposes Leopard Prometheus metrics.
+      #
+      # @param workers [Array<Object>] Active Leopard worker instances to observe.
+      #
+      # @return [Thread] The server thread.
       def start_metrics_server(workers)
         port = ENV.fetch('LEOPARD_METRICS_PORT', '9394').to_i
         Thread.new do
@@ -19,6 +25,12 @@ module Rubyists
         end
       end
 
+      # Handles an individual metrics HTTP client connection.
+      #
+      # @param client [TCPSocket] The connected HTTP client.
+      # @param workers [Array<Object>] Active Leopard worker instances to observe.
+      #
+      # @return [void]
       def handle_metrics_client(client, workers)
         request_line = client.gets
         loop { break if (client.gets || '').chomp.empty? }
@@ -29,12 +41,24 @@ module Rubyists
         close_client(client)
       end
 
+      # Closes a metrics client socket, ignoring cleanup failures.
+      #
+      # @param client [TCPSocket] The connected HTTP client.
+      #
+      # @return [void]
       def close_client(client)
         client.close
       rescue StandardError
         nil
       end
 
+      # Writes the HTTP response for a metrics request.
+      #
+      # @param client [TCPSocket] The connected HTTP client.
+      # @param request_line [String, nil] The first line of the HTTP request.
+      # @param workers [Array<Object>] Active Leopard worker instances to observe.
+      #
+      # @return [void]
       def write_metrics_response(client, request_line, workers)
         if request_line&.start_with?('GET /metrics')
           body = prometheus_metrics(workers)
@@ -46,11 +70,21 @@ module Rubyists
         end
       end
 
+      # Builds the Prometheus metrics payload for the current worker state.
+      #
+      # @param workers [Array<Object>] Active Leopard worker instances to observe.
+      #
+      # @return [String] Rendered Prometheus text exposition output.
       def prometheus_metrics(workers)
         metrics = collect_prometheus_metrics(workers)
         render_metrics_template(metrics)
       end
 
+      # Aggregates per-subject worker utilization metrics.
+      #
+      # @param workers [Array<Object>] Active Leopard worker instances to observe.
+      #
+      # @return [Hash{Symbol => Object}] Metric hashes for the Prometheus template.
       def collect_prometheus_metrics(workers)
         busy    = Hash.new(0)
         pending = Hash.new(0)
@@ -63,6 +97,13 @@ module Rubyists
         }
       end
 
+      # Adds one worker's endpoint saturation metrics to the aggregate hashes.
+      #
+      # @param worker [Object] A Leopard worker instance.
+      # @param busy [Hash{String => Integer}] Subject-to-busy-worker counts.
+      # @param pending [Hash{String => Integer}] Subject-to-pending-message counts.
+      #
+      # @return [void]
       def accumulate_worker_metrics(worker, busy, pending)
         service = worker.instance_variable_get(:@service)
         return unless service
@@ -78,10 +119,18 @@ module Rubyists
         end
       end
 
+      # Renders the metrics ERB template with aggregated metric data.
+      #
+      # @param metrics [Hash{Symbol => Object}] Aggregated metric data for template rendering.
+      #
+      # @return [String] The rendered Prometheus payload.
       def render_metrics_template(metrics)
         ERB.new(File.read(metrics_template_path), trim_mode: '-').result_with_hash(metrics)
       end
 
+      # Returns the absolute path to the Prometheus metrics template.
+      #
+      # @return [String] The metrics template path.
       def metrics_template_path
         File.expand_path('templates/prometheus_metrics.erb', __dir__)
       end