retriable 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575fe838c7ddda74e7e26abf2a3b74a9e4b6866bf20d33a86bc59d1b7c45770d
-  data.tar.gz: f8d81648c9ea122680f3e8eb2f71b7cbbfffc0049313123da850378bf5b3f77d
+  metadata.gz: a5f3739e08167965e6f60cc6104d78f46709c323c2b1a80a839afcd5049ba3ca
+  data.tar.gz: f9d5f2fe821d7629ceb6954c0afd1a99f63d8b6c99cecc9575e9b5672489be31
 SHA512:
-  metadata.gz: bff5a1d9a0efec882841085a306290d11ccd9f20c0622b8a27c733c13981a68c681a562d80eb267c17b866a816a03d514a92b4a17883a1d4180d835f2b76fd02
-  data.tar.gz: 9da2cfea5cf807d352ed899926b0fa9e45d825935697788163dfbd5cf7c47afe7b0cfd7b20af5b29ce61f84d5d923181b7a671e21e3cafd709b15f922c68abf8
+  metadata.gz: f5d91b6ffed2805e0da09e307da9cddf018647c1ff89e040da96c9bffd26b5929465694d251c33fc19927288568b2ada4a52f3c1c50b384423038c0eb578634a
+  data.tar.gz: 1f1e5f0f352a34831f2e71eda177b88336a4d7571be1f4370d98a151e7d06b65468b7d05f02310087e322611149d751e8a271de2c6931bdc8efef9a5f1cb335f

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # HEAD
 
