philiprehberger-retry_kit 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc53b4c9ddcf5c348f93838536633fac3016058065db1b2cc2a7f0f3b2848b50
-  data.tar.gz: 5df8b82142c4b2174f671a1041666c02cfc71f04556135c3b2db011032d6a805
+  metadata.gz: 58a785fcf8b070442e6a6c0c94800303f540a155296497d6ae3cf10784635dc0
+  data.tar.gz: 9061b700576f0fb8c7b20ce6a70b8ebb5a7a268d566e69cba7cdd41323f26e2b
 SHA512:
-  metadata.gz: 361994d3aa900d24f4f248ea5bd48d0a390da49ef2ec97e354f069a953092b9142c55458d8702ec7a520eace4f45180df4935b1523d8c067fd0e31a85d640f89
-  data.tar.gz: 3f71e9a5bbd244abb592f66d8dfaa5100e8e198e52c5e4f92877e6dc3db62af9859f3c071b1b27bd3b924d8615163bf9e8f8291225d6b1a60d6ecb6c7886be9a
+  metadata.gz: 496f17ab9a3170de508f54919596f64824ac8cb9c2612ad073e541bdd6fa296aa46d6a0dacae580f75991fbc23c0643718270d5120763e17633ac4201e93bb9e
+  data.tar.gz: abdf61bc3a020b1d1df72ea03bc306267fc3bfa2252c874b277d658c974d0627ede10910cd31708e226105173064d3125e4b37591e67a7fb619d9751b5b72cec

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-07-15
+
+### Added
+- Fail-fast option validation in `Executor#initialize` — an unknown `backoff:` or `jitter:` symbol, `max_attempts < 1`, a negative `base_delay`, or a `max_delay` below `base_delay` now raise `ArgumentError` at construction time instead of silently succeeding or misbehaving later.
+- Single-trial half-open circuit breaker — when the circuit transitions to half-open only the first caller probes; concurrent callers receive `OpenError` until the probe resolves (success closes the circuit, failure re-opens it), preventing a thundering herd against a recovering dependency.
+
+### Fixed
+- Clamp retry sleeps to the remaining `total_timeout` / `deadline` budget — `wait_and_retry` no longer sleeps a full backoff delay when the budget is nearly exhausted (e.g. a 30s backoff under a 5s `total_timeout`). The delay is capped to the time remaining, and `TotalTimeoutError` / `DeadlineExceededError` is raised immediately when no budget remains.
+
 ## [0.8.1] - 2026-06-14
 
 ### Changed
@@ -124,7 +133,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Retry executor with max attempts, retryable error filtering, and on_retry callback
 - Convenience `RetryKit.run` class method
 
-[Unreleased]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.8.1...HEAD
+[Unreleased]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/philiprehberger/rb-retry-kit/compare/v0.6.0...v0.7.0

data/README.md

