retriable 3.1.2 → 3.4.1

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "retriable"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/retriable/config.rb

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
 require_relative "exponential_backoff"
 
 module Retriable
   class Config
-    ATTRIBUTES = ExponentialBackoff::ATTRIBUTES + [
-      :sleep_disabled,
-      :max_elapsed_time,
-      :intervals,
-      :timeout,
-      :on,
-      :on_retry,
-      :contexts,
-    ].freeze
+    ATTRIBUTES = (ExponentialBackoff::ATTRIBUTES + %i[
+      sleep_disabled
+      max_elapsed_time
+      intervals
+      timeout
+      on
+      retry_if
+      on_retry
+      contexts
+    ]).freeze
 
     attr_accessor(*ATTRIBUTES)
 
@@ -27,11 +30,13 @@ module Retriable
       @intervals        = nil
       @timeout          = nil
       @on               = [StandardError]
+      @retry_if         = nil
       @on_retry         = nil
       @contexts         = {}
 
       opts.each do |k, v|
         raise ArgumentError, "#{k} is not a valid option" if !ATTRIBUTES.include?(k)
+
         instance_variable_set(:"@#{k}", v)
       end
     end

data/lib/retriable/core_ext/kernel.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../../retriable"
 
 module Kernel

data/lib/retriable/exponential_backoff.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 module Retriable
   class ExponentialBackoff
