sidekiq-rescue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f87fcb8d7e00cd287d289735c0655237d16520c298e9c96b12bbd19f745848d
+  data.tar.gz: 2be3ba005f0379b6f124974b0e464c0ac197f174952d2bb50c4be9ec4f6f979b
+SHA512:
+  metadata.gz: 0757e9ea80e869a0eb819e4147d2c65b1bb8e6763af382ae2cf5a8910172d93fafeeb96e1d9cc51af18619e26f7dae0e13b43b2b59cdc07d41ea2330b644bbce
+  data.tar.gz: 3ab9dcffcbe32a7d26b89791b0c76b1b59d46132afd779ace5d02554f95e2bd418b33ecffb05c89ced58554a25e287d6c5a6a8db13988227c65ab47bbedbd2dd

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-01-20
+
+- Initial release
+- Add DSL to configure retries and delay
+- Add middleware to rescue jobs
+- Add specs
+- Add documentation
+- Add CI
+
+[Unreleased]: https://github.com/moofkit/sidekiq-rescue/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/moofkit/sidekiq-rescue/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Dmitrii Ivliev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+# Sidekiq::Rescue
+
+[![Build Status](https://github.com/moofkit/sidekiq-rescue/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/moofkit/sidekiq-rescue/actions/workflows/main.yml)
+
+[Sidekiq](https://github.com/sidekiq/sidekiq) plugin to rescue jobs from expected errors and retry them later.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "sidekiq-rescue"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install sidekiq-rescue
+
+## Usage
+
+1. Add the middleware to your Sidekiq configuration:
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add Sidekiq::Rescue::Middleware
+  end
+end
+```
+
+2. Add DSL to your job:
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::DSL
+
+  sidekiq_rescue ExpectedError
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
+## Configuration
+
+You can configure the number of retries and the delay (in seconds) between retries:
+
+```ruby
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Rescue::DSL
+
+  sidekiq_rescue ExpectedError, delay: 60, limit: 5
+
+  def perform(*)
+    # ...
+  end
+end
+```
+
+The `delay` is not the exact time between retries, but a minimum delay. The actual delay calculates based on retries counter and `delay` value. The formula is `delay + retries * rand(10)` seconds. Randomization is used to avoid retry storms.
+
+The default values are:
+- `delay`: 60 seconds
+- `limit`: 5 retries
+
+Delay and limit can be configured globally:
+
+```ruby
+Sidekiq::Rescue.configure do |config|
+  config.delay = 65
+  config.limit = 10
+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.
+
+## 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.
+In addition, it provides a way to configure the number of retries and the delay between retries independently from the Sidekiq standard retry mechanism.
+
+## Supported Ruby versions
+
+This gem supports Ruby 2.7+
+
+If something doesn't work on one of these versions, it's a bug
+
+## Supported Sidekiq versions
+
+This gem supports Sidekiq 6.5+. It may work with older versions, but it's not tested.
+
+If you need support for older versions, please open an issue
+
+## Development
+
+To install dependencies and run tests:
+```bash
+make init
+make test
+make lint
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moofkit/sidekiq-rescue.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/sidekiq/rescue/config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Rescue
+    # Config class is used to store the configuration of Sidekiq::Rescue
+    # and to allow to configure it.
+    class Config
+      DEFAULTS = {
+        delay: 60,
+        limit: 10
+      }.freeze
+
+      def initialize
+        @delay = DEFAULTS[:delay]
+        @limit = DEFAULTS[:limit]
+        @logger = Sidekiq.logger
+      end
+
+      # Delay in seconds before retrying the job.
+      # @return [Integer, Float]
+      attr_reader :delay
+
+      # @param delay [Integer, Float] The delay in seconds before retrying the job.
+      # @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
+      end
+
+      # The maximum number of retries.
+      # @return [Integer]
+      attr_reader :limit
+
+      # @param limit [Integer] The maximum number of retries.
+      # @return [void]
+      # @raise [ArgumentError] if limit is not an Integer
+      def limit=(limit)
+        raise ArgumentError, "limit must be an Integer" unless limit.is_a?(Integer)
+
+        @limit = limit
+      end
+
+      # The logger instance.
+      # @return [Logger]
+      # @note The default logger is Sidekiq's logger.
+      attr_reader :logger
+
+      # @param logger [Logger] The logger instance.
+      # @return [void]
+      # @raise [ArgumentError] if logger is not a Logger
+      def logger=(logger)
+        raise ArgumentError, "logger must be a Logger" if !logger.nil? && !logger.respond_to?(:info)
+
+        @logger = logger
+      end
+    end
+  end
+end

data/lib/sidekiq/rescue/dsl.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Rescue
+    # This module is included into the job class to provide the DSL for
+    # configuring rescue options.
+    module DSL
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.sidekiq_class_attribute(:sidekiq_rescue_options)
+      end
+
+      # 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 limit [Integer] The maximum number of retries.
+        # @return [void]
+        # @raise [ArgumentError] if error is not a StandardError
+        # @raise [ArgumentError] if error is not an array of StandardError
+        # @raise [ArgumentError] if delay is not an Integer or Float
+        # @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)
+          validate_delay_argument(delay)
+          validate_limit_argument(limit)
+
+          self.sidekiq_rescue_options = {
+            error: error,
+            delay: delay || Sidekiq::Rescue.config.delay,
+            limit: limit || Sidekiq::Rescue.config.limit
+          }
+        end
+
+        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
+
+          raise ArgumentError,
+                "error must be an ancestor of StandardError or an array of ancestors of StandardError"
+        end
+
+        def validate_delay_argument(delay)
+          return unless delay && !delay.is_a?(Integer) && !delay.is_a?(Float)
+
+          raise ArgumentError,
+                "delay must be integer or float"
+        end
+
+        def validate_limit_argument(limit)
+          raise ArgumentError, "limit must be integer" if limit && !limit.is_a?(Integer)
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/rescue/server_middleware.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Rescue
+    # Server middleware for sidekiq-rescue
+    # It is responsible for catching the errors and rescheduling the job
+    # according to the options provided
+    # @api private
+    class ServerMiddleware
+      include Sidekiq::ServerMiddleware
+
+      def call(job_instance, job_payload, _queue, &block)
+        job_class = job_instance.class
+        options = job_class.sidekiq_rescue_options if job_class.respond_to?(:sidekiq_rescue_options)
+        if options
+          sidekiq_rescue(job_payload, **options, &block)
+        else
+          yield
+        end
+      end
+
+      private
+
+      def sidekiq_rescue(job_payload, delay:, limit:, error:, **)
+        yield
+      rescue *error => e
+        rescue_counter = job_payload["sidekiq_rescue_counter"].to_i
+        rescue_counter += 1
+        raise e if rescue_counter > limit
+
+        # 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
+
+        Sidekiq::Rescue.logger.info("[sidekiq_rescue] Job failed #{rescue_counter} times with error:" \
+                                    "#{e.message}; rescheduling at #{reschedule_at}")
+        Sidekiq::Client.push(job_payload.merge("at" => reschedule_at, "sidekiq_rescue_counter" => rescue_counter))
+      end
+    end
+  end
+end

data/lib/sidekiq/rescue/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Rescue
+    VERSION = "0.1.0"
+  end
+end

data/lib/sidekiq/rescue.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+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
+  # in your job class and use the sidekiq_rescue class method to define
+  # exception handlers.
+  #
+  #     class MyJob
+  #       include Sidekiq::Job
+  #       include Sidekiq::Rescue::DSL
+  #
+  #       sidekiq_rescue NetworkError, delay: 60, limit: 10
+  #
+  #       def perform
+  #         # ...
+  #       end
+  #     end
+  #
+  # Also it needs to be registered in Sidekiq server middleware chain:
+  #    Sidekiq.configure_server do |config|
+  #      config.server_middleware do |chain|
+  #        chain.add Sidekiq::Rescue::ServerMiddleware
+  #        ...
+  module Rescue
+    @mutex = Mutex.new
+    @config = Config.new.freeze
+
+    class << self
+      extend Forwardable
+      # Returns the logger instance
+      #
+      # @return [Logger] The logger instance.
+      def_delegators :config, :logger
+
+      # @return [Sidekiq::Rescue::Config] The configuration object.
+      attr_reader :config
+
+      # Configures Sidekiq::Rescue
+      # @return [void]
+      # @yieldparam config [Sidekiq::Rescue::Config] The configuration object.
+      # @example
+      #  Sidekiq::Rescue.configure do |config|
+      #    config.delay = 10
+      #    config.limit = 5
+      #    config.logger = Logger.new($stdout)
+      #  end
+      def configure
+        @mutex.synchronize do
+          config = @config.dup
+          yield(config)
+          @config = config.freeze
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq-rescue.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "sidekiq_rescue"

data/lib/sidekiq_rescue.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+require "forwardable"
+require_relative "sidekiq/rescue/config"
+require_relative "sidekiq/rescue"
+require_relative "sidekiq/rescue/version"
+require_relative "sidekiq/rescue/dsl"
+require_relative "sidekiq/rescue/server_middleware"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: sidekiq-rescue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dmitrii Ivliev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.5'
+description:
+email:
+- mail@ivda.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sidekiq-rescue.rb
+- lib/sidekiq/rescue.rb
+- lib/sidekiq/rescue/config.rb
+- lib/sidekiq/rescue/dsl.rb
+- lib/sidekiq/rescue/server_middleware.rb
+- lib/sidekiq/rescue/version.rb
+- lib/sidekiq_rescue.rb
+homepage: https://github.com/moofkit/sidekiq-rescue
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Rescue Sidekiq jobs on expected error and reschedule them
+test_files: []