retriable 3.5.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfd17d793faa48456456036eee71083bf629041cfe6f3f673e3bc92ff0090a88
-  data.tar.gz: 27946e72249fce2362c2a374c8f352dd27bd8edd4ee3deea61c80e4d0da8f5cd
+  metadata.gz: 575fe838c7ddda74e7e26abf2a3b74a9e4b6866bf20d33a86bc59d1b7c45770d
+  data.tar.gz: f8d81648c9ea122680f3e8eb2f71b7cbbfffc0049313123da850378bf5b3f77d
 SHA512:
-  metadata.gz: 00424ca023aa864fd2a36016138d0dfd2a6a9030f64c7dd427bb296908b244847db139fcad208527f3bcb5cac075c5e0545fd5dd994f4fef48a31ef55baf2939
-  data.tar.gz: a414ecfe2931a0bf3fb56f831d654c497a5a1b4d37e4dbe1acf1cbd646083f15bbd85271afcf8f5b9b9f6c484c9f4c5b34ef462b35b2ffd7ec4371b50e7769ab
+  metadata.gz: bff5a1d9a0efec882841085a306290d11ccd9f20c0622b8a27c733c13981a68c681a562d80eb267c17b866a816a03d514a92b4a17883a1d4180d835f2b76fd02
+  data.tar.gz: 9da2cfea5cf807d352ed899926b0fa9e45d825935697788163dfbd5cf7c47afe7b0cfd7b20af5b29ce61f84d5d923181b7a671e21e3cafd709b15f922c68abf8

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.
+
 ## 3.5.0
 
 - Fix: Do not count skipped sleep intervals against `max_elapsed_time` when `sleep_disabled` is true.

data/README.md

@@ -32,7 +32,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.5'
+gem 'retriable', '~> 3.6'
 ```
 
 ## Usage
@@ -94,6 +94,8 @@ 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.
+
 #### Configuring Which Options to Retry With :on
 
 **`:on`** Can take the form:
@@ -147,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
 
@@ -367,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/config.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "exponential_backoff"
+require_relative "validation"
 
 module Retriable
   class Config
+    include Validation
+
     ATTRIBUTES = (ExponentialBackoff::ATTRIBUTES + %i[
       sleep_disabled
       max_elapsed_time
@@ -39,6 +42,8 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def to_h
@@ -46,5 +51,28 @@ module Retriable
         hash[key] = public_send(key)
       end
     end
+
+    def validate!
+      validate_optional_non_negative_number(:max_elapsed_time, max_elapsed_time)
+      validate_optional_non_negative_number(:timeout, timeout)
+      validate_intervals
+      return if intervals
+
+      validate_positive_integer(:tries, tries)
+      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_intervals
+      return if intervals.nil?
+      raise ArgumentError, "intervals must be an Array" unless intervals.is_a?(Array)
+      return if intervals.all? { |interval| finite_number?(interval) && interval >= 0 }
+
+      raise ArgumentError, "intervals must contain only non-negative numbers"
+    end
   end
 end

data/lib/retriable/exponential_backoff.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "validation"
+
 module Retriable
   class ExponentialBackoff
+    include Validation
+
     ATTRIBUTES = %i[
       tries
       base_interval
@@ -24,6 +28,8 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def intervals
@@ -38,6 +44,14 @@ module Retriable
 
     private
 
+    def validate!
+      validate_non_negative_integer(:tries, tries)
+      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
+
     def randomize(interval)
       delta = rand_factor * interval.to_f
       min = interval - delta

data/lib/retriable/validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Retriable
+  module Validation
+    private
+
+    def validate_positive_integer(name, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive integer"
+    end
+
+    def validate_non_negative_integer(name, value)
+      return if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative integer"
+    end
+
+    def validate_non_negative_number(name, value)
+      return if finite_number?(value) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative number"
+    end
+
+    def validate_optional_non_negative_number(name, value)
+      return if value.nil?
+
+      validate_non_negative_number(name, value)
+    end
+
+    def validate_rand_factor
+      return if finite_number?(rand_factor) && rand_factor >= 0 && rand_factor <= 1
+
+      raise ArgumentError, "rand_factor must be between 0 and 1"
+    end
+
+    def finite_number?(value)
+      value.is_a?(Numeric) && value.to_f.finite?
+    end
+  end
+end

data/lib/retriable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Retriable
-  VERSION = "3.5.0"
+  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,12 +52,16 @@ 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.
+    local_config.validate!
+
     tries = local_config.tries
     intervals = build_intervals(local_config, tries)
     timeout = local_config.timeout
@@ -196,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,
@@ -215,5 +235,6 @@ module Retriable
     :context_options_for,
     :config_contexts,
     :override_contexts,
+    :current_override,
   )
 end

data/spec/config_spec.rb

@@ -56,4 +56,13 @@ describe Retriable::Config do
   it "raises errors on invalid configuration" do
     expect { described_class.new(does_not_exist: 123) }.to raise_error(ArgumentError, /not a valid option/)
   end
+
+  it "raises errors on invalid timing configuration" do
+    expect { described_class.new(rand_factor: 1.1) }.to raise_error(ArgumentError, /rand_factor/)
+    expect { described_class.new(timeout: -1) }.to raise_error(ArgumentError, /timeout/)
+  end
+
+  it "raises errors when intervals is not an array" do
+    expect { described_class.new(intervals: "1") }.to raise_error(ArgumentError, /intervals must be an Array/)
+  end
 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 = {}
@@ -375,6 +375,37 @@ describe Retriable do
     it "raises ArgumentError on invalid options" do
       expect { described_class.retriable(does_not_exist: 123) { increment_tries } }.to raise_error(ArgumentError)
     end
+
+    it "raises ArgumentError when tries is not a positive integer" do
+      expect { described_class.retriable(tries: 1.5) { increment_tries } }
+        .to raise_error(ArgumentError, /tries/)
+    end
+
+    it "raises ArgumentError when an interval is negative" do
+      expect { described_class.retriable(intervals: [-1]) { increment_tries } }
+        .to raise_error(ArgumentError, /intervals/)
+    end
+
+    it "raises ArgumentError when configured timing options become invalid" do
+      described_class.configure { |config| config.tries = 0 }
+
+      expect { described_class.retriable { increment_tries } }
+        .to raise_error(ArgumentError, /tries/)
+    end
+
+    it "does not validate generated backoff options when intervals are provided" do
+      described_class.retriable(intervals: [0], tries: 0, rand_factor: 1.1) { increment_tries }
+
+      expect(@tries).to eq(1)
+    end
+
+    it "allows an empty interval array as one attempt" do
+      expect do
+        described_class.retriable(intervals: []) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(1)
+    end
   end
 
   context "#configure" do
@@ -384,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)
@@ -396,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
@@ -423,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
 
@@ -433,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)
@@ -468,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
 
@@ -492,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
 
@@ -515,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
 
@@ -525,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 = {} }
@@ -539,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
 
@@ -550,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
 
@@ -561,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
 
@@ -572,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
@@ -583,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
 
-      opts[:tries] = 2
+      expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(3)
+    end
 
-      expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }.to raise_error(StandardError)
-      expect(@tries).to eq(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: 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.0
+  version: 3.6.0
 platform: ruby
 authors:
 - Jack Chu
@@ -74,10 +74,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/testing.md
 - lib/retriable.rb
 - lib/retriable/config.rb
 - lib/retriable/core_ext/kernel.rb
 - lib/retriable/exponential_backoff.rb
+- lib/retriable/validation.rb
 - lib/retriable/version.rb
 - retriable.gemspec
 - sig/retriable.rbs