retriable 3.6.1 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9120a536b473da5668754cf8d0021abc06200c558bc916091b871efb24c60f4c
-  data.tar.gz: eb4eaf3b7509cf88c57609a70b83b8fdc75da2727c05a7a0cd5daadf36b601d4
+  metadata.gz: 25948e6545b8d98b0c7b08416bdf23b017ced352eb2a4eb1f2e9fdac45912031
+  data.tar.gz: 4a92afb17f79a4ad173b046158ca634b0728fc6ccceedc1b7789c9106342b513
 SHA512:
-  metadata.gz: 0123eb6bbcdb8d392bb5b4b7eab3c59db53970a8bd48b2a320c2d5b085e9196dc2918fd9934f054755069d7cbc7f3d434cac87d2878f2b4ae767d138e5b03d16
-  data.tar.gz: 8d09ecc45ce61a5c76e0afd319b6ddbdb37ae99477f9ec0b6faf81caf6bfbd678abb1336b4254a15350efb2c2bede124625722707241729ed74169d8dfae5a9d
+  metadata.gz: e43731b305a64c806bf57c13d78da410412d8ea4adaec9f255bd434b2d190ac53b6fac29172b72ed6bcc7329a3d5378c4075d72f6dede791f1e0bd16f400e58e
+  data.tar.gz: 4259468487738b9ae5bcc817ac992af3341f15bcfe604ab0a61ddf1f8793b444775aa57c06ce5f95561e179186e7360e86a877afd02f3b346b68377ffb3ecaf9

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # HEAD
 
+## 3.8.0
+
+### Deprecations
+
+- Deprecated the `timeout:` option ahead of its removal in Retriable 4.0. Non-nil timeout values supplied through `Retriable.configure`, `Retriable.retriable(...)`, or `Retriable.with_override(...)` now emit a deprecation warning while keeping the existing runtime behavior unchanged. On Ruby 2.7+ the warning is emitted via `Kernel.warn(..., category: :deprecated)`, so callers can silence it through the standard Ruby controls (`Warning[:deprecated] = false`, `ruby -W:no-deprecated`, or a custom `Warning.warn`). To keep the notice from drowning busy applications, it is emitted at most once per process; suppression via `Warning[:deprecated]` leaves the warner armed for the next call that re-enables the category. Prefer library-native timeout settings, or wrap the retried block in `Timeout.timeout(...)` directly if you still need that behavior. See the README migration guidance for details.
+
+## 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.

data/README.md

