activejob-retry 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5143405bed9e31a9105b3dc8d245f6e6d6b3f772
-  data.tar.gz: 029ae74c9cce202706f109991d67b07404cef2fc
+  metadata.gz: 60dfb14cc0c6a91446c784b4e8411e9aae47c7ee
+  data.tar.gz: a718488ecd619792443718c66ecea001eeeb5266
 SHA512:
-  metadata.gz: a34362c6832bf49579a692d5219d808a46ccc2a89c9ebe6b02e8a53f8158091a20ce9e546697f3b78bc7c3a9294e84ec9cf0f8fb096f4d7c444e0f54f08f22d2
-  data.tar.gz: 5b3457112e0080fd42c0e9f288b89c8fd15cf473b6ce815a801be010949ed21a8555425503dd9b5b6cf08294384ee7383039e3c12fa31231ba3774395ac985c6
+  metadata.gz: 697ffb8e3dba15591d96f1f9c65d8bd75692266c1c90e64eb527eb6bccceb0bca21838b1f348a9afcfbdb3b9634743f544bbbc98e570c12b790776fe6b5e0c3e
+  data.tar.gz: d894718b172f33037f94089b54b6cb39d62e23c2b1df82a9ff8a70a48d6665c1bdc38a62d6b5ba813243516856fc9edbe4036df28d3aaacd81b148248651d377

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.5.0 - July 23, 2015
+
+- Add exponential backoff strategy (by [@DavydenkovM](https://github.com/DavydenkovM))
+
+## 0.4.2 - March 22, 2015
+
+- Remove Sidekiq from the problematic adapter blacklist (patch by [@troter](https://github.com/troter))
+
+## 0.4.1 - March 18, 2015
+
+- Remove the need for an explicit require (patch by [@isaacseymour](https://github.com/isaacseymour))
+
 ## 0.4.0 - January 16, 2015
 
 - Blacklist problematic adapters rather than whitelisting known good ones (patch by [@isaacseymour](https://github.com/isaacseymour))

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activejob-retry (0.4.2)
+    activejob-retry (0.5.0)
       activejob (>= 4.2)
       activesupport (>= 4.2)
 
@@ -207,3 +207,6 @@ DEPENDENCIES
   sequel
   sidekiq
   sqlite3
+
+BUNDLED WITH
+   1.10.5

data/README.md

@@ -4,7 +4,7 @@ ActiveJob::Retry [![Build Status](https://travis-ci.org/gocardless/activejob-ret
 **This is an alpha library** in active development, so the API may change.
 
 Automatic retry functionality for ActiveJob. Just `include ActiveJob::Retry` in your job
-class and call one of `constant_retry`, `variable_retry`, or `retry_with` to define your
+class and call one of `constant_retry`, `variable_retry`, `exponential_retry` or `retry_with` to define your
 retry strategy:
 
 ```ruby
@@ -14,10 +14,13 @@ class ProcessWebhook < ActiveJob::Base
   queue_as :webhooks
 
   # Constant delay between attempts:
-  constant_retry limit: 3, delay: 5, retryable_exceptions: [TimeoutError, NetworkError]
+  constant_retry limit: 3, delay: 5.minutes, retryable_exceptions: [TimeoutError, NetworkError]
 
   # Or, variable delay between attempts:
-  variable_retry delays: [1, 5, 10, 30]
+  variable_retry delays: [1.minute, 5.minutes, 10.minutes, 30.minutes]
+
+  # Or, exponential delay between attempts:
+  exponential_retry limit: 25
 
   # You can also use a custom backoff strategy by passing an object which responds to
   # `should_retry?(attempt, exception)`, and `retry_delay(attempt, exception)`
@@ -48,15 +51,23 @@ if the exception is not going to be retried, or has failed the final retry.
 |:---------------------- |:------- |:-------------- |
 | `limit`                | `1`     | Maximum number of times to attempt the job (default: 1).
 | `unlimited_retries`    | `false` | If set to `true`, this job will be repeated indefinitely until in succeeds. Use with extreme caution.
-| `delay`                | `0`     | Time between attempts (default: 0).
+| `delay`                | `0`     | Time between attempts in seconds (default: 0).
 | `retryable_exceptions` | `nil`   | A whitelist of exceptions to retry. When `nil`, all exceptions will result in a retry.
 | `fatal_exceptions`     | `[]`    | A blacklist of exceptions to not retry (default: []).
 
+#### exponential_retry options
+|  Option                | Default | Description    |
+|:---------------------- |:------- |:-------------- |
+| `limit`                | `1`     | Maximum number of times to attempt the job (default: 1).
+| `unlimited_retries`    | `false` | If set to `true`, this job will be repeated indefinitely until in succeeds. Use with extreme caution.
+| `retryable_exceptions` | `nil`   | Same as for [constant_retry](#constant_retry-options).
+| `fatal_exceptions`     | `[]`    | Same as for [constant_retry](#constant_retry-options).
+
 #### variable_retry options
 
 | Option                 | Default | Description   |
 |:---------------------- |:------- |:------------- |
-| `delays`               |         | __required__ An array of delays between attempts. The first attempt will occur whenever you originally enqueued the job to happen.
+| `delays`               |         | __required__ An array of delays between attempts in seconds. The first attempt will occur whenever you originally enqueued the job to happen.
 | `min_delay_multiplier` |         | If supplied, each delay will be multiplied by a random number between this and `max_delay_multiplier`.
 | `max_delay_multiplier` |         | The other end of the range for `min_delay_multiplier`. If one is supplied, both must be.
 | `retryable_exceptions` | `nil`   | Same as for [constant_retry](#constant_retry-options).

data/lib/active_job/retry.rb

@@ -5,6 +5,7 @@ require 'active_job/retry/version'
 require 'active_job/retry/errors'
 require 'active_job/retry/constant_backoff_strategy'
 require 'active_job/retry/variable_backoff_strategy'
+require 'active_job/retry/exponential_backoff_strategy'
 
 unless ActiveJob::Base.method_defined?(:deserialize)
   require 'active_job/retry/deserialize_monkey_patch'
@@ -45,6 +46,10 @@ module ActiveJob
         retry_with(VariableBackoffStrategy.new(options))
       end
 
+      def exponential_retry(options)
+        retry_with(ExponentialBackoffStrategy.new(options))
+      end
+
       def retry_with(backoff_strategy)
         unless backoff_strategy_valid?(backoff_strategy)
           raise InvalidConfigurationError,

data/lib/active_job/retry/exponential_backoff_strategy.rb

@@ -0,0 +1,18 @@
+require 'active_job/retry/exponential_options_validator'
+
+module ActiveJob
+  module Retry
+    class ExponentialBackoffStrategy < ConstantBackoffStrategy
+      def initialize(options)
+        ExponentialOptionsValidator.new(options).validate!
+        @retry_limit          = options.fetch(:limit, 1)
+        @fatal_exceptions     = options.fetch(:fatal_exceptions, [])
+        @retryable_exceptions = options.fetch(:retryable_exceptions, nil)
+      end
+
+      def retry_delay(attempt, _exception)
+        (attempt**4 + 15 + (rand(30) * (attempt + 1))).seconds
+      end
+    end
+  end
+end

data/lib/active_job/retry/exponential_options_validator.rb

@@ -0,0 +1,79 @@
+require 'active_job/retry/errors'
+
+module ActiveJob
+  module Retry
+    class ExponentialOptionsValidator
+      def initialize(options)
+        @options = options
+      end
+
+      def validate!
+        validate_limit_numericality!
+        validate_infinite_limit!
+        validate_delay_not_specified!
+        validate_not_both_exceptions!
+        # Fatal exceptions must be an array (cannot be nil, since then all
+        # exceptions would be fatal - for that just set `limit: 0`)
+        validate_array_of_exceptions!(:fatal_exceptions)
+        # Retryable exceptions must be an array of exceptions or `nil` to retry
+        # any exception
+        if options[:retryable_exceptions]
+          validate_array_of_exceptions!(:retryable_exceptions)
+        end
+      end
+
+      private
+
+      attr_reader :options
+
+      # Limit must be an integer >= 0, or nil
+      def validate_limit_numericality!
+        return unless options[:limit]
+        return if options[:limit].is_a?(Fixnum) && options[:limit] >= 0
+
+        raise InvalidConfigurationError,
+              'Limit must be an integer >= 0, or nil for unlimited retries'
+      end
+
+      # If no limit is supplied, you *must* set `unlimited_retries: true` and
+      # understand that your ops team might hurt you.
+      def validate_infinite_limit!
+        limit = options.fetch(:limit, 1)
+        return unless limit.nil? ^ options[:unlimited_retries] == true
+
+        if limit.nil? && options[:unlimited_retries] != true
+          raise InvalidConfigurationError,
+                'You must set `unlimited_retries: true` to use `limit: nil`'
+        else
+          raise InvalidConfigurationError,
+                'You must set `limit: nil` to have unlimited retries'
+        end
+      end
+
+      # Delay must not be set
+      def validate_delay_not_specified!
+        return unless options[:delay]
+
+        raise InvalidConfigurationError,
+              'You can`t set delay for ExponentialBackoffStrategy'
+      end
+
+      def validate_not_both_exceptions!
+        return unless options[:fatal_exceptions] && options[:retryable_exceptions]
+
+        raise InvalidConfigurationError,
+              'fatal_exceptions and retryable_exceptions cannot be used together'
+      end
+
+      def validate_array_of_exceptions!(key)
+        return unless options[key]
+        if options[key].is_a?(Array) &&
+           options[key].all? { |ex| ex.is_a?(Class) && ex <= Exception }
+          return
+        end
+
+        raise InvalidConfigurationError, "#{key} must be an array of exceptions!"
+      end
+    end
+  end
+end

data/lib/active_job/retry/version.rb

@@ -1,5 +1,5 @@
 module ActiveJob
   module Retry
-    VERSION = '0.4.2'
+    VERSION = '0.5.0'
   end
 end

data/spec/retry/exponential_backoff_strategy_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+
+RSpec.describe ActiveJob::Retry::ExponentialBackoffStrategy do
+  let(:strategy) { described_class.new(options) }
+
+  describe '#should_retry?' do
+    subject { strategy.should_retry?(attempt, exception) }
+    let(:attempt) { 1 }
+    let(:exception) { RuntimeError.new }
+
+    context 'when the limit is infinite' do
+      let(:options) { { limit: nil, unlimited_retries: true } }
+
+      context '1st attempt' do
+        let(:attempt) { 1 }
+        it { is_expected.to be(true) }
+      end
+
+      context '99999th attempt' do
+        let(:attempt) { 99_999 }
+        it { is_expected.to be(true) }
+      end
+    end
+
+    context 'when the limit is 0' do
+      let(:options) { { limit: 0 } }
+
+      context '1st attempt' do
+        let(:attempt) { 1 }
+        it { is_expected.to be(false) }
+      end
+
+      context '99999th attempt' do
+        let(:attempt) { 99_999 }
+        it { is_expected.to be(false) }
+      end
+    end
+
+    context 'when the limit is 5' do
+      let(:options) { { limit: 5 } }
+
+      context '1st attempt' do
+        let(:attempt) { 1 }
+        it { is_expected.to be(true) }
+      end
+
+      context '4th attempt' do
+        let(:attempt) { 4 }
+        it { is_expected.to be(true) }
+      end
+
+      context '5th attempt' do
+        let(:attempt) { 5 }
+        it { is_expected.to be(false) }
+      end
+    end
+
+    context 'defaults (retry everything)' do
+      let(:options) { { limit: 10 } }
+
+      context 'Exception' do
+        let(:exception) { Exception.new }
+        it { is_expected.to be(true) }
+      end
+
+      context 'RuntimeError' do
+        let(:exception) { RuntimeError.new }
+        it { is_expected.to be(true) }
+      end
+
+      context 'subclass of RuntimeError' do
+        let(:exception) { Class.new(RuntimeError).new }
+        it { is_expected.to be(true) }
+      end
+    end
+
+    context 'with whitelist' do
+      let(:options) { { limit: 10, retryable_exceptions: [RuntimeError] } }
+
+      context 'Exception' do
+        let(:exception) { Exception.new }
+        it { is_expected.to be(false) }
+      end
+
+      context 'RuntimeError' do
+        let(:exception) { RuntimeError.new }
+        it { is_expected.to be(true) }
+      end
+
+      context 'subclass of RuntimeError' do
+        let(:exception) { Class.new(RuntimeError).new }
+        it { is_expected.to be(true) }
+      end
+    end
+
+    context 'with blacklist' do
+      let(:options) { { limit: 10, fatal_exceptions: [RuntimeError] } }
+
+      context 'Exception' do
+        let(:exception) { Exception.new }
+        it { is_expected.to be(true) }
+      end
+
+      context 'RuntimeError' do
+        let(:exception) { RuntimeError.new }
+        it { is_expected.to be(false) }
+      end
+
+      context 'subclass of RuntimeError' do
+        let(:exception) { Class.new(RuntimeError).new }
+        it { is_expected.to be(false) }
+      end
+    end
+  end
+
+  describe '#retry_delay' do
+    subject { strategy.retry_delay(attempt, exception) }
+    let(:exception) { RuntimeError.new }
+
+    context 'limited retries' do
+      let(:options) { { limit: 5 } }
+      let(:attempt) { 1 }
+
+      let(:attempt_3_delay) { strategy.retry_delay(attempt_3, exception) }
+      let(:attempt_5_delay) { strategy.retry_delay(attempt_5, exception) }
+
+      let(:attempt_3) { 3 }
+      let(:attempt_5) { 5 }
+
+      it 'returns value greater than previous for each of the following attempts' do
+        expect(subject).to be < attempt_3_delay
+        expect(attempt_3_delay).to be < attempt_5_delay
+      end
+    end
+
+    context 'unlimited retries' do
+      let(:options) { { limit: nil, unlimited_retries: true } }
+      let(:attempt) { 1000 }
+
+      specify { expect { subject }.to_not raise_error }
+    end
+  end
+end

data/spec/retry/exponential_options_validator_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+RSpec.describe ActiveJob::Retry::ExponentialOptionsValidator do
+  let(:validator) { described_class.new(options) }
+  subject(:validate!) { -> { validator.validate! } }
+
+  context 'valid options' do
+    context 'unlimited retries' do
+      let(:options) { { limit: nil, unlimited_retries: true } }
+      it { is_expected.to_not raise_error }
+    end
+
+    context 'no retries' do
+      let(:options) { { limit: 0 } }
+      it { is_expected.to_not raise_error }
+    end
+
+    context 'some retries' do
+      let(:options) { { limit: 3 } }
+      it { is_expected.to_not raise_error }
+    end
+
+    context 'fatal_exceptions' do
+      let(:options) { { fatal_exceptions: [RuntimeError] } }
+      it { is_expected.to_not raise_error }
+    end
+
+    context 'retryable_exceptions' do
+      let(:options) { { retryable_exceptions: [StandardError, NoMethodError] } }
+      it { is_expected.to_not raise_error }
+    end
+
+    context 'multiple options' do
+      let(:options) { { limit: 3, retryable_exceptions: [RuntimeError] } }
+
+      it { is_expected.to_not raise_error }
+    end
+  end
+
+  context 'invalid options' do
+    context 'bad limit' do
+      let(:options) { { limit: -1 } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'accidental infinite limit' do
+      let(:options) { { limit: nil } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'accidental finite limit' do
+      let(:options) { { unlimited_retries: true } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'delay provided' do
+      let(:options) { { delay: 1 } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'bad fatal_exceptions' do
+      let(:options) { { fatal_exceptions: ['StandardError'] } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'bad retryable_exceptions' do
+      let(:options) { { retryable_exceptions: [:runtime] } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+
+    context 'retry and fatal exceptions together' do
+      let(:options) { { fatal_exceptions: [StandardError], retryable_exceptions: [] } }
+      it { is_expected.to raise_error(ActiveJob::Retry::InvalidConfigurationError) }
+    end
+  end
+end

data/spec/retry_spec.rb

@@ -43,6 +43,28 @@ RSpec.describe ActiveJob::Retry do
     end
   end
 
+  describe '.exponential_retry' do
+    it 'sets an ExponentialBackoffStrategy' do
+      job.exponential_retry(limit: 10)
+      expect(job.backoff_strategy).to be_a(ActiveJob::Retry::ExponentialBackoffStrategy)
+    end
+
+    context 'invalid options' do
+      let(:options) { { limit: -2 } }
+      let(:options_with_delay) { { limit: 2, delay: 3 } }
+
+      specify do
+        expect { job.exponential_retry(options) }.
+          to raise_error(ActiveJob::Retry::InvalidConfigurationError)
+      end
+
+      specify do
+        expect { job.exponential_retry(options_with_delay) }.
+          to raise_error(ActiveJob::Retry::InvalidConfigurationError)
+      end
+    end
+  end
+
   describe '.retry_with' do
     it 'rejects invalid backoff strategies' do
       expect { job.retry_with(Object.new) }.

metadata

@@ -1,97 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: activejob-retry
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Isaac Seymour
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-22 00:00:00.000000000 Z
+date: 2015-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   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: rspec-its
   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: rubocop
   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: |2
@@ -110,10 +110,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .rubocop.yml
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -126,12 +126,16 @@ files:
 - lib/active_job/retry/constant_options_validator.rb
 - lib/active_job/retry/deserialize_monkey_patch.rb
 - lib/active_job/retry/errors.rb
+- lib/active_job/retry/exponential_backoff_strategy.rb
+- lib/active_job/retry/exponential_options_validator.rb
 - lib/active_job/retry/variable_backoff_strategy.rb
 - lib/active_job/retry/variable_options_validator.rb
 - lib/active_job/retry/version.rb
 - lib/activejob/retry.rb
 - spec/retry/constant_backoff_strategy_spec.rb
 - spec/retry/constant_options_validator_spec.rb
+- spec/retry/exponential_backoff_strategy_spec.rb
+- spec/retry/exponential_options_validator_spec.rb
 - spec/retry/variable_backoff_strategy_spec.rb
 - spec/retry/variable_options_validator_spec.rb
 - spec/retry_spec.rb
@@ -189,12 +193,12 @@ 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: []