retriable 3.8.0 → 4.1.0

data/lib/retriable.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "timeout"
 require_relative "retriable/config"
 require_relative "retriable/exponential_backoff"
 require_relative "retriable/version"
@@ -41,7 +40,7 @@ module Retriable
     end
   end
 
-  def with_context(context_key, options = {}, &block)
+  def with_context(context_key, options = {}, &)
     contexts = available_contexts
 
     if !contexts.key?(context_key)
@@ -51,25 +50,25 @@ module Retriable
 
     return unless block_given?
 
-    retriable(context_options_for(context_key, options), &block)
+    retriable(context_options_for(context_key, options), &)
   end
 
-  def retriable(opts = {}, &block)
+  def retriable(opts = {}, &)
     override_config = current_override
     local_config = if opts.empty? && !override_config
                      config
                    else
-                     Config.new(apply_override_options(config.to_h.merge(opts), override_config))
+                     Config.new(apply_override_options(merge_layer(config.to_h, opts), override_config))
                    end
 
     # Config is mutable through `configure`, so validate again immediately before use.
     local_config.validate!
 
     plan = retry_plan(local_config)
-    timeout = local_config.timeout
     on = local_config.on
     retry_if = local_config.retry_if
     on_retry = local_config.on_retry
+    on_give_up = local_config.on_give_up
     sleep_disabled = local_config.sleep_disabled
     max_elapsed_time = local_config.max_elapsed_time
 
@@ -79,22 +78,22 @@ module Retriable
     elapsed_time = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time }
 
     execute_tries(
-      max_tries: plan.max_tries, interval_for: plan.interval_for, timeout: timeout,
+      max_tries: plan.max_tries, interval_for: plan.interval_for,
       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
+      on_give_up: on_give_up, elapsed_time: elapsed_time, max_elapsed_time: max_elapsed_time,
+      sleep_disabled: sleep_disabled, &
     )
   end
 
   def execute_tries( # rubocop:disable Metrics/ParameterLists
-    max_tries:, interval_for:, timeout:, exception_list:,
-    on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
+    max_tries:, interval_for:, exception_list:,
+    on:, retry_if:, on_retry:, on_give_up:, elapsed_time:, max_elapsed_time:, sleep_disabled:
   )
     try = 0
     loop do
       try += 1
       begin
-        return call_with_timeout(timeout, try, &block)
+        return yield(try)
       rescue *exception_list => e
         raise unless retriable_exception?(e, on, exception_list, retry_if)
 
@@ -102,7 +101,13 @@ module Retriable
         call_on_retry(on_retry, e, try, elapsed_time.call, interval)
 
         elapsed_interval = sleep_disabled == true ? 0 : interval
-        raise unless can_retry?(try, max_tries, elapsed_time.call, elapsed_interval, max_elapsed_time)
+        # Snapshot elapsed_time once so the stop check and on_give_up see the same value.
+        current_elapsed_time = elapsed_time.call
+        stop_reason = retry_stop_reason(try, max_tries, current_elapsed_time, elapsed_interval, max_elapsed_time)
+        if stop_reason
+          call_on_give_up(on_give_up, e, try, current_elapsed_time, interval, stop_reason)
+          raise
+        end
 
         sleep interval if sleep_disabled != true
       end
@@ -132,23 +137,30 @@ module Retriable
     ).interval_provider
   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, max_tries, elapsed_time, interval, max_elapsed_time)
-    return false if max_tries && try >= max_tries
-    return true if max_elapsed_time.nil?
+  def call_on_give_up( # rubocop:disable Metrics/ParameterLists
+    on_give_up, exception, try, elapsed_time, interval, reason
+  )
+    return unless on_give_up
 
-    (elapsed_time + interval) <= max_elapsed_time
+    on_give_up.call(exception, try, elapsed_time, interval, reason)
+  end
+
+  # `:tries_exhausted` is checked first, but the two conditions can't both hold
+  # on the same try in practice: `retry_plan` returns a nil interval whenever
+  # `try >= max_tries`, so `(elapsed_time + interval) > max_elapsed_time` is not
+  # evaluable on the exhausted-tries try. The early return guards against that
+  # nil and also pins precedence in case the plan ever changes.
+  def retry_stop_reason(try, max_tries, elapsed_time, interval, max_elapsed_time)
+    return :tries_exhausted if max_tries && try >= max_tries
+    return nil if max_elapsed_time.nil?
+
+    :max_elapsed_time if (elapsed_time + interval) > max_elapsed_time
   end
 
   # When `on` is a Hash, we need to verify the exception matches a pattern.
@@ -204,9 +216,17 @@ module Retriable
   def apply_override_options(options, overrides)
     return options unless overrides
 
-    options = options.merge(overrides)
-    options[:intervals] = nil if overrides.key?(:tries) && !overrides.key?(:intervals)
-    options
+    merge_layer(options, overrides)
+  end
+
+  # Merge a higher-precedence option layer onto a base layer. A higher layer
+  # that sets `tries` without `intervals` clears the base layer's inherited
+  # `intervals`, so a caller's `tries:` is never silently ignored. When the
+  # higher layer supplies its own `intervals`, those win (same-call override).
+  def merge_layer(base, higher)
+    merged = base.merge(higher)
+    merged[:intervals] = nil if higher.key?(:tries) && !higher.key?(:intervals)
+    merged
   end
 
   def available_contexts
@@ -216,7 +236,7 @@ module Retriable
   def context_options_for(context_key, options)
     context_options = config_contexts.fetch(context_key, {})
     context_options = {} unless context_options.is_a?(Hash)
