fuik 0.12.0 → 0.13.0

data/app/controllers/fuik/retries_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fuik
+  class RetriesController < Fuik.configuration.events_controller_parent.constantize
+    def create
+      webhook_event = WebhookEvent.find(params[:event_id])
+      webhook_event.retry!
+
+      redirect_to event_path(webhook_event)
+    end
+  end
+end

data/app/controllers/fuik/webhooks_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Fuik
-  class WebhooksController < Fuik::Engine.config.webhooks_controller_parent.constantize
+  class WebhooksController < Fuik.configuration.webhooks_controller_parent.constantize
     include EventType
 
     skip_before_action :verify_authenticity_token
@@ -17,14 +17,29 @@ module Fuik
         headers: headers
       )
 
-      process_later!(webhook_event)
+      Notifications.received(
+        provider: params[:provider],
+        event_id: event_id,
+        event_type: event_type,
+        webhook_event: webhook_event
+      )
+
+      webhook_event.process_later!
 
       head :ok
     rescue Fuik::InvalidSignature
+      Notifications.signature_invalid(
+        provider: params[:provider],
+        event_id: event_id
+      )
       head :unauthorized
     rescue ActiveRecord::RecordNotUnique
       head :ok
-    rescue
+    rescue => error
+      Notifications.receive_error(
+        provider: request.path_parameters[:provider],
+        error: error
+      )
       head :internal_server_error
     end
 
@@ -60,27 +75,16 @@ module Fuik
     end
 
     def process!(webhook_event)
-      event_class = event_class_for(webhook_event.provider, webhook_event.event_type)
+      event_class = WebhookEvent.event_class_for(webhook_event.provider, webhook_event.event_type)
       return unless event_class
 
       event_class.new(webhook_event).process!
     end
 
-    def process_later!(webhook_event)
-      event_class = event_class_for(webhook_event.provider, webhook_event.event_type)
-      return unless event_class
-
-      WebhookProcessingJob.perform_later(event_class.name, webhook_event)
-    end
-
     def url_encoded_body?
       request.media_type == "application/x-www-form-urlencoded"
     end
 
-    def event_class_for(provider, event_type)
-      "#{provider.camelize}::#{event_type.tr("./:-[]", "_").camelize}".safe_constantize
-    end
-
     def should_verify? = base_class&.respond_to?(:verify!)
 
     def base_class

data/app/jobs/fuik/webhook_processing_job.rb

@@ -1,7 +1,21 @@
 module Fuik
   class WebhookProcessingJob < ApplicationJob
+    queue_as :default
+
+    discard_on ActiveJob::DeserializationError
+
     def perform(event_class_name, webhook_event)
       Object.const_get(event_class_name).new(webhook_event).process!
+    rescue => error
+      webhook_event.failed!(error)
+
+      Notifications.failed(
+        webhook_event: webhook_event,
+        event_class: event_class_name,
+        error: error
+      )
+
+      raise
     end
   end
 end

data/app/models/fuik/event.rb

@@ -4,14 +4,50 @@ module Fuik
   class Event
     using DotAccess
 
+    class_attribute :event_type_config, default: nil
+    class_attribute :event_id_config, default: nil
+
+    class << self
+      def event_type(key = nil, **options)
+        self.event_type_config = key || options
+      end
+
+      def event_id(key = nil, **options)
+        self.event_id_config = key || options
+      end
+    end
+
     def initialize(webhook_event)
       @webhook_event = webhook_event
     end
 
+    # Called when the webhook event is processed. Override to handle the event
+    # payload and transition the event's status to processed or failed.
+    #
+    # @return [void]
+    #
+    # @example Implementing a checkout.session.completed handler
+    #   def process!
+    #     User.find_by(id: payload.client_reference_id).tap do |user|
+    #       user.activate_subscription!
+    #       user.send_welcome_email
+    #     end
+    #
+    #     @webhook_event.processed!
+    #   end
     def process!
       raise NotImplementedError, "#{self.class} must implement #process!"
     end
 
+    # Access the webhook payload with dot notation or standard hash access.
+    #
+    # @return [Fuik::DotAccess::AccessPayload] the parsed JSON body wrapped in a dot-accessible object
+    #
+    # @example Dot notation
+    #   payload.customer.email
+    #
+    # @example Hash access
+    #   payload["line_items"][0]["product_id"]
     def payload
       @webhook_event.payload.to_dot
     end

data/app/models/fuik/webhook_event/filterable.rb

@@ -7,10 +7,9 @@ module Fuik
 
       class_methods do
         def filtered(params)
