philiprehberger-retry_queue 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 933efd4881279b847d651e774a565205b246ae3859b624cc2715373549664d58
-  data.tar.gz: c24e1b713702a4775248ca23b4e88d08dab9b2e077c0f78ca866ad08ec50a629
+  metadata.gz: 96d4078aaeb7a082f0b36dc2121077882c4ae88d5acba91acdf668b2de76d42c
+  data.tar.gz: 92e49204be845308e033260af04fa8aa1d40fa328ab14a7cb2c31a5e4c54cbb7
 SHA512:
-  metadata.gz: d17e2e333cbf2cf723ea0bbb2519186a24487fc5fe1fc4410302791ba211292b8092f9d84120a713951d433a3dfb1a237d051a7f5ebe6d31cd47c3f102b93462
-  data.tar.gz: 408fb3f24b0928ecf0438a5773c5fafc6404b73139cecbfe470235bcb5476741197bb402054e8b96b1e480b74f3ac19d6564f569db9bfa0c57e4d7e512c22f72
+  metadata.gz: a43f5db92ac6e907a95b51b066852a55f9203f88f44600649dd12bfd6b93568dea33c12722869dc951b3f2927f70adca69a68a6cc423bdd4ac2463d815259319
+  data.tar.gz: 03466f8aeb298b0d4ff161b43a913967662ed59d2add9e5a9ff6cdbc7b027a849a556d370e9edd41badc3e18b409f05d43079f5b3ab28e08e0dc98839525cc4d

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-07
+
+### Added
+- `Result#failure_rate` — counterpart to `#success_rate`, returns the ratio of failed items to total. Returns `0.0` for empty batches.
+
+## [0.5.0] - 2026-04-23
+
+### Added
+- Optional `jitter:` (0.0..1.0) on `RetryQueue.process` — multiplies backoff delay by `1 + rand * jitter` to reduce thundering-herd risk.
+- `Result#empty?` and `Result#size` convenience methods.
+- YARD clarification that `max_retries: 0` means one attempt, no retries.
+
 ## [0.4.0] - 2026-04-19
 
 ### Added

data/README.md

