shoryuken 7.0.0.alpha2 → 7.0.0

data/lib/shoryuken/worker.rb

@@ -1,56 +1,244 @@
 # 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
+    # Sets up the including class with Shoryuken worker functionality
+    #
+    # @param base [Class] the class including this module
+    # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
       base.shoryuken_class_attribute :shoryuken_options_hash
     end
 
+    # Class methods added to classes that include Shoryuken::Worker.
+    # Provides methods for configuring the worker, enqueueing jobs, and managing middleware.
     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] SQS message options for the delayed job
+      # @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 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
 
+      # Returns the shoryuken options for this worker class
+      # @return [Hash] the options hash
       def get_shoryuken_options # :nodoc:
         shoryuken_options_hash || Shoryuken.default_worker_options
       end
 
+      # Converts hash keys to strings
+      # @param hash [Hash] the hash to convert
+      # @return [Hash] hash with string keys
       def stringify_keys(hash) # :nodoc:
         new_hash = {}
         hash.each { |key, value| new_hash[key.to_s] = value }
         new_hash
       end
 
+      # Defines inheritable class attributes for workers
+      # @param attrs [Array<Symbol>] attribute names to define
+      # @return [void]
       def shoryuken_class_attribute(*attrs) # :nodoc:
         attrs.each do |name|
           singleton_class.instance_eval do
@@ -108,6 +296,8 @@ module Shoryuken
 
       private
 
+      # Normalizes the queue option and registers the worker
+      # @return [void]
       def normalize_worker_queue!
         queue = shoryuken_options_hash['queue']
         if queue.respond_to?(:call)
@@ -125,6 +315,9 @@ module Shoryuken
         [shoryuken_options_hash['queue']].flatten.compact.each(&method(:register_worker))
       end
 
+      # Registers this worker class for a queue
+      # @param queue [String] the queue name
+      # @return [void]
       def register_worker(queue)
         Shoryuken.register_worker(queue, self)
       end

data/lib/shoryuken/worker_registry.rb

@@ -1,33 +1,66 @@
 # frozen_string_literal: true
 
 module Shoryuken
+  # Abstract base class for worker registries.
+  # Defines the interface for storing and retrieving worker classes.
+  # @abstract Subclass and implement all methods to create a custom registry
   class WorkerRegistry
+    # Checks if the workers for a queue support batch message processing
+    #
+    # @param _queue [String] the queue name
+    # @return [Boolean] true if batch processing is supported
+    # @raise [NotImplementedError] if not implemented by subclass
     def batch_receive_messages?(_queue)
       # true if the workers for queue support batch processing of messages
       fail NotImplementedError
     end
 
+    # Removes all worker registrations
+    #
+    # @return [void]
+    # @raise [NotImplementedError] if not implemented by subclass
     def clear
       # must remove all worker registrations
       fail NotImplementedError
     end
 
+    # Fetches a worker instance for processing a message
+    #
+    # @param _queue [String] the queue name
+    # @param _message [Shoryuken::Message, Array<Shoryuken::Message>] the message or batch
+    # @return [Object] a worker instance
+    # @raise [NotImplementedError] if not implemented by subclass
     def fetch_worker(_queue, _message)
       # must return an instance of the worker that handles
       # message received on queue
       fail NotImplementedError
     end
 
+    # Returns a list of all queues with registered workers
+    #
+    # @return [Array<String>] the queue names
+    # @raise [NotImplementedError] if not implemented by subclass
     def queues
       # must return a list of all queues with registered workers
       fail NotImplementedError
     end
 
+    # Registers a worker class for a queue
+    #
+    # @param _queue [String] the queue name
+    # @param _clazz [Class] the worker class
+    # @return [void]
+    # @raise [NotImplementedError] if not implemented by subclass
     def register_worker(_queue, _clazz)
       # must register the worker as a consumer of messages from queue
       fail NotImplementedError
     end
 
