shoryuken 7.0.0.alpha2 → 7.0.0

data/lib/shoryuken/polling/weighted_round_robin.rb

@@ -2,7 +2,14 @@
 
 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
@@ -10,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
@@ -19,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)
@@ -33,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
@@ -46,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)
 
@@ -53,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]
@@ -62,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,20 +1,38 @@
 # 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
@@ -41,18 +59,31 @@ module Shoryuken
 
     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

data/lib/shoryuken/queue.rb

@@ -1,20 +1,41 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Represents an SQS queue and provides methods for sending and receiving messages.
+  # Handles both standard and FIFO queues, automatically adding required FIFO attributes.
   class Queue
     include Util
 
+    # SQS attribute name for FIFO queue identification
     FIFO_ATTR               = 'FifoQueue'
+
+    # Default message group ID used for FIFO queues
     MESSAGE_GROUP_ID        = 'ShoryukenMessage'
+
+    # SQS attribute name for visibility timeout
     VISIBILITY_TIMEOUT_ATTR = 'VisibilityTimeout'
 
-    attr_accessor :name, :client, :url
+    # @return [String] the queue name
+    attr_accessor :name
+
+    # @return [Aws::SQS::Client] the SQS client
+    attr_accessor :client
+
+    # @return [String] the queue URL
+    attr_accessor :url
 
+    # Initializes a new Queue instance
+    #
+    # @param client [Aws::SQS::Client] the SQS client
+    # @param name_or_url_or_arn [String] the queue name, URL, or ARN
     def initialize(client, name_or_url_or_arn)
       self.client = client
       set_name_and_url(name_or_url_or_arn)
     end
 
+    # Returns the visibility timeout for the queue
+    #
+    # @return [Integer] the visibility timeout in seconds
     def visibility_timeout
       # Always lookup for the latest visibility when cache is disabled
       # setting it to nil, forces re-lookup
@@ -22,6 +43,11 @@ module Shoryuken
       @_visibility_timeout ||= queue_attributes.attributes[VISIBILITY_TIMEOUT_ATTR].to_i
     end
 
