shoryuken 7.0.2 → 7.0.4

data/lib/active_job/queue_adapters/shoryuken_adapter.rb

@@ -13,7 +13,7 @@ module ActiveJob
     # Shoryuken adapter for Active Job.
     # To use Shoryuken set the queue_adapter config to +:shoryuken+.
     #
-    # @example Rails configuration
+    # Example Rails configuration:
     #   Rails.application.config.active_job.queue_adapter = :shoryuken
 
     # Determine the appropriate base class based on Rails version
@@ -63,9 +63,8 @@ module ActiveJob
 
       # Indicates whether Shoryuken is in the process of shutting down.
       #
-      # This method is required for ActiveJob Continuations support (Rails 8.1+).
-      # When true, it signals to jobs that they should checkpoint their progress
-      # and gracefully interrupt execution to allow for resumption after restart.
+      # This method is required for ActiveJob Continuations support (Rails 8.1+). When true, it signals to jobs that they
+      # should checkpoint their progress and gracefully interrupt execution to allow for resumption after restart.
       #
       # @return [Boolean] true if Shoryuken is shutting down, false otherwise
       # @see https://github.com/rails/rails/pull/55127 Rails ActiveJob Continuations
@@ -177,9 +176,11 @@ module ActiveJob
           message_attributes: attributes.merge(MESSAGE_ATTRIBUTES)
         }
 
-        if queue.fifo?
+        if queue.fifo? && Shoryuken.active_job_fifo_message_deduplication?
           # See https://github.com/ruby-shoryuken/shoryuken/issues/457 and
           # https://github.com/ruby-shoryuken/shoryuken/pull/750#issuecomment-1781317929
+          # Disable via Shoryuken.active_job_fifo_message_deduplication = false when distinct
+          # enqueues of the same job class and arguments must not be silently deduplicated.
           msg[:message_deduplication_id] = Digest::SHA256.hexdigest(
             JSON.dump(body.except('job_id', 'enqueued_at'))
           )

data/lib/shoryuken/active_job/current_attributes.rb

@@ -11,7 +11,10 @@ module Shoryuken
     # This ensures that request-scoped context (like current user, tenant, locale)
     # automatically flows from the code that enqueues a job to the job's execution.
     #
-    # Based on Sidekiq's approach to persisting current attributes.
+    # Based on Sidekiq's approach to persisting current attributes, with one deliberate difference in cleanup: Sidekiq only
+    # touches the classes carried by a job and leaves the general reset to the Rails executor it runs jobs inside. Shoryuken
+    # does not run jobs inside that executor by default, so the loader resets every registered class after each job itself -
+    # see the note on {Loading#perform}.
     #
     # @example Setup in initializer
     #   require 'shoryuken/active_job/current_attributes'
@@ -58,8 +61,12 @@ module Shoryuken
         def persist(*klasses)
           @cattrs ||= {}
 
-          klasses.flatten.each_with_index do |klass, idx|
-            key = @cattrs.empty? ? 'cattr' : "cattr_#{idx}"
+          klasses.flatten.each do |klass|
+            # Key off the running registry size, not the per-call index, so that
+            # registering classes across separate persist calls still produces
+            # distinct keys (a per-call index restarts at 0 each call and would
+            # overwrite earlier registrations).
+            key = @cattrs.empty? ? 'cattr' : "cattr_#{@cattrs.size}"
             @cattrs[key] = klass.to_s
           end
 
@@ -109,13 +116,10 @@ module Shoryuken
         # @param hash [Hash] the deserialized job data
         # @return [void]
         def perform(sqs_msg, hash)
-          klasses_to_reset = []
-
           CurrentAttributes.cattrs&.each do |key, klass_name|
             next unless hash.key?(key)
 
             klass = klass_name.constantize
-            klasses_to_reset << klass
 
             begin
               attrs = Serializer.deserialize(hash[key])
@@ -131,7 +135,29 @@ module Shoryuken
 
           super
         ensure
