retriable 3.5.1 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0cb0bb3751f465d22addceebf5466b165871741e5820c7c3291d2e842f6f48a
-  data.tar.gz: 8bef0641e9c3b0e39c04d79ffcbdaf4542790264ce6648f6540db933cfddbc54
+  metadata.gz: 9120a536b473da5668754cf8d0021abc06200c558bc916091b871efb24c60f4c
+  data.tar.gz: eb4eaf3b7509cf88c57609a70b83b8fdc75da2727c05a7a0cd5daadf36b601d4
 SHA512:
-  metadata.gz: 6c4e07023a30aa934d5397717344c480fb6af8dd56349fcbcb9b85b9ba5539a3f16d2b16a30cbb3682e4140a04f3ace9ecbf0602e68bc4a1a5c805230a031de6
-  data.tar.gz: 4272451f1213b81537fd8f7cd85ced8a341b8f8dbf228493a42393b74cee3400e90eb9aa466ec3e404b98eef78b2a42ade5600b49c5d8d9ba7dd9e9b4ae1f444
+  metadata.gz: 0123eb6bbcdb8d392bb5b4b7eab3c59db53970a8bd48b2a320c2d5b085e9196dc2918fd9934f054755069d7cbc7f3d434cac87d2878f2b4ae767d138e5b03d16
+  data.tar.gz: 8d09ecc45ce61a5c76e0afd319b6ddbdb37ae99477f9ec0b6faf81caf6bfbd678abb1336b4254a15350efb2c2bede124625722707241729ed74169d8dfae5a9d

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+
 ## 3.5.1
 
 - Fix: Validate retry timing and count options before use to reject invalid retry configurations. `tries` must now be a positive integer unless a custom `intervals` array is provided.

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+
@@ -32,7 +55,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.5'
+gem 'retriable', '~> 3.6'
 ```
 
 ## Usage
@@ -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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -149,31 +172,46 @@ end
 
 ### Override
 
-If you need to force values globally (including over per-call options), use
-`#override`:
+`#with_override` is a block-scoped API for forcing retry options that should
+take precedence over both `#configure` defaults and per-call options. It is
+primarily intended for tests — it lets a test force values like `tries: 1` or
+`base_interval: 0` so the suite runs quickly and predictably, regardless of
+the application's `#configure` defaults. In application code, prefer
+`#configure` for app-level defaults and per-call options for caller-specific
+values.
 
 ```ruby
-Retriable.override(tries: 1, base_interval: 0)
+Retriable.with_override(tries: 1, base_interval: 0) do
+  Retriable.retriable do
+    # code here...
+  end
+end
 ```
 
-`#override` precedence:
+Precedence inside the block:
 
 ```
-override > local options > configure defaults
+with_override > local options > configure defaults
 ```
 
-`#override` uses process-global state. Once set, it affects every caller and
-thread until `#reset_override` runs. Prefer setting it once at boot (or in test
-helpers), and avoid toggling it per request in multi-threaded runtimes.
+`#with_override` requires a block and raises `ArgumentError` if called without
+one. The override is active only while the block is executing, and is
+automatically restored to its previous value when the block returns or raises.
+Nested `#with_override` calls work as expected: the inner block temporarily
+replaces the active override and the outer override is restored when the
+inner block exits.
 
-`#override` stores the provided options directly. Do not mutate the options hash
-or nested values after passing them to `#override`.
+`#with_override` is scoped to the **current thread**. The active override
+does not affect any other thread, and child threads spawned inside the block
+do not inherit it. This makes `#with_override` safe to use in parallel test
+runners. Fibers running inside the same thread share the thread's active
+override.
 
-To clear an override:
+`#with_override` stores the provided options directly. Do not mutate the
+options hash or nested values for the duration of the block.
 
-```ruby
-Retriable.reset_override
-```
+For test-integration patterns (RSpec `around`, helper methods, Minitest, etc.),
+see [docs/testing.md](docs/testing.md).
 
 ### Example Usage
 
