rails_webhook_outbox 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 743d24ea18d5fad259efd9369fc228866eeb883e6f5911d96d081e304a62aca4
-  data.tar.gz: 9bd087f6a44e6eedb95b1ccd97fd9e52423c547f67f3d4d384eb5b407fdfee1e
+  metadata.gz: 78b2ef77e9c0d4c8e0805566fd1da1e813b5e60163b3032f0584267a925803e3
+  data.tar.gz: 9a3154d6f2029879ed18aaf83548e9a950f27a27057c9a3c517363eaca21ca3e
 SHA512:
-  metadata.gz: 02b57c5bfb462a475dde3036a6ee5f18fe033faaaa808d03d1bd45417f687162210ad6987aee0135775a5d2298fa989d65ac24c06762201cffcad05bb66938f8
-  data.tar.gz: 5fdaac46aa8ad0591e5c0837df73d9d6bd10a9af15f02f96415ac45ced02e85608198bc8beed2baaa42449e93986ac3a816b9da0e66ae8ff5ff636c2c6807a1a
+  metadata.gz: 4e527d2e705089dc96fbba1f913c15d03a5c1ed54b221c4e26dbd1b97d3aae10ad58dc8f910d1db090d6846438302fbef079c78cac0a58b6bca0b50c7c941b2d
+  data.tar.gz: fd935881ea40dc8e68fd3b4df3a240adf2f23b7c60e5ce938865a1f59b2f74e4e3a62123bffa6553428bb52b709d4e289adb5219bcaf75ec64b16ca38ca7c265

data/README.md

