resque-retry 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d4c061060637465cbab7c2348d2facefa1816493
-  data.tar.gz: 3b76a1d34c68eeb3fae868900b75ca02192bc851
+  metadata.gz: e13254ff1b1a5e06977bbbbfa6a28843629f2133
+  data.tar.gz: e9ebf7d623865a0d067c060a804ccae233a34728
 SHA512:
-  metadata.gz: 63bcdd107167973953477e6e591c8ce86d2a2957b41bb93cbe161153f5f2e6fd69e417718ba46d497f755fcde882373f2f992538c48b7aa11b7a449ba2aec867
-  data.tar.gz: 4d34d77f1fe0b4ae1728495865f79f20b05ef7896ddf30d23d70cdef2d03caf57ff995617e2e6aff3b854a34865933a05913a638e2fb0e285f75685bb334771a
+  metadata.gz: fa3fba3ab9b3945a9b9de6cd3f16a59ce85ac8365d5ac2fc7c962573e74b0236cc2e0526c0435f925c22a7648aefa0fa9f6dc9015ff9a415cb36137b2f239ff7
+  data.tar.gz: 30220fc7c9f30c3b7c0fa63105f86dbcc4c10f59e7cc1bd0e638581b87abf320d5fdae7deb0c9aadbe327f6c0af501fe5bf76842d6f488e15405ded60222af2f

data/HISTORY.md

@@ -1,5 +1,10 @@
 ## HEAD
 
+# 1.5.0 (2015-10-24)
+
+* Ability to define 'try again' and 'give up' callbacks/hooks (@thenovices)
+* Allow `retry_criteria_check` to be registered with Symbols (@thenovices)
+
 ## 1.4.0 (2015-01-07)
 
 * Dependency on `resque-scheduler` bumped to ~> 4.0

data/README.md

@@ -1,7 +1,7 @@
 resque-retry
 ============
 
-A [Resque][rq] plugin. Requires Resque ~> 1.25 & [resque-scheduler][rqs] ~> 4.0.
+A [Resque][resque] plugin. Requires Resque ~> 1.25 & [resque-scheduler][resque-scheduler] ~> 4.0.
 
 This gem provides retry, delay and exponential backoff support for resque jobs.
 
@@ -18,11 +18,12 @@ Install & Quick Start
 ---------------------
 
 To install:
+```
+$ gem install resque-retry
+```
 
-    $ gem install resque-retry
-
-If you're using [Bundler][bundler] to manage your dependencies, you should add `gem
-'resque-retry'` to your projects `Gemfile`.
+If you're using [Bundler][bundler] to manage your dependencies, you should add
+`gem 'resque-retry'` to your `Gemfile`.
 
 Add this to your `Rakefile`:
 ```ruby
@@ -30,7 +31,7 @@ require 'resque/tasks'
 require 'resque/scheduler/tasks'
 ```
 
-The delay between retry attempts is provided by [resque-scheduler][rqs].
+The delay between retry attempts is provided by [resque-scheduler][resque-scheduler].
 You'll want to run the scheduler process, otherwise delayed retry attempts
 will never perform:
 ```
@@ -79,7 +80,8 @@ actually completed successfully just by just using the resque-web interface.
 
 ### Failure Backend
 
-`MultipleWithRetrySuppression` is a multiple failure backend, with retry suppression.
+`MultipleWithRetrySuppression` is a multiple failure backend, with retry
+suppression.
 
 Here's an example, using the Redis failure backend:
 ```ruby
@@ -92,8 +94,8 @@ Resque::Failure::MultipleWithRetrySuppression.classes = [Resque::Failure::Redis]
 Resque::Failure.backend = Resque::Failure::MultipleWithRetrySuppression
 ```
 
-If a job fails, but **can and will** retry, the failure details wont be
-logged in the Redis failed queue *(visible via resque-web)*.
+If a job fails, but **can and will** retry, the failure details wont be logged
+in the Redis failed queue *(visible via resque-web)*.
 
 If the job fails, but **can't or won't** retry, the failure will be logged in
 the Redis failed queue, like a normal failure *(without retry)* would.
@@ -101,7 +103,7 @@ the Redis failed queue, like a normal failure *(without retry)* would.
 ### Resque Web Additions
 
 If you're using the `MultipleWithRetrySuppression` failure backend, you should