@@ -279,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:
@@ -369,72 +427,16 @@ retriable_with_context(:api) do
 end
 ```
 
-## Short Circuiting Retriable While Testing Your App
-
-When you are running tests for your app it often takes a long time to retry blocks that fail. This is because Retriable will default to 3 tries with exponential backoff. Ideally your tests will run as quickly as possible.
-
-If you want to short-circuit retries in tests, including calls that pass local options, use `Retriable.override` and set `tries` to `1`.
-
-Under Rails, keep shared defaults in `Retriable.configure` and apply test-only overrides conditionally:
-
-```ruby
-# config/initializers/retriable.rb
-Retriable.configure do |c|
-  c.tries = 3
-  c.base_interval = 0.5
-  c.rand_factor = 0.5
-end
-
-if Rails.env.test?
-  Retriable.override(tries: 1, base_interval: 0, rand_factor: 0)
-end
-```
-
-If you need to run a specific test with normal retry behavior, call `Retriable.reset_override` for that example and then reapply your test override afterward.
-
-Alternately, if you are using RSpec, you could override the Retriable configuration in your `spec_helper`.
-
-```ruby
-# spec/spec_helper.rb
-Retriable.override(tries: 1, base_interval: 0, rand_factor: 0)
-```
-
-If you have defined contexts for your configuration, top-level override values (such as `tries: 1`) already take precedence over context-specific values. However, if you need to override context-specific options (for example, clearing a context's `:intervals` array or changing its `:on` exception list), pass `:contexts` to `Retriable.override`:
-
-For example assuming you have configured a `google_api` context:
-
-```ruby
-# config/initializers/retriable.rb
-Retriable.configure do |c|
-  c.contexts[:google_api] = {
-      tries:         5,
-      base_interval: 3,
-      on:            [
-          Net::ReadTimeout,
-          Signet::AuthorizationError,
-          Errno::ECONNRESET,
-          OpenSSL::SSL::SSLError
-      ]
-  }
-end
-```
-
-Then in your test environment, you can override both top-level defaults and per-context options:
+## Testing
 
-```ruby
-# Build context overrides from existing configured context keys
-context_overrides = {}
-Retriable.config.contexts.each_key do |key|
-  context_overrides[key] = { tries: 1, base_interval: 0 }
-end
+`Retriable.with_override` is designed to short-circuit retries in your test
+suite so failing blocks do not slow tests down. The simplest pattern is an
+RSpec `around(:each)` hook (or your test framework's equivalent) that wraps
+every example in `with_override(tries: 1, base_interval: 0)`.
 
-Retriable.override(
-  multiplier: 1.0,
-  rand_factor: 0.0,
-  base_interval: 0,
-  contexts: context_overrides,
-)
-```
+For Rails integration, opting out of the override for specific tests, and
+overriding configured contexts in tests, see
+[docs/testing.md](docs/testing.md).
 
 ## Credits
 

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/docs/testing.md

@@ -0,0 +1,212 @@
+# Testing with Retriable
+
+`Retriable.with_override` exists primarily for tests. It lets a test force
+retry options like `tries: 1` or `base_interval: 0` so the suite runs quickly
+and predictably, regardless of what the application's `Retriable.configure`
+defaults are.
+
+`with_override` is block-scoped: the override is active inside the block and
+restored to its previous value (which is usually "no override") when the block
+exits, even if the block raises. It is also thread-local — overrides set in
+one thread do not affect other threads — so it is safe for parallel test
+runners. See the README for the full API contract.
+
+## RSpec
+
+### Apply an override to every test
+
+Use `around(:each)` in `RSpec.configure` so every test in the suite runs inside
+the override. This is the most common pattern:
+
+```ruby
+RSpec.configure do |config|
+  config.around(:each) do |example|
+    Retriable.with_override(tries: 1, base_interval: 0) do
+      example.run
+    end
+  end
+end
+```
+
+### Apply an override to a specific context
+
+```ruby
+describe MyClient do
+  context "when external calls should not retry" do
+    around(:each) do |example|
+      Retriable.with_override(tries: 1) { example.run }
+    end
+
+    it "fails fast" do
+      # `with_override(tries: 1)` is active here
+    end
+  end
+end
+```
+
+### Apply an override to a single test
+
+Wrap the test body directly:
+
+```ruby
+it "does the thing without waiting" do
+  Retriable.with_override(tries: 1, base_interval: 0) do
+    # test body
+  end
+end
+```
+
+### Reusable helper
+
+Wrap a common configuration in a helper to keep tests readable:
+
+```ruby
+module RetriableHelpers
+  def with_fast_retries(&block)
+    Retriable.with_override(tries: 1, base_interval: 0, &block)
+  end
+end
+
+RSpec.configure do |config|
+  config.include RetriableHelpers
+end
+
+# In a spec:
+it "does the thing" do
+  with_fast_retries do
+    # test body
+  end
+end
+```
+
+## Minitest
+
+```ruby
+class MyClientTest < Minitest::Test
+  def around
+    Retriable.with_override(tries: 1, base_interval: 0) { yield }
+  end
+
+  def test_fails_fast
+    # `with_override(tries: 1)` is active here
+  end
+end
+```
+
+Older Minitest versions without `around` can wrap the test body directly:
+
+```ruby
+def test_fails_fast
+  Retriable.with_override(tries: 1) do
+    # test body
+  end
+end
+```
+
+## Short-Circuiting Retriable in Your Test Suite
+
+When you are running tests for your app, the default retry behavior (3 tries
+with exponential backoff) makes failing blocks take a long time. To short-circuit
+retries — including calls that pass local options — set `tries: 1` and disable
+backoff using `with_override`.
+
+### Under Rails
+
+Keep shared defaults in `Retriable.configure` and apply test-only overrides via
+RSpec's `around` hook (or your test framework's equivalent):
+
+```ruby
+# config/initializers/retriable.rb
+Retriable.configure do |c|
+  c.tries = 3
+  c.base_interval = 0.5
+  c.rand_factor = 0.5
+end
+
+# spec/spec_helper.rb (or equivalent)
+RSpec.configure do |config|
+  config.around(:each) do |example|
+    Retriable.with_override(tries: 1, base_interval: 0, rand_factor: 0) do
+      example.run
+    end
+  end
+end
+```
+
+If a specific test needs normal retry behavior, opt out by running outside the
+`around` hook. The cleanest way is to tag the example and skip the hook for
+tagged examples:
+
+```ruby
+config.around(:each, retriable: :real) { |example| example.run }
+config.around(:each) do |example|
+  next example.run if example.metadata[:retriable] == :real
+
+  Retriable.with_override(tries: 1, base_interval: 0, rand_factor: 0) do
+    example.run
+  end
+end
+
+it "exercises the real retry behavior", retriable: :real do
+  # `with_override` is not applied here
+end
+```
+
+### Overriding Configured Contexts in Tests
+
+If you have configured contexts, top-level override values (such as `tries: 1`)
+already take precedence over context-specific values. To override
+context-specific options as well (for example, clearing a context's
+`:intervals` array or shrinking its `:on` exception list), pass `:contexts` to
+`with_override`.
+
+Given a configured `google_api` context:
+
+```ruby
+# config/initializers/retriable.rb
+Retriable.configure do |c|
+  c.contexts[:google_api] = {
+    tries:         5,
+    base_interval: 3,
+    on: [
+      Net::ReadTimeout,
+      Signet::AuthorizationError,
+      Errno::ECONNRESET,
+      OpenSSL::SSL::SSLError,
+    ],
+  }
+end
+```
+
+You can override both top-level defaults and per-context options in your
+test setup:
+
+```ruby
+RSpec.configure do |config|
+  config.around(:each) do |example|
+    context_overrides = Retriable.config.contexts.each_key.with_object({}) do |key, h|
+      h[key] = { tries: 1, base_interval: 0 }
+    end
+
+    Retriable.with_override(
+      multiplier: 1.0,
+      rand_factor: 0.0,
+      base_interval: 0,
+      contexts: context_overrides,
+    ) do
+      example.run
+    end
+  end
+end
+```
+
+## Notes
+
+- The override is automatically cleared when the block exits, including when
+  the block raises. You do not need to clean up after the block.
+- `with_override` calls nest: an inner block temporarily replaces the active
+  override, and the outer override is restored when the inner block exits.
+- Overrides are thread-local. Child threads spawned inside the block do not
+  inherit it. If a test spawns background threads that themselves call
+  `Retriable.retriable`, wrap each background thread's body in its own
+  `with_override` call.

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.5.1"
+  VERSION = "3.6.1"
 end