-          klasses_to_reset.each(&:reset)
+          # Reset every registered CurrentAttributes class after the job - not
+          # only the ones whose key was in this message.
+          #
+          # Why unconditional (and why this differs from Sidekiq): Sidekiq's
+          # loader only touches classes present in the job and relies on the
+          # Rails executor - which it runs every job inside - to reset all
+          # CurrentAttributes between units of work. Shoryuken has no such safety
+          # net: it wraps a job in the reloader/executor only when
+          # `enable_reloading` is set, which is off by default, so nothing else
+          # clears CurrentAttributes between jobs.
+          #
+          # A blanket reset here is therefore the only thing guaranteeing a clean
+          # thread. Resetting only the present keys leaks whenever a value ends up
+          # set during a job whose message carried no cattr key - e.g. the worker
+          # (or code it calls) writes to Current, on a keyless message (empty
+          # context at enqueue, a different producer, or persist configured after
+          # the message was queued). CurrentAttributes are thread-local and the
+          # pool reuses threads, so that value would surface in the next job.
+          CurrentAttributes.cattrs&.each_value do |klass_name|
+            klass_name.constantize.reset
+          rescue => e
+            Shoryuken.logger.warn("Failed to reset CurrentAttributes #{klass_name}: #{e.message}")
+          end
         end
       end
     end

data/lib/shoryuken/body_parser.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Shoryuken
-  # Parses SQS message bodies according to worker configuration.
-  # Supports JSON parsing, text extraction, custom Procs, and
+  # Parses SQS message bodies according to worker configuration. Supports JSON parsing, text extraction, custom Procs, and
   # any object that responds to parse or load methods.
   class BodyParser
     class << self

data/lib/shoryuken/client.rb

@@ -4,16 +4,22 @@ module Shoryuken
   # Client class for interacting with SQS queues.
   # Provides a simple interface for accessing and managing queue instances.
   class Client
-    # @return [Hash{String => Shoryuken::Queue}] cached queue instances by name
+    # Cached queue instances by name (Hash{String => Shoryuken::Queue}).
     @@queues = {}
 
+    # Guards the queue cache. queues is called concurrently from the dispatch
+    # thread, processor-completion threads and worker threads, and building a
+    # Shoryuken::Queue makes SQS API calls, so an unsynchronized `||=` would let
+    # several callers build the same queue (and corrupt the hash on JRuby).
+    @@queues_mutex = Mutex.new
+
     class << self
       # Returns a Queue instance for the given queue name
       #
       # @param name [String, Symbol] the name of the queue
       # @return [Shoryuken::Queue] the queue instance
       def queues(name)
-        @@queues[name.to_s] ||= Shoryuken::Queue.new(sqs, name)
+        @@queues_mutex.synchronize { @@queues[name.to_s] ||= Shoryuken::Queue.new(sqs, name) }
       end
 
       # Returns the current SQS client
@@ -29,10 +35,13 @@ module Shoryuken
       # @return [Aws::SQS::Client] the SQS client
       def sqs=(sqs)
         # Since the @@queues values (Shoryuken::Queue objects) are built referencing @@sqs, if it changes, we need to
-        #   re-build them on subsequent calls to `.queues(name)`.
-        @@queues = {}
-
-        Shoryuken.sqs_client = sqs
+        #   re-build them on subsequent calls to `.queues(name)`. Swap the client and reset the cache inside the same
+        #   critical section: otherwise a concurrent `queues` call could slip between the reset and the assignment,
+        #   read the old client, and cache a queue built with it that survives the replacement.
+        @@queues_mutex.synchronize do
+          Shoryuken.sqs_client = sqs
+          @@queues = {}
+        end
       end
     end
   end

data/lib/shoryuken/default_exception_handler.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 module Shoryuken
-  # Default exception handler that logs errors during message processing.
-  # Implements a simple error logging strategy that outputs the exception
-  # message and backtrace to the configured logger.
+  # Default exception handler that logs errors during message processing. Implements a simple error logging strategy that
+  # outputs the exception message and backtrace to the configured logger.
   class DefaultExceptionHandler
     extend Util
 

