philiprehberger-retry_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '087ec5bc777335b701a4c95fed80654168c61f7f99db577dfbe11c0f548bbc90'
+  data.tar.gz: aa0f0381cb4d79add6829653d1aabb0d37127ae99edfe158921b7f0d30dd4a39
+SHA512:
+  metadata.gz: 6b5d3c1f93a480f75d5007b223fdd26c24a17f5d7f428c3f094bbd54a2051635a1066fcb8b57d986628550559b77445120afe9499a916b7bfdc76f5037866849
+  data.tar.gz: 640c8a218b0b51fb89c4a416e6ee84b9719bcd810001f9c3a71b38458f7a801269ca16c436710a9189772d0e3a4d31ede051d33e9ba90effdfe39a114f12a584

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+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/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-10
+
+### Added
+- Initial release
+- Exponential, linear, and constant backoff strategies
+- Full and equal jitter modes
+- Circuit breaker with configurable threshold and cooldown
+- Retry executor with max attempts, retryable error filtering, and on_retry callback
+- Convenience `RetryKit.run` class method

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# philiprehberger-retry_kit
+
+[![Tests](https://github.com/philiprehberger/rb-retry-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-retry-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-retry_kit.svg)](https://rubygems.org/gems/philiprehberger-retry_kit)
+
+Retry with exponential backoff, jitter, and circuit breaker for resilient Ruby applications.
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-retry_kit"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-retry_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/retry_kit"
+
+# Simple retry with defaults (3 attempts, exponential backoff, full jitter)
+result = Philiprehberger::RetryKit.run do
+  api.call
+end
+```
+
+### Custom Options
+
+```ruby
+Philiprehberger::RetryKit.run(
+  max_attempts: 5,
+  backoff: :exponential,
+  base_delay: 1,
+  max_delay: 60,
+  jitter: :equal,
+  on: [Net::ReadTimeout, Errno::ECONNRESET]
+) do
+  http_request
+end
+```
+
+### Retry Callback
+
+```ruby
+Philiprehberger::RetryKit.run(
+  max_attempts: 4,
+  on_retry: ->(error, attempt, delay) {
+    puts "Attempt #{attempt} failed: #{error.message}. Retrying in #{delay}s..."
+  }
+) do
+  flaky_operation
+end
+```
+
+### Backoff Strategies
+
+```ruby
+# Exponential: 0.5s, 1s, 2s, 4s, ...
+Philiprehberger::RetryKit.run(backoff: :exponential)
+
+# Linear: 0.5s, 1s, 1.5s, 2s, ...
+Philiprehberger::RetryKit.run(backoff: :linear)
+
+# Constant: 1s, 1s, 1s, ...
+Philiprehberger::RetryKit.run(backoff: :constant, base_delay: 1)
+```
+
+### Circuit Breaker
+
+```ruby
+breaker = Philiprehberger::RetryKit::CircuitBreaker.new(
+  failure_threshold: 5,
+  cooldown: 30
+)
+
+# Use with retry
+Philiprehberger::RetryKit.run(circuit_breaker: breaker) do
+  external_service.call
+end
+
+# Use standalone
+breaker.call { risky_operation }
+
+# Check state
+breaker.state        # => :closed, :open, or :half_open
+breaker.failure_count
+breaker.reset
+```
+
+### Backoff Utilities
+
+```ruby
+Philiprehberger::RetryKit::Backoff.exponential(3, base_delay: 0.5, max_delay: 30)
+# => 4.0
+
+Philiprehberger::RetryKit::Backoff.jitter(4.0, mode: :full)
+# => 0.0..4.0 (random)
+```
+
+## API
+
+| Method / Class | Description |
+|----------------|-------------|
+| `RetryKit.run(**options, &block)` | Execute a block with retry logic |
+| `Executor.new(**options)` | Create a reusable retry executor |
+| `Executor#call(&block)` | Execute the block with retries |
+| `CircuitBreaker.new(failure_threshold:, cooldown:)` | Create a circuit breaker |
+| `CircuitBreaker#call(&block)` | Execute through the circuit breaker |
+| `CircuitBreaker#state` | Current state (`:closed`, `:open`, `:half_open`) |
+| `CircuitBreaker#reset` | Reset to closed state |
+| `Backoff.exponential(attempt, base_delay:, max_delay:)` | Calculate exponential delay |
+| `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 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/retry_kit/backoff.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    # Backoff strategy calculators.
+    module Backoff
+      module_function
+
+      # Exponential backoff: base_delay * 2^attempt
+      #
+      # @param attempt [Integer] the current attempt number (0-based)
+      # @param base_delay [Numeric] the base delay in seconds
+      # @param max_delay [Numeric] the maximum delay cap in seconds
+      # @return [Numeric] delay in seconds
+      def exponential(attempt, base_delay: 0.5, max_delay: 30)
+        delay = base_delay * (2**attempt)
+        [delay, max_delay].min
+      end
+
+      # Linear backoff: base_delay * (attempt + 1)
+      #
+      # @param attempt [Integer] the current attempt number (0-based)
+      # @param base_delay [Numeric] the base delay in seconds
+      # @param max_delay [Numeric] the maximum delay cap in seconds
+      # @return [Numeric] delay in seconds
+      def linear(attempt, base_delay: 0.5, max_delay: 30)
+        delay = base_delay * (attempt + 1)
+        [delay, max_delay].min
+      end
+
+      # Constant backoff: always the same delay.
+      #
+      # @param _attempt [Integer] ignored
+      # @param delay [Numeric] the constant delay in seconds
+      # @return [Numeric] delay in seconds
+      def constant(_attempt, delay: 1)
+        delay
+      end
+
+      # Add jitter to a delay value.
+      #
+      # @param delay [Numeric] the base delay
+      # @param mode [Symbol] jitter mode — :full, :equal, or :decorrelated
+      # @return [Float] jittered delay
+      def jitter(delay, mode: :full)
+        case mode
+        when :full
+          rand * delay
+        when :equal
+          (delay / 2.0) + (rand * delay / 2.0)
+        when :none
+          delay.to_f
+        else
+          raise ArgumentError, "Unknown jitter mode: #{mode}. Use :full, :equal, or :none"
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_kit/circuit_breaker.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    # A simple circuit breaker that tracks failures and opens the circuit
+    # when a threshold is exceeded, preventing further calls until a
+    # cooldown period has elapsed.
+    class CircuitBreaker
+      # Raised when the circuit is open and a call is attempted.
+      class OpenError < Error; end
+
+      STATES = %i[closed open half_open].freeze
+
+      attr_reader :state, :failure_count, :failure_threshold, :cooldown
+
+      # @param failure_threshold [Integer] number of failures before opening
+      # @param cooldown [Numeric] seconds to wait before transitioning to half-open
+      def initialize(failure_threshold: 5, cooldown: 30)
+        @failure_threshold = failure_threshold
+        @cooldown = cooldown
+        @failure_count = 0
+        @state = :closed
+        @last_failure_time = nil
+        @mutex = Mutex.new
+      end
+
+      # Execute a block through the circuit breaker.
+      #
+      # @yield the block to execute
+      # @return the block's return value
+      # @raise [OpenError] if the circuit is open
+      def call(&block)
+        raise ArgumentError, "Block required" unless block
+
+        @mutex.synchronize { check_state! }
+
+        result = block.call
+        record_success
+        result
+      rescue OpenError
+        raise
+      rescue StandardError => e
+        record_failure
+        raise e
+      end
+
+      # Reset the circuit breaker to closed state.
+      def reset
+        @mutex.synchronize do
+          @failure_count = 0
+          @state = :closed
+          @last_failure_time = nil
+        end
+      end
+
+      private
+
+      def check_state!
+        case @state
+        when :open
+          unless cooldown_elapsed?
+            raise OpenError, "Circuit is open (#{@failure_count} failures, cooldown: #{@cooldown}s)"
+          end
+
+          @state = :half_open
+        when :half_open
+          # Allow one attempt through
+        end
+      end
+
+      def record_success
+        @mutex.synchronize do
+          @failure_count = 0
+          @state = :closed
+          @last_failure_time = nil
+        end
+      end
+
+      def record_failure
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          @state = :open if @failure_count >= @failure_threshold
+        end
+      end
+
+      def cooldown_elapsed?
+        @last_failure_time && (Time.now - @last_failure_time) >= @cooldown
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_kit/executor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    # Executes a block with configurable retry logic, backoff, and optional circuit breaker.
+    class Executor
+      # @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
+      def initialize(**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]))
+        @circuit_breaker = options[:circuit_breaker]
+        @on_retry = options[:on_retry]
+      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
+
+        attempt_with_retries(0, &block)
+      end
+
+      private
+
+      def attempt_with_retries(attempt, &)
+        execute_attempt(&)
+      rescue CircuitBreaker::OpenError
+        raise
+      rescue *@retryable_errors => e
+        raise e if attempt + 1 >= @max_attempts
+
+        delay = compute_delay(attempt)
+        @on_retry&.call(e, attempt + 1, delay)
+        sleep(delay)
+        attempt_with_retries(attempt + 1, &)
+      end
+
+      def execute_attempt(&)
+        if @circuit_breaker
+          @circuit_breaker.call(&)
+        else
+          yield
+        end
+      end
+
+      def compute_delay(attempt)
+        raw = backoff_delay(attempt)
+        Backoff.jitter(raw, mode: @jitter)
+      end
+
+      def backoff_delay(attempt)
+        case @backoff
+        when :exponential then Backoff.exponential(attempt, base_delay: @base_delay, max_delay: @max_delay)
+        when :linear then Backoff.linear(attempt, base_delay: @base_delay, max_delay: @max_delay)
+        when :constant then Backoff.constant(attempt, delay: @base_delay)
+        else raise ArgumentError, "Unknown backoff strategy: #{@backoff}"
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/retry_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    VERSION = "0.1.0"
+  end
+end

data/lib/philiprehberger/retry_kit.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RetryKit
+    class Error < StandardError; end
+
+    # Execute a block with retry logic.
+    #
+    # @param options [Hash] options passed to Executor.new
+    # @yield the block to execute
+    # @return the block's return value
+    # @see Executor#initialize for available options
+    def self.run(**options, &)
+      Executor.new(**options).call(&)
+    end
+  end
+end
+
+require_relative "retry_kit/version"
+require_relative "retry_kit/backoff"
+require_relative "retry_kit/circuit_breaker"
+require_relative "retry_kit/executor"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-retry_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-10 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
+  applications.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/retry_kit.rb
+- lib/philiprehberger/retry_kit/backoff.rb
+- lib/philiprehberger/retry_kit/circuit_breaker.rb
+- lib/philiprehberger/retry_kit/executor.rb
+- lib/philiprehberger/retry_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-retry-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-retry-kit
+  source_code_uri: https://github.com/philiprehberger/rb-retry-kit
+  changelog_uri: https://github.com/philiprehberger/rb-retry-kit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Retry with exponential backoff, jitter, and circuit breaker
+test_files: []