@@ -21,6 +21,7 @@ A Rails engine for sending outgoing webhooks with HMAC signing, ActiveJob-based
 - [HMAC Signing](#hmac-signing)
 - [Usage](#usage)
 - [Manual Dispatch](#manual-dispatch)
+- [Testing](#testing)
 - [Development](#development)
   - [Dummy App](#dummy-app)
 - [Contributing](#contributing)
@@ -64,9 +65,14 @@ RailsWebhookOutbox.configure do |config|
   config.retry_backoff      = :exponential
   config.request_timeout    = 5
   config.delivery_job_queue = :webhooks
+  config.max_payload_size   = 65_536  # bytes; set to nil or 0 to disable
 end
 ```
 
+When `config.events` is set, both `dispatch` and `Dispatchable` callbacks will raise `ArgumentError` if the event name is not in the list. Leave `config.events` empty to skip validation entirely.
+
+If the JSON-serialised payload exceeds `config.max_payload_size` bytes, `RailsWebhookOutbox::PayloadSizeError` is raised before any `Delivery` record is created or job enqueued. The default limit is 64 KB (`65_536` bytes).
+
 [Back to top](#table-of-contents)
 
 ## Subscriptions
@@ -146,7 +152,7 @@ The job uses polynomial backoff (`:polynomially_longer`) between retries — wai
 | n (`max_retries`) | non-2xx response | `failed` — no further retry |
 | any | 2xx response | `delivered` |
 
-Every attempt (success or failure) increments `delivery.attempts` and stores the `response_code` and `response_body`. Successful deliveries also set `delivered_at`.
+Every attempt (success or failure) increments `delivery.attempts` and stores the `response_code` and `response_body`. Successful deliveries also set `delivered_at`. Retryable failures set `next_retry_at` to the estimated time of the next attempt (based on the polynomial formula `executions⁴ + 2` seconds); it is cleared to `nil` once all retries are exhausted.
 
 Enqueue a delivery manually:
 
@@ -175,6 +181,8 @@ X-Webhook-Timestamp: 1719100800
 }
 ```
 
+`X-Webhook-Delivery` is the delivery's `idempotency_key` — a UUID generated once when the `Delivery` record is created and reused on every retry attempt. Subscribers can use this value to deduplicate incoming webhooks.
+
 Non-2xx responses raise `RailsWebhookOutbox::DeliveryError`, which carries `response_code` and `response_body` for logging and retry decisions.
 
 [Back to top](#table-of-contents)
@@ -257,12 +265,52 @@ RailsWebhookOutbox.dispatch("payment.completed", {
 })
 ```
 
-`dispatch` finds every active `Subscription` that includes the given event, creates a `Delivery` record for each one, and enqueues a `DeliveryJob`. Subscriptions that are inactive or do not subscribe to the event are skipped silently.
+`dispatch` validates the event name against `config.events` (if configured), then finds every active `Subscription` that includes the given event, creates a `Delivery` record for each one, and enqueues a `DeliveryJob`. Subscriptions that are inactive or do not subscribe to the event are skipped silently.
+
+You can also validate an event name directly without dispatching:
+
+```ruby
+RailsWebhookOutbox.validate_event!("payment.completed")
+# raises ArgumentError if the event is not in config.events
+```
 
 This is the same delivery pipeline used by `Dispatchable` callbacks, so retries, HMAC signing, and delivery logging all apply.
 
 [Back to top](#table-of-contents)
 
+## Testing
+
+Enable test mode in your `rails_helper.rb` to suppress HTTP calls and DB writes during specs:
+
+```ruby
+require "rails_webhook_outbox/rspec_matchers"
+
+RailsWebhookOutbox.configure { |c| c.test_mode = true }
+
+RSpec.configure do |config|
+  config.before { RailsWebhookOutbox::Testing.clear_deliveries! }
+end
+```
+
+When `test_mode` is `true`, dispatched events are captured in memory instead of creating `Delivery` records or enqueuing jobs. Use the `dispatch_webhook` matcher to assert on them:
+
+```ruby
+expect { order.save! }.to dispatch_webhook("order.created")
+expect { order.save! }.to dispatch_webhook("order.created").with_payload({ id: order.id })
+expect { order.save! }.not_to dispatch_webhook("order.updated")
+```
+
+Inspect captured events directly if needed:
+
+```ruby
+RailsWebhookOutbox::Testing.deliveries
+# => [{ event: "order.created", payload: { "id" => 1, ... } }]
+```
+
+`DeliveryJob` also respects `test_mode` — if a job is enqueued and performed directly in a test, it marks the delivery as `delivered` without making an HTTP call.
+
+[Back to top](#table-of-contents)
+
 ## Development
 
 ```bash

data/app/jobs/rails_webhook_outbox/delivery_job.rb

@@ -4,6 +4,11 @@ module RailsWebhookOutbox
     retry_on RailsWebhookOutbox::DeliveryError, wait: :polynomially_longer, attempts: :unlimited
 
     def perform(delivery)
+      if RailsWebhookOutbox.config.test_mode
+        delivery.update!(status: :delivered, attempts: delivery.attempts + 1, delivered_at: Time.current)
+        return
+      end
+
       response = Sender.call(delivery)
       delivery.update!(
         status: :delivered,
@@ -14,13 +19,15 @@ module RailsWebhookOutbox
       )
     rescue DeliveryError => e
       max_retries = RailsWebhookOutbox.config.max_retries
+      final = executions >= max_retries
       delivery.update!(
         response_code: e.response_code,
         response_body: e.response_body&.truncate(1000),
         attempts: delivery.attempts + 1,
-        status: executions >= max_retries ? :failed : :pending
+        status: final ? :failed : :pending,
+        next_retry_at: final ? nil : Time.current + ((executions**4) + 2).seconds
       )
-      raise if executions < max_retries
+      raise unless final
     end
   end
 end

data/app/models/rails_webhook_outbox/delivery.rb

@@ -6,9 +6,18 @@ module RailsWebhookOutbox
 
     enum :status, { pending: 0, delivered: 1, failed: 2 }
 
+    before_validation :generate_idempotency_key, on: :create
+
     validates :event, presence: true
     validates :payload, presence: true
+    validates :idempotency_key, presence: true
 
     scope :retryable, -> { pending }
+
+    private
+
+    def generate_idempotency_key
+      self.idempotency_key ||= SecureRandom.uuid
+    end
   end
 end

data/db/migrate/20260629000002_add_idempotency_key_to_webhook_outbox_deliveries.rb

@@ -0,0 +1,6 @@
+class AddIdempotencyKeyToWebhookOutboxDeliveries < ActiveRecord::Migration[7.2]
+  def change
+    add_column :webhook_outbox_deliveries, :idempotency_key, :string
+    add_index :webhook_outbox_deliveries, :idempotency_key, unique: true
+  end
+end

data/lib/generators/rails_webhook_outbox/install/install_generator.rb

@@ -16,11 +16,11 @@ module RailsWebhookOutbox
 
       def copy_migrations
         migration_template(
-          "create_webhook_outbox_subscriptions.rb",
+          "create_webhook_outbox_subscriptions.rb.tt",
           "db/migrate/create_webhook_outbox_subscriptions.rb"
         )
         migration_template(
-          "create_webhook_outbox_deliveries.rb",
+          "create_webhook_outbox_deliveries.rb.tt",
           "db/migrate/create_webhook_outbox_deliveries.rb"
         )
       end

data/lib/generators/rails_webhook_outbox/install/templates/{create_webhook_outbox_deliveries.rb → create_webhook_outbox_deliveries.rb.tt}

@@ -8,6 +8,7 @@ class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[<%= ActiveRecord::
       t.integer :response_code
       t.text :response_body
       t.integer :attempts, null: false, default: 0
+      t.string :idempotency_key
       t.datetime :delivered_at
       t.datetime :next_retry_at
       t.timestamps
@@ -17,4 +18,4 @@ class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[<%= ActiveRecord::
     add_index :webhook_outbox_deliveries, :event
     add_index :webhook_outbox_deliveries, [:subscription_id, :created_at]
   end
-end
+end

data/lib/generators/rails_webhook_outbox/install/templates/initializer.rb

@@ -19,4 +19,12 @@ RailsWebhookOutbox.configure do |config|
 
   # ActiveJob queue for delivery jobs.
   config.delivery_job_queue = :webhooks
+
+  # Maximum payload size in bytes. Raises PayloadSizeError before enqueuing if exceeded.
+  # Set to nil or 0 to disable.
+  config.max_payload_size = 65_536
+
+  # Set to true in test environments to suppress HTTP calls and capture dispatched events
+  # in RailsWebhookOutbox::Testing.deliveries instead of creating DB records or jobs.
+  # config.test_mode = false
 end

data/lib/rails_webhook_outbox/configuration.rb

@@ -5,7 +5,7 @@ module RailsWebhookOutbox
 
     attr_accessor :events, :signing_algorithm, :signing_header,
                   :max_retries, :retry_backoff, :request_timeout,
-                  :delivery_job_queue
+                  :delivery_job_queue, :max_payload_size, :test_mode
 
     def initialize
       @events = []
@@ -15,6 +15,8 @@ module RailsWebhookOutbox
       @retry_backoff = :exponential
       @request_timeout = 5
       @delivery_job_queue = :webhooks
+      @max_payload_size = 65_536
+      @test_mode = false
     end
 
     def signing_algorithm=(value)

data/lib/rails_webhook_outbox/dispatchable.rb

@@ -24,7 +24,15 @@ module RailsWebhookOutbox
     def _dispatch_webhook(event, condition)
       return if condition && !instance_exec(&condition)
 
+      RailsWebhookOutbox.validate_event!(event)
+
       payload = webhook_payload
+      RailsWebhookOutbox.validate_payload_size!(payload)
+
+      if RailsWebhookOutbox.config.test_mode
+        RailsWebhookOutbox::Testing.deliveries << { event: event.to_s, payload: payload }
+        return
+      end
 
       Subscription.active.each do |subscription|
         next unless subscription.subscribes_to?(event)

data/lib/rails_webhook_outbox/payload_size_error.rb

@@ -0,0 +1,7 @@
+module RailsWebhookOutbox
+  class PayloadSizeError < StandardError
+    def initialize(size, max)
+      super("Payload too large: #{size} bytes exceeds the #{max}-byte limit")
+    end
+  end
+end

data/lib/rails_webhook_outbox/rspec_matchers.rb

@@ -0,0 +1,32 @@
+require "rails_webhook_outbox/testing"
+
+RSpec::Matchers.define :dispatch_webhook do |expected_event|
+  chain :with_payload do |payload|
+    @expected_payload = payload
+  end
+
+  match do |block|
+    before = RailsWebhookOutbox::Testing.deliveries.dup
+    block.call
+    @dispatched = RailsWebhookOutbox::Testing.deliveries.drop(before.size)
+    @dispatched.any? do |d|
+      d[:event] == expected_event.to_s &&
+        (@expected_payload.nil? || d[:payload] == @expected_payload)
+    end
+  end
+
+  supports_block_expectations
+
+  failure_message do
+    if @dispatched.empty?
+      "expected #{expected_event.inspect} webhook to be dispatched, but no webhooks were dispatched"
+    else
+      events = @dispatched.map { |d| d[:event].inspect }.join(", ")
+      "expected #{expected_event.inspect} webhook to be dispatched, but dispatched: #{events}"
+    end
+  end
+
+  failure_message_when_negated do
+    "expected #{expected_event.inspect} webhook not to be dispatched, but it was"
+  end
+end

data/lib/rails_webhook_outbox/sender.rb

@@ -37,7 +37,7 @@ module RailsWebhookOutbox
       req["Content-Type"] = "application/json"
       req["X-Webhook-Signature"] = Signature.header_value(body, @delivery.subscription.secret)
       req["X-Webhook-Event"] = @delivery.event
-      req["X-Webhook-Delivery"] = SecureRandom.uuid
+      req["X-Webhook-Delivery"] = @delivery.idempotency_key
       req["X-Webhook-Timestamp"] = Time.now.utc.to_i.to_s
       req.body = body
       req

data/lib/rails_webhook_outbox/testing.rb

@@ -0,0 +1,13 @@
+module RailsWebhookOutbox
+  module Testing
+    class << self
+      def deliveries
+        @deliveries ||= []
+      end
+
+      def clear_deliveries!
+        @deliveries = []
+      end
+    end
+  end
+end

data/lib/rails_webhook_outbox/version.rb

@@ -1,3 +1,3 @@
 module RailsWebhookOutbox
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/rails_webhook_outbox.rb

@@ -2,6 +2,8 @@ require "rails_webhook_outbox/version"
 require "rails_webhook_outbox/configuration"
 require "rails_webhook_outbox/signature"
 require "rails_webhook_outbox/delivery_error"
+require "rails_webhook_outbox/payload_size_error"
+require "rails_webhook_outbox/testing"
 require "rails_webhook_outbox/sender"
 require "rails_webhook_outbox/dispatchable"
 require "rails_webhook_outbox/engine"
@@ -22,7 +24,31 @@ module RailsWebhookOutbox
       @configuration = Configuration.new
     end
 
+    def validate_event!(event)
+      registered = config.events
+      return if registered.empty?
+      return if registered.include?(event.to_s)
+
+      raise ArgumentError, "Unknown event #{event.inspect}. Registered events: #{registered.join(", ")}"
+    end
+
+    def validate_payload_size!(payload)
+      max = config.max_payload_size
+      return unless max && max > 0
+
+      size = JSON.generate(payload).bytesize
+      raise PayloadSizeError.new(size, max) if size > max
+    end
+
     def dispatch(event, payload)
+      validate_event!(event)
+      validate_payload_size!(payload)
+
+      if config.test_mode
+        Testing.deliveries << { event: event.to_s, payload: payload }
+        return
+      end
+
       Subscription.active.each do |subscription|
         next unless subscription.subscribes_to?(event)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_webhook_outbox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -44,17 +44,21 @@ files:
 - config/routes.rb
 - db/migrate/20260624000001_create_webhook_outbox_subscriptions.rb
 - db/migrate/20260624000002_create_webhook_outbox_deliveries.rb
+- db/migrate/20260629000002_add_idempotency_key_to_webhook_outbox_deliveries.rb
 - lib/generators/rails_webhook_outbox/install/install_generator.rb
-- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_deliveries.rb
-- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_subscriptions.rb
+- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_deliveries.rb.tt
+- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_subscriptions.rb.tt
 - lib/generators/rails_webhook_outbox/install/templates/initializer.rb
 - lib/rails_webhook_outbox.rb
 - lib/rails_webhook_outbox/configuration.rb
 - lib/rails_webhook_outbox/delivery_error.rb
 - lib/rails_webhook_outbox/dispatchable.rb
 - lib/rails_webhook_outbox/engine.rb
+- lib/rails_webhook_outbox/payload_size_error.rb
+- lib/rails_webhook_outbox/rspec_matchers.rb
 - lib/rails_webhook_outbox/sender.rb
 - lib/rails_webhook_outbox/signature.rb
+- lib/rails_webhook_outbox/testing.rb
 - lib/rails_webhook_outbox/version.rb
 - lib/tasks/rails_webhook_outbox_tasks.rake
 homepage: https://github.com/eclectic-coding/rails_webhook_outbox