rescue_like_a_pro 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 381039cc44e8aabc625166b7d946c9f43af4ecc5118145ee8fe0d21d3adc1ba5
+  data.tar.gz: f05a0235ccf2228cd9eb9aad18352a67c35f02bba482ffb28fbc6857204f56a5
+SHA512:
+  metadata.gz: b00b75eee64fe164bf675642e7ad9c2d48812c1b2dcdcf13215ff0bb35f1de5466f50f9287a7dee81b0fbdd0fc62acc3dbd3eee00a663e7b2712c440d6708e80
+  data.tar.gz: 2b06313d25b86045a64eeac6a0a459d8f2ef84bfd05c565367565be45b524b5ead85f4b5d7d0ecc71ca22e19aa00efc1740caa3536f68dc4c7fbcaef0803481c

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2022 thomas morgan
+
+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,128 @@
+# RescueLikeAPro
+
+RescueLikeAPro rethinks ActiveJob's exception handling system by:
+* Improving usage with class inheritance and mixins
+* Adding fallback retries exhausted and discard handlers
+* Making jitter computation more flexible
+
+
+### Primary differences from standard ActiveJob
+
+* Exceptions are always matched in order of most-specific to least-specific, regardless of the order of definition.
+
+  This allows for a more natural inheritance mechanism. It also eliminates ordering issues when using mixins.
+
+  ```ruby
+  class ApplicationJob < ActiveJob::Base
+    discard_on ActiveJob::DeserializationError
+  end
+  class SomeJob < ApplicationJob
+    retry_on StandardError, attempts: 5
+  end
+  ```
+
+  With ActiveJob's default exception handling, `DeserializationError`s will never be discarded by `SomeJob` because exceptions are processed from last to first. Since `DeserializationError` is a type of `StandardError`, `retry_on` will see it, reattempt 5 times, then trigger retries-exhausted--which in this case, without a block on `retry_on`, will bubble the error upward.
+
+  In contrast, RescueLikeAPro will recognize that `DeserializationError` is a more specific type of `StandardError` and will discard it immediately, while still retrying all other types of
+  `StandardError`s.
+
+  Child classes may, of course, still redefine handling for an exception previously defined in a parent.
+
+  When redefining an exception, the new rules (:attempts, :wait, etc) fully replace the previous ones. They are not merged.
+
+* As a byproduct of the above, when two or more exceptions are defined together, retry attempts are counted per-exception class, and not in combination.
+
+  ```ruby
+  retry_on FirstError, SecondError, attempts: 5
+  ```
+
+  Here, ActiveJob natively allows for 5 combined `FirstError` and `SecondError`s. In contrast, RescueLikeAPro will allow for 5 of each.
+
+  There is no behavior change when defining only a single exception per `retry_on`.
+
+* Default handlers for retries-exhausted and discard are added at the job-class level. These are used as defaults when individual retry_on and discard_on calls don't specify their own block. These are properly inheritable from parent to child job classes.
+
+* Specifying `retry_on(jitter: nil)` uses the default `retry_jitter` instead of becoming `0.0`. `jitter: 0` still works as expected.
+
+  For values < 1.0, ActiveJob's default behavior of adding a multiple of extra time remains the same. For example, Rails 6.1+'s default value of 0.15 adds between 0-15% extra time to the calculated `:wait` time.
+
+  RescueLikeAPro also recognizes ranges, which are treated as a seconds to be added to `:wait` (or subtracted if negative). Scalar values >= 1 are treated like the range `0..n`.
+
+  ```ruby
+  self.retry_jitter = 0.05   # Adds 0-5% of jitter
+  self.retry_jitter = 5..10  # Adds 5 to 10 seconds of jitter
+  self.retry_jitter = -5..5  # Adds -5 to -5 seconds of jitter
+  self.retry_jitter = 30     # Adds 0 to 30 seconds of jitter
+  self.retry_jitter = 1.hour # Adds 0 to 3600 seconds of jitter
+  ```
+
+* Jitter is applied to all retries. In contrast, ActiveJob skips jitter when `:wait` is a Proc.
+
+
+### Example syntax
+
+```ruby
+class SomeJob < ApplicationJob
+  discard_on ActiveJob::DeserializationError
+  discard_on ApiError do |job, error|
+    # Called when job is discarded
+  end
+
+  retry_on SomeError, attempts: 5
+  retry_on AnotherError do |job, error|
+    # Called when retries are exhausted
+  end
+end
+
+class ApplicationJob
+  # All of these work on individual job classes as well. Job class definitions take precedence over parent classes like here.
+
+  self.retry_jitter = 0.15      # Rails default: add 0-15% extra
+  self.retry_jitter = 7.seconds # Add 0-7 seconds extra
+
+  on_discard do |job, error|
+    # Add a default handler when a job is discarded. Only used when discard_on did not define a handler.
+  end
+
+  on_retries_exhausted do |job, error|
+    # Add a default handler when retries are exhausted. Only used when retry_on did not define a handler.
+  end
+end
+```
+
+
+## Usage
+
+With Rails, RescueLikeAPro automatically initializes itself. Simply add it to your Gemfile.
+
+If you want to modify behavior of every job, *including* Rails' built-in jobs, add an initializer:
+
+```ruby
+class ActiveJob::Base
+  # self.retry_jitter = 7.seconds
+  # on_discard{ ... }
+  # on_retries_exhausted{ ... }
+  # etc
+```
+
+Otherwise, to just modify all of your app's jobs, add instructions to `app/jobs/application_job.rb`.
+
+And of course, add any per-Job instructions directly to that job class.
+
+
+## Installation
+
+As usual, add RescueLikeAPro to your Gemfile:
+
+```ruby
+gem "rescue_like_a_pro"
+```
+
+
+## Contributing
+
+Pull requests welcomed. If unsure whether a proposed addition is in scope, feel free to open an Issue for discussion (not required though).
+
+
+## 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 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/rescue_like_a_pro/active_job.rb

