shoryuken 7.0.0.alpha2 → 7.0.0

data/lib/shoryuken/middleware/entry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Middleware
+    # Represents an entry in a middleware chain, storing the middleware class
+    # and any arguments needed for its instantiation.
+    #
+    # @api private
+    class Entry
+      # @return [Class] The middleware class this entry represents
+      attr_reader :klass
+
+      # Creates a new middleware entry.
+      #
+      # @param klass [Class] The middleware class
+      # @param args [Array] Arguments to pass to the middleware constructor
+      def initialize(klass, *args)
+        @klass = klass
+        @args  = args
+      end
+
+      # Creates a new instance of the middleware class with the stored arguments.
+      #
+      # @return [Object] A new instance of the middleware class
+      def make_new
+        @klass.new(*@args)
+      end
+    end
+  end
+end

data/lib/shoryuken/middleware/server/active_record.rb

@@ -2,8 +2,16 @@
 
 module Shoryuken
   module Middleware
+    # Server-side middleware that runs around message processing
     module Server
+      # Middleware that clears ActiveRecord connections after message processing.
+      # Ensures database connections are returned to the pool after each job.
       class ActiveRecord
+        # Processes a message and clears database connections afterwards
+        #
+        # @param _args [Array<Object>] middleware call arguments (unused)
+        # @yield continues to the next middleware in the chain
+        # @return [Object] return value from the next middleware or worker in the chain
         def call(*_args)
           yield
         ensure

data/lib/shoryuken/middleware/server/auto_delete.rb

@@ -3,7 +3,17 @@
 module Shoryuken
   module Middleware
     module Server
+      # Middleware that automatically deletes messages after successful processing.
+      # Only deletes messages when the worker has auto_delete enabled.
       class AutoDelete
+        # Processes a message and deletes it if auto_delete is enabled
+        #
+        # @param worker [Object] the worker instance
+        # @param queue [String] the queue name
+        # @param sqs_msg [Shoryuken::Message, Array<Shoryuken::Message>] the message or batch
+        # @param _body [Object] the parsed message body (unused)
+        # @yield continues to the next middleware in the chain
+        # @return [void]
         def call(worker, queue, sqs_msg, _body)
           yield
 

data/lib/shoryuken/middleware/server/auto_extend_visibility.rb

@@ -3,11 +3,22 @@
 module Shoryuken
   module Middleware
     module Server
+      # Middleware that automatically extends message visibility timeout during processing.
+      # Prevents messages from becoming visible to other consumers while still being processed.
       class AutoExtendVisibility
         include Util
 
+        # Number of seconds before timeout to extend visibility
         EXTEND_UPFRONT_SECONDS = 5
 
+        # Processes a message with automatic visibility timeout extension
+        #
+        # @param worker [Object] the worker instance
+        # @param queue [String] the queue name
+        # @param sqs_msg [Shoryuken::Message, Array<Shoryuken::Message>] the message or batch
+        # @param body [Object] the parsed message body
+        # @yield continues to the next middleware in the chain
+        # @return [void]
         def call(worker, queue, sqs_msg, body)
           return yield unless worker.class.auto_visibility_timeout?
 
@@ -24,13 +35,21 @@ module Shoryuken
 
         private
 
+        # Helper class for extending message visibility
         class MessageVisibilityExtender
           include Util
 
+          # Creates a timer task that extends message visibility
+          #
+          # @param _worker [Object] the worker instance (unused)
+          # @param queue [String] the queue name
+          # @param sqs_msg [Shoryuken::Message] the message
+          # @param _body [Object] the parsed message body (unused)
+          # @return [Shoryuken::Helpers::TimerTask] the timer task
           def auto_extend(_worker, queue, sqs_msg, _body)
             queue_visibility_timeout = Shoryuken::Client.queues(queue).visibility_timeout
 
-            Concurrent::TimerTask.new(execution_interval: queue_visibility_timeout - EXTEND_UPFRONT_SECONDS) do
+            Shoryuken::Helpers::TimerTask.new(execution_interval: queue_visibility_timeout - EXTEND_UPFRONT_SECONDS) do
               logger.debug do
                 "Extending message #{queue}/#{sqs_msg.message_id} visibility timeout by #{queue_visibility_timeout}s"
               end