data/lib/shoryuken/errors.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Shoryuken
-  # Namespace for all Shoryuken-specific errors.
-  # These provide more meaningful error types than generic Ruby exceptions,
+  # Namespace for all Shoryuken-specific errors. These provide more meaningful error types than generic Ruby exceptions,
   # making it easier to rescue and handle specific failure cases.
   module Errors
     # Base class for all Shoryuken errors
@@ -14,8 +13,7 @@ module Shoryuken
     # Raised when a specified SQS queue does not exist or cannot be accessed
     QueueNotFoundError = Class.new(BaseError)
 
-    # Raised when worker registration fails due to conflicts
-    # (e.g., registering multiple workers for a batch queue)
+    # Raised when worker registration fails due to conflicts (e.g., registering multiple workers for a batch queue)
     InvalidWorkerRegistrationError = Class.new(BaseError)
 
     # Raised when an invalid polling strategy is specified

data/lib/shoryuken/fetcher.rb

@@ -72,12 +72,18 @@ module Shoryuken
 
       shoryuken_queue = Shoryuken::Client.queues(queue.name)
 
-      options[:max_number_of_messages]  = max_number_of_messages(shoryuken_queue, limit, options)
       options[:message_attribute_names] = %w[All]
       options[:attribute_names]         = %w[All]
 
+      # Merge per-queue options BEFORE computing the cap so the FIFO
+      # one-at-a-time guard (and FETCH_LIMIT) always win. Computing the cap last
+      # means a queue option of max_number_of_messages can only lower the count,
+      # never raise a non-batch FIFO queue above 1 - which would let SQS return
+      # several messages from the same group and break ordering.
       options.merge!(queue.options)
 
+      options[:max_number_of_messages] = max_number_of_messages(shoryuken_queue, limit, options)
+
       shoryuken_queue.receive_messages(options)
     end
 

data/lib/shoryuken/helpers/atomic_counter.rb

@@ -4,13 +4,11 @@ module Shoryuken
   module Helpers
     # A thread-safe counter implementation using Ruby's Mutex.
     #
-    # This class provides atomic operations for incrementing, decrementing, and reading
-    # integer values in a thread-safe manner. It serves as a drop-in replacement for
-    # Concurrent::AtomicFixnum without requiring external dependencies.
+    # This class provides atomic operations for incrementing, decrementing, and reading integer values in a thread-safe
+    # manner. It serves as a drop-in replacement for Concurrent::AtomicFixnum without requiring external dependencies.
     #
-    # The implementation uses a Mutex to ensure thread safety across all Ruby
-    # implementations including JRuby, where true parallelism makes atomic operations
-    # critical for data integrity.
+    # The implementation uses a Mutex to ensure thread safety across all Ruby implementations including JRuby, where true
+    # parallelism makes atomic operations critical for data integrity.
     #
     # @note This class is optimized for scenarios with frequent atomic updates
     #   and occasional reads, such as tracking active worker counts.
@@ -82,9 +80,8 @@ module Shoryuken
 
       # Atomically decrements the counter by 1 and returns the new value.
       #
-      # This operation is thread-safe and can be called concurrently from
-      # multiple threads without risk of data corruption or lost updates.
-      # The counter can go negative if decremented below zero.
+      # This operation is thread-safe and can be called concurrently from multiple threads without risk of data corruption or
+      # lost updates. The counter can go negative if decremented below zero.
       #
       # @return [Integer] The new counter value after decrementing
       #

data/lib/shoryuken/helpers/atomic_hash.rb

@@ -4,14 +4,12 @@ module Shoryuken
   module Helpers
     # A thread-safe hash implementation using Ruby's Mutex for all operations.
     #
-    # This class provides a hash-like interface with thread-safe operations, serving as a
-    # drop-in replacement for Concurrent::Hash without requiring external dependencies.
-    # The implementation uses a single mutex to protect both read and write operations,
-    # ensuring complete thread safety across all Ruby implementations including JRuby.
+    # This class provides a hash-like interface with thread-safe operations, serving as a drop-in replacement for
+    # Concurrent::Hash without requiring external dependencies. The implementation uses a single mutex to protect both read
+    # and write operations, ensuring complete thread safety across all Ruby implementations including JRuby.
     #
