Retriable

Retriable is a simple DSL to retry failed code blocks with randomized exponential backoff time intervals. This is especially useful when interacting external APIs, remote services, or file system calls.

Requirements

Ruby 2.3.0+

If you need ruby 2.0.0-2.2.x support, use the 3.1 branch by specifying ~3.1 in your Gemfile.

If you need ruby 1.9.3 support, use the 2.x branch by specifying ~2.1 in your Gemfile.

If you need ruby 1.8.x to 1.9.2 support, use the 1.x branch by specifying ~1.4 in your Gemfile.

Installation

Via command line:

gem install retriable

In your ruby script:

require 'retriable'

In your Gemfile:

gem 'retriable', '~> 3.4'

Usage

Code in a Retriable.retriable block will be retried if an exception is raised.

require 'retriable'

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

Defaults

By default, Retriable will:

• rescue any exception inherited from StandardError
• make 3 tries (including the initial attempt) before raising the last exception
• use randomized exponential backoff to calculate each succeeding try interval.

The default interval table with 10 tries looks like this (in seconds, rounded to the nearest millisecond):

| Retry # | Min | Average | Max | | ------- | -------- | -------- | -------- | | 1 | 0.25 | 0.5 | 0.75 | | 2 | 0.375 | 0.75 | 1.125 | | 3 | 0.563 | 1.125 | 1.688 | | 4 | 0.844 | 1.688 | 2.531 | | 5 | 1.266 | 2.531 | 3.797 | | 6 | 1.898 | 3.797 | 5.695 | | 7 | 2.848 | 5.695 | 8.543 | | 8 | 4.271 | 8.543 | 12.814 | | 9 | 6.407 | 12.814 | 19.222 | | 10 | stop | stop | stop |

Options

Here are the available options, in some vague order of relevance to most common use patterns:

| Option | Default | Definition | | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tries | 3 | Number of attempts to make at running your code block (includes initial attempt). | | on | [StandardError] | Type of exceptions to retry. Read more. | | retry_if | nil | Callable (for example a Proc or lambda) that receives the rescued exception and returns true/false to decide whether to retry. Read more. | | on_retry | nil | Proc to call after each try is rescued. Read more. | | sleep_disabled | false | When true, disable exponential backoff and attempt retries immediately. | | base_interval | 0.5 | The initial interval in seconds between tries. | | max_elapsed_time | 900 (15 min) | The maximum amount of total time in seconds that code is allowed to keep being retried. Set to nil to disable the time limit and retry based solely on tries. | | max_interval | 60 | The maximum interval in seconds that any individual retry can reach. | | multiplier | 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. | | rand_factor | 0.5 | The percentage to randomize the next retry interval time. The next interval calculation is randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])