def_retry 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7d7d2f3cfa3b5fb99b74a57b3d40ebdbc03161ca
+  data.tar.gz: 3288a59b0594666400dcad6244f00c67182d4ad5
+SHA512:
+  metadata.gz: e10727f4637076e2cc7ac9a233e003bf917e355e2eab7a660b00952b1f169d24808498658a9c23b93bb1c2206fecd175d755f2f332d2f80041e3be00d4ef9816
+  data.tar.gz: 5fbe0d54a06c2c5cb547bf5e3e4d75c37ec31c083cb341ef0103de7d69e6c19bc0b81b153f0cca73f56618bdb3c434c62630eeeb884a8bcbd01492ba63e87208

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.rspec

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Diego Salazar
+
+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,96 @@
+# DefRetry
+
+An expressive, fully spec'd gem to add the Retry Pattern to your methods and/or objects. With DefRetry
+you can define methods with retry logic built-in or you can wrap your code in a
+`retry` and specify options to customize the behavior.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'def_retry'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install def_retry
+
+## Usage
+
+### Defining a retryable method
+
+```ruby
+require 'def_retry'
+
+class ApiWrapper
+  include DefRetry
+
+  def_retry :get_data, on: ApiError do
+    do_api_call
+  end
+end
+```
+
+This will define an instance method named `:get_data` and rescue the exception
+`ApiError` and retry the block:
+
+```ruby
+do
+  do_api_call
+end
+```
+3 times (the default).
+
+### Retrying a block of code
+
+```ruby
+require 'def_retry'
+
+class ApiWrapper
+  include DefRetry
+
+  def get_data
+    @some_state = 'start'
+
+    retryable on: ApiError do
+      @some_state = 'working'
+      do_api_call
+      @some_state = 'done'
+    end
+  end
+end
+```
+
+This will retry just that block of code.
+
+### Don't want to mixin?
+
+Use `DefRetry.retry` directly:
+
+```ruby
+require 'def_retry'
+
+DefRetry.retry on: ApiError do
+  do_api_call
+end
+```
+
+### Options
+
+These apply to both `.def_retry` and `#retryable`:
+  - `:on`: A single class or an array of exception classes to be rescued
+  - `:tries`: Integer number of maximum retries to run. DefRetry will stop retrying if the retry count reaches this number
+  - `:sleep`: Either a Proc that receives the current try count as its only argument or a Symbol naming one of these sleep strategies: constant, linear, exponential (see: `DefRetry::Retrier::SLEEP_STRATEGIES`)
+  - `:on_retry`: A callback to run every time a retry happens i.e. the specified exception(s) are rescued. It will receive the exception that was rescued and the current try count as arguments, respectively.
+  - `:on_ensure`: A callback to run at the end before returning the block's value. It will receive the block's return value and the current try count as arguments, respectively.
+
+## Contributing
+
+1. Fork it ( https://github.com/DiegoSalazar/def_retry/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/def_retry.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'def_retry/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "def_retry"
+  spec.version       = DefRetry::VERSION
+  spec.authors       = ["Diego Salazar"]
+  spec.email         = ["diego@greyrobot.com"]
+  spec.summary       = %q{The Retry Pattern in a gem.}
+  spec.description   = %q{Allows you to define methods that will retry on exception or declare blocks of code with retry.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/def_retry.rb

@@ -0,0 +1,28 @@
+require "def_retry/version"
+
+module DefRetry
+  autoload :Retrier, 'def_retry/retrier'
+
+  def self.included(base)
+    base.extend ClassMethods
+    base.send :include, InstanceMethods
+  end
+
+  def self.retry(options, &block)
+    Retrier.new(options, block).run
+  end
+
+  module ClassMethods
+    def def_retry(name, options = {}, &block)
+      define_method name do
+        DefRetry.retry options, &block
+      end
+    end
+  end
+
+  module InstanceMethods
+    def retryable(options = {}, &block)
+      DefRetry.retry options, &block
+    end
+  end
+end

data/lib/def_retry/retrier.rb

@@ -0,0 +1,48 @@
+module DefRetry
+  class Retrier
+    DEFAULT_TRIES = 3
+    SLEEP_STRATEGIES = {
+      constant:    ->(n) { 1 },
+      linear:      ->(n) { n },
+      exponential: ->(n) { n**2 }
+    }
+
+    def initialize(options, block)
+      @block     = block
+      @tries     = options.fetch :tries, DEFAULT_TRIES
+      @on_retry  = options.fetch :on_retry, ->(e, n) {}
+      @on_ensure = options.fetch :on_ensure, ->(r, n) {}
+      @sleep     = options.fetch :sleep, false
+
+      begin
+        @sleep = SLEEP_STRATEGIES.fetch @sleep if @sleep.is_a? Symbol
+      rescue KeyError
+        raise ArgumentError, "The :sleep option must be a Proc or one of: #{SLEEP_STRATEGIES.keys.join(', ')}"
+      end
+
+      begin
+        @exceptions = Array options.fetch(:on)
+      rescue KeyError
+        raise ArgumentError, 'You must specify which :exceptions to retry on'
+      end
+    end
+
+    def run
+      @try_count = 0
+      @return = nil
+
+      begin
+        @return = @block.call
+      rescue *@exceptions => e
+        @try_count += 1
+        sleep @sleep.call(@try_count) if @sleep
+        @on_retry.call e, @try_count
+
+        retry if @try_count < @tries
+      ensure
+        @on_ensure.call @return, @try_count
+        @return
+      end
+    end
+  end
+end

data/lib/def_retry/version.rb

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

data/spec/def_retry_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+require 'def_retry'
+
+class MockRetryable
+  include DefRetry
+
+  def_retry :api_call, on: Exception do
+    1 + 1 # expensive API call!
+  end
+end
+
+describe DefRetry do
+  let(:mock_retryable) { MockRetryable }
+
+  context '.def_retry' do
+    it 'defines an instance method' do
+      expect(mock_retryable.new).to respond_to :api_call
+    end
+  end
+
+  context '#retryable' do
+    it "returns the block's value" do
+      mocked = mock_retryable.new
+      expect(mocked.retryable(on: Exception) { 2 + 2 }).to be 4
+    end
+  end
+end
+
+# Note: see retrier_spec.rb for full specs

data/spec/retrier_spec.rb

@@ -0,0 +1,160 @@
+require 'spec_helper'
+require 'def_retry/retrier'
+
+describe DefRetry::Retrier do
+  let :block_exception do
+    -> {
+      @retries ||= 0
+      @retries += 1
+      raise Exception
+    }
+  end
+
+  context '#new' do
+    it 'requires exceptions to be specified' do
+      expect {
+        DefRetry::Retrier.new({}, -> {})
+      }.to raise_error ArgumentError
+    end
+
+    it 'complains about invalid sleep strategies' do
+      expect {
+        DefRetry::Retrier.new({
+          on: Exception,
+          sleep: :invalid
+        }, -> {})
+      }.to raise_error ArgumentError
+    end
+  end
+
+  context '#run' do
+    it 'executes the block and returns its value' do
+      the_block = -> { :ran }
+      retrier = DefRetry::Retrier.new({
+        on: Exception
+      }, the_block)
+
+      expect(retrier.run).to be :ran
+    end
+
+    it 'retries on exception :limit times' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        tries: 2
+      }, block_exception)
+
+      retrier.run
+      expect(@retries).to be 2
+    end
+
+    it 'raises unspecified exceptions' do
+      retrier = DefRetry::Retrier.new({
+        on: ArgumentError
+      }, block_exception)
+
+      expect { retrier.run }.to raise_error Exception
+    end
+
+    it 'runs an on_retry callback' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        on_retry: ->(e, n) { @did_retry = :yes }
+      }, block_exception)
+
+      retrier.run
+      expect(@did_retry).to be :yes
+    end
+
+    it 'runs an on_ensure callback' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        on_ensure: ->(r, n) { @did_ensure = :yes }
+      }, -> {})
+
+      retrier.run
+      expect(@did_ensure).to be :yes
+    end
+
+    it 'passes the exception and retry count to on_retry' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        on_retry: ->(e, r) {
+          @exception = e
+          @retry_count = r
+        }
+      }, block_exception)
+
+      retrier.run
+      expect(@exception).to be_kind_of Exception
+      expect(@retry_count).to be 3 # default limit
+    end
+
+    it 'passes the return value and retry count to on_ensure' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        on_ensure: ->(v, r) {
+          @value = v
+          @retry_count = r
+        }
+      }, -> { :ran })
+
+      retrier.run
+      expect(@value).to be :ran
+      expect(@retry_count).to be 0 # default limit
+    end
+  end
+
+  context '#run with :constant sleep strategy' do
+    it 'sleeps for 2 seconds' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        sleep: :constant,
+        # the 1st retry will sleep for 1 second
+        # the 2nd retry will sleep for 1 second
+        tries: 2
+      }, block_exception)
+
+      start_time = Time.now.to_i
+      retrier.run
+      end_time = Time.now.to_i
+
+      expect(end_time - start_time).to be 2
+    end
+  end
+
+  context '#run with :linear sleep strategy' do
+    it 'sleeps for 3 seconds' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        sleep: :linear,
+        # the 1st retry will sleep for 1 second
+        # the 2nd retry will sleep for 2 seconds, and so on
+        tries: 2
+      }, block_exception)
+
+      start_time = Time.now.to_i
+      retrier.run
+      end_time = Time.now.to_i
+
+      expect(end_time - start_time).to be 3
+    end
+  end
+
+  context '#run with :exponential sleep strategy' do
+    it 'sleeps for 5 seconds' do
+      retrier = DefRetry::Retrier.new({
+        on: Exception,
+        sleep: :exponential,
+        # the 1st retry will sleep for 1**2 == 1 second
+        # the 2nd retry will sleep for 2**2 == 4 seconds
+        tries: 2
+      }, block_exception)
+
+      start_time = Time.now.to_i
+      retrier.run
+      end_time = Time.now.to_i
+
+      expect(end_time - start_time).to be 5
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: def_retry
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Diego Salazar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows you to define methods that will retry on exception or declare
+  blocks of code with retry.
+email:
+- diego@greyrobot.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- def_retry.gemspec
+- lib/def_retry.rb
+- lib/def_retry/retrier.rb
+- lib/def_retry/version.rb
+- spec/def_retry_spec.rb
+- spec/retrier_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: The Retry Pattern in a gem.
+test_files:
+- spec/def_retry_spec.rb
+- spec/retrier_spec.rb
+- spec/spec_helper.rb