shoryuken 6.2.1 → 7.0.2

data/lib/shoryuken/queue.rb

@@ -1,18 +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
 
-    FIFO_ATTR               = 'FifoQueue'.freeze
-    MESSAGE_GROUP_ID        = 'ShoryukenMessage'.freeze
-    VISIBILITY_TIMEOUT_ATTR = 'VisibilityTimeout'.freeze
+    # 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'
+
+    # @return [String] the queue name
+    attr_accessor :name
+
+    # @return [Aws::SQS::Client] the SQS client
+    attr_accessor :client
 
-    attr_accessor :name, :client, :url
+    # @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
@@ -20,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)
@@ -31,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)
 
@@ -39,18 +76,35 @@ 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/phstc/shoryuken/pull/529
+      # see https://github.com/ruby-shoryuken/shoryuken/pull/529
       return @_fifo if defined?(@_fifo)
 
       @_fifo = queue_attributes.attributes[FIFO_ATTR] == 'true'
@@ -59,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)
@@ -104,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|
@@ -128,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?
 
@@ -137,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $stdout.sync = true
 
 require 'singleton'
@@ -7,25 +9,32 @@ require 'erb'
 require 'shoryuken'
 
 module Shoryuken
-  # rubocop:disable Lint/InheritException
-  # 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
 
       %w[INT TERM USR1 TSTP TTIN].each do |sig|
-        begin
-          trap sig do
-            self_write.puts(sig)
-          end
-        rescue ArgumentError
-          puts "Signal #{sig} not supported"
+        trap sig do
+          self_write.puts(sig)
         end
+      rescue ArgumentError
+        puts "Signal #{sig} not supported"
       end
 
       loader = EnvironmentLoader.setup_options(options)
@@ -52,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
 
@@ -66,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]
 
@@ -77,11 +98,9 @@ module Shoryuken
       Process.daemon(true, true)
 
       files_to_reopen.each do |file|
-        begin
-          file.reopen file.path, 'a+'
-          file.sync = true
-        rescue ::Exception
-        end
+        file.reopen file.path, 'a+'
+        file.sync = true
+      rescue ::Exception
       end
 
       [$stdout, $stderr].each do |io|
@@ -93,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']}" }
@@ -123,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,41 +1,66 @@
+# 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]
       arr.reverse! if reverse
       arr.each do |block|
-        begin
-          block.call(event_options)
-        rescue => ex
-          logger.warn(event: event)
-          logger.warn "#{ex.class.name}: #{ex.message}"
-        end
+        block.call(event_options)
+      rescue => e
+        logger.warn(event: event)
+        logger.warn "#{e.class.name}: #{e.message}"
       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,3 +1,6 @@
+# frozen_string_literal: true
+
 module Shoryuken
-  VERSION = '6.2.1'.freeze
+  # Current version of the Shoryuken gem
+  VERSION = '7.0.2'
 end

data/lib/shoryuken/worker/default_executor.rb

@@ -1,7 +1,19 @@
+# frozen_string_literal: true
+
 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'] = {
@@ -16,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
@@ -23,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

@@ -1,17 +1,34 @@
+# frozen_string_literal: true
+
 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']
+          message_attributes = options.delete(:message_attributes) || {}
+          message_attributes['shoryuken_class'] = {
+            string_value: worker_class.to_s,
+            data_type: 'String'
+          }
 
-          sqs_msg = OpenStruct.new(
+          sqs_msg = InlineMessage.new(
             body: body,
             attributes: nil,
             md5_of_body: nil,
             md5_of_message_attributes: nil,
-            message_attributes: nil,
+            message_attributes: message_attributes,
             message_id: nil,
             receipt_handle: nil,
             delete: nil,
@@ -21,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']