philiprehberger-retry_kit 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb6f9448eb54f6b7d540f0fbce8e867316e559c7b65f0c4f22d25d2380a1d913
-  data.tar.gz: 504733ba0b309f42dd95a7a79de9113b5caac7d84172d9e2b239e467b366c335
+  metadata.gz: 5396e04754dc4723f9c7b19fa77aa89661ad290f580a4c2c7450a61b91af6805
+  data.tar.gz: c64abc10a925d3dffdac7c879a007e4199b8807946e3f3488813cb8dd7b2a8ee
 SHA512:
-  metadata.gz: 7f49a0afb554d1142b0372c1da8fa1c0165cdbefe538b6af73987c1aeecc35a3c2725e6fd5f7272dd1091b46e48ee0b23f0f09c5dd70d24bced6ab49bf61a3d5
-  data.tar.gz: e75f35e7fc516765fee442e48119b00e5f6e1395a98b0edd3b3d152004ff65e9411a8efac276c4c1c44ad2c71b3160c568031ad7169ea627f55bc34fa895789b
+  metadata.gz: aee34894d6b70dcbf1e05bf320da0d32090ed3f64bdded686f38115013f4a6532b32015347a2ba939981bb466cfa06403485cf08455fe8213791de35f616a97f
+  data.tar.gz: 97aaf45c7d40ad94c87c87cd9680c4a8a8e9de6efffea4ea2c4a8fe08bfca97a94044a7f44b175f2bd09ea4bc713bf6c43dc121b36355ad79e4cf009f8f4e780

data/CHANGELOG.md

@@ -1,10 +1,5 @@
 # Changelog
 
-## 0.2.2
-
-- Add License badge to README
-- Add bug_tracker_uri to gemspec
-
 All notable changes to this gem will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -12,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-16
+
+### Added
+- Decorrelated jitter mode (`jitter: :decorrelated`) — AWS-style algorithm with better delay distribution
+- Fallback handler (`fallback:`) — execute alternative code when all retries are exhausted instead of raising
+- Retry predicate (`retry_if:`) — custom predicate for fine-grained retry decisions beyond exception class filtering
+- Per-attempt callback (`on_attempt:`) — hook called after every attempt for metrics/logging
+- Retry budget (`Budget`) — thread-safe sliding window counter shared across executors to prevent retry storms
+
+## [0.2.2] - 2026-03-12
+
+### Fixed
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+
 ## [0.2.1] - 2026-03-12
 
 ### Fixed

data/README.md

