shoryuken 6.2.1 → 7.0.2

data/lib/shoryuken/polling/base_strategy.rb

@@ -0,0 +1,127 @@
+# 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.
+    #
+    # This class defines the interface that all polling strategies must implement
+    # to manage queue selection and message flow control in Shoryuken workers.
+    # Polling strategies determine which queue to fetch messages from next and
+    # how to handle scenarios where queues have no messages available.
+    #
+    # @abstract Subclass and override {#next_queue}, {#messages_found}, and {#active_queues}
+    #   to implement a custom polling strategy.
+    #
+    # @example Implementing a custom polling strategy
+    #   class CustomStrategy < BaseStrategy
+    #     def initialize(queues)
+    #       @queues = queues
+    #     end
+    #
+    #     def next_queue
+    #       # Return next queue to poll
+    #       @queues.sample
+    #     end
+    #
+    #     def messages_found(queue, count)
+    #       # Handle result of polling
+    #       logger.info "Found #{count} messages in #{queue}"
+    #     end
+    #
+    #     def active_queues
+    #       # Return list of active queues
+    #       @queues
+    #     end
+    #   end
+    #
+    # @see WeightedRoundRobin
+    # @see StrictPriority
+    class BaseStrategy
+      include Util
+
+      # Returns the next queue to poll for messages.
+      #
+      # This method should return a QueueConfiguration object representing
+      # the next queue that should be polled for messages, or nil if no
+      # queues are currently available for polling.
+      #
+      # @abstract Subclasses must implement this method
+      # @return [QueueConfiguration, nil] Next queue to poll, or nil if none available
+      # @raise [NotImplementedError] if not implemented by subclass
+      def next_queue
+        fail NotImplementedError
+      end
+
+      # Called when messages are found (or not found) in a queue.
+      #
+      # This method is invoked after polling a queue to inform the strategy
+      # about the number of messages that were retrieved. Strategies can use
+      # this information to make decisions about future polling behavior,
+      # such as pausing empty queues or adjusting queue weights.
+      #
+      # @abstract Subclasses must implement this method
+      # @param _queue [String] The name of the queue that was polled
+      # @param _messages_found [Integer] The number of messages retrieved
+      # @raise [NotImplementedError] if not implemented by subclass
+      def messages_found(_queue, _messages_found)
+        fail NotImplementedError
+      end
+
+      # Called when a message from a queue has been processed.
+      #
+      # This optional callback is invoked after a message has been successfully
+      # processed by a worker. Strategies can use this information for cleanup
+      # or to adjust their polling behavior.
+      #
+      # @param _queue [String] The name of the queue whose message was processed
+      # @return [void]
+      def message_processed(_queue); end
+
+      # Returns the list of currently active queues.
+      #
+      # This method should return an array representing the queues that are
+      # currently active and available for polling. The format may vary by
+      # strategy implementation.
+      #
+      # @abstract Subclasses must implement this method
+      # @return [Array] List of active queues
+      # @raise [NotImplementedError] if not implemented by subclass
+      def active_queues
+        fail NotImplementedError
+      end
+
+      # Compares this strategy with another object for equality.
+      #
+      # Two strategies are considered equal if they have the same active queues.
+      # This method also supports comparison with Array objects for backward
+      # compatibility.
+      #
+      # @param other [Object] Object to compare with
+      # @return [Boolean] true if strategies are equivalent
+      def ==(other)
+        case other
+        when Array
+          @queues == other
+        else
+          if other.respond_to?(:active_queues)
+            active_queues == other.active_queues
+          else
+            false
+          end
+        end
+      end
+
+      # Returns the delay time for pausing empty queues.
+      #
+      # This method returns the amount of time (in seconds) that empty queues
+      # should be paused before being polled again. The delay can be set at
+      # the strategy level or falls back to the global Shoryuken delay setting.
+      #
+      # @return [Float] Delay time in seconds
+      def delay
+        @delay || Shoryuken.options[:delay].to_f
+      end
+    end
+  end
+end

