activejob-retry 0.0.1 → 0.1.1

data/activejob-retry.gemspec

@@ -1,7 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'active_job/retry/version'
+require File.expand_path('../lib/active_job/retry/version', __FILE__)
 
 Gem::Specification.new do |s|
   s.name = 'activejob-retry'
@@ -9,24 +6,24 @@ Gem::Specification.new do |s|
   s.date = Date.today.strftime('%Y-%m-%d')
   s.authors = ['Isaac Seymour']
   s.email = ['isaac@isaacseymour.co.uk']
-  s.summary = 'Automatic retrying DSL for ActiveJob'
+  s.summary = 'Automatic retry functionality for ActiveJob.'
   s.description = <<-EOL
-    activejob-retry provides a simple DSL for automatically retrying ActiveJobs when they
-    fail, with exponential backoff.
+    activejob-retry provides automatic retry functionality for failed
+    ActiveJobs, with exponential backoff.
 
     Features:
 
-    * (Should) work with any queue adapter that supports retries.
+    * Works with any queue adapter that supports retries.
     * Whitelist/blacklist exceptions to retry on.
     * Exponential backoff (varying the delay between retries).
     * Light and easy to override retry logic.
   EOL
-  s.homepage = 'http://github.com/isaacseymour/activejob-retry'
+  s.homepage = 'http://github.com/gocardless/activejob-retry'
   s.license = 'MIT'
 
   s.has_rdoc = false
-  s.files = `git ls-files`.split($/)
-  s.require_paths = %w[lib]
+  s.files = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  s.require_paths = %w(lib)
 
   s.add_dependency('activejob', '>= 4.2')
   s.add_dependency('activesupport', '>= 4.2')
@@ -34,5 +31,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency('rake', ' >= 10.3')
   s.add_development_dependency('rspec')
   s.add_development_dependency('rspec-its')
-  s.add_development_dependency('pry-byebug')
+  s.add_development_dependency('rubocop')
 end

data/lib/active_job/retry.rb

@@ -1,87 +1,73 @@
+require 'active_job'
+require 'active_support'
+require 'active_support/core_ext' # ActiveJob uses core exts, but doesn't require it
+require 'active_job/retry/version'
+require 'active_job/retry/errors'
+require 'active_job/retry/constant_backoff_strategy'
+require 'active_job/retry/variable_backoff_strategy'
+
+unless ActiveJob::Base.method_defined?(:deserialize)
+  require 'active_job/retry/deserialize_monkey_patch'
+end
+
 module ActiveJob
   module Retry
-    class UnsupportedAdapterError < StandardError; end
-    SUPPORTED_ADAPTERS = %i(backburner delayed_job que resque sidekiq).freeze
-
-    # If you want your job to retry on failure, simply include this module in your class,
-    #
-    #   class DeliverWebHook < ActiveJob::Base
-    #     include ActiveJob::Retry
-    #     queue_as :web_hooks
-    #
-    #     retry_with limit: 8,                         # default 1
-    #                delay: 60,                        # default 0
-    #                fatal_exceptions: [RuntimeError], # default [], i.e. none
-    #                retry_exceptions: [TimeoutError]  # default nil, i.e. all
-    #
-    #     def perform(url, web_hook_id, hmac_key)
-    #       work!
-    #     end
-    #   end
+    SUPPORTED_ADAPTERS = [
+      'ActiveJob::QueueAdapters::BackburnerAdapter',
+      'ActiveJob::QueueAdapters::DelayedJobAdapter',
+      'ActiveJob::QueueAdapters::ResqueAdapter',
+      'ActiveJob::QueueAdapters::QueAdapter'
+    ].freeze
+
     def self.included(base)
-      # This breaks all specs because the adapter gets set after class eval :(
-      # unless SUPPORTED_ADAPTERS.include?(ActiveJob::Base.queue_adapter)
-      #   raise UnsupportedAdapterError,
-      #         "Only Backburner, DelayedJob, Que, Resque, and Sidekiq support delayed " \
-      #         "retries. #{ActiveJob::Base.queue_adapter} is not supported."
-      # end
+      unless SUPPORTED_ADAPTERS.include?(ActiveJob::Base.queue_adapter.to_s)
+        raise UnsupportedAdapterError,
+              'Only Backburner, DelayedJob, Que, and Resque support delayed ' \
+              "retries. #{ActiveJob::Base.queue_adapter} is not supported."
+      end
 
       base.extend(ClassMethods)
     end
 
-    module ClassMethods
-      # Setup DSL
-      def retry_with(options)
-        OptionsValidator.new(options).validate!
-
-        @retry_limit      = options[:limit]            if options[:limit]
-        @retry_delay      = options[:delay]            if options[:delay]
-        @fatal_exceptions = options[:fatal_exceptions] if options[:fatal_exceptions]
-        @retry_exceptions = options[:retry_exceptions] if options[:retry_exceptions]
-      end
+    #################
+    # Configuration #
+    #################
 
