stubbornly 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1205ff4f8568bb88aca04e7f902a002865684100594a40dd3b1b2ad34c3e2590
-  data.tar.gz: 48b4637aa7db561154399bb69c0f0b1b289700c606d3550a11f139daa4bedffb
+  metadata.gz: 61541dc62beb9db0f9aeefe99bf5dd84d1773efe2af2994a445f1b5f33a102b0
+  data.tar.gz: e69c526fd99e7ac41e1e5b813511d24d0bf67948ca0ffd5cc7c5ce0d1adf202f
 SHA512:
-  metadata.gz: 8c0522171461dccbaf95ad5286d78296201bc3a9bfbf8a06b9a22499a1c74eea32a81c424cca81feba69dd96f269099b36971f9f3d61e1b24bf8e45595d9a06c
-  data.tar.gz: 0ceedfba3af82388158b7d848650b226384d8337d553361a0e9759703c781e8d56601410dd436d993a3cd675a2b55be6fa072bcc5b9a3bfa5592cb3063c0382f
+  metadata.gz: ffeaf2ef474a9f22d0fff5d17dc9d03d1c08dc94862f9cf48b74181501bdace3f65d798ef03aec92d9e3732204b20fce3f72570c5bf9e5394169e7ad046568c3
+  data.tar.gz: e99e74cbe1ba5081f6db301e267ca7fc8b900fc3445782fbf7c0384c224684e06589a918b69e265f17bee9f21641f148ae4a0fb818a00e159b03c90d3ddf2338

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2018-07-01 13:37:09 +0200 using RuboCop version 0.57.2.
+# on 2018-07-01 19:37:52 +0200 using RuboCop version 0.57.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -8,18 +8,22 @@
 
 # Offense count: 1
 Metrics/AbcSize:
-  Max: 22
+  Max: 27
 
-# Offense count: 1
+# Offense count: 2
 Metrics/CyclomaticComplexity:
   Max: 7
 
 # Offense count: 2
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 24
+  Max: 27
 
 # Offense count: 1
 Security/Eval:
   Exclude:
-    - 'spec/unit/examples_spec.rb'
+    - 'spec/system/readme_spec.rb'
+
+Style/MutableConstant:
+  Exclude:
+    - 'lib/stubbornly/version.rb'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stubbornly (0.1.0)
+    stubbornly (0.2.0)
       null-logger
 
 GEM
@@ -101,6 +101,7 @@ GEM
       unf_ext
     unf_ext (0.0.7.5)
     unicode-display_width (1.4.0)
+    yard (0.9.14)
 
 PLATFORMS
   ruby
@@ -117,6 +118,7 @@ DEPENDENCIES
   rspec
   rubocop
   stubbornly!
+  yard
 
 BUNDLED WITH
    1.16.2

data/Guardfile

