retriable 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0e8971cb9e6833e2795f2537ee69950714f7eb85989b497d15fad7f2e2552b6
-  data.tar.gz: 222c0e1664bf327dfb22cf161c42a3f3bec07a54ea3787af24a86ebd86abcd50
+  metadata.gz: 1c6c4929adafa9b223f3fbe0ee530ef8a7d1e764cac8f5605be9ce33e3d1b0cc
+  data.tar.gz: 5d7013b0d5ce9ab8514a8deab7a32d77b0422cc02ead4aceb5a8c9b5ba28bff1
 SHA512:
-  metadata.gz: b768d200c1dd25f9a5218096e5bba26b0ee815833fb87ed6a004d90d7f94208f4520df0fdb1172fc6fdea55209cf1eeb15d6efc39a52bd2f32c0222b5aecca5a
-  data.tar.gz: 0a095f55fcdbe49adf71bb06682c062ed98a4328ef0e4648926e6782b93152c337cd78b2f30a2bf5a79affc37c31c3f2b39730600c3c63b5dcb41d5c09b59380
+  metadata.gz: 9a83302cfe426348ae0a35e6410edce33c8985d49289ab06100be7c5d49a586f93a429632814b2129e67b20dde8963eb2f5941bcc59d12f4c1db56ce05fd6784
+  data.tar.gz: 792c54b8b8805eb11c93d9ac100671b357b91a465424939a5c3995a2a50a8449033a0e94138bdf2510b2a7f89b4dc35787b0c490c53d63c9a0d2b85f044c80a9

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # HEAD
 
+## 3.4.0
+
+- Add `retry_if` option to support custom retry predicates, including checks against wrapped `exception.cause` values.
+
 ## 3.3.0
 
 - Refactor `Retriable.retriable` internals into focused private helpers to improve readability while preserving behavior.

data/README.md

@@ -32,7 +32,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 3.1'
+gem 'retriable', '~> 3.4'
 ```
 
 ## Usage
@@ -83,6 +83,7 @@ Here are the available options, in some vague order of relevance to most common
 | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | **`on`**               | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **`retry_if`**         | `nil`             | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if).                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **`on_retry`**         | `nil`             | `Proc` to call after each try is rescued. [Read more](#callbacks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | **`sleep_disabled`**   | `false`           | When true, disable exponential backoff and attempt retries immediately.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **`base_interval`**    | `0.5`             | The initial interval in seconds between tries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -104,6 +105,32 @@ Here are the available options, in some vague order of relevance to most common
   - A single `Regexp` pattern (retries exceptions ONLY if their `message` matches the pattern)
   - An array of patterns (retries exceptions ONLY if their `message` matches at least one of the patterns)
 
+#### Advanced Retry Matching With :retry_if
+
+Use **`:retry_if`** when retry logic depends on details that `:on` does not cover. The Proc receives the rescued exception and should return `true` to retry or `false` to re-raise immediately.
+
+```ruby
+def caused_by?(error, klass)
+  current = error
+  while current
+    return true if current.is_a?(klass)
+
+    current = current.cause
+  end
+
+  false
+end
+
+Retriable.retriable(
+  on: [Faraday::ConnectionFailed],
+  retry_if: ->(exception) { caused_by?(exception, Errno::ECONNRESET) }
+) do
+  # code here...
+end
+```
+
+`:retry_if` runs after the exception type has matched `:on`.
+
 ### Configuration
 
 You can change the global defaults with a `#configure` block:

data/lib/retriable/config.rb

@@ -4,14 +4,15 @@ require_relative "exponential_backoff"
 
 module Retriable
   class Config
