Skip to content
Yet another Ruby retry library.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib
test
.gitignore
.travis.yml
Gemfile
LICENSE.txt
README.md
Rakefile
reattempt.gemspec

README.md

Reattempt

Simple Enumerable APIs offering retries with exponential backoff and jitter.

Installation

Add this line to your application's Gemfile:

gem 'reattempt'

And then execute:

$ bundle

Or install it yourself as:

$ gem install reattempt

Synopsis

Simplest use with the defaults - 5 attempts, 0.02 to 1 second delay, 0.2 jitter (delay is randomised ±10%), catching StandardError:

begin
  Reattempt::Retry.new.each do
    poke_remote_api
  end
rescue Reattempt::RetriesExceeded => e
  handle_repeated_failure(e.cause)
end

Instances are thread-safe, and it's suggested that you separate their creation from usage: inject them as dependencies, configure them in class attributes, store them in constants, etc.

Usage

Reattempt consists of two main classes:

Backoff

Backoff implements a simple jittered exponential backoff calculator as an Enumerable:

# Start delay 0.075-0.125 seconds, increasing to 0.75-1.25 seconds
bo = Reattempt::Backoff.new(min_delay: 0.1, max_delay: 1.0, jitter: 0.5)

bo.take(4).map { |x| x.round(4) } # => [0.1138, 0.2029, 0.4227, 0.646]
bo.take(2).each { |delay| sleep delay }
bo.delay_for_attempt(4) # => 1.0403524624141058
bo[4] # => 0.8328055668923606

bo.each do |delay|
  printf("Sleeping for about %.2f seconds\n", delay)
  sleep delay
end

Note Backoff is strictly a calculator, it does not implement sleep itself.

The iterator is unbounded and you're expected to take however many you need, or manually exit the loop.

Retry

Retry implements a retrying iterator, catching the given Exception types and sleeping as per a configured Backoff instance.

bo = Reattempt::Backoff.new(min_delay: 0.1, max_delay: 1.0, jitter: 0.5)
try = Reattempt::Retry.new(tries: 5, rescue: TempError, backoff: bo)
begin
  try.each do |attempt|
    raise TempError, "Failed in attempt #{attempt}"
  end
rescue Reattempt::RetriesExceeded => e
  p e.cause # => #<TempError: "Failed in attempt 5">
end

rescue is coerced to an array, and its contents are simply expected to respond to ===, so you can do complex matching like this:

exception_matcher = ->(ex) do
  ex.is_a?(IOError) && ex.message.includes?('closed stream')
end

try = Reattempt::Retry.new(rescue: [exception_matcher, SomeOtherException])

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Freaky/ruby-reattempt.

License

The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.