-    # Since hash operations (lookup, assignment) are very fast, the mutex overhead is
-    # minimal while providing guaranteed safety and simplicity. This approach avoids
-    # the complexity of copy-on-write while maintaining excellent performance for
+    # Since hash operations (lookup, assignment) are very fast, the mutex overhead is minimal while providing guaranteed
+    # safety and simplicity. This approach avoids the complexity of copy-on-write while maintaining excellent performance for
     # typical usage patterns.
     #
     # @note This implementation uses mutex synchronization for all operations,
@@ -52,8 +50,7 @@ module Shoryuken
     class AtomicHash
       # Creates a new empty atomic hash.
       #
-      # The hash starts empty and ready to accept key-value pairs through
-      # thread-safe operations.
+      # The hash starts empty and ready to accept key-value pairs through thread-safe operations.
       #
       # @return [AtomicHash] A new empty atomic hash instance
       #
@@ -67,8 +64,7 @@ module Shoryuken
 
       # Returns the value associated with the given key.
       #
-      # This operation is thread-safe and will return a consistent value
-      # even when called concurrently with write operations.
+      # This operation is thread-safe and will return a consistent value even when called concurrently with write operations.
       #
       # @param key [Object] The key to look up
       # @return [Object, nil] The value associated with the key, or nil if not found
@@ -115,8 +111,7 @@ module Shoryuken
 
       # Removes all key-value pairs from the hash.
       #
-      # This is a thread-safe write operation that ensures atomicity
-      # when called concurrently with other operations.
+      # This is a thread-safe write operation that ensures atomicity when called concurrently with other operations.
       #
       # @return [Hash] An empty hash (for compatibility with standard Hash#clear)
       #
@@ -154,8 +149,7 @@ module Shoryuken
 
       # Returns the value for the given key, or a default value if the key is not found.
       #
-      # This operation is thread-safe and will return a consistent value
-      # even when called concurrently with write operations.
+      # This operation is thread-safe and will return a consistent value even when called concurrently with write operations.
       #
       # @param key [Object] The key to look up
       # @param default [Object] The value to return if the key is not found

data/lib/shoryuken/helpers/hash_utils.rb

@@ -4,10 +4,9 @@ module Shoryuken
   module Helpers
     # Utility methods for hash manipulation.
     #
-    # This module provides helper methods for common hash operations that were
-    # previously implemented as core class extensions. By using a dedicated
-    # helper module, we avoid polluting the global namespace while maintaining
-    # the same functionality.
+    # This module provides helper methods for common hash operations that were previously implemented as core class
+    # extensions. By using a dedicated helper module, we avoid polluting the global namespace while maintaining the same
+    # functionality.
     #
     # @example Basic usage
     #   hash = { 'key1' => 'value1', 'key2' => { 'nested' => 'value2' } }
@@ -17,9 +16,8 @@ module Shoryuken
       class << self
         # Recursively converts hash keys to symbols.
         #
-        # This method traverses a hash structure and converts all string keys
-        # to symbols, including nested hashes. Non-hash values are left unchanged.
-        # This is useful for normalizing configuration data loaded from YAML files.
+        # This method traverses a hash structure and converts all string keys to symbols, including nested hashes. Non-hash
+        # values are left unchanged. This is useful for normalizing configuration data loaded from YAML files.
         #
         # @param hash [Hash, Object] The hash to convert, or any other object
         # @return [Hash, Object] Hash with symbolized keys, or the original object if not a hash

data/lib/shoryuken/helpers/string_utils.rb

@@ -4,10 +4,9 @@ module Shoryuken
   module Helpers
     # Utility methods for string manipulation.
     #
-    # This module provides helper methods for common string operations that were
-    # previously implemented as core class extensions. By using a dedicated
-    # helper module, we avoid polluting the global namespace while maintaining
-    # the same functionality.
+    # This module provides helper methods for common string operations that were previously implemented as core class
+    # extensions. By using a dedicated helper module, we avoid polluting the global namespace while maintaining the same
+    # functionality.
     #
     # @example Basic usage
     #   klass = Shoryuken::Helpers::StringUtils.constantize('MyWorker')