@@ -0,0 +1,116 @@
+module RescueLikeAPro::ActiveJob
+  extend ActiveSupport::Concern
+
+
+  prepended do
+    rescue_from Exception, with: :rescue_like_a_pro
+
+    class_attribute :retries_exhausted_handler, instance_writer: false, instance_predicate: false
+    class_attribute :discard_handler, instance_writer: false, instance_predicate: false
+    class_attribute :rescue_pro_rules, instance_writer: false, instance_predicate: false, default: {}
+      # {'Module::SomeException' => {..rules..}, ...}
+  end
+
+  module ClassMethods
+
+    def retry_on(*exceptions, wait: 3.seconds, attempts: 5, queue: nil, priority: nil, jitter: nil, &block)
+      exception_map = exceptions.each_with_object({}) do |exception, h|
+        h[exception.to_s] = { action: :retry_on, wait: wait, attempts: attempts, queue: queue, priority: priority, jitter: jitter, handler: block }
+      end
+      self.rescue_pro_rules = rescue_pro_rules.merge exception_map
+    end
+
+    def discard_on(*exceptions, &block)
+      exception_map = exceptions.each_with_object({}) do |exception, h|
+        h[exception.to_s] = { action: :discard_on, handler: block }
+      end
+      self.rescue_pro_rules = rescue_pro_rules.merge exception_map
+    end
+
+    def on_retries_exhausted(&block)
+      self.retries_exhausted_handler = block
+    end
+
+    def on_discard(&block)
+      self.discard_handler = block
+    end
+
+  end
+
+
+  private
+
+  def rescue_like_a_pro(error)
+    rules = lookup_handler(error)
+    executions = executions_for([error])
+    case rules[:action]
+    when :retry_on
+      jitter = rules[:jitter] || self.class.retry_jitter
+      if rules[:attempts] == :unlimited || executions < rules[:attempts]
+        retry_job(
+          wait:     determine_delay(seconds_or_duration_or_algorithm: rules[:wait], executions: executions, jitter: jitter),
+          queue:    rules[:queue],
+          priority: rules[:priority],
+          error:    error
+        )
+        return
+      else
+        handler  = rules[:handler] || retries_exhausted_handler
+        inst_key = :retry_stopped
+      end
+    when :discard_on
+      handler  = rules[:handler] || discard_handler || proc{}
+      inst_key = :discard
+    end
+    if handler
+      instrument inst_key, error: error do
+        handler.call(*[self, error].take(handler.arity))
+      end
+    else
+      instrument inst_key, error: error
+      raise error
+    end
+    nil
+  end
+
+  def lookup_handler(exception)
+    ex = exception.class
+    while ex
+      if r = rescue_pro_rules[ex.to_s]
+        return r
+      end
+      ex = ex.superclass
+    end
+    raise exception
+  end
+
+  def determine_delay(seconds_or_duration_or_algorithm:, executions:, jitter: nil)
+    case seconds_or_duration_or_algorithm
+    when :exponentially_longer
+      delay = executions**4
+      delay_jitter = determine_jitter_for_delay(delay, jitter)
+      delay + delay_jitter + 2
+    when ActiveSupport::Duration, Integer
+      delay = seconds_or_duration_or_algorithm.to_i
+      delay_jitter = determine_jitter_for_delay(delay, jitter)
+      delay + delay_jitter
+    when Proc
+      algorithm = seconds_or_duration_or_algorithm
+      delay = algorithm.call(executions)
+      delay_jitter = determine_jitter_for_delay(delay, jitter)
+      delay + delay_jitter
+    else
+      raise "Couldn't determine a delay based on #{seconds_or_duration_or_algorithm.inspect}"
+    end
+  end
+
+  def determine_jitter_for_delay(delay, jitter)
+    if jitter.is_a?(Range) || jitter >= 1.0
+      Kernel.rand jitter
+    else
+      return 0.0 if jitter.zero?
+      Kernel.rand * delay * jitter
+    end
+  end
+
+end

data/lib/rescue_like_a_pro/railtie.rb

@@ -0,0 +1,9 @@
+module RescueLikeAPro
+  class Railtie < ::Rails::Railtie
+
+    ActiveSupport.on_load(:active_job) do
+      prepend RescueLikeAPro::ActiveJob
+    end
+
+  end
+end

data/lib/rescue_like_a_pro/version.rb

@@ -0,0 +1,3 @@
+module RescueLikeAPro
+  VERSION = "1.0.0"
+end

data/lib/rescue_like_a_pro.rb

@@ -0,0 +1,5 @@
+%w(active_job version).each do |f|
+  require "rescue_like_a_pro/#{f}"
+end
+
+require "rescue_like_a_pro/railtie" if defined?(::Rails)

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: rescue_like_a_pro
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- thomas morgan
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: RescueLikeAPro rethinks ActiveJob's exception handling system to improve
+  usage with class inheritance and mixins, add fallback retries exhausted and discard
+  handlers, and improve jitter flexibility.
+email:
+- tm@iprog.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rescue_like_a_pro.rb
+- lib/rescue_like_a_pro/active_job.rb
+- lib/rescue_like_a_pro/railtie.rb
+- lib/rescue_like_a_pro/version.rb
+homepage: https://github.com/zarqman/rescue_like_a_pro
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zarqman/rescue_like_a_pro
+  source_code_uri: https://github.com/zarqman/rescue_like_a_pro
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Improve ActiveJob exception handling with inheritance, fallback handlers,
+  more jitter options, etc.
+test_files: []