attempt_this 0.8.1 → 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 99adc9216b884599d6cdf76e1232bd76ac60f58f
+  data.tar.gz: f284433eefff3989b31ffefe6438264c19b7c6ee
+SHA512:
+  metadata.gz: 5b26edd0f899dd2d1f37ca0ea35a888b4a246e565b190a8e970cff6c85bc78ab81177c5f5f1687e8fcf7f776c58c5944a800e639d81e21a387aefd08f3cc7827
+  data.tar.gz: 8938c34e49c4ea02ed9123c655900e62914b72895a84d75d24bc656268340be9ca66e5ebf9430984870e050f1ad9178b05aca70aa12cf593d5a1a4972e121dd1

data/.gitignore

@@ -0,0 +1,3 @@
+.idea/*
+attempt_this-*.gem
+coverage/*

data/Gemfile

@@ -0,0 +1,7 @@
+source 'http://rubygems.org'
+
+gem 'rspec'
+
+group :test do
+	gem 'simplecov', require: false	
+end

data/Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.4)
+    multi_json (1.7.7)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+
+PLATFORMS
+  ruby
+  x86-mingw32
+
+DEPENDENCIES
+  rspec
+  simplecov

data/README.md

@@ -0,0 +1,84 @@
+attempt_this
+============
+
+Exception-based retry policy mix-in for Ruby project. Its purpose it to retry a code block given number of times if it throws an exception.
+```ruby
+
+attempt(3.times) do
+	# Do something
+end
+```
+This will retry the code block up to three times. If the last attempt will result in an exception, that exception will be thrown outside of the attempt block.
+If you don't like that behavior, you can specify a function to be called after all attempts have failed.
+```ruby
+is_failed = false
+attempt(3.times)
+.and_default_to(->{is_failed = true}) do
+	# Do something
+end
+```
+
+You may want to retry on specific exception types:
+```ruby
+attempt(3.times)
+.with_filter(RecoverableError1, RecoverableError2) do
+	# Do something
+end
+```
+
+You may chose how to reset the environment between failed attempts. This is useful for transactions:
+```ruby
+attempt(3.times)
+.with_reset(->{rollback}) do
+	start_transaction
+	# Do something
+	commit_transaction
+end
+```
+You can specify delay between failed attempts:
+
+```ruby
+
+# Wait for 5 seconds between failures.
+attempt(3.times)
+.with_delay(5) do
+	# Do something
+end
+
+# Random delay between 30 and 60 seconds.
+attempt(3.times)
+.with_delay([30..60]) do
+	# Do something
+end
+
+# Start with 10 seconds delay and double it after each failed attempt.
+attempt(5.times)
+.with_binary_backoff(10) do
+	# Do something
+end
+```
+
+Of course, you can combine multiple options together:
+```ruby
+attempt(3.times)
+.with_delay(30)
+.with_reset(->{rollback})
+.and_default_to(->{is_failed = true}) do
+    # Do something
+end
+```
+
+Finally, you can store various configurations as scenarios and use them by name. This is useful when you need different approaches for specific cases (handling HTTP failures, for example). But remember that you should register your scenarios before using them:
+
+```ruby
+# Run this code when the application starts
+AttemptThis.attempt(5.times).with_filter(*RECOVERABLE_HTTP_ERRORS).scenario(:http)
+
+
+# And run this from your method:
+attempt(:http) do
+	# Make an HTTP call
+end
+```
+
+Enjoy! And feel free to contribute; just make sure you haven't broken any tests by running 'rake' from project's root.

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/attempt_this.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+	s.name				= 'attempt_this'
+	s.version			= '0.9.0'
+	s.date				= '2013-05-05'
+	s.summary			= 'Retry policy mix-in'
+	s.description		= <<EOM
+Retry policy mix-in with configurable number of attempts, delays, exception filters, and fall back strategies.
+
+See project's home page for usage examples and more information.
+EOM
+	s.authors			= ['Aliaksei Baturytski']
+	s.email				= 'abaturytski@gmail.com'
+	s.files				= `git ls-files`.split($/)
+	s.homepage			= 'https://github.com/aliakb/attempt_this'
+end

data/lib/attempt_this/attempt_object.rb

@@ -5,6 +5,19 @@ module AttemptThis
 	# Retry policy implementation.
 	# This class is internal and is not supposed to be used outside of the module.
 	class AttemptObject
+		@@scenarios = {}					# All registered scenarios
+
+		# Resets all static data.
+		def self.reset
+			@@scenarios = {}
+		end
+
+		def self.get_object(id_or_enumerator)
+			impl = @@scenarios[id_or_enumerator]
+			impl ||= AttemptObject.new(id_or_enumerator)
+			impl
+		end
+
 		# Initializes object with enumerator.
 		def initialize(enumerator)
 			@enumerator = enumerator
@@ -20,6 +33,7 @@ module AttemptThis
 				@reset_method = ->{} unless @reset_method
 				@exception_filter = ExceptionTypeFilter.new([StandardError]) unless @exception_filter 
 
+				@enumerator.rewind
 				@enumerator.each do
 					@delay_policy.call unless first_time
 					last_exception = nil
@@ -108,5 +122,13 @@ module AttemptThis
 			@exception_filter = ExceptionTypeFilter.new(exceptions)
 			attempt(block)
 		end
+
+		# Creates a scenario with the given id.
+		def scenario(id)
+			raise(ArgumentError, 'Blank id!') if id.nil? || id.empty?
+			raise(ArgumentError, "There is already a scenario with id #{id}") if @@scenarios.has_key?(id)
+
+			@@scenarios[id] = self
+		end
 	end
 end

data/lib/attempt_this/attempt_this.rb

@@ -0,0 +1,18 @@
+require 'attempt_this/attempt_object.rb'
+
+module AttemptThis
+	extend self
+
+	# Attempts code block until it doesn't throw an exception or the end of enumerator has been reached.
+	def attempt(enumerator, &block)
+		raise(ArgumentError, 'Nil enumerator!') if enumerator.nil?
+
+		impl = AttemptObject::get_object(enumerator)
+		impl.attempt(block)
+	end
+
+	# Resets all static data (scenarios). This is intended to use by tests only (to reset scenarios)
+	def self.reset
+		AttemptObject.reset
+	end
+end

data/lib/attempt_this.rb

@@ -1,11 +1,2 @@
-require 'attempt_this/attempt_object.rb'
+require 'attempt_this/attempt_this'
 
-module AttemptThis
-	# Attempts code block until it doesn't throw an exception or the end of enumerator has been reached.
-	def attempt(enumerator, &block)
-		raise(ArgumentError, 'Nil enumerator!') if enumerator.nil?
-
-		impl = AttemptObject.new(enumerator)
-		impl.attempt(block)
-	end
-end

data/spec/attempt_spec.rb

@@ -0,0 +1,291 @@
+require 'spec_helper.rb'
+
+describe AttemptThis do
+	include AttemptThis
+
+	context 'attempt' do
+		it 'should reject nil enumerator' do
+			->{attempt(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should allow execution without a code block' do
+			->{attempt(3.times)}.should_not raise_error
+		end
+
+		it 'should execute code block' do
+			was_called = false
+			attempt(1.times) {was_called = true}
+			was_called.should be_true
+		end
+
+		it 'should execute the code block only once' do
+			call_count = 0
+			attempt(3.times) { call_count += 1 }
+			call_count.should eql(1)
+		end
+
+		it 'should not execute the code' do
+			call_count = 0
+			attempt(0.times) { call_count += 1 }
+
+			call_count.should eql(0)
+		end
+
+		it 'should re-throw the original exception' do
+			->{attempt(2.times){raise 'Test'}}.should raise_error('Test')
+		end
+
+		it 'should attempt 3 times' do
+			call_count = 0
+			->{attempt(3.times) { call_count += 1; raise 'Test'}}.should raise_error('Test')
+			call_count.should eql(3)
+		end
+
+		it 'should stop trying after a successful attempt' do
+			attempt_count = 0
+			attempt(3.times) do
+				attempt_count += 1
+				raise 'Test' if attempt_count < 2 
+			end
+
+			attempt_count.should eql(2)
+		end
+	end
+
+	context 'with_delay' do
+		it 'should reject nil delay' do
+			->{attempt(3.times).with_delay(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject negative delay' do
+			->{attempt(3.times).with_delay(-1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject non-number delay' do
+			->{attempt(3.times).with_delay('foo')}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept floating point delay' do
+			->{attempt(3.times).with_delay(1.5)}.should_not raise_error
+		end
+
+		it 'should accept zero delay' do
+			->{attempt(3.times).with_delay(0)}.should_not raise_error
+		end
+
+		it 'should accept calls without a code block' do
+			->{attempt(3.times).with_delay(3)}.should_not raise_error
+		end
+
+		it 'should call the code block' do
+			was_called = false
+			attempt(3.times).with_delay(1) do
+				was_called = true
+			end
+			was_called.should be_true
+		end
+
+		it 'should not sleep on success' do
+			Kernel.should_not_receive(:sleep)
+			attempt(3.times).with_delay(3) {}
+		end
+
+		it 'should sleep for given number of seconds between failed attempts' do
+			Kernel.should_receive(:sleep).with(5).exactly(2).times
+			->{attempt(3.times).with_delay(5) {raise 'Test'}}.should raise_error('Test')
+		end
+
+		it 'should not fail on zero delay' do
+			->{attempt(3.times).with_delay(0) { raise 'Test' }}.should raise_error('Test')
+		end
+
+		it 'should reject negative start' do
+			->{attempt(3.times).with_delay(-1..1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject negative end' do
+			->{attempt(3.times).with_delay(1..-1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject non-number range' do
+			->{attempt(3.times).with_delay('x'..'y')}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept floating point range' do
+			->{attempt(3.times).with_delay(1.5..3)}.should_not raise_error
+		end
+
+		it 'should reject inverse range' do
+			->{attempt(2.times).with_delay(3..1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept zero seconds interval' do
+			->{attempt(3.times).with_delay(0..0)}.should_not raise_error
+		end
+
+		it 'should wait for specified number of seconds' do
+			Kernel.should_receive(:sleep).with(5).exactly(2).times
+			->{attempt(3.times).with_delay(5..5){raise 'Test'}}.should raise_error('Test')
+		end
+
+		it 'should reject multiple delay policies' do
+			->{attempt(3.times).with_delay(1).with_delay(1)}.should raise_error(ArgumentError)
+		end
+	end
+
+	context 'with_reset' do
+		it 'should reject nil reset proc' do
+			->{attempt(3.times).with_reset(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept calls without a code block' do
+			->{attempt(3.times).with_reset(->{})}.should_not raise_error
+		end
+
+		it 'should call the code block' do
+			was_called = false
+			attempt(1.times).with_reset(->{}) { was_called = true }
+
+			was_called.should be_true
+		end
+
+		it 'should reject multiple reset procs' do
+			->{attempt(3.times).with_reset(->{}).with_reset(->{})}.should raise_error(ArgumentError)
+		end
+
+		it 'should not be called on successful calls' do
+			was_called = false
+
+			attempt(1.times).with_reset(->{ was_called = true }) {}
+			was_called.should be_false
+		end
+
+		it 'should be called on each failure' do
+			reset_count = 0
+
+			->{attempt(3.times).with_reset(->{ reset_count += 1 }) { raise 'Test' }}.should raise_error('Test')
+			reset_count.should eql(3)
+		end
+	end
+
+	context 'and_default_to' do
+		it 'should reject nil default method' do
+			->{attempt(3.times).and_default_to(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject duplicate default methods' do
+			->{attempt(3.times).and_default_to(->{}).and_default_to(->{})}.should raise_error(ArgumentError)
+		end
+
+		it 'should allow calls without a code block' do
+			->{attempt(3.times).and_default_to(->{})}.should_not raise_error
+		end
+
+		it 'should call the code block' do
+			was_called = false
+			attempt(3.times).and_default_to(->{}){ was_called = true }
+
+			was_called.should be_true
+		end
+
+		it 'should not be called on success' do
+			was_called = false
+			attempt(3.times).and_default_to(->{ was_called = true }) {}
+			was_called.should be_false
+		end
+
+		it 'should be called once on the failure' do
+			call_count = 0
+			attempt(3.times).and_default_to(->{ call_count += 1 }){ raise 'Test'}
+
+			call_count.should eql(1)
+		end
+
+		it 'should not be called if code block stopped failing' do
+			call_count = 0
+			was_called = false
+
+			attempt(3.times).and_default_to(->{ was_called = true }) { call_count += 1; raise 'Test' if call_count < 2 }
+			was_called.should be_false
+		end
+	end
+
+	context 'with_binary_backoff' do
+		it 'should reject nil initial delay' do
+			->{attempt(3.times).with_binary_backoff(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject non-integer initial delay' do
+			->{attempt(3.times).with_binary_backoff('foo')}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject zero initial delay' do
+			->{attempt(3.times).with_binary_backoff(0)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject negative initial delay' do
+			->{attempt(3.times).with_binary_backoff(-1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject multiple policies' do
+			->{attempt(3.times).with_binary_backoff(1).with_binary_backoff(2)}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept calls without a code block' do
+			->{attempt(3.times).with_binary_backoff(1)}.should_not raise_error
+		end
+
+		it 'should call the code block' do
+			was_called = false
+
+			attempt(3.times).with_binary_backoff(1) { was_called = true }
+			was_called.should be_true
+		end
+
+		it 'should double delay on each failure' do
+			Kernel.should_receive(:sleep).ordered.with(1)
+			Kernel.should_receive(:sleep).ordered.with(2)
+			Kernel.should_receive(:sleep).ordered.with(4)
+
+			attempt(4.times).with_binary_backoff(1).and_default_to(->{}) { raise 'Test' }
+		end
+	end
+
+	context 'with_filter' do
+		it 'should reject empty exceptions list' do
+			->{attempt.with_filter}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject non-exceptions' do
+			->{attempt.with_filter(1)}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept calls without a block' do
+			->{attempt(2.times).with_filter(Exception)}.should_not raise_error
+		end
+
+		it 'should call code within the block' do
+			was_called = false
+			attempt(2.times).with_filter(Exception){ was_called = true }
+			was_called.should be_true
+		end
+
+		it 'should ignore other exceptions' do
+			count = 0
+			->{attempt(3.times).with_filter(StandardError){ count += 1; raise(Exception, 'Test')}}.should raise_error(Exception)
+			count.should eql(1)
+		end
+
+		it 'should not ignore specified exceptions' do
+			count = 0
+			->{attempt(3.times).with_filter(RuntimeError){ count += 1; raise 'Test'}}.should raise_error(RuntimeError)
+			count.should eql(3)
+		end
+
+		it 'should not ignore derived exceptions' do
+			count = 0
+			->{attempt(3.times).with_filter(Exception){ count += 1; raise(StandardError, 'Test')}}.should raise_error(StandardError)
+			count.should eql(3)
+		end
+	end
+end

data/spec/scenarios_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe AttemptThis do
+	include AttemptThis
+
+	before(:each) do
+		AttemptThis.reset
+	end
+
+	context 'validation' do
+		it 'should reject nil scenario id' do
+			->{AttemptThis.attempt(3.times).scenario(nil)}.should raise_error(ArgumentError)
+		end
+
+		it 'should reject empty scenario id' do
+			->{AttemptThis.attempt(3.times).scenario('')}.should raise_error(ArgumentError)
+		end
+
+		it 'should accept string ids' do
+			->{AttemptThis.attempt(3.times).scenario('uploads')}.should_not raise_error
+		end
+
+		it 'should accept symbol ids' do
+			->{AttemptThis.attempt(3.times).scenario(:uploads)}.should_not raise_error
+		end
+
+		it 'should reject duplicate names' do
+			AttemptThis.attempt(3.times).scenario(:uploads)
+			->{AttemptThis.attempt(3.times).scenario(:uploads)}.should raise_error(ArgumentError)
+		end
+	end
+
+	context 'operation' do
+		it 'should attempt given number of times' do
+			AttemptThis.attempt(3.times).scenario(:test)
+			count = 0
+
+			->{attempt(:test) { count += 1; raise 'Test' }}.should raise_error('Test')
+			count.should eql(3)
+		end
+
+		it 'should reuse scenario' do
+			AttemptThis.attempt(3.times).scenario(:test)
+			->{attempt(:test) { raise 'Test'}}.should raise_error('Test')
+
+			count = 0
+			->{attempt(:test) {count += 1; raise 'Test'}}.should raise_error('Test')
+			count.should eql(3)
+		end
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'simplecov'
+SimpleCov.start
+
+require_relative '../lib/attempt_this.rb'

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attempt_this
 version: !ruby/object:Gem::Version
-  version: 0.8.1
-  prerelease: 
+  version: 0.9.0
 platform: ruby
 authors:
 - Aliaksei Baturytski
@@ -11,44 +10,50 @@ bindir: bin
 cert_chain: []
 date: 2013-05-05 00:00:00.000000000 Z
 dependencies: []
-description: ! 'Retry policy mix-in with configurable number of attempts, delays,
-  exception filters, and fall back strategies.
+description: |
+  Retry policy mix-in with configurable number of attempts, delays, exception filters, and fall back strategies.
 
-
-  See project''s home page for usage examples and more information.
-
-'
+  See project's home page for usage examples and more information.
 email: abaturytski@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- attempt_this.gemspec
 - lib/attempt_this.rb
 - lib/attempt_this/attempt_object.rb
+- lib/attempt_this/attempt_this.rb
 - lib/attempt_this/binary_backoff_policy.rb
 - lib/attempt_this/exception_type_filter.rb
+- spec/attempt_spec.rb
+- spec/scenarios_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/aliakb/attempt_this
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Retry policy mix-in
 test_files: []