@@ -44,6 +63,13 @@ module Shoryuken
           end
         end
 
+        # Creates and starts a visibility extension timer
+        #
+        # @param worker [Object] the worker instance
+        # @param queue [String] the queue name
+        # @param sqs_msg [Shoryuken::Message] the message
+        # @param body [Object] the parsed message body
+        # @return [Shoryuken::Helpers::TimerTask] the started timer
         def auto_visibility_timer(worker, queue, sqs_msg, body)
           MessageVisibilityExtender.new.auto_extend(worker, queue, sqs_msg, body).tap(&:execute)
         end

data/lib/shoryuken/middleware/server/exponential_backoff_retry.rb

@@ -3,9 +3,22 @@
 module Shoryuken
   module Middleware
     module Server
+      # Middleware that implements exponential backoff retry for failed messages.
+      # When a job fails, the message visibility timeout is adjusted based on
+      # configured retry intervals.
       class ExponentialBackoffRetry
         include Util
 
+        # Processes a message with exponential backoff retry on failure
+        #
+        # @param worker [Object] the worker instance
+        # @param _queue [String] the queue name (unused)
+        # @param sqs_msg [Shoryuken::Message, Array<Shoryuken::Message>] the message or batch
+        # @param _body [Object] the parsed message body (unused)
+        # @yield continues to the next middleware in the chain
+        # @return [void]
+        # @raise [StandardError] re-raises the original exception if retry intervals are not configured
+        #   or if retry limit is exceeded
         def call(worker, _queue, sqs_msg, _body)
           return yield unless worker.class.exponential_backoff?
 
@@ -32,6 +45,11 @@ module Shoryuken
 
         private
 
+        # Gets the retry interval for a given attempt number
+        #
+        # @param retry_intervals [Array<Integer>, #call] the configured intervals or callable
+        # @param attempts [Integer] the current attempt number
+        # @return [Integer, nil] the interval in seconds or nil
         def get_interval(retry_intervals, attempts)
           return retry_intervals.call(attempts) if retry_intervals.respond_to?(:call)
 
@@ -42,12 +60,23 @@ module Shoryuken
           end
         end
 
+        # Calculates the next visibility timeout capped at SQS maximum
+        #
+        # @param interval [Integer] the desired interval
+        # @param started_at [Time] when processing started
+        # @return [Integer] the capped visibility timeout
         def next_visibility_timeout(interval, started_at)
           max_timeout = 43_200 - (Time.now - started_at).ceil - 1
           interval = max_timeout if interval > max_timeout
           interval.to_i
         end
 
+        # Handles a message failure by adjusting visibility timeout
+        #
+        # @param sqs_msg [Shoryuken::Message] the failed message
+        # @param started_at [Time] when processing started
+        # @param retry_intervals [Array<Integer>, #call] the configured intervals
+        # @return [Boolean] true if retry was scheduled, false otherwise
         def handle_failure(sqs_msg, started_at, retry_intervals)
           receive_count = sqs_msg.attributes['ApproximateReceiveCount'].to_i
 

data/lib/shoryuken/middleware/server/timing.rb

@@ -3,9 +3,20 @@
 module Shoryuken
   module Middleware
     module Server
+      # Middleware that logs timing information for message processing.
+      # Records start time, completion time, and warns if processing
+      # exceeds the queue's visibility timeout.
       class Timing
         include Util
 
+        # Processes a message while logging timing information
+        #
+        # @param _worker [Object] the worker instance (unused)
+        # @param queue [String] the queue name
+        # @param _sqs_msg [Shoryuken::Message] the message being processed (unused)
+        # @param _body [Object] the parsed message body (unused)
+        # @yield continues to the next middleware in the chain
+        # @return [void]
         def call(_worker, queue, _sqs_msg, _body)
           started_at = Time.now
 

data/lib/shoryuken/options.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Stores and manages all Shoryuken configuration options.
+  # This class is used internally to hold settings for workers, queues,
+  # middleware, and other runtime configurations.
   class Options
+    # Default configuration values for Shoryuken
     DEFAULTS = {
       thread_priority: -1,
       concurrency: 25,
@@ -19,14 +23,31 @@ module Shoryuken
       }
     }.freeze
 