data/lib/shoryuken/polling/queue_configuration.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  module Polling
+    # Configuration object representing a queue and its associated options.
+    #
+    # This class encapsulates a queue name along with any polling-specific
+    # options or metadata. It provides a structured way to pass queue
+    # information between polling strategies and the message fetching system.
+    #
+    # The class extends Struct to provide attribute accessors for name and options
+    # while adding custom behavior for equality comparison and string representation.
+    #
+    # @example Creating a basic queue configuration
+    #   config = QueueConfiguration.new('my_queue', {})
+    #   config.name     # => 'my_queue'
+    #   config.options  # => {}
+    #
+    # @example Creating a queue configuration with options
+    #   config = QueueConfiguration.new('priority_queue', { priority: :high })
+    #   config.name     # => 'priority_queue'
+    #   config.options  # => { priority: :high }
+    #
+    # @example Comparing configurations
+    #   config1 = QueueConfiguration.new('queue', {})
+    #   config2 = QueueConfiguration.new('queue', {})
+    #   config1 == config2  # => true
+    #   config1 == 'queue'  # => true (when options are empty)
+    #
+    # @attr_reader [String] name The name of the queue
+    # @attr_reader [Hash] options Additional options or metadata for the queue
+    QueueConfiguration = Struct.new(:name, :options) do
+      # Generates a hash value based on the queue name.
+      #
+      # This method ensures that QueueConfiguration objects can be used
+      # as hash keys and that configurations with the same queue name
+      # will have the same hash value regardless of their options.
+      #
+      # @return [Integer] Hash value based on the queue name
+      def hash
+        name.hash
+      end
+
+      # Compares this configuration with another object for equality.
+      #
+      # Two QueueConfiguration objects are equal if they have the same name
+      # and options. For convenience, a configuration with empty options can
+      # also be compared directly with a string queue name.
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] true if the objects are considered equal
+      #
+      # @example Comparing with another QueueConfiguration
+      #   config1 = QueueConfiguration.new('queue', {})
+      #   config2 = QueueConfiguration.new('queue', {})
+      #   config1 == config2  # => true
+      #
+      # @example Comparing with a string (only when options are empty)
+      #   config = QueueConfiguration.new('queue', {})
+      #   config == 'queue'  # => true
+      #
+      #   config_with_options = QueueConfiguration.new('queue', { weight: 5 })
+      #   config_with_options == 'queue'  # => false
+      def ==(other)
+        case other
+        when String
+          if options.empty?
+            name == other
+          else
+            false
+          end
+        else
+          super
+        end
+      end
+
+      alias_method :eql?, :==
+
+      # Returns a string representation of the queue configuration.
+      #
+      # For configurations with empty options, returns just the queue name.
+      # For configurations with options, returns a detailed representation
+      # showing both the name and the options hash.
+      #
+      # @return [String] String representation of the configuration
+      #
+      # @example Simple queue without options
+      #   config = QueueConfiguration.new('simple_queue', {})
+      #   config.to_s  # => 'simple_queue'
+      #
+      # @example Queue with options
+      #   config = QueueConfiguration.new('complex_queue', { priority: :high })
+      #   config.to_s  # => '#<QueueConfiguration complex_queue options={:priority=>:high}>'
+      def to_s
+        if options&.empty?
+          name
+        else
+          "#<QueueConfiguration #{name} options=#{options.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/shoryuken/polling/strict_priority.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 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
@@ -17,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)
@@ -30,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
@@ -38,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}"
@@ -47,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?
 
@@ -60,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
@@ -67,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
 

data/lib/shoryuken/polling/weighted_round_robin.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Polling
+    # A polling strategy that processes queues in weighted round-robin order.
+    # Queue weights determine how often each queue is polled relative to others.
+    # Queues are temporarily paused when no messages are found.
     class WeightedRoundRobin < BaseStrategy
+      # Initializes a new WeightedRoundRobin polling strategy
+      #
+      # @param queues [Array<String>] array of queue names, with weights indicated by repetition
+      # @param delay [Float, nil] delay in seconds before unpausing empty queues
       def initialize(queues, delay = nil)
         @initial_queues = queues
         @queues = queues.dup.uniq
@@ -8,6 +17,9 @@ module Shoryuken
         @delay = delay
       end
 
+      # Returns the next queue to poll in round-robin order
+      #
+      # @return [QueueConfiguration, nil] the next queue configuration or nil if all paused
       def next_queue
         unpause_queues
         queue = @queues.shift
@@ -17,6 +29,11 @@ module Shoryuken
         QueueConfiguration.new(queue, {})
       end
 
+      # Handles the result of polling a queue, adjusting weight if messages were found
+      #
+      # @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)
@@ -31,10 +48,17 @@ module Shoryuken
         end
       end
 
+      # Returns the list of active queues with their current weights
+      #
+      # @return [Array<Array>] array of [queue_name, weight] pairs
       def active_queues
         unparse_queues(@queues)
       end
 
+      # Called when a message from a queue has been processed
+      #
+      # @param queue [String] the queue name
+      # @return [void]
       def message_processed(queue)
         paused_queue = @paused_queues.find { |_time, name| name == queue }
         return unless paused_queue
