resque-retry 0.0.5 → 0.0.6

data/HISTORY.md

@@ -1,3 +1,7 @@
+## 0.0.6 (2010-07-11)
+
+* Feature: Added support for custom retry criteria check callbacks.
+
 ## 0.0.5 (2010-06-27)
 
 * Handle our own dependancies.

data/README.md

@@ -105,6 +105,36 @@ it so only specific exceptions are retried using `retry_exceptions`:
 The above modification will **only** retry if a `NetworkError` (or subclass)
 exception is thrown.
 
+### Custom Retry Criteria Check Callbacks
+
+You may define custom retry criteria callbacks:
+
+    class TurkWorker
+      extend Resque::Plugins::Retry
+      @queue = :turk_job_processor
+
+      @retry_exceptions = [NetworkError]
+
+      retry_criteria_check do |exception, *args|
+        if exception.message =~ /InvalidJobId/
+          false # don't retry if we got passed a invalid job id.
+        else
+          true  # its okay for a retry attempt to continue.
+        end
+      end
+
+      def self.perform(job_id)
+        heavy_lifting
+      end
+    end
+
+Similar to the previous example, this job will retry if either a
+`NetworkError` (or subclass) exception is thrown **or** any of the callbacks
+return true.
+
+Use `@retry_exceptions = []` to **only** use callbacks, to determine if the
+job should retry.
+
 Customise & Extend
 ------------------
 

data/lib/resque/plugins/exponential_backoff.rb

@@ -1,7 +1,6 @@
 module Resque
   module Plugins
 
-    ##
     # If you want your job to retry on failure using a varying delay, simply
     # extend your module/class with this module:
     #
@@ -38,7 +37,6 @@ module Resque
     module ExponentialBackoff
       include Resque::Plugins::Retry
 
-      ##
       # Defaults to the number of delays in the backoff strategy.
       #
       # @return [Number] maximum number of retries
@@ -46,7 +44,6 @@ module Resque
         @retry_limit ||= backoff_strategy.length
       end
 
-      ##
       # Selects the delay from the backoff strategy.
       #
       # @return [Number] seconds to delay until the next retry.
@@ -54,7 +51,6 @@ module Resque
         backoff_strategy[retry_attempt] || backoff_strategy.last
       end
 
-      ##
       # @abstract
       # The backoff strategy is used to vary the delay between retry attempts.
       # 

data/lib/resque/plugins/retry.rb

@@ -1,7 +1,6 @@
 module Resque
   module Plugins
 
-    ##
     # If you want your job to retry on failure, simply extend your module/class
     # with this module:
     #
@@ -34,7 +33,13 @@ module Resque
     #   end
     #
     module Retry
-      ##
+
+      # Copy retry criteria checks on inheritance.
+      def inherited(subclass)
+        super(subclass)
+        subclass.instance_variable_set("@retry_criteria_checks", retry_criteria_checks.dup)
+      end
+
       # @abstract You may override to implement a custom identifier,
       #           you should consider doing this if your job arguments
       #           are many/long or may not cleanly cleanly to strings.
@@ -49,7 +54,6 @@ module Resque
         args_string.empty? ? nil : args_string
       end
 
-      ##
       # Builds the redis key to be used for keeping state of the job
       # attempts.
       #
@@ -58,7 +62,6 @@ module Resque
         ['resque-retry', name, identifier(*args)].compact.join(":").gsub(/\s/, '')
       end
 
-      ##
       # Maximum number of retrys we can attempt to successfully perform the job.
       # A retry limit of 0 or below will retry forever.
       #
@@ -67,7 +70,6 @@ module Resque
         @retry_limit ||= 1
       end
 
-      ##
       # Number of retry attempts used to try and perform the job.
       #
       # The real value is kept in Redis, it is accessed and incremented using
@@ -78,7 +80,6 @@ module Resque
         @retry_attempt ||= 0
       end
 
-      ##
       # @abstract
       # Number of seconds to delay until the job is retried.
       # 
@@ -87,7 +88,6 @@ module Resque
         @retry_delay ||= 0
       end
 
-      ##
       # @abstract
       # Modify the arguments used to retry the job. Use this to do something
       # other than try the exact same job again.
@@ -97,7 +97,6 @@ module Resque
         args
       end
 
-      ##
       # Convenience method to test whether you may retry on a given exception.
       #
       # @return [Boolean]
@@ -106,7 +105,6 @@ module Resque
         !! retry_exceptions.any? { |ex| ex >= exception }
       end
 
-      ##
       # @abstract
       # Controls what exceptions may be retried.
       #