-also checkout the resque-web additions!
+also checkout the `resque-web` additions!
 
 The new Retry tab displays delayed jobs with retry information; the number of
 attempts and the exception details from the last failure.
@@ -109,17 +111,16 @@ attempts and the exception details from the last failure.
 
 ### Configuring and running the Resque-Web Interface
 
-#### Using a Rack configuration: 
-
-One alternative is to use a rack configuration file. To use this, make 
-sure you include this in your `config.ru` or similar file:
+#### Using a Rack configuration:
 
+One alternative is to use a rack configuration file. To use this, make sure you
+include this in your `config.ru` or similar file:
 ```ruby
 require 'resque-retry'
 require 'resque-retry/server'
 
 # Make sure to require your workers & application code below this line:
-# require '[path]/[to]/[jobs]/your_worker' 
+# require '[path]/[to]/[jobs]/your_worker'
 
 # Run the server
 run Resque::Server.new
@@ -132,33 +133,30 @@ rackup -p 9292 config.ru
 
 When using bundler, you can also run the server like this:
 ```
-bundle exec rackup -p 9292 config.ru 
+bundle exec rackup -p 9292 config.ru
 ```
 
 
 #### Using the 'resque-web' command with a configuration file:
 
-Another alternative is to use resque's built-in 'resque-web' command with
-the additional resque-retry tabs. In order to do this, you must first create
-a configuration file. For the sake of this example we'll create the configuration
-file in a 'config' directory, and name it 'resque_web_config.rb'. In practice 
-you could rename this configuration file to anything you'd like and place in your
-project in any directory of your choosing. The contents of the configuration file
+Another alternative is to use resque's built-in 'resque-web' command with the
+additional resque-retry tabs. In order to do this, you must first create a
+configuration file. For the sake of this example we'll create the configuration
+file in a 'config' directory, and name it 'resque_web_config.rb'. In practice
+you could rename this configuration file to anything you like and place in your
+project in a directory of your choosing. The contents of the configuration file
 would look like this:
-
 ```ruby
 # [app_dir]/config/resque_web_config.rb
 require 'resque-retry'
 require 'resque-retry/server'
 
 # Make sure to require your workers & application code below this line:
-# require '[path]/[to]/[jobs]/your_worker' 
-
+# require '[path]/[to]/[jobs]/your_worker'
 ```
 
 Once you have the configuration file ready, you can pass the configuration file
 to the resque-web command as a parameter, like so:
-
 ```
 resque-web [app_dir]/config/resque_web_config.rb
 ```
@@ -170,10 +168,24 @@ Retry Options & Logic
 Please take a look at the [yardoc](http://rubydoc.info/gems/resque-retry)/code
 for more details on methods you may wish to override.
 
-Customisation is pretty easy, the below examples should give you
-some ideas =), adapt for your own usage and feel free to pick and mix!
-
-### Retry Defaults
+Customisation is pretty easy, the below examples should give you some ideas =),
+adapt for your own usage and feel free to pick and mix!
+
+Here are a list of the options provided (click to jump):
+ * [Retry Defaults](#retry_defaults)
+ * [Custom Retry](#custom_retry)
+ * [Sleep After Requeuing](#sleep)
+ * [Exponential Backoff](#exp)
+ * [Retry Specific Exceptions](#specific)
+ * [Fail Fast For Specific Exceptions](#fail_fast)
+ * [Custom Retry Criteria Check Callbacks](#custom_check)
+ * [Retry Arguments](#retry_args)
+ * [Job Retry Identifier/Key](#retry_key)
+ * [Expire Retry Counters From Redis](#expire)
+ * [Try Again and Give Up Callbacks](#callbacks)
+ * [Debug Plugin Logging](#debug_log)
+
+### <a name="retry_defaults"></a> Retry Defaults 
 
 Retry the job **once** on failure, with zero delay.
 ```ruby
@@ -193,7 +205,7 @@ When a job runs, the number of retry attempts is checked and incremented
 in Redis. If your job fails, the number of retry attempts is used to
 determine if we can requeue the job for another go.
 
-### Custom Retry
+### <a name="custom_retry"></a> Custom Retry
 ```ruby
 class DeliverWebHook
   extend Resque::Plugins::Retry
@@ -208,13 +220,12 @@ class DeliverWebHook
 end
 ```
 