@@ -44,6 +68,10 @@ module Shoryuken
 
       private
 
+      # Pauses a queue by removing it from active rotation
+      #
+      # @param queue [String] the queue name to pause
+      # @return [void]
       def pause(queue)
         return unless @queues.delete(queue)
 
@@ -51,6 +79,9 @@ module Shoryuken
         logger.debug "Paused #{queue}"
       end
 
+      # Unpauses queues whose delay has expired
+      #
+      # @return [void]
       def unpause_queues
         return if @paused_queues.empty?
         return if Time.now < @paused_queues.first[0]
@@ -60,14 +91,27 @@ module Shoryuken
         logger.debug "Unpaused #{pause[1]}"
       end
 
+      # Returns the current weight of a queue in the active rotation
+      #
+      # @param queue [String] the queue name
+      # @return [Integer] the current weight
       def current_queue_weight(queue)
         queue_weight(@queues, queue)
       end
 
+      # Returns the maximum configured weight of a queue
+      #
+      # @param queue [String] the queue name
+      # @return [Integer] the maximum weight
       def maximum_queue_weight(queue)
         queue_weight(@initial_queues, queue)
       end
 
+      # Counts how many times a queue appears in the given array
+      #
+      # @param queues [Array<String>] the array to count in
+      # @param queue [String] the queue name to count
+      # @return [Integer] the count
       def queue_weight(queues, queue)
         queues.count { |q| q == queue }
       end

data/lib/shoryuken/processor.rb

@@ -1,21 +1,42 @@
+# frozen_string_literal: true
+
 module Shoryuken
+  # Processes SQS messages by invoking the appropriate worker.
+  # Handles middleware chain execution and exception handling.
   class Processor
     include Util
 
-    attr_reader :queue, :sqs_msg
+    # @return [String] the queue name
+    attr_reader :queue
+
+    # @return [Aws::SQS::Types::Message, Array<Aws::SQS::Types::Message>] the message or batch
+    attr_reader :sqs_msg
 
+    # Processes a message from a queue
+    #
+    # @param queue [String] the queue name
+    # @param sqs_msg [Aws::SQS::Types::Message, Array<Aws::SQS::Types::Message>] the message or batch
+    # @return [Object] the result of the worker's perform method
     def self.process(queue, sqs_msg)
       new(queue, sqs_msg).process
     end
 
+    # Initializes a new Processor
+    #
+    # @param queue [String] the queue name
+    # @param sqs_msg [Aws::SQS::Types::Message, Array<Aws::SQS::Types::Message>] the message or batch
     def initialize(queue, sqs_msg)
       @queue   = queue
       @sqs_msg = sqs_msg
     end
 
+    # Processes the message through the middleware chain and worker
+    #
+    # @return [Object] the result of the worker's perform method
     def process
       worker_perform = proc do
         return logger.error { "No worker found for #{queue}" } unless worker
+
         Shoryuken::Logging.with_context("#{worker_name(worker.class, sqs_msg, body)}/#{queue}/#{sqs_msg.message_id}") do
           worker.class.server_middleware.invoke(worker, queue, sqs_msg, body) do
             worker.perform(sqs_msg, body)
@@ -30,26 +51,39 @@ module Shoryuken
       else
         worker_perform.call
       end
-    rescue Exception => ex
-      Array(Shoryuken.exception_handlers).each { |handler| handler.call(ex, queue, sqs_msg) }
+    rescue Exception => e
+      Array(Shoryuken.exception_handlers).each { |handler| handler.call(e, queue, sqs_msg) }
 
       raise
     end
 
     private
 
+    # Fetches the worker instance for processing
+    #
+    # @return [Object, nil] the worker instance or nil if not found
     def worker
       @_worker ||= Shoryuken.worker_registry.fetch_worker(queue, sqs_msg)
     end
 
+    # Returns the worker class
+    #
+    # @return [Class] the worker class
     def worker_class
       worker.class
     end
 
+    # Parses the message body or bodies for batch processing
+    #
+    # @return [Object, Array<Object>] the parsed body or array of bodies
     def body
       @_body ||= sqs_msg.is_a?(Array) ? sqs_msg.map(&method(:parse_body)) : parse_body(sqs_msg)
     end
 
+    # Parses a single message body
+    #
+    # @param sqs_msg [Aws::SQS::Types::Message] the message to parse
+    # @return [Object] the parsed message body
     def parse_body(sqs_msg)
       BodyParser.parse(worker_class, sqs_msg)
     end