+    # @return [Boolean] whether to enable ActiveJob queue name prefixing
+    # @return [Boolean] whether to cache SQS visibility timeout
+    # @return [Hash{String => Hash}] the configured processing groups
+    # @return [Object] the executor used to launch workers
+    # @return [Proc] the code reloader proc for development environments
+    # @return [Boolean] whether code reloading is enabled
+    # @return [Proc, nil] callback to execute when server starts
+    # @return [Proc, nil] callback to execute when server stops
+    # @return [Class] the executor class for running workers
+    # @return [Shoryuken::WorkerRegistry] the registry for worker classes
+    # @return [Array<#call>] handlers for processing exceptions
     attr_accessor :active_job_queue_name_prefixing, :cache_visibility_timeout,
                   :groups, :launcher_executor, :reloader, :enable_reloading,
                   :start_callback, :stop_callback, :worker_executor, :worker_registry,
                   :exception_handlers
 
+    # @return [Hash] the default options for workers
+    # @return [Aws::SQS::Client] the SQS client instance
+    # @return [Logger] the logger instance
     attr_writer :default_worker_options, :sqs_client, :logger
+
+    # @return [Hash] options passed to SQS receive_message calls
     attr_reader :sqs_client_receive_message_opts
 
+    # Initializes a new Options instance with default values
     def initialize
       self.groups = {}
       self.worker_registry = DefaultWorkerRegistry.new
@@ -40,10 +61,19 @@ module Shoryuken
       @sqs_client_receive_message_opts ||= {}
     end
 
+    # Checks if ActiveJob is available
+    #
+    # @return [Boolean] true if ActiveJob is defined
     def active_job?
       defined?(::ActiveJob)
     end
 
+    # Adds a processing group with the specified concurrency and delay
+    #
+    # @param group [String] the name of the group
+    # @param concurrency [Integer, nil] the number of concurrent workers for the group
+    # @param delay [Float, nil] the delay between polling cycles
+    # @return [Hash] the group configuration
     def add_group(group, concurrency = nil, delay: nil)
       concurrency ||= options[:concurrency]
       delay ||= options[:delay]
@@ -55,16 +85,29 @@ module Shoryuken
       }
     end
 
+    # Adds a queue to a processing group with the specified weight
+    #
+    # @param queue [String] the name of the queue
+    # @param weight [Integer] the weight (priority) of the queue
+    # @param group [String] the name of the group to add the queue to
+    # @return [void]
     def add_queue(queue, weight, group)
       weight.times do
         groups[group][:queues] << queue
       end
     end
 
+    # Returns all queues from all groups
+    #
+    # @return [Array<String>] flat array of all queue names
     def ungrouped_queues
       groups.values.flat_map { |options| options[:queues] }
     end
 
+    # Returns the polling strategy class for a group
+    #
+    # @param group [String] the name of the group
+    # @return [Class] the polling strategy class to use
     def polling_strategy(group)
       strategy = (group == 'default' ? options : options[:groups].to_h[group]).to_h[:polling_strategy]
       case strategy
@@ -76,61 +119,111 @@ module Shoryuken
         begin
           Object.const_get(strategy)
         rescue NameError
-          raise ArgumentError, "#{strategy} is not a valid polling_strategy"
+          raise Errors::InvalidPollingStrategyError, "#{strategy} is not a valid polling_strategy"
         end
       when Class
         strategy
       end
     end
 
+    # Returns the polling delay for a group
+    #
+    # @param group [String] the name of the group
+    # @return [Float] the delay in seconds
     def delay(group)
       groups[group].to_h.fetch(:delay, options[:delay]).to_f
     end
 
+    # Returns the SQS client, initializing a default one if needed.
+    # Uses AWS configuration from options[:aws] if available.
+    #
+    # @return [Aws::SQS::Client] the SQS client
     def sqs_client
-      @sqs_client ||= Aws::SQS::Client.new
+      @sqs_client ||= Aws::SQS::Client.new(options[:aws])
     end
 
+    # Sets the SQS client receive message options for the default group
+    #
+    # @param sqs_client_receive_message_opts [Hash] the options hash
+    # @return [Hash] the options hash
     def sqs_client_receive_message_opts=(sqs_client_receive_message_opts)
       @sqs_client_receive_message_opts['default'] = sqs_client_receive_message_opts
     end
 
