leopard 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cb911c6ac11f486f56610fd734ae2a4e5187495d28524621d742fca976377eb
-  data.tar.gz: 713a3ea176a74f8a47abc83c4340a9432b781262b9fd5e431ada44991d9c2395
+  metadata.gz: 8407a7e14f98bddcfb36e679dead026ab8f809e8da6d4d25ca2b4cda32ff348e
+  data.tar.gz: 283df9d8c6e450f397fa68fbec41d19a9b52497046e39b7a60f4ee817c479060
 SHA512:
-  metadata.gz: ee37dc08e56cb6dc95262c0c61df02ad8f9fc2168cfff2c30fcf908dfb51c502676e796d00e2903bc9c8251d1d866b829579abce5fca3172336f1a74fb18b1a6
-  data.tar.gz: f09054e25ce41281175c0d09ccc993ec735f2c3278c9d631d964aa39850fc9fdfd54b08144c67df4d938079245f60a5da0079fda68fb209131f83384c8e421f8
+  metadata.gz: df9cae013a07f3478d9309b089db7a985e413963c5422e7c2cb6ee120adba4a40b1d7421320789c0e8e0a3afa6fdd496a1b32664990d2a4f166b177ca7686da3
+  data.tar.gz: 7072583f8e389016a2b1b6bdbe4aaddb2e32571730c205fbaee4c4fb73f9b78bd3099e57a8c87369f6e52193a4940b0a24d6bf9dca3bad32377671d79850c04f

data/.release-please-manifest.json

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

data/.version.txt

@@ -1 +1 @@
-0.1.5
+0.1.6

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/examples/echo_endpoint.rb

@@ -7,13 +7,21 @@ 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) }
 end
 
 if __FILE__ == $PROGRAM_NAME
   EchoService.run(
     nats_url: 'nats://localhost:4222',
-    service_opts: { name: 'example.echo', version: '1.0.0' },
+    service_opts: {
+      name: 'example.echo',
+      version: '1.0.0',
+      instance_args: [2],
+    },
     instances: 4,
   )
 end

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)
+          logger.info 'Setting up signal trap...'
+          trap_signals(workers, pool)
           return pool unless blocking
 
-          # Otherwise, just sleep the main thread forever
           sleep
         end
 
@@ -92,16 +92,86 @@ module Rubyists
         # @param count [Integer] The number of instances to spawn.
         #
         # @return [Concurrent::FixedThreadPool] The thread pool managing the worker threads.
-        def spawn_instances(url, opts, count)
+        def spawn_instances(url, opts, count, workers)
           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, eps, gps, workers) }
           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 workers [Array] The array to store worker instances.
+        #
+        # @return [void]
+        def build_worker(url, opts, eps, gps, workers)
+          worker = @instance_args ? new(*@instance_args) : new
+          workers << worker
+          worker.setup_worker(url, opts, eps, gps)
+        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.
@@ -113,62 +183,80 @@ module Rubyists
         #
         # @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
+          @thread  = Thread.current
+          @client  = NATS.connect url
+          @service = @client.services.add(**opts)
+          group_map = add_groups(gps)
+          add_endpoints eps, group_map
           sleep
         end
 
+        # Stops the NATS API server worker.
+        def stop
+          @service&.stop
+          @client&.close
+          @thread&.wakeup
+        rescue ThreadError
+          nil
+        end
+
+        private
+
         # 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 +268,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 +291,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.6'
     # 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.6
 platform: ruby
 authors:
 - bougyman
 bindir: exe
 cert_chain: []
-date: 2025-07-31 00:00:00.000000000 Z
+date: 2025-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby