rails_webhook_outbox 0.2.0 → 0.4.0

data/app/controllers/rails_webhook_outbox/base_controller.rb

@@ -0,0 +1,15 @@
+module RailsWebhookOutbox
+  class BaseController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "rails_webhook_outbox/application"
+    helper RailsWebhookOutbox::ApplicationHelper
+
+    before_action :check_dashboard_enabled
+
+    private
+
+      def check_dashboard_enabled
+        head :forbidden unless RailsWebhookOutbox.config.dashboard_enabled
+      end
+  end
+end

data/app/controllers/rails_webhook_outbox/deliveries_controller.rb

@@ -0,0 +1,46 @@
+module RailsWebhookOutbox
+  class DeliveriesController < BaseController
+    PER_PAGE = 50
+
+    def index
+      @status = params[:status] if Delivery.statuses.key?(params[:status])
+      @event = params[:event] if RailsWebhookOutbox.config.events.include?(params[:event])
+      @from = parse_date(params[:from])
+      @to = parse_date(params[:to])
+      @page = params[:page].to_i
+      @page = 1 if @page < 1
+
+      deliveries = Delivery.order(created_at: :desc)
+      deliveries = deliveries.where(status: @status) if @status
+      deliveries = deliveries.where(event: @event) if @event
+      deliveries = deliveries.where(created_at: @from..) if @from
+      deliveries = deliveries.where(created_at: ..@to.end_of_day) if @to
+
+      @total_count = deliveries.count
+      @deliveries = deliveries.limit(PER_PAGE).offset((@page - 1) * PER_PAGE)
+    end
+
+    def show
+      @delivery = Delivery.find(params[:id])
+    end
+
+    def retry
+      @delivery = Delivery.find(params[:id])
+      @delivery.update!(status: :pending, next_retry_at: nil)
+      DeliveryJob.perform_later(@delivery)
+
+      respond_to do |format|
+        format.turbo_stream
+        format.html { redirect_to delivery_path(@delivery) }
+      end
+    end
+
+    private
+
+      def parse_date(value)
+        Date.parse(value) if value.present?
+      rescue ArgumentError
+        nil
+      end
+  end
+end

data/app/controllers/rails_webhook_outbox/events_controller.rb

@@ -0,0 +1,13 @@
+module RailsWebhookOutbox
+  class EventsController < BaseController
+    def index
+      @events = RailsWebhookOutbox.config.events.map do |event|
+        {
+          name: event,
+          subscriber_count: Subscription.active.select { |s| s.subscribes_to?(event) }.size,
+          example: Delivery.where(event: event).order(created_at: :desc).first&.payload
+        }
+      end
+    end
+  end
+end

data/app/controllers/rails_webhook_outbox/overview_controller.rb

@@ -0,0 +1,7 @@
+module RailsWebhookOutbox
+  class OverviewController < BaseController
+    def show
+      @overview = Overview.new
+    end
+  end
+end

data/app/controllers/rails_webhook_outbox/subscriptions_controller.rb

@@ -0,0 +1,62 @@
+module RailsWebhookOutbox
+  class SubscriptionsController < BaseController
+    def index
+      @subscriptions = Subscription.order(created_at: :desc)
+    end
+
+    def show
+      @subscription = Subscription.find(params[:id])
+    end
+
+    def new
+      @subscription = Subscription.new
+    end
+
+    def create
+      @subscription = Subscription.new(subscription_params)
+
+      if @subscription.save
+        redirect_to subscription_path(@subscription)
+      else
+        render :new, status: 422
+      end
+    end
+
+    def edit
+      @subscription = Subscription.find(params[:id])
+    end
+
+    def update
+      @subscription = Subscription.find(params[:id])
+
+      if @subscription.update(subscription_params)
+        redirect_to subscription_path(@subscription)
+      else
+        render :edit, status: 422
+      end
+    end
+
+    def rotate_secret
+      @subscription = Subscription.find(params[:id])
+      @subscription.rotate_secret!
+      redirect_to subscription_path(@subscription)
+    rescue RailsWebhookOutbox::SecretRotationError
+      redirect_to subscription_path(@subscription, rotation_error: true)
+    end
+
+    private
+
+      def subscription_params
+        permitted = params.require(:subscription).permit(:url, :description, :active, events: [])
+        raw_events = params[:subscription][:events]
+
+        if raw_events.is_a?(String)
+          permitted[:events] = raw_events.split(",").map(&:strip).reject(&:empty?)
+        elsif permitted.key?(:events)
+          permitted[:events] = Array(permitted[:events]).map(&:to_s).map(&:strip).reject(&:empty?)
+        end
+
+        permitted
+      end
+  end
+end

data/app/helpers/rails_webhook_outbox/application_helper.rb

@@ -0,0 +1,29 @@
+module RailsWebhookOutbox
+  module ApplicationHelper
+    def inline_styles
+      dir = RailsWebhookOutbox::Engine.root.join("app/assets/stylesheets/rails_webhook_outbox")
+      css = dir.glob("_*.css").sort.map(&:read).join("\n")
+      content_tag(:style, css.html_safe)
+    end
+
+    def status_badge(status)
+      css_class = case status.to_s
+      when "delivered" then "rwo-badge--delivered"
+      when "failed"    then "rwo-badge--failed"
+      else                  "rwo-badge--pending"
+      end
+      content_tag(:span, status.to_s.capitalize, class: "rwo-badge #{css_class}")
+    end
+
+    def active_badge(active)
+      css_class = active ? "rwo-badge--delivered" : "rwo-badge--failed"
+      content_tag(:span, active ? "Active" : "Disabled", class: "rwo-badge #{css_class}")
+    end
+
+    def masked_secret(secret)
+      return "" if secret.blank?
+
+      "#{"•" * 8}#{secret.last(4)}"
+    end
+  end
+end

data/app/javascript/rails_webhook_outbox/application.js

@@ -0,0 +1,2 @@
+import "@hotwired/turbo"
+import "rails_webhook_outbox/controllers"

data/app/javascript/rails_webhook_outbox/controllers/application.js

@@ -0,0 +1,4 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+export { application }

data/app/javascript/rails_webhook_outbox/controllers/index.js

@@ -0,0 +1,4 @@
+import { application } from "rails_webhook_outbox/controllers/application"
+import SecretController from "rails_webhook_outbox/controllers/secret_controller"
+
+application.register("secret", SecretController)

data/app/javascript/rails_webhook_outbox/controllers/secret_controller.js

@@ -0,0 +1,24 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["display", "revealButton", "copiedHint"]
+  static values  = { value: String }
+
+  connect() {
+    this.masked = this.displayTarget.textContent
+    this.revealed = false
+  }
+
+  reveal() {
+    this.revealed = !this.revealed
+    this.displayTarget.textContent = this.revealed ? this.valueValue : this.masked
+    this.revealButtonTarget.textContent = this.revealed ? "Hide" : "Reveal"
+  }
+
+  copy() {
+    navigator.clipboard.writeText(this.valueValue).then(() => {
+      this.copiedHintTarget.hidden = false
+      setTimeout(() => { this.copiedHintTarget.hidden = true }, 1500)
+    })
+  }
+}

data/app/jobs/rails_webhook_outbox/delivery_job.rb

@@ -4,12 +4,21 @@ module RailsWebhookOutbox
     retry_on RailsWebhookOutbox::DeliveryError, wait: :polynomially_longer, attempts: :unlimited
 
     def perform(delivery)
+      return skip_disabled_subscription(delivery) unless delivery.subscription.active?
+
       if RailsWebhookOutbox.config.test_mode
+        record_attempt(delivery, outcome: :delivered, duration_ms: 0)
         delivery.update!(status: :delivered, attempts: delivery.attempts + 1, delivered_at: Time.current)
+        delivery.subscription.record_delivery_success!
+        notify("webhook.delivered.rails_webhook_outbox", delivery, 0)
         return
       end
 
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       response = Sender.call(delivery)
+      duration_ms = elapsed_ms(start)
+      record_attempt(delivery, outcome: :delivered, response_code: response.code.to_i,
+        response_body: response.body.truncate(1000), duration_ms: duration_ms)
       delivery.update!(
         status: :delivered,
         response_code: response.code.to_i,
@@ -17,9 +26,15 @@ module RailsWebhookOutbox
         delivered_at: Time.current,
         attempts: delivery.attempts + 1
       )
+      delivery.subscription.record_delivery_success!
+      Rails.logger.info { "[RailsWebhookOutbox] delivered event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{response.code} duration=#{duration_ms}ms" }
+      notify("webhook.delivered.rails_webhook_outbox", delivery, duration_ms)
     rescue DeliveryError => e
+      duration_ms = elapsed_ms(start)
       max_retries = RailsWebhookOutbox.config.max_retries
       final = executions >= max_retries
+      record_attempt(delivery, outcome: :failed, response_code: e.response_code,
+        response_body: e.response_body&.truncate(1000), duration_ms: duration_ms)
       delivery.update!(
         response_code: e.response_code,
         response_body: e.response_body&.truncate(1000),
@@ -27,7 +42,53 @@ module RailsWebhookOutbox
         status: final ? :failed : :pending,
         next_retry_at: final ? nil : Time.current + ((executions**4) + 2).seconds
       )
-      raise unless final
+      if final
+        Rails.logger.error { "[RailsWebhookOutbox] failed event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{e.response_code} attempts=#{delivery.attempts}" }
+        notify("webhook.failed.rails_webhook_outbox", delivery, duration_ms)
+        record_failure_and_notify_if_tripped(delivery)
+      else
+        Rails.logger.warn { "[RailsWebhookOutbox] retry event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{e.response_code} attempt=#{delivery.attempts} next_retry_at=#{delivery.next_retry_at.utc.iso8601}" }
+        raise
+      end
+    end
+
+    private
+
+    def skip_disabled_subscription(delivery)
+      delivery.update!(status: :failed, next_retry_at: nil)
+      Rails.logger.warn { "[RailsWebhookOutbox] skipped event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} reason=subscription_inactive" }
+    end
+
+    def record_attempt(delivery, outcome:, duration_ms:, response_code: nil, response_body: nil)
+      delivery.delivery_attempts.create!(
+        attempt_number: delivery.attempts + 1,
+        outcome: outcome,
+        response_code: response_code,
+        response_body: response_body,
+        duration_ms: duration_ms
+      )
+    end
+
+    def elapsed_ms(start)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+    end
+
+    def notify(event_name, delivery, duration_ms)
+      ActiveSupport::Notifications.instrument(event_name,
+        event: delivery.event,
+        subscription_id: delivery.subscription_id,
+        delivery_id: delivery.id,
+        duration: duration_ms)
+    end
+
+    def record_failure_and_notify_if_tripped(delivery)
+      return unless delivery.subscription.record_delivery_failure!
+
+      subscription = delivery.subscription
+      Rails.logger.warn { "[RailsWebhookOutbox] circuit_breaker_tripped subscription_id=#{subscription.id} consecutive_failures=#{subscription.consecutive_failures}" }
+      ActiveSupport::Notifications.instrument("webhook.circuit_breaker_tripped.rails_webhook_outbox",
+        subscription_id: subscription.id,
+        consecutive_failures: subscription.consecutive_failures)
     end
   end
 end

data/app/models/rails_webhook_outbox/delivery.rb

@@ -1,8 +1,12 @@
 module RailsWebhookOutbox
   class Delivery < ApplicationRecord
+    include ActionView::RecordIdentifier
+
     self.table_name = "webhook_outbox_deliveries"
 
     belongs_to :subscription
+    # Not `attempts`: that name is the integer counter column on this table.
+    has_many :delivery_attempts, -> { order(:attempt_number) }, dependent: :delete_all
 
     enum :status, { pending: 0, delivered: 1, failed: 2 }
 
@@ -14,10 +18,34 @@ module RailsWebhookOutbox
 
     scope :retryable, -> { pending }
 
+    after_update_commit :broadcast_row_update
+    after_update_commit :broadcast_detail_update
+    after_commit :broadcast_overview_update
+
     private
 
     def generate_idempotency_key
       self.idempotency_key ||= SecureRandom.uuid
     end
+
+    def broadcast_row_update
+      broadcast_replace_to "rails_webhook_outbox_deliveries", html: render_partial("rails_webhook_outbox/deliveries/row")
+    end
+
+    def broadcast_detail_update
+      broadcast_replace_to self, target: dom_id(self, :detail), html: render_partial("rails_webhook_outbox/deliveries/detail")
+    end
+
+    # Rendered through the engine's own controller: Turbo's default (the host app's
+    # ApplicationController) renders blank in an API-only host and has no access to
+    # the engine's route helpers.
+    def render_partial(partial)
+      BaseController.render(partial: partial, locals: { delivery: self }, formats: [:html])
+    end
+
+    def broadcast_overview_update
+      Overview.broadcast_stats
+      Overview.broadcast_recent_failures
+    end
   end
 end

data/app/models/rails_webhook_outbox/delivery_attempt.rb

@@ -0,0 +1,13 @@
+module RailsWebhookOutbox
+  # One HTTP attempt to deliver a webhook. Written by DeliveryJob so the dashboard
+  # can show the full attempt history, not just the latest result on the Delivery.
+  class DeliveryAttempt < ApplicationRecord
+    self.table_name = "webhook_outbox_delivery_attempts"
+
+    belongs_to :delivery
+
+    enum :outcome, { delivered: 0, failed: 1 }
+
+    validates :attempt_number, presence: true
+  end
+end

data/app/models/rails_webhook_outbox/overview.rb

@@ -0,0 +1,49 @@
+module RailsWebhookOutbox
+  # Read model behind the dashboard overview page. Shared by OverviewController
+  # and the Turbo Stream broadcasts so the page and its live updates can't drift.
+  class Overview
+    STREAM = "rails_webhook_outbox_overview".freeze
+    STATS_TARGET = "rwo-overview-stats".freeze
+    FAILURES_TARGET = "rwo-overview-failures".freeze
+    RECENT_FAILURES_LIMIT = 10
+
+    def self.broadcast_stats
+      broadcast_replace(STATS_TARGET, "rails_webhook_outbox/overview/stats")
+    end
+
+    def self.broadcast_recent_failures
+      broadcast_replace(FAILURES_TARGET, "rails_webhook_outbox/overview/recent_failures")
+    end
+
+    # Rendered through the engine's own controller: the host app's ApplicationController
+    # (which Turbo defaults to) may be API-only and renders partials blank, and it has no
+    # access to the engine's route helpers.
+    def self.broadcast_replace(target, partial)
+      html = BaseController.render(partial: partial, locals: { overview: new }, formats: [:html])
+      Turbo::StreamsChannel.broadcast_replace_to(STREAM, target: target, html: html)
+    end
+    private_class_method :broadcast_replace
+
+    def subscription_count
+      Subscription.count
+    end
+
+    def active_subscription_count
+      Subscription.active.count
+    end
+
+    def delivery_count(status)
+      delivery_counts.fetch(status.to_s, 0)
+    end
+
+    def recent_failures
+      Delivery.failed.includes(:subscription).order(created_at: :desc).limit(RECENT_FAILURES_LIMIT)
+    end
+
+    private
+
+    def delivery_counts
+      @delivery_counts ||= Delivery.group(:status).count
+    end
+  end
+end

