Retriable

Retriable is an simple DSL to retry failed code blocks with randomized exponential backoff time intervals. This is especially useful when interacting external api/services or file system calls.

Requirements

Ruby 2.0+

If you need 1.9.x support, use the 1.x branch.

WARNING: 2.x isn't API compatible with 1.x.

Installation

via command line:

gem install retriable

In your ruby script:

require 'retriable'

In your Gemfile:

gem 'retriable', '~> 2.0'

Usage

Code in a Retriable.retriable block will be retried if an exception is raised. By default, Retriable will rescue any exception inherited from StandardError, make 3 retry tries before raising the last exception, and also use randomized exponential backoff to calculate each succeeding try interval. The default interval table with 10 tries looks like this (in seconds):

require 'retriable'

class Api
  # Use it in methods that interact with unreliable services
  def get
    Retriable.retriable do
      # code here...
    end
  end
end

Options

Here are the available options:

tries (default: 3) - Number of tries to make at running your code block.

base_interval (default: 0.5) - The initial interval in seconds between tries.

max_interval (default: 60) - The maximum interval in seconds that any try can reach.

rand_factor (default: 0.25) - The percent range above and below the next interval is randomized between. The calculation is calculated like this:

randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])

multiplier (default: 1.5) - Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.

max_elapsed_time (default: 900 (15 min)) - The maximum amount of total time that code is allowed to keep being retried.

intervals (default: nil) - Skip generated intervals and provide your own array of intervals in seconds. Setting this option will ignore tries, base_interval, max_interval, rand_factor, and multiplier values.

timeout (default: 0) - Number of seconds to allow the code block to run before raising a Timeout::Error

on (default: [StandardError]) - An Array of exceptions to rescue for each try, a Hash where the keys are Exception classes and the values can be a single Regexp pattern or a list of patterns, or a single Exception type.

on_retry - (default: nil) - Proc to call after each try is rescued.

Config

You can change the global defaults with a #configure block:

Retriable.configure do |c|
  c.tries = 5
  c.max_elapsed_time = 3600 # 1 hour
end

Examples

Retriable.retriable accepts custom arguments. This example will only retry on a Timeout::Error, retry 3 times and sleep for a full second before each try.

Retriable.retriable on: Timeout::Error, tries: 3, base_interval: 1 do
  # code here...
end

You can also specify multiple errors to retry on by passing an array of exceptions.

Retriable.retriable on: [Timeout::Error, Errno::ECONNRESET] do
  # code here...
end

You can also specify a Hash of exceptions where the values are a list or single Regexp pattern.

Retriable.retriable on: {
  ActiveRecord::RecordNotUnique => nil,
  ActiveRecord::RecordInvalid => [/Email has already been taken/, /Username has already been taken/],
  Mysql2::Error => /Duplicate entry/
} do
  # code here...
end

You can also specify a timeout if you want the code block to only make an try for X amount of seconds. This timeout is per try.

Retriable.retriable timeout: 60 do
  # code here...
end

If you need millisecond units of time for the sleep or the timeout:

Retriable.retriable base_interval: (200/1000.0), timeout: (500/1000.0) do
  # code here...
end

Custom Interval Array

You can also bypass the built-in interval generation and provide your own array of intervals. Supplying your own intervals overrides the tries, base_interval, max_interval, rand_factor, and multiplier parameters.

Retriable.retriable intervals: [0.5, 1.0, 2.0, 2.5] do
  # code here...
end

Turn off Exponential Backoff

Exponential backoff is enabled by default, if you want to simply execute code every second, you can do this:

Retriable.retriable base_interval: 1.0, multiplier: 1.0, rand_factor: 0.0 do
  # code here...
end

If you don't want exponential backoff, but you still want some randomization between intervals, this code will run every 1 seconds with a randomization factor of 0.2, which means each interval will be a random value between 0.8 and 1.2 (1 second +/- 0.2):

Retriable.retriable base_interval: 1.0, multiplier: 1.0, rand_factor: 0.2 do
  # code here...
end

Callbacks

#retriable also provides a callback called :on_retry that will run after an exception is rescued. This callback provides the exception that was raised in the current try, the try_number, the elapsed_time for all tries so far, and the time in seconds of the next_interval. As these are specified in a Proc, unnecessary variables can be left out of the parameter list.

do_this_on_each_retry = Proc.new do |exception, try, elapsed_time, next_interval|
  log "#{exception.class}: '#{exception.message}' - #{try} tries in #{elapsed_time} seconds and #{next_interval} seconds until the next try."}
end

Retriable.retriable on_retry: do_this_on_each_retry do
  # code here...
end

Ensure/Else

What if I want to execute a code block at the end, whether or not an exception was rescued (ensure)? Or, what if I want to execute a code block if no exception is raised (else)? Instead of providing more callbacks, I recommend you just wrap retriable in a begin/retry/else/ensure block:

begin
  Retriable.retriable do
    # some code
  end
rescue => e
  # run this if retriable ends up re-rasing the exception
else
  # run this if retriable doesn't raise any exceptions
ensure
  # run this no matter what, exception or no exception
end

Kernel Extension

If you want to call Retriable.retriable without the Retriable module prefix and you don't mind extending Kernel, there is a kernel extension available for this.

In your ruby script:

require 'retriable/core_ext/kernel'

or in your Gemfile:

gem 'retriable', require: 'retriable/core_ext/kernel'

and then you can call #retriable in any context like this:

retriable do
  # code here...
end

Credits

Retriable was originally forked from the retryable-rb gem by Robert Sosinski, which in turn originally inspired by code written by Michael Celona and later assisted by David Malin. The attempt gem by Daniel J. Berger was also an inspiration.