@@ -94,6 +94,85 @@ executor.last_attempts     # => 3 (number of attempts made)
 executor.last_total_delay  # => 3.5 (total seconds spent in backoff sleeps)
 ```
 
+### Decorrelated Jitter
+
+AWS-style decorrelated jitter provides better delay distribution than full or equal jitter:
+
+```ruby
+Philiprehberger::RetryKit.run(
+  backoff: :exponential,
+  jitter: :decorrelated,
+  base_delay: 0.5,
+  max_delay: 30
+) do
+  api_call
+end
+```
+
+Each delay is randomized between `base_delay` and `3 * last_sleep`, capped at `max_delay`.
+
+### Fallback Handler
+
+Execute alternative code when all retries are exhausted instead of raising:
+
+```ruby
+result = Philiprehberger::RetryKit.run(
+  max_attempts: 3,
+  fallback: ->(error) { default_value }
+) do
+  unreliable_call
+end
+```
+
+The fallback proc receives the last error and its return value becomes the result of `run`.
+
+### Retry Predicate
+
+Custom predicate for fine-grained retry decisions beyond exception class filtering:
+
+```ruby
+Philiprehberger::RetryKit.run(
+  retry_if: ->(error, attempt) { error.message.include?("timeout") && attempt < 3 }
+) do
+  api_call
+end
+```
+
+If `retry_if` returns false, retrying stops immediately even if `max_attempts` has not been reached. Works in addition to the `on:` exception class filter (both must pass).
+
+### Per-Attempt Callback
+
+Hook called after every attempt (not just retries) for metrics and logging:
+
+```ruby
+Philiprehberger::RetryKit.run(
+  on_attempt: ->(attempt, duration, error) {
+    puts "Attempt #{attempt} took #{duration}s#{error ? " (failed: #{error.message})" : ""}"
+  }
+) do
+  api_call
+end
+```
+
+Called after each attempt with: attempt number (1-based), duration in seconds, and error (`nil` on success).
+
+### Retry Budget
+
+Global retry budget shared across executors to prevent retry storms:
+
+```ruby
+budget = Philiprehberger::RetryKit::Budget.new(max_retries: 100, window: 60)
+
+# Multiple executors share the budget
+Philiprehberger::RetryKit.run(budget: budget) { call_a }
+Philiprehberger::RetryKit.run(budget: budget) { call_b }
+
+budget.remaining   # => remaining retry count
+budget.exhausted?  # => true/false
+```
+
+Thread-safe sliding window counter. When the budget is exhausted, retries are skipped and the error is raised immediately (or the fallback is invoked if provided).
+
 ### Backoff Strategies
 
 ```ruby
@@ -155,6 +234,11 @@ Philiprehberger::RetryKit::Backoff.jitter(4.0, mode: :full)
 | `Backoff.linear(attempt, base_delay:, max_delay:)` | Calculate linear delay |
 | `Backoff.constant(attempt, delay:)` | Calculate constant delay |
 | `Backoff.jitter(delay, mode:)` | Apply jitter to a delay (`:full`, `:equal`, `:none`) |
+| `Backoff.decorrelated(last_delay, base_delay:, max_delay:)` | Calculate decorrelated jitter delay |
+| `Budget.new(max_retries:, window:)` | Create a shared retry budget |
+| `Budget#acquire` | Consume one retry from the budget |
+| `Budget#remaining` | Remaining retries in the current window |
+| `Budget#exhausted?` | Whether the budget is exhausted |
 | `Executor#last_attempts` | Number of attempts in the last execution |
 | `Executor#last_total_delay` | Total backoff sleep time (seconds) in the last execution |
 | `TotalTimeoutError` | Raised when `total_timeout` is exceeded |

data/lib/philiprehberger/retry_kit/backoff.rb

@@ -54,6 +54,16 @@ module Philiprehberger
           raise ArgumentError, "Unknown jitter mode: #{mode}. Use :full, :equal, or :none"
         end
       end
+
+      # Compute decorrelated jitter delay (AWS-style).
+      #
+      # @param last_delay [Numeric] the previous sleep duration
+      # @param base_delay [Numeric] the base delay in seconds
+      # @param max_delay [Numeric] the maximum delay cap in seconds
+      # @return [Float] decorrelated jitter delay
+      def decorrelated(last_delay, base_delay: 0.5, max_delay: 30)
+        [max_delay, rand(base_delay.to_f..(last_delay * 3).to_f)].min
+      end
     end
   end
 end

data/lib/philiprehberger/retry_kit/budget.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    # Thread-safe sliding window retry budget to prevent retry storms.
+    #
+    # Multiple executors can share a single budget instance. When the budget
+    # is exhausted, retries are skipped and the error is raised immediately.
+    class Budget
+      # Raised when the retry budget is exhausted.
+      class ExhaustedError < Error; end
+
+      # @param max_retries [Integer] maximum number of retries allowed in the window
+      # @param window [Numeric] sliding window duration in seconds
+      def initialize(max_retries:, window:)
+        @max_retries = max_retries
+        @window = window
+        @timestamps = []
+        @mutex = Mutex.new
+      end
+
+      # Try to consume one retry from the budget.
+      #
+      # @return [Boolean] true if a retry was consumed, false if budget is exhausted
+      def acquire
+        @mutex.synchronize do
+          prune
+          return false if @timestamps.length >= @max_retries
+
+          @timestamps << now
+          true
+        end
+      end
+
+      # Returns the number of remaining retries in the current window.
+      #
+      # @return [Integer]
+      def remaining
+        @mutex.synchronize do
+          prune
+          @max_retries - @timestamps.length
+        end
+      end
+
+      # Returns whether the budget is exhausted.
+      #
+      # @return [Boolean]
+      def exhausted?
+        remaining <= 0
+      end
+
+      private
+
+      def prune
+        cutoff = now - @window
+        @timestamps.reject! { |t| t < cutoff }
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_kit/executor.rb

@@ -2,42 +2,21 @@
 
 module Philiprehberger
   module RetryKit
-    # Executes a block with configurable retry logic, backoff, and optional circuit breaker.
     class Executor
-      # Number of attempts in the last execution.
-      # @return [Integer]
-      attr_reader :last_attempts
-
-      # Total delay (seconds) spent sleeping across retries in the last execution.
-      # @return [Float]
-      attr_reader :last_total_delay
-
-      # @param options [Hash] retry configuration options
-      # @option options [Integer] :max_attempts (3) maximum number of attempts
-      # @option options [Symbol] :backoff (:exponential) backoff strategy
-      # @option options [Numeric] :base_delay (0.5) base delay in seconds
-      # @option options [Numeric] :max_delay (30) maximum delay cap in seconds
-      # @option options [Symbol] :jitter (:full) jitter mode
-      # @option options [Array<Class>] :on ([StandardError]) exception classes to retry on
-      # @option options [CircuitBreaker, nil] :circuit_breaker (nil) optional circuit breaker
-      # @option options [Proc, nil] :on_retry (nil) callback before each retry
-      # @option options [Numeric, nil] :total_timeout (nil) max total seconds across all attempts
+      attr_reader :last_attempts, :last_total_delay
+
       def initialize(**options)
         assign_options(options)
         @last_attempts = 0
         @last_total_delay = 0.0
       end
 
-      # Execute the block with retry logic.
-      #
-      # @yield the block to execute
-      # @return the block's return value
-      # @raise the last exception if all attempts are exhausted
       def call(&block)
         raise ArgumentError, "Block required" unless block
 
         @last_attempts = 0
         @last_total_delay = 0.0
+        @last_decorrelated_delay = @base_delay
         @start_time = @total_timeout ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
 
         attempt_with_retries(0, &block)
@@ -48,13 +27,39 @@ module Philiprehberger
       def attempt_with_retries(attempt, &)
         @last_attempts = attempt + 1
         check_total_timeout!
-        execute_attempt(&)
+        result, duration, error = timed_attempt(&)
+        @on_attempt&.call(attempt + 1, duration, error)
+        return result unless error
+
+        handle_failure(error, attempt, &)
+      end
+
+      def timed_attempt(&)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = execute_attempt(&)
+        [result, Process.clock_gettime(Process::CLOCK_MONOTONIC) - start, nil]
       rescue CircuitBreaker::OpenError, TotalTimeoutError
         raise
       rescue *@retryable_errors => e
-        raise e if attempt + 1 >= @max_attempts
+        [nil, Process.clock_gettime(Process::CLOCK_MONOTONIC) - start, e]
+      end
 
-        wait_and_retry(e, attempt, &)
+      def handle_failure(error, attempt, &)
+        if should_stop?(error, attempt)
+          return @fallback.call(error) if @fallback
+
+          raise error
+        end
+
+        wait_and_retry(error, attempt, &)
+      end
+
+      def should_stop?(error, attempt)
+        return true if attempt + 1 >= @max_attempts
+        return true if @retry_if && !@retry_if.call(error, attempt + 1)
+        return true if @budget && !@budget.acquire
+
+        false
       end
 
       def wait_and_retry(error, attempt, &)
@@ -66,15 +71,27 @@ module Philiprehberger
       end
 
       def assign_options(options)
+        assign_core_options(options)
+        assign_callback_options(options)
+      end
+
+      def assign_core_options(options)
         @max_attempts = options.fetch(:max_attempts, 3)
         @backoff = options.fetch(:backoff, :exponential)
         @base_delay = options.fetch(:base_delay, 0.5)
         @max_delay = options.fetch(:max_delay, 30)
         @jitter = options.fetch(:jitter, :full)
         @retryable_errors = Array(options.fetch(:on, [StandardError]))
+      end
+
+      def assign_callback_options(options)
         @circuit_breaker = options[:circuit_breaker]
         @on_retry = options[:on_retry]
         @total_timeout = options[:total_timeout]
+        @fallback = options[:fallback]
+        @retry_if = options[:retry_if]
+        @on_attempt = options[:on_attempt]
+        @budget = options[:budget]
       end
 
       def check_total_timeout!
@@ -88,16 +105,18 @@ module Philiprehberger
       end
 
       def execute_attempt(&)
-        if @circuit_breaker
-          @circuit_breaker.call(&)
-        else
-          yield
-        end
+        @circuit_breaker ? @circuit_breaker.call(&) : yield
       end
 
       def compute_delay(attempt)
-        raw = backoff_delay(attempt)
-        Backoff.jitter(raw, mode: @jitter)
+        return compute_decorrelated_delay if @jitter == :decorrelated
+
+        Backoff.jitter(backoff_delay(attempt), mode: @jitter)
+      end
+
+      def compute_decorrelated_delay
+        delay = Backoff.decorrelated(@last_decorrelated_delay, base_delay: @base_delay, max_delay: @max_delay)
+        @last_decorrelated_delay = delay
       end
 
       def backoff_delay(attempt)

data/lib/philiprehberger/retry_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module RetryKit
-    VERSION = "0.2.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/philiprehberger/retry_kit.rb

@@ -21,5 +21,6 @@ end
 
 require_relative "retry_kit/version"
 require_relative "retry_kit/backoff"
+require_relative "retry_kit/budget"
 require_relative "retry_kit/circuit_breaker"
 require_relative "retry_kit/executor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-retry_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-17 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight retry library with exponential/linear/constant backoff,
   configurable jitter strategies, and an optional circuit breaker for resilient Ruby
@@ -24,6 +24,7 @@ files:
 - README.md
 - lib/philiprehberger/retry_kit.rb
 - lib/philiprehberger/retry_kit/backoff.rb
+- lib/philiprehberger/retry_kit/budget.rb
 - lib/philiprehberger/retry_kit/circuit_breaker.rb
 - lib/philiprehberger/retry_kit/executor.rb
 - lib/philiprehberger/retry_kit/version.rb