Merge branch 'main' into instrumentation-system

Author: mensfeld

CHANGELOG.md

@@ -1,4 +1,17 @@
 ## [7.0.0] - Unreleased
+- Breaking: Add `Shoryuken::Errors` module with domain-specific error classes
+  - Introduces `Shoryuken::Errors::BaseError` as base class for all Shoryuken errors
+  - `Shoryuken::Errors::QueueNotFoundError` for non-existent or inaccessible SQS queues
+  - `Shoryuken::Errors::InvalidConfigurationError` for configuration validation failures
+  - `Shoryuken::Errors::InvalidWorkerRegistrationError` for worker registration conflicts
+  - `Shoryuken::Errors::InvalidPollingStrategyError` for invalid polling strategy configuration
+  - `Shoryuken::Errors::InvalidEventError` for invalid lifecycle event names
+  - `Shoryuken::Errors::InvalidDelayError` for delays exceeding SQS 15-minute maximum
+  - `Shoryuken::Errors::InvalidArnError` for invalid ARN format
+  - `Shoryuken::Errors::Shutdown` for graceful shutdown (replaces `Shoryuken::Shutdown`)
+  - Replaces generic Ruby exceptions (ArgumentError, RuntimeError) with specific error types
+  - Code rescuing `Shoryuken::Shutdown` must change to `Shoryuken::Errors::Shutdown`
+
 - Fix: Raise ArgumentError when using delay with FIFO queues
   - FIFO queues do not support per-message DelaySeconds
   - Previously caused confusing AWS errors with ActiveJob's `retry_on` (Rails 6.1+ defaults to `wait: 3.seconds`)

lib/shoryuken/default_worker_registry.rb

@@ -56,10 +56,10 @@ def queues
     # @param queue [String] the queue name
     # @param clazz [Class] the worker class to register
     # @return [Class] the registered worker class
-    # @raise [ArgumentError] if a batchable worker is already registered for the queue
+    # @raise [Errors::InvalidWorkerRegistrationError] if a batchable worker is already registered for the queue
     def register_worker(queue, clazz)
       if (worker_class = @workers[queue]) && (worker_class.get_shoryuken_options['batch'] == true || clazz.get_shoryuken_options['batch'] == true)
-        fail ArgumentError, "Could not register #{clazz} for #{queue}, "\
+        raise Errors::InvalidWorkerRegistrationError, "Could not register #{clazz} for #{queue}, "\
           "because #{worker_class} is already registered for this queue, "\
           "and Shoryuken doesn't support a batchable worker for a queue with multiple workers"
       end

lib/shoryuken/environment_loader.rb

@@ -80,7 +80,7 @@ def initialize_options
     def config_file_options
       return {} unless (path = options[:config_file])
 
-      fail ArgumentError, "The supplied config file #{path} does not exist" unless File.exist?(path)
+      raise Errors::InvalidConfigurationError, "The supplied config file #{path} does not exist" unless File.exist?(path)
 
       if (result = YAML.load(ERB.new(IO.read(path)).result))
         Shoryuken::Helpers::HashUtils.deep_symbolize_keys(result)
@@ -248,10 +248,7 @@ def validate_queues
         It's also possible that you don't have permission to access the specified queues.
       MSG
 
-      fail(
-        ArgumentError,
-        error_msg
-      )
+      raise Errors::QueueNotFoundError, error_msg
     end
 
     # Validates that all queues have registered workers