@@ -17,5 +17,7 @@ guard :rspec, cmd: 'bundle exec rspec' do
   watch(rspec.spec_helper) { rspec.spec_dir }
   watch(rspec.spec_files)
   watch(%r{^lib/.*/(.+)\.rb$}) { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch('README.markdown') { 'spec/system/examples_spec.rb' }
+  watch(%r{^examples/(.+)}) { |m| "spec/system/examples/#{m[1]}_spec.rb" }
   dsl.watch_spec_files_for(dsl.ruby.lib_files)
 end

data/README.markdown

@@ -2,20 +2,20 @@
 
 [![Build Status](https://travis-ci.org/suhlig/stubbornly.svg?branch=master)](https://travis-ci.org/suhlig/stubbornly)
 
-Stubbornly retries a given block until the maximum number of attempts or timeout has been reached.
+Stubbornly retries a given block until the maximum number of attempts or a timeout has been reached.
 
-## Example
+## Examples
+
+### Timeout
 
 ```ruby
 require 'stubbornly'
 require 'http'
-require 'logger'
 
 class Checker
   def initialize(url)
     @url = url
-    @logger = Logger.new(STDOUT)
-    @stubbornly = Stubbornly.new(logger: @logger)
+    @stubbornly = Stubbornly.new
   end
 
   def up?
@@ -25,10 +25,37 @@ class Checker
   end
 end
 
-if Checker.new('http://localhost:8765').up?
-  puts "Website is up"
-else
-  warn "We are DOWN!"
+begin
+  Checker.new('http://localhost:8765').up?
+rescue => e
+  warn "Error: #{e.message}"
+end
+```
+
+### Maximum number of attempts
+
+```ruby
+require 'stubbornly'
+require 'http'
+
+class Checker
+  def initialize(url)
+    @url = url
+    @stubbornly = Stubbornly.new
+  end
+
+  def up?
+    @stubbornly.retry(attempts: 3) do
+      response = HTTP.get(@url)
+      puts "The site at #{@url} is up 👍"
+    end
+  end
+end
+
+begin
+  Checker.new('http://localhost:8765').up?
+rescue => e
+  warn "Error: #{e.message}"
 end
 ```
 

data/Rakefile

@@ -8,4 +8,8 @@ RSpec::Core::RakeTask.new(:spec)
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
+require 'yard'
+require 'yard/rake/yardoc_task'
+YARD::Rake::YardocTask.new
+
 task default: %i[rubocop spec]

data/examples/http_status

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'stubbornly'
+require 'http'
+require 'logger'
+
+#
+# Checks a URL
+#
+class Checker
+  def initialize(url)
+    @url = url
+    @logger = Logger.new(STDERR, progname: self.class)
+    @stubbornly = Stubbornly.new(logger: Logger.new(STDERR, progname: Stubbornly))
+  end
+
+  #
+  # Return the status code of the given URL.
+  # Retry if failed, but
+  # - not more often than specified
+  # - only within the given timeout.
+  #
+  def status
+    @logger.info "Checking status of #{@url}"
+    @stubbornly.retry(timeout: 10, attempts: 4) do
+      HTTP.get(@url).code.tap do |result|
+        @logger.info "Result is #{result}"
+      end
+    end
+  end
+end
+
+url = ARGV.shift || 'http://example.com'
+
+begin
+  puts Checker.new(url).status
+rescue StandardError => e
+  warn "Error: #{e.message}"
+  exit 1
+end

data/lib/stubbornly.rb

@@ -4,37 +4,70 @@ require 'null_logger'
 require 'English'
 
 class Stubbornly
-  def initialize(logger: NullLogger.new)
+  #
+  # Constructs a new `Stubbornly` instance.
+  #
+  # If a block is passed, it will be called to calculate the sleep time (in
+  # seconds) before the next attempt is made. The attempt counter is passed
+  # as a block argument.
+  #
+  # This is useful to determine the backoff characteristics. The result of the
+  # block will be the sleep time in seconds. For instance, the following code
+  # would implement an exponential backoff with retries after 1, 3, 7, 15,
+  # 31, ... seconds:
+  #
+  #   Stubbornly.new {|attempt| 2**attempt - 1 }
+  #
+  # The default backoff is 1 (constant), i.e. the attempts are equidistant at 1s.
+  #
+  def initialize(logger: NullLogger.new, &block)
     @logger = logger
+    @backoff = block || proc { 1 }
   end
 
-  def retry(timeout: Float::INFINITY, attempts: Float::MAX)
-    @logger.debug("Starting first of not more than #{attempts} attempts") if attempts < Float::MAX
+  #
+  # Calls the given block, rescuing its errors, and retries until either the
+  # given timeout or the maximum number of attempts was exceeded.
+  #
+  # When an attempt raises an error, this method will sleep before it retries.
+  # The number of seconds to sleep is determined by the block passed to {#initialize}.
+  #
+  # If the block succeeds, its value is returned.
+  #
+  def retry(timeout: Float::INFINITY, attempts: Float::INFINITY, &block)
+    @logger.debug("Attempting not more than #{attempts} times") unless attempts.infinite?
     @logger.debug("Will time out after #{timeout}s") unless timeout.infinite?
 
-    attempt = 0
+    attempt = 1
     start = Time.now
 
     begin
-      @logger.info "Attempt ##{attempt}"
-      yield.tap do
-        @logger.info "Success after #{elapsed_since(start)}s and #{attempt} attempts"
+      @logger.info "Attempt ##{attempt} #{after_elapsed_since(start)}"
+
+      if block
+        yield(attempt, elapsed_since(start)).tap do
+          @logger.info "Success #{after_elapsed_since(start)} and #{attempt} attempts"
+        end
       end
-    rescue StandardError
-      attempt += 1
-      retry_after = 2**attempt - 1
-      @logger.warn "#{$ERROR_INFO.message}. Trying again in #{retry_after}s."
+    rescue StandardError => error
+      @logger.warn error.message
 
       if attempt >= attempts
-        @logger.error "Maximum number of attempts (#{attempt}) reached"
-        return false
+        @logger.error "Maximum number of attempts (#{attempts}) reached (#{after_elapsed_since(start)})"
+        raise
       end
 
+      # TODO: Give up NOW if retry_after would exceed timeout
+
       if elapsed_since(start) >= timeout
-        @logger.info "Timed out after #{elapsed_since(start)}s"
-        return false
+        @logger.info "Timed out #{after_elapsed_since(start)} (#{attempt} attempts)"
+        raise
       end
 
+      attempt += 1
+      retry_after = @backoff.call(attempt)
+
+      @logger.warn "Trying again in #{retry_after}s."
       sleep(retry_after)
       retry
     end
@@ -45,4 +78,8 @@ class Stubbornly
   def elapsed_since(start)
     Time.now - start
   end
+
+  def after_elapsed_since(start)
+    "after #{elapsed_since(start).round(2)}s"
+  end
 end

data/lib/stubbornly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Stubbornly
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'
 end

data/stubbornly.gemspec

@@ -28,10 +28,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'guard'
   spec.add_development_dependency 'guard-bundler'
   spec.add_development_dependency 'guard-rspec'
-  spec.add_development_dependency 'http'
+  spec.add_development_dependency 'http' # examples
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'yard'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stubbornly
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Steffen Uhlig
@@ -164,6 +164,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: Stubbornly retries a given block until the maximum number of attempts
   or timeout has been reached.
 email:
@@ -183,6 +197,7 @@ files:
 - LICENSE.txt
 - README.markdown
 - Rakefile
+- examples/http_status
 - lib/stubbornly.rb
 - lib/stubbornly/version.rb
 - stubbornly.gemspec