retriable 3.5.0 → 3.8.0

data/lib/retriable/config.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "exponential_backoff"
+require_relative "validation"
 
 module Retriable
   class Config
+    include Validation
+
     ATTRIBUTES = (ExponentialBackoff::ATTRIBUTES + %i[
       sleep_disabled
       max_elapsed_time
@@ -15,6 +18,19 @@ module Retriable
       contexts
     ]).freeze
 
+    TIMEOUT_DEPRECATION_MESSAGE = "NOTE: Retriable's `timeout:` option is deprecated and will be removed in " \
+                                  "Retriable 4.0. It is a thin wrapper around `Timeout.timeout`, which " \
+                                  "can interrupt execution at arbitrary lines and corrupt internal state " \
+                                  "in libraries that are not interrupt-safe. Prefer your library's native " \
+                                  "timeout, or wrap your block in `Timeout.timeout(...)` yourself."
+    private_constant :TIMEOUT_DEPRECATION_MESSAGE
+
+    @timeout_deprecation_warned = false
+
+    class << self
+      attr_accessor :timeout_deprecation_warned
+    end
+
     attr_accessor(*ATTRIBUTES)
 
     def initialize(opts = {})
@@ -39,6 +55,8 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def to_h
@@ -46,5 +64,90 @@ module Retriable
         hash[key] = public_send(key)
       end
     end
+
+    def validate!
+      warn_timeout_deprecation
+      validate_optional_non_negative_number(:timeout, timeout)
+      validate_on(on)
+      validate_intervals
+      if unbounded_tries?(tries)
+        validate_unbounded_tries
+      else
+        validate_optional_non_negative_number(:max_elapsed_time, max_elapsed_time)
+        return if intervals
+
+        validate_positive_integer(:tries, tries)
+      end
+
+      validate_backoff_options
+    end
+
+    private
+
+    # Emits the `timeout:` deprecation notice at most once per process.
+    #
+    # On Rubies that support `Kernel#warn(category: :deprecated)` (2.7+), the
+    # notice is emitted under the `:deprecated` category, so callers can use the
+    # standard controls (`Warning[:deprecated] = false`, `-W:no-deprecated`,
+    # `Warning.warn` override) to silence it. On older Rubies the kwarg is not
+    # available and we fall back to plain `Kernel.warn`.
+    #
+    # When the warning is suppressed (either because `Warning[:deprecated]` is
+    # false or the runtime has otherwise muted the category), we deliberately
+    # leave the once-per-process flag unset so a future call with the category
+    # re-enabled still surfaces the notice.
+    def warn_timeout_deprecation
+      return if timeout.nil?
+      return if self.class.timeout_deprecation_warned
+
+      category_supported = deprecated_warning_category_supported?
+      return if category_supported && !deprecated_warnings_enabled?
+
+      self.class.timeout_deprecation_warned = true
+      if category_supported
+        Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE, category: :deprecated)
+      else
+        Kernel.warn(TIMEOUT_DEPRECATION_MESSAGE)
+      end
+    end
+
+    def deprecated_warning_category_supported?
+      defined?(Warning) && Kernel.method(:warn).parameters.any? { |type, name| type == :key && name == :category }
+    end
+
+    def deprecated_warnings_enabled?
+      return true unless defined?(Warning) && Warning.respond_to?(:[])
+
+      Warning[:deprecated]
+    end
+
+    def validate_backoff_options
+      validate_non_negative_number(:base_interval, base_interval)
+      validate_non_negative_number(:multiplier, multiplier)
+      validate_non_negative_number(:max_interval, max_interval)
+      validate_rand_factor
+    end
+
+    def validate_unbounded_tries
+      if intervals
+        raise ArgumentError,
+              "intervals cannot be used with tries: Float::INFINITY"
+      end
+
+      unless finite_number?(max_elapsed_time)
+        raise ArgumentError,
+              "max_elapsed_time must be a finite number when tries is Float::INFINITY"
+      end
+
+      validate_non_negative_number(:max_elapsed_time, max_elapsed_time)
+    end
+
+    def validate_intervals
+      return if intervals.nil?
+      raise ArgumentError, "intervals must be an Array" unless intervals.is_a?(Array)
+      return if intervals.all? { |interval| finite_number?(interval) && interval >= 0 }
+
+      raise ArgumentError, "intervals must contain only non-negative numbers"
+    end
   end
 end

