philiprehberger-webhook_builder 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c3d746e099083b6d9da206ce5b4630ca0a4c5ee2c4f1f99373af3c992d89c38
-  data.tar.gz: 23ed5e8d7b8e40f27a71cf7f4cb42c91d501ef8a5028d39d0a77cd1d08a589be
+  metadata.gz: b3008661457c2c68b820bfb48c133cc513040bb2f5ec35af8e62a4c0318241c9
+  data.tar.gz: 461cbff339dfd9fab1bccf97e68c855080ee48f3faa685fc92b2aab81c56aeb2
 SHA512:
-  metadata.gz: 7e503cd54a9fb91a78879f0ccd541a24b91a447ca30ba89c7d832a4c757d07de2a35e7c0066c8c0e13c01b130f6765afdc96b4b8e234c4ba60d492aba2d3e536
-  data.tar.gz: 6f9942dc1678940173ab109c17b236f83bf14087ed1dae8880f17a2703e8e89a87c2455e752ea7c9b6aff14f6992bd408db65bd46b0499729ec8644d27e7d561
+  metadata.gz: f68594c755f2995c19390964a63ae42ef14832eefca6a0de3c54deb74a6fd1641908bccbfd11e00b7bc4592a303fd95c552fbb7adfe652a94e7a6dac49c724bd
+  data.tar.gz: 8f6b0914eab043887af35ea57a03a7f85b2d72d0c7cbc3f8d4eecb7746a31c98ba49c0dbe6983784a07f1cb5e06bfc34094b6e302039ee2af77edf2a2ab1a29b

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-08
+
+### Added
+- `Backoff::Decorrelated` — AWS-style decorrelated jitter strategy (`delay = base + rand * (min(cap, prev * 3) - base)`); spreads retries to avoid thundering-herd patterns
+- `Client#new(backoff: :decorrelated)` — `:decorrelated` is now a recognized symbol alongside `:exponential`, `:linear`, `:fixed`, and any callable Proc
+
 ## [0.4.0] - 2026-04-22
 
 ### Added

data/README.md

@@ -86,6 +86,13 @@ client = Philiprehberger::WebhookBuilder.new(
   backoff: :fixed
 )
 
+# Decorrelated jitter (AWS-style): randomized within [base, min(cap, prev*3)]
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  backoff: :decorrelated
+)
+
 # Custom Proc backoff
 client = Philiprehberger::WebhookBuilder.new(
   url: "https://example.com/webhooks",
@@ -216,6 +223,13 @@ delivery.error          # => nil or error message
 | `.new(delay:)` | Create fixed strategy (default: delay=1) |
 | `#call(attempt)` | Returns constant delay |
 
+### `Backoff::Decorrelated`
+
+| Method | Description |
+|--------|-------------|
+| `.new(base:, max_delay:)` | Create decorrelated jitter strategy (defaults: base=1, max_delay=30) |
+| `#call(attempt)` | Returns randomized delay in `[base, min(max_delay, prev * 3)]` |
+
 ## Development
 
 ```bash

data/lib/philiprehberger/webhook_builder/backoff.rb

@@ -53,6 +53,30 @@ module Philiprehberger
         end
       end
 
+      # Decorrelated jitter backoff (AWS-style): each delay is a random value
+      # in `[base, [cap, prev * 3].min]`, which spreads retries to avoid
+      # thundering-herd effects while still trending toward the cap.
+      #
+      # See: https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+      class Decorrelated
+        # @param base [Numeric] minimum delay in seconds (default: 1)
+        # @param max_delay [Numeric] maximum delay in seconds (default: 30)
+        def initialize(base: 1, max_delay: 30)
+          @base = base.to_f
+          @max_delay = max_delay.to_f
+          @prev = @base
+        end
+
+        # @param _attempt [Integer] ignored (state is carried in @prev)
+        # @return [Float] delay in seconds
+        def call(_attempt)
+          upper = [@max_delay, @prev * 3].min
+          upper = @base if upper < @base
+          @prev = @base + (rand * (upper - @base))
+          @prev
+        end
+      end
+
       # Resolve a backoff option into a callable strategy.
       #
       # @param option [Symbol, Proc, nil] the backoff strategy
@@ -65,10 +89,14 @@ module Philiprehberger
           Linear.new
         when :fixed
           Fixed.new
+        when :decorrelated
+          Decorrelated.new
         when Proc
           option
         else
-          raise ArgumentError, "Unknown backoff strategy: #{option.inspect}. Use :exponential, :linear, :fixed, or a Proc."
+          raise ArgumentError,
+                "Unknown backoff strategy: #{option.inspect}. " \
+                'Use :exponential, :linear, :fixed, :decorrelated, or a Proc.'
         end
       end
     end

data/lib/philiprehberger/webhook_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module WebhookBuilder
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-webhook_builder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-05-08 00:00:00.000000000 Z
 dependencies: []
 description: A webhook delivery client that signs payloads with HMAC-SHA256, retries
   failed deliveries with configurable backoff strategies, supports batch delivery,