retriable 3.4.1 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86086d1d868b9f609e96d2b5e8e5f6e5910a9822b7c21dd86a4014a12105d7f3
-  data.tar.gz: a7324a228f6b0565428cb10afe6ecf3a98b7a6984ced4f83c32595f97767b09b
+  metadata.gz: cfd17d793faa48456456036eee71083bf629041cfe6f3f673e3bc92ff0090a88
+  data.tar.gz: 27946e72249fce2362c2a374c8f352dd27bd8edd4ee3deea61c80e4d0da8f5cd
 SHA512:
-  metadata.gz: fc0f71e125a40e52fdb8e4cb99b71b066fc84a067e9011b166a14d08a9f98f20a15a32402818705172275ea8b0a0f814963265eabba9fcae6d7ac40cdfc9e520
-  data.tar.gz: d13f82d53fdc1c2be693a056fd4d164cddc4a7b34096c6c7367213f899881687854a3df5a20a07ad3678c3aa257297bd42a68cb36e9cf0718a2fa8be54a3bd56
+  metadata.gz: 00424ca023aa864fd2a36016138d0dfd2a6a9030f64c7dd427bb296908b244847db139fcad208527f3bcb5cac075c5e0545fd5dd994f4fef48a31ef55baf2939
+  data.tar.gz: a414ecfe2931a0bf3fb56f831d654c497a5a1b4d37e4dbe1acf1cbd646083f15bbd85271afcf8f5b9b9f6c484c9f4c5b34ef462b35b2ffd7ec4371b50e7769ab

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,10 @@
 # HEAD
 
+## 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
@@ -142,6 +142,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 +371,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 +417,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/version.rb

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

data/lib/retriable.rb

@@ -16,19 +16,36 @@ 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
 
     tries = local_config.tries
     intervals = build_intervals(local_config, tries)
@@ -69,7 +86,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 +146,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 +210,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/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 }
@@ -359,6 +384,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 +396,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 +664,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.0
 platform: ruby
 authors:
 - Jack Chu