retriable 3.5.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0cb0bb3751f465d22addceebf5466b165871741e5820c7c3291d2e842f6f48a
-  data.tar.gz: 8bef0641e9c3b0e39c04d79ffcbdaf4542790264ce6648f6540db933cfddbc54
+  metadata.gz: 575fe838c7ddda74e7e26abf2a3b74a9e4b6866bf20d33a86bc59d1b7c45770d
+  data.tar.gz: f8d81648c9ea122680f3e8eb2f71b7cbbfffc0049313123da850378bf5b3f77d
 SHA512:
-  metadata.gz: 6c4e07023a30aa934d5397717344c480fb6af8dd56349fcbcb9b85b9ba5539a3f16d2b16a30cbb3682e4140a04f3ace9ecbf0602e68bc4a1a5c805230a031de6
-  data.tar.gz: 4272451f1213b81537fd8f7cd85ced8a341b8f8dbf228493a42393b74cee3400e90eb9aa466ec3e404b98eef78b2a42ade5600b49c5d8d9ba7dd9e9b4ae1f444
+  metadata.gz: bff5a1d9a0efec882841085a306290d11ccd9f20c0622b8a27c733c13981a68c681a562d80eb267c17b866a816a03d514a92b4a17883a1d4180d835f2b76fd02
+  data.tar.gz: 9da2cfea5cf807d352ed899926b0fa9e45d825935697788163dfbd5cf7c47afe7b0cfd7b20af5b29ce61f84d5d923181b7a671e21e3cafd709b15f922c68abf8

data/CHANGELOG.md

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