data/app/models/rails_webhook_outbox/subscription.rb

@@ -2,11 +2,13 @@ module RailsWebhookOutbox
   class Subscription < ApplicationRecord
     self.table_name = "webhook_outbox_subscriptions"
 
-    URL_FORMAT = /\Ahttps?:\/\/.+/i
+    URL_FORMAT = /\Ahttps?:\/\/.+\z/i
 
     attribute :active, :boolean, default: true
 
     before_validation :generate_secret, on: :create
+    before_save :reset_consecutive_failures_on_reactivation
+    after_commit :broadcast_overview_stats
 
     validates :url, presence: true, format: { with: URL_FORMAT, message: "must be a valid HTTP or HTTPS URL" }
     validates :secret, presence: true
@@ -18,10 +20,56 @@ module RailsWebhookOutbox
       events.include?(event.to_s)
     end
 
+    def rotate_secret!(grace_period: RailsWebhookOutbox.config.secret_rotation_grace_period, force: false)
+      raise SecretRotationError if previous_secret_active? && !force
+
+      update!(
+        previous_secret: secret,
+        previous_secret_expires_at: Time.current + grace_period,
+        secret: generate_secret_value
+      )
+    end
+
+    def previous_secret_active?
+      previous_secret.present? && previous_secret_expires_at.present? && previous_secret_expires_at.future?
+    end
+
+    def signing_secrets
+      previous_secret_active? ? [secret, previous_secret] : [secret]
+    end
+
+    def record_delivery_success!
+      update!(consecutive_failures: 0) if consecutive_failures != 0
+    end
+
+    def record_delivery_failure!(threshold: RailsWebhookOutbox.config.circuit_breaker_threshold)
+      with_lock do
+        next false unless active?
+
+        increment!(:consecutive_failures)
+        next false unless threshold&.positive? && consecutive_failures >= threshold
+
+        update!(active: false)
+        true
+      end
+    end
+
     private
 
     def generate_secret
-      self.secret ||= SecureRandom.hex(32)
+      self.secret ||= generate_secret_value
+    end
+
+    def generate_secret_value
+      SecureRandom.hex(32)
+    end
+
+    def reset_consecutive_failures_on_reactivation
+      self.consecutive_failures = 0 if active_changed?(from: false, to: true)
+    end
+
+    def broadcast_overview_stats
+      Overview.broadcast_stats
     end
   end
 end

data/app/views/layouts/rails_webhook_outbox/application.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>RailsWebhookOutbox</title>
+  <link rel="icon" href="data:,">
+  <%= inline_styles %>
+  <%= javascript_importmap_tags "rails_webhook_outbox" %>
+</head>
+<body>
+  <nav class="rwo-nav">
+    <%= link_to "Overview", root_path, class: "rwo-nav-link" %>
+    <%= link_to "Subscriptions", subscriptions_path, class: "rwo-nav-link" %>
+    <%= link_to "Deliveries", deliveries_path, class: "rwo-nav-link" %>
+    <%= link_to "Events", events_path, class: "rwo-nav-link" %>
+  </nav>
+  <main class="rwo-main">
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/rails_webhook_outbox/deliveries/_detail.html.erb

