retriable 3.1.1 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ba6b290804243a8b08f6f4542f1516ca38f52205
-  data.tar.gz: 618793b8cdb2566ff83fa037252a17874d490936
+SHA256:
+  metadata.gz: b43ddaf802607e93a68f1f2862c4a951b10f98ff3447f70da26ca72582f5c2ec
+  data.tar.gz: 6893753a86f08975dd6781ce504ef5e373c3ce06ccc56e1fabbb46a701893bfb
 SHA512:
-  metadata.gz: bb9a7cc6d5661743f636d8a2aa82d5cc12f03e41e2ffe93721af71081199f696d7cf6d4dcc830da3dc0cf3bd87b0fd9fd43f1f807b173fa4389f00358132cd48
-  data.tar.gz: 6434a4c6910b02caf3f1a8d822ceb543c511168052eb6bcd0e3c496d99931951143946456d212fb0f13193e88724ce7ff3d9cac9f242a8b5910fb8a7a2d225a8
+  metadata.gz: 67c9f7740db524df4f4b5301c9c66fbecfc70a98413d4e2dc830f19ecc8365d507373f481a678e53c4ca23063069319d2198bac4f89e6a9641b7c6e0487928f8
+  data.tar.gz: 76f62f0a03ac6e7c43c5fd6e6eeaaa3223edae83e55414bff6ec24464ab1991e6c405e569a7c17cfe0b3904bcec52867e69d9743440e14fb0a7d56ab7ff080fd

data/.hound.yml

@@ -0,0 +1,2 @@
+ruby:
+  config_file: .rubocop.yml

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -7,16 +7,13 @@ Style/Documentation:
 Style/TrailingCommaInArguments:
   EnforcedStyleForMultiline: comma
 
-Style/TrailingCommaInLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/InheritException:
+Lint/InheritException:
   Enabled: false
 
-Style/IndentArray:
+Layout/IndentArray:
   Enabled: false
 
-Style/IndentHash:
+Layout/IndentHash:
   Enabled: false
 
 Style/NegatedIf:
@@ -29,7 +26,7 @@ Metrics/ModuleLength:
   Enabled: false
 
 Metrics/LineLength:
-  Enabled: false
+  Max: 120
 
 Metrics/MethodLength:
   Enabled: false

data/.travis.yml

@@ -1,24 +1,25 @@
 # Send builds to container-based infrastructure
 # http://docs.travis-ci.com/user/workers/container-based-infrastructure/
+dist: trusty
 sudo: false
 language: ruby
 rvm:
   - 2.0.0
   - 2.1.10
-  - 2.2.7
-  - 2.3.4
-  - 2.4.1
-  - rbx
-  - jruby-9.0.5.0
-  - jruby-9.1.12.0
+  - 2.2.10
+  - 2.3.7
+  - 2.4.4
+  - 2.5.1
   - ruby-head
+  - jruby-9.2.0.0
   - jruby-head
+  - rbx-3.99
+script:
+  - bundle exec rspec
 
 matrix:
   allow_failures:
-    - rvm: rbx
-    - rvm: ruby-head
-    - rvm: jruby-head
+    - rvm: rbx-3.99
 
 before_install:
   - gem update --system

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## HEAD
 
+## 3.1.2
+
+* Replace `minitest` gem with `rspec`
+* Fancier README
+* Remove unnecessary short circuit in `randomize` method
+
 ## 3.1.1
 
 * Fix typo in contexts exception message.

data/Gemfile

@@ -1,12 +1,10 @@
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in retriable.gemspec
 gemspec
 
 group :test do
-  # gem "ruby_gntp"
   gem "codeclimate-test-reporter", require: false
-  gem "minitest-focus"
+  gem "rspec"
   gem "simplecov", require: false
 end
 

data/README.md

