shoryuken 7.0.0.alpha1 → 7.0.0.rc1

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,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Polling
     class StrictPriority < BaseStrategy

data/lib/shoryuken/polling/weighted_round_robin.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Polling
     class WeightedRoundRobin < BaseStrategy

data/lib/shoryuken/processor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   class Processor
     include Util
@@ -16,6 +18,7 @@ module Shoryuken
     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,8 +33,8 @@ 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

data/lib/shoryuken/queue.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module Shoryuken
   class Queue
     include Util
 
-    FIFO_ATTR               = 'FifoQueue'.freeze
-    MESSAGE_GROUP_ID        = 'ShoryukenMessage'.freeze
-    VISIBILITY_TIMEOUT_ATTR = 'VisibilityTimeout'.freeze
+    FIFO_ATTR               = 'FifoQueue'
+    MESSAGE_GROUP_ID        = 'ShoryukenMessage'
+    VISIBILITY_TIMEOUT_ATTR = 'VisibilityTimeout'
 
     attr_accessor :name, :client, :url
 
@@ -50,7 +52,7 @@ module Shoryuken
 
     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'

data/lib/shoryuken/runner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $stdout.sync = true
 
 require 'singleton'
@@ -7,7 +9,6 @@ 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
 
@@ -15,17 +16,18 @@ module Shoryuken
     include Util
     include Singleton
 
+    # @return [Shoryuken::Launcher, nil] the launcher instance, or nil if not yet initialized
+    attr_reader :launcher
+
     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)
@@ -77,11 +79,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|

data/lib/shoryuken/util.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Util
     def logger
@@ -9,12 +11,10 @@ module Shoryuken
       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
 

data/lib/shoryuken/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
-  VERSION = '7.0.0.alpha1'.freeze
+  VERSION = '7.0.0.rc1'
 end

data/lib/shoryuken/worker/default_executor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Worker
     class DefaultExecutor

data/lib/shoryuken/worker/inline_executor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   module Worker
     class InlineExecutor
@@ -11,7 +13,7 @@ module Shoryuken
             data_type: 'String'
           }
 
