retriable 3.4.1 → 4.1.1

data/lib/retriable.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
-require "timeout"
 require_relative "retriable/config"
 require_relative "retriable/exponential_backoff"
 require_relative "retriable/version"
 
 module Retriable
+  # Thread-local storage key for the active #with_override block.
+  # We deliberately use Thread#thread_variable_set/get (true thread-local)
+  # rather than Thread.current[] (fiber-local) so that fibers within a thread
+  # share the same override. Changing this to Thread.current[] would silently
+  # break callers that use fiber-based concurrency.
+  OVERRIDE_THREAD_KEY = :retriable_override
+
+  RetryPlan = Struct.new(:max_tries, :interval_for)
+  private_constant :RetryPlan
+
   module_function
 
   def configure
@@ -16,26 +25,50 @@ module Retriable
     @config ||= Config.new
   end
 
-  def with_context(context_key, options = {}, &block)
-    if !config.contexts.key?(context_key)
+  def with_override(opts = {})
+    raise ArgumentError, "empty override options are not allowed" if opts.empty?
+    raise ArgumentError, "with_override requires a block" unless block_given?
+
+    validate_override_options(opts)
+
+    previous = Thread.current.thread_variable_get(OVERRIDE_THREAD_KEY)
+    Thread.current.thread_variable_set(OVERRIDE_THREAD_KEY, opts)
+    begin
+      yield
+    ensure
+      Thread.current.thread_variable_set(OVERRIDE_THREAD_KEY, previous)
+    end
+  end
+
+  def with_context(context_key, options = {}, &)
+    contexts = available_contexts
+
+    if !contexts.key?(context_key)
       raise ArgumentError,
-            "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
+            "#{context_key} not found in Retriable contexts (including overrides). Available contexts: #{contexts.keys}"
     end
 
     return unless block_given?
 
-    retriable(config.contexts[context_key].merge(options), &block)
+    retriable(context_options_for(context_key, options), &)
   end
 
-  def retriable(opts = {}, &block)
-    local_config = opts.empty? ? config : Config.new(config.to_h.merge(opts))
+  def retriable(opts = {}, &)
+    override_config = current_override
+    local_config = if opts.empty? && !override_config
+                     config
+                   else
+                     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!
 
-    tries = local_config.tries
-    intervals = build_intervals(local_config, tries)
-    timeout = local_config.timeout
+    plan = retry_plan(local_config)
     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
 
@@ -44,54 +77,64 @@ module Retriable
     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,
+      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
-    tries:, intervals:, 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:
   )
-    tries.times do |index|
-      try = index + 1
-
+    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)
 
-        interval = intervals[index]
+        interval = interval_for.call(try - 1)
         call_on_retry(on_retry, e, try, elapsed_time.call, interval)
 
-        raise unless can_retry?(try, tries, elapsed_time.call, interval, max_elapsed_time)
+        elapsed_interval = sleep_disabled == true ? 0 : interval
+        # 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
     end
   end
 
-  def build_intervals(local_config, tries)
-    return local_config.intervals if local_config.intervals
+  def retry_plan(local_config)
+    return RetryPlan.new(nil, interval_provider(local_config)) if Validation.unbounded_tries?(local_config.tries)
+
+    if local_config.intervals
+      intervals = local_config.intervals
+      return RetryPlan.new(intervals.size + 1, ->(index) { intervals[index] })
+    end
+
+    max_tries = local_config.tries
+    provider = interval_provider(local_config)
 
+    RetryPlan.new(max_tries, ->(index) { index < max_tries - 1 ? provider.call(index) : nil })
+  end
+
+  def interval_provider(local_config)
     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)
+    ).interval_provider
   end
 
   def call_on_retry(on_retry, exception, try, elapsed_time, interval)
@@ -100,11 +143,24 @@ module Retriable
     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?
+  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.
@@ -128,13 +184,97 @@ module Retriable
     end
   end
 
