retryable

Retryable

Description

Runs a code block, and retries it when an exception occurs. It's great when working with flakey webservices (for example).

It's configured using several optional parameters :tries, :on, :sleep, :matching, :ensure, :exception_cb, :not, :sleep_method and runs the passed block. Should an exception occur, it'll retry for (n-1) times.

Should the number of retries be reached without success, the last exception will be raised.

Installation

Install the gem:

$ gem install retryable

Add it to your Gemfile:

gem 'retryable'

Examples

Open an URL, retry up to two times when an OpenURI::HTTPError occurs.

require "open-uri"Retryable.retryable(tries: 3, on: OpenURI::HTTPError) do
  xml = open("http://example.com/test.xml").readend

Try the block forever.

# For ruby versions prior to 1.9.2 use :infinite symbol insteadRetryable.retryable(tries: Float::INFINITY) do
  # code hereend

Do something, retry up to four times for either ArgumentError orTimeout::Error exceptions.

Retryable.retryable(tries: 5, on: [ArgumentError, Timeout::Error]) do
  # code hereend

Ensure that the block of code is executed, regardless of whether an exception was raised. It doesn't matter if the block exits normally, if it retries to execute the block of code, or if it is terminated by an uncaught exception -- the :ensure block will get run.

f = File.open("testfile")ensure_cb = proc do |retries|  puts "total retry attempts: #{retries}"

  f.closeendRetryable.retryable(ensure: ensure_cb) do
  # process fileend

Defaults

contexts:     {},
ensure:       proc { },
exception_cb: proc { },
log_method:   proc { },
matching:     /.*/,
not:          [],
on:           StandardError,
sleep:        1,
sleep_method: lambda { |n| Kernel.sleep(n) },
tries:        2

Retryable also could be configured globally to change those defaults:

Retryable.configure do |config|  config.contexts     = {}
  config.ensure       = proc {}
  config.exception_cb = proc {}
  config.log_method   = proc {}
  config.matching     = /.*/
  config.not          = []
  config.on           = StandardError
  config.sleep        = 1
  config.sleep_method = lambda { |n| Kernel.sleep(n) }
  config.tries        = 2end

Sleeping

By default, Retryable waits for one second between retries. You can change this and even provide your own exponential backoff scheme.

Retryable.retryable(sleep: 0) { }                     # don't pause at all between retriesRetryable.retryable(sleep: 10) { }                    # sleep ten seconds between retriesRetryable.retryable(sleep: lambda { |n| 4**n }) { }   # sleep 1, 4, 16, etc. each try

Matching error messages

You can also retry based on the exception message:

Retryable.retryable(matching: /IO timeout/) do |retries, exception|  raise "oops IO timeout!" if retries == 0end#matching param supports array format as well:Retryable.retryable(matching: [/IO timeout/, "IO tymeout"]) do |retries, exception|  raise "oops IO timeout!" if retries == 0end

Block Parameters

Your block is called with two optional parameters: the number of tries until now, and the most recent exception.

Retryable.retryable do |retries, exception|  puts "try #{retries} failed with exception: #{exception}" if retries > 0
  # code hereend

Callback to run after an exception is rescued

exception_cb = proc do |exception|  # http://smartinez87.github.io/exception_notification
  ExceptionNotifier.notify_exception(exception, data: {message: "it failed"})endRetryable.retryable(exception_cb: exception_cb) do
  # code hereend

Logging

# or extract it to global config instead:log_method = lambda do |retries, exception|  Logger.new(STDOUT).debug("[Attempt ##{retries}] Retrying because [#{exception.class} - #{exception.message}]: #{exception.backtrace.first(5).join(' | ')}")endRetryable.retryable(log_method: log_method, matching: /IO timeout/) do |retries, exception|  raise "oops IO timeout!" if retries == 0end#D, [2018-09-01T18:19:06.093811 #22535] DEBUG -- : [Attempt #1] Retrying because [RuntimeError - oops IO timeout!]: (irb#1):6:in `block in irb_binding' | /home/nikita/Projects/retryable/lib/retryable.rb:73:in `retryable' | (irb#1):6:in `irb_binding' | /home/nikita/.rvm/rubies/ruby-2.5.0/lib/ruby/2.5.0/irb/workspace.rb:85:in `eval' | /home/nikita/.rvm/rubies/ruby-2.5.0/lib/ruby/2.5.0/irb/workspace.rb:85:in `evaluate'

If you prefer to use Rails' native logger:

log_method = lambda do |retries, exception|  Rails.logger.debug("[Attempt ##{retries}] Retrying because [#{exception.class} - #{exception.message}]: #{exception.backtrace.first(5).join(' | ')}")end

Contexts

Contexts allow you to extract common Retryable.retryable calling options for reuse or readability purposes.

Retryable.configure do |config|  config.contexts[:faulty_service] = {on: [FaultyServiceTimeoutError],sleep: 10,tries: 5
  }endRetryable.with_context(:faulty_service) {
  # code here}

You may also override options defined in your contexts:

# :on & sleep defined in the context earlier are still effectiveRetryable.with_context(:faulty_service, tries: 999) {
  # code here}

You can temporary disable retryable blocks

Retryable.enabled?=> trueRetryable.disableRetryable.enabled?=> false

Specify exceptions where a retry should NOT be performed

No more tries will be made if an exception listed in :not is raised. Takes precedence over :on.

class MyError < StandardError; endRetryable.retryable(tries: 5, on: [StandardError], not: [MyError]) do
  raise MyError "No retries!"end

Specify the :sleep_method to use

This can be very useful when you are working with Celluloid which implements its own version of the method sleep.

Retryable.retryable(sleep_method: Celluloid.method(:sleep)) do
  # code hereend

Supported Ruby Versions

This library aims to support and is tested against the following Ruby versions:

• Ruby 3.3

• Ruby 3.2

• Ruby 3.1

• Ruby 3.0

• Ruby 2.7

• Ruby 2.6

• Ruby 2.5

• Ruby 2.4

• Ruby 2.3

• Ruby 2.2

• Ruby 2.1

• Ruby 2.0

NOTE: if you need retryable to be running on Ruby 1.8 use gem versions prior to 3.0.0 release

If something doesn't work on one of these versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby versions, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version or implementation, you may volunteer to be a maintainer.