-      ############
-      # Defaults #
-      ############
-      def retry_limit
-        @retry_limit ||= 1
-      end
-
-      def retry_delay
-        @retry_delay ||= 0
-      end
+    module ClassMethods
+      attr_reader :backoff_strategy
 
-      def fatal_exceptions
-        @fatal_exceptions ||= []
+      def constant_retry(options)
+        retry_with(ConstantBackoffStrategy.new(options))
       end
 
-      def retry_exceptions
-        @retry_exceptions ||= nil
+      def variable_retry(options)
+        retry_with(VariableBackoffStrategy.new(options))
       end
 
-      #################
-      # Retry helpers #
-      #################
-      def retry_exception?(exception)
-        return true if retry_exceptions.nil? && fatal_exceptions.empty?
-        return exception_whitelisted?(exception) unless retry_exceptions.nil?
-        !exception_blacklisted?(exception)
-      end
+      def retry_with(backoff_strategy)
+        unless backoff_strategy_valid?(backoff_strategy)
+          raise InvalidConfigurationError,
+                'Backoff strategies must define `should_retry?(attempt, exception)`, ' \
+                'and `retry_delay(attempt, exception)`.'
+        end
 
-      def exception_whitelisted?(exception)
-        retry_exceptions.any? { |ex| exception.is_a?(ex) }
+        @backoff_strategy = backoff_strategy
       end
 
-      def exception_blacklisted?(exception)
-        fatal_exceptions.any? { |ex| exception.is_a?(ex) }
+      def backoff_strategy_valid?(backoff_strategy)
+        backoff_strategy.respond_to?(:should_retry?) &&
+          backoff_strategy.respond_to?(:retry_delay) &&
+          backoff_strategy.method(:should_retry?).arity == 2 &&
+          backoff_strategy.method(:retry_delay).arity == 2
       end
     end
 
-    #############
-    # Overrides #
-    #############
+    #############################
+    # Storage of attempt number #
+    #############################
+
     def serialize
-      super.merge('retry_attempt' => retry_attempt + 1)
+      super.merge('retry_attempt' => retry_attempt)
     end
 
     def deserialize(job_data)
@@ -89,42 +75,35 @@ module ActiveJob
       @retry_attempt = job_data['retry_attempt']
     end
 
-    # Override `rescue_with_handler` to make sure our catch is the last one, and doesn't
-    # happen if the exception has already been caught in a `rescue_from`
-    def rescue_with_handler(exception)
-      super || retry_or_reraise(exception)
-    end
-
-    ##################
-    # Retrying logic #
-    ##################
     def retry_attempt
-      @retry_attempt ||= 0
+      @retry_attempt ||= 1
     end
 
-    # Override me if you want more complex behaviour
-    def retry_delay
-      self.class.retry_delay
-    end
+    ##########################
+    # Performing the retries #
+    ##########################
 
-    def should_retry?(exception)
-      return false if retry_limit_reached?
-      return false unless self.class.retry_exception?(exception)
-      true
+    # Override `rescue_with_handler` to make sure our catch is the last one, and doesn't
+    # happen if the exception has already been caught in a `rescue_from`
+    def rescue_with_handler(exception)
+      super || retry_or_reraise(exception)
     end
 
-    def retry_limit_reached?
-      return true if self.class.retry_limit == 0
-      return false if self.class.retry_limit == -1
-      retry_attempt >= self.class.retry_limit
-    end
+    private
 
     def retry_or_reraise(exception)
-      raise exception unless should_retry?(exception)
+      unless self.class.backoff_strategy.should_retry?(retry_attempt, exception)
+        raise exception
+      end
 
-      this_delay = retry_delay
-      logger.log(Logger::INFO, "Retrying (attempt #{retry_attempt + 1}, waiting #{this_delay}s)")
+      this_delay = self.class.backoff_strategy.retry_delay(retry_attempt, exception)
+      # TODO: This breaks DelayedJob and Resque for some weird ActiveSupport reason.
+      # logger.log(Logger::INFO,
+      #            "Retrying (attempt #{retry_attempt + 1}, waiting #{this_delay}s)")
+      @retry_attempt += 1
       retry_job(wait: this_delay)
+
+      true # Exception has been handled
     end
   end
 end

data/lib/active_job/retry/constant_backoff_strategy.rb

