Giter Club home page Giter Club logo

retryable's Introduction

Retryable

Gem Version Gem Code Climate Test Coverage Inline docs

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").read
end

Try the block forever.

# For ruby versions prior to 1.9.2 use :infinite symbol instead
Retryable.retryable(tries: Float::INFINITY) do
  # code here
end

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

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

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.close
end

Retryable.retryable(ensure: ensure_cb) do
  # process file
end

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        = 2
end

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 retries
Retryable.retryable(sleep: 10) { }                    # sleep ten seconds between retries
Retryable.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 == 0
end

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

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 here
end

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"})
end

Retryable.retryable(exception_cb: exception_cb) do
  # code here
end

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(' | ')}")
end

Retryable.retryable(log_method: log_method, matching: /IO timeout/) do |retries, exception|
  raise "oops IO timeout!" if retries == 0
end
#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
  }
end


Retryable.with_context(:faulty_service) {
  # code here
}

You may also override options defined in your contexts:

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

You can temporary disable retryable blocks

Retryable.enabled?
=> true

Retryable.disable

Retryable.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; end

Retryable.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 here
end

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
  • Ruby 1.9

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.

retryable's People

Contributors

adsummos avatar amatsuda avatar bbonamin avatar chubchenko avatar cjbottaro avatar czottmann avatar darkhelmet avatar drunkel avatar jondruse avatar kml avatar m-nakamura145 avatar nfedyashev avatar opt-link avatar orien avatar peter50216 avatar reiz avatar speric avatar tas50 avatar y-yagi avatar ybiquitous avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

retryable's Issues

Feature: "Reset time" option for tries

Some kind of "reset time" option for tries would be nice.
When this option is set it should reset the tries count back to 0.
Why could this be useful?

I wrote a script that connects to a mysql server, sometimes i need to restart the server, so i wrapped my code with this gem.
When the server is restarting, a exception is raised, then it waits 10 seconds, the server is online again end everything is fine,
except i restart the server multiple times a week then the tries count is reached an the script stops.
but if i could define a timeout after the tries count is resetted this would work perfect.

sorry for my bad english, i hope you can understand what i mean.

Force-trigger exception/retry

Is there a way to force an exception that Retryable would pick up?
I'm trying to retry if HTTParty response.code is not a 200 or 204. I can get it to raise, but that goes to my begin/rescue, and skips out of Retryable's logic.

def httpPost(results, url = @url)
    #ensure_cb = Proc.new { |retries| puts "Total Retries: #{retries}" }
    exception_cb = Proc.new { |exception| puts "For URL: #{url}\nRetry-rescued error: #{exception.inspect}"}
    begin
      Retryable.retryable(:exception_cb => exception_cb, tries: 10, sleep: lambda { |n| 4**n }, on: [Errno::ECONNREFUSED, SocketError, Net::ReadTimeout, HTTParty::Error, Timeout::Error, Errno::EPIPE, OpenSSL::SSL::SSLError, EOFError]) do |retries, exception|
        response = HTTParty.post(url, body: results.to_json, headers: {'Content-Type' => 'application/json', 'User-Agent' => 'SendGrid 1.0'})
        puts "Attempt #{retries} failed with exception: #{exception}" if retries > 0
        exception if not [200, 204].include?(response.code) #throw http-code-level error if not a 200 or 204
        puts "Total Attempts: #{retries + 1}" if retries > 0
        return response
      end
    rescue StandardError => e
      puts "#{Time.now} - httpPost error: #{e.inspect}"
    end
  end

Update image version

Hi,

The version 3.0.5 is from 2019.
There are changes being made since then. I am interested specifically the ruby compatibility for the v3.1 and v3.2 that was done in Jan 2023.
Are those changes inside of 3.0.5 version? Do you plan on releasing a new image version?

Thanks!

Readme is confusing regarding sleep vs sleep_method

The default configuration object includes both sleep and sleep_method but the "Sleeping" section shows a lambda being given to sleep: and not sleep_method:

Is that an error in the Sleeping section? (I came here today because it seems that sleep with a lambda used to work but doesn't seem to be working now.

image

constant ::TimeoutError is deprecated

All references to TimeoutError should be changed to Timeout::Error, at least for Ruby versions newer than 2.3. It seems that TimeoutError was deprecated.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.