-The above modification will allow your job to retry up to 10 times, with
-a delay of 120 seconds, or 2 minutes between retry attempts.
+The above modification will allow your job to retry up to 10 times, with a delay
+of 120 seconds, or 2 minutes between retry attempts.
 
-Alternatively you could override the `retry_delay` method to do something
-more special.
+You can override the `retry_delay` method to set the delay value dynamically.
 
-### Sleep After Requeuing
+### <a name="sleep"></a> Sleep After Requeuing
 
 Sometimes it is useful to delay the worker that failed a job attempt, but
 still requeue the job for immediate processing by other workers. This can be
@@ -235,17 +246,17 @@ end
 This retries the job once and causes the worker that failed to sleep for 5
 seconds after requeuing the job. If there are multiple workers in the system
 this allows the job to be retried immediately while the original worker heals
-itself.For example failed jobs may cause other (non-worker) OS processes to
-die. A system monitor such as [god][god] can fix the server while the job is
-being retried on a different worker.
+itself. For example failed jobs may cause other (non-worker) OS processes to
+die. A system monitor such as [monit][monit] or [god][god] can fix the server
+while the job is being retried on a different worker.
 
 `@sleep_after_requeue` is independent of `@retry_delay`. If you set both, they
 both take effect.
 
-You can override the method `sleep_after_requeue` to set the sleep value
+You can override the `sleep_after_requeue` method to set the sleep value
 dynamically.
 
-### Exponential Backoff
+### <a name="exp"></a> Exponential Backoff
 
 Use this if you wish to vary the delay between retry attempts:
 ```ruby
@@ -263,17 +274,17 @@ end
 ```
 key: m = minutes, h = hours
 
-              no delay, 1m, 10m,   1h,    3h,    6h
+                    0s, 1m, 10m,   1h,    3h,    6h
 @backoff_strategy = [0, 60, 600, 3600, 10800, 21600]
 @retry_delay_multiplicand_min = 1.0
 @retry_delay_multiplicand_max = 1.0
 ```
 
-The first delay will be 0 seconds, the 2nd will be 60 seconds, etc...
-Again, tweak to your own needs.
+The first delay will be 0 seconds, the 2nd will be 60 seconds, etc...  Again,
+tweak to your own needs.
 
-The number of retries is equal to the size of the `backoff_strategy`
-array, unless you set `retry_limit` yourself.
+The number of retries is equal to the size of the `backoff_strategy` array,
+unless you set `retry_limit` yourself.
 
 The delay values will be multiplied by a random `Float` value between
 `retry_delay_multiplicand_min` and `retry_delay_multiplicand_max` (both have a
@@ -282,10 +293,10 @@ attempt. This feature can be useful if you have a lot of jobs fail at the same
 time (e.g. rate-limiting/throttling or connectivity issues) and you don't want
 them all retried on the same schedule.
 
-### Retry Specific Exceptions
+### <a name="specific"></a> Retry Specific Exceptions
 
-The default will allow a retry for any type of exception. You may change
-it so only specific exceptions are retried using `retry_exceptions`:
+The default will allow a retry for any type of exception. You may change it so
+only specific exceptions are retried using `retry_exceptions`:
 ```ruby
 class DeliverSMS
   extend Resque::Plugins::Retry
@@ -305,8 +316,8 @@ exception is thrown.
 You may also want to specify different retry delays for different exception
 types. You may optionally set `@retry_exceptions` to a hash where the keys are
 your specific exception classes to retry on, and the values are your retry
-delays in seconds or an array of retry delays to be used similar to
-exponential backoff.
+delays in seconds or an array of retry delays to be used similar to exponential
+backoff.
 ```ruby
 class DeliverSMS
   extend Resque::Plugins::Retry
@@ -325,7 +336,7 @@ In the above example, Resque would retry any `DeliverSMS` jobs which throw a
 will be retried 30 seconds later, if it throws `SystemCallError` it will first
 retry 120 seconds later then subsequent retry attempts 240 seconds later.
 
-### Fail Fast For Specific Exceptions
+### <a name="fail_fast"></a> Fail Fast For Specific Exceptions
 
 The default will allow a retry for any type of exception. You may change
 it so specific exceptions fail immediately by using `fatal_exceptions`:
@@ -346,7 +357,7 @@ In the above example, Resque would retry any `DeliverSMS` jobs that throw any
 type of error other than `NetworkError`. If the job throws a `NetworkError` it
 will be marked as "failed" immediately.
 
-### Custom Retry Criteria Check Callbacks
+### <a name="custom_check"></a> Custom Retry Criteria Check Callbacks
 
 You may define custom retry criteria callbacks:
 ```ruby