@@ -17,6 +17,7 @@ Retriable is a simple DSL to retry failed code blocks with randomized [exponenti
   - [Configuration](#configuration)
   - [Override](#override)
   - [Example Usage](#example-usage)
+    - [Migrating off `timeout:`](#migrating-off-timeout)
   - [Custom Interval Array](#custom-interval-array)
   - [Turn off Exponential Backoff](#turn-off-exponential-backoff)
   - [Callbacks](#callbacks)
@@ -55,7 +56,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.6'
+gem 'retriable', '~> 3.8'
 ```
 
 ## Usage
@@ -102,22 +103,22 @@ The default interval table with 10 tries looks like this (in seconds, rounded to
 
 Here are the available options, in some vague order of relevance to most common use patterns:
 
-| Option                 | Default           | Definition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **`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. 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **`max_interval`**     | `60`              | The maximum interval in seconds that any individual retry can reach.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| **`multiplier`**       | `1.5`             | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| **`rand_factor`**      | `0.5`             | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])`                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **`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.
+| Option                 | Default           | Definition                                                                                                                                                                                                                                                                                                       |
+| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`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. 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`.                                                                                                                                                |
+| **`max_interval`**     | `60`              | The maximum interval in seconds that any individual retry can reach.                                                                                                                                                                                                                                             |
+| **`multiplier`**       | `1.5`             | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.                                                                                                                                                                                     |
+| **`rand_factor`**      | `0.5`             | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])`                                                                                                 |
+| **`intervals`**        | `nil`             | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array).                                                                                                                                                                                                |
+| **`timeout`**          | `nil`             | Deprecated in 3.8.0 and removed in 4.0. 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. Non-nil values emit a deprecation warning. See [Migrating off `timeout:`](#migrating-off-timeout). |
+
+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
 
@@ -243,20 +244,32 @@ Retriable.retriable(on: {
 end
 ```
 
-You can also specify a timeout if you want the code block to only try for X amount of seconds. This timeout is per try.
+#### Migrating off `timeout:`
 
-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/). You can use this option, but you need to be very careful because the code in the block, including libraries or other code it calls, could be interrupted by the timeout at any line. You must ensure you have the right rescue logic and guards in place ([Thread.handle_interrupt](https://www.rubydoc.info/stdlib/core/Thread.handle_interrupt)) to handle that possible behavior. If that's not possible, the recommendation is that you're better off impelenting your own timeout methods depending on what your code is doing than use this feature.
+The `timeout:` option is deprecated in Retriable 3.8.0 and will be removed in Retriable 4.0. It still works in 3.x, but any non-nil value supplied through `Retriable.configure`, `Retriable.retriable(...)`, or `Retriable.with_override(...)` emits a deprecation warning. In Retriable 4.0, passing `timeout:` will raise `ArgumentError` because it will no longer be a valid option.
+
+`timeout:` is deprecated because it is a thin wrapper around `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/). It can interrupt the retried block at any line, including inside libraries that are not interrupt-safe.
+
+Prefer timeout settings from the library you are calling, such as `Net::HTTP#read_timeout`, `Net::HTTP#open_timeout`, or Faraday's request timeout options. If you still need `Timeout.timeout`, wrap the retried block explicitly so the risk is visible at the call site:
 
 ```ruby
-Retriable.retriable(timeout: 60) do
-  # code here...
+require "timeout"
+
+Retriable.retriable(on: Timeout::Error, tries: 3) do
+  Timeout.timeout(5) do
+    # code here...
+  end
 end
 ```
 
-If you need millisecond units of time for the sleep or the timeout:
+Like the deprecated `timeout:` option, `Timeout.timeout(5)` inside the block is per-try — each retry gets a fresh 5-second budget. If you want an overall cap across all retries instead, prefer `max_elapsed_time:`.
+
+The deprecation warning is emitted under the `:deprecated` warning category and at most once per process. To silence it (for example, in tests), use the standard Ruby controls — set `Warning[:deprecated] = false`, run with `ruby -W:no-deprecated`, or override `Warning.warn` to filter the message.
+
+If you need millisecond units of time for the sleep interval:
 
 ```ruby
-Retriable.retriable(base_interval: (200 / 1000.0), timeout: (500 / 1000.0)) do
+Retriable.retriable(base_interval: (200 / 1000.0)) do
   # code here...
 end
 ```
@@ -273,6 +286,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:

data/lib/retriable/config.rb

@@ -18,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 = {})
@@ -53,20 +66,81 @@ module Retriable
     end
 
     def validate!
-      validate_optional_non_negative_number(:max_elapsed_time, max_elapsed_time)
+      warn_timeout_deprecation
       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)
+      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
 
-      validate_positive_integer(:tries, tries)
+    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

@@ -38,6 +38,12 @@ module Retriable
       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
@@ -73,7 +79,10 @@ module Retriable
     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}"

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "3.6.1"
+  VERSION = "3.8.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
@@ -231,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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 describe Retriable::Config do
   let(:default_config) { described_class.new }
 
@@ -59,13 +61,123 @@ describe Retriable::Config do
 
   it "raises errors on invalid timing configuration" do
     expect { described_class.new(rand_factor: 1.1) }.to raise_error(ArgumentError, /rand_factor/)
-    expect { described_class.new(timeout: -1) }.to raise_error(ArgumentError, /timeout/)
+    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

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rbconfig"
+require "stringio"
 
 describe Retriable do
   let(:time_table_handler) do
@@ -50,7 +51,9 @@ describe Retriable do
 
     it "raises a LocalJumpError if not given a block" do
       expect { described_class.retriable }.to raise_error(LocalJumpError)
-      expect { described_class.retriable(timeout: 2) }.to raise_error(LocalJumpError)
+      expect do
+        expect { described_class.retriable(timeout: 2) }.to raise_error(LocalJumpError)
+      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
     end
 
     it "stops at first try if the block does not raise an exception" do
@@ -84,8 +87,170 @@ 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)
+      expect do
+        expect { described_class.retriable(timeout: 1) { sleep(1.1) } }.to raise_error(Timeout::Error)
+      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
+    end
+
+    context "timeout: deprecation" do
+      it "warns at most once per process across repeated retriable calls" do
+        original_stderr = $stderr
+        stderr = StringIO.new
+        begin
+          $stderr = stderr
+
+          described_class.retriable(timeout: 5) { :noop }
+          described_class.retriable(timeout: 5) { :noop }
+          described_class.retriable(timeout: 5) { :noop }
+
+          expect(stderr.string.scan("timeout:` option is deprecated").size).to eq(1)
+        ensure
+          $stderr = original_stderr
+        end
+      end
+
+      it "warns when timeout is passed to retriable" do
+        expect do
+          described_class.retriable(timeout: 5) { :noop }
+        end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
+      end
+
+      it "keeps applying timeout while deprecated" do
+        original_stderr = $stderr
+        begin
+          $stderr = StringIO.new
+          expect do
+            described_class.retriable(timeout: 0.05, tries: 1) { sleep(0.5) }
+          end.to raise_error(Timeout::Error)
+        ensure
+          $stderr = original_stderr
+        end
+      end
+
+      it "warns when timeout is supplied through with_override" do
+        expect do
+          described_class.with_override(timeout: 5) do
+            described_class.retriable { :noop }
+          end
+        end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
+      end
+
+      it "warns when timeout is supplied through configure" do
+        original_config = described_class.config
+        begin
+          expect do
+            described_class.configure { |config| config.timeout = 5 }
+            described_class.retriable { :noop }
+          end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
+        ensure
+          described_class.configure do |config|
+            original_config.to_h.each { |key, value| config.public_send("#{key}=", value) }
+          end
+        end
+      end
+
+      it "is silenced by Warning[:deprecated] = false", if: WARN_CATEGORY_SUPPORTED do
+        original = Warning[:deprecated]
+        begin
+          Warning[:deprecated] = false
+          expect do
+            described_class.retriable(timeout: 5) { :noop }
+          end.not_to output.to_stderr
+        ensure
+          Warning[:deprecated] = original
+        end
+      end
+
+      it "does not warn when timeout is absent" do
+        expect do
+          described_class.retriable { :noop }
+        end.not_to output.to_stderr
+      end
     end
 
     it "applies a randomized exponential backoff to each try" do

data/spec/spec_helper.rb

@@ -7,8 +7,21 @@ require "pry"
 require_relative "../lib/retriable"
 require_relative "support/exceptions"
 
+# Make Retriable's deprecation notices observable to RSpec's
+# `output().to_stderr` matcher. On Ruby 3.0+ the `:deprecated` warning category
+# is suppressed by default, which would hide the notices we want to assert on.
+WARNING_DEPRECATION_SUPPORTED = defined?(Warning) && Warning.respond_to?(:[])
+Warning[:deprecated] = true if WARNING_DEPRECATION_SUPPORTED
+
+# Used by deprecation specs that only make sense on Rubies where `Kernel#warn`
+# supports the `category:` keyword (added in Ruby 2.7).
+WARN_CATEGORY_SUPPORTED = WARNING_DEPRECATION_SUPPORTED &&
+                          Kernel.method(:warn).parameters.include?(%i[key category])
+
 RSpec.configure do |config|
   config.before(:each) do
     srand(0)
+    Retriable::Config.timeout_deprecation_warned = false
+    Warning[:deprecated] = true if WARNING_DEPRECATION_SUPPORTED
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.8.0
 platform: ruby
 authors:
 - Jack Chu
@@ -74,7 +74,6 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- docs/superpowers/specs/2026-05-26-on-give-up-callback-followups-design.md
 - docs/testing.md
 - lib/retriable.rb
 - lib/retriable/config.rb

data/docs/superpowers/specs/2026-05-26-on-give-up-callback-followups-design.md

@@ -1,116 +0,0 @@
-# Design: `on_give_up` callback follow-ups (issue #72, PR #127)
-
-## Context
-
-- Issue [#72](https://github.com/kamui/retriable/issues/72) requests a callback that fires only after all retries are exhausted.
-- Draft PR [#127](https://github.com/kamui/retriable/pull/127) (branch `feat/on-give-up-callback`, authored by maintainer @kamui) implements this as `on_give_up`. It is largely production-ready.
-
-This spec defines a small set of follow-up additions on top of `feat/on-give-up-callback`. It does **not** revisit the design decisions already settled in #127 (naming, signature, reason symbols, opt-out behavior).
-
-## Settled decisions inherited from #127
-
-| Decision | Resolution |
-| --- | --- |
-| Callback name | `on_give_up` |
-| Signature | `(exception, try, elapsed_time, next_interval, reason)` |
-| Reason values | `:tries_exhausted`, `:max_elapsed_time` |
-| `next_interval` when `:tries_exhausted` | `nil` |
-| `next_interval` when `:max_elapsed_time` | The interval that would have been slept before the next try |
-| Opt-out | `on_give_up: false` (or `nil`) disables a configured handler |
-| Order vs `on_retry` | `on_retry` runs first; `on_give_up` runs just before re-raise |
-| Non-retriable exception types | `on_give_up` does **not** fire |
-| `retry_if` rejection | `on_give_up` does **not** fire |
-| `elapsed_time` for the give-up decision | Re-read after `on_retry` returns so handler time counts toward `max_elapsed_time` |
-| Threading through `Config::ATTRIBUTES` | Already enables `with_context`, `override`, and `configure` automatically |
-
-## Gaps to fill
-
-PR #127 has the mechanics right. The follow-up work below closes documentation and test-coverage gaps and locks in undocumented-but-implied semantics.
-
-### 1. Document non-firing cases in README
-
-PR #127 covers the firing cases. The README should explicitly state when the callback does **not** fire, because users wiring up paging/metrics need to know.
-
-Add one paragraph at the end of the new `on_give_up` subsection in `README.md`:
-
-> `on_give_up` is invoked only when Retriable rescued an exception that matched the retry rules and then decided to stop. It does **not** fire when the block raises an exception that is not in `on`, nor when `retry_if` returns false. Both of those cases are immediate re-raises, not retry exhaustion, and should be handled with normal Ruby `rescue` blocks around the `Retriable.retriable` call.
-
-### 2. Document handler-raised-error policy in README
-
-Current `on_retry` documentation does not state what happens if the handler itself raises. PR #127 silently inherits the same behavior: an exception inside `on_give_up` propagates, replacing the original. Make this explicit.
-
-Add one sentence to the same subsection:
-
-> If `on_give_up` itself raises, that exception propagates to the caller and replaces the original retried exception. Keep the handler defensive (rescue inside it) if you need the original exception to surface.
-
-### 3. Mention `on_give_up` in the Contexts example
-
-`README.md` already has a Contexts example at `README.md:306`. Extend the `:aws` context to demonstrate `on_give_up`:
-
-```ruby
-Retriable.configure do |c|
-  c.contexts[:aws] = {
-    tries: 3,
-    base_interval: 5,
-    on_retry: Proc.new { puts 'Curse you, AWS!' },
-    on_give_up: Proc.new { |_e, _try, _elapsed, _interval, reason|
-      puts "Gave up on AWS: #{reason}"
-    },
-  }
-end
-```
-
-### 4. Test: per-context `override` accepts and dispatches `on_give_up`
-
-PR #127 adds a positive `with_context` spec and an `override` spec for top-level overrides, but no spec for the call shape `Retriable.override(contexts: { key: { on_give_up: ... } })`, which is validated by `validate_context_override_options` and applied by `context_options_for`. Add one spec under the existing `#override` context that:
-
-1. Calls `Retriable.override(contexts: { api: { on_give_up: handler, tries: 1 } })`.
-2. Invokes `Retriable.with_context(:api) { raise StandardError }`.
-3. Asserts the handler was invoked exactly once with `reason == :tries_exhausted`.
-
-### 5. Test: kernel extension passes `on_give_up` through
-
-PR #127 does not exercise the kernel extension (`Kernel#retriable` and `Kernel#retriable_with_context`). The delegation is trivial, but a regression guard is cheap. Add one spec inside the existing `context "global scope extension"` block that requires `retriable/core_ext/kernel`, invokes `retriable(tries: 1, on_give_up: handler) { raise }`, and asserts the handler ran with `reason == :tries_exhausted`. A second `retriable_with_context` spec is not needed because item 4 already covers the context-dispatch path.
-
-### 6. Test: handler that raises propagates and replaces the original
-
-Lock in the policy from item 2 with a spec: handler raises `RuntimeError`, caller observes `RuntimeError`, not the original `StandardError`.
-
-### 7. CHANGELOG entry: include signature and reasons
-
-PR #127's CHANGELOG line is:
-
-> - Add `on_give_up` callback to observe when retries stop because tries are exhausted or the next retry would exceed `max_elapsed_time`.
-
-Rewrite to:
-
-> - Add `on_give_up` callback that runs when Retriable stops retrying after a rescued retriable exception. Receives `(exception, try, elapsed_time, next_interval, reason)`, where `reason` is `:tries_exhausted` or `:max_elapsed_time`. Does not fire for non-retriable exceptions or `retry_if` rejections. Pass `on_give_up: false` to suppress a configured handler for a single call.
-
-## Out of scope
-
-- Renaming `on_give_up`. The maintainer authored the draft with this name.
-- Changing the callback signature (e.g., removing `next_interval`).
-- Firing for `retry_if` rejection. That decision was made deliberately in #127.
-- Version bump. Deferred to the maintainer's release commit.
-- Touching the pre-existing rubocop offenses noted in PR #127's description (`retriable.gemspec`, `spec/exponential_backoff_spec.rb`).
-
-## Files touched
-
-- `README.md` — items 1, 2, 3.
-- `spec/retriable_spec.rb` — items 4, 5, 6.
-- `CHANGELOG.md` — item 7.
-
-No changes to `lib/retriable.rb` or `lib/retriable/config.rb`; PR #127's implementation already satisfies the behavior.
-
-## Verification
-
-```sh
-bundle exec rspec
-bundle exec rubocop lib spec
-```
-
-Both must pass. Pre-existing rubocop offenses in `retriable.gemspec` and `spec/exponential_backoff_spec.rb` are intentionally left untouched (see Out of scope).
-
-## Delivery
-
-Push as additional commits on the existing `feat/on-give-up-callback` branch (PR #127). If we lack push access to the maintainer's branch, open a PR targeting `feat/on-give-up-callback` with these follow-ups, or post the diff as a review comment on #127.