+    # Deletes messages from the queue in batch
+    #
+    # @param options [Hash] options for delete_message_batch
+    # @option options [Array<Hash>] :entries entries to delete with id and receipt_handle
+    # @return [Boolean] true if any messages failed to delete
     def delete_messages(options)
       failed_messages = client.delete_message_batch(
         options.merge(queue_url: url)
@@ -33,6 +59,15 @@ module Shoryuken
       end
     end
 
+    # Sends a single message to the queue
+    #
+    # @param options [Hash, String] message options or message body string
+    # @option options [String] :message_body the message body
+    # @option options [Integer] :delay_seconds delay before message becomes visible
+    # @option options [Hash] :message_attributes custom message attributes
+    # @option options [String] :message_group_id FIFO queue message group ID
+    # @option options [String] :message_deduplication_id FIFO queue deduplication ID
+    # @return [Aws::SQS::Types::SendMessageResult] the send result
     def send_message(options)
       options = sanitize_message!(options).merge(queue_url: url)
 
@@ -41,15 +76,32 @@ module Shoryuken
       end
     end
 
+    # Sends multiple messages to the queue in batch
+    #
+    # @param options [Hash, Array] batch options or array of message bodies/hashes
+    # @option options [Array<Hash>] :entries message entries to send
+    # @return [Aws::SQS::Types::SendMessageBatchResult] the batch send result
     def send_messages(options)
       client.send_message_batch(sanitize_messages!(options).merge(queue_url: url))
     end
 
+    # Receives messages from the queue
+    #
+    # @param options [Hash] options for receive_message
+    # @option options [Integer] :max_number_of_messages maximum messages to receive
+    # @option options [Integer] :visibility_timeout visibility timeout for received messages
+    # @option options [Integer] :wait_time_seconds long polling wait time
+    # @option options [Array<String>] :attribute_names SQS attributes to retrieve
+    # @option options [Array<String>] :message_attribute_names message attributes to retrieve
+    # @return [Array<Shoryuken::Message>] the received messages
     def receive_messages(options)
       messages = client.receive_message(options.merge(queue_url: url)).messages || []
       messages.map { |m| Message.new(client, self, m) }
     end
 
+    # Checks if the queue is a FIFO queue
+    #
+    # @return [Boolean] true if the queue is a FIFO queue
     def fifo?
       # Make sure the memoization work with boolean to avoid multiple calls to SQS
       # see https://github.com/ruby-shoryuken/shoryuken/pull/529
@@ -61,32 +113,51 @@ module Shoryuken
 
     private
 
+    # Initializes the FIFO attribute by calling fifo?
+    #
+    # @return [Boolean] whether the queue is FIFO
     def initialize_fifo_attribute
       # calling fifo? will also initialize it
       fifo?
     end
 
+    # Sets the queue name and URL from a queue name
+    #
+    # @param name [String] the queue name
+    # @return [void]
     def set_by_name(name) # rubocop:disable Naming/AccessorMethodName
       self.name = name
       self.url  = client.get_queue_url(queue_name: name).queue_url
     end
 
+    # Sets the queue name and URL from a queue URL
+    #
+    # @param url [String] the queue URL
+    # @return [void]
     def set_by_url(url) # rubocop:disable Naming/AccessorMethodName
       self.name = url.split('/').last
       self.url  = url
     end
 
+    # Converts an ARN to a queue URL
+    #
+    # @param arn_str [String] the ARN string
+    # @return [String] the queue URL
     def arn_to_url(arn_str)
       *, region, account_id, resource = arn_str.split(':')
 
       required = [region, account_id, resource].map(&:to_s)
       valid = required.none?(&:empty?)
 
-      abort "Invalid ARN: #{arn_str}. A valid ARN must include: region, account_id and resource." unless valid
+      raise Errors::InvalidArnError, "Invalid ARN: #{arn_str}. A valid ARN must include: region, account_id and resource." unless valid
 
       "https://sqs.#{region}.amazonaws.com/#{account_id}/#{resource}"
     end
 
+    # Sets the queue name and URL from a name, URL, or ARN
+    #
+    # @param name_or_url_or_arn [String] the queue identifier
+    # @return [void]
     def set_name_and_url(name_or_url_or_arn) # rubocop:disable Naming/AccessorMethodName
       if name_or_url_or_arn.include?('://')
         set_by_url(name_or_url_or_arn)
@@ -106,16 +177,24 @@ module Shoryuken
       end
 
       set_by_name(name_or_url_or_arn)
-    rescue Aws::Errors::NoSuchEndpointError, Aws::SQS::Errors::NonExistentQueue => e
-      raise e, "The specified queue #{name_or_url_or_arn} does not exist."
+    rescue Aws::Errors::NoSuchEndpointError, Aws::SQS::Errors::NonExistentQueue
+      raise Errors::QueueNotFoundError, "The specified queue #{name_or_url_or_arn} does not exist."
     end
 
+    # Returns the queue attributes from SQS
+    #
+    # @return [Aws::SQS::Types::GetQueueAttributesResult] the queue attributes
     def queue_attributes
       # Note: Retrieving all queue attributes as requesting `FifoQueue` on non-FIFO queue raises error.
       # See issue: https://github.com/aws/aws-sdk-ruby/issues/1350
       client.get_queue_attributes(queue_url: url, attribute_names: ['All'])
     end
 
+    # Sanitizes a batch of messages, converting to proper format
+    #
+    # @param options [Hash, Array] batch options or array of messages
+    # @option options [Array<Hash>] :entries message entries
+    # @return [Hash] the sanitized options with entries key
     def sanitize_messages!(options)
       if options.is_a?(Array)
         entries = options.map.with_index do |m, index|
@@ -130,6 +209,11 @@ module Shoryuken
       options
     end
 
+    # Adds FIFO attributes to message options if needed
+    #
+    # @param options [Hash] the message options
+    # @option options [String] :message_body the message body
+    # @return [Hash] the options with FIFO attributes added
     def add_fifo_attributes!(options)
       return unless fifo?
 
@@ -139,6 +223,11 @@ module Shoryuken
       options
     end
 
+    # Sanitizes a single message, converting body to JSON if needed
+    #
+    # @param options [Hash, String] message options or body string
+    # @option options [String, Hash] :message_body the message body
+    # @return [Hash] the sanitized message options
     def sanitize_message!(options)
       options = { message_body: options } if options.is_a?(String)
 

data/lib/shoryuken/runner.rb

@@ -9,13 +9,23 @@ require 'erb'
 require 'shoryuken'
 
 module Shoryuken
-  # See: https://github.com/mperham/sidekiq/blob/33f5d6b2b6c0dfaab11e5d39688cab7ebadc83ae/lib/sidekiq/cli.rb#L20
-  class Shutdown < Interrupt; end
-
+  # Runs the Shoryuken server process.
+  # Handles signal trapping, daemonization, and lifecycle management.
   class Runner
     include Util
     include Singleton
 
+    # @return [Shoryuken::Launcher, nil] the launcher instance, or nil if not yet initialized
+    attr_reader :launcher
+
+    # Runs the Shoryuken server with the given options
+    #
+    # @param options [Hash] runtime configuration options
+    # @option options [Boolean] :daemon whether to daemonize the process
+    # @option options [String] :pidfile path to the PID file
+    # @option options [String] :logfile path to the log file
+    # @option options [String] :config_file path to the configuration file
+    # @return [void]
     def run(options)
       self_read, self_write = IO.pipe
 
@@ -51,12 +61,18 @@ module Shoryuken
       end
     end
 
+    # Checks if the server is healthy
+    #
+    # @return [Boolean] true if the launcher is running and healthy
     def healthy?
       (@launcher && @launcher.healthy?) || false
     end
 
     private
 
+    # Initializes the Concurrent Ruby logger
+    #
+    # @return [void]
     def initialize_concurrent_logger
       return unless Shoryuken.logger
 
@@ -65,6 +81,12 @@ module Shoryuken
       end
     end
 
+    # Daemonizes the process
+    #
+    # @param options [Hash] options containing daemon and logfile settings
+    # @option options [Boolean] :daemon whether to daemonize
+    # @option options [String] :logfile path to the log file for daemon output
+    # @return [void]
     def daemonize(options)
       return unless options[:daemon]
 
@@ -90,25 +112,39 @@ module Shoryuken
       $stdin.reopen('/dev/null')
     end
 
+    # Writes the process ID to a file
+    #
+    # @param options [Hash] options containing the pidfile path
+    # @option options [String] :pidfile path to write the PID file
+    # @return [void]
     def write_pid(options)
       return unless (path = options[:pidfile])
 
       File.open(path, 'w') { |f| f.puts(Process.pid) }
     end
 
+    # Executes a soft shutdown on USR1 signal
+    #
+    # @return [void]
     def execute_soft_shutdown
-      logger.info { 'Received USR1, will soft shutdown down' }
+      logger.info { 'Received USR1, will soft shutdown' }
 
       @launcher.stop
       exit 0
     end
 
+    # Executes a terminal stop on TSTP signal
+    #
+    # @return [void]
     def execute_terminal_stop
       logger.info { 'Received TSTP, will stop accepting new work' }
 
       @launcher.stop
     end
 
+    # Prints backtraces of all threads
+    #
+    # @return [void]
     def print_threads_backtrace
       Thread.list.each do |thread|
         logger.info { "Thread TID-#{thread.object_id.to_s(36)} #{thread['label']}" }
@@ -120,6 +156,11 @@ module Shoryuken
       end
     end
 
+    # Handles incoming signals
+    #
+    # @param sig [String] the signal name
+    # @return [void]
+    # @raise [Interrupt] on TERM or INT signals
     def handle_signal(sig)
       logger.debug "Got #{sig} signal"
 

data/lib/shoryuken/util.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Utility methods shared across Shoryuken classes.
+  # Provides logging, event firing, and helper methods.
   module Util
+    # Returns the Shoryuken logger
+    #
+    # @return [Logger] the configured logger
     def logger
       Shoryuken.logger
     end
 
+    # Fires a lifecycle event to all registered handlers
+    #
+    # @param event [Symbol] the event name to fire
+    # @param reverse [Boolean] whether to call handlers in reverse order
+    # @param event_options [Hash] options to pass to event handlers
+    # @return [void]
     def fire_event(event, reverse = false, event_options = {})
       logger.debug { "Firing '#{event}' lifecycle event" }
       arr = Shoryuken.options[:lifecycle_events][event]
@@ -18,24 +29,38 @@ module Shoryuken
       end
     end
 
+    # Calculates elapsed time in milliseconds
+    #
+    # @param started_at [Time] the start time
+    # @return [Float] elapsed time in milliseconds
     def elapsed(started_at)
       # elapsed in ms
       (Time.now - started_at) * 1000
     end
 
+    # Converts a queue array to a hash of queue names and weights
+    #
+    # @param queues [Array<String>] array of queue names with possible duplicates
+    # @return [Array<Array>] array of [queue_name, weight] pairs
     def unparse_queues(queues)
       queues.each_with_object({}) do |name, queue_and_weights|
         queue_and_weights[name] = queue_and_weights[name].to_i + 1
       end.to_a
     end
 
+    # Returns a display name for the worker processing a message
+    #
+    # @param worker_class [Class] the worker class
+    # @param sqs_msg [Aws::SQS::Types::Message, Array] the message or batch
+    # @param body [Object, nil] the parsed message body
+    # @return [String] the worker display name
     def worker_name(worker_class, sqs_msg, body = nil)
       if Shoryuken.active_job? \
           && !sqs_msg.is_a?(Array) \
           && sqs_msg.message_attributes \
           && sqs_msg.message_attributes['shoryuken_class'] \
           && sqs_msg.message_attributes['shoryuken_class'][:string_value] \
-          == ActiveJob::QueueAdapters::ShoryukenAdapter::JobWrapper.to_s \
+          == 'Shoryuken::ActiveJob::JobWrapper' \
           && body
 
         "ActiveJob/#{body['job_class']}"

data/lib/shoryuken/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Shoryuken
-  VERSION = '7.0.0.alpha2'
+  # Current version of the Shoryuken gem
+  VERSION = '7.0.0'
 end

data/lib/shoryuken/worker/default_executor.rb

@@ -2,8 +2,18 @@
 
 module Shoryuken
   module Worker
+    # Default executor that sends messages to SQS for asynchronous processing.
+    # This is the standard executor used in production environments.
     class DefaultExecutor
       class << self
+        # Enqueues a job for asynchronous processing via SQS
+        #
+        # @param worker_class [Class] the worker class that will process the message
+        # @param body [Object] the message body
+        # @param options [Hash] additional SQS message options
+        # @option options [Hash] :message_attributes custom message attributes
+        # @option options [String] :queue override the default queue
+        # @return [Aws::SQS::Types::SendMessageResult] the send result
         def perform_async(worker_class, body, options = {})
           options[:message_attributes] ||= {}
           options[:message_attributes]['shoryuken_class'] = {
@@ -18,6 +28,16 @@ module Shoryuken
           Shoryuken::Client.queues(queue).send_message(options)
         end
 
+        # Enqueues a job for delayed processing via SQS
+        #
+        # @param worker_class [Class] the worker class that will process the message
+        # @param interval [Integer, Float] delay in seconds or timestamp
+        # @param body [Object] the message body
+        # @param options [Hash] SQS message options for the delayed job
+        # @option options [Hash] :message_attributes custom message attributes
+        # @option options [String] :queue override the default queue
+        # @return [Aws::SQS::Types::SendMessageResult] the send result
+        # @raise [Errors::InvalidDelayError] if delay exceeds 15 minutes
         def perform_in(worker_class, interval, body, options = {})
           interval = interval.to_f
           now = Time.now.to_f
@@ -25,7 +45,7 @@ module Shoryuken
 
           delay = (ts - now).ceil
 
-          raise 'The maximum allowed delay is 15 minutes' if delay > 15 * 60
+          raise Errors::InvalidDelayError, 'The maximum allowed delay is 15 minutes' if delay > 15 * 60
 
           worker_class.perform_async(body, options.merge(delay_seconds: delay))
         end

data/lib/shoryuken/worker/inline_executor.rb

@@ -2,8 +2,18 @@
 
 module Shoryuken
   module Worker
+    # Executor that processes jobs synchronously in the current thread.
+    # Useful for testing and development environments.
     class InlineExecutor
       class << self
+        # Processes a job synchronously in the current thread
+        #
+        # @param worker_class [Class] the worker class that will process the message
+        # @param body [Object] the message body
+        # @param options [Hash] inline execution options
+        # @option options [String] :queue override the default queue name
+        # @option options [Hash] :message_attributes custom message attributes
+        # @return [Object] the result of the worker's perform method
         def perform_async(worker_class, body, options = {})
           body = JSON.dump(body) if body.is_a?(Hash)
           queue_name = options.delete(:queue) || worker_class.get_shoryuken_options['queue']
@@ -28,12 +38,26 @@ module Shoryuken
           call(worker_class, sqs_msg)
         end
 
+        # Processes a job synchronously, ignoring the delay interval
+        #
+        # @param worker_class [Class] the worker class that will process the message
+        # @param _interval [Integer, Float] ignored for inline execution
+        # @param body [Object] the message body
+        # @param options [Hash] inline execution options
+        # @option options [String] :queue override the default queue name
+        # @option options [Hash] :message_attributes custom message attributes
+        # @return [Object] the result of the worker's perform method
         def perform_in(worker_class, _interval, body, options = {})
           worker_class.perform_async(body, options)
         end
 
         private
 
+        # Instantiates and calls the worker
+        #
+        # @param worker_class [Class] the worker class
+        # @param sqs_msg [Shoryuken::InlineMessage] the message
+        # @return [Object] the result of the worker's perform method
         def call(worker_class, sqs_msg)
           parsed_body = BodyParser.parse(worker_class, sqs_msg)
           batch = worker_class.shoryuken_options_hash['batch']