-          sqs_msg = OpenStruct.new(
+          sqs_msg = InlineMessage.new(
             body: body,
             attributes: nil,
             md5_of_body: nil,

data/lib/shoryuken/worker.rb

@@ -1,4 +1,46 @@
+# frozen_string_literal: true
+
 module Shoryuken
+  # Worker module provides the core functionality for creating Shoryuken workers
+  # that process messages from Amazon SQS queues.
+  #
+  # Including this module in a class provides methods for configuring queue processing,
+  # enqueueing jobs, and setting up middleware. Workers can be configured for different
+  # processing patterns including single message processing, batch processing, and
+  # various retry and visibility timeout strategies.
+  #
+  # @example Basic worker implementation
+  #   class EmailWorker
+  #     include Shoryuken::Worker
+  #     shoryuken_options queue: 'emails'
+  #
+  #     def perform(sqs_msg, body)
+  #       send_email(body['recipient'], body['subject'], body['content'])
+  #     end
+  #   end
+  #
+  # @example Advanced worker with all options
+  #   class AdvancedWorker
+  #     include Shoryuken::Worker
+  #
+  #     shoryuken_options queue: 'advanced_queue',
+  #                       batch: false,
+  #                       auto_delete: true,
+  #                       auto_visibility_timeout: true,
+  #                       retry_intervals: [1, 5, 25, 125, 625]
+  #
+  #     server_middleware do |chain|
+  #       chain.add MyCustomMiddleware
+  #     end
+  #
+  #     def perform(sqs_msg, body)
+  #       # Worker implementation
+  #     end
+  #   end
+  #
+  # @see ClassMethods#shoryuken_options Primary configuration method
+  # @see ClassMethods#perform_async For enqueueing jobs
+  # @see https://github.com/ruby-shoryuken/shoryuken/wiki/Workers Comprehensive worker documentation
   module Worker
     def self.included(base)
       base.extend(ClassMethods)
@@ -6,35 +48,166 @@ module Shoryuken
     end
 
     module ClassMethods
+      # Enqueues a job to be processed asynchronously by a Shoryuken worker.
+      #
+      # @param body [Object] The job payload that will be passed to the worker's perform method
+      # @param options [Hash] Additional options for job enqueueing
+      # @option options [String] :message_group_id FIFO queue group ID for message ordering
+      # @option options [String] :message_deduplication_id FIFO queue deduplication ID
+      # @option options [Hash] :message_attributes Custom SQS message attributes
+      # @return [String] The message ID of the enqueued job
+      #
+      # @example Basic job enqueueing
+      #   MyWorker.perform_async({ user_id: 123, action: 'send_email' })
+      #
+      # @example FIFO queue with ordering
+      #   MyWorker.perform_async(data, message_group_id: 'user_123')
       def perform_async(body, options = {})
         Shoryuken.worker_executor.perform_async(self, body, options)
       end
 
+      # Enqueues a job to be processed after a specified time interval.
+      #
+      # @param interval [Integer, ActiveSupport::Duration] Delay in seconds, or duration object
+      # @param body [Object] The job payload that will be passed to the worker's perform method
+      # @param options [Hash] Additional options for job enqueueing (see {#perform_async})
+      # @return [String] The message ID of the enqueued job
+      #
+      # @example Delay job by 5 minutes
+      #   MyWorker.perform_in(5.minutes, { user_id: 123 })
+      #
+      # @example Delay job by specific number of seconds
+      #   MyWorker.perform_in(300, { user_id: 123 })
       def perform_in(interval, body, options = {})
         Shoryuken.worker_executor.perform_in(self, interval, body, options)
       end
 
       alias_method :perform_at, :perform_in
 
+      # Configures server-side middleware chain for this worker class.
+      # Middleware runs before and after job processing, similar to Rack middleware.
+      #
+      # @yield [Shoryuken::Middleware::Chain] The middleware chain for configuration
+      # @return [Shoryuken::Middleware::Chain] The configured middleware chain
+      #
+      # @example Adding custom middleware
+      #   class MyWorker
+      #     include Shoryuken::Worker
+      #
+      #     server_middleware do |chain|
+      #       chain.add MyCustomMiddleware
+      #       chain.remove Shoryuken::Middleware::Server::ActiveRecord
+      #     end
+      #   end
       def server_middleware
         @_server_chain ||= Shoryuken.server_middleware.dup
         yield @_server_chain if block_given?
         @_server_chain
       end
 
+      # Configures worker options including queue assignment, processing behavior,
+      # and SQS-specific settings. This is the main configuration method for workers.
+      #
+      # @param opts [Hash] Configuration options for the worker
+      # @option opts [String, Array<String>] :queue Queue name(s) this worker processes
+      # @option opts [Boolean] :batch (false) Process messages in batches of up to 10
+      # @option opts [Boolean] :auto_delete (false) Automatically delete messages after processing
+      # @option opts [Boolean] :auto_visibility_timeout (false) Automatically extend message visibility
+      # @option opts [Array<Integer>] :retry_intervals Exponential backoff retry intervals in seconds
+      # @option opts [Hash] :sqs Additional SQS client options
+      #
+      # @example Basic worker configuration
+      #   class MyWorker
+      #     include Shoryuken::Worker
+      #     shoryuken_options queue: 'my_queue'
+      #
+      #     def perform(sqs_msg, body)
+      #       # Process the message
+      #     end
+      #   end
+      #
+      # @example Worker with auto-delete and retries
+      #   class ReliableWorker
+      #     include Shoryuken::Worker
+      #     shoryuken_options queue: 'important_queue',
+      #                       auto_delete: true,
+      #                       retry_intervals: [1, 5, 25, 125]
+      #   end
+      #
+      # @example Batch processing worker
+      #   class BatchWorker
+      #     include Shoryuken::Worker
+      #     shoryuken_options queue: 'batch_queue', batch: true
+      #
+      #     def perform(sqs_msgs, bodies)
+      #       # Process array of up to 10 messages
+      #       bodies.each { |body| process_item(body) }
+      #     end
+      #   end
+      #
+      # @example Multiple queues with priorities
+      #   class MultiQueueWorker
+      #     include Shoryuken::Worker
+      #     shoryuken_options queue: ['high_priority', 'low_priority']
+      #   end
+      #
+      # @example Auto-extending visibility timeout for long-running jobs
+      #   class LongRunningWorker
+      #     include Shoryuken::Worker
+      #     shoryuken_options queue: 'slow_queue',
+      #                       auto_visibility_timeout: true
+      #
+      #     def perform(sqs_msg, body)
+      #       # Long processing that might exceed visibility timeout
+      #       complex_processing(body)
+      #     end
+      #   end
       def shoryuken_options(opts = {})
         self.shoryuken_options_hash = get_shoryuken_options.merge(stringify_keys(opts || {}))
         normalize_worker_queue!
       end
 
+      # Checks if automatic visibility timeout extension is enabled for this worker.
+      # When enabled, Shoryuken automatically extends the message visibility timeout
+      # during processing to prevent the message from becoming visible to other consumers.
+      #
+      # @return [Boolean] true if auto visibility timeout is enabled
+      #
+      # @see #shoryuken_options Documentation for enabling auto_visibility_timeout
       def auto_visibility_timeout?
         !!get_shoryuken_options['auto_visibility_timeout']
       end
 
+      # Checks if exponential backoff retry is configured for this worker.
+      # When retry intervals are specified, failed jobs will be retried with
+      # increasing delays between attempts.
+      #
+      # @return [Boolean] true if retry intervals are configured
+      #
+      # @example Configuring exponential backoff
+      #   shoryuken_options retry_intervals: [1, 5, 25, 125, 625]
+      #   # Will retry after 1s, 5s, 25s, 125s, then 625s before giving up
+      #
+      # @see #shoryuken_options Documentation for configuring retry_intervals
       def exponential_backoff?
         !!get_shoryuken_options['retry_intervals']
       end
 
+      # Checks if automatic message deletion is enabled for this worker.
+      # When enabled, successfully processed messages are automatically deleted
+      # from the SQS queue. When disabled, you must manually delete messages
+      # or they will become visible again after the visibility timeout.
+      #
+      # @return [Boolean] true if auto delete is enabled
+      #
+      # @example Manual message deletion when auto_delete is false
+      #   def perform(sqs_msg, body)
+      #     process_message(body)
+      #     # Manually delete the message after successful processing
+      #     sqs_msg.delete
+      #   end
+      #
+      # @see #shoryuken_options Documentation for enabling auto_delete
       def auto_delete?
         !!(get_shoryuken_options['delete'] || get_shoryuken_options['auto_delete'])
       end

data/lib/shoryuken/worker_registry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shoryuken
   class WorkerRegistry
     def batch_receive_messages?(_queue)

data/lib/shoryuken.rb

@@ -1,38 +1,17 @@
+# frozen_string_literal: true
+
 require 'yaml'
 require 'json'
 require 'aws-sdk-sqs'
 require 'time'
 require 'concurrent'
 require 'forwardable'
+require 'zeitwerk'
 
-require 'shoryuken/version'
-require 'shoryuken/core_ext'
-require 'shoryuken/util'
-require 'shoryuken/logging'
-require 'shoryuken/environment_loader'
-require 'shoryuken/queue'
-require 'shoryuken/message'
-require 'shoryuken/client'
-require 'shoryuken/worker'
-require 'shoryuken/worker/default_executor'
-require 'shoryuken/worker/inline_executor'
-require 'shoryuken/worker_registry'
-require 'shoryuken/default_worker_registry'
-require 'shoryuken/default_exception_handler'
-require 'shoryuken/middleware/chain'
-require 'shoryuken/middleware/server/auto_delete'
-Shoryuken::Middleware::Server.autoload :AutoExtendVisibility, 'shoryuken/middleware/server/auto_extend_visibility'
-require 'shoryuken/middleware/server/exponential_backoff_retry'
-require 'shoryuken/middleware/server/timing'
-require 'shoryuken/polling/base'
-require 'shoryuken/polling/weighted_round_robin'
-require 'shoryuken/polling/strict_priority'
-require 'shoryuken/manager'
-require 'shoryuken/launcher'
-require 'shoryuken/processor'
-require 'shoryuken/body_parser'
-require 'shoryuken/fetcher'
-require 'shoryuken/options'
+# Set up Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/shoryuken/extensions")
+loader.setup
 
 module Shoryuken
   extend SingleForwardable
@@ -75,6 +54,7 @@ module Shoryuken
     :exception_handlers=,
     :options,
     :logger,
+    :logger=,
     :register_worker,
     :configure_server,
     :server?,

data/shoryuken.gemspec

@@ -1,4 +1,3 @@
-
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'shoryuken/version'
@@ -17,14 +16,15 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'aws-sdk-sqs', '>= 1.66.0'
+  spec.add_dependency 'concurrent-ruby'
+  spec.add_dependency 'thor'
+  spec.add_dependency 'zeitwerk', '~> 2.6'
+
   spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'ostruct'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
 
-  spec.add_dependency 'aws-sdk-sqs', '>= 1.66.0'
-  spec.add_dependency 'concurrent-ruby'
-  spec.add_dependency 'thor'
-
-  spec.required_ruby_version = '>= 3.0.0'
+  spec.required_ruby_version = '>= 3.1.0'
 end