lib/shoryuken/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Shoryuken
+  # Namespace for all Shoryuken-specific errors.
+  # These provide more meaningful error types than generic Ruby exceptions,
+  # making it easier to rescue and handle specific failure cases.
+  module Errors
+    # Base class for all Shoryuken errors
+    BaseError = Class.new(StandardError)
+
+    # Raised when there is a configuration validation failure
+    InvalidConfigurationError = Class.new(BaseError)
+
+    # Raised when a specified SQS queue does not exist or cannot be accessed
+    QueueNotFoundError = Class.new(BaseError)
+
+    # Raised when worker registration fails due to conflicts
+    # (e.g., registering multiple workers for a batch queue)
+    InvalidWorkerRegistrationError = Class.new(BaseError)
+
+    # Raised when an invalid polling strategy is specified
+    InvalidPollingStrategyError = Class.new(BaseError)
+
+    # Raised when an invalid lifecycle event name is used
+    InvalidEventError = Class.new(BaseError)
+
+    # Raised when a delay exceeds the maximum allowed by SQS (15 minutes)
+    InvalidDelayError = Class.new(BaseError)
+
+    # Raised when an ARN format is invalid
+    InvalidArnError = Class.new(BaseError)
+
+    # Exception raised to trigger graceful shutdown of the server
+    # @see https://github.com/mperham/sidekiq/blob/33f5d6b2b6c0dfaab11e5d39688cab7ebadc83ae/lib/sidekiq/cli.rb#L20
+    Shutdown = Class.new(Interrupt)
+  end
+end

lib/shoryuken/options.rb

@@ -119,7 +119,7 @@ def polling_strategy(group)
         begin
           Object.const_get(strategy)
         rescue NameError
-          raise ArgumentError, "#{strategy} is not a valid polling_strategy"
+          raise Errors::InvalidPollingStrategyError, "#{strategy} is not a valid polling_strategy"
         end
       when Class
         strategy
@@ -267,8 +267,8 @@ def on_stop(&block)
     #     end
     #   end
     def on(event, &block)
-      fail ArgumentError, "Symbols only please: #{event}" unless event.is_a?(Symbol)
-      fail ArgumentError, "Invalid event name: #{event}" unless options[:lifecycle_events].key?(event)
+      raise Errors::InvalidEventError, "Symbols only please: #{event}" unless event.is_a?(Symbol)
+      raise Errors::InvalidEventError, "Invalid event name: #{event}" unless options[:lifecycle_events].key?(event)
 
       options[:lifecycle_events][event] << block
     end

lib/shoryuken/queue.rb

@@ -149,7 +149,7 @@ def arn_to_url(arn_str)
       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
@@ -177,8 +177,8 @@ def set_name_and_url(name_or_url_or_arn) # rubocop:disable Naming/AccessorMethod
       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

lib/shoryuken/runner.rb

@@ -9,10 +9,6 @@
 require 'shoryuken'
 
 module Shoryuken
-  # Exception raised to trigger shutdown
-  # @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

lib/shoryuken/worker/default_executor.rb

@@ -37,15 +37,15 @@ def perform_async(worker_class, body, 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
-        # @raise [RuntimeError] if delay exceeds 15 minutes
+        # @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
           ts = (interval < 1_000_000_000 ? (now + interval).to_f : interval)
 
           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

spec/lib/shoryuken/environment_loader_spec.rb

@@ -24,7 +24,7 @@
     context "when given queues don't exist" do
       specify do
         expect { subject.load }.to raise_error(
-          ArgumentError,
+          Shoryuken::Errors::QueueNotFoundError,
           <<-MSG.gsub(/^\s+/, '')
             The specified queue(s) stubbed_queue do not exist.
             Try 'shoryuken sqs create QUEUE-NAME' for creating a queue with default settings.

spec/lib/shoryuken/options_spec.rb

@@ -188,8 +188,8 @@ def perform(sqs_msg, body); end
       end
 
       specify do
-        expect { Shoryuken.polling_strategy('default') }.to raise_error(ArgumentError)
-        expect { Shoryuken.polling_strategy('group1') }.to raise_error(ArgumentError)
+        expect { Shoryuken.polling_strategy('default') }.to raise_error(Shoryuken::Errors::InvalidPollingStrategyError)
+        expect { Shoryuken.polling_strategy('group1') }.to raise_error(Shoryuken::Errors::InvalidPollingStrategyError)
       end
     end