+  def validate_override_options(opts)
+    opts.each_key do |k|
+      raise ArgumentError, "#{k} is not a valid option" unless Config::ATTRIBUTES.include?(k)
+    end
+
+    return unless opts.key?(:contexts)
+
+    contexts = opts[:contexts]
+    return if contexts.nil?
+
+    raise ArgumentError, "contexts must be a Hash or nil, got #{contexts.inspect}" unless contexts.is_a?(Hash)
+
+    contexts.each do |context_key, context_options|
+      validate_context_override_options(context_key, context_options)
+    end
+  end
+
+  def validate_context_override_options(context_key, context_options)
+    unless context_options.is_a?(Hash)
+      raise ArgumentError,
+            "contexts[#{context_key.inspect}] must be a Hash, got #{context_options.inspect}"
+    end
+
+    context_attributes = Config::ATTRIBUTES - [:contexts]
+    context_options.each_key do |k|
+      raise ArgumentError, "#{k} is not a valid option" unless context_attributes.include?(k)
+    end
+  end
+
+  def apply_override_options(options, overrides)
+    return options unless overrides
+
+    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
+    config_contexts.merge(override_contexts)
+  end
+
+  def context_options_for(context_key, options)
+    context_options = config_contexts.fetch(context_key, {})
+    context_options = {} unless context_options.is_a?(Hash)
+    context_options = merge_layer(context_options, options)
+
+    override_context_options = override_contexts[context_key]
+    return context_options unless override_context_options.is_a?(Hash)
+
+    apply_override_options(context_options, override_context_options)
+  end
+
+  def config_contexts
+    config.contexts.is_a?(Hash) ? config.contexts : {}
+  end
+
+  def override_contexts
+    override_config = current_override
+    contexts = override_config && override_config[:contexts]
+    contexts.is_a?(Hash) ? contexts : {}
+  end
+
+  def current_override
+    Thread.current.thread_variable_get(OVERRIDE_THREAD_KEY)
+  end
+
   private_class_method(
+    :validate_override_options,
+    :validate_context_override_options,
     :execute_tries,
-    :build_intervals,
-    :call_with_timeout,
+    :retry_plan,
+    :interval_provider,
     :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,
+    :override_contexts,
+    :current_override,
   )
 end

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/sig/retriable.rbs