+## 3.7.0
+
+- Feature: Opt-in unbounded retries via `tries: Float::INFINITY`. Requires a finite `max_elapsed_time` as a safety bound and is incompatible with custom `intervals:`. Both invalid configurations raise `ArgumentError` from `Config#validate!`.
+
+## 3.6.1
+
+- Fix: Validate the `on:` option before retrying. Previously, passing a non-`Exception` value such as `Object`, `Kernel`, or a plain `Module` (which appear in every `Exception`'s ancestor chain) would silently retry process-critical exceptions like `SystemExit` and `Interrupt`. The `on:` option now requires an `Exception` subclass, an array of them, or a hash whose keys are such classes and whose values are `nil`, a `Regexp`, or an array of `Regexp`s. Invalid shapes raise `ArgumentError` before the block runs.
+- Fix: Validate `with_override(contexts:)` shape before applying overrides. `contexts` may be `nil` or a hash, and each per-context override must be a hash.
+- Docs: Document that `on_retry: false` disables a callback set in `Retriable.configure` for a single call.
+
 ## 3.6.0
 
 - Breaking: `Retriable.override` and `Retriable.reset_override` are removed and replaced by block-scoped `Retriable.with_override(opts) { ... }`. The new API requires a block, restores the previous override (or absence of override) when the block exits via `ensure`, and is thread-local — overrides set in one thread do not affect other threads, and child threads do not inherit them. Fibers within a thread still share the thread's active override. Nested `with_override` calls correctly restore the outer override on inner exit. See the README and `docs/testing.md` for migration and testing patterns. This replaces the override API introduced in 3.5.0.

data/README.md

@@ -5,6 +5,29 @@
 
 Retriable is a simple DSL to retry failed code blocks with randomized [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff) time intervals. This is especially useful when interacting external APIs, remote services, or file system calls.
 
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Defaults](#defaults)
+  - [Options](#options)
+    - [Configuring Which Options to Retry With :on](#configuring-which-options-to-retry-with-on)
+    - [Advanced Retry Matching With :retry_if](#advanced-retry-matching-with-retry_if)
+  - [Configuration](#configuration)
+  - [Override](#override)
+  - [Example Usage](#example-usage)
+  - [Custom Interval Array](#custom-interval-array)
+  - [Turn off Exponential Backoff](#turn-off-exponential-backoff)
+  - [Callbacks](#callbacks)
+  - [Ensure/Else](#ensureelse)
+- [Contexts](#contexts)
+- [Kernel Extension](#kernel-extension)
+- [Testing](#testing)
+- [Credits](#credits)
+- [Development](#development)
+  - [Running Specs](#running-specs)
+
 ## Requirements
 
 Ruby 2.3.0+
@@ -81,10 +104,10 @@ Here are the available options, in some vague order of relevance to most common
 
 | Option                 | Default           | Definition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt). Pass `Float::INFINITY` to keep retrying until success or until `max_elapsed_time` is reached.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | **`on`**               | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | **`retry_if`**         | `nil`             | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if).                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **`on_retry`**         | `nil`             | `Proc` to call after each try is rescued. [Read more](#callbacks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **`on_retry`**         | `nil`             | `Proc` to call after each try is rescued. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **`sleep_disabled`**   | `false`           | When true, disable exponential backoff and attempt retries immediately.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **`base_interval`**    | `0.5`             | The initial interval in seconds between tries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | **`max_elapsed_time`** | `900` (15 min)    | The maximum amount of total time in seconds that code is allowed to keep being retried. Set to `nil` to disable the time limit and retry based solely on `tries`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -94,7 +117,7 @@ Here are the available options, in some vague order of relevance to most common
 | **`intervals`**        | `nil`             | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | **`timeout`**          | `nil`             | Number of seconds to allow the code block to run before raising a `Timeout::Error` inside each try. `nil` means the code block can run forever without raising error. The implementation uses `Timeout::timeout`, which may be [unsafe](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/) [and](http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html) [even](https://adamhooper.medium.com/in-ruby-dont-use-timeout-77d9d4e5a001) [dangerous](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/). Proceed with caution. |
 
-Timing options are validated before retrying. `tries` must be a positive integer when Retriable generates intervals. `base_interval`, `max_interval`, `multiplier`, `max_elapsed_time`, and `timeout` must be non-negative numbers, with `max_elapsed_time` and `timeout` also accepting `nil`. `rand_factor` must be a number from `0` through `1`. If provided, `intervals` must be an array of non-negative numbers; because it replaces generated intervals, it also overrides `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` validation.
+Timing options are validated before retrying. `tries` must be a positive integer when Retriable generates intervals, or `Float::INFINITY` for unbounded retries. `base_interval`, `max_interval`, `multiplier`, `max_elapsed_time`, and `timeout` must be non-negative numbers, with `max_elapsed_time` and `timeout` also accepting `nil`. `rand_factor` must be a number from `0` through `1`. If provided, `intervals` must be an array of non-negative numbers; because it replaces generated intervals, it also overrides `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` validation. `intervals` cannot be combined with `tries: Float::INFINITY`.
 
 #### Configuring Which Options to Retry With :on
 
@@ -250,6 +273,21 @@ end
 
 This example makes 5 total attempts. If the first attempt fails, the 2nd attempt occurs 0.5 seconds later.
 
+### Unbounded Retries (Opt-in)
+
+You can opt in to unbounded retries with `tries: Float::INFINITY`. This is useful for long-running worker processes where retrying should continue indefinitely, but it must be used with care.
+
+```ruby
+Retriable.retriable(tries: Float::INFINITY, max_elapsed_time: 300) do
+  # code here...
+end
+```
+
+When `tries: Float::INFINITY` is set:
+
+- `max_elapsed_time` must be a finite number. Retriable raises `ArgumentError` if it is `nil` or `Float::INFINITY`. This is a safety bound that prevents accidentally unbounded loops.
+- Custom `intervals:` cannot be combined with `Float::INFINITY` and raises `ArgumentError`. Use the exponential backoff settings (`base_interval`, `multiplier`, `max_interval`, `rand_factor`) instead.
+
 ### Turn off Exponential Backoff
 
 Exponential backoff is enabled by default. If you want to simply retry code every second, 5 times maximum, you can do this:
@@ -294,6 +332,26 @@ Retriable.retriable(on_retry: do_this_on_each_retry) do
 end
 ```
 
+#### Disabling a Configured Callback Per Call
+
+If `on_retry` is set in `Retriable.configure`, every call uses it by default. To opt a specific call out — for example, a critical call site that should not log on retry — pass `on_retry: false`. Passing `nil` does not work for this purpose because per-call options are merged over configured defaults; `false` is the explicit "disabled" sentinel.
+
+```ruby
+Retriable.configure do |c|
+  c.on_retry = ->(exception, try, elapsed_time, next_interval) { log(...) }
+end
+
+# Most calls use the configured callback.
+Retriable.retriable do
+  # ...
+end
+
+# This specific call opts out of the configured callback.
+Retriable.retriable(on_retry: false) do
+  # ...
+end
+```
+
 ### Ensure/Else
 
 What if I want to execute a code block at the end, whether or not an exception was rescued ([ensure](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-ensure))? Or what if I want to execute a code block if no exception is raised ([else](http://ruby-doc.org/docs/keywords/1.9/Object.html#method-i-else))? Instead of providing more callbacks, I recommend you just wrap retriable in a begin/retry/else/ensure block:

data/lib/retriable/config.rb

@@ -53,19 +53,43 @@ module Retriable
     end
 
     def validate!
-      validate_optional_non_negative_number(:max_elapsed_time, max_elapsed_time)
       validate_optional_non_negative_number(:timeout, timeout)
+      validate_on(on)
       validate_intervals
-      return if 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)
+        validate_positive_integer(:tries, tries)
+      end
+
+      validate_backoff_options
+    end
+
+    private
+
+    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
 
-    private
+    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?

data/lib/retriable/exponential_backoff.rb

@@ -33,13 +33,19 @@ module Retriable
     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
 
-      return intervals if rand_factor.zero?
+    def interval_provider
+      raw_interval = base_interval
 
-      intervals.map { |i| randomize(i) }
+      lambda do |_iteration|
+        interval = [raw_interval, max_interval].min
+        raw_interval = next_raw_interval(raw_interval)
+
+        rand_factor.zero? ? interval : randomize(interval)
+      end
     end
 
     private
@@ -52,6 +58,12 @@ module Retriable
       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

@@ -37,5 +37,55 @@ module Retriable
     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.6.0"
+  VERSION = "3.7.0"
 end

data/lib/retriable.rb

@@ -13,6 +13,9 @@ module Retriable
   # 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
@@ -62,8 +65,7 @@ module Retriable
     # Config is mutable through `configure`, so validate again immediately before use.
     local_config.validate!
 
-    tries = local_config.tries
-    intervals = build_intervals(local_config, tries)
+    plan = retry_plan(local_config)
     timeout = local_config.timeout
     on = local_config.on
     retry_if = local_config.retry_if
@@ -76,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
@@ -87,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)
@@ -133,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
@@ -166,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?
 
-    contexts.each_value do |context_options|
-      validate_context_override_options(context_options)
+    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_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|
@@ -224,7 +242,8 @@ module Retriable
     :validate_override_options,
     :validate_context_override_options,
     :execute_tries,
-    :build_intervals,
+    :retry_plan,
+    :interval_provider,
     :call_with_timeout,
     :call_on_retry,
     :can_retry?,

data/spec/config_spec.rb

@@ -65,4 +65,90 @@ describe Retriable::Config do
   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

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

data/spec/retriable_spec.rb

@@ -84,6 +84,90 @@ describe Retriable do
       expect(@tries).to eq(10)
     end
 
+    it "does not prebuild generated intervals before the first successful try" do
+      interval_for = ->(_index) { raise "interval should not be used" }
+      backoff = instance_double(Retriable::ExponentialBackoff, interval_provider: interval_for)
+      allow(Retriable::ExponentialBackoff).to receive(:new).and_call_original
+      allow(Retriable::ExponentialBackoff).to receive(:new).with(
+        hash_including(:base_interval, :multiplier, :max_interval, :rand_factor),
+      ).and_return(backoff)
+
+      described_class.retriable(tries: 1_000_000) { increment_tries }
+
+      expect(@tries).to eq(1)
+      expect(backoff).to have_received(:interval_provider)
+    end
+
+    it "supports unbounded retries until the block succeeds" do
+      described_class.retriable(tries: Float::INFINITY, max_elapsed_time: 60) do
+        increment_tries
+        raise StandardError if @tries < 5
+      end
+
+      expect(@tries).to eq(5)
+    end
+
+    it "stops unbounded retries at max_elapsed_time" do
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      timeline = [
+        start_time,
+        start_time,
+        start_time,
+        start_time + 0.01,
+        start_time + 0.01,
+        start_time + 0.02,
+        start_time + 0.02,
+      ]
+      allow(Process).to receive(:clock_gettime).with(Process::CLOCK_MONOTONIC) { timeline.shift || timeline.last }
+
+      expect do
+        described_class.retriable(
+          tries: Float::INFINITY,
+          base_interval: 0.01,
+          multiplier: 1.0,
+          rand_factor: 0.0,
+          sleep_disabled: true,
+          max_elapsed_time: 0.015,
+        ) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(3)
+    end
+
+    it "raises ArgumentError when tries is Float::INFINITY without a finite max_elapsed_time" do
+      expect do
+        described_class.retriable(tries: Float::INFINITY, max_elapsed_time: nil) { increment_tries }
+      end.to raise_error(ArgumentError, /max_elapsed_time must be a finite number/)
+    end
+
+    it "raises ArgumentError when tries is Float::INFINITY with infinite max_elapsed_time" do
+      expect do
+        described_class.retriable(tries: Float::INFINITY, max_elapsed_time: Float::INFINITY) { increment_tries }
+      end.to raise_error(ArgumentError, /max_elapsed_time must be a finite number/)
+    end
+
+    it "raises ArgumentError when tries is Float::INFINITY with custom intervals" do
+      expect do
+        described_class.retriable(tries: Float::INFINITY, intervals: [0.1, 0.2], max_elapsed_time: 60) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(ArgumentError, /intervals cannot be used with tries: Float::INFINITY/)
+    end
+
+    it "raises ArgumentError when tries is Float::NAN" do
+      expect do
+        described_class.retriable(tries: Float::NAN) { increment_tries }
+      end.to raise_error(ArgumentError, /tries/)
+    end
+
+    it "raises ArgumentError when tries is negative infinity" do
+      expect do
+        described_class.retriable(tries: -Float::INFINITY) { increment_tries }
+      end.to raise_error(ArgumentError, /tries/)
+    end
+
     it "will timeout after 1 second" do
       expect { described_class.retriable(timeout: 1) { sleep(1.1) } }.to raise_error(Timeout::Error)
     end
@@ -406,6 +490,16 @@ describe Retriable do
 
       expect(@tries).to eq(1)
     end
+
+    it "rejects on: Object before invoking the block" do
+      block_invoked = false
+
+      expect do
+        described_class.retriable(on: Object) { block_invoked = true }
+      end.to raise_error(ArgumentError, /on must be an Exception class/)
+
+      expect(block_invoked).to be(false)
+    end
   end
 
   context "#configure" do
@@ -587,25 +681,45 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
-    it "ignores non-hash override contexts values in with_context" do
-      described_class.configure do |c|
-        c.contexts[:api] = { tries: 1 }
-      end
+    it "raises ArgumentError on non-hash override contexts values" do
+      block_called = false
 
-      described_class.with_override(contexts: 123) do
-        described_class.with_context(:api) { increment_tries }
+      expect { described_class.with_override(contexts: 123) { block_called = true } }
+        .to raise_error(ArgumentError, /contexts must be a Hash or nil/)
+      expect(block_called).to be(false)
+    end
+
+    it "raises ArgumentError on non-hash per-context override values" do
+      block_called = false
+
+      expect { described_class.with_override(contexts: { api: 123 }) { block_called = true } }
+        .to raise_error(ArgumentError, /contexts\[:api\] must be a Hash/)
+      expect(block_called).to be(false)
+    end
+
+    it "preserves outer override after rejected nested override contexts values" do
+      described_class.with_override(tries: 2) do
+        expect { described_class.with_override(tries: 1, contexts: 123) { :noop } }
+          .to raise_error(ArgumentError, /contexts must be a Hash or nil/)
+
+        expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }
+          .to raise_error(StandardError)
       end
 
-      expect(@tries).to eq(1)
+      expect(@tries).to eq(2)
     end
 
-    it "ignores non-hash per-context override values in with_context" do
+    it "preserves outer context override after rejected nested per-context values" do
       described_class.configure do |c|
-        c.contexts[:api] = { tries: 2 }
+        c.contexts[:api] = { tries: 10 }
       end
 
-      described_class.with_override(contexts: { api: 123 }) do
-        expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      described_class.with_override(contexts: { api: { tries: 2 } }) do
+        expect { described_class.with_override(contexts: { api: 123 }) { :noop } }
+          .to raise_error(ArgumentError, /contexts\[:api\] must be a Hash/)
+
+        expect { described_class.with_context(:api) { increment_tries_with_exception } }
+          .to raise_error(StandardError)
       end
 
       expect(@tries).to eq(2)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Jack Chu