README.md in resque-retry-0.0.6 vs README.md in resque-retry-0.1.0

- old
+ new

@@ -1,29 +1,122 @@ resque-retry ============ -A [Resque][rq] plugin. Requires Resque 1.8.0 & [resque-scheduler][rqs] +A [Resque][rq] plugin. Requires Resque 1.8.0 & [resque-scheduler][rqs]. resque-retry provides retry, delay and exponential backoff support for resque jobs. -### Features + * Redis backed retry count/limit. + * Retry on all or specific exceptions. + * Exponential backoff (varying the delay between retrys). + * Multiple failure backend with retry suppression & resque-web tab. + * Small & Extendable - plenty of places to override retry logic/settings. - - Redis backed retry count/limit. - - Retry on all or specific exceptions. - - Exponential backoff (varying the delay between retrys). - - Small & Extendable - plenty of places to override retry logic/settings. +Install & Quick Start +--------------------- -Usage / Examples ----------------- +To install: -Just extend your module/class with this module, and your ready to retry! + $ gem install resque-retry +You'll want add this to your `Rakefile`: + + require 'resque/tasks' + require 'resque_scheduler/tasks' + +The delay between retry attempts is provided by [resque-scheduler][rqs]. +You'll want to run the scheduler process, otherwise delayed retry attempts +will never perform: + + $ rake resque:scheduler + +Use the plugin: + + require 'resque-retry' + + class ExampleRetryJob + extend Resque::Plugins::Retry + @queue = :example_queue + + @retry_limit = 3 + @retry_delay = 60 + + def self.perform(*args) + # your magic/heavy lifting goes here. + end + end + +Then start up a resque worker as normal: + + $ QUEUE=* rake resque:work + +Now if you ExampleRetryJob fails, it will be retried 3 times, with a 60 second +delay between attempts. + +For more explanation and examples, please see the remaining documentation. + +Failure Backend & Resque Web Additions +-------------------------------------- + +Lets say your using the Redis failure backend of resque (the default). +Every time a job fails, the failure queue is populated with the job and +exception details. + +Normally this is useful, but if your jobs retry... it can cause a bit of a mess. + +For example: given a job that retried 4 times before completing successful. +You'll have a lot of failures for the same job and you wont be sure if it +actually completed successfully just by just using the resque-web interface. + +### Failure Backend + +`MultipleWithRetrySuppression` is a multiple failure backend, with retry suppression. + +Here's an example, using the Redis failure backend: + + require 'resque-retry' + require 'resque/failure/redis' + + # require your jobs & application code. + + 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 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. + +### Resque Web Additions + +If your using the `MultipleWithRetrySuppression` failure backend, you should +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. + +Make sure you include this in your `config.ru` or similar file: + + require 'resque-retry' + require 'resque-retry/server' + + # require your jobs & application code. + + run Resque::Server.new + +Retry Options & Logic +--------------------- + +Please take a look at the yardoc/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 +### Retry Defaults Retry the job **once** on failure, with zero delay. require 'require-retry' @@ -133,18 +226,29 @@ return true. Use `@retry_exceptions = []` to **only** use callbacks, to determine if the job should retry. -Customise & Extend ------------------- +### Retry Arguments -Please take a look at the yardoc/code for more details on methods you may -wish to override. +You may override `args_for_retry`, which is passed the current +job arguments, to modify the arguments for the next retry attempt. -Some things worth noting: + class DeliverViaSMSC + extend Resque::Plugins::Retry + @queue = :mt_smsc_messages + # retry using the emergency SMSC. + def self.args_for_retry(smsc_id, mt_message) + [999, mt_message] + end + + self.perform(smsc_id, mt_message) + heavy_lifting + end + end + ### Job Identifier/Key The retry attempt is incremented and stored in a Redis key. The key is built using the `identifier`. If you have a lot of arguments or really long ones, you should consider overriding `identifier` to define a more precise @@ -168,31 +272,18 @@ self.perform(mt_id, mobile_number, message) heavy_lifting end end -### Retry Arguments +Contributing/Pull Requests +-------------------------- -You may override `args_for_retry`, which is passed the current -job arguments, to modify the arguments for the next retry attempt. + * Yes please! + * Fork the project. + * Make your feature addition or bug fix. + * Add tests for it. + * Commit. + * Send me a pull request. Bonus points for topic branches. + * If you edit the gemspec/version etc, do it in another commit please. - class DeliverViaSMSC - extend Resque::Plugins::Retry - @queue = :mt_smsc_messages - - # retry using the emergency SMSC. - def self.args_for_retry(smsc_id, mt_message) - [999, mt_message] - end - - self.perform(smsc_id, mt_message) - heavy_lifting - end - end - -Install -------- - - $ gem install resque-retry - [rq]: http://github.com/defunkt/resque -[rqs]: http://github.com/bvandenbos/resque-scheduler \ No newline at end of file +[rqs]: http://github.com/bvandenbos/resque-scheduler