-    ATTRIBUTES = (ExponentialBackoff::ATTRIBUTES + [
-      :sleep_disabled,
-      :max_elapsed_time,
-      :intervals,
-      :timeout,
-      :on,
-      :on_retry,
-      :contexts,
+    ATTRIBUTES = (ExponentialBackoff::ATTRIBUTES + %i[
+      sleep_disabled
+      max_elapsed_time
+      intervals
+      timeout
+      on
+      retry_if
+      on_retry
+      contexts
     ]).freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -29,6 +30,7 @@ module Retriable
       @intervals        = nil
       @timeout          = nil
       @on               = [StandardError]
+      @retry_if         = nil
       @on_retry         = nil
       @contexts         = {}
 

data/lib/retriable/version.rb

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

data/lib/retriable.rb

@@ -18,7 +18,8 @@ module Retriable
 
   def with_context(context_key, options = {}, &block)
     if !config.contexts.key?(context_key)
-      raise ArgumentError, "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
+      raise ArgumentError,
+            "#{context_key} not found in Retriable.config.contexts. Available contexts: #{config.contexts.keys}"
     end
 
     return unless block_given?
@@ -33,6 +34,7 @@ module Retriable
     intervals = build_intervals(local_config, tries)
     timeout = local_config.timeout
     on = local_config.on
+    retry_if = local_config.retry_if
     on_retry = local_config.on_retry
     sleep_disabled = local_config.sleep_disabled
     max_elapsed_time = local_config.max_elapsed_time
@@ -46,7 +48,7 @@ module Retriable
 
     execute_tries(
       tries: tries, intervals: intervals, timeout: timeout,
-      exception_list: exception_list, on: on, on_retry: on_retry,
+      exception_list: exception_list, on: on, retry_if: retry_if, on_retry: on_retry,
       elapsed_time: elapsed_time, max_elapsed_time: max_elapsed_time,
       sleep_disabled: sleep_disabled, &block
     )
@@ -54,7 +56,7 @@ module Retriable
 
   def execute_tries( # rubocop:disable Metrics/ParameterLists
     tries:, intervals:, timeout:, exception_list:,
-    on:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
+    on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
   )
     tries.times do |index|
       try = index + 1
@@ -62,7 +64,7 @@ module Retriable
       begin
         return call_with_timeout(timeout, try, &block)
       rescue *exception_list => e
-        raise unless retriable_exception?(e, on, exception_list)
+        raise unless retriable_exception?(e, on, exception_list, retry_if)
 
         interval = intervals[index]
         call_on_retry(on_retry, e, try, elapsed_time.call, interval)
@@ -105,9 +107,11 @@ module Retriable
   # When `on` is a Hash, we need to verify the exception matches a pattern.
   # For any non-Hash `on` value (e.g., Array of classes, single Exception class,
   # or Module), the `rescue *exception_list` clause already guarantees the
-  # exception is retriable, so we return true unconditionally.
-  def retriable_exception?(exception, on, exception_list)
+  # exception is retriable with respect to `on`; `retry_if`, if provided, is an
+  # additional gate that can still cause this method to return false.
+  def retriable_exception?(exception, on, exception_list, retry_if)
     return false if on.is_a?(Hash) && !hash_exception_match?(exception, on, exception_list)
+    return false if retry_if && !retry_if.call(exception)
 
     true
   end

data/spec/config_spec.rb

@@ -40,6 +40,10 @@ describe Retriable::Config do
       expect(default_config.on).to eq([StandardError])
     end
 
+    it "retry_if defaults to nil" do
+      expect(default_config.retry_if).to be_nil
+    end
+
     it "on_retry handler defaults to nil" do
       expect(default_config.on_retry).to be_nil
     end

data/spec/retriable_spec.rb

@@ -259,6 +259,50 @@ describe Retriable do
       end
     end
 
+    context "with a :retry_if parameter" do
+      it "retries only when retry_if returns true" do
+        described_class.retriable(tries: 3, retry_if: ->(_exception) { @tries < 3 }) do
+          increment_tries
+          raise StandardError, "StandardError occurred" if @tries < 3
+        end
+
+        expect(@tries).to eq(3)
+      end
+
+      it "does not retry when retry_if returns false" do
+        expect do
+          described_class.retriable(tries: 3, retry_if: ->(_exception) { false }) do
+            increment_tries_with_exception
+          end
+        end.to raise_error(StandardError)
+
+        expect(@tries).to eq(1)
+      end
+
+      it "can retry based on the wrapped exception cause" do
+        root_cause_class = Class.new(StandardError)
+        wrapper_class = Class.new(StandardError)
+
+        described_class.retriable(
+          on: [wrapper_class],
+          tries: 3,
+          retry_if: ->(exception) { exception.cause.is_a?(root_cause_class) },
+        ) do
+          increment_tries
+
+          if @tries < 3
+            begin
+              raise root_cause_class, "root cause"
+            rescue root_cause_class
+              raise wrapper_class, "wrapped"
+            end
+          end
+        end
+
+        expect(@tries).to eq(3)
+      end
+    end
+
     it "runs for a max elapsed time of 2 seconds" do
       described_class.configure { |c| c.sleep_disabled = false }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Jack Chu