retryable 2.0.4 → 3.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4adf6498d39c3a76bb6c3ea4c2ef8bd479d620b65c969cc43c970ae1dc1e8dd7
+  data.tar.gz: d60ff44f63519d2df8a70ca8729e5db2cda03e2b9ba2bf9af42dae66df9f65d5
+SHA512:
+  metadata.gz: 24fc7de390a5996451a2c9d0296811b031ce21e38a3c4374d4a002e3e12d6278c07f31a84dd86efcf9006fd2ff2f7ef40e40da791f2d98dedb56ee2b0c7b3006
+  data.tar.gz: '09360b246ca4c6868fc40807f1fc4978933f3aae138237efdb396e51e52a36fd2c8e1a44310365336cc9d43c08df62726d9d390739e3fdcce23640abdb0b2733'

data/CHANGELOG.md

@@ -1,8 +1,42 @@
+## Retryable 3.0.5 ##
+
+Instead of :infinite magic constant from now on you can just use Ruby's native infinity data type e.g. Float::INFINITY.
+See https://github.com/nfedyashev/retryable/commit/16f60bb09560c9470266dca8cd47c934594a67c5
+This version is backwards compatible with older versions, no changes needed in your code.
+
+## Retryable 3.0.4 ##
+
+Fixed typo in exception message given invalid :matching argument type https://github.com/nfedyashev/retryable/pull/29
+Thanks @msroz
+
+## Retryable 3.0.3 ##
+
+No changes to the source code, only added direct Changelog link on
+rubygems.org for ease of use.
+
+## Retryable 3.0.2 ##
+
+*   :log_method param has been added for flexible logging of your retries. It is silent by default.
+
+## Retryable 3.0.1 ##
+
+*   :matching param from now on could be called in form of array with multiple matching conditions. This version is backwards compatible with 3.0.0
+
+## Retryable 3.0.0 ##
+NOTE: this version is backwards compatible with 2.0.4 version unless you're running it against Ruby 1.8 version.
+
+*   retryable can now also be configured via stored contexts.
+*   Ruby 1.8 support has been dropped.
+
+    Thanks @chubchenko for refactoring and various improvements.
+
 ## Retryable 2.0.4 ##
 
 *   :infinite value is now available as :tries paramater.  Use it for retrying your blocks infinitely until it stops failing.
 *   :sleep_method parameter has been added. This can be very useful when you are working with Celluloid which implements its own version of the method sleep.
-    Use `:sleep_method => Celluloid.method(:sleep)` in such cases.
+    Use `:sleep_method: Celluloid.method(:sleep)` in such cases.
+
+    Thanks @alexcastano
 
 ## Retryable 2.0.3 ##
 

data/Gemfile

@@ -0,0 +1,20 @@
+source 'http://rubygems.org'
+
+gem 'rake', '~> 10.4'
+gem 'yard'
+
+group :development do
+  gem 'fasterer'
+  gem 'overcommit'
+  gem 'pry', '= 0.9.12.6'
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'codeclimate-test-reporter'
+  gem 'rspec', '~> 3.1'
+  gem 'simplecov', require: false
+end
+
+gemspec

data/README.md

@@ -1,8 +1,11 @@
-retryable gem
-=====
+# Retryable
 
