leopard 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8407a7e14f98bddcfb36e679dead026ab8f809e8da6d4d25ca2b4cda32ff348e
-  data.tar.gz: 283df9d8c6e450f397fa68fbec41d19a9b52497046e39b7a60f4ee817c479060
+  metadata.gz: 550ad9a639b0f8caf0989990853c1ab49428f4f48c0b28a6fdc30c30d8450a03
+  data.tar.gz: 0b2fdc7d99a23fe156b446b724407eedb074806d989542f42af4ff63d74744c7
 SHA512:
-  metadata.gz: df9cae013a07f3478d9309b089db7a985e413963c5422e7c2cb6ee120adba4a40b1d7421320789c0e8e0a3afa6fdd496a1b32664990d2a4f166b177ca7686da3
-  data.tar.gz: 7072583f8e389016a2b1b6bdbe4aaddb2e32571730c205fbaee4c4fb73f9b78bd3099e57a8c87369f6e52193a4940b0a24d6bf9dca3bad32377671d79850c04f
+  metadata.gz: 68cc478abf3538e4d567fe170fa72340632ac056608d16aa1dc426842c2c9de3fbb6001ac8c75058a43d41558d625fbe31ad52104d54d5c33f5363b5d84d1f7e
+  data.tar.gz: 9b9769a6a7c5eeadc28424f530fef164cd6ed558f1fb975afbecbefb01d96c10428bf653fddf3a6840072fe02b89a6b15eee121f55e9bf5cbd01b0e56aee1a69

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.6"
+  ".": "0.2.0"
 }

data/.version.txt

@@ -1 +1 @@
-0.1.6
+0.2.0

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.2.0](https://github.com/rubyists/leopard/compare/v0.1.7...v0.2.0) (2025-08-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* Big move to use kwargs as the initializer for classes which include us ([#28](https://github.com/rubyists/leopard/issues/28))
+
+### Bug Fixes
+
+* Big move to use kwargs as the initializer for classes which include us ([#28](https://github.com/rubyists/leopard/issues/28)) ([72293b4](https://github.com/rubyists/leopard/commit/72293b434998679fe3ff2d467a6a39c11a325b5a))
+
+## [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)
 
 

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,11 +7,12 @@ require_relative '../lib/leopard/nats_api_server'
 class EchoService
   include Rubyists::Leopard::NatsApiServer
 
-  def initialize(a_var = 1)
+  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
@@ -20,8 +21,8 @@ if __FILE__ == $PROGRAM_NAME
     service_opts: {
       name: 'example.echo',
       version: '1.0.0',
-      instance_args: [2],
+      instance_args: { a_var: 2 },
     },
-    instances: 4,
+    instances: 1,
   )
 end

data/lib/leopard/message_wrapper.rb

@@ -10,10 +10,11 @@ module Rubyists
       #
       # @!attribute [r] data
       # @return [Object] The parsed data from the NATS message.
+      attr_reader :raw, :data
       #
-      # @!attribute [r] headers
+      # @!attribute [w] headers
       # @return [Hash] The headers from the NATS message.
-      attr_reader :raw, :data, :headers
+      attr_accessor :headers
 
       # @param nats_msg [NATS::Message] The NATS message to wrap.
       def initialize(nats_msg)
@@ -26,15 +27,15 @@ module Rubyists
       #
       # @return [void]
       def respond(payload)
+        raw.header = headers unless headers.empty?
         raw.respond(serialize(payload))
       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

@@ -75,7 +75,7 @@ module Rubyists
         def run(nats_url:, service_opts:, instances: 1, blocking: true)
           logger.info 'Booting NATS API server...'
           workers = Concurrent::Array.new
-          pool = spawn_instances(nats_url, service_opts, instances, workers)
+          pool = spawn_instances(nats_url, service_opts, instances, workers, blocking)
           logger.info 'Setting up signal trap...'
           trap_signals(workers, pool)
           return pool unless blocking
@@ -90,33 +90,37 @@ 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, workers)
+        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}"
+          raise ArgumentError, 'instance_args must be a Hash' if @instance_args && !@instance_args.is_a?(Hash)
+
           count.times do
-            eps = endpoints.dup
-            gps = groups.dup
-            pool.post { build_worker(url, opts, eps, gps, workers) }
+            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 eps [Array<Hash>] The list of endpoints to add.
-        # @param gps [Hash] The groups to add.
+        # @param nats_url [String] The URL of the NATS server.
+        # @param service_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, eps, gps, workers)
-          worker = @instance_args ? new(*@instance_args) : new
+        def build_worker(nats_url, service_opts, workers, blocking)
+          worker = @instance_args ? new(**@instance_args) : new
           workers << worker
-          worker.setup_worker(url, opts, eps, gps)
+          args = { nats_url:, service_opts: }
+          return worker.setup_worker!(**args) if blocking
+
+          worker.setup_worker(**args)
         end
 
         # Shuts down the NATS API server gracefully.
@@ -174,7 +178,6 @@ module Rubyists
 
         # 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.
@@ -182,12 +185,21 @@ module Rubyists
         # @param gps [Hash] The groups to add.
         #
         # @return [void]
-        def setup_worker(url, opts, eps, gps)
+        def setup_worker(nats_url: 'nats://localhost:4222', service_opts: {})
           @thread  = Thread.current
-          @client  = NATS.connect url
-          @service = @client.services.add(**opts)
+          @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
 
@@ -202,6 +214,18 @@ module Rubyists
 
         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 gps [Hash] The groups to add, where keys are group names and values are group definitions.

data/lib/leopard/version.rb

@@ -3,7 +3,7 @@
 module Rubyists
   module Leopard
     # x-release-please-start-version
-    VERSION = '0.1.6'
+    VERSION = '0.2.0'
     # 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.6
+  version: 0.2.0
 platform: ruby
 authors:
 - bougyman
 bindir: exe
 cert_chain: []
-date: 2025-08-03 00:00:00.000000000 Z
+date: 2025-08-07 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