sidekiq-rescue 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f87fcb8d7e00cd287d289735c0655237d16520c298e9c96b12bbd19f745848d
-  data.tar.gz: 2be3ba005f0379b6f124974b0e464c0ac197f174952d2bb50c4be9ec4f6f979b
+  metadata.gz: d1a8899e388b21924f60017c1eb3b724bc129bec25c96f4765a37ab1f1d8e7fb
+  data.tar.gz: 41c934da18716cf917af164e92ce1bccdcab1a5bbce08df1c4cbf6550d5cfe70
 SHA512:
-  metadata.gz: 0757e9ea80e869a0eb819e4147d2c65b1bb8e6763af382ae2cf5a8910172d93fafeeb96e1d9cc51af18619e26f7dae0e13b43b2b59cdc07d41ea2330b644bbce
-  data.tar.gz: 3ab9dcffcbe32a7d26b89791b0c76b1b59d46132afd779ace5d02554f95e2bd418b33ecffb05c89ced58554a25e287d6c5a6a8db13988227c65ab47bbedbd2dd
+  metadata.gz: a644feb9b9c4d3e1eef97d24738b1157c7efc370102d3db19db3df23f2133382878a264818b5a9a99059e1f64e9b60cbe8e4ea8b297757a760e00fb1df71865b
+  data.tar.gz: 678d83f42a1ffff8dd71def36911fcdc42b7cf2186e053e47b02c9d4237ea51efc2bd10ed003c7909ec830006b3e725b5e64253faca3c0d4555d97a8536be114

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.2.1] - 2024-02-27
+
+- Fix readme with correct middleware name
+- Add RSpec matchers
+
+## [0.2.0] - 2024-02-03
+
+- Rename `Sidekiq::Rescue::DSL` to `Sidekiq::Rescue::Dsl`
+- Update the `delay` option to now accept a proc as an argument
+- Update dsl to accept a list of errors
+
 ## [0.1.0] - 2024-01-20
 
 - Initial release
@@ -9,5 +20,7 @@
 - Add documentation
 - Add CI
 
-[Unreleased]: https://github.com/moofkit/sidekiq-rescue/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/moofkit/sidekiq-rescue/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/moofkit/sidekiq-rescue/releases/tag/v0.2.1
+[0.2.0]: https://github.com/moofkit/sidekiq-rescue/releases/tag/v0.2.0
 [0.1.0]: https://github.com/moofkit/sidekiq-rescue/releases/tag/v0.1.0

data/README.md

@@ -27,7 +27,7 @@ Or install it yourself as:
 ```ruby
 Sidekiq.configure_server do |config|
   config.server_middleware do |chain|
-    chain.add Sidekiq::Rescue::Middleware
+    chain.add Sidekiq::Rescue::ServerMiddleware
   end
 end
 ```
@@ -37,7 +37,7 @@ end
 ```ruby
 class MyJob
   include Sidekiq::Job
-  include Sidekiq::Rescue::DSL
+  include Sidekiq::Rescue::Dsl
 
   sidekiq_rescue ExpectedError
 
@@ -54,7 +54,7 @@ You can configure the number of retries and the delay (in seconds) between retri
 ```ruby
 class MyJob
   include Sidekiq::Job
-  include Sidekiq::Rescue::DSL
+  include Sidekiq::Rescue::Dsl
 
   sidekiq_rescue ExpectedError, delay: 60, limit: 5
 