@@ -374,13 +385,30 @@ 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.
+You can also register a retry criteria check with a Symbol if the method is
+already defined on the job class:
+```
+class AlwaysRetryJob
+  extend Resque::Plugins::Retry
+
+  retry_criteria_check :yes
 
-### Retry Arguments
+  def self.yes(ex, *args)
+    true
+  end
+end
+
+Use `@retry_exceptions = []` to **only** use your custom retry criteria checks
+to determine if the job should retry.
 
-You may override `retry_args`, which is passed the current
-job arguments, to modify the arguments for the next retry attempt.
+NB: Your callback must be able to accept the exception and job arguments as
+passed parameters, or else it cannot be called. e.g., in the example above,
+defining `def self.yes; true; end` would not work.
+
+### <a name="retry_args"></a> Retry Arguments
+
+You may override `retry_args`, which is passed the current job arguments, to
+modify the arguments for the next retry attempt.
 ```ruby
 class DeliverViaSMSC
   extend Resque::Plugins::Retry
@@ -397,10 +425,10 @@ class DeliverViaSMSC
 end
 ```
 
-Alternatively, if you require finer control of the args based on the
-exception thrown, you may override `retry_args_for_exception`, which is passed
-the exception and the current job arguments, to modify the arguments for the
-next retry attempt.
+Alternatively, if you require finer control of the args based on the exception
+thrown, you may override `retry_args_for_exception`, which is passed the
+exception and the current job arguments, to modify the arguments for the next
+retry attempt.
 ```ruby
 class DeliverViaSMSC
   extend Resque::Plugins::Retry
@@ -416,17 +444,17 @@ class DeliverViaSMSC
   end
 end
 ```
-### Job Retry Identifier/Key
+### <a name="retry_key"></a> Job Retry Identifier/Key
 
-The retry attempt is incremented and stored in a Redis key. The key is
-built using the `retry_identifier`. If you have a lot of arguments or really long
+The retry attempt is incremented and stored in a Redis key. The key is built
+using the `retry_identifier`. If you have a lot of arguments or really long
 ones, you should consider overriding `retry_identifier` to define a more precise
 or loose custom retry identifier.
 
-The default retry identifier is just your job arguments joined with a dash `-`.
+The default identifier is just your job arguments joined with a dash `'-'`.
 
-By default the key uses this format: 
-`resque-retry:<job class name>:<retry_identifier>`.
+By default the key uses this format:
+`'resque-retry:<job class name>:<retry_identifier>'`.
 
 Or you can define the entire key by overriding `redis_retry_key`.
 ```ruby
@@ -444,11 +472,10 @@ class DeliverSMS
 end
 ```
 
-### Expire Retry Counters From Redis
+### <a name="expire"></a> Expire Retry Counters From Redis
 
 Allow the Redis to expire stale retry counters from the database by setting
 `@expire_retry_key_after`:
-
 ```ruby
 class DeliverSMS
   extend Resque::Plugins::Retry
@@ -459,15 +486,78 @@ class DeliverSMS
     heavy_lifting
   end
 end