@@ -0,0 +1,50 @@
+require 'active_job/retry/constant_options_validator'
+
+module ActiveJob
+  module Retry
+    class ConstantBackoffStrategy
+      def initialize(options)
+        ConstantOptionsValidator.new(options).validate!
+        @retry_limit      = options.fetch(:limit, 1)
+        @retry_delay      = options.fetch(:delay, 0)
+        @fatal_exceptions = options.fetch(:fatal_exceptions, [])
+        @retry_exceptions = options.fetch(:retry_exceptions, nil)
+      end
+
+      def should_retry?(attempt, exception)
+        return false if retry_limit_reached?(attempt)
+        return false unless retry_exception?(exception)
+        true
+      end
+
+      def retry_delay(_attempt, _exception)
+        @retry_delay
+      end
+
+      private
+
+      attr_reader :retry_limit, :fatal_exceptions, :retry_exceptions
+
+      def retry_limit_reached?(attempt)
+        return false unless retry_limit
+        attempt >= retry_limit
+      end
+
+      def retry_exception?(exception)
+        if retry_exceptions.nil?
+          !exception_blacklisted?(exception)
+        else
+          exception_whitelisted?(exception)
+        end
+      end
+
+      def exception_whitelisted?(exception)
+        retry_exceptions.any? { |ex| exception.is_a?(ex) }
+      end
+
+      def exception_blacklisted?(exception)
+        fatal_exceptions.any? { |ex| exception.is_a?(ex) }
+      end
+    end
+  end
+end

data/lib/active_job/retry/constant_options_validator.rb

@@ -0,0 +1,76 @@
+require 'active_job/retry/errors'
+
+module ActiveJob
+  module Retry
+    class ConstantOptionsValidator
+      def initialize(options)
+        @options = options
+      end
+
+      def validate!
+        validate_limit_numericality!
+        validate_infinite_limit!
+        validate_delay!
+        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)
+        # Retry exceptions must be an array of exceptions or `nil` to retry any exception
+        validate_array_of_exceptions!(:retry_exceptions) if options[:retry_exceptions]
+      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 be non-negative
+      def validate_delay!
+        return unless options[:delay]
+        return if options[:delay] >= 0
+
+        raise InvalidConfigurationError, 'Delay must be non-negative'
+      end
+
+      def validate_not_both_exceptions!
+        return unless options[:fatal_exceptions] && options[:retry_exceptions]
+
+        raise InvalidConfigurationError,
+              'fatal_exceptions and retry_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/deserialize_monkey_patch.rb

@@ -4,19 +4,24 @@
 # of the deserialization as possible to the instance, i.e. `ActiveJob::Base#deserialize`,
 # which can be overridden. This allows us to store extra information in the queue (i.e.
 # retry_attempt), which is essential for ActiveJob::Retry.
+#
+# This monkey patch is automatically applied if necessary when ActiveJob::Retry is
+# required.
 
-raise "Unnecessary monkey patch!" if ActiveJob::Base.method_defined?(:deserialize)
+raise 'Unnecessary monkey patch!' if ActiveJob::Base.method_defined?(:deserialize)
 
-class ActiveJob::Base
-  def self.deserialize(job_data)
-    job = job_data['job_class'].constantize.new
-    job.deserialize(job_data)
-    job
-  end
+module ActiveJob
+  class Base
+    def self.deserialize(job_data)
+      job = job_data['job_class'].constantize.new
+      job.deserialize(job_data)
+      job
+    end
 
-  def deserialize(job_data)
-    self.job_id               = job_data['job_id']
-    self.queue_name           = job_data['queue_name']
-    self.serialized_arguments = job_data['arguments']
+    def deserialize(job_data)
+      self.job_id               = job_data['job_id']
+      self.queue_name           = job_data['queue_name']
+      self.serialized_arguments = job_data['arguments']
+    end
   end
-end
+end

data/lib/active_job/retry/errors.rb

@@ -0,0 +1,6 @@
+module ActiveJob
+  module Retry
+    class InvalidConfigurationError < StandardError; end
+    class UnsupportedAdapterError < StandardError; end
+  end
+end

data/lib/active_job/retry/variable_backoff_strategy.rb

@@ -0,0 +1,34 @@
+require 'active_job/retry/constant_backoff_strategy'
+require 'active_job/retry/variable_options_validator'
+
+module ActiveJob
+  module Retry
+    class VariableBackoffStrategy < ConstantBackoffStrategy
+      def initialize(options)
+        super(options)
+        VariableOptionsValidator.new(options).validate!
+        @retry_limit          = options.fetch(:delays).length + 1
+        @retry_delays         = options.fetch(:delays)
+        @min_delay_multiplier = options.fetch(:min_delay_multiplier, 1.0)
+        @max_delay_multiplier = options.fetch(:max_delay_multiplier, 1.0)
+      end
+
+      def retry_delay(attempt, _exception)
+        (retry_delays[attempt - 1] * delay_multiplier).to_i
+      end
+
+      private
+
+      attr_reader :retry_delays, :min_delay_multiplier, :max_delay_multiplier
+
+      def random_delay?
+        min_delay_multiplier != max_delay_multiplier
+      end
+
+      def delay_multiplier
+        return max_delay_multiplier unless random_delay?
+        rand(min_delay_multiplier..max_delay_multiplier)
+      end
+    end
+  end
+end