retriable 3.4.1 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86086d1d868b9f609e96d2b5e8e5f6e5910a9822b7c21dd86a4014a12105d7f3
-  data.tar.gz: a7324a228f6b0565428cb10afe6ecf3a98b7a6984ced4f83c32595f97767b09b
+  metadata.gz: b0cb0bb3751f465d22addceebf5466b165871741e5820c7c3291d2e842f6f48a
+  data.tar.gz: 8bef0641e9c3b0e39c04d79ffcbdaf4542790264ce6648f6540db933cfddbc54
 SHA512:
-  metadata.gz: fc0f71e125a40e52fdb8e4cb99b71b066fc84a067e9011b166a14d08a9f98f20a15a32402818705172275ea8b0a0f814963265eabba9fcae6d7ac40cdfc9e520
-  data.tar.gz: d13f82d53fdc1c2be693a056fd4d164cddc4a7b34096c6c7367213f899881687854a3df5a20a07ad3678c3aa257297bd42a68cb36e9cf0718a2fa8be54a3bd56
+  metadata.gz: 6c4e07023a30aa934d5397717344c480fb6af8dd56349fcbcb9b85b9ba5539a3f16d2b16a30cbb3682e4140a04f3ace9ecbf0602e68bc4a1a5c805230a031de6
+  data.tar.gz: 4272451f1213b81537fd8f7cd85ced8a341b8f8dbf228493a42393b74cee3400e90eb9aa466ec3e404b98eef78b2a42ade5600b49c5d8d9ba7dd9e9b4ae1f444

data/.github/workflows/main.yml

@@ -7,6 +7,9 @@ on:
     branches: [main]
     types: [opened, synchronize, reopened]
 
+permissions:
+  contents: read
+
 jobs:
   ci:
     # The type of runner that the job will run on
@@ -34,10 +37,10 @@ jobs:
 
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Setup ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # HEAD
 
+## 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.
+- Add `override` and `reset_override` APIs to force retry settings over local call options when needed (for example, test short-circuiting).
+
 ## 3.4.1
 
 - Fix: Use `Process.clock_gettime(CLOCK_MONOTONIC)` for elapsed time tracking so retry timing is immune to wall-clock adjustments (NTP, manual changes).

data/README.md

@@ -32,7 +32,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.4'
+gem 'retriable', '~> 3.5'
 ```
 
 ## 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:
@@ -142,6 +144,37 @@ Retriable.configure do |c|
 end
 ```
 
+`#configure` sets defaults only. Per-call options passed to `Retriable.retriable` and
+`Retriable.with_context` still take precedence.
+
+### Override
+
+If you need to force values globally (including over per-call options), use
+`#override`:
+
+```ruby
+Retriable.override(tries: 1, base_interval: 0)
+```
+
+`#override` precedence:
+
+```
+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.
+
+`#override` stores the provided options directly. Do not mutate the options hash
+or nested values after passing them to `#override`.
+
+To clear an override:
+
+```ruby
+Retriable.reset_override
+```
+
 ### Example Usage
 
 This example will only retry on a `Timeout::Error`, retry 3 times and sleep for a full second before each try.
@@ -340,33 +373,33 @@ end
 
 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.
 