@@ -52,6 +52,8 @@ Philiprehberger::RetryKit.run(
 end
 ```
 
+Options are validated up front. `Executor.new` / `RetryKit.run` raise `ArgumentError` immediately for an unknown `backoff:` strategy or `jitter:` mode, `max_attempts` below 1, a negative `base_delay`, or a `max_delay` smaller than `base_delay` — so a misconfiguration surfaces at construction time instead of silently succeeding.
+
 ### Retry Callback
 
 ```ruby
@@ -78,6 +80,8 @@ Philiprehberger::RetryKit.run(
 end
 ```
 
+Backoff sleeps are clamped to the remaining budget: if a computed delay would sleep past `total_timeout` (or `deadline`), it is shortened to the time left, and `TotalTimeoutError` / `DeadlineExceededError` is raised as soon as no budget remains — the executor never overshoots the stated bound by sleeping a full backoff delay.
+
 ### Absolute Deadline
 
 Stop retrying once a specific wall-clock `Time` has passed. Useful when the caller has a hard SLA (e.g. "respond before the request times out") rather than a relative budget:
@@ -292,6 +296,8 @@ breaker.reset        # reset to closed
 breaker.trip!        # force open immediately (operational kill-switch)
 ```
 
+After the cooldown elapses the circuit becomes half-open and probes with a **single trial**: only the first caller is allowed through, and concurrent callers receive `OpenError` until the probe resolves. A successful probe closes the circuit; a failed probe re-opens it and starts a fresh cooldown. This prevents a thundering herd from hammering a dependency that is still recovering.
+
 ### Backoff Utilities
 
 ```ruby

data/lib/philiprehberger/retry_kit/circuit_breaker.rb

@@ -23,6 +23,7 @@ module Philiprehberger
         @failure_count = 0
         @state = :closed
         @last_failure_time = nil
+        @half_open_in_flight = false
         @mutex = Mutex.new
       end
 
@@ -50,6 +51,7 @@ module Philiprehberger
       def reset
         @mutex.synchronize do
           @failure_count = 0
+          @half_open_in_flight = false
           transition_to(:closed)
           @last_failure_time = nil
         end
@@ -63,6 +65,7 @@ module Philiprehberger
       def trip!
         @mutex.synchronize do
           @failure_count = @failure_threshold
+          @half_open_in_flight = false
           @last_failure_time = Time.now
           transition_to(:open)
         end
@@ -79,14 +82,20 @@ module Philiprehberger
           end
 
           transition_to(:half_open)
+          @half_open_in_flight = true
         when :half_open
-          # Allow one attempt through
+          # Only the first caller probes; concurrent callers are rejected
+          # until the probe resolves (success closes, failure re-opens).
+          raise OpenError, 'Circuit is half-open (probe in progress)' if @half_open_in_flight
+
+          @half_open_in_flight = true
         end
       end
 
       def record_success
         @mutex.synchronize do
           @failure_count = 0
+          @half_open_in_flight = false
           transition_to(:closed)
           @last_failure_time = nil
         end
@@ -95,6 +104,7 @@ module Philiprehberger
       def record_failure
         @mutex.synchronize do
           @failure_count += 1
+          @half_open_in_flight = false
           @last_failure_time = Time.now
 
           transition_to(:open) if @failure_count >= @failure_threshold

data/lib/philiprehberger/retry_kit/executor.rb

@@ -3,10 +3,14 @@
 module Philiprehberger
   module RetryKit
     class Executor
+      VALID_BACKOFFS = %i[exponential linear constant].freeze
+      VALID_JITTERS = %i[full equal none decorrelated].freeze
+
       attr_reader :last_attempts, :last_total_delay
 
       def initialize(**options)
         assign_options(options)
+        validate_options!
         @last_attempts = 0
         @last_total_delay = 0.0
       end
@@ -69,13 +73,36 @@ module Philiprehberger
       end
 
       def wait_and_retry(error, attempt, &)
-        delay = compute_delay(attempt)
+        delay = clamp_delay(compute_delay(attempt))
         @last_total_delay += delay
         @on_retry&.call(error, attempt + 1, delay)
         sleep(delay)
         attempt_with_retries(attempt + 1, &)
       end
 
+      # Cap the computed backoff delay to whatever time budget remains so a
+      # long backoff never sleeps past +total_timeout+/+deadline+. Raises the
+      # appropriate error immediately when the budget is already exhausted
+      # rather than sleeping.
+      def clamp_delay(delay)
+        check_total_timeout!
+        check_deadline!
+
+        [delay, remaining_timeout, remaining_deadline].compact.min
+      end
+
+      def remaining_timeout
+        return nil unless @start_time
+
+        @total_timeout - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time)
+      end
+
+      def remaining_deadline
+        return nil unless @deadline
+
+        @deadline - Time.now
+      end
+
       def assign_options(options)
         assign_core_options(options)
         assign_callback_options(options)
@@ -103,6 +130,27 @@ module Philiprehberger
         @deadline = options[:deadline]
       end
 
+      # Fail fast on invalid configuration so misconfigured retries surface at
+      # construction time instead of silently succeeding or misbehaving later.
+      def validate_options!
+        unless VALID_BACKOFFS.include?(@backoff)
+          raise ArgumentError, "Unknown backoff strategy: #{@backoff.inspect}. Use :exponential, :linear, or :constant"
+        end
+        unless VALID_JITTERS.include?(@jitter)
+          raise ArgumentError, "Unknown jitter mode: #{@jitter.inspect}. Use :full, :equal, :none, or :decorrelated"
+        end
+
+        validate_numeric_options!
+      end
+
+      def validate_numeric_options!
+        raise ArgumentError, "max_attempts must be >= 1 (got #{@max_attempts})" if @max_attempts < 1
+        raise ArgumentError, "base_delay must be >= 0 (got #{@base_delay})" if @base_delay.negative?
+        return unless @max_delay < @base_delay
+
+        raise ArgumentError, "max_delay (#{@max_delay}) must be >= base_delay (#{@base_delay})"
+      end
+
       def check_total_timeout!
         return unless @start_time
 

data/lib/philiprehberger/retry_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module RetryKit
-    VERSION = '0.8.1'
+    VERSION = '0.9.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-retry_kit
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-07-16 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