-    ATTRIBUTES = [
-      :tries,
-      :base_interval,
-      :multiplier,
-      :max_interval,
-      :rand_factor,
+    ATTRIBUTES = %i[
+      tries
+      base_interval
+      multiplier
+      max_interval
+      rand_factor
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -19,13 +21,14 @@ module Retriable
 
       opts.each do |k, v|
         raise ArgumentError, "#{k} is not a valid option" if !ATTRIBUTES.include?(k)
+
         instance_variable_set(:"@#{k}", v)
       end
     end
 
     def intervals
       intervals = Array.new(tries) do |iteration|
-        [base_interval * multiplier**iteration, max_interval].min
+        [base_interval * (multiplier**iteration), max_interval].min
       end
 
       return intervals if rand_factor.zero?
@@ -36,7 +39,7 @@ module Retriable
     private
 
     def randomize(interval)
-      delta = rand_factor * interval * 1.0
+      delta = rand_factor * interval.to_f
       min = interval - delta
       max = interval + delta
       rand(min..max)

data/lib/retriable/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Retriable
-  VERSION = "3.1.2".freeze
+  VERSION = "3.4.1"
 end

data/lib/retriable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "timeout"
 require_relative "retriable/config"
 require_relative "retriable/exponential_backoff"
@@ -16,61 +18,123 @@ module Retriable
 
   def with_context(context_key, options = {}, &block)
     if !config.contexts.key?(context_key)
-      raise ArgumentError, "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
+      raise ArgumentError,
+            "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
     end
 
-    retriable(config.contexts[context_key].merge(options), &block) if block
+    return unless block_given?
+
+    retriable(config.contexts[context_key].merge(options), &block)
   end
 
-  def retriable(opts = {})
+  def retriable(opts = {}, &block)
     local_config = opts.empty? ? config : Config.new(config.to_h.merge(opts))
 
-    tries             = local_config.tries
-    base_interval     = local_config.base_interval
-    max_interval      = local_config.max_interval
-    rand_factor       = local_config.rand_factor
-    multiplier        = local_config.multiplier
-    max_elapsed_time  = local_config.max_elapsed_time
-    intervals         = local_config.intervals
-    timeout           = local_config.timeout
-    on                = local_config.on
-    on_retry          = local_config.on_retry
-    sleep_disabled    = local_config.sleep_disabled
+    tries = local_config.tries
+    intervals = build_intervals(local_config, tries)
+    timeout = local_config.timeout
+    on = local_config.on
+    retry_if = local_config.retry_if
+    on_retry = local_config.on_retry
+    sleep_disabled = local_config.sleep_disabled
+    max_elapsed_time = local_config.max_elapsed_time
 
     exception_list = on.is_a?(Hash) ? on.keys : on
-    start_time = Time.now
-    elapsed_time = -> { Time.now - start_time }
-
-    if intervals
-      tries = intervals.size + 1
-    else
-      intervals = ExponentialBackoff.new(
-        tries:          tries - 1,
-        base_interval:  base_interval,
-        multiplier:     multiplier,
-        max_interval:   max_interval,
-        rand_factor:    rand_factor
-      ).intervals
-    end
+    exception_list = [*exception_list]
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    elapsed_time = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time }
+
+    tries = intervals.size + 1
 
+    execute_tries(
+      tries: tries, intervals: intervals, timeout: timeout,
+      exception_list: exception_list, on: on, retry_if: retry_if, on_retry: on_retry,
+      elapsed_time: elapsed_time, max_elapsed_time: max_elapsed_time,
+      sleep_disabled: sleep_disabled, &block
+    )
+  end
+
+  def execute_tries( # rubocop:disable Metrics/ParameterLists
+    tries:, intervals:, timeout:, exception_list:,
+    on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
+  )
     tries.times do |index|
       try = index + 1
 
       begin
-        return Timeout.timeout(timeout) { return yield(try) } if timeout
-        return yield(try)
-      rescue *[*exception_list] => exception
-        if on.is_a?(Hash)
-          raise unless exception_list.any? do |e|
-            exception.is_a?(e) && ([*on[e]].empty? || [*on[e]].any? { |pattern| exception.message =~ pattern })
-          end
-        end
+        return call_with_timeout(timeout, try, &block)
+      rescue *exception_list => e
+        raise unless retriable_exception?(e, on, exception_list, retry_if)
 
         interval = intervals[index]
-        on_retry.call(exception, try, elapsed_time.call, interval) if on_retry
-        raise if try >= tries || (elapsed_time.call + interval) > max_elapsed_time
+        call_on_retry(on_retry, e, try, elapsed_time.call, interval)
+
+        raise unless can_retry?(try, tries, elapsed_time.call, interval, max_elapsed_time)
+
         sleep interval if sleep_disabled != true
       end
     end
   end
+
+  def build_intervals(local_config, tries)
+    return local_config.intervals if local_config.intervals
+
+    ExponentialBackoff.new(
+      tries: tries - 1,
+      base_interval: local_config.base_interval,
+      multiplier: local_config.multiplier,
+      max_interval: local_config.max_interval,
+      rand_factor: local_config.rand_factor,
+    ).intervals
+  end
+
+  def call_with_timeout(timeout, try)
+    return Timeout.timeout(timeout) { yield(try) } if timeout
+
+    yield(try)
+  end
+
+  def call_on_retry(on_retry, exception, try, elapsed_time, interval)
+    return unless on_retry
+
+    on_retry.call(exception, try, elapsed_time, interval)
+  end
+
+  def can_retry?(try, tries, elapsed_time, interval, max_elapsed_time)
+    return false unless try < tries
+    return true if max_elapsed_time.nil?
+
+    (elapsed_time + interval) <= max_elapsed_time
+  end
+
+  # When `on` is a Hash, we need to verify the exception matches a pattern.
+  # For any non-Hash `on` value (e.g., Array of classes, single Exception class,
+  # or Module), the `rescue *exception_list` clause already guarantees the
+  # exception is retriable with respect to `on`; `retry_if`, if provided, is an
+  # additional gate that can still cause this method to return false.
+  def retriable_exception?(exception, on, exception_list, retry_if)
+    return false if on.is_a?(Hash) && !hash_exception_match?(exception, on, exception_list)
+    return false if retry_if && !retry_if.call(exception)
+
+    true
+  end
+
+  def hash_exception_match?(exception, on, exception_list)
+    exception_list.any? do |error_class|
+      next false unless exception.is_a?(error_class)
+
+      patterns = [*on[error_class]]
+      patterns.empty? || patterns.any? { |pattern| exception.message =~ pattern }
+    end
+  end
+
+  private_class_method(
+    :execute_tries,
+    :build_intervals,
+    :call_with_timeout,
+    :call_on_retry,
+    :can_retry?,
+    :retriable_exception?,
+    :hash_exception_match?,
+  )
 end

data/retriable.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "retriable/version"
 
@@ -9,24 +10,20 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jack Chu"]
   spec.email         = ["jack@jackchu.com"]
   spec.summary       = "Retriable is a simple DSL to retry failed code blocks with randomized exponential backoff"
-  spec.description   = "Retriable is a simple DSL to retry failed code blocks with randomized exponential backoff. This is especially useful when interacting external api/services or file system calls."
-  spec.homepage      = "http://github.com/kamui/retriable"
+  spec.description   = "Retriable is a simple DSL to retry failed code blocks with randomized " \
+                       "exponential backoff. This is especially useful when interacting with external " \
+                       "APIs/services or file system calls."
+  spec.homepage      = "https://github.com/kamui/retriable"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.0.0"
+  spec.required_ruby_version = ">= 2.3.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rspec", "~> 3"
 
-  if RUBY_VERSION < "2.3"
-    spec.add_development_dependency "ruby_dep", "~> 1.3.1"
-    spec.add_development_dependency "listen", "~> 3.0.8"
-  else
-    spec.add_development_dependency "listen", "~> 3.1"
-  end
+  spec.add_development_dependency "listen", "~> 3.1"
 end

data/sig/retriable.rbs

@@ -0,0 +1,4 @@
+module Retriable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/spec/config_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 describe Retriable::Config do
   let(:default_config) { described_class.new }
 
@@ -38,6 +40,10 @@ describe Retriable::Config do
       expect(default_config.on).to eq([StandardError])
     end
 
+    it "retry_if defaults to nil" do
+      expect(default_config.retry_if).to be_nil
+    end
+
     it "on_retry handler defaults to nil" do
       expect(default_config.on_retry).to be_nil
     end

data/spec/exponential_backoff_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 describe Retriable::ExponentialBackoff do
   context "defaults" do
     let(:backoff_config) { described_class.new }

data/spec/retriable_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 describe Retriable do
   let(:time_table_handler) do
     ->(_exception, try, _elapsed_time, next_interval) { @next_interval_table[try] = next_interval }
@@ -94,6 +96,28 @@ describe Retriable do
       expect(@tries).to eq(10)
     end
 
+    it "does not call on_retry when explicitly set to false" do
+      callback_called = false
+      original_on_retry = described_class.config.on_retry
+
+      begin
+        described_class.configure do |c|
+          c.on_retry = proc { |_exception, _try, _elapsed_time, _next_interval| callback_called = true }
+        end
+
+        expect do
+          described_class.retriable(on_retry: false, tries: 3) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+
+        expect(@tries).to eq(3)
+        expect(callback_called).to be(false)
+      ensure
+        described_class.configure do |c|
+          c.on_retry = original_on_retry
+        end
+      end
+    end
+
     context "with rand_factor 0.0 and an on_retry handler" do
       let(:tries) { 6 }
       let(:no_rand_timetable) { { 1 => 0.5, 2 => 0.75, 3 => 1.125 } }
@@ -130,6 +154,34 @@ describe Retriable do
         expect(@next_interval_table).to eq(interval_hash)
         expect(@tries).to eq(intervals.size + 1)
       end
+
+      it "intervals option overrides tries, base_interval, max_interval, rand_factor, and multiplier" do
+        # Even though we specify tries: 10, base_interval: 1.0, max_interval: 100.0,
+        # rand_factor: 0.8, and multiplier: 2.0, the explicit intervals should take precedence
+        custom_intervals = [0.1, 0.2, 0.3]
+
+        expect do
+          described_class.retriable(
+            intervals: custom_intervals,
+            tries: 10,
+            base_interval: 1.0,
+            max_interval: 100.0,
+            rand_factor: 0.8,
+            multiplier: 2.0,
+            on_retry: time_table_handler,
+          ) do
+            increment_tries_with_exception
+          end
+        end.to raise_error(StandardError)
+
+        # Should have 4 tries (3 intervals + 1), not 10
+        expect(@tries).to eq(4)
+        # Should use the exact intervals provided, not generate them
+        expect(@next_interval_table[1]).to eq(0.1)
+        expect(@next_interval_table[2]).to eq(0.2)
+        expect(@next_interval_table[3]).to eq(0.3)
+        expect(@next_interval_table[4]).to be_nil
+      end
     end
 
     context "with an array :on parameter" do
@@ -207,6 +259,50 @@ describe Retriable do
       end
     end
 
+    context "with a :retry_if parameter" do
+      it "retries only when retry_if returns true" do
+        described_class.retriable(tries: 3, retry_if: ->(_exception) { @tries < 3 }) do
+          increment_tries
+          raise StandardError, "StandardError occurred" if @tries < 3
+        end
+
+        expect(@tries).to eq(3)
+      end
+
+      it "does not retry when retry_if returns false" do
+        expect do
+          described_class.retriable(tries: 3, retry_if: ->(_exception) { false }) do
+            increment_tries_with_exception
+          end
+        end.to raise_error(StandardError)
+
+        expect(@tries).to eq(1)
+      end
+
+      it "can retry based on the wrapped exception cause" do
+        root_cause_class = Class.new(StandardError)
+        wrapper_class = Class.new(StandardError)
+
+        described_class.retriable(
+          on: [wrapper_class],
+          tries: 3,
+          retry_if: ->(exception) { exception.cause.is_a?(root_cause_class) },
+        ) do
+          increment_tries
+
+          if @tries < 3
+            begin
+              raise root_cause_class, "root cause"
+            rescue root_cause_class
+              raise wrapper_class, "wrapped"
+            end
+          end
+        end
+
+        expect(@tries).to eq(3)
+      end
+    end
+
     it "runs for a max elapsed time of 2 seconds" do
       described_class.configure { |c| c.sleep_disabled = false }
 
@@ -219,12 +315,55 @@ describe Retriable do
       expect(@tries).to eq(2)
     end
 
+    it "retries up to tries limit when max_elapsed_time is nil" do
+      expect do
+        described_class.retriable(tries: 4, max_elapsed_time: nil) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(4)
+    end
+
+    it "uses monotonic clock for elapsed time tracking" do
+      # Stub Process.clock_gettime to return controlled values so we can
+      # verify elapsed_time passed to on_retry is derived from the monotonic clock.
+      clock_calls = 0
+      allow(Process).to receive(:clock_gettime).with(Process::CLOCK_MONOTONIC) do
+        value = clock_calls.to_f
+        clock_calls += 1
+        value
+      end
+
+      elapsed_times = []
+      on_retry = ->(_exception, _try, elapsed_time, _next_interval) { elapsed_times << elapsed_time }
+
+      expect do
+        described_class.retriable(tries: 3, on_retry: on_retry) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      # start_time (call 0) + at least one elapsed_time computation per retry
+      expect(clock_calls).to be >= 3
+      # elapsed_time values should be positive and non-decreasing
+      expect(elapsed_times).to all(be > 0)
+      expect(elapsed_times).to eq(elapsed_times.sort)
+    end
+
     it "raises ArgumentError on invalid options" do
       expect { described_class.retriable(does_not_exist: 123) { increment_tries } }.to raise_error(ArgumentError)
     end
   end
 
   context "#configure" do
+    it "exposes only the intended public API" do
+      public_api_methods = %i[
+        retriable
+        with_context
+        configure
+        config
+      ]
+
+      expect(described_class.singleton_methods(false)).to match_array(public_api_methods)
+    end
+
     it "raises NoMethodError on invalid configuration" do
       expect { described_class.configure { |c| c.does_not_exist = 123 } }.to raise_error(NoMethodError)
     end
@@ -245,6 +384,22 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
+    it "returns nil when called without a block" do
+      expect(described_class.with_context(:sql)).to be_nil
+      expect(@tries).to eq(0)
+    end
+
+    it "passes try count through to the context block" do
+      seen_tries = []
+
+      described_class.with_context(:api) do |try|
+        seen_tries << try
+        raise StandardError if try < 3
+      end
+
+      expect(seen_tries).to eq([1, 2, 3])
+    end
+
     it "respects the context options" do
       expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(api_tries)

data/spec/spec_helper.rb

@@ -1,15 +1,11 @@
-require "codeclimate-test-reporter"
-require "simplecov"
-
-CodeClimate::TestReporter.configure do |config|
-  config.logger.level = Logger::WARN
-end
+# frozen_string_literal: true
 
+require "simplecov"
 SimpleCov.start
 
 require "pry"
 require_relative "../lib/retriable"
-require_relative "support/exceptions.rb"
+require_relative "support/exceptions"
 
 RSpec.configure do |config|
   config.before(:each) do

data/spec/support/exceptions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class NonStandardError < Exception; end
 class SecondNonStandardError < NonStandardError; end
 class DifferentError < Exception; end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.4.1
 platform: ruby
 authors:
 - Jack Chu
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.1'
 description: Retriable is a simple DSL to retry failed code blocks with randomized
-  exponential backoff. This is especially useful when interacting external api/services
+  exponential backoff. This is especially useful when interacting with external APIs/services
   or file system calls.
 email:
 - jack@jackchu.com
@@ -61,31 +60,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
+- ".github/workflows/main.yml"
 - ".gitignore"
 - ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
 - README.md
+- Rakefile
+- bin/console
+- bin/setup
 - lib/retriable.rb
 - lib/retriable/config.rb
 - lib/retriable/core_ext/kernel.rb
 - lib/retriable/exponential_backoff.rb
 - lib/retriable/version.rb
 - retriable.gemspec
+- sig/retriable.rbs
 - spec/config_spec.rb
 - spec/exponential_backoff_spec.rb
 - spec/retriable_spec.rb
 - spec/spec_helper.rb
 - spec/support/exceptions.rb
-homepage: http://github.com/kamui/retriable
+homepage: https://github.com/kamui/retriable
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -93,16 +97,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Retriable is a simple DSL to retry failed code blocks with randomized exponential
   backoff