@@ -79,10 +79,148 @@ Sidekiq::Rescue.configure do |config|
 end
 ```
 
+You can also configure a job to have the delay to be a proc:
+
+```ruby
+sidekiq_rescue ExpectedError, delay: ->(counter) { counter * 60 }
+```
+
+or globally:
+
+```ruby
+Sidekiq::Rescue.configure do |config|
+  config.delay = ->(counter) { counter * 60 }
+end
+```
+
+### Testing
+
+1. Unit tests (recommended)
+
+In case you want to test the rescue configuration, this gem provides RSpec matchers:
+
+```ruby
+RSpec.cofigure do |config|
+  config.include Sidekiq::Rescue::RSpec::Matchers, type: :job
+end
+
+RSpec.describe MyJob do
+  it "rescues from expected errors" do
+    expect(MyJob).to have_sidekiq_rescue(ExpectedError)
+  end
+end
+```
+
+It also provides a way to test the delay and limit:
+
+```ruby
+RSpec.describe MyJob do
+  it "rescues from expected errors with custom delay and limit" do
+    expect(MyJob).to have_sidekiq_rescue(ExpectedError).with_delay(60).with_limit(5)
+  end
+end
+```
+
+2. Integration tests with `Sidekiq::Testing`
+Firstly, you need to configure `Sidekiq::Testing` to use `Sidekiq::Rescue::ServerMiddleware` middleware:
+
+```ruby
+# spec/spec_helper.rb or spec/rails_helper.rb
+require "sidekiq/testing"
+
+RSpec.configure do |config|
+  config.before(:all) do
+    Sidekiq::Testing.fake!
+
+    Sidekiq::Testing.server_middleware do |chain|
+      chain.add Sidekiq::Rescue::ServerMiddleware
+    end
+  end
+end
+```
+
+And test the job with the next snippet
+
+```ruby
+# spec/jobs/my_job_spec.rb
+RSpec.describe MyJob do
+  before do
+    allow(ApiClient).to receive(:new).and_raise(ApiClient::SomethingWentWrongError)
+  end
+
+  it "retries job if it fails with ExpectedError" do
+    MyJob.perform_async('test')
+    expect { MyJob.perform_one }.not_to raise_error # pefrom_one is a method from Sidekiq::Testing that runs the job once
+  end
+end
+```
+
 ## Use cases
 
 Sidekiq::Rescue is useful when you want to retry jobs that failed due to expected errors and not spam your exception tracker with these errors. For example, you may want to retry a job that failed due to a network error or a temporary outage of a third party service, rather than a bug in your code.
 
+## Examples
+
+### Retry a job that may failed due to a network error
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::Dsl
+
+  sidekiq_rescue Faraday::ConnectionFailed
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
+### Retry a job that may failed due to different errors
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::Dsl
+
+  sidekiq_rescue Faraday::ConnectionFailed, Faraday::TimeoutError
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
+### Retry a job that may failed due to different errors with custom delay
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::Dsl
+
+  sidekiq_rescue Faraday::ConnectionFailed, Faraday::TimeoutError, delay: 60
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
+### Retry a job that may failed due to different errors with custom delays and limits
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::Dsl
+
+  sidekiq_rescue Faraday::ConnectionFailed, Faraday::TimeoutError, delay: 60, limit: 5
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
 ## Motivation
 
 Sidekiq provides a retry mechanism for jobs that failed due to unexpected errors. However, it does not provide a way to retry jobs that failed due to expected errors. This gem aims to fill this gap.

data/lib/sidekiq/rescue/config.rb

@@ -24,9 +24,12 @@ module Sidekiq
       # @return [void]
       # @raise [ArgumentError] if delay is not an Integer or Float
       def delay=(delay)
-        raise ArgumentError, "delay must be an Integer or Float" unless delay.is_a?(Integer) || delay.is_a?(Float)
-
-        @delay = delay
+        case delay
+        when Integer, Float, Proc
+          @delay = delay
+        else
+          raise ArgumentError, "delay must be Integer, Float or Proc"
+        end
       end
 
       # The maximum number of retries.

data/lib/sidekiq/rescue/dsl.rb

@@ -2,20 +2,20 @@
 
 module Sidekiq
   module Rescue
-    # This module is included into the job class to provide the DSL for
+    # This module is included into the job class to provide the Dsl for
     # configuring rescue options.
-    module DSL
+    module Dsl
       def self.included(base)
         base.extend(ClassMethods)
         base.sidekiq_class_attribute(:sidekiq_rescue_options)
       end
 
-      # Module containing the DSL methods
+      # Module containing the Dsl methods
       module ClassMethods
         # Configure rescue options for the job.
         # @param error [StandardError] The error class to rescue.
         # @param error [Array<StandardError>] The error classes to rescue.
-        # @param delay [Integer] The delay in seconds before retrying the job.
+        # @param delay [Integer, Float, Proc] The delay in seconds before retrying the job.
         # @param limit [Integer] The maximum number of retries.
         # @return [void]
         # @raise [ArgumentError] if error is not a StandardError
@@ -24,8 +24,8 @@ module Sidekiq
         # @raise [ArgumentError] if limit is not an Integer
         # @example
         #  sidekiq_rescue NetworkError, delay: 60, limit: 10
-        def sidekiq_rescue(error, delay: nil, limit: nil)
-          validate_error_argument(error)
+        def sidekiq_rescue(*error, delay: nil, limit: nil)
+          error = validate_and_unpack_error_argument(error)
           validate_delay_argument(delay)
           validate_limit_argument(limit)
 
@@ -38,23 +38,26 @@ module Sidekiq
 
         private
 
-        def validate_error_argument(error)
-          error_arg_valid = if error.is_a?(Array)
-                              error.all? { |e| e < StandardError }
-                            else
-                              error < StandardError
-                            end
-          return if error_arg_valid
+        def validate_and_unpack_error_argument(error)
+          error_arg_valid = error.any? && error.flatten.all? { |e| e < StandardError } if error.is_a?(Array)
+          return error.flatten if error_arg_valid
 
           raise ArgumentError,
-                "error must be an ancestor of StandardError or an array of ancestors of StandardError"
+                "error must be an ancestor of StandardError"
         end
 
         def validate_delay_argument(delay)
-          return unless delay && !delay.is_a?(Integer) && !delay.is_a?(Float)
+          return if delay.nil?
+          return if delay.is_a?(Integer) || delay.is_a?(Float)
+
+          if delay.is_a?(Proc)
+            raise ArgumentError, "delay proc must accept counter as argument" if delay.arity.zero?
+
+            return
+          end
 
           raise ArgumentError,
-                "delay must be integer or float"
+                "delay must be integer, float or proc"
         end
 
         def validate_limit_argument(limit)
@@ -62,5 +65,9 @@ module Sidekiq
         end
       end
     end
+    # Alias for Dsl; TODO: remove in 1.0.0
+    # @deprecated
+    # @see Dsl
+    DSL = Dsl
   end
 end

data/lib/sidekiq/rescue/rspec/matchers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+return unless defined?(RSpec)
+
+require "rspec/matchers"
+
+module Sidekiq
+  module Rescue
+    module RSpec
+      # RSpec matchers for Sidekiq::Rescue
+      module Matchers
+        ::RSpec::Matchers.define :have_sidekiq_rescue do |expected| # rubocop:disable Metrics/BlockLength
+          description { "be rescueable with #{expected}" }
+          failure_message do |actual|
+            str = "expected #{actual} to be rescueable with #{expected}"
+            str += " and delay #{@delay}" if @delay
+            str += " and limit #{@limit}" if @limit
+            str
+          end
+          failure_message_when_negated { |actual| "expected #{actual} not to be rescueable with #{expected}" }
+
+          chain :with_delay do |delay|
+            @delay = delay
+          end
+
+          chain :with_limit do |limit|
+            @limit = limit
+          end
+
+          match do |actual|
+            actual.is_a?(Class) &&
+              actual.include?(Sidekiq::Rescue::Dsl) &&
+              actual.sidekiq_rescue_options[:error].include?(expected) &&
+              (@delay.nil? || actual.sidekiq_rescue_options[:delay] == @delay) &&
+              (@limit.nil? || actual.sidekiq_rescue_options[:limit] == @limit)
+          end
+
+          match_when_negated do |actual|
+            raise NotImplementedError, "it's confusing to use `not_to be_rescueable` with `with_delay`" if @delay
+            raise NotImplementedError, "it's confusing to use `not_to be_rescueable` with `with_limit`" if @limit
+
+            actual.is_a?(Class) &&
+              actual.include?(Sidekiq::Rescue::Dsl) &&
+              !actual.sidekiq_rescue_options[:error].include?(expected)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/rescue/server_middleware.rb

@@ -24,18 +24,35 @@ module Sidekiq
       def sidekiq_rescue(job_payload, delay:, limit:, error:, **)
         yield
       rescue *error => e
+        rescue_counter = increment_rescue_counter(job_payload)
+        raise e if rescue_counter > limit
+
+        reschedule_at = calculate_reschedule_time(delay, rescue_counter)
+        log_reschedule_info(rescue_counter, e, reschedule_at)
+        reschedule_job(job_payload, reschedule_at, rescue_counter)
+      end
+
+      def increment_rescue_counter(job_payload)
         rescue_counter = job_payload["sidekiq_rescue_counter"].to_i
         rescue_counter += 1
-        raise e if rescue_counter > limit
+        rescue_counter
+      end
 
+      def calculate_reschedule_time(delay, rescue_counter)
         # NOTE: we use the retry counter to increase the jitter
         # so that the jobs don't retry at the same time
         # inspired by sidekiq https://github.com/sidekiq/sidekiq/blob/73c150d0430a8394cadb5cd49218895b113613a0/lib/sidekiq/job_retry.rb#L188
         jitter = rand(10) * rescue_counter
-        reschedule_at = Time.now.to_f + delay + jitter
+        delay = delay.call(rescue_counter) if delay.is_a?(Proc)
+        Time.now.to_f + delay + jitter
+      end
+
+      def log_reschedule_info(rescue_counter, error, reschedule_at)
+        Sidekiq::Rescue.logger.info("[sidekiq_rescue] Job failed #{rescue_counter} times with error: " \
+                                    "#{error.message}; rescheduling at #{reschedule_at}")
+      end
 
-        Sidekiq::Rescue.logger.info("[sidekiq_rescue] Job failed #{rescue_counter} times with error:" \
-                                    "#{e.message}; rescheduling at #{reschedule_at}")
+      def reschedule_job(job_payload, reschedule_at, rescue_counter)
         Sidekiq::Client.push(job_payload.merge("at" => reschedule_at, "sidekiq_rescue_counter" => rescue_counter))
       end
     end

data/lib/sidekiq/rescue/version.rb

@@ -2,6 +2,6 @@
 
 module Sidekiq
   module Rescue
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/sidekiq/rescue.rb

@@ -4,13 +4,13 @@ module Sidekiq
   # Sidekiq::Rescue is a Sidekiq plugin which allows you to easily handle
   # exceptions thrown by your jobs.
   #
-  # To use Sidekiq::Rescue, you need to include Sidekiq::Rescue::DSL module
+  # To use Sidekiq::Rescue, you need to include Sidekiq::Rescue::Dsl module
   # in your job class and use the sidekiq_rescue class method to define
   # exception handlers.
   #
   #     class MyJob
   #       include Sidekiq::Job
-  #       include Sidekiq::Rescue::DSL
+  #       include Sidekiq::Rescue::Dsl
   #
   #       sidekiq_rescue NetworkError, delay: 60, limit: 10
   #

data/lib/sidekiq_rescue.rb

@@ -7,3 +7,4 @@ require_relative "sidekiq/rescue"
 require_relative "sidekiq/rescue/version"
 require_relative "sidekiq/rescue/dsl"
 require_relative "sidekiq/rescue/server_middleware"
+require_relative "sidekiq/rescue/rspec/matchers"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-rescue
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dmitrii Ivliev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-21 00:00:00.000000000 Z
+date: 2024-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sidekiq
@@ -39,6 +39,7 @@ files:
 - lib/sidekiq/rescue.rb
 - lib/sidekiq/rescue/config.rb
 - lib/sidekiq/rescue/dsl.rb
+- lib/sidekiq/rescue/rspec/matchers.rb
 - lib/sidekiq/rescue/server_middleware.rb
 - lib/sidekiq/rescue/version.rb
 - lib/sidekiq_rescue.rb
@@ -49,6 +50,7 @@ metadata:
   homepage_uri: https://github.com/moofkit/sidekiq-rescue
   source_code_uri: https://github.com/moofkit/sidekiq-rescue
   changelog_uri: https://github.com/moofkit/sidekiq-rescue/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/sidekiq-rescue/0.2.1
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []