pester 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c726cd4ef970107604a3cabf1d26ddf04fffbc45
-  data.tar.gz: 3579a4065f03f7791720e9d98d0c6bdc5a3c57f7
+  metadata.gz: 2e359e529e96c33e2c045131b4105c957f4574f1
+  data.tar.gz: 7ecedc1fd852d0ed9ffd87f0e453140a86a586c2
 SHA512:
-  metadata.gz: 3e6af9161e42c15a613748d81845adfa8d786b4a5309b41163b87c5d42945968e984e66e84a95f9ba141b2a713c1c30f1a2d5c6b8b8648e516fc1cb0931b84d0
-  data.tar.gz: a5719117192311422b5bce432f1b53cef9d98f12ef3b4e1df6b244d237709353ce64af6152c015b75910226b010119abadd890cc23a5f15eeebf34c441b0f450
+  metadata.gz: 1ee4066ba850950f881d26f79ef5128161732db89f6403a7f0ee6125a92661b4824dce2e9033e80cfe3da4150559a166fefd70e99c1d634b6e41f29fd31487c8
+  data.tar.gz: b6633b146f951025076480d0f236bf50232e27faef95ff0080764435e3e34f972b188d9bb1016648512059e384c8194c7b0cd35abf100fd5a6778f9e6dffcc19

data/.travis.yml

@@ -0,0 +1,9 @@
+---
+language: ruby
+cache:
+  - bundler
+rvm:
+  - ruby-2.0.0-p353
+env:
+  TRAVIS: true
+script: "bundle exec rspec spec --color"

data/README.md

@@ -1,6 +1,106 @@
-# Pester
+# Pester - Coordinated retry logic
 