-          events = all
-          events = events.where(status: params[:status]) if params[:status].present?
-          events = events.where(provider: params[:provider]) if params[:provider].present?
-          events
+          filters = %w[status provider event_id event_type]
+
+          where(params.permit(*filters).compact_blank.transform_values { it.split(",") })
         end
 
         def options_for_select

data/app/models/fuik/webhook_event.rb

@@ -4,6 +4,10 @@ module Fuik
   class WebhookEvent < ApplicationRecord
     self.table_name = "fuik_webhook_events"
 
+    def self.event_class_for(provider, event_type)
+      "#{provider.camelize}::#{event_type.tr("./:-[]", "_").camelize}".safe_constantize
+    end
+
     include Filterable
 
     enum :status, %w[pending processed failed].index_by(&:itself), default: "pending"
@@ -17,12 +21,39 @@ module Fuik
       {}
     end
 
+    # Mark the event as successfully processed.
+    #
+    # @return [Boolean] true if the update succeeded
     def processed!
       update!(status: "processed")
     end
 
-    def failed!(error)
+    # Mark the event as failed and record the error.
+    #
+    # @param error [String, nil] optional error message or object
+    #
+    # @return [Boolean] true if the update succeeded
+    def failed!(error = nil)
       update!(status: "failed", error: error.to_s)
     end
+
+    # Retry a failed event. Resets its status back to pending, clears the error,
+    # and enqueues processing via WebhookProcessingJob.
+    #
+    # @raise [RuntimeError] if the event is not in a failed state
+    #
+    # @return [Boolean] true if the update succeeded
+    def retry!
+      raise "Can only retry failed events" unless failed?
+
+      update!(status: "pending", error: nil)
+      process_later!
+    end
+
+    def process_later!
+      event_class = self.class.event_class_for(provider, event_type)
+
+      Fuik.webhook_processing_job_class.constantize.perform_later(event_class.name, self) if event_class
+    end
   end
 end

data/app/views/fuik/events/index.html.erb

@@ -1,4 +1,4 @@
-<h1>Webhooks</h1>
+<h1 class="heading"><%= Fuik.configuration.title %></h1>
 
 <%= render "filters" %>
 
@@ -20,4 +20,8 @@
       <% end %>
     </li>
   <% end %>
+
+  <li class="empty-state">
+    <p>No webhook events…</p>
+  </li>
 </ul>

data/app/views/fuik/events/show.html.erb

@@ -1,34 +1,57 @@
-<% content_for :title, "#{@webhook_event.provider} / #{@webhook_event.event_type} | Fuik Admin" %>
+<% content_for :title, "#{@webhook_event.provider} / #{@webhook_event.event_type} - #{Fuik.configuration.title}" %>
 
-<h1>
-  <%= link_to "Webhooks", root_path %> / <%= @webhook_event.event_id %>
+<h1 class="heading">
+  <%= link_to Fuik.configuration.title, root_path %> <span class="divider">/</span> <%= @webhook_event.event_id %>
 </h1>
 
-<dl>
-  <dt>Provider</dt>
-  <dd><%= @webhook_event.provider %></dd>
+<dl class="details">
+  <dt class="description">Provider</dt>
+  <dd class="value">
+    <%= fuik_icon @webhook_event.provider %> <%= @webhook_event.provider %>
+  </dd>
 
-  <dt>Event ID</dt>
-  <dd><%= tag.code @webhook_event.event_id, id: "event_id" %> <%= render "copy_button", target: "event_id" %></dd>
+  <dt class="description">Event ID</dt>
+  <dd class="value">
+    <%= tag.code @webhook_event.event_id, id: "event_id", data: {action: "copy", copy_delay: 5000} %> <%= render "copy_button", target: "event_id" %>
+  </dd>
 
-  <dt>Type</dt>
-  <dd><%= @webhook_event.event_type %></dd>
+  <dt class="description">Type</dt>
+  <dd class="value">
+    <%= @webhook_event.event_type %>
+  </dd>
 
-  <dt>Status</dt>
-  <dd class="status" data-status="<%= @webhook_event.status %>"><%= @webhook_event.status %></dd>
+  <dt class="description">Status</dt>
+  <dd class="value status" data-status="<%= @webhook_event.status %>">
+    <%= tag.span @webhook_event.status %>
 
