retriable 3.5.0 → 4.2.0

data/sig/retriable.rbs

@@ -1,4 +1,32 @@
 module Retriable
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  OVERRIDE_THREAD_KEY: Symbol
+
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
+  def self.with_override: (Hash[Symbol, untyped] options) { () -> untyped } -> untyped
+  def self.with_context: (Symbol context_key, ?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
+  def self.retriable: (?Hash[Symbol, untyped] options) { (Integer) -> untyped } -> untyped
+
+  class Config
+    ATTRIBUTES: Array[Symbol]
+
+    attr_accessor tries: Numeric
+    attr_accessor base_interval: Numeric
+    attr_accessor max_interval: Numeric
+    attr_accessor rand_factor: Numeric
+    attr_accessor multiplier: Numeric
+    attr_accessor sleep_disabled: bool
+    attr_accessor max_elapsed_time: Numeric?
+    attr_accessor intervals: Array[Numeric]?
+    attr_accessor on: untyped
+    attr_accessor retry_if: untyped
+    attr_accessor on_retry: untyped
+    attr_accessor on_give_up: untyped
+    attr_accessor contexts: Hash[Symbol, untyped]
+
+    def initialize: (?Hash[Symbol, untyped] opts) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def validate!: () -> void
+  end
 end

data/spec/config_spec.rb

@@ -32,10 +32,6 @@ describe Retriable::Config do
       expect(default_config.intervals).to be_nil
     end
 
-    it "timeout defaults to nil" do
-      expect(default_config.timeout).to be_nil
-    end
-
     it "on defaults to [StandardError]" do
       expect(default_config.on).to eq([StandardError])
     end
@@ -48,6 +44,10 @@ describe Retriable::Config do
       expect(default_config.on_retry).to be_nil
     end
 
+    it "on_give_up handler defaults to nil" do
+      expect(default_config.on_give_up).to be_nil
+    end
+
     it "contexts defaults to {}" do
       expect(default_config.contexts).to eq({})
     end
@@ -56,4 +56,157 @@ 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 "rejects timeout as an unknown option" do
+    expect { described_class.new(timeout: 5) }.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/)
+  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
+
+  it "requires a finite max_elapsed_time when tries is Float::INFINITY" do
+    expect { described_class.new(tries: Float::INFINITY, max_elapsed_time: nil) }
+      .to raise_error(ArgumentError, /max_elapsed_time must be a finite number/)
+  end
+
+  it "rejects intervals combined with tries: Float::INFINITY" do
+    expect do
+      described_class.new(
+        tries: Float::INFINITY,
+        max_elapsed_time: 60,
+        intervals: [0.1, 0.2],
+      )
+    end.to raise_error(ArgumentError, /intervals cannot be used with tries: Float::INFINITY/)
+  end
+
+  it "accepts tries: Float::INFINITY with a finite max_elapsed_time" do
+    expect { described_class.new(tries: Float::INFINITY, max_elapsed_time: 60) }
+      .not_to raise_error
+  end
+
+  context "on: option validation" do
+    it "accepts a single Exception subclass" do
+      expect { described_class.new(on: StandardError) }.not_to raise_error
+    end
+
+    it "accepts Exception itself" do
+      expect { described_class.new(on: Exception) }.not_to raise_error
+    end
+
+    it "accepts an array of Exception subclasses" do
+      expect { described_class.new(on: [StandardError, RuntimeError]) }.not_to raise_error
+    end
+
+    it "accepts a Set of Exception subclasses" do
+      expect { described_class.new(on: Set[StandardError, RuntimeError]) }.not_to raise_error
+    end
+
+    it "rejects a Set containing a non-Exception class" do
+      expect { described_class.new(on: Set[StandardError, Kernel]) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "accepts a hash with nil pattern values" do
+      expect { described_class.new(on: { StandardError => nil }) }.not_to raise_error
+    end
+
+    it "accepts a hash with Regexp pattern values" do
+      expect { described_class.new(on: { StandardError => /boom/ }) }.not_to raise_error
+    end
+
+    it "accepts a hash with Array-of-Regexp pattern values" do
+      expect { described_class.new(on: { StandardError => [/a/, /b/] }) }.not_to raise_error
+    end
+
+    it "rejects Object as on:" do
+      expect { described_class.new(on: Object) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects Kernel as on:" do
+      expect { described_class.new(on: Kernel) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects an array containing a non-Exception class" do
+      expect { described_class.new(on: [StandardError, Kernel]) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects a hash key that is not an Exception class" do
+      expect { described_class.new(on: { Kernel => nil }) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "rejects a hash value that is a String" do
+      expect { described_class.new(on: { StandardError => "boom" }) }
+        .to raise_error(ArgumentError, /on\[StandardError\] must be nil, a Regexp, or an Array of Regexps/)
+    end
+
+    it "rejects a hash value that is an Array containing a non-Regexp" do
+      expect { described_class.new(on: { StandardError => [/a/, "b"] }) }
+        .to raise_error(ArgumentError, /on\[StandardError\] must be nil, a Regexp, or an Array of Regexps/)
+    end
+
+    it "rejects a string passed as on:" do
+      expect { described_class.new(on: "StandardError") }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+
+    it "validates on: even when intervals is provided" do
+      expect { described_class.new(intervals: [0.1], on: Object) }
+        .to raise_error(ArgumentError, /on must be an Exception class/)
+    end
+  end
+
+  context "callable option validation" do
+    %i[retry_if on_retry on_give_up].each do |opt|
+      it "accepts a callable for #{opt}" do
+        expect { described_class.new(opt => ->(*) {}) }.not_to raise_error
+      end
+
+      it "accepts nil and false for #{opt}" do
+        expect { described_class.new(opt => nil) }.not_to raise_error
+        expect { described_class.new(opt => false) }.not_to raise_error
+      end
+
+      it "rejects a non-callable truthy value for #{opt}" do
+        expect { described_class.new(opt => 5) }.to raise_error(ArgumentError, /#{opt}.*#call/)
+      end
+    end
+  end
+
+  context "context structure validation" do
+    it "rejects a context whose options contain a nested :contexts key" do
+      expect { described_class.new(contexts: { api: { contexts: {} } }) }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
+    it "rejects a context with an unknown option key" do
+      expect { described_class.new(contexts: { api: { does_not_exist: 1 } }) }
+        .to raise_error(ArgumentError, /does_not_exist is not a valid option/)
+    end
+
+    it "validates context structure even when intervals is provided" do
+      expect { described_class.new(intervals: [0.1], contexts: { api: { contexts: {} } }) }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
+    it "accepts a non-Hash context value (treated as empty options)" do
+      expect { described_class.new(contexts: { broken: nil }) }.not_to raise_error
+    end
+
+    it "accepts nil contexts" do
+      expect { described_class.new(contexts: nil) }.not_to raise_error
+    end
+
+    it "accepts a valid context" do
+      expect { described_class.new(contexts: { api: { tries: 3, base_interval: 1.0 } }) }.not_to raise_error
+    end
+  end
 end

data/spec/exponential_backoff_spec.rb

@@ -22,17 +22,19 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates 10 randomized intervals" do
-    expect(described_class.new(tries: 9).intervals).to eq([
-      0.5244067512211441,
-      0.9113920238761231,
-      1.2406087918999114,
-      1.7632403621664823,
-      2.338001204738311,
-      4.350816718580626,
-      5.339852157217869,
-      11.889873261212443,
-      18.756037881636484,
-    ])
+    expect(described_class.new(tries: 9).intervals).to eq(
+      [
+        0.5244067512211441,
+        0.9113920238761231,
+        1.2406087918999114,
+        1.7632403621664823,
+        2.338001204738311,
+        4.350816718580626,
+        5.339852157217869,
+        11.889873261212443,
+        18.756037881636484,
+      ],
+    )
   end
 
   it "generates defined number of intervals" do
@@ -40,19 +42,23 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates intervals with a defined base interval" do
-    expect(described_class.new(base_interval: 1).intervals).to eq([
-      1.0488135024422882,
-      1.8227840477522461,
-      2.4812175837998227,
-    ])
+    expect(described_class.new(base_interval: 1).intervals).to eq(
+      [
+        1.0488135024422882,
+        1.8227840477522461,
+        2.4812175837998227,
+      ],
+    )
   end
 
   it "generates intervals with a defined multiplier" do
-    expect(described_class.new(multiplier: 1).intervals).to eq([
-      0.5244067512211441,
-      0.607594682584082,
-      0.5513816852888495,
-    ])
+    expect(described_class.new(multiplier: 1).intervals).to eq(
+      [
+        0.5244067512211441,
+        0.607594682584082,
+        0.5513816852888495,
+      ],
+    )
   end
 
   it "generates intervals with a defined max interval" do
@@ -60,15 +66,28 @@ describe Retriable::ExponentialBackoff do
   end
 
   it "generates intervals with a defined rand_factor" do
-    expect(described_class.new(rand_factor: 0.2).intervals).to eq([
-      0.5097627004884576,
-      0.8145568095504492,
-      1.1712435167599646,
-    ])
+    expect(described_class.new(rand_factor: 0.2).intervals).to eq(
+      [
+        0.5097627004884576,
+        0.8145568095504492,
+        1.1712435167599646,
+      ],
+    )
   end
 
   it "generates 10 non-randomized intervals" do
     non_random_intervals = 9.times.inject([0.5]) { |memo, _i| memo + [memo.last * 1.5] }
     expect(described_class.new(tries: 10, rand_factor: 0.0).intervals).to eq(non_random_intervals)
   end
+
+  it "provides capped intervals lazily" do
+    interval_for = described_class.new(
+      base_interval: 1.0,
+      multiplier: 2.0,
+      max_interval: 4.0,
+      rand_factor: 0.0,
+    ).interval_provider
+
+    expect(Array.new(5) { |index| interval_for.call(index) }).to eq([1.0, 2.0, 4.0, 4.0, 4.0])
+  end
 end