data/lib/retriable/exponential_backoff.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "validation"
+
 module Retriable
   class ExponentialBackoff
+    include Validation
+
     ATTRIBUTES = %i[
       tries
       base_interval
@@ -24,20 +28,42 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def intervals
-      intervals = Array.new(tries) do |iteration|
-        [base_interval * (multiplier**iteration), max_interval].min
-      end
+      provider = interval_provider
+      Array.new(tries) { |iteration| provider.call(iteration) }
+    end
+
+    def interval_provider
+      raw_interval = base_interval
 
-      return intervals if rand_factor.zero?
+      lambda do |_iteration|
+        interval = [raw_interval, max_interval].min
+        raw_interval = next_raw_interval(raw_interval)
 
-      intervals.map { |i| randomize(i) }
+        rand_factor.zero? ? interval : randomize(interval)
+      end
     end
 
     private
 
+    def validate!
+      validate_non_negative_integer(:tries, tries)
+      validate_non_negative_number(:base_interval, base_interval)
+      validate_non_negative_number(:multiplier, multiplier)
+      validate_non_negative_number(:max_interval, max_interval)
+      validate_rand_factor
+    end
+
+    def next_raw_interval(raw_interval)
+      return max_interval if multiplier >= 1 && raw_interval >= max_interval
+
+      raw_interval * multiplier
+    end
+
     def randomize(interval)
       delta = rand_factor * interval.to_f
       min = interval - delta

data/lib/retriable/validation.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Retriable
+  module Validation
+    private
+
+    def validate_positive_integer(name, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive integer"
+    end
+
+    def validate_non_negative_integer(name, value)
+      return if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative integer"
+    end
+
+    def validate_non_negative_number(name, value)
+      return if finite_number?(value) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative number"
+    end
+
+    def validate_optional_non_negative_number(name, value)
+      return if value.nil?
+
+      validate_non_negative_number(name, value)
+    end
+
+    def validate_rand_factor
+      return if finite_number?(rand_factor) && rand_factor >= 0 && rand_factor <= 1
+
+      raise ArgumentError, "rand_factor must be between 0 and 1"
+    end
+
+    def finite_number?(value)
+      value.is_a?(Numeric) && value.to_f.finite?
+    end
+
+    def unbounded_tries?(value)
+      value.is_a?(Numeric) && value.respond_to?(:infinite?) && value.infinite? == 1
+    end
+
+    module_function :unbounded_tries?
+
+    # Validates an `on:` value. Acceptable shapes:
+    #   - a Class that descends from Exception
+    #   - an Array whose elements are Classes that descend from Exception
+    #   - a Hash whose keys are such Classes and whose values are nil,
+    #     a Regexp, or an Array of Regexps
+    #
+    # Without this validation, callers can pass values like `Object` or
+    # `Kernel` and silently retry process-critical exceptions such as
+    # SystemExit and Interrupt, because every Exception's ancestor chain
+    # includes both. Hash values that are not Regexps (e.g. plain Strings)
+    # also silently fail to match in #hash_exception_match?, so we require
+    # Regexp values explicitly.
+    def validate_on(value)
+      case value
+      when Hash
+        value.each do |klass, pattern|
+          validate_on_class(klass)
+          validate_on_hash_value(klass, pattern)
+        end
+      when Array
+        value.each { |klass| validate_on_class(klass) }
+      else
+        validate_on_class(value)
+      end
+    end
+
+    def validate_on_class(klass)
+      return if klass.is_a?(Class) && klass <= Exception
+
+      raise ArgumentError, "on must be an Exception class or a collection of Exception classes, got #{klass.inspect}"
+    end
+
+    def validate_on_hash_value(klass, pattern)
+      return if pattern.nil?
+      return if pattern.is_a?(Regexp)
+      # Ruby 2.3 does not support Enumerable#all?(pattern).
+      # rubocop:disable Style/PredicateWithKind
+      return if pattern.is_a?(Array) && pattern.all? { |p| p.is_a?(Regexp) }
+      # rubocop:enable Style/PredicateWithKind
+
+      raise ArgumentError,
+            "on[#{klass}] must be nil, a Regexp, or an Array of Regexps, got #{pattern.inspect}"
+    end
+  end
+end

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "3.5.0"
+  VERSION = "3.8.0"
 end

data/lib/retriable.rb

@@ -6,6 +6,16 @@ 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,15 +26,19 @@ module Retriable
     @config ||= Config.new
   end
 
-  def override(opts = {})
-    raise ArgumentError, "empty override options are not allowed; use reset_override instead" if opts.empty?
+  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)
-    @override_config = opts
-  end
 
-  def reset_override
-    @override_config = nil
+    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 = {}, &block)
@@ -41,14 +55,17 @@ module Retriable
   end
 
   def retriable(opts = {}, &block)