-TODO: Write a gem description
+[![Travis](https://travis-ci.org/lumoslabs/pester.svg?branch=master)](https://travis-ci.org/lumoslabs/pester)
+[![Code Climate](https://codeclimate.com/github/lumoslabs/pester/badges/gpa.svg)](https://codeclimate.com/github/lumoslabs/pester)
+
+In a lot of our backend code, we quite often found ourselves repeating some of the same patterns for retry logic. Relying on external services--including internal service endpoints and databases--means things fail intermittently. Many of these operations are idempotent and can be retried, but external services don't especially like being pestered without some pause, so you need to slow your roll.
+
+## Usage
+
+From the outset, the goal of Pester is to offer a simple interface. For example:
+
+    irb(main):001:0> require 'pester'
+    => true
+    irb(main):002:0> Pester.retry { fail 'derp' }
+    W, [2015-04-04T10:37:46.413158 #87600]  WARN -- : Failure encountered: derp, backing off and trying again 3 more times. etc etc
+
+will retry the block--which always fails--until Pester has exhausted its amount of retries. With no options provided, this will sleep for a constant number of seconds between attempts.
+
+Pester's basic retry behaviors are defined by three options:
+
+* `delay_interval`
+* `max_attempts`
+* `on_retry`
+
+`delay_interval` is the unit, in seconds, that will be delayed between attempts. Normally, this is just the total number of seconds, but it can change with other `Behavior`s. `max_attempts` is the number of tries Pester will make, including the initial one. If this is set to 1, Pester will basically not retry; less than 1, it will not even bother executing the block:
+
+    irb(main):001:0> Pester.retry(max_attempts: 0) { puts 'Trying...'; fail 'derp' }
+    => nil
+
+`on_retry` defines the behavior between retries, which can either be a custom block of code, or one of the predefined `Behavior`s, specifically in `Pester::Behaviors::Sleep`. If passed an empty lambda/block, Pester will immediately retry. When writing a custom behavior, `on_retry` expects a block that can be called with two parameters, `attempt_num`, and `delay_interval`, the idea being that these will mostly be used to define a function that determines just how long to sleep between attempts.
+
+Three behaviors are provided out-of-the box:
+
+* `Constant` is the default, and will simply sleep for `delay_interval` seconds
+* `Linear` simply multiplies `attempt_num` by `delay_interval` and sleeps for that many seconds
+* `Exponential` sleeps for 2<sup>(`attempt_num` - 1)</sup> * `delay_interval` seconds
+
+All three are available either by passing the behaviors to `on_retry`, or by calling the increasingly-verbosely-named `retry` (constant), `retry_with_backoff` (linear), or `retry_with_exponential_backoff` (exponential).
+
+Pester does log retry attempts (see below), however custom retry behavior that wraps existing `Behavior`s may be appropriate for logging custom information, incrementing statsd counters, etc. Also of note, different loggers can be passed per-call via the `logger` option.
+
+Finally, one last behavior is executed once the max number of retries has been exhausted, `on_max_attempts_exceeded`, which is also configurable per-call. By default, this will log an exhaustion message to `warn` and just reraise the called exception, preserving the original stacktrace.
+
+### Choosing what to retry
+
+Pester can be configured to be picky about what it chooses to retry and what it lets through. Three options control this behavior:
+
+* retry_error_classes
+* reraise_error_classes
+* retry_error_messages
+
+The first two are mutually-exclusive whitelist and blacklists, both taking either a single error class or an array. Raising an error not covered by `retry_error_classes` (whitelist) causes it to immediately fail:
+
+    irb(main):002:0> Pester.retry(retry_error_classes: NotImplementedError) do
+      puts 'Trying...'
+      fail 'derp'
+    end
+    Trying...
+    RuntimeError: derp
+
+Raising an error covered by `reraise_error_classes` (blacklist) causes it to immediately fail:
+
+    irb(main):002:0> Pester.retry(reraise_error_classes: NotImplementedError) do
+      puts 'Trying...'
+      raise NotImplementedError.new('derp')
+    end
+    Trying...
+    NotImplementedError: derp
+
+`retry_error_messages` also takes a single string or array, and calls `include?` on the error message. If it matches, the error's retried:
+
+    irb(main):002:0> Pester.retry(retry_error_messages: 'please') do
+      puts 'Trying...'
+      fail 'retry this, please'
+    end
+    Trying...
+    Trying...
+
+Because it calls `include?`, this also works for regexes:
+
+    irb(main):002:0> Pester.retry(retry_error_messages: /\d/) do
+      puts 'Trying...'
+      fail 'retry this 2'
+    end
+    Trying...
+    Trying...
+
+### Configuration
+
+Pester will write retry and exhaustion information into your logs, by default using a ruby `Logger` to standard out. This can be configured either per-call, or one time per application in your initializer via `Pester#configure`. The following will suppress all logs by using a class that simply does nothing with log data, as found in `spec/`:
+
+    Pester.configure do |c|
+      c.logger = NullLogger.new
+    end
+
+And thus:
+
+    irb(main):002:0> Pester.retry(delay_interval: 1) { puts 'Trying...'; fail 'derp' }
+    Trying...
+    Trying...
+    Trying...
+    Trying...
+    RuntimeError: derp
 
 ## Installation
 
@@ -18,10 +118,6 @@ Or install it yourself as:
 
     $ gem install pester
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/pester/fork )

data/lib/pester.rb

@@ -9,7 +9,7 @@ module Pester
   end
 
   def self.retry(options = {}, &block)
-    retry_action(options.merge(on_retry: ->(_, delay_interval) { sleep(delay_interval) }), &block)
+    retry_action(options.merge(on_retry: Behaviors::Sleep::Constant), &block)
   end
 
   def self.retry_with_backoff(options = {}, &block)
@@ -71,6 +71,8 @@ module Pester
         end
       end
     end
+
+    nil
   end
 
   private

data/lib/pester/behaviors/sleep.rb

@@ -1,6 +1,8 @@
 module Pester
   module Behaviors
     module Sleep
+      Constant = ->(_, delay_interval) { sleep(delay_interval) }
+
       Linear = ->(attempt_num, delay_interval) { sleep(attempt_num * delay_interval) }
 
       Exponential = ->(attempt_num, delay_interval) { sleep((2**attempt_num - 1) * delay_interval) }

data/lib/pester/version.rb

@@ -1,3 +1,3 @@
 module Pester
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/pester.gemspec

@@ -22,7 +22,7 @@ EOD
   spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.2'
 end

data/spec/pester_spec.rb

@@ -28,6 +28,17 @@ shared_examples 'returns and succeeds' do
   end
 end
 
+shared_examples 'has not run' do
+  it 'returns the intended result' do
+    expect(Pester.retry_action(options) { action }).to eq(nil)
+  end
+
+  it 'succeeds exactly once' do
+    Pester.retry_action(options) { action }
+    expect(failer.successes).to eq(0)
+  end
+end
+
 shared_examples 'raises an error only in the correct cases with a retry class' do
   context 'when neither the class is in the retry list, nor is the message matched' do
     let(:actual_error_class) { non_matching_error_class }
@@ -192,6 +203,59 @@ describe 'retry_action' do
       end
     end
   end
+
+  context 'when max_attempts is set' do
+    let(:intended_result) { 42 }
+    let(:options) { { delay_interval: 0, logger: null_logger, max_attempts: max_attempts } }
+
+    shared_examples "doesn't even run" do
+      let(:action) { failer.fail(StandardError, 'Dying') }
+
+      context 'for block does not fail' do
+        let(:failer) { ScriptedFailer.new(0, intended_result) }
+
+        it_has_behavior "doesn't raise an error"
+        it_has_behavior 'has not run'
+      end
+
+      context 'for block fails' do
+        let(:failer) { ScriptedFailer.new(1, intended_result) }
+
+        it_has_behavior "doesn't raise an error"
+        it_has_behavior 'has not run'
+      end
+    end
+
+    context 'to one' do
+      let(:max_attempts) { 1 }
+      let(:action) { failer.fail(StandardError, 'Dying') }
+
+      context 'for block does not fail' do
+        let(:failer) { ScriptedFailer.new(0, intended_result) }
+
+        it_has_behavior "doesn't raise an error"
+        it_has_behavior 'returns and succeeds'
+      end
+
+      context 'for block fails' do
+        let(:failer) { ScriptedFailer.new(1, intended_result) }
+
+        it_has_behavior 'raises an error'
+      end
+    end
+
+    context 'to zero' do
+      let(:max_attempts) { 0 }
+
+      it_has_behavior "doesn't even run"
+    end
+
+    context 'to less than zero' do
+      let(:max_attempts) { -1 }
+
+      it_has_behavior "doesn't even run"
+    end
+  end
 end
 
 describe 'logger' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pester
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Marc Bollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-01 00:00:00.000000000 Z
+date: 2015-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +65,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md