+[![Gem Version](https://badge.fury.io/rb/retryable.svg)](https://badge.fury.io/rb/retryable)
 [![Build Status](https://travis-ci.org/nfedyashev/retryable.png?branch=master)](https://travis-ci.org/nfedyashev/retryable)
-[![Dependency Status](https://www.versioneye.com/ruby/retryable/badge.svg)](https://www.versioneye.com/ruby/retryable)
+[![Code Climate](https://codeclimate.com/github/nfedyashev/retryable/badges/gpa.svg)](https://codeclimate.com/github/nfedyashev/retryable)
+[![Test Coverage](https://codeclimate.com/github/nfedyashev/retryable/badges/coverage.svg)](https://codeclimate.com/github/nfedyashev/retryable/coverage)
+
+[![Inline docs](http://inch-ci.org/github/nfedyashev/retryable.svg?branch=master)](http://inch-ci.org/github/nfedyashev/retryable)
 
 Description
 --------
@@ -16,6 +19,21 @@ 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:
+
+``` bash
+$ gem install retryable
+```
+
+Add it to your Gemfile:
+
+``` ruby
+gem 'retryable'
+```
+
 
 Examples
 --------
@@ -25,24 +43,26 @@ Open an URL, retry up to two times when an `OpenURI::HTTPError` occurs.
 ``` ruby
 require "open-uri"
 
-Retryable.retryable(:tries => 3, :on => OpenURI::HTTPError) do
+Retryable.retryable(tries: 3, on: OpenURI::HTTPError) do
   xml = open("http://example.com/test.xml").read
 end
 ```
 
 Try the block forever.
 ```ruby
-Retryable.retryable(:tries => :infinite) do
-  # some code
+# 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
-`TimeoutError` exceptions.
+Do something, retry up to four times for either `ArgumentError` or
+`Timeout::Error` exceptions.
 
 ``` ruby
-Retryable.retryable(:tries => 5, :on => [ArgumentError, TimeoutError]) do
-  # some crazy code
+Retryable.retryable(tries: 5, on: [ArgumentError, Timeout::Error]) do
+  # code here
 end
 ```
 
@@ -51,33 +71,44 @@ Ensure that block of code is executed, regardless of whether an exception was ra
 ``` ruby
 f = File.open("testfile")
 
-ensure_cb = Proc.new do |retries|
+ensure_cb = proc do |retries|
   puts "total retry attempts: #{retries}"
 
   f.close
 end
 
-Retryable.retryable(:ensure => ensure_cb) do
+Retryable.retryable(ensure: ensure_cb) do
   # process file
 end
 ```
 
 ## Defaults
 
-    :tries => 2, :on => StandardError, :sleep => 1, :matching  => /.*/, :ensure => Proc.new { }, :exception_cb => Proc.new { }, :not => [], :sleep_method => lambda { |n| Kernel.sleep(n) }
+    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:
 
-```
+```ruby
 Retryable.configure do |config|
-  config.ensure       = Proc.new {}
-  config.exception_cb = Proc.new {}
+  config.contexts     = {}
+  config.ensure       = proc {}
+  config.exception_cb = proc {}
+  config.log_method   = proc {}
   config.matching     = /.*/
+  config.not          = []
   config.on           = StandardError
   config.sleep        = 1
-  config.tries        = 2
-  config.not          = []
   config.sleep_method = Celluloid.method(:sleep)
+  config.tries        = 2
 end
 ```
 
@@ -86,19 +117,24 @@ 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
+```ruby
+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 "yo, IO timeout!" if retries == 0
+```ruby
+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
 ```
 
@@ -106,31 +142,85 @@ Block Parameters
 --------
 Your block is called with two optional parameters: the number of tries until now, and the most recent exception.
 
-```
+```ruby
 Retryable.retryable do |retries, exception|
   puts "try #{retries} failed with exception: #{exception}" if retries > 0
-  pick_up_soap
+  # code here
 end
 ```
 
 Callback to run after an exception is rescued
 --------
 
-```
-exception_cb = Proc.new do |exception|
+```ruby
+exception_cb = proc do |exception|
   # http://smartinez87.github.io/exception_notification
-  ExceptionNotifier.notify_exception(exception, :data => {:message => "it failed"})
+  ExceptionNotifier.notify_exception(exception, data: {message: "it failed"})
 end
 
-Retryable.retryable(:exception_cb => exception_cb) do
-  # perform risky operation
+Retryable.retryable(exception_cb: exception_cb) do
+  # code here
 end
 ```
 
-You can temporary disable retryable blocks
+Logging
 --------
 
+```ruby
+
+# 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:
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+# :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
+--------
+
+```ruby
 Retryable.enabled?
 => true
 
@@ -145,10 +235,10 @@ 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`.
 
-```
+```ruby
 class MyError < StandardError; end
 
-Retryable.retryable(:tries => 5, :on => [StandardError], :not => [MyError]) do
+Retryable.retryable(tries: 5, on: [StandardError], not: [MyError]) do
   raise MyError "No retries!"
 end
 
@@ -159,9 +249,9 @@ Specify the sleep method to use
 This can be very useful when you are working with [Celluloid](https://github.com/celluloid/celluloid)
 which implements its own version of the method sleep.
 
-```
-Retryable.retryable(:sleep_method => Celluloid.method(:sleep)) do
-  retrieve_url
+```ruby
+Retryable.retryable(sleep_method: Celluloid.method(:sleep)) do
+  # code here
 end
 ```
 
@@ -171,12 +261,16 @@ Supported Ruby Versions
 This library aims to support and is [tested against][travis] the following Ruby
 versions:
 
-* Ruby 1.8.7
-* Ruby 1.9.2
 * Ruby 1.9.3
 * Ruby 2.0.0
-* Ruby 2.1.2
-* Ruby 2.2.0
+* Ruby 2.1.10
+* Ruby 2.2.10
+* Ruby 2.3.8
+* Ruby 2.4.5
+* Ruby 2.5.3
+* Ruby 2.6.1
+
+*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.
 
@@ -185,27 +279,3 @@ 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.
-
-
-Installation
--------
-
-Install the gem:
-
-``` bash
-$ gem install retryable
-```
-
-Add it to your Gemfile:
-
-``` ruby
-gem 'retryable'
-```
-
-## Thanks
-
-[Chu Yeow for this nifty piece of code](http://blog.codefront.net/2008/01/14/retrying-code-blocks-in-ruby-on-exceptions-whatever/)
-
-[Scott Bronson](https://github.com/bronson/retryable)
-
-[travis]: http://travis-ci.org/nfedyashev/retryable

data/Rakefile

@@ -4,8 +4,8 @@ Bundler::GemHelper.install_tasks
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-task :test => :spec
-task :default => :spec
+task test: :spec
+task default: :spec
 
 require 'yard'
 YARD::Rake::YardocTask.new

data/lib/retryable/configuration.rb

@@ -1,45 +1,42 @@
 module Retryable
   # Used to set up and modify settings for the retryable.
   class Configuration
-    OPTIONS = [
+    VALID_OPTION_KEYS = [
+      :contexts,
       :ensure,
       :exception_cb,
+      :log_method,
       :matching,
+      :not,
       :on,
       :sleep,
-      :tries,
-      :not,
-      :sleep_method
+      :sleep_method,
+      :tries
     ].freeze
 
-    attr_accessor :ensure
-    attr_accessor :exception_cb
-    attr_accessor :matching
-    attr_accessor :on
-    attr_accessor :sleep
-    attr_accessor :tries
-    attr_accessor :not
-    attr_accessor :sleep_method
+    attr_accessor(*VALID_OPTION_KEYS)
 
     attr_accessor :enabled
 
-    alias_method :enabled?, :enabled
-
     def initialize
-      @ensure       = Proc.new {}
-      @exception_cb = Proc.new {}
+      @contexts     = {}
+      @ensure       = proc {}
+      @exception_cb = proc {}
+      @log_method   = proc {}
       @matching     = /.*/
+      @not          = []
       @on           = StandardError
       @sleep        = 1
+      @sleep_method = ->(seconds) { Kernel.sleep(seconds) }
       @tries        = 2
-      @not          = []
-      @sleep_method = lambda do |seconds| Kernel.sleep(seconds) end
-      @enabled     = true
+
+      @enabled      = true
     end
 
     def enable
       @enabled = true
     end
+    alias enabled? enabled
 
     def disable
       @enabled = false
@@ -54,9 +51,8 @@ module Retryable
 
     # Returns a hash of all configurable options
     def to_hash
-      OPTIONS.inject({}) do |hash, option|
-        hash[option.to_sym] = self.send(option)
-        hash
+      VALID_OPTION_KEYS.each_with_object({}) do |key, memo|
+        memo[key] = instance_variable_get("@#{key}")
       end
     end
 

data/lib/retryable/version.rb

@@ -1,16 +1,40 @@
 module Retryable
-  class Version
-    MAJOR = 2 unless defined? Retryable::Version::MAJOR
-    MINOR = 0 unless defined? Retryable::Version::MINOR
-    PATCH = 4 unless defined? Retryable::Version::PATCH
+  # This module holds the Retryable version information.
+  module Version
+    module_function
 
-    class << self
+    # @return [Integer]
+    def major
+      3
+    end
+
+    # @return [Integer]
+    def minor
+      0
+    end
+
+    # @return [Integer]
+    def patch
+      5
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        major: major,
+        minor: minor,
+        patch: patch
+      }
+    end
 
-      # @return [String]
-      def to_s
-        [MAJOR, MINOR, PATCH].compact.join('.')
-      end
+    # @return [Hash]
+    def to_a
+      [major, minor, patch].compact
+    end
 
+    # @return [String]
+    def to_s
+      to_a.join('.')
     end
   end
 end

data/lib/retryable.rb

@@ -1,8 +1,12 @@
 require 'retryable/version'
 require 'retryable/configuration'
+require 'forwardable'
 
+# Runs a code block, and retries it when an exception occurs. It's great when working with flakey webservices (for example).
 module Retryable
   class << self
+    extend Forwardable
+
     # A Retryable configuration object. Must act like a hash and return sensible
     # values for all Retryable configuration options. See Retryable::Configuration.
     attr_writer :configuration
@@ -11,13 +15,16 @@ module Retryable
     #
     # @example
     #   Retryable.configure do |config|
-    #     config.ensure       = Proc.new {}
-    #     config.exception_cb = Proc.new {}
+    #     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 = ->(seconds) { Kernel.sleep(seconds) }
     #     config.tries        = 2
-    #     config.not          = []
     #   end
     def configure
       yield(configuration)
@@ -29,49 +36,48 @@ module Retryable
       @configuration ||= Configuration.new
     end
 
-    def enabled?
-      configuration.enabled?
-    end
+    delegate [:enabled?, :enable, :disable] => :configuration
 
-    def enable
-      configuration.enable
+    def with_context(context_key, options = {}, &block)
+      unless configuration.contexts.key?(context_key)
+        raise ArgumentError, "#{context_key} not found in Retryable.configuration.contexts. Available contexts: #{configuration.contexts.keys}"
+      end
+      retryable(configuration.contexts[context_key].merge(options), &block) if block
     end
 
-    def disable
-      configuration.disable
-    end
+    alias retryable_with_context with_context
 
-    def retryable(options = {}, &block)
-      opts = {
-        :tries        => self.configuration.tries,
-        :sleep        => self.configuration.sleep,
-        :on           => self.configuration.on,
-        :matching     => self.configuration.matching,
-        :ensure       => self.configuration.ensure,
-        :exception_cb => self.configuration.exception_cb,
-        :not          => self.configuration.not,
-        :sleep_method => self.configuration.sleep_method
-      }
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
+    def retryable(options = {})
+      opts = configuration.to_hash
 
       check_for_invalid_options(options, opts)
       opts.merge!(options)
 
+      # rubocop:disable Style/NumericPredicate
       return if opts[:tries] == 0
+      # rubocop:enable Style/NumericPredicate
 
-      on_exception = [ opts[:on] ].flatten
-      not_exception = [ opts[:not] ].flatten
+      on_exception = opts[:on].is_a?(Array) ? opts[:on] : [opts[:on]]
+      not_exception = opts[:not].is_a?(Array) ? opts[:not] : [opts[:not]]
+
+      matching = opts[:matching].is_a?(Array) ? opts[:matching] : [opts[:matching]]
       tries = opts[:tries]
       retries = 0
       retry_exception = nil
 
       begin
+        opts[:log_method].call(retries, retry_exception) if retries > 0
         return yield retries, retry_exception
       rescue *not_exception
         raise
       rescue *on_exception => exception
         raise unless configuration.enabled?
-        raise unless exception.message =~ opts[:matching]
-        raise if tries != :infinite && retries+1 >= tries
+        raise unless matches?(exception.message, matching)
+
+        infinite_retries = :infinite || tries.respond_to?(:infinite?) && tries.infinite?
+        raise if tries != infinite_retries && retries + 1 >= tries
 
         # Interrupt Exception could be raised while sleeping
         begin
@@ -90,13 +96,28 @@ module Retryable
         opts[:ensure].call(retries)
       end
     end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/PerceivedComplexity
 
     private
 
     def check_for_invalid_options(custom_options, default_options)
       invalid_options = default_options.merge(custom_options).keys - default_options.keys
+      return if invalid_options.empty?
+      raise ArgumentError, "[Retryable] Invalid options: #{invalid_options.join(', ')}"
+    end
 
-      raise ArgumentError.new("[Retryable] Invalid options: #{invalid_options.join(", ")}") unless invalid_options.empty?
+    def matches?(message, candidates)
+      candidates.any? do |candidate|
+        case candidate
+        when String
+          message.include?(candidate)
+        when Regexp
+          message =~ candidate
+        else
+          raise ArgumentError, ':matching must be a string or regex'
+        end
+      end
     end
   end
 end