@@ -117,21 +115,68 @@ module Resque
         @retry_exceptions ||= nil
       end
 
-      ##
       # Test if the retry criteria is valid.
       #
       # @param [Exception] exception
       # @param [Array] args job arguments
       # @return [Boolean]
       def retry_criteria_valid?(exception, *args)
-        # FIXME: let people extend retry criteria, give them a chance to say no.
+        # if the retry limit was reached, dont bother checking anything else.
+        return false if retry_limit_reached?
+
+        # We always want to retry if the exception matches.
+        should_retry = retry_exception?(exception.class)
+
+        # call user retry criteria check blocks.
+        retry_criteria_checks.each do |criteria_check|
+          should_retry ||= !!criteria_check.call(exception, *args)
+        end
+
+        should_retry
+      end
+
+      # Retry criteria checks.
+      #
+      # @return [Array]
+      def retry_criteria_checks
+        @retry_criteria_checks ||= []
+        @retry_criteria_checks
+      end
+
+      # Test if the retry limit has been reached.
+      #
+      # @return [Boolean]
+      def retry_limit_reached?
         if retry_limit > 0
-          return false if retry_attempt >= retry_limit
+          return true if retry_attempt >= retry_limit
         end
-        retry_exception?(exception.class)
+        false
+      end
+
+      # Register a retry criteria check callback to be run before retrying
+      # the job again.
+      #
+      # If any callback returns `true`, the job will be retried.
+      #
+      # @example Using a custom retry criteria check.
+      #
+      #   retry_criteria_check do |exception, *args|
+      #     if exception.message =~ /InvalidJobId/
+      #       # don't retry if we got passed a invalid job id.
+      #       false
+      #     else
+      #       true
+      #     end
+      #   end
+      #
+      # @yield [exception, *args]
+      # @yieldparam exception [Exception] the exception that was raised
+      # @yieldparam args [Array] job arguments
+      # @yieldreturn [Boolean] false == dont retry, true = can retry
+      def retry_criteria_check(&block)
+        retry_criteria_checks << block
       end
 
-      ##
       # Will retry the job.
       def try_again(*args)
         if retry_delay <= 0
@@ -142,7 +187,6 @@ module Resque
         end
       end
 
-      ##
       # Resque before_perform hook.
       #
       # Increments and sets the `@retry_attempt` count.
@@ -152,7 +196,6 @@ module Resque
         @retry_attempt = Resque.redis.incr(retry_key) # increment by 1.
       end
 
-      ##
       # Resque after_perform hook.
       #
       # Deletes retry attempt count from Redis.
@@ -160,7 +203,6 @@ module Resque
         Resque.redis.del(redis_retry_key(*args))
       end
 
-      ##
       # Resque on_failure hook.
       #
       # Checks if our retry criteria is valid, if it is we try again.
@@ -172,7 +214,7 @@ module Resque
           Resque.redis.del(redis_retry_key(*args))
         end
       end
-    end
 
+    end
   end
-end
+end

data/test/exponential_backoff_test.rb

@@ -38,22 +38,22 @@ class ExponentialBackoffTest < Test::Unit::TestCase
     assert_equal now.to_i + 10_800, delayed[3], '5th delay'
     assert_equal now.to_i + 21_600, delayed[4], '6th delay'
   end
-  
+
   def test_custom_backoff_strategy
     now = Time.now
     4.times do
       Resque.enqueue(CustomExponentialBackoffJob, 'http://lividpenguin.com', 1305, 'cd8079192d379dc612f17c660591a6cfb05f1dda')
       perform_next_job @worker
     end
-    
+
     delayed = Resque.delayed_queue_peek(0, 3)
     assert_equal now.to_i + 10, delayed[0], '1st delay'
     assert_equal now.to_i + 20, delayed[1], '2nd delay'
     assert_equal now.to_i + 30, delayed[2], '3rd delay'
     assert_equal 2, Resque.delayed_timestamp_size(delayed[2]), '4th delay should share delay with 3rd'
-    
+
     assert_equal 4, Resque.info[:processed], 'processed jobs'
     assert_equal 4, Resque.info[:failed], 'failed jobs'
     assert_equal 0, Resque.info[:pending], 'pending jobs'
   end
-end
+end

data/test/retry_criteria_test.rb