+    # Returns all worker classes registered for a queue
+    #
+    # @param _queue [String] the queue name
+    # @return [Array<Class>] the worker classes, or empty array
+    # @raise [NotImplementedError] if not implemented by subclass
     def workers(_queue)
       # must return the list of workers registered for queue, or []
       fail NotImplementedError

data/lib/shoryuken.rb

@@ -1,25 +1,37 @@
 # frozen_string_literal: true
 
-require 'yaml'
-require 'json'
 require 'aws-sdk-sqs'
+require 'json'
+require 'logger'
 require 'time'
 require 'concurrent'
 require 'forwardable'
 require 'zeitwerk'
+require 'yaml'
 
 # Set up Zeitwerk loader
 loader = Zeitwerk::Loader.for_gem
-loader.ignore("#{__dir__}/shoryuken/extensions")
+loader.ignore("#{__dir__}/active_job")
 loader.setup
 
+# Shoryuken is a super efficient AWS SQS thread based message processor.
+# It provides a simple interface to process SQS messages using Ruby workers.
 module Shoryuken
   extend SingleForwardable
 
+  # Returns the global Shoryuken configuration options instance.
+  # This is used internally for storing and accessing configuration settings.
+  #
+  # @return [Shoryuken::Options] The global options instance
   def self.shoryuken_options
     @_shoryuken_options ||= Shoryuken::Options.new
   end
 
+  # Checks if the Shoryuken server is running and healthy.
+  # A server is considered healthy when all configured processing groups
+  # are running and able to process messages.
+  #
+  # @return [Boolean] true if the server is healthy
   def self.healthy?
     Shoryuken::Runner.instance.healthy?
   end
@@ -77,7 +89,7 @@ module Shoryuken
 end
 
 if Shoryuken.active_job?
-  require 'shoryuken/extensions/active_job_extensions'
-  require 'shoryuken/extensions/active_job_adapter'
-  require 'shoryuken/extensions/active_job_concurrent_send_adapter'
+  require 'active_job/extensions'
+  require 'active_job/queue_adapters/shoryuken_adapter'
+  require 'active_job/queue_adapters/shoryuken_concurrent_send_adapter'
 end

data/renovate.json

@@ -3,14 +3,41 @@
   "extends": [
     "config:recommended"
   ],
+  "minimumReleaseAge": "7 days",
   "github-actions": {
     "enabled": true,
     "pinDigests": true
   },
+  "bundler": {
+    "enabled": true,
+    "managerFilePatterns": [
+      "/(^|/)Gemfile$/",
+      "/\\.gemfile$/",
+      "/(^|/)gems\\.rb$/",
+      "/spec/gemfiles/.+\\.gemfile$/",
+      "/spec/integration/.*/Gemfile$/"
+    ]
+  },
   "packageRules": [
     {
-      "matchManagers": ["github-actions"],
-      "minimumReleaseAge": "7 days"
+      "matchManagers": [
+        "bundler"
+      ],
+      "matchFileNames": [
+        "spec/gemfiles/**"
+      ],
+      "groupName": "Rails test dependencies",
+      "description": "Group Rails version-specific test Gemfiles together"
+    },
+    {
+      "matchManagers": [
+        "bundler"
+      ],
+      "matchFileNames": [
+        "spec/integration/**/Gemfile"
+      ],
+      "groupName": "Integration test dependencies",
+      "description": "Group integration test Gemfiles together"
     }
   ]
 }

data/shoryuken.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'ostruct'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'warning'
 
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.2.0'
 end