+    # Returns the global options hash
+    #
+    # @return [Hash] the options hash
     def options
       @options ||= DEFAULTS.dup
     end
 
+    # Returns the logger instance
+    #
+    # @return [Logger] the logger
     def logger
       @logger ||= Shoryuken::Logging.logger
     end
 
+    # Returns the thread priority setting
+    #
+    # @return [Integer] the thread priority
     def thread_priority
       @thread_priority ||= options[:thread_priority]
     end
 
+    # Sets the thread priority
+    #
+    # @param value [Integer] the thread priority value
+    # @return [Integer] the thread priority
+    attr_writer :thread_priority
+
+    # Registers a worker class with the worker registry
+    #
+    # @param args [Array] arguments to pass to the registry
+    # @return [void]
     def register_worker(*args)
       worker_registry.register_worker(*args)
     end
 
+    # Yields self if running as a server for server-specific configuration
+    #
+    # @yield [Shoryuken::Options] the options instance
+    # @return [void]
     def configure_server
       yield self if server?
     end
 
+    # Returns the server middleware chain
+    #
+    # @yield [Shoryuken::Middleware::Chain] the middleware chain for configuration
+    # @return [Shoryuken::Middleware::Chain] the server middleware chain
     def server_middleware
       @_server_chain ||= default_server_middleware
       yield @_server_chain if block_given?
       @_server_chain
     end
 
+    # Yields self unless running as a server for client-specific configuration
+    #
+    # @yield [Shoryuken::Options] the options instance
+    # @return [void]
     def configure_client
       yield self unless server?
     end
 
+    # Returns the client middleware chain
+    #
+    # @yield [Shoryuken::Middleware::Chain] the middleware chain for configuration
+    # @return [Shoryuken::Middleware::Chain] the client middleware chain
     def client_middleware
       @_client_chain ||= default_client_middleware
       yield @_client_chain if block_given?
       @_client_chain
     end
 
+    # Returns the default worker options hash
+    #
+    # @return [Hash{String => Object}] the default worker options
     def default_worker_options
       @default_worker_options ||= {
         'queue' => 'default',
@@ -142,43 +235,70 @@ module Shoryuken
       }
     end
 
+    # Registers a callback to run when the server starts
+    #
+    # @param block [Proc] the block to execute on start
+    # @return [void]
+    # @yield the block to execute on start
     def on_start(&block)
       self.start_callback = block
     end
 
+    # Registers a callback to run when the server stops
+    #
+    # @param block [Proc] the block to execute on stop
+    # @return [void]
+    # @yield the block to execute on stop
     def on_stop(&block)
       self.stop_callback = block
     end
 
-    # Register a block to run at a point in the Shoryuken lifecycle.
-    # :startup, :quiet, :shutdown or :stopped are valid events.
+    # Registers a block to run at a point in the Shoryuken lifecycle.
     #
+    # @param event [Symbol] the lifecycle event (:startup, :quiet, :shutdown, or :stopped)
+    # @param block [Proc] the block to execute for the event
+    # @return [void]
+    # @raise [ArgumentError] if event is not a Symbol or not a valid event name
+    # @yield the block to execute for the event
+    # @example
     #   Shoryuken.configure_server do |config|
     #     config.on(:shutdown) do
     #       puts "Goodbye cruel world!"
     #     end
     #   end
     def on(event, &block)
-      fail ArgumentError, "Symbols only please: #{event}" unless event.is_a?(Symbol)
-      fail ArgumentError, "Invalid event name: #{event}" unless options[:lifecycle_events].key?(event)
+      raise Errors::InvalidEventError, "Symbols only please: #{event}" unless event.is_a?(Symbol)
+      raise Errors::InvalidEventError, "Invalid event name: #{event}" unless options[:lifecycle_events].key?(event)
 
       options[:lifecycle_events][event] << block
     end
 
+    # Checks if running as a server (CLI mode)
+    #
+    # @return [Boolean] true if Shoryuken::CLI is defined
     def server?
       defined?(Shoryuken::CLI)
     end
 