@@ -16,10 +15,9 @@ module Shoryuken
       class << self
         # Converts a string to a constant.
         #
-        # This method takes a string representation of a constant name and returns
-        # the actual constant. It handles nested constants (e.g., 'Foo::Bar') and
-        # leading double colons (e.g., '::Object'). This is commonly used for
-        # dynamically loading worker classes from configuration.
+        # This method takes a string representation of a constant name and returns the actual constant. It handles nested
+        # constants (e.g., 'Foo::Bar') and leading double colons (e.g., '::Object'). This is commonly used for dynamically
+        # loading worker classes from configuration.
         #
         # @param string [String] The string to convert to a constant
         # @return [Class, Module] The constant represented by the string

data/lib/shoryuken/helpers/timer_task.rb

@@ -42,14 +42,21 @@ module Shoryuken
       #
       # @return [Boolean] true if killed, false if already killed
       def kill
+        thread_to_kill = nil
+
         @mutex.synchronize do
           return false if @killed
 
           @killed = true
           @running = false
-
-          @thread.kill if @thread&.alive?
+          thread_to_kill = @thread
         end
+
+        # Kill the thread AFTER releasing the mutex. The timer loop's ensure
+        # block calls @mutex.synchronize to clear @running; killing the thread
+        # while holding that mutex deadlocks on Ruby 3.2, where Thread#kill
+        # yields the GVL to the killed thread for cleanup before returning.
+        thread_to_kill&.kill if thread_to_kill&.alive?
         true
       end
 
@@ -59,6 +66,16 @@ module Shoryuken
       #
       # @return [void]
       def run_timer_loop
+        # The timer thread inherits the priority of the thread that called
+        # #execute. Shoryuken runs workers at a lowered priority
+        # (Shoryuken.thread_priority, default -1) and starts the
+        # auto-visibility-extension timer from inside that worker thread, so the
+        # timer would otherwise inherit -1. A latency-sensitive timer must not
+        # run below normal priority: under CPU contention a delayed extension can
+        # miss the visibility timeout and let the message be redelivered (double
+        # processed). Reset to normal priority.
+        Thread.current.priority = 0
+
         until @killed
           sleep(@execution_interval)
           break if @killed

data/lib/shoryuken/inline_message.rb

@@ -3,10 +3,9 @@
 module Shoryuken
   # A high-performance alternative to OpenStruct for representing SQS messages.
   #