data/spec/integration/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/spec/integration/active_job/adapter_configuration/configuration_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# This spec tests ActiveJob adapter configuration including adapter type,
+# Rails 7.2+ transaction commit hook, and singleton pattern.
+
+setup_active_job
+
+class ConfigTestJob < ActiveJob::Base
+  queue_as :config_test
+
+  def perform(data)
+    "Processed: #{data}"
+  end
+end
+
+adapter = ActiveJob::Base.queue_adapter
+assert_equal("ActiveJob::QueueAdapters::ShoryukenAdapter", adapter.class.name)
+
+adapter_instance = ActiveJob::QueueAdapters::ShoryukenAdapter.new
+assert(adapter_instance.respond_to?(:enqueue_after_transaction_commit?))
+assert_equal(true, adapter_instance.enqueue_after_transaction_commit?)
+
+instance1 = ActiveJob::QueueAdapters::ShoryukenAdapter.instance
+instance2 = ActiveJob::QueueAdapters::ShoryukenAdapter.instance
+assert_equal(instance1.object_id, instance2.object_id)
+assert(instance1.is_a?(ActiveJob::QueueAdapters::ShoryukenAdapter))

data/spec/integration/active_job/bulk_enqueue/bulk_enqueue_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Bulk enqueue integration test
+# Tests perform_all_later with the new enqueue_all method using SQS batch API
+
+setup_localstack
+setup_active_job
+
+queue_name = DT.queue
+create_test_queue(queue_name)
+
+class BulkTestJob < ActiveJob::Base
+  def perform(index, data)
+    DT[:executions] << {
+      index: index,
+      data: data,
+      job_id: job_id,
+      executed_at: Time.now
+    }
+  end
+end
+
+BulkTestJob.queue_as(queue_name)
+
+Shoryuken.add_group('default', 1)
+Shoryuken.add_queue(queue_name, 1, 'default')
+Shoryuken.register_worker(queue_name, Shoryuken::ActiveJob::JobWrapper)
+
+jobs = (1..15).map { |i| BulkTestJob.new(i, "payload_#{i}") }
+
+# Use perform_all_later which should call enqueue_all
+ActiveJob.perform_all_later(jobs)
+
+successfully_enqueued_count = jobs.count(&:successfully_enqueued?)
+assert_equal(15, successfully_enqueued_count, "Expected all 15 jobs to be marked as successfully enqueued")
+
+poll_queues_until(timeout: 45) do
+  DT[:executions].size >= 15
+end
+
+assert_equal(15, DT[:executions].size, "Expected 15 job executions, got #{DT[:executions].size}")
+
+executed_indices = DT[:executions].map { |e| e[:index] }.sort
+expected_indices = (1..15).to_a
+assert_equal(expected_indices, executed_indices, "All job indices should be present")
+
+DT[:executions].each do |execution|
+  expected_data = "payload_#{execution[:index]}"
+  assert_equal(expected_data, execution[:data], "Job #{execution[:index]} should have correct data")
+end
+
+job_ids = DT[:executions].map { |e| e[:job_id] }
+assert_equal(15, job_ids.uniq.size, "All job IDs should be unique")

data/spec/integration/active_job/current_attributes/bulk_enqueue_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# CurrentAttributes are persisted correctly when using bulk enqueue (perform_all_later)
+
+setup_localstack
+setup_active_job
+
+require 'active_support/current_attributes'
+require 'shoryuken/active_job/current_attributes'
+
+queue_name = DT.queue
+create_test_queue(queue_name)
+
+class TestCurrent < ActiveSupport::CurrentAttributes
+  attribute :user_id, :tenant_id
+end
+
+Shoryuken::ActiveJob::CurrentAttributes.persist(TestCurrent)
+
+class BulkCurrentAttributesTestJob < ActiveJob::Base
+  def perform(index)
+    DT[:executions] << {
+      index: index,
+      user_id: TestCurrent.user_id,
+      tenant_id: TestCurrent.tenant_id
+    }
+  end
+end
+
+BulkCurrentAttributesTestJob.queue_as(queue_name)
+
+Shoryuken.add_group('default', 1)
+Shoryuken.add_queue(queue_name, 1, 'default')
+Shoryuken.register_worker(queue_name, Shoryuken::ActiveJob::JobWrapper)
+
+TestCurrent.user_id = 'bulk-user-123'
+TestCurrent.tenant_id = 'bulk-tenant'
+
+jobs = (1..3).map { |i| BulkCurrentAttributesTestJob.new(i) }
+ActiveJob.perform_all_later(jobs)
+
+TestCurrent.reset
+
+poll_queues_until(timeout: 30) { DT[:executions].size >= 3 }
+
+assert_equal(3, DT[:executions].size)
+DT[:executions].each do |job|
+  assert_equal('bulk-user-123', job[:user_id])
+  assert_equal('bulk-tenant', job[:tenant_id])
+end

