retryable-rb 1.0.0

data/CHANGELOG

@@ -0,0 +1 @@
+v1.0.0. First release.

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Robert Sosinski (http://www.robertsosinski.com)
+
+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/Manifest

@@ -0,0 +1,9 @@
+CHANGELOG
+LICENSE
+Manifest
+README.markdown
+Rakefile
+lib/retryable.rb
+retryable-rb.gemspec
+retryable.gemspec
+test/retryable_test.rb

data/README.markdown

@@ -0,0 +1,82 @@
+Introduction
+============
+
+Retryable 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.
+
+Installation
+------------
+
+    gem install retryable
+
+    # In your ruby application
+    require 'retryable'
+
+Using Retryable
+---------------
+
+Code wrapped in a Retryable 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.
+
+    # Include Retryable into your class
+    class Api
+      include Retryable
+    
+      # Use it in methods that interact with unreliable services
+      def get
+        retryable do
+          # code here...
+        end
+      end
+    end
+    
+By default, Retryable will rescue any exception inherited from `Exception`, retry once (for a total of two attempts) and sleep for 100 milliseconds.  You can choose additional options by passing them via an options `Hash`.
+
+    retryable :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.
+
+    retryable :on => [Timeout::Error, Errno::ECONNRESET] do
+      # code here...
+    end
+
+Retryable also allows for callbacks to be defined, which is useful to log failures for analytics purposes or cleanup after repeated failures.  Retryable has three types of callbacks: `then`, `finally`, and `always`.
+
+`then`: Run every time a failure occurs.
+
+`finally`: Run when the number of retries runs out.
+
+`always`: Run when the code wrapped in a Retryable block passes or when the number of retries runs out.
+
+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 Retryable block and the callbacks defined.
+
+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.
+
+    then_cb = Proc.new do |exception, handler, attempts, retries, times|
+      log "#{exception.class}: '#{exception.message}' - #{attempts} attempts, #{retries} out of #{times} retries left."}
+    end
+    
+    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
+    
+    always_cb = Proc.new do |handler, attempts|
+      log "total time for #{attempts} attempts: #{Time.now - handler[:start]}"
+    end
+
+    retryable :then => then_cb do, :finally => finally_cb, :always => always_cb |handler|
+      handler[:start] ||= Time.now
+    
+      # code here...
+    end
+
+If you are using Retryable once or outside of a class, you can also use it via its module method as well.
+
+    Retryable.retryable do
+      # code here...
+    end
+
+Credits
+-------
+
+Retryable was inspired by code written by [Michael Celona](http://github.com/mcelona) and later assisted by [David Malin](http://github.com/dmalin).

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rake'
+require 'rake/testtask'
+require 'echoe'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+end
+
+Echoe.new("retryable-rb") do |p|
+  p.author = "Robert Sosinski"
+  p.email = "email@robertsosinski.com"
+  p.url = "http://github.com/robertsosinski/retryable"
+  p.description = p.summary = "Easy to use DSL to retry code if an exception is raised."
+  p.runtime_dependencies = []
+  p.development_dependencies = ["echoe >=4.3.1"]
+end

data/lib/retryable.rb

@@ -0,0 +1,33 @@
+module Retryable
+  extend self
+  
+  def retryable(options = {})
+    opts    = {:on => Exception, :times => 1, :sleep => 0.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]
+        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

data/retryable-rb.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{retryable-rb}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Robert Sosinski"]
+  s.date = %q{2011-04-12}
+  s.description = %q{Easy to use DSL to retry code if an exception is raised.}
+  s.email = %q{email@robertsosinski.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.markdown", "lib/retryable.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.markdown", "Rakefile", "lib/retryable.rb", "retryable-rb.gemspec", "retryable.gemspec", "test/retryable_test.rb"]
+  s.homepage = %q{http://github.com/robertsosinski/retryable}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Retryable-rb", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{retryable-rb}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Easy to use DSL to retry code if an exception is raised.}
+  s.test_files = ["test/retryable_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<echoe>, [">= 4.3.1"])
+    else
+      s.add_dependency(%q<echoe>, [">= 4.3.1"])
+    end
+  else
+    s.add_dependency(%q<echoe>, [">= 4.3.1"])
+  end
+end

data/retryable.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{retryable}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Robert Sosinski"]
+  s.date = %q{2011-04-11}
+  s.description = %q{Easy to use DSL to retry code if an exception is raised.}
+  s.email = %q{email@robertsosinski.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.markdown", "lib/retryable.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.markdown", "Rakefile", "lib/retryable.rb", "retryable.gemspec", "test/retryable_test.rb"]
+  s.homepage = %q{http://github.com/robertsosinski/retryable}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Retryable", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{retryable}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Easy to use DSL to retry code if an exception is raised.}
+  s.test_files = ["test/retryable_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<echoe>, [">= 4.3.1"])
+    else
+      s.add_dependency(%q<echoe>, [">= 4.3.1"])
+    end
+  else
+    s.add_dependency(%q<echoe>, [">= 4.3.1"])
+  end
+end

data/test/retryable_test.rb

@@ -0,0 +1,72 @@
+$:.unshift(File.dirname(__FILE__) + "../lib")
+
+require 'test/unit'
+require 'retryable'
+
+class RetryableTest < Test::Unit::TestCase
+  def test_without_arguments
+    i = 0
+    
+    Retryable.retryable do
+      i += 1
+      
+      raise Exception.new
+    end
+  rescue Exception
+    assert_equal i, 2
+  end
+  
+  def test_with_one_exception_and_two_times
+    i = 0
+    
+    Retryable.retryable :on => EOFError, :times => 2 do
+      i += 1
+      
+      raise EOFError.new
+    end
+  
+  rescue EOFError
+    assert_equal i, 3
+  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
+      
+      Retryable.retryable :on => [EOFError, ArgumentError], :then => then_cb, :finally => finally_cb, :always => always_cb, :times => 5, :sleep => 0.2 do |h|
+        i += 1
+        
+        h[:value] = true
+        
+        raise ArgumentError.new
+      end
+      
+    rescue ArgumentError
+      assert_equal i, 6
+    end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification 
+name: retryable-rb
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Robert Sosinski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-12 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 4
+        - 3
+        - 1
+        version: 4.3.1
+  type: :development
+  version_requirements: *id001
+description: Easy to use DSL to retry code if an exception is raised.
+email: email@robertsosinski.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- LICENSE
+- README.markdown
+- lib/retryable.rb
+files: 
+- CHANGELOG
+- LICENSE
+- Manifest
+- README.markdown
+- Rakefile
+- lib/retryable.rb
+- retryable-rb.gemspec
+- retryable.gemspec
+- test/retryable_test.rb
+has_rdoc: true
+homepage: http://github.com/robertsosinski/retryable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Retryable-rb
+- --main
+- README.markdown
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: retryable-rb
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Easy to use DSL to retry code if an exception is raised.
+test_files: 
+- test/retryable_test.rb