-  # InlineMessage is a Struct-based implementation that provides the same interface
-  # as the previous OpenStruct-based message representation but with significantly
-  # better performance characteristics. It contains all the essential attributes
-  # needed to represent an Amazon SQS message within the Shoryuken framework.
+  # InlineMessage is a Struct-based implementation that provides the same interface as the previous OpenStruct-based message
+  # representation but with significantly better performance characteristics. It contains all the essential attributes needed
+  # to represent an Amazon SQS message within the Shoryuken framework.
   InlineMessage = Struct.new(
     :body,
     :attributes,

data/lib/shoryuken/launcher.rb

@@ -14,9 +14,8 @@ module Shoryuken
 
     # Indicates whether the launcher is in the process of stopping.
     #
-    # This flag is set to true when either {#stop} or {#stop!} is called,
-    # and is used by ActiveJob adapters to signal jobs that they should
-    # checkpoint and prepare for graceful shutdown.
+    # This flag is set to true when either {#stop} or {#stop!} is called, and is used by ActiveJob adapters to signal jobs
+    # that they should checkpoint and prepare for graceful shutdown.
     #
     # @return [Boolean] true if stopping, false otherwise
     def stopping?
@@ -43,8 +42,7 @@ module Shoryuken
       # Don't await here so the timeout below is not delayed
       stop_new_dispatching
 
-      executor.shutdown
-      executor.kill unless executor.wait_for_termination(Shoryuken.options[:timeout])
+      shutdown_executor
 
       fire_event(:stopped)
     end
@@ -61,8 +59,7 @@ module Shoryuken
       stop_new_dispatching
       await_dispatching_in_progress
 
-      executor.shutdown
-      executor.wait_for_termination
+      shutdown_executor
 
       fire_event(:stopped)
     end
@@ -93,11 +90,25 @@ module Shoryuken
       @managers.each(&:await_dispatching_in_progress)
     end
 
+    # Shuts the executor down, giving in-flight workers up to the configured timeout to finish before force-killing them so
+    # the process can exit. Used by both the graceful ({#stop}) and immediate ({#stop!}) shutdowns: a graceful stop still
+    # waits for workers, but must not block forever on a hung one.
+    #
+    # @return [void]
+    def shutdown_executor
+      executor.shutdown
+      executor.kill unless executor.wait_for_termination(Shoryuken.options[:timeout])
+    end
+
     # Returns the executor for running async operations
     #
+    # Owns a dedicated executor rather than borrowing Concurrent.global_io_executor: {#stop} and {#stop!} shut down and kill
+    # this executor, and destroying the process-global pool would break anything else relying on it (including Shoryuken's
+    # own ShoryukenConcurrentSendAdapter) and prevent a fresh launcher from starting in the same process.
+    #
     # @return [Concurrent::ExecutorService] the executor service
     def executor
-      @_executor ||= Shoryuken.launcher_executor || Concurrent.global_io_executor
+      @_executor ||= Shoryuken.launcher_executor || Concurrent::CachedThreadPool.new(auto_terminate: true)
     end
 
     # Starts all managers in parallel futures

data/lib/shoryuken/manager.rb

@@ -32,6 +32,7 @@ module Shoryuken
       @executor                   = executor
       @running                    = Shoryuken::Helpers::AtomicBoolean.new(true)
       @stop_new_dispatching       = Shoryuken::Helpers::AtomicBoolean.new(false)
+      @dispatch_started           = Shoryuken::Helpers::AtomicBoolean.new(false)
       @dispatching_release_signal = ::Queue.new
     end
 
@@ -48,6 +49,14 @@ module Shoryuken
     # @return [void]
     def stop_new_dispatching
       @stop_new_dispatching.make_true
+
+      # If the dispatch loop never ran (e.g. a stop arrives before the start
+      # Future is scheduled, or in an embedded host whose executor is
+      # saturated), there is no loop to observe the flag and close the release
+      # signal, so await_dispatching_in_progress would block forever. Close it
+      # here in that case. Queue#close is idempotent, so a dispatch_loop that
+      # does start later and closes it again is harmless.
+      @dispatching_release_signal.close unless @dispatch_started.true?
     end
 
     # Waits for any in-progress dispatching to complete
@@ -57,6 +66,9 @@ module Shoryuken
       # There might still be a dispatching on-going, as the response from SQS could take some time
       # We don't want to stop the process before processing incoming messages, as they would stay "in-flight" for some time on SQS
       # We use a queue, as the dispatch_loop is running on another thread, and this is a efficient way of communicating between threads.
+      # The dispatch loop closes the queue when it observes the stop flag; pop on a closed queue
+      # returns immediately, so this stays safe when stop is requested more than once
+      # (e.g. TSTP followed by USR1, which both trigger a graceful stop).
       @dispatching_release_signal.pop
     end
 
@@ -73,12 +85,29 @@ module Shoryuken
     #
     # @return [void]
     def dispatch_loop
+      # Mark that the loop has run at least once so stop_new_dispatching knows
+      # it can rely on the loop to close the release signal (and otherwise
+      # closes it itself to avoid a deadlock).
+      @dispatch_started.make_true
+
       if @stop_new_dispatching.true? || !running?
-        @dispatching_release_signal << 1
+        # Close (instead of push) so every pending and future
+        # await_dispatching_in_progress call returns, not just the first one
+        @dispatching_release_signal.close
         return
       end
 
       @executor.post { dispatch }
+    rescue Concurrent::RejectedExecutionError
+      # The executor was shut down between the running? check and the post
+      # (e.g. a hard stop racing the dispatch loop); release any waiters as
+      # the dispatch chain ends here
+      @dispatching_release_signal.close
+    rescue StandardError
+      # Unexpected error from post (e.g. ThreadError if the OS thread limit is
+      # hit); the dispatch chain ends here so release waiters before re-raising
+      @dispatching_release_signal.close
+      raise
     end
 
     # Dispatches messages from a queue
@@ -129,13 +158,20 @@ module Shoryuken
       return unless @polling_strategy.respond_to?(:message_processed)
 
       @polling_strategy.message_processed(queue)
+    rescue => e
+      # Swallow (but log) failures from the SQS lookups or the strategy callback:
+      # the busy counter was already decremented above and the caller's ensure
+      # must not run completion twice
+      logger.error { "Processor completion failed for #{queue}: #{e.message}" }
+      logger.debug { e.backtrace.join("\n") } unless e.backtrace.nil?
     end
 
     # Assigns a message to a processor
     #
     # @param queue_name [String] the queue name
     # @param sqs_msg [Aws::SQS::Types::Message, Array<Aws::SQS::Types::Message>] the message or batch
-    # @return [Concurrent::Promise, nil] the processing promise or nil if not running
+    # @return [Concurrent::Promise, nil] the processing promise, or nil if the manager
+    #   is not running or the executor rejects the worker post
     def assign(queue_name, sqs_msg)
       return unless running?
 
@@ -144,6 +180,11 @@ module Shoryuken
       @busy_processors.increment
       fire_utilization_update_event
 
+      # Completion runs in an ensure so it executes exactly once whether
+      # processing succeeds or raises. The previous `.then { processor_done }
+      # .rescue { processor_done }` chain ran completion twice when
+      # processor_done itself raised, double decrementing the busy counter
+      # and silently breaking the concurrency limit
       Concurrent::Promise
         .execute(executor: @executor) do
           original_priority = Thread.current.priority
@@ -152,10 +193,20 @@ module Shoryuken
             Processor.process(queue_name, sqs_msg)
           ensure
             Thread.current.priority = original_priority
+            processor_done(queue_name)
           end
         end
-        .then { processor_done(queue_name) }
-        .rescue { processor_done(queue_name) }
+    rescue Concurrent::RejectedExecutionError
+      # The executor was shut down (or a bounded custom launcher_executor is
+      # saturated) between the running? check above and the post. The promise
+      # body - and therefore processor_done - never ran, so roll back the
+      # increment here. Leaking it would permanently shrink `ready`
+      # (@max_processors - busy) until dispatch stalls and the group stops
+      # processing. The message was never processed, so we must not run the
+      # FIFO message_processed callback - decrement directly instead.
+      @busy_processors.decrement
+      fire_utilization_update_event
+      nil
     end
 
     # Dispatches a batch of messages from a queue
@@ -208,9 +259,17 @@ module Shoryuken
       logger.error { "Manager failed: #{ex.message}" }
       logger.error { ex.backtrace.join("\n") } unless ex.backtrace.nil?
 
-      Process.kill('USR1', Process.pid)
-
+      # Stop this manager first so Launcher#healthy? surfaces the failure to
+      # whoever is supervising us (the CLI Runner, or an embedding application).
       @running.make_false
+
+      # In server (CLI) mode the Runner traps USR1 and turns it into a graceful
+      # shutdown of the whole process, so a process supervisor can restart us.
+      # When embedded (no Runner), USR1 keeps its default disposition and would
+      # terminate the host process - and any in-flight workers - so we must not
+      # send it. The stopped manager above is enough for Launcher#healthy? to
+      # report the failure to the embedding application.
+      Process.kill('USR1', Process.pid) if Shoryuken.server?
     end
 
     # Fires a utilization update event

data/lib/shoryuken/message.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 module Shoryuken
-  # Represents an SQS message received by a Shoryuken worker.
-  # This class wraps the raw AWS SQS message data and provides convenient methods
-  # for interacting with the message, including deletion and visibility timeout management.
+  # Represents an SQS message received by a Shoryuken worker. This class wraps the raw AWS SQS message data and provides
+  # convenient methods for interacting with the message, including deletion and visibility timeout management.
   #
   # Message instances are automatically created by Shoryuken and passed to your
   # worker's `perform` method as the first argument.