retriable 3.2.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8df6a3c9b00afd6e5f3e307fdb07d3cedae54c43b4f3537998ebae78dd17ab29
-  data.tar.gz: 46023d8f2d1731ea9a3c66c61839b04aa49b18d3def72d1ea1fc36d9c9e7a1c3
+  metadata.gz: 1c6c4929adafa9b223f3fbe0ee530ef8a7d1e764cac8f5605be9ce33e3d1b0cc
+  data.tar.gz: 5d7013b0d5ce9ab8514a8deab7a32d77b0422cc02ead4aceb5a8c9b5ba28bff1
 SHA512:
-  metadata.gz: cd71b6a0a42cb2c6482409bcbc42d57504c5f601aa33e80d8a032dd97e31df582234bbb8959c1cf70eb92b7cf67c650497820be5b219053322317cbb7d748efa
-  data.tar.gz: 617c7c1785c0b7691655615484251b8b591afa43d211d0ea4ef0d94def9747e84814dbdbe9095c388c112a9957c6050d17ba4c3044bb2e2f299bf4d892f6fd04
+  metadata.gz: 9a83302cfe426348ae0a35e6410edce33c8985d49289ab06100be7c5d49a586f93a429632814b2129e67b20dde8963eb2f5941bcc59d12f4c1db56ce05fd6784
+  data.tar.gz: 792c54b8b8805eb11c93d9ac100671b357b91a465424939a5c3995a2a50a8449033a0e94138bdf2510b2a7f89b4dc35787b0c490c53d63c9a0d2b85f044c80a9

data/.github/workflows/main.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
-    branches: [master]
+    branches: [main]
     types: [opened, synchronize, reopened]
 
 jobs:

data/.gitignore

@@ -4,6 +4,8 @@
 /_yardoc/
 /coverage/
 /doc/
+/docs/plans/
+/.worktrees/
 /pkg/
 /spec/reports/
 /tmp/

data/.rubocop.yml

@@ -1,3 +1,7 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.3
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
@@ -13,12 +17,6 @@ Style/TrailingCommaInArguments:
 Lint/InheritException:
   Enabled: false
 
-Layout/FirstArrayElementIndentation:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
 Style/NegatedIf:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,7 +1,17 @@
 # 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.
+- Modernize `.rubocop.yml` with explicit modern defaults to enable new cops while preserving existing project style policies.
+
 ## 3.2.1
-- Remove executables from gemspec as it was poluting the path for some users. Thanks @hsbt.
+
+- Remove executables from gemspec as it was polluting the path for some users. Thanks @hsbt.
 
 ## 3.2.0
 

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/exponential_backoff.rb

@@ -2,12 +2,12 @@
 
 module Retriable
   class ExponentialBackoff
