philiprehberger-webhook_builder 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7754a65fd17d3f711872d837db0a95670d245eab1da96df4d42c723b8d7f9f3d
-  data.tar.gz: 8be04c1b22974980e572ca5073279d995f6e8f67d8853742de62297e5951a532
+  metadata.gz: b3008661457c2c68b820bfb48c133cc513040bb2f5ec35af8e62a4c0318241c9
+  data.tar.gz: 461cbff339dfd9fab1bccf97e68c855080ee48f3faa685fc92b2aab81c56aeb2
 SHA512:
-  metadata.gz: 5f756201c37028a4f44d5975200d24fb811d87ecbc13467b9a9f3e5c792333c26dc546177871b9bda42d4bef3da1093202aa5f82279622521bf5c443d4fe61f8
-  data.tar.gz: c09e9a31e51d343140eb0beaa1db83560bd7a35dca976f00332534a888ece0eb8263a9701a6b5bf14720388ad381245b44b089689700fa0298ff9a5b16130742
+  metadata.gz: f68594c755f2995c19390964a63ae42ef14832eefca6a0de3c54deb74a6fd1641908bccbfd11e00b7bc4592a303fd95c552fbb7adfe652a94e7a6dac49c724bd
+  data.tar.gz: 8f6b0914eab043887af35ea57a03a7f85b2d72d0c7cbc3f8d4eecb7746a31c98ba49c0dbe6983784a07f1cb5e06bfc34094b6e302039ee2af77edf2a2ab1a29b

data/CHANGELOG.md

@@ -7,6 +7,17 @@ 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
+- `Client#signature_for(body:)` — compute the HMAC-SHA256 signature this client would send for a given body without performing a delivery.
+
 ## [0.3.0] - 2026-04-18
 
 ### 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",
@@ -134,6 +141,24 @@ receiver.verify_signature(body: body, signature: signature) # => true
 receiver.verify_signature(body: body, signature: "tampered") # => false
 ```
 
+You can also compute the signature the client would send for a body without
+performing a delivery — useful for preparing payloads offline or mirroring
+`verify_signature`:
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "shared-signing-secret"
+)
+
+body = '{"event":"order.created","payload":{"id":1}}'
+signature = client.signature_for(body: body)
+
+client.verify_signature(body: body, signature: signature) # => true
+```
+
 ### Delivery Tracking
 
 ```ruby
@@ -164,6 +189,7 @@ delivery.error          # => nil or error message
 | `#deliver(event:, payload:, headers:)` | Deliver a webhook event and return a Delivery |
 | `#deliver_batch(events)` | Deliver multiple events concurrently and return an array of Delivery results |
 | `#verify_signature(body:, signature:)` | Constant-time HMAC-SHA256 verification of an incoming signature; returns `true`/`false` and never raises |
+| `#signature_for(body:)` | Compute the HMAC-SHA256 signature for a body without sending |
 
 ### `Delivery`
 
@@ -197,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/client.rb

@@ -153,6 +153,18 @@ module Philiprehberger
         OpenSSL.fixed_length_secure_compare(expected, signature)
       end
 
+      # Compute the HMAC-SHA256 hex signature this client would send for the given body.
+      #
+      # Mirrors +verify_signature+: the signature returned by +signature_for(body:)+
+      # will verify against the same body. Useful when preparing payloads offline or
+      # re-computing signatures without sending a request.
+      #
+      # @param body [String] the raw request body
+      # @return [String] the hex-encoded HMAC signature
+      def signature_for(body:)
+        sign(body)
+      end
+
       private
 
       # Sign the request body with HMAC-SHA256.

data/lib/philiprehberger/webhook_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module WebhookBuilder
-    VERSION = '0.3.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-19 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,