data/spec/integration/active_job/current_attributes/complex_types_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# CurrentAttributes with complex data types (hashes, arrays, symbols) are serialized and restored
+
+setup_localstack
+setup_active_job
+
+require 'active_support/current_attributes'
+require 'shoryuken/active_job/current_attributes'
+
+queue_name = DT.queue
+create_test_queue(queue_name)
+
+class TestCurrent < ActiveSupport::CurrentAttributes
+  attribute :user_id, :tenant_id
+end
+
+Shoryuken::ActiveJob::CurrentAttributes.persist(TestCurrent)
+
+class ComplexTypesTestJob < ActiveJob::Base
+  def perform
+    DT[:executions] << {
+      user_id: TestCurrent.user_id,
+      tenant_id: TestCurrent.tenant_id
+    }
+  end
+end
+
+ComplexTypesTestJob.queue_as(queue_name)
+
+Shoryuken.add_group('default', 1)
+Shoryuken.add_queue(queue_name, 1, 'default')
+Shoryuken.register_worker(queue_name, Shoryuken::ActiveJob::JobWrapper)
+
+TestCurrent.user_id = { role: :admin, permissions: [:read, :write, :delete] }
+TestCurrent.tenant_id = [:tenant_a, :tenant_b]
+
+ComplexTypesTestJob.perform_later
+
+TestCurrent.reset
+
+poll_queues_until(timeout: 30) { DT[:executions].size >= 1 }
+
+result = DT[:executions].first
+
+user_data = result[:user_id]
+assert(user_data.is_a?(Hash))
+role = user_data['role'] || user_data[:role]
+assert_equal('admin', role.to_s)
+permissions = user_data['permissions'] || user_data[:permissions]
+assert_equal(3, permissions.size)
+
+tenant_data = result[:tenant_id]
+assert(tenant_data.is_a?(Array))
+assert_equal(2, tenant_data.size)

data/spec/integration/active_job/current_attributes/empty_context_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# CurrentAttributes without any values set result in nil attributes during job execution
+
+setup_localstack
+setup_active_job
+
+require 'active_support/current_attributes'
+require 'shoryuken/active_job/current_attributes'
+
+queue_name = DT.queue
+create_test_queue(queue_name)
+
+class TestCurrent < ActiveSupport::CurrentAttributes
+  attribute :user_id, :tenant_id
+end
+
+Shoryuken::ActiveJob::CurrentAttributes.persist(TestCurrent)
+
+class EmptyContextTestJob < ActiveJob::Base
+  def perform
+    DT[:executions] << {
+      user_id: TestCurrent.user_id,
+      tenant_id: TestCurrent.tenant_id
+    }
+  end
+end
+
+EmptyContextTestJob.queue_as(queue_name)
+
+Shoryuken.add_group('default', 1)
+Shoryuken.add_queue(queue_name, 1, 'default')
+Shoryuken.register_worker(queue_name, Shoryuken::ActiveJob::JobWrapper)
+
+EmptyContextTestJob.perform_later
+
+poll_queues_until(timeout: 30) { DT[:executions].size >= 1 }
+
+result = DT[:executions].first
+assert(result[:user_id].nil?)
+assert(result[:tenant_id].nil?)