-    ATTRIBUTES = [
-      :tries,
-      :base_interval,
-      :multiplier,
-      :max_interval,
-      :rand_factor,
+    ATTRIBUTES = %i[
+      tries
+      base_interval
+      multiplier
+      max_interval
+      rand_factor
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -21,6 +21,7 @@ module Retriable
 
       opts.each do |k, v|
         raise ArgumentError, "#{k} is not a valid option" if !ATTRIBUTES.include?(k)
+
         instance_variable_set(:"@#{k}", v)
       end
     end

data/lib/retriable/version.rb

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

data/lib/retriable.rb

@@ -18,64 +18,120 @@ 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
 
-    retriable(config.contexts[context_key].merge(options), &block) if block
+    return unless block_given?
+
+    retriable(config.contexts[context_key].merge(options), &block)
   end
 
-  def retriable(opts = {})
+  def retriable(opts = {}, &block)
     local_config = opts.empty? ? config : Config.new(config.to_h.merge(opts))
 
-    tries             = local_config.tries
-    base_interval     = local_config.base_interval
-    max_interval      = local_config.max_interval
-    rand_factor       = local_config.rand_factor
-    multiplier        = local_config.multiplier
-    max_elapsed_time  = local_config.max_elapsed_time
-    intervals         = local_config.intervals
-    timeout           = local_config.timeout
-    on                = local_config.on
-    on_retry          = local_config.on_retry
-    sleep_disabled    = local_config.sleep_disabled
+    tries = local_config.tries
+    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
 
     exception_list = on.is_a?(Hash) ? on.keys : on
+    exception_list = [*exception_list]
     start_time = Time.now
     elapsed_time = -> { Time.now - start_time }
 
-    if !intervals
-      intervals = ExponentialBackoff.new(
-        tries:          tries - 1,
-        base_interval:  base_interval,
-        multiplier:     multiplier,
-        max_interval:   max_interval,
-        rand_factor:    rand_factor
-      ).intervals
-    end
-
     tries = intervals.size + 1
 
+    execute_tries(
+      tries: tries, intervals: intervals, timeout: timeout,
+      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
+    )
+  end
+
+  def execute_tries( # rubocop:disable Metrics/ParameterLists
+    tries:, intervals:, timeout:, exception_list:,
+    on:, retry_if:, on_retry:, elapsed_time:, max_elapsed_time:, sleep_disabled:, &block
+  )
     tries.times do |index|
       try = index + 1
 
       begin
-        return Timeout.timeout(timeout) { return yield(try) } if timeout
-
-        return yield(try)
-      rescue *[*exception_list] => exception
-        if on.is_a?(Hash)
-          raise unless exception_list.any? do |e|
-            exception.is_a?(e) && ([*on[e]].empty? || [*on[e]].any? { |pattern| exception.message =~ pattern })
-          end
-        end
+        return call_with_timeout(timeout, try, &block)
+      rescue *exception_list => e
+        raise unless retriable_exception?(e, on, exception_list, retry_if)
 
         interval = intervals[index]
-        on_retry.call(exception, try, elapsed_time.call, interval) if on_retry
+        call_on_retry(on_retry, e, try, elapsed_time.call, interval)
 
-        raise if try >= tries || (elapsed_time.call + interval) > max_elapsed_time
+        raise unless can_retry?(try, tries, elapsed_time.call, interval, max_elapsed_time)
 
         sleep interval if sleep_disabled != true
       end
     end
   end
+
+  def build_intervals(local_config, tries)
+    return local_config.intervals if local_config.intervals
+
+    ExponentialBackoff.new(
+      tries: tries - 1,
+      base_interval: local_config.base_interval,
+      multiplier: local_config.multiplier,
+      max_interval: local_config.max_interval,
+      rand_factor: local_config.rand_factor,
+    ).intervals
+  end
+
+  def call_with_timeout(timeout, try)
+    return Timeout.timeout(timeout) { yield(try) } if timeout
+
+    yield(try)
+  end
+
+  def call_on_retry(on_retry, exception, try, elapsed_time, interval)
+    return unless on_retry
+
+    on_retry.call(exception, try, elapsed_time, interval)
+  end
+
+  def can_retry?(try, tries, elapsed_time, interval, max_elapsed_time)
+    try < tries && (elapsed_time + interval) <= max_elapsed_time
+  end
+
+  # 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 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
+
+  def hash_exception_match?(exception, on, exception_list)
+    exception_list.any? do |error_class|
+      next false unless exception.is_a?(error_class)
+
+      patterns = [*on[error_class]]
+      patterns.empty? || patterns.any? { |pattern| exception.message =~ pattern }
+    end
+  end
+
+  private_class_method(
+    :execute_tries,
+    :build_intervals,
+    :call_with_timeout,
+    :call_on_retry,
+    :can_retry?,
+    :retriable_exception?,
+    :hash_exception_match?,
+  )
 end

data/retriable.gemspec

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-lib = File.expand_path("../lib", __FILE__)
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "retriable/version"
 
@@ -9,7 +10,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jack Chu"]
   spec.email         = ["jack@jackchu.com"]
   spec.summary       = "Retriable is a simple DSL to retry failed code blocks with randomized exponential backoff"
-  spec.description   = "Retriable is a simple DSL to retry failed code blocks with randomized exponential backoff. This is especially useful when interacting external api/services or file system calls."
+  spec.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."
   spec.homepage      = "https://github.com/kamui/retriable"
   spec.license       = "MIT"
 

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

@@ -96,6 +96,28 @@ describe Retriable do
       expect(@tries).to eq(10)
     end
 
+    it "does not call on_retry when explicitly set to false" 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: false, 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
+
     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 } }
@@ -237,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 }
 
@@ -255,6 +321,17 @@ describe Retriable do
   end
 
   context "#configure" do
+    it "exposes only the intended public API" do
+      public_api_methods = %i[
+        retriable
+        with_context
+        configure
+        config
+      ]
+
+      expect(described_class.singleton_methods(false)).to match_array(public_api_methods)
+    end
+
     it "raises NoMethodError on invalid configuration" do
       expect { described_class.configure { |c| c.does_not_exist = 123 } }.to raise_error(NoMethodError)
     end
@@ -275,6 +352,22 @@ 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
+      expect(@tries).to eq(0)
+    end
+
+    it "passes try count through to the context block" do
+      seen_tries = []
+
+      described_class.with_context(:api) do |try|
+        seen_tries << try
+        raise StandardError if try < 3
+      end
+
+      expect(seen_tries).to eq([1, 2, 3])
+    end
+
     it "respects the context options" do
       expect { described_class.with_context(:api) { increment_tries_with_exception } }.to raise_error(StandardError)
       expect(@tries).to eq(api_tries)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: retriable
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.4.0
 platform: ruby
 authors:
 - Jack Chu
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.1'
 description: Retriable is a simple DSL to retry failed code blocks with randomized
-  exponential backoff. This is especially useful when interacting external api/services
+  exponential backoff. This is especially useful when interacting with external APIs/services
   or file system calls.
 email:
 - jack@jackchu.com