@@ -1,4 +1,32 @@
 module Retriable
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  OVERRIDE_THREAD_KEY: Symbol
+
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
+  def self.with_override: (Hash[Symbol, untyped] options) { () -> untyped } -> untyped
+  def self.with_context: (Symbol context_key, ?Hash[Symbol, untyped] options) ?{ (Integer) -> untyped } -> untyped
+  def self.retriable: (?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
+
+  class Config
+    ATTRIBUTES: Array[Symbol]
+
+    attr_accessor tries: Numeric
+    attr_accessor base_interval: Numeric
+    attr_accessor max_interval: Numeric
+    attr_accessor rand_factor: Numeric
+    attr_accessor multiplier: Numeric
+    attr_accessor sleep_disabled: bool
+    attr_accessor max_elapsed_time: Numeric?
+    attr_accessor intervals: Array[Numeric]?
+    attr_accessor on: untyped
+    attr_accessor retry_if: untyped
+    attr_accessor on_retry: untyped
+    attr_accessor on_give_up: untyped
+    attr_accessor contexts: Hash[Symbol, untyped]
+
+    def initialize: (?Hash[Symbol, untyped] opts) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def validate!: () -> void
+  end
 end

data/spec/config_spec.rb

@@ -32,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
@@ -48,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
@@ -56,4 +56,128 @@ describe Retriable::Config do
   it "raises errors on invalid configuration" do
     expect { described_class.new(does_not_exist: 123) }.to raise_error(ArgumentError, /not a valid option/)
   end
+
+  it "rejects timeout as an unknown option" do
+    expect { described_class.new(timeout: 5) }.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/)
+  end
+
+  it "raises errors when intervals is not an array" do
+    expect { described_class.new(intervals: "1") }.to raise_error(ArgumentError, /intervals must be an Array/)
+  end
+
+  it "requires a finite max_elapsed_time when tries is Float::INFINITY" do
+    expect { described_class.new(tries: Float::INFINITY, max_elapsed_time: nil) }
+      .to raise_error(ArgumentError, /max_elapsed_time must be a finite number/)
+  end
+
+  it "rejects intervals combined with tries: Float::INFINITY" do
+    expect do
+      described_class.new(
+        tries: Float::INFINITY,
+        max_elapsed_time: 60,
+        intervals: [0.1, 0.2],
+      )
+    end.to raise_error(ArgumentError, /intervals cannot be used with tries: Float::INFINITY/)
+  end
+
+  it "accepts tries: Float::INFINITY with a finite max_elapsed_time" do
+    expect { described_class.new(tries: Float::INFINITY, max_elapsed_time: 60) }
+      .not_to raise_error
+  end
+
+  context "on: option validation" do
+    it "accepts a single Exception subclass" do
+      expect { described_class.new(on: StandardError) }.not_to raise_error
+    end
+
+    it "accepts Exception itself" do
+      expect { described_class.new(on: Exception) }.not_to raise_error
+    end
+
+    it "accepts an array of Exception subclasses" 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
+
+    it "accepts a hash with Regexp pattern values" do
+      expect { described_class.new(on: { StandardError => /boom/ }) }.not_to raise_error
+    end
+
+    it "accepts a hash with Array-of-Regexp pattern values" do
+      expect { described_class.new(on: { StandardError => [/a/, /b/] }) }.not_to raise_error
+    end
+
+    it "rejects Object as on:" do
+      expect { described_class.new(on: Object) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects Kernel as on:" do
+      expect { described_class.new(on: Kernel) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects an array containing a non-Exception class" do
+      expect { described_class.new(on: [StandardError, Kernel]) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects a hash key that is not an Exception class" do
+      expect { described_class.new(on: { Kernel => nil }) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects a hash value that is a String" do
+      expect { described_class.new(on: { StandardError => "boom" }) }
+        .to raise_error(ArgumentError, /on\[StandardError\] must be nil, a Regexp, or an Array of Regexps/)
+    end
+
+    it "rejects a hash value that is an Array containing a non-Regexp" do
+      expect { described_class.new(on: { StandardError => [/a/, "b"] }) }
+        .to raise_error(ArgumentError, /on\[StandardError\] must be nil, a Regexp, or an Array of Regexps/)
+    end
+
+    it "rejects a string passed as on:" do
+      expect { described_class.new(on: "StandardError") }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "validates on: even when intervals is provided" do
+      expect { described_class.new(intervals: [0.1], on: Object) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+  end
+
+  context "callable option validation" do
+    %i[retry_if on_retry on_give_up].each do |opt|
+      it "accepts a callable for #{opt}" do
+        expect { described_class.new(opt => ->(*) {}) }.not_to raise_error
+      end
+
+      it "accepts nil and false for #{opt}" do
+        expect { described_class.new(opt => nil) }.not_to raise_error
+        expect { described_class.new(opt => false) }.not_to raise_error
+      end
+
+      it "rejects a non-callable truthy value for #{opt}" do
+        expect { described_class.new(opt => 5) }.to raise_error(ArgumentError, /#{opt}.*#call/)
+      end
+    end
+  end
 end

data/spec/exponential_backoff_spec.rb

@@ -22,17 +22,19 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates 10 randomized intervals" do
-    expect(described_class.new(tries: 9).intervals).to eq([
-      0.5244067512211441,
-      0.9113920238761231,
-      1.2406087918999114,
-      1.7632403621664823,
-      2.338001204738311,
-      4.350816718580626,
-      5.339852157217869,
-      11.889873261212443,
-      18.756037881636484,
-    ])
+    expect(described_class.new(tries: 9).intervals).to eq(
+      [
+        0.5244067512211441,
+        0.9113920238761231,
+        1.2406087918999114,
+        1.7632403621664823,
+        2.338001204738311,
+        4.350816718580626,
+        5.339852157217869,
+        11.889873261212443,
+        18.756037881636484,
+      ],
+    )
   end
 
   it "generates defined number of intervals" do
@@ -40,19 +42,23 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates intervals with a defined base interval" do
-    expect(described_class.new(base_interval: 1).intervals).to eq([
-      1.0488135024422882,
-      1.8227840477522461,
-      2.4812175837998227,
-    ])
+    expect(described_class.new(base_interval: 1).intervals).to eq(
+      [
+        1.0488135024422882,
+        1.8227840477522461,
+        2.4812175837998227,
+      ],
+    )
   end
 
   it "generates intervals with a defined multiplier" do
-    expect(described_class.new(multiplier: 1).intervals).to eq([
-      0.5244067512211441,
-      0.607594682584082,
-      0.5513816852888495,
-    ])
+    expect(described_class.new(multiplier: 1).intervals).to eq(
+      [
+        0.5244067512211441,
+        0.607594682584082,
+        0.5513816852888495,
+      ],
+    )
   end
 
   it "generates intervals with a defined max interval" do
@@ -60,15 +66,28 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates intervals with a defined rand_factor" do
-    expect(described_class.new(rand_factor: 0.2).intervals).to eq([
-      0.5097627004884576,
-      0.8145568095504492,
-      1.1712435167599646,
-    ])
+    expect(described_class.new(rand_factor: 0.2).intervals).to eq(
+      [
+        0.5097627004884576,
+        0.8145568095504492,
+        1.1712435167599646,
+      ],
+    )
   end
 
   it "generates 10 non-randomized intervals" do
     non_random_intervals = 9.times.inject([0.5]) { |memo, _i| memo + [memo.last * 1.5] }
     expect(described_class.new(tries: 10, rand_factor: 0.0).intervals).to eq(non_random_intervals)
   end
+
+  it "provides capped intervals lazily" do
+    interval_for = described_class.new(
+      base_interval: 1.0,
+      multiplier: 2.0,
+      max_interval: 4.0,
+      rand_factor: 0.0,
+    ).interval_provider
+
+    expect(Array.new(5) { |index| interval_for.call(index) }).to eq([1.0, 2.0, 4.0, 4.0, 4.0])
+  end
 end