-    context_options = context_options.merge(options)
+    context_options = merge_layer(context_options, options)
 
     override_context_options = override_contexts[context_key]
     return context_options unless override_context_options.is_a?(Hash)
@@ -244,12 +264,13 @@ module Retriable
     :execute_tries,
     :retry_plan,
     :interval_provider,
-    :call_with_timeout,
     :call_on_retry,
-    :can_retry?,
+    :call_on_give_up,
+    :retry_stop_reason,
     :retriable_exception?,
     :hash_exception_match?,
     :apply_override_options,
+    :merge_layer,
     :available_contexts,
     :context_options_for,
     :config_contexts,

data/retriable.gemspec

@@ -15,15 +15,10 @@ Gem::Specification.new do |spec|
                        "APIs/services or file system calls."
   spec.homepage      = "https://github.com/kamui/retriable"
   spec.license       = "MIT"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.3.0"
-
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rspec", "~> 3"
-
-  spec.add_development_dependency "listen", "~> 3.1"
+  spec.required_ruby_version = ">= 3.2"
 end

data/spec/config_spec.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "stringio"
-
 describe Retriable::Config do
   let(:default_config) { described_class.new }
 
@@ -34,10 +32,6 @@ describe Retriable::Config do
       expect(default_config.intervals).to be_nil
     end
 
-    it "timeout defaults to nil" do
-      expect(default_config.timeout).to be_nil
-    end
-
     it "on defaults to [StandardError]" do
       expect(default_config.on).to eq([StandardError])
     end
@@ -50,6 +44,10 @@ describe Retriable::Config do
       expect(default_config.on_retry).to be_nil
     end
 
+    it "on_give_up handler defaults to nil" do
+      expect(default_config.on_give_up).to be_nil
+    end
+
     it "contexts defaults to {}" do
       expect(default_config.contexts).to eq({})
     end
@@ -59,99 +57,12 @@ describe Retriable::Config do
     expect { described_class.new(does_not_exist: 123) }.to raise_error(ArgumentError, /not a valid option/)
   end
 
-  it "raises errors on invalid timing configuration" do
-    expect { described_class.new(rand_factor: 1.1) }.to raise_error(ArgumentError, /rand_factor/)
-    expect do
-      expect { described_class.new(timeout: -1) }.to raise_error(ArgumentError, /timeout/)
-    end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
+  it "rejects timeout as an unknown option" do
+    expect { described_class.new(timeout: 5) }.to raise_error(ArgumentError, /not a valid option/)
   end
 
-  context "timeout deprecation" do
-    it "warns when timeout is configured" do
-      expect do
-        described_class.new(timeout: 5)
-      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-    end
-
-    it "warns when timeout is set before validation" do
-      config = described_class.new
-      config.timeout = 5
-
-      expect do
-        config.validate!
-      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-    end
-
-    it "does not warn when timeout is nil" do
-      expect do
-        described_class.new(timeout: nil)
-      end.not_to output.to_stderr
-    end
-
-    it "does not warn when timeout is omitted" do
-      expect do
-        described_class.new
-      end.not_to output.to_stderr
-    end
-
-    it "warns at most once per process" do
-      original_stderr = $stderr
-      stderr = StringIO.new
-      begin
-        $stderr = stderr
-
-        described_class.new(timeout: 5)
-        described_class.new(timeout: 5)
-
-        config = described_class.new
-        config.timeout = 5
-        config.validate!
-      ensure
-        $stderr = original_stderr
-      end
-
-      expect(stderr.string.scan("timeout:` option is deprecated").size).to eq(1)
-    end
-
-    it "emits the warning under the :deprecated category when supported", if: WARN_CATEGORY_SUPPORTED do
-      captured = []
-      allow(Warning).to receive(:warn) do |message, category: nil|
-        captured << [message, category]
-      end
-
-      described_class.new(timeout: 5)
-
-      expect(captured.size).to eq(1)
-      message, category = captured.first
-      expect(message).to match(/timeout.*deprecated.*Retriable 4\.0/i)
-      expect(category).to eq(:deprecated)
-    end
-
-    it "is silenced by Warning[:deprecated] = false", if: WARN_CATEGORY_SUPPORTED do
-      original = Warning[:deprecated]
-      begin
-        Warning[:deprecated] = false
-        expect do
-          described_class.new(timeout: 5)
-        end.not_to output.to_stderr
-      ensure
-        Warning[:deprecated] = original
-      end
-    end
-
-    it "remains armed when silenced via Warning[:deprecated]", if: WARN_CATEGORY_SUPPORTED do
-      original = Warning[:deprecated]
-      begin
-        Warning[:deprecated] = false
-        described_class.new(timeout: 5)
-      ensure
-        Warning[:deprecated] = original
-      end
-
-      expect do
-        described_class.new(timeout: 5)
-      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-    end
+  it "raises errors on invalid timing configuration" do
+    expect { described_class.new(rand_factor: 1.1) }.to raise_error(ArgumentError, /rand_factor/)
   end
 
   it "raises errors when intervals is not an array" do
@@ -191,6 +102,15 @@ describe Retriable::Config do
       expect { described_class.new(on: [StandardError, RuntimeError]) }.not_to raise_error
     end
 
+    it "accepts a Set of Exception subclasses" do
+      expect { described_class.new(on: Set[StandardError, RuntimeError]) }.not_to raise_error
+    end
+
+    it "rejects a Set containing a non-Exception class" do
+      expect { described_class.new(on: Set[StandardError, Kernel]) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
     it "accepts a hash with nil pattern values" do
       expect { described_class.new(on: { StandardError => nil }) }.not_to raise_error
     end