@@ -45,6 +45,20 @@ result = Philiprehberger::RetryQueue.process(items, max_retries: 5, backoff: ->(
 end
 ```
 
+### Jitter
+
+Reduce thundering-herd risk by randomizing the backoff delay. Pass a fraction in
+`0.0..1.0`; the computed delay is multiplied by `1 + rand * jitter`. A value of
+`0.0` (default) disables jitter.
+
+```ruby
+result = Philiprehberger::RetryQueue.process(items, max_retries: 3, jitter: 0.3) do |item|
+  external_api_call(item)
+end
+```
+
+Values outside `0.0..1.0` or non-Numeric values raise `ArgumentError`.
+
 ### Selective Retry
 
 ```ruby
@@ -112,18 +126,28 @@ stats = result.stats
 ```ruby
 result = Philiprehberger::RetryQueue.process(items, max_retries: 3) { |item| call(item) }
 result.success_rate # => 0.92
+result.failure_rate # => 0.08
 ```
 
+`Result#failure_rate` is the counterpart to `#success_rate` and pairs naturally with
+it — for any non-empty Result, `success_rate + failure_rate` sums to `1.0`. Empty
+batches return `0.0` for both.
+
 ## API
 
 | Method | Description |
 |--------|-------------|
-| `.process(items, max_retries:, concurrency:, backoff:, retry_on:, on_retry:, on_failure:) { \|item\| }` | Process items with retry logic |
+| `.process(items, max_retries:, concurrency:, backoff:, retry_on:, on_retry:, on_failure:, jitter:) { \|item\| }` | Process items with retry logic |
+| `max_retries:` | Integer >= 0. `0` means one attempt with no retries (not zero attempts) |
+| `jitter:` | Numeric in `0.0..1.0`; multiplies backoff delay by `1 + rand * jitter`. Defaults to `0.0` |
 | `on_failure:` | Callable `(item, error)` invoked once per item that exhausts retries; hook errors are swallowed |
 | `Result#succeeded` | Array of successfully processed items |
 | `Result#failed` | Array of hashes with `:item`, `:error`, `:attempts` |
 | `Result#stats` | Hash with `:total`, `:succeeded`, `:failed`, `:success_rate`, `:elapsed` |
 | `Result#success_rate` | Float in `[0.0, 1.0]`; ratio of succeeded to total items (`0.0` for empty batches) |
+| `Result#failure_rate` | Ratio of failed items to total (0.0..1.0); pairs with success_rate |
+| `Result#empty?` | `true` when `stats[:total]` is 0 |
+| `Result#size` | Returns `stats[:total]` (succeeded + failed count) |
 | `Result#reprocess_failed { \|item, error\| }` | Reprocess failed items, returns a new Result |
 
 ## Development

data/lib/philiprehberger/retry_queue/processor.rb

@@ -7,7 +7,8 @@ module Philiprehberger
       # Default backoff strategy: exponential with base 0.1s.
       DEFAULT_BACKOFF = ->(attempt) { 0.1 * (2**attempt) }
 
-      # @param max_retries [Integer] maximum retry attempts per item
+      # @param max_retries [Integer] maximum retry attempts per item. `max_retries: 0` means
+      #   one attempt with no retries (not zero attempts).
       # @param concurrency [Integer] number of concurrent workers (reserved for future use)
       # @param backoff [Proc, nil] proc receiving attempt number, returns sleep duration
       # @param retry_on [Array<Class>, nil] exception classes to retry on; nil means retry all
@@ -15,8 +16,12 @@ module Philiprehberger
       # @param on_failure [Proc, nil] callable invoked with `(item, error)` once per item that
       #   exhausts retries and moves to the dead-letter list; exceptions raised by the hook are
       #   swallowed so a faulty hook cannot break the queue
-      def initialize(max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil, on_failure: nil)
+      # @param jitter [Numeric] fraction in `0.0..1.0` applied to the computed backoff delay as
+      #   `delay * (1 + rand * jitter)`. Defaults to `0.0` (no jitter).
+      def initialize(max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil, on_failure: nil,
+                     jitter: 0.0)
         raise Error, 'max_retries must be non-negative' unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ArgumentError, 'jitter must be a Numeric in 0.0..1.0' unless valid_jitter?(jitter)
 
         @max_retries = max_retries
         @concurrency = concurrency
@@ -24,6 +29,7 @@ module Philiprehberger
         @retry_on = retry_on
         @on_retry_hooks = Array(on_retry)
         @on_failure = on_failure
+        @jitter = jitter.to_f
       end
 
       # Process a collection of items with retry logic.
@@ -64,11 +70,21 @@ module Philiprehberger
 
           fire_on_retry_hooks(item, e, attempts)
 
-          sleep_duration = @backoff.call(attempts - 1)
+          sleep_duration = apply_jitter(@backoff.call(attempts - 1))
           sleep(sleep_duration) if sleep_duration.positive?
         end
       end
 
+      def apply_jitter(delay)
+        return delay if @jitter.zero?
+
+        delay * (1 + (rand * @jitter))
+      end
+
+      def valid_jitter?(jitter)
+        jitter.is_a?(Numeric) && jitter >= 0.0 && jitter <= 1.0
+      end
+
       def retryable?(error)
         return true if @retry_on.nil?
 

data/lib/philiprehberger/retry_queue/result.rb

@@ -33,6 +33,20 @@ module Philiprehberger
         }
       end
 
+      # Whether the batch processed zero items.
+      #
+      # @return [Boolean] true when no items were processed (succeeded and failed both empty)
+      def empty?
+        stats[:total].zero?
+      end
+
+      # Total number of items processed, including both succeeded and failed.
+      #
+      # @return [Integer] `stats[:total]`
+      def size
+        stats[:total]
+      end
+
       # Ratio of succeeded items to total processed items.
       #
       # Returns 0.0 for an empty batch to avoid ZeroDivisionError.
@@ -45,6 +59,18 @@ module Philiprehberger
         @succeeded.size.to_f / total
       end
 
+      # Ratio of failed items to total processed items.
+      #
+      # Returns 0.0 for an empty batch to avoid ZeroDivisionError.
+      #
+      # @return [Float] ratio in the range [0.0, 1.0]
+      def failure_rate
+        total = @succeeded.size + @failed.size
+        return 0.0 if total.zero?
+
+        @failed.size.to_f / total
+      end
+
       # Reprocess failed items by yielding each item and its last error to the block.
       # Returns a new Result with the reprocessing outcomes.
       #

data/lib/philiprehberger/retry_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module RetryQueue
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/retry_queue.rb

@@ -11,7 +11,9 @@ module Philiprehberger
     # Process items with per-item retry, backoff, and dead letter collection.
     #
     # @param items [Array] items to process
-    # @param max_retries [Integer] maximum retry attempts per item
+    # @param max_retries [Integer] maximum retry attempts per item. Note: `max_retries: 0`
+    #   means one attempt with no retries (not zero attempts); the item is processed once
+    #   and moves straight to the dead-letter list on failure.
     # @param concurrency [Integer] number of concurrent workers
     # @param backoff [Proc, nil] custom backoff strategy
     # @param retry_on [Array<Class>, nil] exception classes to retry on; others go straight to failed
@@ -19,17 +21,20 @@ module Philiprehberger
     # @param on_failure [Proc, nil] callable invoked with `(item, error)` once per item that
     #   exhausts retries and moves to the dead-letter list; exceptions raised by the hook are
     #   swallowed so a faulty hook cannot break the queue
+    # @param jitter [Numeric] fraction in `0.0..1.0` applied to the computed backoff delay as
+    #   `delay * (1 + rand * jitter)` to reduce thundering-herd risk. Defaults to `0.0` (no jitter).
     # @yield [item] block that processes a single item
     # @return [Result] processing result
     def self.process(items, max_retries: 3, concurrency: 1, backoff: nil, retry_on: nil, on_retry: nil,
-                     on_failure: nil, &block)
+                     on_failure: nil, jitter: 0.0, &block)
       processor = Processor.new(
         max_retries: max_retries,
         concurrency: concurrency,
         backoff: backoff,
         retry_on: retry_on,
         on_retry: on_retry,
-        on_failure: on_failure
+        on_failure: on_failure,
+        jitter: jitter
       )
       processor.call(items, &block)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-retry_queue
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies: []
 description: Processes collections of items with configurable per-item retry logic,
   exponential backoff, and dead letter collection for failed items. Returns detailed