-You can disable retrying by setting `tries` to 1 in the test environment. If you want to test that the code is retrying an error, you want to [turn off exponential backoff](#turn-off-exponential-backoff).
+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, you could change your initializer to have different options in test, as follows:
+Under Rails, keep shared defaults in `Retriable.configure` and apply test-only overrides conditionally:
 
 ```ruby
 # config/initializers/retriable.rb
 Retriable.configure do |c|
-  # ... default configuration
+  c.tries = 3
+  c.base_interval = 0.5
+  c.rand_factor = 0.5
+end
 
-  if Rails.env.test?
-    c.tries = 1
-  end
+if Rails.env.test?
+  Retriable.override(tries: 1, base_interval: 0, rand_factor: 0)
 end
 ```
 
-Note: In this and the following examples, `Retriable.configure` sets a default config, it doesn't override the configuration for the `retriable` method calls. Calling `Retriable.retriable` with options will override the default configuration for that call. So if you have `tries` set to 5 in `Retriable.configure`, but then you call `Retriable.retriable(tries: 3)`, that call will use 3 tries instead of 5. The configuration is basically a default set of options that can be overridden by passing options to the `retriable` method or by using contexts.
+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 confguration in your `spec_helper`.
+Alternately, if you are using RSpec, you could override the Retriable configuration in your `spec_helper`.
 
 ```ruby
 # spec/spec_helper.rb
-Retriable.configure do |c|
-  c.tries = 1
-end
+Retriable.override(tries: 1, base_interval: 0, rand_factor: 0)
 ```
 
-If you have defined contexts for your configuration, you'll need to change values for each context, because those values take precedence over the default configured value.
+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:
 
@@ -386,20 +419,21 @@ Retriable.configure do |c|
 end
 ```
 
-Then in your test environment, you would need to set each context and the default value:
+Then in your test environment, you can override both top-level defaults and per-context options:
 
 ```ruby
-# spec/spec_helper.rb
-Retriable.configure do |c|
-  c.multiplier    = 1.0
-  c.rand_factor   = 0.0
-  c.base_interval = 0
-
-  c.contexts.keys.each do |context|
-    c.contexts[context][:tries]         = 1
-    c.contexts[context][:base_interval] = 0
-  end
+# 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,
+)
 ```
 
 ## Credits

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.4.1"
+  VERSION = "3.5.1"
 end

data/lib/retriable.rb

@@ -16,19 +16,39 @@ module Retriable
     @config ||= Config.new
   end
 
+  def override(opts = {})
+    raise ArgumentError, "empty override options are not allowed; use reset_override instead" if opts.empty?
+
+    validate_override_options(opts)
+    @override_config = opts
+  end
+
+  def reset_override
+    @override_config = nil
+  end
+
   def with_context(context_key, options = {}, &block)
-    if !config.contexts.key?(context_key)
+    contexts = available_contexts
+
+    if !contexts.key?(context_key)
       raise ArgumentError,
-            "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
+            "#{context_key} not found in Retriable contexts (including overrides). Available contexts: #{contexts.keys}"
     end
 
     return unless block_given?
 
-    retriable(config.contexts[context_key].merge(options), &block)
+    retriable(context_options_for(context_key, options), &block)
   end
 
   def retriable(opts = {}, &block)
-    local_config = opts.empty? ? config : Config.new(config.to_h.merge(opts))
+    local_config = if opts.empty? && !@override_config
+                     config
+                   else
+                     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)
@@ -69,7 +89,8 @@ module Retriable
         interval = intervals[index]
         call_on_retry(on_retry, e, try, elapsed_time.call, interval)
 
-        raise unless can_retry?(try, tries, elapsed_time.call, interval, max_elapsed_time)
+        elapsed_interval = sleep_disabled == true ? 0 : interval
+        raise unless can_retry?(try, tries, elapsed_time.call, elapsed_interval, max_elapsed_time)
 
         sleep interval if sleep_disabled != true
       end
@@ -128,7 +149,63 @@ module Retriable
     end
   end
 
+  def validate_override_options(opts)
+    opts.each_key do |k|
+      raise ArgumentError, "#{k} is not a valid option" unless Config::ATTRIBUTES.include?(k)
+    end
+
+    contexts = opts[:contexts]
+    return unless contexts.is_a?(Hash)
+
+    contexts.each_value do |context_options|
+      validate_context_override_options(context_options)
+    end
+  end
+
+  def validate_context_override_options(context_options)
+    return unless context_options.is_a?(Hash)
+
+    context_attributes = Config::ATTRIBUTES - [:contexts]
+    context_options.each_key do |k|
+      raise ArgumentError, "#{k} is not a valid option" unless context_attributes.include?(k)
+    end
+  end
+
+  def apply_override_options(options, overrides)
+    return options unless overrides
+
+    options = options.merge(overrides)
+    options[:intervals] = nil if overrides.key?(:tries) && !overrides.key?(:intervals)
+    options
+  end
+
+  def available_contexts
+    config_contexts.merge(override_contexts)
+  end
+
+  def context_options_for(context_key, options)
+    context_options = config_contexts.fetch(context_key, {})
+    context_options = {} unless context_options.is_a?(Hash)
+    context_options = context_options.merge(options)
+
+    override_context_options = override_contexts[context_key]
+    return context_options unless override_context_options.is_a?(Hash)
+
+    apply_override_options(context_options, override_context_options)
+  end
+
+  def config_contexts
+    config.contexts.is_a?(Hash) ? config.contexts : {}
+  end
+
+  def override_contexts
+    contexts = @override_config && @override_config[:contexts]
+    contexts.is_a?(Hash) ? contexts : {}
+  end
+
   private_class_method(
+    :validate_override_options,
+    :validate_context_override_options,
     :execute_tries,
     :build_intervals,
     :call_with_timeout,
@@ -136,5 +213,10 @@ module Retriable
     :can_retry?,
     :retriable_exception?,
     :hash_exception_match?,
+    :apply_override_options,
+    :available_contexts,
+    :context_options_for,
+    :config_contexts,
+    :override_contexts,
   )
 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

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require "rbconfig"
+
 describe Retriable do
   let(:time_table_handler) do
     ->(_exception, try, _elapsed_time, next_interval) { @next_interval_table[try] = next_interval }
   end
 
   before(:each) do
+    described_class.instance_variable_set(:@config, nil)
+    described_class.reset_override
     described_class.configure { |c| c.sleep_disabled = true }
     @tries = 0
     @next_interval_table = {}
@@ -23,7 +27,9 @@ describe Retriable do
 
   context "global scope extension" do
     it "cannot be called in the global scope without requiring the core_ext/kernel" do
-      expect { retriable { puts "should raise NoMethodError" } }.to raise_error(NoMethodError)
+      script = "require 'retriable'; begin; retriable {}; rescue NoMethodError; exit 0; end; exit 1"
+
+      expect(system(RbConfig.ruby, "-Ilib", "-e", script)).to be(true)
     end
 
     it "can be called once the kernel extension is required" do
@@ -35,6 +41,13 @@ describe Retriable do
   end
 
   context "#retriable" do
+    it "reuses the singleton config when no local options or overrides are provided" do
+      expect(described_class::Config).not_to receive(:new)
+
+      described_class.retriable { increment_tries }
+      expect(@tries).to eq(1)
+    end
+
     it "raises a LocalJumpError if not given a block" do
       expect { described_class.retriable }.to raise_error(LocalJumpError)
       expect { described_class.retriable(timeout: 2) }.to raise_error(LocalJumpError)
@@ -315,6 +328,18 @@ describe Retriable do
       expect(@tries).to eq(2)
     end
 
+    it "does not count skipped sleep intervals against max elapsed time" do
+      allow(Process).to receive(:clock_gettime).with(Process::CLOCK_MONOTONIC).and_return(0.0)
+
+      expect do
+        described_class.retriable(tries: 3, base_interval: 1.0, rand_factor: 0.0, max_elapsed_time: 0.1) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(3)
+    end
+
     it "retries up to tries limit when max_elapsed_time is nil" do
       expect do
         described_class.retriable(tries: 4, max_elapsed_time: nil) { increment_tries_with_exception }
@@ -350,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
@@ -359,6 +415,8 @@ describe Retriable do
         with_context
         configure
         config
+        override
+        reset_override
       ]
 
       expect(described_class.singleton_methods(false)).to match_array(public_api_methods)
@@ -369,6 +427,227 @@ describe Retriable do
     end
   end
 
+  context "#override" do
+    after(:each) do
+      described_class.reset_override
+    end
+
+    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)
+      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)
+
+      expect(@tries).to eq(1)
+    end
+
+    it "lets override tries take precedence over context intervals" 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)
+      expect(@tries).to eq(1)
+    end
+
+    it "lets override context tries take precedence over context intervals" 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)
+      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)
+
+      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)
+
+      expect(@tries).to eq(3)
+      expect(@next_interval_table[1]).to be_between(0.0, 1.0)
+    end
+
+    it "applies override context values after with_context local options" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 3, base_interval: 1.0 }
+      end
+
+      described_class.override(contexts: { api: { tries: 1 } })
+
+      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_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 } })
+
+      expect { described_class.retriable(tries: 3) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(3)
+    end
+
+    it "keeps configured context matchers when top-level override values apply" 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)
+      expect(@tries).to eq(1)
+    end
+
+    it "combines local options with override-only contexts" do
+      described_class.override(contexts: { api: { tries: 1 } })
+
+      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
+
+    it "reuses configured contexts when override does not include contexts" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 1 }
+      end
+
+      described_class.override(tries: 1)
+
+      described_class.with_context(:api) { increment_tries }
+      expect(@tries).to eq(1)
+    end
+
+    it "treats non-hash configured contexts as empty when override contexts are hash" do
+      begin
+        described_class.configure { |c| c.contexts = nil }
+
+        described_class.override(contexts: { api: { tries: 1 } })
+
+        described_class.with_context(:api) { increment_tries }
+        expect(@tries).to eq(1)
+      ensure
+        described_class.configure { |c| c.contexts = {} }
+      end
+    end
+
+    it "ignores nil override contexts values in with_context" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 1 }
+      end
+
+      described_class.override(contexts: nil)
+
+      described_class.with_context(:api) { increment_tries }
+      expect(@tries).to eq(1)
+    end
+
+    it "ignores non-hash override contexts values in with_context" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 1 }
+      end
+
+      described_class.override(contexts: 123)
+
+      described_class.with_context(:api) { increment_tries }
+      expect(@tries).to eq(1)
+    end
+
+    it "ignores non-hash per-context override values in with_context" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 2 }
+      end
+
+      described_class.override(contexts: { api: 123 })
+
+      expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(2)
+    end
+
+    it "shows merged context keys in with_context missing-context errors" do
+      described_class.configure do |c|
+        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/)
+    end
+
+    it "does not snapshot configured contexts when adding override-only contexts" do
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 2 }
+      end
+
+      described_class.override(contexts: { test_only: { tries: 1 } })
+
+      described_class.configure do |c|
+        c.contexts[:api] = { tries: 5 }
+      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)
+    end
+
+    it "raises ArgumentError on empty override options" do
+      expect { described_class.override({}) }.to raise_error(ArgumentError, /empty override/)
+    end
+
+    it "raises ArgumentError on invalid context override options" do
+      expect { described_class.override(contexts: { api: { does_not_exist: 123 } }) }
+        .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)
+
+      opts[:tries] = 2
+
+      expect { described_class.retriable(tries: 10) { increment_tries_with_exception } }.to raise_error(StandardError)
+      expect(@tries).to eq(2)
+    end
+  end
+
   context "#with_context" do
     let(:api_tries) { 4 }
 
@@ -416,5 +695,14 @@ describe Retriable do
     it "raises an ArgumentError when the context isn't found" do
       expect { described_class.with_context(:wtf) { increment_tries } }.to raise_error(ArgumentError, /wtf not found/)
     end
+
+    it "treats non-Hash context values as empty options" do
+      described_class.configure do |c|
+        c.contexts[:broken] = nil
+      end
+
+      described_class.with_context(:broken) { increment_tries }
+      expect(@tries).to eq(1)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.4.1
+  version: 3.5.1
 platform: ruby
 authors:
 - Jack Chu
@@ -78,6 +78,7 @@ files:
 - 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