@@ -32,7 +32,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.5'
+gem 'retriable', '~> 3.6'
 ```
 
 ## Usage
@@ -149,31 +149,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
 
@@ -369,72 +384,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.
+## Testing
 
-Alternately, if you are using RSpec, you could override the Retriable configuration in your `spec_helper`.
+`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)`.
 
-```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:
-
-```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.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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "3.5.1"
+  VERSION = "3.6.0"
 end

data/lib/retriable.rb

@@ -6,6 +6,13 @@ require_relative "retriable/exponential_backoff"
 require_relative "retriable/version"
 
 module Retriable
+  # Thread-local storage key for the active #with_override block.
+  # We deliberately use Thread#thread_variable_set/get (true thread-local)
+  # rather than Thread.current[] (fiber-local) so that fibers within a thread
+  # share the same override. Changing this to Thread.current[] would silently
+  # break callers that use fiber-based concurrency.
+  OVERRIDE_THREAD_KEY = :retriable_override
+
   module_function
 
   def configure
@@ -16,15 +23,19 @@ module Retriable
     @config ||= Config.new
   end
 
-  def override(opts = {})
-    raise ArgumentError, "empty override options are not allowed; use reset_override instead" if opts.empty?
+  def with_override(opts = {})
+    raise ArgumentError, "empty override options are not allowed" if opts.empty?
+    raise ArgumentError, "with_override requires a block" unless block_given?
 
     validate_override_options(opts)
-    @override_config = opts
-  end
 
-  def reset_override
-    @override_config = nil
+    previous = Thread.current.thread_variable_get(OVERRIDE_THREAD_KEY)
+    Thread.current.thread_variable_set(OVERRIDE_THREAD_KEY, opts)
+    begin
+      yield
+    ensure
+      Thread.current.thread_variable_set(OVERRIDE_THREAD_KEY, previous)
+    end
   end
 
   def with_context(context_key, options = {}, &block)
@@ -41,10 +52,11 @@ module Retriable
   end
 
   def retriable(opts = {}, &block)
-    local_config = if opts.empty? && !@override_config
+    override_config = current_override
+    local_config = if opts.empty? && !override_config
                      config
                    else
-                     Config.new(apply_override_options(config.to_h.merge(opts), @override_config))
+                     Config.new(apply_override_options(config.to_h.merge(opts), override_config))
                    end
 
     # Config is mutable through `configure`, so validate again immediately before use.
@@ -199,10 +211,15 @@ module Retriable
   end
 
   def override_contexts
-    contexts = @override_config && @override_config[:contexts]
+    override_config = current_override
+    contexts = override_config && override_config[:contexts]
     contexts.is_a?(Hash) ? contexts : {}
   end
 
+  def current_override
+    Thread.current.thread_variable_get(OVERRIDE_THREAD_KEY)
+  end
+
   private_class_method(
     :validate_override_options,
     :validate_context_override_options,
@@ -218,5 +235,6 @@ module Retriable
     :context_options_for,
     :config_contexts,
     :override_contexts,
+    :current_override,
   )
 end

data/spec/retriable_spec.rb

@@ -9,7 +9,7 @@ describe Retriable do
 
   before(:each) do
     described_class.instance_variable_set(:@config, nil)
-    described_class.reset_override
+    Thread.current.thread_variable_set(Retriable::OVERRIDE_THREAD_KEY, nil)
     described_class.configure { |c| c.sleep_disabled = true }
     @tries = 0
     @next_interval_table = {}
@@ -415,8 +415,7 @@ describe Retriable do
         with_context
         configure
         config
-        override
-        reset_override
+        with_override
       ]
 
       expect(described_class.singleton_methods(false)).to match_array(public_api_methods)
@@ -427,25 +426,23 @@ describe Retriable do
     end
   end
 
-  context "#override" do
-    after(:each) do
-      described_class.reset_override
-    end
-
+  context "#with_override" do
     it "takes precedence over both global config and local options" do
       described_class.configure { |c| c.tries = 2 }
-      described_class.override(tries: 1)
 
-      expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }.to raise_error(StandardError)
+      described_class.with_override(tries: 1) do
+        expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }.to raise_error(StandardError)
+      end
+
       expect(@tries).to eq(1)
     end
 
     it "lets override tries take precedence over local intervals" do
-      described_class.override(tries: 1)
-
-      expect do
-        described_class.retriable(intervals: [0.5, 1.0]) { increment_tries_with_exception }
-      end.to raise_error(StandardError)
+      described_class.with_override(tries: 1) do
+        expect do
+          described_class.retriable(intervals: [0.5, 1.0]) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+      end
 
       expect(@tries).to eq(1)
     end
@@ -454,9 +451,11 @@ describe Retriable do
       described_class.configure do |c|
         c.contexts[:api] = { intervals: [0.5, 1.0] }
       end
-      described_class.override(tries: 1)
 
-      expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      described_class.with_override(tries: 1) do
+        expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      end
+
       expect(@tries).to eq(1)
     end
 
@@ -464,31 +463,34 @@ describe Retriable do
       described_class.configure do |c|
         c.contexts[:api] = { intervals: [0.5, 1.0] }
       end
-      described_class.override(contexts: { api: { tries: 1 } })
 
-      expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      described_class.with_override(contexts: { api: { tries: 1 } }) do
+        expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      end
+
       expect(@tries).to eq(1)
     end
 
     it "replaces hash-valued options instead of deep-merging them" do
-      described_class.override(on: { NonStandardError => nil })
-
-      expect do
-        described_class.retriable(on: { StandardError => nil }, tries: 2) { increment_tries_with_exception }
-      end.to raise_error(StandardError)
+      described_class.with_override(on: { NonStandardError => nil }) do
+        expect do
+          described_class.retriable(on: { StandardError => nil }, tries: 2) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+      end
 
       expect(@tries).to eq(1)
     end
 
     it "can override local intervals with nil to use configured backoff" do
       described_class.configure { |c| c.tries = 3 }
-      described_class.override(intervals: nil)
 
-      expect do
-        described_class.retriable(intervals: [0.5, 1.0], on_retry: time_table_handler) do
-          increment_tries_with_exception
-        end
-      end.to raise_error(StandardError)
+      described_class.with_override(intervals: nil) do
+        expect do
+          described_class.retriable(intervals: [0.5, 1.0], on_retry: time_table_handler) do
+            increment_tries_with_exception
+          end
+        end.to raise_error(StandardError)
+      end
 
       expect(@tries).to eq(3)
       expect(@next_interval_table[1]).to be_between(0.0, 1.0)
@@ -499,23 +501,26 @@ describe Retriable do
         c.contexts[:api] = { tries: 3, base_interval: 1.0 }
       end
 
-      described_class.override(contexts: { api: { tries: 1 } })
+      described_class.with_override(contexts: { api: { tries: 1 } }) do
+        described_class.with_context(:api, tries: 10) { increment_tries }
+      end
 
-      described_class.with_context(:api, tries: 10) { increment_tries }
       expect(@tries).to eq(1)
     end
 
     it "can define a context only in override config" do
-      described_class.override(contexts: { test_only: { tries: 1 } })
+      described_class.with_override(contexts: { test_only: { tries: 1 } }) do
+        described_class.with_context(:test_only) { increment_tries }
+      end
 
-      described_class.with_context(:test_only) { increment_tries }
       expect(@tries).to eq(1)
     end
 
     it "does not apply context-only overrides to plain retriable calls" do
-      described_class.override(contexts: { api: { tries: 1 } })
+      described_class.with_override(contexts: { api: { tries: 1 } }) do
+        expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
+      end
 
-      expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(3)
     end
 
@@ -523,21 +528,24 @@ describe Retriable do
       described_class.configure do |c|
         c.contexts[:api] = { tries: 3, on: NonStandardError }
       end
-      described_class.override(tries: 1)
 
-      expect { described_class.with_context(:api) { increment_tries_with_exception(NonStandardError) } }
-        .to raise_error(NonStandardError)
+      described_class.with_override(tries: 1) do
+        expect { described_class.with_context(:api) { increment_tries_with_exception(NonStandardError) } }
+          .to raise_error(NonStandardError)
+      end
+
       expect(@tries).to eq(1)
     end
 
     it "combines local options with override-only contexts" do
-      described_class.override(contexts: { api: { tries: 1 } })
+      described_class.with_override(contexts: { api: { tries: 1 } }) do
+        expect do
+          described_class.with_context(:api, on: NonStandardError) do
+            increment_tries_with_exception(NonStandardError)
+          end
+        end.to raise_error(NonStandardError)
+      end
 
-      expect do
-        described_class.with_context(:api, on: NonStandardError) do
-          increment_tries_with_exception(NonStandardError)
-        end
-      end.to raise_error(NonStandardError)
       expect(@tries).to eq(1)
     end
 
@@ -546,9 +554,10 @@ describe Retriable do
         c.contexts[:api] = { tries: 1 }
       end
 
-      described_class.override(tries: 1)
+      described_class.with_override(tries: 1) do
+        described_class.with_context(:api) { increment_tries }
+      end
 
-      described_class.with_context(:api) { increment_tries }
       expect(@tries).to eq(1)
     end
 
@@ -556,9 +565,10 @@ describe Retriable do
       begin
         described_class.configure { |c| c.contexts = nil }
 
-        described_class.override(contexts: { api: { tries: 1 } })
+        described_class.with_override(contexts: { api: { tries: 1 } }) do
+          described_class.with_context(:api) { increment_tries }
+        end
 
-        described_class.with_context(:api) { increment_tries }
         expect(@tries).to eq(1)
       ensure
         described_class.configure { |c| c.contexts = {} }
@@ -570,9 +580,10 @@ describe Retriable do
         c.contexts[:api] = { tries: 1 }
       end
 
-      described_class.override(contexts: nil)
+      described_class.with_override(contexts: nil) do
+        described_class.with_context(:api) { increment_tries }
+      end
 
-      described_class.with_context(:api) { increment_tries }
       expect(@tries).to eq(1)
     end
 
@@ -581,9 +592,10 @@ describe Retriable do
         c.contexts[:api] = { tries: 1 }
       end
 
-      described_class.override(contexts: 123)
+      described_class.with_override(contexts: 123) do
+        described_class.with_context(:api) { increment_tries }
+      end
 
-      described_class.with_context(:api) { increment_tries }
       expect(@tries).to eq(1)
     end
 
@@ -592,9 +604,10 @@ describe Retriable do
         c.contexts[:api] = { tries: 2 }
       end
 
-      described_class.override(contexts: { api: 123 })
+      described_class.with_override(contexts: { api: 123 }) do
+        expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      end
 
-      expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(2)
     end
 
@@ -603,10 +616,10 @@ describe Retriable do
         c.contexts[:configured] = { tries: 2 }
       end
 
-      described_class.override(contexts: { override_only: { tries: 1 } })
-
-      expect { described_class.with_context(:missing) { increment_tries } }
-        .to raise_error(ArgumentError, /override_only/)
+      described_class.with_override(contexts: { override_only: { tries: 1 } }) do
+        expect { described_class.with_context(:missing) { increment_tries } }
+          .to raise_error(ArgumentError, /override_only/)
+      end
     end
 
     it "does not snapshot configured contexts when adding override-only contexts" do
@@ -614,37 +627,200 @@ describe Retriable do
         c.contexts[:api] = { tries: 2 }
       end
 
-      described_class.override(contexts: { test_only: { tries: 1 } })
+      described_class.with_override(contexts: { test_only: { tries: 1 } }) do
+        described_class.configure do |c|
+          c.contexts[:api] = { tries: 5 }
+        end
 
-      described_class.configure do |c|
-        c.contexts[:api] = { tries: 5 }
+        expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
       end
 
-      expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(5)
     end
 
     it "raises ArgumentError on invalid override options" do
-      expect { described_class.override(does_not_exist: 123) }.to raise_error(ArgumentError)
+      expect { described_class.with_override(does_not_exist: 123) { :noop } }.to raise_error(ArgumentError)
     end
 
     it "raises ArgumentError on empty override options" do
-      expect { described_class.override({}) }.to raise_error(ArgumentError, /empty override/)
+      expect { described_class.with_override({}) { :noop } }.to raise_error(ArgumentError, /empty override/)
+    end
+
+    it "raises ArgumentError when called without a block" do
+      expect { described_class.with_override(tries: 1) }.to raise_error(ArgumentError, /requires a block/)
     end
 
     it "raises ArgumentError on invalid context override options" do
-      expect { described_class.override(contexts: { api: { does_not_exist: 123 } }) }
+      expect { described_class.with_override(contexts: { api: { does_not_exist: 123 } }) { :noop } }
         .to raise_error(ArgumentError, /does_not_exist is not a valid option/)
     end
 
-    it "does not copy the provided override options" do
-      opts = { tries: 1 }
-      described_class.override(opts)
+    it "clears the override after the block returns" do
+      described_class.with_override(tries: 1) do
+        # active here
+      end
+
+      expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(3)
+    end
 
-      opts[:tries] = 2
+    it "clears the override when the block raises" do
+      expect do
+        described_class.with_override(tries: 1) { raise "boom" }
+      end.to raise_error(RuntimeError, "boom")
 
-      expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }.to raise_error(StandardError)
-      expect(@tries).to eq(2)
+      expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(3)
+    end
+
+    it "returns the block's return value" do
+      result = described_class.with_override(tries: 1) { :return_value }
+      expect(result).to eq(:return_value)
+    end
+
+    it "restores the outer override when nested blocks exit" do
+      tries_seen = []
+      handler = ->(_exception, try, _elapsed, _next) { tries_seen << [Thread.current.object_id, try] }
+
+      described_class.with_override(tries: 2, on_retry: handler) do
+        described_class.with_override(tries: 4, on_retry: handler) do
+          expect { described_class.retriable { increment_tries_with_exception } }.to raise_error(StandardError)
+        end
+
+        # After the inner block exits, the outer tries: 2 override is restored.
+        @tries = 0
+        expect { described_class.retriable { increment_tries_with_exception } }.to raise_error(StandardError)
+        expect(@tries).to eq(2)
+      end
+    end
+  end
+
+  context "#with_override thread safety" do
+    # Coordinate threads with queues rather than sleep so tests are deterministic.
+    # sleep_disabled is already set to true in the top-level before(:each), so
+    # retriable calls do not actually sleep between attempts.
+
+    it "isolates overrides between threads" do
+      ready = Queue.new
+      proceed = Queue.new
+      results = {}
+      mutex = Mutex.new
+
+      threads = [1, 2].map do |id|
+        Thread.new do
+          described_class.with_override(tries: id) do
+            ready << true
+            proceed.pop
+            tries = 0
+            begin
+              described_class.retriable do
+                tries += 1
+                raise StandardError
+              end
+            rescue StandardError
+              mutex.synchronize { results[id] = tries }
+            end
+          end
+        end
+      end
+
+      2.times { ready.pop }
+      2.times { proceed << true }
+      threads.each(&:join)
+
+      expect(results).to eq(1 => 1, 2 => 2)
+    end
+
+    it "does not leak an active override into a sibling thread" do
+      override_active = Queue.new
+      sibling_done = Queue.new
+      sibling_tries = nil
+
+      setter = Thread.new do
+        described_class.with_override(tries: 1) do
+          override_active << true
+          sibling_done.pop
+        end
+      end
+
+      sibling = Thread.new do
+        override_active.pop
+        tries = 0
+        begin
+          described_class.retriable(tries: 3) do
+            tries += 1
+            raise StandardError
+          end
+        rescue StandardError
+          sibling_tries = tries
+        end
+        sibling_done << true
+      end
+
+      [setter, sibling].each(&:join)
+      expect(sibling_tries).to eq(3)
+    end
+
+    it "does not propagate an active override to a child thread" do
+      child_tries = nil
+
+      described_class.with_override(tries: 1) do
+        Thread.new do
+          tries = 0
+          begin
+            described_class.retriable(tries: 3) do
+              tries += 1
+              raise StandardError
+            end
+          rescue StandardError
+            child_tries = tries
+          end
+        end.join
+      end
+
+      expect(child_tries).to eq(3)
+    end
+
+    it "shares the active override with fibers in the same thread" do
+      fiber_tries = nil
+
+      Thread.new do
+        described_class.with_override(tries: 1) do
+          Fiber.new do
+            tries = 0
+            begin
+              described_class.retriable(tries: 10) do
+                tries += 1
+                raise StandardError
+              end
+            rescue StandardError
+              fiber_tries = tries
+            end
+          end.resume
+        end
+      end.join
+
+      expect(fiber_tries).to eq(1)
+    end
+
+    it "does not treat a main-thread override as a global default for other threads" do
+      other_thread_tries = nil
+
+      described_class.with_override(tries: 1) do
+        Thread.new do
+          tries = 0
+          begin
+            described_class.retriable(tries: 3) do
+              tries += 1
+              raise StandardError
+            end
+          rescue StandardError
+            other_thread_tries = tries
+          end
+        end.join
+      end
+
+      expect(other_thread_tries).to eq(3)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.5.1
+  version: 3.6.0
 platform: ruby
 authors:
 - Jack Chu
@@ -74,6 +74,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/testing.md
 - lib/retriable.rb
 - lib/retriable/config.rb
 - lib/retriable/core_ext/kernel.rb