retries 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+Gemfile.lock
+doc/
+.yardoc/

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected --markup=markdown -- lib/**/*.rb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in retries.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ooyala, Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# Retries
+
+Retries is a small gem that provides a single function, `with_retries`, to evaluate a block with randomized,
+truncated, exponential backoff.
+
+There are similar projects out there (see [here](https://github.com/afazio/retry_block) and
+[here](https://bitbucket.org/amanking/retry_this/wiki/Home)) but these will require you to implement the
+backoff scheme yourself. If you don't need randomized exponential backoff, you should check out those gems.
+
+## Installation
+
+You can get the gem with `gem install retries` or simply add `gem "retries"` to your Gemfile if you're using
+bundler.
+
+## Usage
+
+Suppose we have some task we are trying to perform: `do_the_thing`. This might be a call to a third-party API
+or a flaky service. Here's how you can try it three times before failing:
+
+``` ruby
+require "retries"
+
+with_retries(:max_tries => 3) { do_the_thing }
+```
+
+The block is passed a single parameter, `attempt_number`, which is the number of attempts that have been made
+(starting at 1):
+
+``` ruby
+with_retries(:max_tries => 3) do |attempt_number|
+  puts "Trying to do the thing: attempt #{attempt_number}"
+  do_the_thing
+end
+```
+
+### Custom exceptions
+
+By default `with_retries` rescues instances of `StandardError`. You'll likely want to make this more specific
+to your use case. You may provide an exception class or an array of classes:
+
+``` ruby
+with_retries(:max_tries => 3, :rescue => RestClient::Exception) { do_the_thing }
+with_retries(:max_tries => 3, :rescue => [RestClient::Unauthorized, RestClient::RequestFailed]) do
+  do_the_thing
+end
+```
+
+### Handlers
+
+`with_retries` allows you to pass a custom handler that will be called each time before the block is retried.
+The handler will be called with two arguments: `exception` (the rescued exception) and `attempt_number` (the
+number of attempts that have been made thus far).
+
+``` ruby
+handler = Proc.new do |exception, attempt_number|
+  puts "Handler saw a #{exception.class}; retry attempt #{attempt_number}"
+end
+with_retries(:max_tries => 5, :handler => handler, :rescue => [RuntimeError, ZeroDivisionError]) do |attempt|
+  (1 / 0) if attempt == 3
+  raise "hey!" if attempt < 5
+end
+```
+
+This will print:
+
+```
+Handler saw a RuntimeError; retry attempt 1
+Handler saw a RuntimeError; retry attempt 2
+Handler saw a ZeroDivisionError; retry attempt 3
+Handler saw a RuntimeError; retry attempt 4
+```
+
+### Delay parameters
+
+By default, `with_retries` will wait about a half second between the first and second attempts, and then the
+delay time will increase exponentially between attempts (but stay at no more than 1 second). The delays are
+perturbed randomly. You can control the parameters via the two options `:base_sleep_seconds` and
+`:max_sleep_seconds`. For instance, you can start the delay at 100ms and go up to a maximum of about 2
+seconds:
+
+``` ruby
+with_retries(:max_tries => 10, :base_sleep_seconds => 0.1, :max_sleep_seconds => 2.0) { do_the_thing }
+```
+
+## Issues
+
+File tickets here on Github.
+
+## Development
+
+To run the tests: first clone the repo, then
+
+    $ bundle install
+    $ bundle exec rake test
+
+## License
+
+Retries is released under the [MIT License](http://opensource.org/licenses/mit-license.php/).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :test => ["test:units"]
+
+namespace :test do
+  Rake::TestTask.new(:units) do |task|
+    task.test_files = FileList["test/**/*.rb"]
+  end
+end

data/lib/retries.rb

@@ -0,0 +1,50 @@
+require "retries/version"
+
+module Kernel
+  # Runs the supplied code block an retries with an exponential backoff.
+  #
+  # @param [Hash] options the retry options.
+  # @option options [Fixnum] :max_tries (3) The maximum number of times to run the block.
+  # @option options [Float] :base_sleep_seconds (0.5) The starting delay between retries.
+  # @option options [Float] :max_sleep_seconds (1.0) The maximum to which to expand the delay between retries.
+  # @option options [Proc] :handler (nil) If not `nil`, a `Proc` that will be called for each retry. It will be
+  #         passed two arguments, `exception` (the rescued exception) and `attempt_number`.
+  # @option options [Exception, <Exception>] :rescue (StandardError) This may be a specific exception class to
+  #         rescue or an array of classes.
+  # @yield [attempt_number] The (required) block to be executed, which is passed the attempt number as a
+  #         parameter.
+  def with_retries(options = {}, &block)
+    # Check the options and set defaults
+    options_error_string = "Error with options to with_retries:"
+    max_tries = options[:max_tries] || 3
+    raise "#{options_error_string} :max_tries must be greater than 0." unless max_tries > 0
+    base_sleep_seconds = options[:base_sleep_seconds] || 0.5
+    max_sleep_seconds = options[:max_sleep_seconds] || 1.0
+    if base_sleep_seconds > max_sleep_seconds
+      raise "#{options_error_string} :base_sleep_seconds cannot be greater than :max_sleep_seconds."
+    end
+    handler = options[:handler]
+    exception_types_to_rescue = options[:rescue] || StandardError
+    exception_types_to_rescue = [exception_types_to_rescue] unless exception_types_to_rescue.is_a?(Array)
+    raise "#{options_error_string} with_retries must be passed a block" unless block_given?
+
+    # Let's do this thing
+    attempts = 0
+    begin
+      attempts += 1
+      return block.call(attempts)
+    rescue *exception_types_to_rescue => exception
+      raise exception if attempts >= max_tries
+      handler.call(exception, attempts) if handler
+      # The sleep time is an exponentially-increasing function of base_sleep_seconds. But, it never exceeds
+      # max_sleep_seconds.
+      sleep_seconds = [base_sleep_seconds * (2 ** (attempts - 1)), max_sleep_seconds].min
+      # Randomize to a random value in the range sleep_seconds/2 .. sleep_seconds
+      sleep_seconds = sleep_seconds * (0.5 * (1 + rand()))
+      # But never sleep less than base_sleep_seconds
+      sleep_seconds = [base_sleep_seconds, sleep_seconds].max
+      sleep sleep_seconds
+      retry
+    end
+  end
+end

data/lib/retries/version.rb

@@ -0,0 +1,3 @@
+module Retries
+  VERSION = "0.0.1"
+end

data/retries.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/retries/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Caleb Spare"]
+  gem.email         = ["caleb@ooyala.com"]
+  gem.description   = %q{Retries is a gem for retrying blocks with randomized exponential backoff.}
+  gem.summary       = %q{Retries is a gem for retrying blocks with randomized exponential backoff.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "retries"
+  gem.require_paths = ["lib"]
+  gem.version       = Retries::VERSION
+
+  # For running the tests
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "scope"
+
+  # For generating the documentation
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "redcarpet"
+end

data/test/retries_test.rb

@@ -0,0 +1,73 @@
+require "scope"
+require "minitest/autorun"
+
+$:.unshift File.join(File.dirname(__FILE__), "../lib")
+require "retries"
+
+class CustomErrorA < RuntimeError; end
+class CustomErrorB < RuntimeError; end
+
+class RetriesTest < Scope::TestCase
+  context "with_retries" do
+    should "retry until successful" do
+      tries = 0
+      result = with_retries(:max_tries => 4, :base_sleep_seconds => 0, :max_sleep_seconds => 0,
+                            :rescue => CustomErrorA) do |attempt|
+        tries += 1
+        # Verify that the attempt number passed in is accurate
+        assert_equal tries, attempt
+        raise CustomErrorA.new if tries < 4
+        "done"
+      end
+      assert_equal "done", result
+      assert_equal 4, tries
+    end
+
+    should "re-raise after :max_tries" do
+      assert_raises(CustomErrorA) do
+        with_retries(:base_sleep_seconds => 0, :max_sleep_seconds => 0, :rescue => CustomErrorA) do
+          raise CustomErrorA.new
+        end
+      end
+    end
+
+    should "immediately raise any exception not specified by :rescue" do
+      tries = 0
+      assert_raises(CustomErrorA) do
+        with_retries(:base_sleep_seconds => 0, :max_sleep_seconds => 0, :rescue => CustomErrorB) do
+          tries += 1
+          raise CustomErrorA.new
+        end
+      end
+      assert_equal 1, tries
+    end
+
+    should "allow for catching any of an array of exceptions specified by :rescue" do
+      result = with_retries(:max_tries => 3, :base_sleep_seconds => 0, :max_sleep_seconds => 0,
+                   :rescue => [CustomErrorA, CustomErrorB]) do |attempt|
+        raise CustomErrorA.new if attempt == 0
+        raise CustomErrorB.new if attempt == 1
+        "done"
+      end
+      assert_equal "done", result
+    end
+
+    should "run :handler with the expected arguments upon each handled exception" do
+      exception_handler_run_times = 0
+      tries = 0
+      handler = Proc.new do |exception, attempt_number|
+        exception_handler_run_times += 1
+        # Check that the handler is passed the proper exception and attempt number
+        assert_equal exception_handler_run_times, attempt_number
+        assert exception.is_a?(CustomErrorA)
+      end
+      with_retries(:max_tries => 4, :base_sleep_seconds => 0, :max_sleep_seconds => 0, :handler => handler,
+                   :rescue => CustomErrorA) do
+        tries += 1
+        raise CustomErrorA.new if tries < 4
+      end
+      assert_equal 4, tries
+      assert_equal 3, exception_handler_run_times
+    end
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: retries
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Caleb Spare
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-15 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &19157880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19157880
+- !ruby/object:Gem::Dependency
+  name: scope
+  requirement: &19157420 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19157420
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &19156980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19156980
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &19156540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19156540
+description: Retries is a gem for retrying blocks with randomized exponential backoff.
+email:
+- caleb@ooyala.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/retries.rb
+- lib/retries/version.rb
+- retries.gemspec
+- test/retries_test.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Retries is a gem for retrying blocks with randomized exponential backoff.
+test_files:
+- test/retries_test.rb
+has_rdoc: