retriable 3.6.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575fe838c7ddda74e7e26abf2a3b74a9e4b6866bf20d33a86bc59d1b7c45770d
-  data.tar.gz: f8d81648c9ea122680f3e8eb2f71b7cbbfffc0049313123da850378bf5b3f77d
+  metadata.gz: 9120a536b473da5668754cf8d0021abc06200c558bc916091b871efb24c60f4c
+  data.tar.gz: eb4eaf3b7509cf88c57609a70b83b8fdc75da2727c05a7a0cd5daadf36b601d4
 SHA512:
-  metadata.gz: bff5a1d9a0efec882841085a306290d11ccd9f20c0622b8a27c733c13981a68c681a562d80eb267c17b866a816a03d514a92b4a17883a1d4180d835f2b76fd02
-  data.tar.gz: 9da2cfea5cf807d352ed899926b0fa9e45d825935697788163dfbd5cf7c47afe7b0cfd7b20af5b29ce61f84d5d923181b7a671e21e3cafd709b15f922c68abf8
+  metadata.gz: 0123eb6bbcdb8d392bb5b4b7eab3c59db53970a8bd48b2a320c2d5b085e9196dc2918fd9934f054755069d7cbc7f3d434cac87d2878f2b4ae767d138e5b03d16
+  data.tar.gz: 8d09ecc45ce61a5c76e0afd319b6ddbdb37ae99477f9ec0b6faf81caf6bfbd678abb1336b4254a15350efb2c2bede124625722707241729ed74169d8dfae5a9d

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # HEAD
 
+## 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+
@@ -84,7 +107,7 @@ Here are the available options, in some vague order of relevance to most common
 | **`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. [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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -294,6 +317,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/docs/superpowers/specs/2026-05-26-on-give-up-callback-followups-design.md

@@ -0,0 +1,116 @@
+# 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.

data/lib/retriable/config.rb

@@ -55,6 +55,7 @@ module Retriable
     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
 

data/lib/retriable/validation.rb

@@ -37,5 +37,46 @@ module Retriable
     def finite_number?(value)
       value.is_a?(Numeric) && value.to_f.finite?
     end
+
+    # 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)
+      return if pattern.is_a?(Array) && pattern.all? { |p| p.is_a?(Regexp) }
+
+      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.6.1"
 end

data/lib/retriable.rb

@@ -166,16 +166,23 @@ module Retriable
       raise ArgumentError, "#{k} is not a valid option" unless Config::ATTRIBUTES.include?(k)
     end
 
+    return unless opts.key?(:contexts)
+
     contexts = opts[:contexts]
-    return unless contexts.is_a?(Hash)
+    return if contexts.nil?
+
+    raise ArgumentError, "contexts must be a Hash or nil, got #{contexts.inspect}" unless contexts.is_a?(Hash)
 
-    contexts.each_value do |context_options|
-      validate_context_override_options(context_options)
+    contexts.each do |context_key, context_options|
+      validate_context_override_options(context_key, context_options)
     end
   end
 
-  def validate_context_override_options(context_options)
-    return unless context_options.is_a?(Hash)
+  def validate_context_override_options(context_key, context_options)
+    unless context_options.is_a?(Hash)
+      raise ArgumentError,
+            "contexts[#{context_key.inspect}] must be a Hash, got #{context_options.inspect}"
+    end
 
     context_attributes = Config::ATTRIBUTES - [:contexts]
     context_options.each_key do |k|

data/spec/config_spec.rb

@@ -65,4 +65,70 @@ 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
+
+  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/retriable_spec.rb

@@ -406,6 +406,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 +597,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.6.1
 platform: ruby
 authors:
 - Jack Chu
@@ -74,6 +74,7 @@ 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