@@ -4,7 +4,7 @@
 [![Code Climate](https://codeclimate.com/github/kamui/retriable/badges/gpa.svg)](https://codeclimate.com/github/kamui/retriable)
 [![Test Coverage](https://codeclimate.com/github/kamui/retriable/badges/coverage.svg)](https://codeclimate.com/github/kamui/retriable)
 
-Retriable is a simple DSL to retry failed code blocks with randomized [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff) time intervals. This is especially useful when interacting external api/services or file system calls.
+Retriable is a simple DSL to retry failed code blocks with randomized [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff) time intervals. This is especially useful when interacting external APIs, remote services, or file system calls.
 
 ## Requirements
 
@@ -16,7 +16,7 @@ If you need ruby 1.8.x to 1.9.2 support, use the [1.x branch](https://github.com
 
 ## Installation
 
-via command line:
+Via command line:
 
 ```ruby
 gem install retriable
@@ -35,21 +35,7 @@ gem 'retriable', '~> 3.1'
 ```
 
 ## Usage
-
-Code in a `Retriable.retriable` block will be retried if an exception is raised. By default, Retriable will rescue any exception inherited from `StandardError`, make 3 tries (including the initial attempt) before raising the last exception, and also use randomized exponential backoff to calculate each succeeding try interval. The default interval table with 10 tries looks like this (in seconds):
-
-| retry#   | retry interval | randomized interval             |
-| -------- | -------------- | ------------------------------- |
-| 1        |    0.5         |  [0.25,   0.75]                 |
-| 2        |    0.75        |  [0.375,  1.125]                |
-| 3        |    1.125       |  [0.5625,  1.6875]              |
-| 4        |    1.6875      |  [0.84375, 2.53125]             |
-| 5        |    2.53125     |  [1.265625, 3.796875]           |
-| 6        |    3.796875    |  [1.8984375,  5.6953125]        |
-| 7        |    5.6953125   |  [2.84765625,  8.54296875]      |
-| 8        |   8.54296875   |  [4.271484375, 12.814453125]    |
-| 9        |  12.814453125  |  [6.4072265625, 19.2216796875]  |
-| 10       | 19.2216796875  |  stop                           |
+Code in a `Retriable.retriable` block will be retried if an exception is raised.
 
 ```ruby
 require 'retriable'
@@ -64,35 +50,57 @@ class Api
 end
 ```
 
-### Options
-
-Here are the available options:
+### Defaults
+By default, `Retriable` will:
+* rescue any exception inherited from `StandardError`
+* make 3 tries (including the initial attempt) before raising the last exception
+* use randomized exponential backoff to calculate each succeeding try interval.
 
-`tries` (default: 3) - Number of attempts to make at running your code block (includes intial attempt).
+The default interval table with 10 tries looks like this (in seconds, rounded to the nearest millisecond):
 
-`base_interval` (default: 0.5) - The initial interval in seconds between tries.
+| Retry #  | Min      | Average  | Max      |
+| -------- | -------- | -------- | -------- |
+| 1        | `0.25`   | `0.5`    | `0.75`   |
+| 2        | `0.375`  | `0.75`   | `1.125`  |
+| 3        | `0.563`  | `1.125`  | `1.688`  |
+| 4        | `0.844`  | `1.688`  | `2.531`  |
+| 5        | `1.266`  | `2.531`  | `3.797`  |
+| 6        | `1.898`  | `3.797`  | `5.695`  |
+| 7        | `2.848`  | `5.695`  | `8.543`  |
+| 8        | `4.271`  | `8.543`  | `12.814` |
+| 9        | `6.407`  | `12.814` | `19.222` |
+| 10       | **stop** | **stop** | **stop** |
 
-`max_interval` (default: 60) - The maximum interval in seconds that any try can reach.
 
-`rand_factor` (default: 0.25) - The percent range above and below the next interval is randomized between. The calculation is calculated like this:
-
-```
-randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])
-```
-
-`multiplier` (default: 1.5) - Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.
+### Options
 
-`max_elapsed_time`  (default: 900 (15 min)) - The maximum amount of total time that code is allowed to keep being retried.
+Here are the available options, in some vague order of relevance to most common use patterns:
 
-`intervals`  (default: nil) - Skip generated intervals and provide your own array of intervals in seconds. Setting this option will ignore `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` values.
+| Option | Default | Definition |
+| ------ | ------- | ---------- |
+| **`tries`** | `3` | Number of attempts to make at running your code block (includes initial attempt). |
+| **`on`** | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on). |
+| **`on_retry`** | `nil` | `Proc` to call after each try is rescued. [Read more](#callbacks). |
+| **`base_interval`** | `0.5` | The initial interval in seconds between tries. |
+| **`max_elapsed_time`** | `900` (15 min) | The maximum amount of total time in seconds that code is allowed to keep being retried. |
+| **`max_interval`** | `60` | The maximum interval in seconds that any individual retry can reach. |
+| **`multiplier`** | `1.5` | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval. |
+| **`timeout`** | `nil` | Number of seconds to allow the code block to run before raising a `Timeout::Error` inside each try. `nil` means the code block can run forever without raising error. (You may want to read up on [the dangers of using Ruby `Timeout`](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/) before using this feature.) |
+| **`rand_factor`** | `0.25` | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])` |
+| **`intervals`** | `nil` | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array). |
 
-`timeout` (default: nil) - Number of seconds to allow the code block to run before raising a `Timeout::Error` inside each try. Default is `nil` means the code block can run forever without raising error.
+#### Configuring Which Options to Retry With :on
+**`:on`** Can take the form:
 
-`on` (default: [StandardError]) - An `Array` of exceptions to rescue for each try, a `Hash` where the keys are `Exception` classes and the values can be a single `Regexp` pattern or a list of patterns, or a single `Exception` type. Subclasses of the listed exceptions will be retried and have their messages matched in the same way.
+- An `Exception` class (retry every exception of this type, including subclasses)
+- An `Array` of `Exception` classes (retry any exception of one of these types, including subclasses)
+- A `Hash` where the keys are `Exception` classes and the values are one of:
+  - `nil` (retry every exception of the key's type, including subclasses)
+  - A single `Regexp` pattern (retries exceptions ONLY if their `message` matches the pattern)
+  - An array of patterns (retries exceptions ONLY if their `message` matches at least one of the patterns)
 
-`on_retry` - (default: nil) - Proc to call after each try is rescued.
 
-### Config
+### Configuration
 
 You can change the global defaults with a `#configure` block:
 
@@ -103,12 +111,12 @@ Retriable.configure do |c|
 end
 ```
 
-### Examples
+### Example Usage
 
-`Retriable.retriable` accepts custom arguments. This example will only retry on a `Timeout::Error`, retry 3 times and sleep for a full second before each try.
+This example will only retry on a `Timeout::Error`, retry 3 times and sleep for a full second before each try.
 
 ```ruby
-Retriable.retriable on: Timeout::Error, tries: 3, base_interval: 1 do
+Retriable.retriable(on: Timeout::Error, tries: 3, base_interval: 1) do
   # code here...
 end
 ```
@@ -116,27 +124,27 @@ end
 You can also specify multiple errors to retry on by passing an array of exceptions.
 
 ```ruby
-Retriable.retriable on: [Timeout::Error, Errno::ECONNRESET] do
+Retriable.retriable(on: [Timeout::Error, Errno::ECONNRESET]) do
   # code here...
 end
 ```
 
-You can also specify a Hash of exceptions where the values are a list or single Regexp pattern.
+You can also use a hash to specify that you only want to retry exceptions with certain messages (see [the documentation above](#configuring-which-options-to-retry-with-on)).  This example will retry all `ActiveRecord::RecordNotUnique` exceptions, `ActiveRecord::RecordInvalid` exceptions where the message matches either `/Parent must exist/` or `/Username has already been taken/`, or `Mysql2::Error` exceptions where the message matches `/Duplicate entry/`.
 
 ```ruby
-Retriable.retriable on: {
+Retriable.retriable(on: {
   ActiveRecord::RecordNotUnique => nil,
-  ActiveRecord::RecordInvalid => [/Email has already been taken/, /Username has already been taken/],
+  ActiveRecord::RecordInvalid => [/Parent must exist/, /Username has already been taken/],
   Mysql2::Error => /Duplicate entry/
-} do
+}) do
   # code here...
 end
 ```
 
-You can also specify a timeout if you want the code block to only try for X amount of seconds. This timeout is per try.
+You can also specify a timeout if you want the code block to only try for X amount of seconds. This timeout is per try. (You may want to read up on [the dangers of using Ruby `Timeout`](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/) before using this feature.)
 
 ```ruby
-Retriable.retriable timeout: 60 do
+Retriable.retriable(timeout: 60) do
   # code here...
 end
 ```
@@ -144,7 +152,7 @@ end
 If you need millisecond units of time for the sleep or the timeout:
 
 ```ruby
-Retriable.retriable base_interval: (200/1000.0), timeout: (500/1000.0) do
+Retriable.retriable(base_interval: (200 / 1000.0), timeout: (500 / 1000.0)) do
   # code here...
 end
 ```
@@ -154,39 +162,39 @@ end
 You can also bypass the built-in interval generation and provide your own array of intervals. Supplying your own intervals overrides the `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` parameters.
 
 ```ruby
-Retriable.retriable intervals: [0.5, 1.0, 2.0, 2.5] do
+Retriable.retriable(intervals: [0.5, 1.0, 2.0, 2.5]) do
   # code here...
 end
 ```
 
-This example makes 5 total attempts, if the first attempt fails, the 2nd attempt occurs 0.5 seconds later.
+This example makes 5 total attempts. If the first attempt fails, the 2nd attempt occurs 0.5 seconds later.
 
 ### Turn off Exponential Backoff
 
-Exponential backoff is enabled by default, if you want to simply retry code every second, 5 times maximum, you can do this:
+Exponential backoff is enabled by default.  If you want to simply retry code every second, 5 times maximum, you can do this:
 
 ```ruby
-Retriable.retriable tries: 5, base_interval: 1.0, multiplier: 1.0, rand_factor: 0.0 do
+Retriable.retriable(tries: 5, base_interval: 1.0, multiplier: 1.0, rand_factor: 0.0) do
   # code here...
 end
 ```
 
-This works by starting at a 1 second interval (`base_interval`), setting the `multipler` to 1.0 means each subsequent try will increase 1x, which is still `1.0` seconds, and then a `rand_factor` of 0.0 means that there's no randomization of that interval. By default, it would randomize 0.25 seconds, which would mean normally the intervals would randomize between 0.75 and 1.25 seconds, but in this case `rand_factor` is basically being disabled.
+This works by starting at a 1 second `base_interval`.  Setting the `multipler` to 1.0 means each subsequent try will increase 1x, which is still `1.0` seconds, and then a `rand_factor` of 0.0 means that there's no randomization of that interval. (By default, it would randomize 0.25 seconds, which would mean normally the intervals would randomize between 0.75 and 1.25 seconds, but in this case `rand_factor` is basically being disabled.)
 
 Another way to accomplish this would be to create an array with a fixed interval. In this example, `Array.new(5, 1)` creates an array with 5 elements, all with the value 1. The code block will retry up to 5 times, and wait 1 second between each attempt.
 
 ```ruby
 # Array.new(5, 1) # => [1, 1, 1, 1, 1]
 
-Retriable.retriable intervals: Array.new(5, 1) do
+Retriable.retriable(intervals: Array.new(5, 1)) do
   # code here...
 end
 ```
 
-If you don't want exponential backoff, but you still want some randomization between intervals, this code will run every 1 seconds with a randomization factor of 0.2, which means each interval will be a random value between 0.8 and 1.2 (1 second +/- 0.2):
+If you don't want exponential backoff but you still want some randomization between intervals, this code will run every 1 seconds with a randomization factor of 0.2, which means each interval will be a random value between 0.8 and 1.2 (1 second +/- 0.2):
 
 ```ruby
-Retriable.retriable base_interval: 1.0, multiplier: 1.0, rand_factor: 0.2 do
+Retriable.retriable(base_interval: 1.0, multiplier: 1.0, rand_factor: 0.2) do
   # code here...
 end
 ```
@@ -200,14 +208,14 @@ do_this_on_each_retry = Proc.new do |exception, try, elapsed_time, next_interval
   log "#{exception.class}: '#{exception.message}' - #{try} tries in #{elapsed_time} seconds and #{next_interval} seconds until the next try."
 end
 
-Retriable.retriable on_retry: do_this_on_each_retry do
+Retriable.retriable(on_retry: do_this_on_each_retry) do
   # code here...
 end
 ```
 
 ### Ensure/Else
 
-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:
+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
@@ -262,7 +270,7 @@ You can even temporarily override individual options for a configured context:
 
 ```ruby
 Retriable.with_context(:mysql, tries: 30) do
-  # write_to_table
+  # write_to_table with :mysql context, except with 30 tries instead of 10
 end
 ```
 
@@ -295,6 +303,69 @@ retriable_with_context(:api) do
 end
 ```
 
+## Short Circuiting Retriable While Testing Your App
+
+When you are running tests for your app it often takes a long time to retry blocks that fail. This is because Retriable will default to 3 tries with exponential backoff. Ideally your tests will run as quickly as possible.
+
+You can disable retrying by setting `tries` to 1 in the test environment. If you want to test that the code is retrying an error, you want to [turn off exponential backoff](#turn-off-exponential-backoff).
+
+Under Rails, you could change your initializer to have different options in test, as follows:
+
+```ruby
+# config/initializers/retriable.rb
+Retriable.configure do |c|
+  # ... default configuration
+
+  if Rails.env.test?
+    c.tries = 1
+  end
+end
+```
+
+Alternately, if you are using RSpec, you could override the Retriable confguration in your `spec_helper`.
+
+```ruby
+# spec/spec_helper.rb
+Retriable.configure do |c|
+  c.tries = 1
+end
+```
+
+If you have defined contexts for your configuration, you'll need to change values for each context, because those values take precedence over the default configured value.
+
+For example assuming you have configured a `google_api` context:
+```ruby
+# config/initializers/retriable.rb
+Retriable.configure do |c|
+  c.contexts[:google_api] = {
+      tries:         5,
+      base_interval: 3,
+      on:            [
+          Net::ReadTimeout,
+          Signet::AuthorizationError,
+          Errno::ECONNRESET,
+          OpenSSL::SSL::SSLError
+      ]
+  }
+end
+```
+
+Then in your test environment, you would need to set each context and the default value:
+
+```ruby
+# spec/spec_helper.rb
+Retriable.configure do |c|
+  c.multiplier    = 1.0
+  c.rand_factor   = 0.0
+  c.base_interval = 0
+
+  c.contexts.keys.each do |context|
+    c.contexts[context][:tries]         = 1
+    c.contexts[context][:base_interval] = 0
+  end
+end
+```
+
 ## Proxy Wrapper Object
 
 [@julik](https://github.com/julik) has created a gem called [retriable_proxy](https://github.com/julik/retriable_proxy) that extends `retriable` with the ability to wrap objects and specify which methods you want to be retriable, like so:
@@ -307,3 +378,9 @@ RetriableProxy.for_object(api_endpoint, on: Net::TimeoutError)
 ## Credits
 
 The randomized exponential backoff implementation was inspired by the one used in Google's [google-http-java-client](https://code.google.com/p/google-http-java-client/wiki/ExponentialBackoff) project.
+
+## Development
+### Running Specs
+```bash
+bundle exec rspec
+```

data/lib/retriable.rb

@@ -37,6 +37,7 @@ module Retriable
     on_retry          = local_config.on_retry
     sleep_disabled    = local_config.sleep_disabled
 
+    exception_list = on.is_a?(Hash) ? on.keys : on
     start_time = Time.now
     elapsed_time = -> { Time.now - start_time }
 
@@ -52,10 +53,9 @@ module Retriable
       ).intervals
     end
 
-    exception_list = on.is_a?(Hash) ? on.keys : on
-
     tries.times do |index|
       try = index + 1
+
       begin
         return Timeout.timeout(timeout) { return yield(try) } if timeout
         return yield(try)