-  <dt>Created</dt>
-  <dd><%= @webhook_event.created_at.strftime("%Y-%m-%d %H:%M:%S") %></dd>
+    <%= button_to event_retries_path(@webhook_event), method: :post, class: "retry-button" do %>
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M224,128a96,96,0,0,1-94.71,96H128A95.38,95.38,0,0,1,62.1,197.6a8,8,0,0,1,11-11.63A80,80,0,1,0,71.43,71.39a3.07,3.07,0,0,1-.26.25L44.59,96H72a8,8,0,0,1,0,16H24a8,8,0,0,1-8-8V56a8,8,0,0,1,16,0v29.8L60.17,60.29h0A96,96,0,0,1,224,128Z"/></svg>
 
-  <dt>Payload</dt>
-  <dd><pre id="payload" data-root="payload" class="json-highlight"><%= highlighted(JSON.pretty_generate(@webhook_event.payload)) %></pre> <div class="actions"><%= button_to downloads_path, params: { event_id: @webhook_event.id }, method: :post, class: "" do %><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34Zm-56,83.32-24,24a8,8,0,0,1-11.32,0l-24-24a8,8,0,0,1,11.32-11.32L120,164.69V120a8,8,0,0,1,16,0v44.69l10.34-10.35a8,8,0,0,1,11.32,11.32ZM152,88V44l44,44Z"/></svg><% end %> <%= render "copy_button", target: "payload" %></div></dd>
+      Retry
+    <% end if @webhook_event.failed? %>
+  </dd>
 
-  <dt>Headers</dt>
-  <dd><pre id="headers" class="json-highlight"><%= highlighted JSON.pretty_generate(@webhook_event.headers) %></pre> <div class="actions"><%= render "copy_button", target: "headers" %></div></dd>
+  <dt class="description">Created</dt>
+  <dd class="value">
+    <%= @webhook_event.created_at.strftime("%Y-%m-%d %H:%M:%S") %>
+  </dd>
+
+  <dt class="description">Payload</dt>
+  <dd class="value">
+    <pre id="payload" data-root="payload" class="json-highlight"><%= highlighted(JSON.pretty_generate(@webhook_event.payload)) %></pre> <div class="actions"><%= button_to downloads_path, params: { event_id: @webhook_event.id }, method: :post, class: "" do %><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34Zm-56,83.32-24,24a8,8,0,0,1-11.32,0l-24-24a8,8,0,0,1,11.32-11.32L120,164.69V120a8,8,0,0,1,16,0v44.69l10.34-10.35a8,8,0,0,1,11.32,11.32ZM152,88V44l44,44Z"/></svg><% end %> <%= render "copy_button", target: "payload" %></div>
+  </dd>
+
+  <dt class="description">Headers</dt>
+  <dd class="value">
+    <pre id="headers" class="json-highlight"><%= highlighted JSON.pretty_generate(@webhook_event.headers) %></pre> <div class="actions"><%= render "copy_button", target: "headers" %></div>
+  </dd>
 
   <% if @webhook_event.error.present? %>
-    <dt>Error</dt>
-    <dd><%= @webhook_event.error %></dd>
+    <dt class="description">Error</dt>
+
+    <dd class="value errors">
+      <%= @webhook_event.error %>
+    </dd>
   <% end %>
 </dl>
 

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

@@ -1,12 +1,22 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title><%= content_for?(:title) ? yield(:title) : "Fuik Admin" %></title>
+  <title><%= content_for?(:title) ? yield(:title) : Fuik.configuration.title %></title>
   <%= csrf_meta_tags %>
   <%= csp_meta_tag %>
 
   <%= yield :head %>
 
+  <style>
+    :root {
+      color-scheme: <%= {
+        auto: "light dark",
+        light: "light",
+        dark: "dark"
+      }.fetch(Fuik.configuration.color_scheme.to_sym) %>;
+    }
+  </style>
+
   <%= stylesheet_link_tag "fuik/application", media: "all" %>
   <script src="<%= asset_path("attractivejs-0.12.0.min.js") %>"></script>
 </head>

data/config/routes.rb

@@ -2,7 +2,10 @@
 
 Fuik::Engine.routes.draw do
   root to: "events#index"
-  resources :events, only: %w[show]
+
+  resources :events, only: %w[index show] do
+    resources :retries, only: %w[create]
+  end
   resources :downloads, only: %w[create]
 
   post ":provider", to: "webhooks#create", constraints: Fuik::Routing::ProviderConstraint.new

data/lib/fuik/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Fuik
+  class Configuration
+    attr_accessor :events_controller_parent, :webhooks_controller_parent,
+      :providers_allowed, :title, :color_scheme, :webhook_processing_job_class
+
+    def initialize
+      @events_controller_parent = "ActionController::Base"
+      @webhooks_controller_parent = "ActionController::Base"
+      @webhook_processing_job_class = "Fuik::WebhookProcessingJob"
+      @providers_allowed = nil
+      @title = "Webhooks"
+      @color_scheme = :light
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    delegate :webhook_processing_job_class, :webhook_processing_job_class=, to: :configuration
+  end
+end

