retriable 3.4.1 → 4.1.1

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,17 +1,20 @@
 # 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
       intervals
-      timeout
       on
       retry_if
       on_retry
+      on_give_up
       contexts
     ]).freeze
 
@@ -28,10 +31,10 @@ module Retriable
       @sleep_disabled   = false
       @max_elapsed_time = 900 # 15 min
       @intervals        = nil
-      @timeout          = nil
       @on               = [StandardError]
       @retry_if         = nil
       @on_retry         = nil
+      @on_give_up       = nil
       @contexts         = {}
 
       opts.each do |k, v|
@@ -39,12 +42,61 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def to_h
-      ATTRIBUTES.each_with_object({}) do |key, hash|
-        hash[key] = public_send(key)
+      ATTRIBUTES.to_h { |key| [key, public_send(key)] }
+    end
+
+    def validate!
+      validate_callable(:retry_if, retry_if)
+      validate_callable(:on_retry, on_retry)
+      validate_callable(:on_give_up, on_give_up)
+      validate_on(on)
+      validate_intervals
+      if unbounded_tries?(tries)
+        validate_unbounded_tries
+      else
+        validate_optional_non_negative_number(:max_elapsed_time, max_elapsed_time)
+        return if intervals
+
+        validate_positive_integer(:tries, tries)
+      end
+
+      validate_backoff_options
+    end
+
+    private
+
+    def validate_backoff_options
+      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 validate_unbounded_tries
+      if intervals
+        raise ArgumentError,
+              "intervals cannot be used with tries: Float::INFINITY"
+      end
+
+      unless finite_number?(max_elapsed_time)
+        raise ArgumentError,
+              "max_elapsed_time must be a finite number when tries is Float::INFINITY"
       end
+
+      validate_non_negative_number(:max_elapsed_time, max_elapsed_time)
+    end
+
+    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/core_ext/kernel.rb

@@ -3,11 +3,11 @@
 require_relative "../../retriable"
 
 module Kernel
-  def retriable(opts = {}, &block)
-    Retriable.retriable(opts, &block)
+  def retriable(opts = {}, &)
+    Retriable.retriable(opts, &)
   end
 
-  def retriable_with_context(context_key, opts = {}, &block)
-    Retriable.with_context(context_key, opts, &block)
+  def retriable_with_context(context_key, opts = {}, &)
+    Retriable.with_context(context_key, opts, &)
   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,20 +28,42 @@ module Retriable
 
         instance_variable_set(:"@#{k}", v)
       end
+
+      validate!
     end
 
     def intervals
-      intervals = Array.new(tries) do |iteration|
-        [base_interval * (multiplier**iteration), max_interval].min
-      end
+      provider = interval_provider
+      Array.new(tries) { |iteration| provider.call(iteration) }
+    end
+
+    def interval_provider
+      raw_interval = base_interval
 
-      return intervals if rand_factor.zero?
+      lambda do |_iteration|
+        interval = [raw_interval, max_interval].min
+        raw_interval = next_raw_interval(raw_interval)
 
-      intervals.map { |i| randomize(i) }
+        rand_factor.zero? ? interval : randomize(interval)
+      end
     end
 
     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 next_raw_interval(raw_interval)
+      return max_interval if multiplier >= 1 && raw_interval >= max_interval
+
+      raw_interval * multiplier
+    end
+
     def randomize(interval)
       delta = rand_factor * interval.to_f
       min = interval - delta

data/lib/retriable/validation.rb

@@ -0,0 +1,95 @@
+# 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_callable(name, value)
+      return unless value # nil/false disable the callback
+      return if value.respond_to?(:call)
+
+      raise ArgumentError, "#{name} must respond to #call or be nil"
+    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
+
+    def unbounded_tries?(value)
+      value.is_a?(Numeric) && value.respond_to?(:infinite?) && value.infinite? == 1
+    end
+
+    module_function :unbounded_tries?
+
+    # Validates an `on:` value. Acceptable shapes:
+    #   - a Class that descends from Exception
+    #   - an Array or Set whose elements are Classes that descend from Exception
+    #   - a Hash whose keys are such Classes and whose values are nil,
+    #     a Regexp, or an Array of Regexps
+    #
+    # Without this validation, callers can pass values like `Object` or
+    # `Kernel` and silently retry process-critical exceptions such as
+    # SystemExit and Interrupt, because every Exception's ancestor chain
+    # includes both. Hash values that are not Regexps (e.g. plain Strings)
+    # also silently fail to match in #hash_exception_match?, so we require
+    # Regexp values explicitly.
+    def validate_on(value)
+      case value
+      in Hash
+        value.each do |klass, pattern|
+          validate_on_class(klass)
+          validate_on_hash_value(klass, pattern)
+        end
+      in Array | Set
+        value.each { |klass| validate_on_class(klass) }
+      else
+        validate_on_class(value)
+      end
+    end
+
+    def validate_on_class(klass)
+      return if klass.is_a?(Class) && klass <= Exception
+
+      raise ArgumentError, "on must be an Exception class or a collection of Exception classes, got #{klass.inspect}"
+    end
+
+    def validate_on_hash_value(klass, pattern)
+      return if pattern.nil?
+      return if pattern.is_a?(Regexp)
+      return if pattern.is_a?(Array) && pattern.all?(Regexp)
+
+      raise ArgumentError,
+            "on[#{klass}] must be nil, a Regexp, or an Array of Regexps, got #{pattern.inspect}"
+    end
+  end
+end

data/lib/retriable/version.rb

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