retriable 3.6.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9120a536b473da5668754cf8d0021abc06200c558bc916091b871efb24c60f4c
-  data.tar.gz: eb4eaf3b7509cf88c57609a70b83b8fdc75da2727c05a7a0cd5daadf36b601d4
+  metadata.gz: a5f3739e08167965e6f60cc6104d78f46709c323c2b1a80a839afcd5049ba3ca
+  data.tar.gz: f9d5f2fe821d7629ceb6954c0afd1a99f63d8b6c99cecc9575e9b5672489be31
 SHA512:
-  metadata.gz: 0123eb6bbcdb8d392bb5b4b7eab3c59db53970a8bd48b2a320c2d5b085e9196dc2918fd9934f054755069d7cbc7f3d434cac87d2878f2b4ae767d138e5b03d16
-  data.tar.gz: 8d09ecc45ce61a5c76e0afd319b6ddbdb37ae99477f9ec0b6faf81caf6bfbd678abb1336b4254a15350efb2c2bede124625722707241729ed74169d8dfae5a9d
+  metadata.gz: f5d91b6ffed2805e0da09e307da9cddf018647c1ff89e040da96c9bffd26b5929465694d251c33fc19927288568b2ada4a52f3c1c50b384423038c0eb578634a
+  data.tar.gz: 1f1e5f0f352a34831f2e71eda177b88336a4d7571be1f4370d98a151e7d06b65468b7d05f02310087e322611149d751e8a271de2c6931bdc8efef9a5f1cb335f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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.

data/README.md

@@ -104,7 +104,7 @@ 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. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -117,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
 
@@ -273,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:

data/lib/retriable/config.rb

@@ -53,20 +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

@@ -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.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
@@ -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

@@ -66,6 +66,26 @@ describe Retriable::Config 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

@@ -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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.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.