-    local_config = if opts.empty? && !@override_config
+    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(config.to_h.merge(opts), override_config))
                    end
 
-    tries = local_config.tries
-    intervals = build_intervals(local_config, tries)
+    # 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
@@ -61,10 +78,8 @@ 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, 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
@@ -72,38 +87,49 @@ module Retriable
   end
 
   def execute_tries( # rubocop:disable Metrics/ParameterLists
-    tries:, intervals:, timeout:, exception_list:,
+    max_tries:, interval_for:, timeout:, exception_list:,
     on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
   )
-    tries.times do |index|
-      try = index + 1
-
+    try = 0
+    loop do
+      try += 1
       begin
         return call_with_timeout(timeout, try, &block)
       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)
 
         elapsed_interval = sleep_disabled == true ? 0 : interval
-        raise unless can_retry?(try, tries, elapsed_time.call, elapsed_interval, max_elapsed_time)
+        raise unless can_retry?(try, max_tries, elapsed_time.call, elapsed_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
+  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
+    ).interval_provider
   end
 
   def call_with_timeout(timeout, try)
@@ -118,8 +144,8 @@ 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
+  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?
 
     (elapsed_time + interval) <= max_elapsed_time
@@ -151,16 +177,23 @@ module Retriable
       raise ArgumentError, "#{k} is not a valid option" unless Config::ATTRIBUTES.include?(k)
     end
 
+    return unless opts.key?(:contexts)
+
     contexts = opts[:contexts]
-    return unless contexts.is_a?(Hash)
+    return if contexts.nil?
+
+    raise ArgumentError, "contexts must be a Hash or nil, got #{contexts.inspect}" unless contexts.is_a?(Hash)
 
-    contexts.each_value do |context_options|
-      validate_context_override_options(context_options)
+    contexts.each do |context_key, context_options|
+      validate_context_override_options(context_key, context_options)
     end
   end
 
-  def validate_context_override_options(context_options)
-    return unless context_options.is_a?(Hash)
+  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|
@@ -196,15 +229,21 @@ module Retriable
   end
 
   def override_contexts
-    contexts = @override_config && @override_config[: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,
+    :retry_plan,
+    :interval_provider,
     :call_with_timeout,
     :call_on_retry,
     :can_retry?,
@@ -215,5 +254,6 @@ module Retriable
     :context_options_for,
     :config_contexts,
     :override_contexts,
+    :current_override,
   )
 end

data/spec/config_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 describe Retriable::Config do
   let(:default_config) { described_class.new }
 
@@ -56,4 +58,189 @@ 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 "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
+  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
+  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 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
 end