retriable 3.8.0 → 4.2.0

data/spec/retriable_spec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "rbconfig"
-require "stringio"
 
 describe Retriable do
   let(:time_table_handler) do
@@ -39,6 +38,49 @@ describe Retriable do
       expect { retriable { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(3)
     end
+
+    it "passes on_give_up through the kernel extension" do
+      require_relative "../lib/retriable/core_ext/kernel"
+      received_reason = nil
+      handler = proc { |_e, _try, _elapsed, _interval, reason| received_reason = reason }
+
+      expect { retriable(tries: 1, on_give_up: handler) { increment_tries_with_exception } }
+        .to raise_error(StandardError)
+
+      expect(received_reason).to eq(:tries_exhausted)
+    end
+
+    # These two specs lock in the anonymous block forwarding (`&`) semantics
+    # across both delegation layers: Kernel#retriable_with_context ->
+    # Retriable.with_context. If the `&` is dropped at either layer, the block
+    # is not forwarded and the `block_given?` guard in with_context raises
+    # ArgumentError instead of running the block.
+    it "forwards a block through Kernel#retriable_with_context" do
+      require_relative "../lib/retriable/core_ext/kernel"
+      Retriable.configure { |c| c.contexts[:sql] = { tries: 1 } }
+
+      retriable_with_context(:sql) { increment_tries }
+
+      expect(@tries).to eq(1)
+    end
+
+    it "raises an ArgumentError when Kernel#retriable_with_context is called without a block" do
+      require_relative "../lib/retriable/core_ext/kernel"
+      Retriable.configure { |c| c.contexts[:sql] = { tries: 1 } }
+
+      expect { retriable_with_context(:sql) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
+      expect(@tries).to eq(0)
+    end
+
+    it "is not callable with an explicit receiver" do
+      require_relative "../lib/retriable/core_ext/kernel"
+
+      expect { "foo".retriable { increment_tries } }
+        .to raise_error(NoMethodError, /private method/)
+      expect { "foo".retriable_with_context(:sql) { increment_tries } }
+        .to raise_error(NoMethodError, /private method/)
+    end
   end
 
   context "#retriable" do
@@ -51,9 +93,6 @@ describe Retriable do
 
     it "raises a LocalJumpError if not given a block" do
       expect { described_class.retriable }.to raise_error(LocalJumpError)
-      expect do
-        expect { described_class.retriable(timeout: 2) }.to raise_error(LocalJumpError)
-      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
     end
 
     it "stops at first try if the block does not raise an exception" do
@@ -171,86 +210,8 @@ describe Retriable do
       end.to raise_error(ArgumentError, /tries/)
     end
 
-    it "will timeout after 1 second" do
-      expect do
-        expect { described_class.retriable(timeout: 1) { sleep(1.1) } }.to raise_error(Timeout::Error)
-      end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-    end
-
-    context "timeout: deprecation" do
-      it "warns at most once per process across repeated retriable calls" do
-        original_stderr = $stderr
-        stderr = StringIO.new
-        begin
-          $stderr = stderr
-
-          described_class.retriable(timeout: 5) { :noop }
-          described_class.retriable(timeout: 5) { :noop }
-          described_class.retriable(timeout: 5) { :noop }
-
-          expect(stderr.string.scan("timeout:` option is deprecated").size).to eq(1)
-        ensure
-          $stderr = original_stderr
-        end
-      end
-
-      it "warns when timeout is passed to retriable" do
-        expect do
-          described_class.retriable(timeout: 5) { :noop }
-        end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-      end
-
-      it "keeps applying timeout while deprecated" do
-        original_stderr = $stderr
-        begin
-          $stderr = StringIO.new
-          expect do
-            described_class.retriable(timeout: 0.05, tries: 1) { sleep(0.5) }
-          end.to raise_error(Timeout::Error)
-        ensure
-          $stderr = original_stderr
-        end
-      end
-
-      it "warns when timeout is supplied through with_override" do
-        expect do
-          described_class.with_override(timeout: 5) do
-            described_class.retriable { :noop }
-          end
-        end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-      end
-
-      it "warns when timeout is supplied through configure" do
-        original_config = described_class.config
-        begin
-          expect do
-            described_class.configure { |config| config.timeout = 5 }
-            described_class.retriable { :noop }
-          end.to output(/timeout.*deprecated.*Retriable 4\.0/i).to_stderr
-        ensure
-          described_class.configure do |config|
-            original_config.to_h.each { |key, value| config.public_send("#{key}=", value) }
-          end
-        end
-      end
-
-      it "is silenced by Warning[:deprecated] = false", if: WARN_CATEGORY_SUPPORTED do
-        original = Warning[:deprecated]
-        begin
-          Warning[:deprecated] = false
-          expect do
-            described_class.retriable(timeout: 5) { :noop }
-          end.not_to output.to_stderr
-        ensure
-          Warning[:deprecated] = original
-        end
-      end
-
-      it "does not warn when timeout is absent" do
-        expect do
-          described_class.retriable { :noop }
-        end.not_to output.to_stderr
-      end
+    it "rejects timeout as an unknown option" do
+      expect { described_class.retriable(timeout: 1) { :noop } }.to raise_error(ArgumentError, /not a valid option/)
     end
 
     it "applies a randomized exponential backoff to each try" do
@@ -296,6 +257,187 @@ describe Retriable do
       end
     end
 
+    it "does not call on_retry when explicitly set to nil" do
+      callback_called = false
+      original_on_retry = described_class.config.on_retry
+
+      begin
+        described_class.configure do |c|
+          c.on_retry = proc { |_exception, _try, _elapsed_time, _next_interval| callback_called = true }
+        end
+
+        expect do
+          described_class.retriable(on_retry: nil, tries: 3) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+
+        expect(@tries).to eq(3)
+        expect(callback_called).to be(false)
+      ensure
+        described_class.configure do |c|
+          c.on_retry = original_on_retry
+        end
+      end
+    end
+
+    it "calls on_give_up with max elapsed time details before re-raising" do
+      described_class.configure { |c| c.sleep_disabled = false }
+      give_up_calls = []
+      on_give_up = proc do |exception, try, elapsed_time, next_interval, reason|
+        give_up_calls << [exception, try, elapsed_time, next_interval, reason]
+      end
+
+      expect do
+        described_class.retriable(
+          intervals: [1.0, 1.0],
+          max_elapsed_time: 0.5,
+          on_give_up: on_give_up,
+        ) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(StandardError)
+
+      exception, try, elapsed_time, next_interval, reason = give_up_calls.fetch(0)
+      expect(give_up_calls.size).to eq(1)
+      expect(exception).to be_a(StandardError)
+      expect(exception.message).to eq("StandardError occurred")
+      expect(try).to eq(1)
+      expect(elapsed_time).to be >= 0
+      expect(next_interval).to eq(1.0)
+      expect(reason).to eq(:max_elapsed_time)
+      expect(@tries).to eq(1)
+    end
+
+    it "calls on_give_up with tries exhausted details before re-raising" do
+      give_up_calls = []
+      on_give_up = proc do |exception, try, elapsed_time, next_interval, reason|
+        give_up_calls << [exception, try, elapsed_time, next_interval, reason]
+      end
+
+      expect do
+        described_class.retriable(tries: 2, on_give_up: on_give_up) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      exception, try, elapsed_time, next_interval, reason = give_up_calls.fetch(0)
+      expect(give_up_calls.size).to eq(1)
+      expect(exception).to be_a(StandardError)
+      expect(exception.message).to eq("StandardError occurred")
+      expect(try).to eq(2)
+      expect(elapsed_time).to be >= 0
+      expect(next_interval).to be_nil
+      expect(reason).to eq(:tries_exhausted)
+      expect(@tries).to eq(2)
+    end
+
+    it "does not call on_give_up when the block eventually succeeds" do
+      callback_called = false
+
+      described_class.retriable(tries: 3, on_give_up: proc { callback_called = true }) do
+        increment_tries
+        raise StandardError if @tries < 2
+      end
+
+      expect(callback_called).to be(false)
+      expect(@tries).to eq(2)
+    end
+
+    it "does not call on_give_up for non-retriable exception types" do
+      callback_called = false
+
+      expect do
+        described_class.retriable(on_give_up: proc { callback_called = true }) do
+          increment_tries_with_exception(NonStandardError)
+        end
+      end.to raise_error(NonStandardError)
+
+      expect(callback_called).to be(false)
+      expect(@tries).to eq(1)
+    end
+
+    it "does not call on_give_up when retry_if rejects the exception" do
+      callback_called = false
+
+      expect do
+        described_class.retriable(
+          tries: 3,
+          retry_if: ->(_exception) { false },
+          on_give_up: proc { callback_called = true },
+        ) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(StandardError)
+
+      expect(callback_called).to be(false)
+      expect(@tries).to eq(1)
+    end
+
+    it "does not call on_give_up when explicitly set to false" do
+      callback_called = false
+      original_on_give_up = described_class.config.on_give_up
+
+      begin
+        described_class.configure do |c|
+          c.on_give_up = proc { callback_called = true }
+        end
+
+        expect do
+          described_class.retriable(on_give_up: false, tries: 1) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+
+        expect(callback_called).to be(false)
+      ensure
+        described_class.configure do |c|
+          c.on_give_up = original_on_give_up
+        end
+      end
+    end
+
+    it "does not call on_give_up when explicitly set to nil" do
+      callback_called = false
+      original_on_give_up = described_class.config.on_give_up
+
+      begin
+        described_class.configure do |c|
+          c.on_give_up = proc { callback_called = true }
+        end
+
+        expect do
+          described_class.retriable(on_give_up: nil, tries: 1) { increment_tries_with_exception }
+        end.to raise_error(StandardError)
+
+        expect(callback_called).to be(false)
+      ensure
+        described_class.configure do |c|
+          c.on_give_up = original_on_give_up
+        end
+      end
+    end
+
+    it "calls on_retry before on_give_up when giving up" do
+      events = []
+
+      expect do
+        described_class.retriable(
+          tries: 1,
+          on_retry: proc { events << :on_retry },
+          on_give_up: proc { events << :on_give_up },
+        ) do
+          increment_tries_with_exception
+        end
+      end.to raise_error(StandardError)
+
+      expect(events).to eq(%i[on_retry on_give_up])
+    end
+
+    it "propagates exceptions raised inside on_give_up, replacing the original exception" do
+      handler = proc { raise "handler exploded" }
+
+      expect do
+        described_class.retriable(tries: 1, on_give_up: handler) { increment_tries_with_exception }
+      end.to raise_error(RuntimeError, "handler exploded")
+
+      expect(@tries).to eq(1)
+    end
+
     context "with rand_factor 0.0 and an on_retry handler" do
       let(:tries) { 6 }
       let(:no_rand_timetable) { { 1 => 0.5, 2 => 0.75, 3 => 1.125 } }
@@ -375,6 +517,19 @@ describe Retriable do
       end
     end
 
+    context "with a Set :on parameter" do
+      it "retries each exception class in the Set" do
+        described_class.retriable(on: Set[StandardError, NonStandardError]) do
+          increment_tries
+
+          raise StandardError if @tries == 1
+          raise NonStandardError if @tries == 2
+        end
+
+        expect(@tries).to eq(3)
+      end
+    end
+
     context "with a hash :on parameter" do
       let(:on_hash) { { NonStandardError => /NonStandardError occurred/ } }
 
@@ -407,6 +562,20 @@ describe Retriable do
         expect(@tries).to eq(1)
       end
 
+      it "does not call on_give_up when exception class matches but message does not" do
+        callback_called = false
+
+        expect do
+          described_class.retriable(on: on_hash, on_give_up: proc { callback_called = true }) do
+            increment_tries
+            raise SecondNonStandardError, "not a match"
+          end
+        end.to raise_error(SecondNonStandardError, /not a match/)
+
+        expect(callback_called).to be(false)
+        expect(@tries).to eq(1)
+      end
+
       it "successfully retries when the values are arrays of exception message patterns" do
         exceptions = []
         handler = ->(exception, try, _elapsed_time, _next_interval) { exceptions[try] = exception }
@@ -601,6 +770,38 @@ describe Retriable do
     end
   end
 
+  context "#retriable tries/intervals precedence" do
+    it "lets a per-call tries clear globally configured intervals" do
+      described_class.configure { |c| c.intervals = [0.5, 1.0] }
+
+      expect do
+        described_class.retriable(tries: 1) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(1)
+    end
+
+    it "still lets per-call intervals win when both intervals and tries are given" do
+      expect do
+        described_class.retriable(intervals: [0.5, 1.0], tries: 1) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(3) # intervals.size + 1
+    end
+
+    it "lets a with_context tries clear context intervals" do
+      described_class.configure do |c|
+        c.contexts[:api] = { intervals: [0.5, 1.0] }
+      end
+
+      expect do
+        described_class.with_context(:api, tries: 1) { increment_tries_with_exception }
+      end.to raise_error(StandardError)
+
+      expect(@tries).to eq(1)
+    end
+  end
+
   context "#with_override" do
     it "takes precedence over both global config and local options" do
       described_class.configure { |c| c.tries = 2 }
@@ -737,17 +938,15 @@ describe Retriable do
     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.with_override(contexts: { api: { tries: 1 } }) do
-          described_class.with_context(:api) { increment_tries }
-        end
+      described_class.configure { |c| c.contexts = nil }
 
-        expect(@tries).to eq(1)
-      ensure
-        described_class.configure { |c| c.contexts = {} }
+      described_class.with_override(contexts: { api: { tries: 1 } }) do
+        described_class.with_context(:api) { increment_tries }
       end
+
+      expect(@tries).to eq(1)
+    ensure
+      described_class.configure { |c| c.contexts = {} }
     end
 
     it "ignores nil override contexts values in with_context" do
@@ -1017,6 +1216,31 @@ describe Retriable do
 
       expect(other_thread_tries).to eq(3)
     end
+
+    it "applies overridden on_give_up handlers" do
+      callback_called = false
+
+      expect do
+        described_class.with_override(on_give_up: proc { callback_called = true }) do
+          described_class.retriable(tries: 1) { increment_tries_with_exception }
+        end
+      end.to raise_error(StandardError)
+
+      expect(callback_called).to be(true)
+    end
+
+    it "applies on_give_up handlers configured via per-context overrides" do
+      received_reason = nil
+      handler = proc { |_e, _try, _elapsed, _interval, reason| received_reason = reason }
+
+      expect do
+        described_class.with_override(contexts: { api: { tries: 1, on_give_up: handler } }) do
+          described_class.with_context(:api) { increment_tries_with_exception }
+        end
+      end.to raise_error(StandardError)
+
+      expect(received_reason).to eq(:tries_exhausted)
+    end
   end
 
   context "#with_context" do
@@ -1034,8 +1258,15 @@ describe Retriable do
       expect(@tries).to eq(1)
     end
 
-    it "returns nil when called without a block" do
-      expect(described_class.with_context(:sql)).to be_nil
+    it "raises an ArgumentError when called without a block" do
+      expect { described_class.with_context(:sql) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
+      expect(@tries).to eq(0)
+    end
+
+    it "checks for a block before looking up the context" do
+      expect { described_class.with_context(:missing) }
+        .to raise_error(ArgumentError, /with_context requires a block/)
       expect(@tries).to eq(0)
     end
 
@@ -1075,5 +1306,24 @@ describe Retriable do
       described_class.with_context(:broken) { increment_tries }
       expect(@tries).to eq(1)
     end
+
+    it "surfaces an invalid context on any retriable call before that context is used" do
+      described_class.configure { |c| c.contexts[:unused] = { contexts: {} } }
+
+      expect { described_class.retriable { :ok } }
+        .to raise_error(ArgumentError, /contexts is not a valid option/)
+    end
+
+    it "invokes on_give_up configured on a context" do
+      callback_called = false
+      described_class.configure do |c|
+        c.contexts[:flaky] = { tries: 1, on_give_up: proc { callback_called = true } }
+      end
+
+      expect { described_class.with_context(:flaky) { increment_tries_with_exception } }
+        .to raise_error(StandardError)
+
+      expect(callback_called).to be(true)
+    end
   end
 end

data/spec/spec_helper.rb

@@ -1,27 +1,16 @@
 # frozen_string_literal: true
 
 require "simplecov"
-SimpleCov.start
+SimpleCov.start do
+  minimum_coverage 95
+end
 
 require "pry"
 require_relative "../lib/retriable"
 require_relative "support/exceptions"
 
-# Make Retriable's deprecation notices observable to RSpec's
-# `output().to_stderr` matcher. On Ruby 3.0+ the `:deprecated` warning category
-# is suppressed by default, which would hide the notices we want to assert on.
-WARNING_DEPRECATION_SUPPORTED = defined?(Warning) && Warning.respond_to?(:[])
-Warning[:deprecated] = true if WARNING_DEPRECATION_SUPPORTED
-
-# Used by deprecation specs that only make sense on Rubies where `Kernel#warn`
-# supports the `category:` keyword (added in Ruby 2.7).
-WARN_CATEGORY_SUPPORTED = WARNING_DEPRECATION_SUPPORTED &&
-                          Kernel.method(:warn).parameters.include?(%i[key category])
-
 RSpec.configure do |config|
   config.before(:each) do
     srand(0)
-    Retriable::Config.timeout_deprecation_warned = false
-    Warning[:deprecated] = true if WARNING_DEPRECATION_SUPPORTED
   end
 end

metadata

@@ -1,56 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Jack Chu
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3'
-- !ruby/object:Gem::Dependency
-  name: listen
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.1'
+dependencies: []
 description: Retriable is a simple DSL to retry failed code blocks with randomized
   exponential backoff. This is especially useful when interacting with external APIs/services
   or file system calls.
@@ -91,7 +49,8 @@ files:
 homepage: https://github.com/kamui/retriable
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -99,20 +58,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Retriable is a simple DSL to retry failed code blocks with randomized exponential
   backoff
-test_files:
-- spec/config_spec.rb
-- spec/exponential_backoff_spec.rb
-- spec/retriable_spec.rb
-- spec/spec_helper.rb
-- spec/support/exceptions.rb
+test_files: []