leopard 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cb911c6ac11f486f56610fd734ae2a4e5187495d28524621d742fca976377eb
-  data.tar.gz: 713a3ea176a74f8a47abc83c4340a9432b781262b9fd5e431ada44991d9c2395
+  metadata.gz: 343e274b8fffbe093d59b1d819a4b0be0ba9efe109c4883c535ba3692f1854a3
+  data.tar.gz: 6b32780cf1bd40d7b0191a79a533382dbc6ed828162d9c6ebeefa2c838191c77
 SHA512:
-  metadata.gz: ee37dc08e56cb6dc95262c0c61df02ad8f9fc2168cfff2c30fcf908dfb51c502676e796d00e2903bc9c8251d1d866b829579abce5fca3172336f1a74fb18b1a6
-  data.tar.gz: f09054e25ce41281175c0d09ccc993ec735f2c3278c9d631d964aa39850fc9fdfd54b08144c67df4d938079245f60a5da0079fda68fb209131f83384c8e421f8
+  metadata.gz: 2ee58b9e7a03d9dee24f3d338e700c0d0456ff0056379e06405418365023a14dc7484bad768d7deff2727cb7e01f0daa331234bfa6b0875b5891f79577a1880e
+  data.tar.gz: '047850ac66d9a789bdaad311ef764bed2bea365776a67d6f47f9634eb039edc303ab48d6227ad443f4f2a49b5fba1f1cd63c5d45068120b544d9a1e8a65c292d'

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.5"
+  ".": "0.1.7"
 }

data/.version.txt