data/lib/fuik/engine.rb

@@ -6,10 +6,6 @@ module Fuik
   class Engine < ::Rails::Engine
     isolate_namespace Fuik
 
-    config.webhooks_controller_parent = "ActionController::Base"
-    config.events_controller_parent = "ActionController::Base"
-    config.providers_allowed = Rails.env.local?
-
     config.to_prepare do
       ActiveSupport.on_load(:action_view) do
         include Fuik::IconHelper

data/lib/fuik/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fuik
+  class InvalidSignature < StandardError; end
+end

data/lib/fuik/notifications.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fuik
+  module Notifications
+    class << self
+      def received(provider:, event_id:, event_type:, webhook_event:)
+        publish("webhook_received",
+          provider: provider,
+          event_id: event_id,
+          event_type: event_type,
+          webhook_event: webhook_event)
+      end
+
+      def processed(webhook_event:, event_class:)
+        publish("webhook_processed",
+          provider: webhook_event.provider,
+          event_id: webhook_event.event_id,
+          event_type: webhook_event.event_type,
+          event_class: event_class,
+          webhook_event: webhook_event)
+      end
+
+      def failed(webhook_event:, event_class:, error:)
+        publish("webhook_failed",
+          provider: webhook_event.provider,
+          event_id: webhook_event.event_id,
+          event_type: webhook_event.event_type,
+          event_class: event_class,
+          error: error,
+          webhook_event: webhook_event)
+      end
+
+      def signature_invalid(provider:, event_id:)
+        publish("webhook_signature_invalid", provider: provider, event_id: event_id)
+      end
+
+      def receive_error(provider:, error:)
+        publish("webhook_receive_error", provider: provider, error: error)
+      end
+
+      private
+
+      def publish(name, payload = {})
+        ActiveSupport::Notifications.publish("#{name}.fuik", payload)
+      end
+    end
+  end
+end

data/lib/fuik/routing/provider_constraint.rb

@@ -15,13 +15,13 @@ module Fuik
 
       private
 
-      def allow_all? = Fuik::Engine.config.providers_allowed.in?([:all, "all"])
+      def allow_all? = Fuik.configuration.providers_allowed.in?([:all, "all"])
 
-      def explicit_allowlist? = Fuik::Engine.config.providers_allowed.is_a?(Array)
+      def explicit_allowlist? = Fuik.configuration.providers_allowed.is_a?(Array)
 
-      def explicit_allowlist = Fuik::Engine.config.providers_allowed.to_set
+      def explicit_allowlist = Fuik.configuration.providers_allowed.to_set
 
-      def providers_allowed = Fuik::Engine.config.providers_allowed
+      def providers_allowed = Fuik.configuration.providers_allowed
 
       def scanned_allowlist
         @scanned_allowlist ||= Dir["#{Rails.root}/app/webhooks/*"]

data/lib/fuik/test_helpers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Fuik
+  module TestHelpers
+    def build_webhook_event(provider: "test", event_id: "test_123", event_type: "test", payload: {})
+      WebhookEventDouble.new(provider, event_id, event_type, payload)
+    end
+
+    class WebhookEventDouble
+      attr_reader :provider, :event_id, :event_type, :status, :error
+
+      def initialize(provider, event_id, event_type, payload)
+        @provider = provider
+        @event_id = event_id
+        @event_type = event_type
+        @payload = payload
+      end
+
+      def payload
+        @payload.is_a?(Hash) ? @payload : {}
+      end
+
+      def processed!
+        @status = "processed"
+      end
+
+      def failed!(error)
+        @status = "failed"
+        @error = error.to_s
+      end
+    end
+  end
+end

data/lib/fuik/version.rb

@@ -1,3 +1,3 @@
 module Fuik
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/fuik.rb

@@ -1,7 +1,16 @@
+# frozen_string_literal: true
+
 require "fuik/version"
+require "fuik/errors"
+require "fuik/configuration"
 require "fuik/dot_access"
+require "fuik/notifications"
 require "fuik/engine"
 
 module Fuik
   class InvalidSignature < StandardError; end
+
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("1.0", "Fuik")
+  end
 end

data/lib/generators/fuik/provider/templates/base.rb.tt

@@ -1,8 +1,17 @@
 module <%= provider_module_name %>
   class Base < Fuik::Event
     # def self.verify!(request)
-      # TODO: Implement signature verification
-      # raise Fuik::InvalidSignature # only raise when signature is invalid
+    #   # TODO: Implement signature verification
+    #   # raise Fuik::InvalidSignature # only raise when signature is invalid
     # end
+
+    # Override if Fuik can't find the event type or id on its own:
+    #
+    # event_type header: "X-Custom-Event"
+    # event_type payload: "event_type"
+    # event_type "always_this_value"
+    #
+    # event_id header: "X-Custom-Id"
+    # event_id payload: "id"
   end
 end

data/lib/generators/fuik/provider/templates/github/base.rb.tt

@@ -1,5 +1,8 @@
 module <%= provider_module_name %>
   class Base < Fuik::Event
+    event_type header: "X-Github-Event"
+    event_id   header: "X-GitHub-Delivery"
+
     def self.verify!(request)
       secret = Rails.application.credentials.dig(:github, :secret)
       signature = request.headers["X-Hub-Signature-256"]

data/lib/generators/fuik/provider/templates/loops/base.rb.tt

@@ -1,5 +1,7 @@
 module <%= provider_module_name %>
   class Base < Fuik::Event
+    event_id header: "webhook-id"
+
     def self.verify!(request)
       secret = Rails.application.credentials.dig(:loops, :signing_secret)
       secret_bytes = Base64.strict_decode64(secret.split("_")[1])

data/lib/generators/fuik/provider/templates/postmark/base.rb.tt

@@ -1,4 +1,5 @@
 module <%= provider_module_name %>
   class Base < Fuik::Event
+    event_type header: "X-Postmark-Event"
   end
 end

data/lib/generators/fuik/provider/templates/spinal/base.rb.tt

@@ -0,0 +1,16 @@
+module <%= provider_module_name %>
+  class Base < Fuik::Event
+    event_type payload: "type"
+    event_id   payload: "data.id"
+
+    # def self.verify!(request)
+    #   secret = Rails.application.credentials.dig(:spinal, :webhook_secret)
+    #   signature = request.headers["webhook-signature"]
+    #   id = request.headers["webhook-id"]
+    #   timestamp = request.headers["webhook-timestamp"]
+
+    #   expected = OpenSSL::HMAC.base64digest("SHA256", secret, "#{id}.#{timestamp}.#{request.raw_post}")
+    #   raise Fuik::InvalidSignature unless Rack::Utils.secure_compare(signature, "v1,#{expected}")
+    # end
+  end
+end

data/lib/generators/fuik/provider/templates/spinal/collection_synced.rb.tt

@@ -0,0 +1,14 @@
+module <%= provider_module_name %>
+  class CollectionSynced < Base
+    def process!
+      # payload["data"]["id"]                # collection id
+      # payload["data"]["stats"]["added"]    # resources added during sync
+      # payload["data"]["stats"]["updated"]  # resources updated during sync
+      # payload["data"]["stats"]["removed"]  # resources removed during sync
+
+      # TODO: Add business logic
+
+      @webhook_event.processed!
+    end
+  end
+end

data/lib/generators/fuik/provider/templates/spinal/resource_created.rb.tt

@@ -0,0 +1,14 @@
+module <%= provider_module_name %>
+  class ResourceCreated < Base
+    def process!
+      # payload["data"]["id"]             # resource id
+      # payload["data"]["filename"]       # e.g., "posts/hello-world.md"
+      # payload["data"]["relative_path"]  # e.g., "posts/hello-world"
+      # payload["data"]["status"]         # "draft" | "published"
+
+      # TODO: Add business logic
+
+      @webhook_event.processed!
+    end
+  end
+end

data/lib/generators/fuik/provider/templates/spinal/resource_pushed.rb.tt

@@ -0,0 +1,13 @@
+module <%= provider_module_name %>
+  class ResourcePushed < Base
+    def process!
+      # payload["data"]["id"]        # resource id
+      # payload["data"]["filename"]  # e.g., "posts/hello-world.md"
+      # payload["data"]["status"]    # "draft" | "published"
+
+      # TODO: Add business logic
+
+      @webhook_event.processed!
+    end
+  end
+end

data/lib/generators/fuik/provider/templates/spinal/resource_scheduled.rb.tt

@@ -0,0 +1,13 @@
+module <%= provider_module_name %>
+  class ResourceScheduled < Base
+    def process!
+      # payload["data"]["id"]            # resource id
+      # payload["data"]["filename"]      # e.g., "posts/hello-world.md"
+      # payload["data"]["published_at"]  # ISO8601 scheduled publish time
+
+      # TODO: Add business logic
+
+      @webhook_event.processed!
+    end
+  end
+end