-
 ```
 
 This saves you from having to run a "house cleaning" or "errand" job.
 
 The expiary timeout is "pushed forward" or "touched" after each failure to
-ensure its not expired too soon.
+ensure it's not expired too soon.
+
+### <a name="callbacks"></a> Try Again and Give Up Callbacks
+Resque's `on_failure` callbacks are always called, regardless of whether the
+job is going to be retried or not. If you want to run a callback only when the
+job is being retried, you can add a `try_again_callback`:
+```ruby
+class LoggedJob
+  extend Resque::Plugins::Retry
+
+  try_again_callback do |exception, *args|
+    logger.info("Received #{exception}, retrying job #{self.name} with #{args}")
+  end
+end
+```
+
+Similarly, if you want to run a callback only when the job has failed, and is
+_not_ retrying, you can add a `give_up_callback`:
+```ruby
+class LoggedJob
+  extend Resque::Plugins::Retry
+  
+  give_up_callback do |exception, *args|
+    logger.error("Received #{exception}, job #{self.name} failed with #{args}")
+  end
+end
+```
+
+You can register a callback with a Symbol if the method is already defined on
+the job class:
+```ruby
+class LoggedJob
+  extend Resque::Plugins::Retry
+  
+  give_up_callback :log_give_up
+
+  def self.log_give_up(ex, *args)
+    logger.error("Received #{exception}, job #{self.name} failed with #{args}")
+  end
+end
+```
+
+You can register multiple callbacks, and they will be called in the order that
+they were registered. You can also set callbacks by setting
+`@try_again_callbacks` or `@give_up_callbacks` to an array where each element
+is a `Proc` or `Symbol`.
+```ruby
+class CallbackJob
+  extend Resque::Plugins::Retry
+
+  @try_again_callbacks = [
+    :call_me_first,
+    :call_me_second,
+    lambda { |*args| call_me_third(*args) }
+  ]
+
+  def self.call_me_first(ex, *args); end
+  def self.call_me_second(ex, *args); end
+  def self.call_me_third(ex, *args); end
+end
+```
+
+Warning: Make sure your callbacks do not throw any exceptions. If they do,
+subsequent callbacks will not be triggered, and the job will not be retried
+(if it was trying again). The retry counter also will not be reset.
 
-### Debug Plugin Logging
+### <a name="debug_log"></a> Debug Plugin Logging
 
 The inner-workings of the plugin are output to the Resque [Logger](https://github.com/resque/resque/wiki/Logging)
 when `Resque.logger.level` is set to `Logger::DEBUG`.
@@ -483,7 +573,8 @@ Contributing/Pull Requests
   * Send us a pull request. Bonus points for topic branches.
   * If you edit the gemspec/version etc, please do so in another commit.
 
-[god]: http://github.com/mojombo/god
-[rq]: http://github.com/resque/resque
-[rqs]: http://github.com/resque/resque-scheduler
+[monit]: https://mmonit.com
+[god]: http://godrb.com
+[resque]: http://github.com/resque/resque
+[resque-scheduler]: http://github.com/resque/resque-scheduler
 [bundler]: http://bundler.io

data/lib/resque-retry/version.rb

@@ -1,3 +1,3 @@
 module ResqueRetry
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

data/lib/resque/plugins/retry.rb

@@ -52,12 +52,15 @@ module Resque
         end
       end
 
-      # Copy retry criteria checks on inheritance.
+      # Copy retry criteria checks, try again callbacks, and give up callbacks
+      # on inheritance.
       #
       # @api private
       def inherited(subclass)
         super(subclass)
         subclass.instance_variable_set('@retry_criteria_checks', retry_criteria_checks.dup)
+        subclass.instance_variable_set('@try_again_callbacks', try_again_callbacks.dup)
+        subclass.instance_variable_set('@give_up_callbacks', give_up_callbacks.dup)
       end
 
       # @abstract You may override to implement a custom retry identifier,
@@ -271,11 +274,9 @@ module Resque
         retry_based_on_criteria = false
         unless retry_based_on_exception
           # call user retry criteria check blocks.
-          retry_criteria_checks.each do |criteria_check|
-            retry_based_on_criteria ||= !!instance_exec(exception, *args, &criteria_check)
-          end
+          retry_based_on_criteria = retry_criteria_checks_pass?(exception, *args)
+          log_message "user retry criteria is #{retry_based_on_criteria ? '' : 'not '}sufficient for a retry", args, exception
         end
-        log_message "user retry criteria is #{retry_based_on_criteria ? '' : 'not '}sufficient for a retry", args, exception
 
         retry_based_on_exception || retry_based_on_criteria
       end
@@ -305,11 +306,11 @@ module Resque
       end
 
       # Register a retry criteria check callback to be run before retrying
-      # the job again
+      # the job again. Can be registered with a block or a symbol.
       #
       # If any callback returns `true`, the job will be retried.
       #
-      # @example Using a custom retry criteria check.
+      # @example Registering a custom retry criteria check.
       #
       #   retry_criteria_check do |exception, *args|
       #     if exception.message =~ /InvalidJobId/
@@ -320,14 +321,36 @@ module Resque
       #     end
       #   end
       #
+      # @example
+      #
+      #   retry_criteria_check :my_check
+      #
+      # @param [Symbol?] method
       # @yield [exception, *args]
       # @yieldparam exception [Exception] the exception that was raised
       # @yieldparam args [Array] job arguments
-      # @yieldreturn [Boolean] false == dont retry, true = can retry
+      # @yieldreturn [Boolean] false == dont retry, true == can retry
       #
       # @api public
-      def retry_criteria_check(&block)
-        retry_criteria_checks << block
+      def retry_criteria_check(method=nil, &block)
+        if method.is_a? Symbol
+          retry_criteria_checks << method
+        elsif block_given?
+          retry_criteria_checks << block
+        end
+      end
+
+      # Returns true if *any* of the retry criteria checks pass. When a retry
+      # criteria check passes, the remaining ones are not executed.
+      #
+      # @returns [Boolean] whether any of the retry criteria checks pass
+      #
+      # @api private
+      def retry_criteria_checks_pass?(exception, *args)
+        retry_criteria_checks.each do |criteria_check|
+          return true if !!call_symbol_or_block(criteria_check, exception, *args)
+        end
+        false
       end
 
       # Retries the job
@@ -335,6 +358,8 @@ module Resque
       # @api private
       def try_again(exception, *args)
         log_message 'try_again', args, exception
+        run_try_again_callbacks(exception, *args)
+
         # some plugins define retry_delay and have it take no arguments, so rather than break those,
         # we'll just check here to see whether it takes the additional exception class argument or not
         temp_retry_delay = ([-1, 1].include?(method(:retry_delay).arity) ? retry_delay(exception.class) : retry_delay)
@@ -365,6 +390,15 @@ module Resque
         sleep(sleep_after_requeue) if sleep_after_requeue > 0
       end
 
+      # We failed and we're not retrying.
+      #
+      # @api private
+      def give_up(exception, *args)
+        log_message 'retry criteria not sufficient for retry', args, exception
+        run_give_up_callbacks(exception, *args)
+        clean_retry_key(*args)
+      end
+
       # Resque before_perform hook
       #
       # Increments `@retry_attempt` count and updates the "retry_key" expiration
@@ -422,8 +456,7 @@ module Resque
         if retry_criteria_valid?(exception, *args)
           try_again(exception, *args)
         else
-          log_message 'retry criteria not sufficient for retry', args, exception
-          clean_retry_key(*args)
+          give_up(exception, *args)
         end
 
         @on_failure_retry_hook_already_called = true
@@ -452,6 +485,121 @@ module Resque
         log_message 'clean_retry_key', args
         Resque.redis.del(redis_retry_key(*args))
       end
+
+      # Returns the try again callbacks.
+      #
+      # @return [Array<Proc>]
+      #
+      # @api public
+      def try_again_callbacks
+        @try_again_callbacks ||= []
+      end
+
+      # Register a try again callback that will be called when the job fails
+      # but is trying again. Can be registered with a block or a symbol.
+      #
+      # @example Registering a callback with a block
+      #
+      #   try_again_callback do |exception, *args|
+      #     logger.error(
+      #       "Resque job received exception #{exception} and is trying again")
+      #   end
+      #
+      # @example Registering a callback with a Symbol
+      #
+      #   try_again_callback :my_callback
+      #
+      # @param [Symbol?] method
+      # @yield [exception, *args]
+      # @yieldparam exception [Exception] the exception that was raised
+      # @yieldparam args [Array] job arguments
+      #
+      # @api public
+      def try_again_callback(method=nil, &block)
+        if method.is_a? Symbol
+          try_again_callbacks << method
+        elsif block_given?
+          try_again_callbacks << block
+        end
+      end
+
+      # Runs all the try again callbacks.
+      #
+      # @param exception [Exception]
+      # @param args [Object...]
+      #
+      # @api private
+      def run_try_again_callbacks(exception, *args)
+        try_again_callbacks.each do |callback|
+          call_symbol_or_block(callback, exception, *args)
+        end
+      end
+
+      # Returns the give up callbacks.
+      #
+      # @return [Array<Proc>]
+      #
+      # @api public
+      def give_up_callbacks
+        @give_up_callbacks ||= []
+      end
+
+      # Register a give up callback that will be called when the job fails
+      # and is not retrying. Can be registered with a block or a symbol.
+      #
+      # @example Registering a callback with a block
+      #
+      #   give_up_callback do |exception, *args|
+      #     logger.error(
+      #       "Resque job received exception #{exception} and is giving up")
+      #   end
+      #
+      # @example Registering a callback with a Symbol
+      #
+      #   give_up_callback :my_callback
+      #
+      # @param [Symbol?] method
+      # @yield [exception, *args]
+      # @yieldparam exception [Exception] the exception that was raised
+      # @yieldparam args [Array] job arguments
+      #
+      # @api public
+      def give_up_callback(method=nil, &block)
+        if method.is_a? Symbol
+          give_up_callbacks << method
+        elsif block_given?
+          give_up_callbacks << block
+        end
+      end
+
+      # Runs all the give up callbacks.
+      #
+      # @param exception [Exception]
+      # @param args [Object...]
+      #
+      # @api private
+      def run_give_up_callbacks(exception, *args)
+        give_up_callbacks.each do |callback|
+          call_symbol_or_block(callback, exception, *args)
+        end
+      end
+
+      # Helper to call functions that may be passed as Symbols or Procs. If
+      # a symbol, it is assumed to refer to a method that is already defined
+      # on this class.
+      #
+      # @param [Symbol|Proc] method
+      # @param [Object...] *args
+      # @return [Object]
+      #
+      # @api private
+      def call_symbol_or_block(method, *args)
+        if method.is_a?(Symbol)
+          send(method, *args)
+        elsif method.respond_to?(:call)
+          instance_exec(*args, &method)
+        end
+      end
     end
   end
 end

data/test/retry_callbacks_test.rb

@@ -0,0 +1,121 @@
+require 'test_helper'
+
+class RetryCallbacksTest < Minitest::Test
+  def setup
+    Resque.redis.flushall
+    @worker = Resque::Worker.new(:testing)
+    @worker.register_worker
+  end
+
+  def test_try_again_callbacks_called
+    # Fail, but not fatally
+    Resque.enqueue(RetryCallbacksJob, false)
+    order = sequence('callback_order')
+
+    # Make sure that we're testing both blocks and symbols in our callbacks.
+    refute_empty RetryCallbacksJob.try_again_callbacks.select { |x| x.is_a? Symbol }
+    refute_empty RetryCallbacksJob.try_again_callbacks.select { |x| x.is_a? Proc }
+
+    RetryCallbacksJob.expects(:on_try_again).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_a).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_b).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_c).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+
+    RetryCallbacksJob.expects(:on_give_up).never
+    RetryCallbacksJob.expects(:on_give_up_a).never
+    RetryCallbacksJob.expects(:on_give_up_b).never
+
+    perform_next_job(@worker)
+  end
+
+  def test_give_up_callbacks_called
+    # Fail fatally
+    Resque.enqueue(RetryCallbacksJob, true)
+    order = sequence('callback_order')
+
+    # Make sure that we're testing both blocks and symbols in our callbacks.
+    refute_empty RetryCallbacksJob.give_up_callbacks.select { |x| x.is_a? Symbol }
+    refute_empty RetryCallbacksJob.give_up_callbacks.select { |x| x.is_a? Proc }
+
+    RetryCallbacksJob.expects(:on_give_up).once
+      .with(instance_of(CustomException), true).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_a).once
+      .with(instance_of(CustomException), true).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_b).once
+      .with(instance_of(CustomException), true).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_c).once
+      .with(instance_of(CustomException), true).in_sequence(order)
+
+    RetryCallbacksJob.expects(:on_try_again).never
+    RetryCallbacksJob.expects(:on_try_again_a).never
+    RetryCallbacksJob.expects(:on_try_again_b).never
+
+    perform_next_job(@worker)
+  end
+
+  def test_try_again_callbacks_called_then_give_up
+    # Try once, retry, then try a second time and give up.
+    Resque.enqueue(RetryCallbacksJob, false)
+    order = sequence('callback_order')
+
+    RetryCallbacksJob.expects(:on_try_again).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_a).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_b).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_try_again_c).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+
+    RetryCallbacksJob.expects(:on_give_up).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_a).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_b).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+    RetryCallbacksJob.expects(:on_give_up_c).once
+      .with(instance_of(AnotherCustomException), false).in_sequence(order)
+
+
+    perform_next_job(@worker)  # Fail and retry
+    perform_next_job(@worker)  # Fail and give up
+  end
+
+  # If an exception is raised in a try again callback, then it should fail and
+  # not be retried.
+  def test_try_again_callback_exception
+    # Trigger a try again callback
+    Resque.enqueue(RetryCallbacksJob, false)
+
+    RetryCallbacksJob.expects(:on_try_again).once.raises(StandardError)
+    RetryCallbacksJob.expects(:on_try_again_a).never
+    RetryCallbacksJob.expects(:on_try_again_b).never
+    RetryCallbacksJob.expects(:on_try_again_c).never
+
+    perform_next_job(@worker)
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 1, Resque.info[:failed], 'failed jobs'
+  end
+
+  # If an exception is raised in a give up callback, then it should fail and
+  # not be retried.
+  def test_give_up_callback_exception
+    # Trigger a give up callback
+    Resque.enqueue(RetryCallbacksJob, true)
+
+    RetryCallbacksJob.expects(:on_give_up).once.raises(StandardError)
+    RetryCallbacksJob.expects(:on_give_up_a).never
+    RetryCallbacksJob.expects(:on_give_up_b).never
+    RetryCallbacksJob.expects(:on_give_up_c).never
+
+    perform_next_job(@worker)
+
+    assert_equal 0, Resque.info[:pending], 'pending jobs'
+    assert_equal 1, Resque.info[:failed], 'failed jobs'
+  end
+end

data/test/retry_criteria_test.rb

@@ -72,4 +72,15 @@ class RetryCriteriaTest < Minitest::Test
     assert_equal 2, Resque.info[:failed], 'failed jobs'
     assert_equal 3, Resque.info[:processed], 'processed job'
   end
+
+  def test_retry_criteria_checks_can_be_registered_with_symbols
+    Resque.enqueue(CustomRetryCriteriaWithSymbol)
+    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
 end

data/test/test_jobs.rb

@@ -409,6 +409,24 @@ class CustomRetryCriteriaCheckMultipleFailTwice
   end
 end
 
+# A job that defines a custom retry criteria check via a symbol, for a method
+# that is already defined.
+class CustomRetryCriteriaWithSymbol
+  extend Resque::Plugins::Retry
+  @queue = :testing
+
+  # make sure the retry exceptions check will return false.
+  @retry_exceptions = [CustomException]
+
+  retry_criteria_check :yes
+
+  def self.yes(ex, *args); true; end
+
+  def self.perform(*args)
+    raise
+  end
+end
+
 # A job to test whether self.inherited is respected
 # when added by other modules.
 class InheritOrderingJobExtendFirst
@@ -512,3 +530,52 @@ class RetryKilledJob
     Process.kill("KILL", Process.pid)
   end
 end
+
+class RetryCallbacksJob
+  extend Resque::Plugins::Retry
+  @queue = :testing
+
+  @fatal_exceptions = [CustomException]
+  @retry_exceptions = [AnotherCustomException]
+  @retry_limit = 1
+
+  def self.perform(is_fatal)
+    if is_fatal
+      raise CustomException, "RetryCallbacksJob failed fatally"
+    else
+      raise AnotherCustomException, "RetryCallbacksJob failed"
+    end
+  end
+
+  def self.on_try_again(ex, *args); end
+  def self.on_try_again_a(ex, *args); end
+  def self.on_try_again_b(ex, *args); end
+  def self.on_try_again_c(ex, *args); end
+
+  def self.on_give_up(ex, *args); end
+  def self.on_give_up_a(ex, *args); end
+  def self.on_give_up_b(ex, *args); end
+  def self.on_give_up_c(ex, *args); end
+
+  @try_again_callbacks = [
+    lambda { |*args| self.on_try_again(*args) },
+    :on_try_again_a
+  ]
+
+  try_again_callback do |*args|
+    on_try_again_b(*args)
+  end
+
+  try_again_callback :on_try_again_c
+
+  @give_up_callbacks = [
+    lambda { |*args| self.on_give_up(*args) },
+    :on_give_up_a
+  ]
+
+  give_up_callback do |*args|
+    on_give_up_b(*args)
+  end
+
+  give_up_callback :on_give_up_c
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resque-retry
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Luke Antins
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-07 00:00:00.000000000 Z
+date: 2015-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: resque
@@ -184,6 +184,7 @@ files:
 - test/multiple_failure_test.rb
 - test/redis-test.conf
 - test/resque_test.rb
+- test/retry_callbacks_test.rb
 - test/retry_criteria_test.rb
 - test/retry_exception_delay_test.rb
 - test/retry_inheriting_checks_test.rb