@@ -1 +1 @@
-0.1.5
+0.1.7

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.1.7](https://github.com/rubyists/leopard/compare/v0.1.6...v0.1.7) (2025-08-06)
+
+
+### Bug Fixes
+
+* Allow non blocking all the way down to the instance level ([#27](https://github.com/rubyists/leopard/issues/27)) ([01748a5](https://github.com/rubyists/leopard/commit/01748a56bc927ee1dbc70d2351fd12037e5b4bef))
+* Stop sending code argument to respond_with_error, it does not accept it ([#23](https://github.com/rubyists/leopard/issues/23)) ([9d87b8c](https://github.com/rubyists/leopard/commit/9d87b8c308a1fdff72769863711bb6bb942b3677))
+
+## [0.1.6](https://github.com/rubyists/leopard/compare/v0.1.5...v0.1.6) (2025-08-03)
+
+
+### Features
+
+* Adds graceful shutdown when INT/TERM/QUIT signal is received ([#18](https://github.com/rubyists/leopard/issues/18)) ([ce03fb0](https://github.com/rubyists/leopard/commit/ce03fb00afcbbadadc413766b62df9451f7b73b8))
+
 ## [0.1.5](https://github.com/rubyists/leopard/compare/v0.1.4...v0.1.5) (2025-07-31)
 
 

data/doc/service-api-vs-rest.adoc

@@ -0,0 +1,149 @@
+= NATS ServiceApi (via Leopard) vs REST
+:revdate: 2025-08-03
+:doctype: whitepaper
+
+== Abstract
+Leopard’s NATS ServiceApi wrapper delivers full-featured service-to-service communication, comparable with REST/GRPC.
+With NATS, you get discovery, health checks, and observability, all at the protocol layer.
+
+All Leopard does is add an Easy Button to serve these endpoints with concurrency to scale NATS connections
+horizontally, and to allow for per-endpoint (or groups of endpoints) scaling.
+
+This abstraction preserves the simplicity of REST requests with the resilience of asynchronous messaging
+under the hood.
+
+This paper contrasts the NATS ServiceApi model with traditional REST, outlines its key benefits and trade-offs,
+and illustrates how Leopard can specifically streamline microservice (and nanoservice) architectures.
+
+== 1. Introduction
+Microservices communicate most often via HTTP/REST today, but REST comes with overhead: service registries,
+load-balancers, schema/version endpoints, and brittle synchronous request patterns.
+Leopard leverages NATS’s ServiceApi layer to deliver:
+
+* **Automatic discovery** via `$SRV.PING/INFO/​STATS` subjects
+* **Dynamic load-balanced routing** with queue groups
+* **Built-in telemetry** (per-endpoint request counts, latencies, errors)
+* **Scalable workers** (Concurrent::FixedThreadPool with Leopard, currently)
+* **Versioned endpoints**  multiple versions can be registered concurrently, no need for /v1, /v2, etc.
+
+== 2. Architecture Overview
+Leopard embeds a “mini web-framework” in Ruby, registering each endpoint on a NATS subject and grouping instances for load-sharing:
+
+[source,mermaid]
+----
+graph LR
+  subgraph ServiceInstance
+    A[NatsApiServer.run] --> B[Registers endpoints]
+  end
+  subgraph NATS_Cluster
+    B --> C["$SRV.INFO.calc"]
+    B --> D["calc.add queue group"]
+  end
+  E[Client] -->|request calc.add| D
+  D --> F[Worker Thread pool]
+  F --> G[Handler & Dry Monads]
+  G -->|respond or error| E
+----
+
+== 3. Key Benefits
+
+=== 3.1 Automatic Discovery & Monitoring
+Leopard services auto-advertise on well-known NATS subjects. Clients can query:
+
+* `$SRV.PING.<name>` – discover live instances & measure RTT
+* `$SRV.INFO.<name>` – retrieve endpoint schemas & metadata
+* `$SRV.STATS.<name>` – fetch per-endpoint metrics
+
+No external service-registry (Consul, etcd) or custom HTTP health paths required.
+
+=== 3.2 Scaling-Per-Endpoint-Group
+Each endpoint (mapped to a NATS subject) is registered with an optional queue group.
+This allows it to enjoy native NATS queue-group load balancing. You can:
+
+* Scale thread-pooled workers independently per service
+* Horizontally add new service instances without redeploying clients
+* Isolate hot-paths (e.g. “reports.generate”) onto dedicated worker farms
+
+=== 3.3 Observability & Telemetry
+Leopard exposes stats out-of-the-box:
+
+* Request counts, error counts, processing time
+* Custom `on_stats` hooks for business metrics
+* Integration with Prometheus or any NATS-capable dashboard
+
+=== 3.4 Asynchronous, Resilient Communication
+Unlike blocking HTTP calls, Leopard’s NATS requests can:
+
+* Employ timeouts, retries, and dead-letter queues
+* Fit into event-driven pipelines, decoupling producers and consumers
+* Maintain throughput under partial outages
+
+== 4. Comparison with REST
+[cols="1,1,1", options="header"]
+|===
+| Feature                   | REST (HTTP)                                                | NATS ServiceApi
+
+| Discovery
+| Requires external service registry or API gateway, A.K.A. "it's always DNS"
+| Built-in via `$SRV.PING`, `$SRV.INFO`, `$SRV.STATS` Works uniformly across all languages
+
+| Load Balancing
+| HTTP load balancer or DNS round-robin
+| Native queue-group load balancing per subject
+
+| Telemetry
+| Custom instrumentation (e.g., `/metrics` endpoint)
+| Auto-collected stats (`service.stats`) and `on_stats` hooks
+
+| Latency & Overhead
+| Higher (HTTP/TCP handshake, headers, JSON)
+| Low-latency binary protocol with optional JSON payloads (other formats supported with plugins)
+
+| Communication Model
+| Synchronous, blocking request/response
+| Asynchronous request/reply, decoupled via subjects
+
+| Schema & Validation
+| OpenAPI/Swagger externally managed
+| Optional metadata on endpoints + pluggable middleware
+
+| Error Handling
+| HTTP status codes and response bodies
+| Standardized error headers (`Nats-Service-Error`, `Nats-Service-Error-Code`)
+
+| Multi-Language Support
+| Varies by framework; patterns differ per language
+| Uniform ServiceApi semantics with native clients in all major languages
+
+| Scalability
+| Scale replicas behind LB
+| Scale thread pools vertically + horizontal instances independently, by endpoint groups (or even a single endpoint)
+|===
+
+== 5. Trade-Offs & Considerations
+. **Dependency on NATS**
+  Leopard requires a healthy NATS cluster; network partition or broker outage impacts all services. (This is not unlike Redis or Postgres dependencies)
+. **Learning Curve**
+  Teams must understand NATS subjects, queue groups, and ServiceApi conventions. (Easier with helpers like Leopard’s `NatsApiServer`.)
+. **Language Support**
+  While Leopard is Ruby-centric, NATS ServiceApi is cross-language. All teams must adopt compatible clients. (And handle concurrency and error handling in their own way.)
+. **Subject Naming**
+  Adopting a consistent naming convention for subjects is crucial. This can be a challenge in large teams.
+  NATS can support a massive number of subjects. But to avoid confusion, subjects should have
+  clear, descriptive names that reflect the service and endpoint purpose.
+  Even though NATS service API exposes auto-discovery, there could (should?) be a central authoritative
+  document that defines the subject structure and naming conventions. This can avoid the TOCTOE issue.
+  (You check for a subject, it's not used, but then someone implements it in the meantime.)
+  That leads to: there should be a "registry" of subjects, that can be queried by developers
+  to discover available subjects.  This can avoid confusion and ensure that all developers are on the same
+  page and not conflicting with one another.
+
+== 6. What, then?
+Leopard’s NATS ServiceApi framework offers a powerful alternative to REST:
+zero-config discovery, per-endpoint scaling, rich observability, and asynchronous resilience.
+
+For high-throughput, low-latency microservice (nano-service?) ecosystems, Leopard can simplify infrastructure,
+reduce boilerplate, and improve operational visibility.
+
+Leopard's aim is to retain the expressiveness and composability of idiomatic Ruby, while leveraging
+NATS's ServiceApi performance and flexibility.

data/examples/echo_endpoint.rb

@@ -7,13 +7,22 @@ require_relative '../lib/leopard/nats_api_server'
 class EchoService
   include Rubyists::Leopard::NatsApiServer
 
+  def initialize(a_var = 1)
+    logger.info "EchoService initialized with a_var: #{a_var}"
+  end
+
   endpoint(:echo) { |msg| Success(msg.data) }
+  endpoint(:echo_fail) { |msg| Failure({ failure: '*boom*', data: msg.data }) }
 end
 
 if __FILE__ == $PROGRAM_NAME
   EchoService.run(
     nats_url: 'nats://localhost:4222',
-    service_opts: { name: 'example.echo', version: '1.0.0' },
-    instances: 4,
+    service_opts: {
+      name: 'example.echo',
+      version: '1.0.0',
+      instance_args: [2],
+    },
+    instances: 1,
   )
 end

data/lib/leopard/message_wrapper.rb

@@ -30,11 +30,10 @@ module Rubyists
       end
 
       # @param err [String, Exception] The error message or exception to respond with.
-      # @param code [Integer] The HTTP status code to use for the error response.
       #
       # @return [void]
-      def respond_with_error(err, code: 500)
-        raw.respond_with_error(err.to_s, code:)
+      def respond_with_error(err)
+        raw.respond_with_error(err.to_s)
       end
 
       private

data/lib/leopard/nats_api_server.rb

@@ -2,6 +2,7 @@
 
 require 'nats/client'
 require 'dry/monads'
+require 'dry/configurable'
 require 'concurrent'
 require_relative '../leopard'
 require_relative 'message_wrapper'
@@ -14,10 +15,14 @@ module Rubyists
 
       def self.included(base)
         base.extend(ClassMethods)
+        base.include(InstanceMethods)
         base.extend(Dry::Monads[:result])
-        base.include(SemanticLogger::Loggable)
+        base.extend(Dry::Configurable)
+        base.setting :logger, default: Rubyists::Leopard.logger, reader: true
       end
 
+      Endpoint = Struct.new(:name, :subject, :queue, :group, :handler)
+
       module ClassMethods
         def endpoints = @endpoints ||= []
         def groups = @groups ||= {}
@@ -33,13 +38,7 @@ module Rubyists
         #
         # @return [void]
         def endpoint(name, subject: nil, queue: nil, group: nil, &handler)
-          endpoints << {
-            name:,
-            subject: subject || name,
-            queue:,
-            group:,
-            handler:,
-          }
+          endpoints << Endpoint.new(name:, subject: subject || name, queue:, group:, handler:)
         end
 
         # Define a group for organizing endpoints.
@@ -75,11 +74,12 @@ module Rubyists
         # @return [void]
         def run(nats_url:, service_opts:, instances: 1, blocking: true)
           logger.info 'Booting NATS API server...'
-          # Return the thread pool if non-blocking
-          pool = spawn_instances(nats_url, service_opts, instances)
+          workers = Concurrent::Array.new
+          pool = spawn_instances(nats_url, service_opts, instances, workers, blocking)
+          logger.info 'Setting up signal trap...'
+          trap_signals(workers, pool)
           return pool unless blocking
 
-          # Otherwise, just sleep the main thread forever
           sleep
         end
 
@@ -90,21 +90,91 @@ module Rubyists
         # @param url [String] The URL of the NATS server.
         # @param opts [Hash] Options for the NATS service.
         # @param count [Integer] The number of instances to spawn.
+        # @param workers [Array] The array to store worker instances.
+        # @param blocking [Boolean] If false, does not block current thread after starting the server.
         #
         # @return [Concurrent::FixedThreadPool] The thread pool managing the worker threads.
-        def spawn_instances(url, opts, count)
+        def spawn_instances(url, opts, count, workers, blocking)
           pool = Concurrent::FixedThreadPool.new(count)
+          @instance_args = opts.delete(:instance_args) || nil
+          logger.info "Building #{count} workers with options: #{opts.inspect}, instance_args: #{@instance_args}"
           count.times do
-            eps = endpoints.dup
-            gps = groups.dup
-            pool.post { setup_worker(url, opts, eps, gps) }
+            pool.post { build_worker(url, opts, workers, blocking) }
           end
           pool
         end
 
+        # Builds a worker instance and sets it up with the NATS server.
+        #
+        # @param url [String] The URL of the NATS server.
+        # @param opts [Hash] Options for the NATS service.
+        # @param workers [Array] The array to store worker instances.
+        # @param blocking [Boolean] If true, blocks the current thread until the worker is set up.
+        #
+        # @return [void]
+        def build_worker(url, opts, workers, blocking)
+          worker = @instance_args ? new(*@instance_args) : new
+          workers << worker
+          return worker.setup_worker!(nats_url: url, service_opts: opts) if blocking
+
+          worker.setup_worker(nats_url: url, service_opts: opts)
+        end
+
+        # Shuts down the NATS API server gracefully.
+        #
+        # @param workers [Array] The array of worker instances to stop.
+        # @param pool [Concurrent::FixedThreadPool] The thread pool managing the worker threads.
+        #
+        # @return [Proc] A lambda that performs the shutdown operations.
+        def shutdown(workers, pool)
+          lambda do
+            logger.warn 'Draining worker subscriptions...'
+            workers.each(&:stop)
+            logger.warn 'All workers stopped, shutting down pool...'
+            pool.shutdown
+            logger.warn 'Pool is shut down, waiting for termination!'
+            pool.wait_for_termination
+            logger.warn 'Bye bye!'
+            wake_main_thread
+          end
+        end
+
+        # Sets up signal traps for graceful shutdown of the NATS API server.
+        #
+        # @param workers [Array] The array of worker instances to stop on signal.
+        # @param pool [Concurrent::FixedThreadPool] The thread pool managing the worker threads.
+        #
+        # @return [void]
+        def trap_signals(workers, pool)
+          return if @trapped
+
+          %w[INT TERM QUIT].each do |sig|
+            trap(sig) do
+              logger.warn "Received #{sig} signal, shutting down..."
+              Thread.new { shutdown(workers, pool).call }
+            end
+          end
+          @trapped = true
+        end
+
+        # Wakes up the main thread to allow it to continue execution after the server is stopped.
+        # This is useful when the server is running in a blocking mode.
+        # If the main thread is not blocked, this method does nothing.
+        #
+        # @return [void]
+        def wake_main_thread
+          Thread.main.wakeup
+        rescue ThreadError
+          nil
+        end
+      end
+
+      module InstanceMethods
+        # Returns the logger configured for the NATS API server.
+        def logger = self.class.logger
+
         # Sets up a worker thread for the NATS API server.
         # This method connects to the NATS server, adds the service, groups, and endpoints,
-        # and keeps the worker thread alive.
         #
         # @param url [String] The URL of the NATS server.
         # @param opts [Hash] Options for the NATS service.
@@ -112,63 +182,102 @@ module Rubyists
         # @param gps [Hash] The groups to add.
         #
         # @return [void]
-        def setup_worker(url, opts, eps, gps)
-          client  = NATS.connect url
-          service = client.services.add(**opts)
-          group_map = add_groups(service, gps)
-          add_endpoints service, eps, group_map
-          # Keep the worker thread alive
+        def setup_worker(nats_url: 'nats://localhost:4222', service_opts: {})
+          @thread  = Thread.current
+          @client  = NATS.connect nats_url
+          @service = @client.services.add(build_service_opts(service_opts:))
+          gps = self.class.groups.dup
+          eps = self.class.endpoints.dup
+          group_map = add_groups(gps)
+          add_endpoints eps, group_map
+        end
+
+        # Sets up a worker thread for the NATS API server and blocks the current thread.
+        #
+        # @see #setup_worker
+        def setup_worker!(nats_url: 'nats://localhost:4222', service_opts: {})
+          setup_worker(nats_url:, service_opts:)
           sleep
         end
 
+        # Stops the NATS API server worker.
+        def stop
+          @service&.stop
+          @client&.close
+          @thread&.wakeup
+        rescue ThreadError
+          nil
+        end
+
+        private
+
+        # Builds the service options for the NATS service.
+        #
+        # @param service_opts [Hash] Options for the NATS service.
+        #
+        # @return [Hash] The complete service options including name and version.
+        def build_service_opts(service_opts:)
+          {
+            name: self.class.name.split('::').join('.'),
+            version: '0.1.0',
+          }.merge(service_opts)
+        end
+
         # Adds groups to the NATS service.
         #
-        # @param service [NATS::Service] The NATS service to add groups to.
         # @param gps [Hash] The groups to add, where keys are group names and values are group definitions.
         #
         # @return [Hash] A map of group names to their created group objects.
-        def add_groups(service, gps)
+        def add_groups(gps)
           created = {}
-          gps.each_key { |name| build_group(service, gps, created, name) }
+          gps.each_key { |name| build_group(gps, created, name) }
           created
         end
 
         # Builds a group in the NATS service.
         #
-        # @param service [NATS::Service] The NATS service to add the group to.
         # @param defs [Hash] The group definitions, where keys are group names and values are group definitions.
         # @param cache [Hash] A cache to store already created groups.
         # @param name [String] The name of the group to build.
         #
         # @return [NATS::Group] The created group object.
-        def build_group(service, defs, cache, name)
+        def build_group(defs, cache, name)
           return cache[name] if cache.key?(name)
 
           gdef = defs[name]
           raise ArgumentError, "Group #{name} not defined" unless gdef
 
-          parent = gdef[:parent] ? build_group(service, defs, cache, gdef[:parent]) : service
+          parent = gdef[:parent] ? build_group(defs, cache, gdef[:parent]) : @service
           cache[name] = parent.groups.add(gdef[:name], queue: gdef[:queue])
         end
 
         # Adds endpoints to the NATS service.
         #
-        # @param service [NATS::Service] The NATS service to add endpoints to.
         # @param endpoints [Array<Hash>] The list of endpoints to add.
         # @param group_map [Hash] A map of group names to their created group objects.
         #
         # @return [void]
-        def add_endpoints(service, endpoints, group_map)
+        def add_endpoints(endpoints, group_map)
           endpoints.each do |ep|
-            parent = ep[:group] ? group_map[ep[:group]] : service
-            raise ArgumentError, "Group #{ep[:group]} not defined" if ep[:group] && parent.nil?
-
-            parent.endpoints.add(
-              ep[:name], subject: ep[:subject], queue: ep[:queue]
-            ) do |raw_msg|
-              wrapper = MessageWrapper.new(raw_msg)
-              dispatch_with_middleware(wrapper, ep[:handler])
-            end
+            grp = ep.group
+            parent = grp ? group_map[grp] : @service
+            raise ArgumentError, "Group #{grp} not defined" if grp && parent.nil?
+
+            build_endpoint(parent, ep)
+          end
+        end
+
+        # Builds an endpoint in the NATS service.
+        #
+        # @param parent [NATS::Group] The parent group or service to add the endpoint to.
+        # @param ept    [Endpoint]    The endpoint definition containing name, subject, queue, and handler.
+        #               NOTE: Named ept because `endpoint` is a DSL method we expose, to avoid confusion.
+        #
+        # @return [void]
+        def build_endpoint(parent, ept)
+          parent.endpoints.add(ept.name, subject: ept.subject, queue: ept.queue) do |raw_msg|
+            wrapper = MessageWrapper.new(raw_msg)
+            dispatch_with_middleware(wrapper, ept.handler)
           end
         end
 
@@ -180,7 +289,7 @@ module Rubyists
         # @return [void]
         def dispatch_with_middleware(wrapper, handler)
           app = ->(w) { handle_message(w.raw, handler) }
-          middleware.reverse_each do |(klass, args, blk)|
+          self.class.middleware.reverse_each do |(klass, args, blk)|
             app = klass.new(app, *args, &blk)
           end
           app.call(wrapper)
@@ -203,7 +312,6 @@ module Rubyists
 
         # Processes the result of the handler execution.
         #
-        #
         # @param wrapper [MessageWrapper] The message wrapper containing the raw message.
         # @param result [Dry::Monads::Result] The result of the handler execution.
         #

data/lib/leopard/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: leopard
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - bougyman
 bindir: exe
 cert_chain: []
-date: 2025-07-31 00:00:00.000000000 Z
+date: 2025-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -98,6 +98,7 @@ files:
 - ci/nats/accounts.txt
 - ci/nats/start.sh
 - ci/publish-gem.sh
+- doc/service-api-vs-rest.adoc
 - examples/echo_endpoint.rb
 - lib/leopard.rb
 - lib/leopard/errors.rb