retriable 1.2.0 → 1.3.0

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+  - ree

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## 1.3.0
+
+* Rewrote a lot of the code with inspiration from [attempt](https://rubygems.org/gems/attempt).
+* Add timeout option to the code block.
+* Include in Kernel by default, but allow require 'retriable/no_kernel' to load a non kernel version.
+* Renamed `:times` option to `:tries`.
+* Renamed `:sleep` option to `:interval`.
+* Renamed `:then` option to `:on_retry`.
+* Removed other callbacks, you can wrap retriable in a begin/rescue/else/ensure block if you need that functionality. It avoids the need to define multiple Procs and makes the code more readable.
+* Rewrote most of the README
+
+## 1.2.0
+
+* Forked the retryable-rb repo.
+* Extend the Kernel module with the retriable method so you can use it anywhere without having to include it in every class.
+* Update gemspec, Gemfile, and Raketask.
+* Remove echoe dependency.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Robert Sosinski (http://www.robertsosinski.com)
+Copyright (c) 2012 Jack Chu (http://www.jackchu.com)
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -1,84 +1,125 @@
-Introduction
+Retriable
 ============
 
-Retriable is an easy to use DSL to retry code if an exception is raised.  This is especially useful when interacting with unreliable services that fail randomly.
+[![Build Status](https://secure.travis-ci.org/kamui/retriable.png)](http://travis-ci.org/kamui/retriable)
+
+Retriable is an simple DSL to retry code if an exception is raised.  This is especially useful when interacting external api/services or file system calls.
 
 Installation
 ------------
+Via command line:
 
-    gem install retriable
-
-    # In your ruby application
-    require 'retriable'
-
-    # In your Gemfile
-    gem 'retriable'
-
-Using Retriable
----------------
-
-Code wrapped in a retriable block will be retried if a failure occurs.  As such, code attempted once, will be retried again for another attempt if it fails to run.
-
-    require 'retriable'
-
-    class Api
-      # Use it in methods that interact with unreliable services
-      def get
-        retriable do
-          # code here...
-        end
-      end
-    end
-
-By default, Retriable will rescue any exception inherited from `Exception`, retry once (for a total of two attempts) and sleep for a random amount time (between 0 to 100 milliseconds, in 10 millisecond increments).  You can choose additional options by passing them via an options `Hash`.
-
-    retriable :on => Timeout::Error, :times => 3, :sleep => 1 do
-      # code here...
-    end
-
-This example will only retry on a `Timeout::Error`, retry 3 times (for a total of 4 attempts) and sleep for a full second before each retry.  You can also specify multiple errors to retry on by passing an array.
-
-    retriable :on => [Timeout::Error, Errno::ECONNRESET] do
-      # code here...
-    end
-
-You can also have Ruby retry immediately after a failure by passing `false` as the sleep option.
+```ruby
+gem install retriable
+```
 
-    retriable :sleep => false do
-      # code here...
-    end
+In your ruby script:
 
-Retriable also allows for callbacks to be defined, which is useful to log failures for analytics purposes or cleanup after repeated failures.  Retriable has three types of callbacks: `then`, `finally`, and `always`.
+```ruby
+require 'retriable'
+```
 
-`then`: Run every time a failure occurs.
+In your Gemfile:
 
-`finally`: Run when the number of retries runs out.
+```ruby
+gem 'retriable'
+```
 
-`always`: Run when the code wrapped in a retriable block passes or when the number of retries runs out.
+By default, requiring 'retriable' will include the #retriable method into th Kernel so that you can use it anywhere. If you don't want this behaviour, you can load a non-kernel included version:
 
-The `then` and `finally` callbacks pass the exception raised, which can be used for logging or error control.  All three callbacks also have a `handler`, which provides an interface to pass data between the code wrapped in the retriable block and the callbacks defined.
+```ruby
+gem 'retriable', require => 'retriable/no_kernel'
+```
 
-Furthermore, each callback provides the number of `attempts`, `retries` and `times` that the wrapped code should be retried.  As these are specified in a `Proc`, unnecessary variables can be left out of the parameter list.
+Or in your ruby script:
 
-    then_cb = Proc.new do |exception, handler, attempts, retries, times|
-      log "#{exception.class}: '#{exception.message}' - #{attempts} attempts, #{retries} out of #{times} retries left."}
-    end
+```ruby
+require 'retriable/no_kernel'
+```
 
-    finally_cb = Proc.new do |exception, handler|
-      log "#{exception.class} raised too many times. First attempt at #{handler[:start]} and final attempt at #{Time.now}"
-    end
+Usage
+---------------
 
-    always_cb = Proc.new do |handler, attempts|
-      log "total time for #{attempts} attempts: #{Time.now - handler[:start]}"
-    end
+Code in a retriable block will be retried if an exception is raised. By default, Retriable will rescue any exception inherited from `Exception` and make 3 retry attempts before raising the last exception.
 
-    retriable :then => then_cb do, :finally => finally_cb, :always => always_cb |handler|
-      handler[:start] ||= Time.now
+```ruby
+require 'retriable'
 
+class Api
+  # Use it in methods that interact with unreliable services
+  def get
+    retriable do
       # code here...
     end
+  end
+end
+```
+
+Here are the available options:
+
+`tries` (default: 3) - Number of attempts to make at running your code block
+`interval` (default: 0) - Number of seconds to sleep between attempts
+`timeout` (default: 0) - Number of seconds to allow the code block to run before raising a Timeout::Error
+`on` (default: Exception) - Exception or array of exceptions to rescue for each attempt
+`on_retry` - (default: nil) - Proc to call after each attempt is rescued
+
+You can pass options via an options `Hash`. This example will only retry on a `Timeout::Error`, retry 3 times and sleep for a full second before each attempt.
+
+```ruby
+retriable :on => Timeout::Error, :tries => 3, :interval => 1 do
+  # code here...
+end
+```
+
+You can also specify multiple errors to retry on by passing an array of exceptions.
+
+```ruby
+retriable :on => [Timeout::Error, Errno::ECONNRESET] do
+  # code here...
+end
+```
+
+You can also specify a timeout if you want the code block to only make an attempt for X amount of seconds. This timeout is per attempt.
+
+```ruby
+retriable :timeout => 1 do
+  # code here...
+end
+```
+
+If you need millisecond units of time for the sleep or the timeout:
+
+```ruby
+retriable :interval => (200/1000.0), :timeout => (500/1000.0) do
+  # code here...
+end
+```
+
+Retriable also provides a callback called `:on_retry` that will run after an exception is rescued. This callback provides the number of `tries`, and the `exception` that was raised in the current attempt. As these are specified in a `Proc`, unnecessary variables can be left out of the parameter list.
+
+```ruby
+on_retry = Proc.new do |exception, tries|
+  log "#{exception.class}: '#{exception.message}' - #{tries} attempts."}
+end
+```
+
+What if I want to execute a code block at the end, whether or not an exception was rescued ([ensure](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-ensure))? Or, what if I want to execute a code block if no exception is raised ([else](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-else))? Instead of providing more callbacks, I recommend you just wrap retriable in a begin/retry/else/ensure block:
+
+```ruby
+begin
+  retriable do
+    # some code
+  end
+rescue Exception => 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
+```
 
 Credits
 -------
 
-Retriable was originally forked from the retryable-rb gem by [Robert Sosinski](https://github.com/robertsosinski), which in turn originally inspired by code written by [Michael Celona](http://github.com/mcelona) and later assisted by [David Malin](http://github.com/dmalin).
+Retriable was originally forked from the retryable-rb gem by [Robert Sosinski](https://github.com/robertsosinski), which in turn originally inspired by code written by [Michael Celona](http://github.com/mcelona) and later assisted by [David Malin](http://github.com/dmalin). The [attempt](https://rubygems.org/gems/attempt) gem by Daniel J. Berger was also an inspiration.

data/Rakefile

@@ -4,7 +4,6 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
-
 task :default => :test
 
 desc "Run tests"

data/lib/retriable.rb

@@ -1,33 +1,4 @@
-require 'retriable/version'
+# encoding: utf-8
 
-module Kernel
-  def retriable(options = {})
-    opts    = {:on => Exception, :times => 1}.merge(options)
-    handler = {}
-
-    retry_exception = opts[:on].is_a?(Array) ? opts[:on] : [opts[:on]]
-    times = retries = opts[:times]
-    attempts        = 0
-
-    begin
-      attempts += 1
-
-      return yield(handler)
-    rescue *retry_exception => exception
-      opts[:then].call(exception, handler, attempts, retries, times) if opts[:then]
-
-      if attempts <= times
-        sleep(opts[:sleep] || (rand(11) / 100.0)) unless opts[:sleep] == false
-        retries -= 1
-        retry
-      else
-        opts[:finally].call(exception, handler, attempts, retries, times) if opts[:finally]
-        raise exception
-      end
-    ensure
-      opts[:always].call(handler, attempts, retries, times) if opts[:always]
-    end
-
-    yield(handler)
-  end
-end
+require 'retriable/no_kernel'
+require 'retriable/core_ext/kernel'

data/lib/retriable/core_ext/kernel.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+module Kernel
+  include Retriable
+end
+
+class Object
+  include Kernel
+end

data/lib/retriable/no_kernel.rb

@@ -0,0 +1,4 @@
+# encoding: utf-8
+
+require 'retriable/retriable'
+require 'retriable/version'

data/lib/retriable/retriable.rb

@@ -0,0 +1,64 @@
+# encoding: utf-8
+
+require 'timeout'
+
+module Retriable
+  class Retry
+    attr_accessor :tries
+    attr_accessor :interval
+    attr_accessor :timeout
+    attr_accessor :on
+    attr_accessor :on_retry
+
+    def initialize
+      @tries      = 3
+      @interval   = 0
+      @timeout    = nil
+      @on         = Exception
+      @on_retry   = nil
+
+      yield self if block_given?
+    end
+
+    def perform
+      count = 0
+      begin
+        if @timeout
+          Timeout::timeout(@timeout) { yield }
+        else
+          yield
+        end
+      rescue *[*on] => exception
+        @tries -= 1
+        if @tries > 0
+          count += 1
+          sleep @interval if @interval > 0
+          @on_retry.call(exception, count) if @on_retry
+          retry
+        else
+          raise
+        end
+      end
+    end
+  end
+
+  def retriable(options = {}, &block)
+    opts = {
+      :tries => 3,
+      :on => Exception,
+      :interval => 1
+    }
+
+    opts.merge!(options)
+
+    raise 'No block given' unless block_given?
+
+    Retry.new do |r|
+      r.tries      = opts[:tries]
+      r.on         = opts[:on]
+      r.interval   = opts[:interval]
+      r.timeout    = opts[:timeout] if opts[:timeout]
+      r.on_retry   = opts[:on_retry] if opts[:on_retry]
+    end.perform(&block)
+  end
+end

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Retriable
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/retriable.gemspec

@@ -1,4 +1,5 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
+
 $:.push File.expand_path("../lib", __FILE__)
 require "retriable/version"
 
@@ -18,4 +19,6 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
+  s.add_development_dependency 'minitest'
 end

data/test/retriable_test.rb

@@ -1,72 +1,46 @@
-$:.unshift(File.dirname(__FILE__) + "../lib")
+# encoding: utf-8
 
-require 'test/unit'
 require 'retriable'
+require 'minitest/autorun'
 
-class RetriableTest < Test::Unit::TestCase
+class RetriableTest < MiniTest::Unit::TestCase
   def test_without_arguments
     i = 0
 
     retriable do
       i += 1
-
       raise Exception.new
     end
   rescue Exception
-    assert_equal i, 2
+    assert_equal 3, i
   end
 
-  def test_with_one_exception_and_two_times
+  def test_with_one_exception_and_two_tries
     i = 0
 
-    retriable :on => EOFError, :times => 2 do
+    retriable :on => EOFError, :tries => 2 do
       i += 1
-
       raise EOFError.new
     end
 
   rescue EOFError
-    assert_equal i, 3
+    assert_equal i, 2
   end
 
-  def test_with_arguments_and_handler
-      i = 0
-
-      then_cb    = Proc.new do |e, h, a, r, t|
-        assert_equal e.class, ArgumentError
-        assert h[:value]
-
-        assert_equal a, i
-        assert_equal r, 6 - a
-        assert_equal t, 5
-      end
-
-      finally_cb = Proc.new do |e, h, a, r, t|
-        assert_equal e.class, ArgumentError
-        assert h[:value]
-
-        assert_equal a, 6
-        assert_equal r, 0
-        assert_equal t, 5
-      end
-
-      always_cb  = Proc.new do |h, a, r, t|
-        assert h[:value]
-
-        assert_equal a, 6
-        assert_equal r, 0
-        assert_equal t, 5
-      end
-
-      retriable :on => [EOFError, ArgumentError], :then => then_cb, :finally => finally_cb, :always => always_cb, :times => 5, :sleep => 0.2 do |h|
-        i += 1
-
-        h[:value] = true
+  def test_with_arguments
+    i = 0
 
-        raise ArgumentError.new
-      end
+    on_retry = Proc.new do |exception, tries|
+      assert_equal exception.class, ArgumentError
+      assert_equal i, tries
+    end
 
-    rescue ArgumentError
-      assert_equal i, 6
+    retriable :on => [EOFError, ArgumentError], :on_retry => on_retry, :tries => 5, :sleep => 0.2 do |h|
+      i += 1
+      raise ArgumentError.new
     end
+
+  rescue ArgumentError
+    assert_equal 5, i
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,19 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-10 00:00:00.000000000 Z
-dependencies: []
+date: 2012-02-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &2163262320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2163262320
 description: Easy to use DSL to retry code if an exception is raised.
 email:
 - jack@jackchu.com
@@ -19,12 +30,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- CHANGELOG
+- .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - lib/retriable.rb
+- lib/retriable/core_ext/kernel.rb
+- lib/retriable/no_kernel.rb
+- lib/retriable/retriable.rb
 - lib/retriable/version.rb
 - retriable.gemspec
 - test/retriable_test.rb
@@ -54,3 +69,4 @@ specification_version: 3
 summary: Easy to use DSL to retry code if an exception is raised.
 test_files:
 - test/retriable_test.rb
+has_rdoc: 

data/CHANGELOG

@@ -1 +0,0 @@
-v1.2.0. Fork the retryable-rb repo. Extend the Kernel module with the retriable method so you can use it anywhere without having to include it in every class. Update gemspec, Gemfile, and Raketask. Remove echoe dependency.