@@ -0,0 +1,75 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class RetryCriteriaTest < Test::Unit::TestCase
+  def setup
+    Resque.redis.flushall
+    @worker = Resque::Worker.new(:testing)
+    @worker.register_worker
+  end
+
+  def test_retry_criteria_check_should_retry
+    Resque.enqueue(RetryModuleCustomRetryCriteriaCheck)
+    3.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 2, Resque.info[:failed], 'failed jobs'
+    assert_equal 2, Resque.info[:processed], 'processed job'
+  end
+
+  def test_retry_criteria_check_hierarchy_should_not_retry
+    Resque.enqueue(CustomRetryCriteriaCheckDontRetry)
+    3.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 1, Resque.info[:failed], 'failed jobs'
+    assert_equal 1, Resque.info[:processed], 'processed job'
+  end
+
+  def test_retry_criteria_check_hierarchy_should_retry
+    Resque.enqueue(CustomRetryCriteriaCheckDoRetry)
+    3.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 2, Resque.info[:failed], 'failed jobs'
+    assert_equal 2, Resque.info[:processed], 'processed job'
+  end
+
+  def test_retry_criteria_check_multiple_never_retry
+    Resque.enqueue(CustomRetryCriteriaCheckMultipleFailTwice, 'dont')
+    6.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 1, Resque.info[:failed], 'failed jobs'
+    assert_equal 1, Resque.info[:processed], 'processed job'
+  end
+
+  def test_retry_criteria_check_multiple_do_retry
+    Resque.enqueue(CustomRetryCriteriaCheckMultipleFailTwice, 'do')
+    6.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 2, Resque.info[:failed], 'failed jobs'
+    assert_equal 3, Resque.info[:processed], 'processed job'
+  end
+
+  def test_retry_criteria_check_multiple_do_retry_again
+    Resque.enqueue(CustomRetryCriteriaCheckMultipleFailTwice, 'do_again')
+    6.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 2, Resque.info[:failed], 'failed jobs'
+    assert_equal 3, Resque.info[:processed], 'processed job'
+  end
+end

data/test/retry_inheriting_checks_test.rb

@@ -0,0 +1,33 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class RetryInheritingChecksTest < Test::Unit::TestCase
+  def setup
+    Resque.redis.flushall
+    @worker = Resque::Worker.new(:testing)
+    @worker.register_worker
+  end
+
+  def test_default_job_has_one_exception
+    assert_equal 0, RetryDefaultsJob.retry_criteria_checks.size
+  end
+
+  def test_inheriting_copies_exceptions
+    assert_equal RetryDefaultsJob.retry_criteria_checks, InheritTestJob.retry_criteria_checks
+  end
+
+  def test_inheriting_adds_exceptions
+    assert_equal 1, InheritTestWithExtraJob.retry_criteria_checks.size
+  end
+
+  def test_extending_with_resque_retry_doesnt_override_previously_defined_inherited_hook
+    klass = InheritOrderingJobExtendLastSubclass
+    assert_equal 1, klass.retry_criteria_checks.size
+    assert_equal 'test', klass.test_value
+  end
+
+  def test_extending_with_resque_retry_then_defining_inherited_does_not_override_previous_hook
+    klass = InheritOrderingJobExtendFirstSubclass
+    assert_equal 1, klass.retry_criteria_checks.size
+    assert_equal 'test', klass.test_value
+  end
+end

data/test/retry_test.rb

@@ -31,6 +31,17 @@ class RetryTest < Test::Unit::TestCase
     assert_equal 2, Resque.info[:processed], 'processed job'
   end
 
+  def test_module_retry_defaults
+    Resque.enqueue(RetryModuleDefaultsJob)
+    3.times do
+      perform_next_job(@worker)
+    end
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 2, Resque.info[:failed], 'failed jobs'
+    assert_equal 2, Resque.info[:processed], 'processed job'
+  end
+
   def test_job_args_are_maintained
     test_args = ['maiow', 'cat', [42, 84]]
 
@@ -142,4 +153,5 @@ class RetryTest < Test::Unit::TestCase
   def test_redis_retry_key_removes_whitespace
     assert_equal 'resque-retry:GoodJob:arg1-removespace', GoodJob.redis_retry_key('arg1', 'remove space')
   end
+
 end

data/test/test_helper.rb

@@ -10,7 +10,6 @@ require 'resque-retry'
 require dir + '/test_jobs'
 
 
-##
 # make sure we can run redis
 if !system("which redis-server")
   puts '', "** can't find `redis-server` in your path"
@@ -19,7 +18,6 @@ if !system("which redis-server")
 end
 
 
-##
 # start our own redis when the tests start,
 # kill it when they end
 at_exit do
@@ -42,7 +40,6 @@ puts "Starting redis for testing at localhost:9736..."
 `redis-server #{dir}/redis-test.conf`
 Resque.redis = '127.0.0.1:9736'
 
-##
 # Test helpers
 class Test::Unit::TestCase
   def perform_next_job(worker, &block)

data/test/test_jobs.rb

@@ -18,6 +18,25 @@ class RetryDefaultsJob
   end
 end
 
+class InheritTestJob < RetryDefaultsJob
+end
+
+class InheritTestWithExtraJob < InheritTestJob
+  retry_criteria_check do |exception, *args|
+    false
+  end
+end
+
+class InheritTestWithMoreExtraJob < InheritTestWithExtraJob
+  retry_criteria_check do |exception, *args|
+    false
+  end
+
+  retry_criteria_check do |exception, *args|
+    false
+  end
+end
+
 class RetryWithModifiedArgsJob < RetryDefaultsJob
   @queue = :testing
 
@@ -48,10 +67,10 @@ end
 class CustomExponentialBackoffJob
   extend Resque::Plugins::ExponentialBackoff
   @queue = :testing
-  
+
   @retry_limit = 4
   @backoff_strategy = [10, 20, 30]
-  
+
   def self.perform(url, hook_id, hmac_key)
     raise
   end
@@ -71,4 +90,119 @@ class RetryCustomExceptionsJob < RetryDefaultsJob
     else raise StandardError
     end
   end
-end
+end
+
+module RetryModuleDefaultsJob
+  extend Resque::Plugins::Retry
+  @queue = :testing
+
+  def self.perform(*args)
+    raise
+  end
+end
+
+module RetryModuleCustomRetryCriteriaCheck
+  extend Resque::Plugins::Retry
+  @queue = :testing
+
+  # make sure the retry exceptions check will return false.
+  @retry_exceptions = [CustomException]
+
+  retry_criteria_check do |exception, *args|
+    true
+  end
+
+  def self.perform(*args)
+    raise
+  end
+end
+
+class CustomRetryCriteriaCheckDontRetry < RetryDefaultsJob
+  @queue = :testing
+
+  # make sure the retry exceptions check will return false.
+  @retry_exceptions = [CustomException]
+
+  retry_criteria_check do |exception, *args|
+    false
+  end
+end
+
+class CustomRetryCriteriaCheckDoRetry < CustomRetryCriteriaCheckDontRetry
+  @queue = :testing
+
+  # make sure the retry exceptions check will return false.
+  @retry_exceptions = [CustomException]
+
+  retry_criteria_check do |exception, *args|
+    true
+  end
+end
+
+# A job using multiple custom retry criteria checks.
+# It always fails 2 times.
+class CustomRetryCriteriaCheckMultipleFailTwice
+  extend Resque::Plugins::Retry
+  @retry_limit = 6
+  @queue = :testing
+
+  # make sure we dont retry due to default exception behaviour.
+  @retry_exceptions = []
+
+  retry_criteria_check do |exception, *args|
+    exception.message == 'dont' ? false : true
+  end
+
+  retry_criteria_check do |exception, *args|
+    exception.message == 'do' ? true : false
+  end
+
+  retry_criteria_check do |exception, *args|
+    exception.message == 'do_again' ? true : false
+  end
+
+  def self.perform(msg)
+    if retry_attempt < 2 # always fail twice please.
+      raise StandardError, msg
+    end
+  end
+end
+
+# A job to test whether self.inherited is respected
+# when added by other modules.
+class InheritOrderingJobExtendFirst
+  extend Resque::Plugins::Retry
+
+  retry_criteria_check do |exception, *args|
+    false
+  end
+
+  class << self
+    attr_accessor :test_value
+  end
+
+  def self.inherited(subclass)
+    super(subclass)
+    subclass.test_value = 'test'
+  end
+end
+
+class InheritOrderingJobExtendLast
+  class << self
+    attr_accessor :test_value
+  end
+
+  def self.inherited(subclass)
+    super(subclass)
+    subclass.test_value = 'test'
+  end
+
+  extend Resque::Plugins::Retry
+
+  retry_criteria_check do |exception, *args|
+    false
+  end
+end
+
+class InheritOrderingJobExtendFirstSubclass < InheritOrderingJobExtendFirst; end
+class InheritOrderingJobExtendLastSubclass < InheritOrderingJobExtendLast; end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Luke Antins
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-27 00:00:00 +01:00
+date: 2010-07-12 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -86,6 +86,8 @@ files:
 - test/exponential_backoff_test.rb
 - test/redis-test.conf
 - test/resque_test.rb
+- test/retry_criteria_test.rb
+- test/retry_inheriting_checks_test.rb
 - test/retry_test.rb
 - test/test_helper.rb
 - test/test_jobs.rb