@@ -0,0 +1,47 @@
+<div id="<%= dom_id(delivery, :detail) %>">
+  <div class="rwo-header rwo-header-row">
+    <h1><%= delivery.event %></h1>
+    <%= status_badge(delivery.status) %>
+  </div>
+
+  <div class="rwo-detail-grid">
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Subscription</div>
+      <div class="rwo-detail-value"><%= link_to delivery.subscription.url, subscription_path(delivery.subscription) %></div>
+    </div>
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Attempts</div>
+      <div class="rwo-detail-value"><%= delivery.attempts %></div>
+    </div>
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Response Code</div>
+      <div class="rwo-detail-value"><%= delivery.response_code || "—" %></div>
+    </div>
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Delivered At</div>
+      <div class="rwo-detail-value"><%= delivery.delivered_at&.strftime("%Y-%m-%d %H:%M:%S") || "—" %></div>
+    </div>
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Next Retry At</div>
+      <div class="rwo-detail-value"><%= delivery.next_retry_at&.strftime("%Y-%m-%d %H:%M:%S") || "—" %></div>
+    </div>
+    <div class="rwo-detail-item">
+      <div class="rwo-detail-label">Created At</div>
+      <div class="rwo-detail-value"><%= delivery.created_at.strftime("%Y-%m-%d %H:%M:%S") %></div>
+    </div>
+  </div>
+
+  <%= render "rails_webhook_outbox/deliveries/timeline", delivery: delivery %>
+
+  <h2 class="rwo-section-title">Payload</h2>
+  <pre class="rwo-monospace rwo-code-block"><%= JSON.pretty_generate(delivery.payload) %></pre>
+
+  <% if delivery.response_body.present? %>
+    <h2 class="rwo-section-title">Response Body</h2>
+    <pre class="rwo-monospace rwo-code-block"><%= delivery.response_body %></pre>
+  <% end %>
+
+  <% if delivery.failed? %>
+    <%= button_to "Retry Delivery", retry_delivery_path(delivery), class: "rwo-btn" %>
+  <% end %>
+</div>

data/app/views/rails_webhook_outbox/deliveries/_row.html.erb

@@ -0,0 +1,7 @@
+<tr id="<%= dom_id(delivery) %>">
+  <td><%= link_to delivery.event, delivery_path(delivery), class: "rwo-path" %></td>
+  <td class="rwo-muted"><%= delivery.subscription.url %></td>
+  <td><%= status_badge(delivery.status) %></td>
+  <td class="rwo-muted"><%= delivery.attempts %></td>
+  <td class="rwo-muted"><%= delivery.created_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+</tr>

data/app/views/rails_webhook_outbox/deliveries/_timeline.html.erb

@@ -0,0 +1,41 @@
+<% attempts = delivery.delivery_attempts.to_a %>
+
+<h2 class="rwo-section-title">Timeline</h2>
+
+<ol class="rwo-timeline">
+  <li class="rwo-timeline-item">
+    <div class="rwo-timeline-title">Queued</div>
+    <div class="rwo-muted"><%= delivery.created_at.strftime("%Y-%m-%d %H:%M:%S") %></div>
+  </li>
+
+  <% attempts.each do |attempt| %>
+    <li class="rwo-timeline-item rwo-timeline-item--<%= attempt.outcome %>">
+      <div class="rwo-timeline-title">
+        Attempt <%= attempt.attempt_number %>
+        <%= status_badge(attempt.outcome) %>
+      </div>
+      <div class="rwo-muted">
+        <%= attempt.created_at.strftime("%Y-%m-%d %H:%M:%S") %>
+        &middot; HTTP <%= attempt.response_code || "—" %>
+        <% if attempt.duration_ms %>&middot; <%= attempt.duration_ms %> ms<% end %>
+      </div>
+      <% if attempt.response_body.present? %>
+        <details class="rwo-timeline-response">
+          <summary class="rwo-muted">Response body</summary>
+          <pre class="rwo-monospace rwo-code-block"><%= attempt.response_body %></pre>
+        </details>
+      <% end %>
+    </li>
+  <% end %>
+
+  <% if delivery.pending? && delivery.next_retry_at %>
+    <li class="rwo-timeline-item rwo-timeline-item--scheduled">
+      <div class="rwo-timeline-title">Retry scheduled</div>
+      <div class="rwo-muted"><%= delivery.next_retry_at.strftime("%Y-%m-%d %H:%M:%S") %></div>
+    </li>
+  <% end %>
+</ol>
+
+<% if attempts.empty? && delivery.attempts.positive? %>
+  <p class="rwo-muted">Attempt history is recorded from version 0.4.0; this delivery was attempted before then.</p>
+<% end %>