+    # Checks if visibility timeout caching is enabled
+    #
+    # @return [Boolean] true if caching is enabled
     def cache_visibility_timeout?
       @cache_visibility_timeout
     end
 
+    # Checks if ActiveJob queue name prefixing is enabled
+    #
+    # @return [Boolean] true if prefixing is enabled
     def active_job_queue_name_prefixing?
       @active_job_queue_name_prefixing
     end
 
     private
 
+    # Creates the default server middleware chain
+    #
+    # @return [Shoryuken::Middleware::Chain] the default middleware chain
     def default_server_middleware
       Middleware::Chain.new do |m|
         m.add Middleware::Server::Timing
@@ -192,6 +312,9 @@ module Shoryuken
       end
     end
 
+    # Creates the default client middleware chain
+    #
+    # @return [Shoryuken::Middleware::Chain] an empty middleware chain
     def default_client_middleware
       Middleware::Chain.new
     end

data/lib/shoryuken/polling/base_strategy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Polling strategies for determining which queue to fetch messages from next
   module Polling
     # Abstract base class for queue polling strategies.
     #

data/lib/shoryuken/polling/strict_priority.rb

@@ -2,7 +2,14 @@
 
 module Shoryuken
   module Polling
+    # A polling strategy that processes queues in strict priority order.
+    # Higher priority queues are always processed before lower priority queues.
+    # Queues are temporarily paused when no messages are found.
     class StrictPriority < BaseStrategy
+      # Initializes a new StrictPriority polling strategy
+      #
+      # @param queues [Array<String>] array of queue names, with higher priority queues appearing more frequently
+      # @param delay [Float, nil] delay in seconds before unpausing empty queues
       def initialize(queues, delay = nil)
         # Priority ordering of the queues, highest priority first
         @queues = queues
@@ -19,11 +26,19 @@ module Shoryuken
         reset_next_queue
       end
 
+      # Returns the next queue to poll based on strict priority
+      #
+      # @return [QueueConfiguration, nil] the next queue configuration or nil if all paused
       def next_queue
         next_queue = next_active_queue
         next_queue.nil? ? nil : QueueConfiguration.new(next_queue, {})
       end
 
+      # Handles the result of polling a queue
+      #
+      # @param queue [String] the queue name
+      # @param messages_found [Integer] number of messages found
+      # @return [void]
       def messages_found(queue, messages_found)
         if messages_found == 0
           pause(queue)
@@ -32,6 +47,9 @@ module Shoryuken
         end
       end
 
+      # Returns the list of active (non-paused) queues with their priorities
+      #
+      # @return [Array<Array>] array of [queue_name, priority] pairs
       def active_queues
         @queues
           .reverse
@@ -40,6 +58,10 @@ module Shoryuken
           .reverse
       end
 
+      # Called when a message from a queue has been processed
+      #
+      # @param queue [String] the queue name
+      # @return [void]
       def message_processed(queue)
         if queue_paused?(queue)
           logger.debug "Unpausing #{queue}"
@@ -49,6 +71,9 @@ module Shoryuken
 
       private
 
+      # Finds the next active (non-paused) queue
+      #
+      # @return [String, nil] the queue name or nil if all paused
       def next_active_queue
         reset_next_queue if queues_unpaused_since?
 
@@ -62,6 +87,9 @@ module Shoryuken
         nil
       end
 
+      # Checks if any queues have been unpaused since last check
+      #
+      # @return [Boolean] true if queues were unpaused
       def queues_unpaused_since?
         last = @last_unpause_check
         now = @last_unpause_check = Time.now
@@ -69,14 +97,25 @@ module Shoryuken
         last && @paused_until.values.any? { |t| t > last && t <= now }
       end
 
+      # Resets the next queue index to start from the highest priority
+      #
+      # @return [void]
       def reset_next_queue
         @next_queue_index = 0
       end
 
+      # Checks if a queue is currently paused
+      #
+      # @param queue [String] the queue name
+      # @return [Boolean] true if the queue is paused
       def queue_paused?(queue)
         @paused_until[queue] > Time.now
       end
 
+      # Pauses a queue for the configured delay time
+      #
+      # @param queue [String] the queue name to pause
+      # @return [void]
       def pause(queue)
         return unless delay > 0