webhukhs 0.6.0 → 0.8.0

data/lib/webhukhs/admin/received_webhooks_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Webhukhs
+  module Admin
+    # Lists and shows stored webhooks. Read-only: the lifecycle belongs to Webhukhs::ProcessingJob.
+    class ReceivedWebhooksController < ApplicationController
+      # Webhooks per index page
+      PAGE_SIZE = 50
+      # Columns the index can be sorted by
+      SORTABLE_COLUMNS = %w[created_at updated_at handler_module_name handler_event_id status].freeze
+
+      helper_method :handler_options, :status_options
+
+      # Renders a filtered, sorted page of webhooks.
+      #
+      # @return [void]
+      def index
+        @sort = params[:sort].presence_in(SORTABLE_COLUMNS) || "created_at"
+        @direction = (params[:direction] == "asc") ? "asc" : "desc"
+        @page = [params[:page].to_i, 1].max
+
+        filters = {handler_module_name: params[:handler], status: params[:status]}.compact_blank
+
+        # Most columns have plenty of ties (status especially), and without a tiebreaker the DB is free
+        # to return them in a different order for every OFFSET - rows then repeat or vanish between pages
+        rows = ReceivedWebhook
+          .where(filters)
+          .order(@sort => @direction, :id => @direction)
+          .offset((@page - 1) * PAGE_SIZE)
+          .limit(PAGE_SIZE + 1)
+        @next_page = @page + 1 if rows.length > PAGE_SIZE
+        @webhooks = rows.first(PAGE_SIZE).map { |webhook| ReceivedWebhookPresenter.new(webhook) }
+      end
+
+      # Renders one webhook with its body and headers.
+      #
+      # @return [void]
+      def show
+        @webhook = ReceivedWebhookPresenter.new(ReceivedWebhook.find(params.fetch(:id)))
+      end
+
+      private
+
+      # The configured handlers rather than a DISTINCT over the table, so that a handler which has
+      # not received anything yet can still be picked - "nothing arrived" is an answer too.
+      #
+      # @return [Array<String>] handler class names
+      def handler_options
+        Webhukhs.configuration.active_handlers.values.map(&:to_s).uniq.sort
+      end
+
+      # Statuses a webhook can be in, to filter by.
+      #
+      # @return [Hash{String => String}]
+      def status_options
+        ReceivedWebhook.statuses
+      end
+    end
+  end
+end

data/lib/webhukhs/admin/view_helper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Webhukhs
+  module Admin
+    # Table-building helpers for the admin views.
+    module ViewHelper
+      # Renders a table inside a scroll container. Cells are `white-space: nowrap`, so one long
+      # column would otherwise take the whole page sideways with it.
+      #
+      # @param columns [Array<String>] header cell contents
+      # @param records [Array] rows to render
+      # @yieldparam record [Object] one of the records
+      # @yieldreturn [Array] cell contents for that record
+      # @return [ActiveSupport::SafeBuffer]
+      def admin_table(columns, records)
+        rows = records.map do |record|
+          tag.tr { safe_join(yield(record).map { |cell| tag.td(cell) }) }
+        end
+        rows = [tag.tr(tag.td("No records.", colspan: columns.length, class: "empty"))] if rows.empty?
+
+        thead = tag.thead(tag.tr(safe_join(columns.map { |column| tag.th(column) })))
+        tag.div(tag.table(safe_join([thead, tag.tbody(safe_join(rows))]), class: "admin-table"), class: "table-scroll")
+      end
+
+      # Column header linking to the index sorted by that column. Clicking the active column
+      # flips the direction, any other column starts out descending.
+      #
+      # @param label [String] header text
+      # @param column [String] column to sort by
+      # @param sort [String] currently sorted column
+      # @param direction [String] current direction, "asc" or "desc"
+      # @return [ActiveSupport::SafeBuffer]
+      def sort_link(label, column, sort:, direction:)
+        active = column == sort
+        next_direction = (active && direction == "desc") ? "asc" : "desc"
+        query = request.query_parameters.except("page").merge("sort" => column, "direction" => next_direction)
+        label = safe_join([label, tag.span((direction == "asc") ? "▲" : "▼", class: "sort-arrow")], " ") if active
+        link_to(label, query, class: "sort-link")
+      end
+
+      # Button copying a value to the clipboard (see admin.js).
+      #
+      # @param value [String] text to copy
+      # @return [ActiveSupport::SafeBuffer]
+      def copy_button(value)
+        tag.button(class: "btn-copy", type: "button", title: "Copy to clipboard", data: {copy: value})
+      end
+    end
+  end
+end

data/lib/webhukhs/admin/views/layouts/webhukhs/admin/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><%= content_for?(:title) ? "#{yield(:title)} · Webhukhs" : "Webhukhs" %></title>
+  <link rel="icon" href="data:,">
+  <%= assiette_stylesheet_tag "/admin.css" %>
+  <script type="module" src="<%= assiette_asset_path "/admin.js" %>" integrity="<%= assiette_asset_integrity "/admin.js" %>" crossorigin="anonymous"></script>
+</head>
+<body>
+  <header class="admin-header">
+    <strong><%= link_to "Webhukhs", root_path %></strong>
+    <nav>
+      <%= link_to "Received webhooks", received_webhooks_path %>
+    </nav>
+  </header>
+  <main>
+    <%= yield %>
+  </main>
+</body>
+</html>

data/lib/webhukhs/admin/views/webhukhs/admin/received_webhooks/index.html.erb

@@ -0,0 +1,50 @@
+<% content_for :title, "Received webhooks" %>
+<div class="page-heading">
+  <h1>Received webhooks</h1>
+  <%# Off by default, admin.js remembers the choice and refetches the listing while it is on %>
+  <label class="switch">
+    <input type="checkbox" id="auto-refresh" role="switch">
+    Auto-refresh
+  </label>
+</div>
+
+<%= form_tag received_webhooks_path, method: :get, class: "filters" do %>
+  <%= hidden_field_tag :sort, @sort, id: nil %>
+  <%= hidden_field_tag :direction, @direction, id: nil %>
+  <%= select_tag :handler, options_for_select([["Any handler", ""]] + handler_options, params[:handler]), "aria-label": "Handler" %>
+  <%= select_tag :status, options_for_select([["Any status", ""]] + status_options.map { |status, _| [status.humanize, status] }, params[:status]), "aria-label": "Status" %>
+  <%= submit_tag "Filter", name: nil %>
+  <%= link_to "Clear", received_webhooks_path(sort: @sort, direction: @direction) %>
+<% end %>
+
+<%
+  columns = [
+    ["Received", "created_at"],
+    ["Handler", "handler_module_name"],
+    ["Status", "status"],
+    ["Event id", "handler_event_id"],
+    ["Updated", "updated_at"]
+  ].map { |label, column| sort_link(label, column, sort: @sort, direction: @direction) }
+%>
+<div id="received-webhooks">
+<%# The id cell carries the link, and the CSS stretches it over the whole row %>
+<%= admin_table(["Id"] + columns, @webhooks) do |webhook|
+  [
+    link_to(tag.code(webhook.id, class: "cell-ellipsis cell-id", title: webhook.id), received_webhook_path(webhook), class: "row-link"),
+    time_tag(webhook.created_at, webhook.created_at.iso8601),
+    webhook.handler_module_name,
+    tag.span(webhook.status, class: ["badge", webhook.status_class]),
+    tag.code(webhook.handler_event_id, class: "cell-ellipsis", title: webhook.handler_event_id),
+    time_tag(webhook.updated_at, webhook.updated_at.iso8601)
+  ]
+end %>
+
+<nav class="pagination">
+  <% if @page > 1 %>
+    <%= link_to "← Previous", request.query_parameters.merge("page" => @page - 1), rel: "prev" %>
+  <% end %>
+  <% if @next_page %>
+    <%= link_to "Next →", request.query_parameters.merge("page" => @next_page), rel: "next" %>
+  <% end %>
+</nav>
+</div>

data/lib/webhukhs/admin/views/webhukhs/admin/received_webhooks/show.html.erb

@@ -0,0 +1,55 @@
+<% content_for :title, "Webhook #{@webhook.id}" %>
+<nav class="breadcrumb">
+  <%= link_to "Received webhooks", received_webhooks_path %> / <code><%= @webhook.id %></code>
+</nav>
+
+<h1><%= @webhook.handler_module_name %> <span class="badge <%= @webhook.status_class %>"><%= @webhook.status %></span></h1>
+
+<h2>Attributes</h2>
+<div class="table-scroll attr-scroll">
+  <table class="admin-table attr-table">
+    <tbody>
+      <tr><th>Id</th><td><code><%= @webhook.id %></code> <%= copy_button(@webhook.id.to_s) %></td></tr>
+      <tr><th>Handler</th><td><code><%= @webhook.handler_module_name %></code></td></tr>
+      <tr><th>Event id</th><td><code><%= @webhook.handler_event_id %></code> <%= copy_button(@webhook.handler_event_id) %></td></tr>
+      <tr><th>Status</th><td><span class="badge <%= @webhook.status_class %>"><%= @webhook.status %></span></td></tr>
+      <tr><th>Received</th><td><%= time_tag(@webhook.created_at, @webhook.created_at.iso8601) %></td></tr>
+      <tr><th>Updated</th><td><%= time_tag(@webhook.updated_at, @webhook.updated_at.iso8601) %></td></tr>
+    </tbody>
+  </table>
+</div>
+
+<h2>Body <span class="muted">(<%= number_to_human_size(@webhook.body.bytesize) %>)</span></h2>
+<% if @webhook.truncated? %>
+  <p class="flash alert">The body was <%= number_to_human_size(@webhook.body.bytesize) %>, display is truncated</p>
+  <pre class="body-detail body-raw"><code><%= @webhook.body_text %></code></pre>
+<% elsif (pretty_json = @webhook.pretty_json) %>
+  <div class="tabs">
+    <div class="tab-bar">
+      <div role="tablist" aria-label="Body">
+        <button type="button" role="tab" id="body-tab-pretty" aria-controls="body-pretty" aria-selected="true">Pretty</button>
+        <button type="button" role="tab" id="body-tab-raw" aria-controls="body-raw" aria-selected="false" tabindex="-1">As sent</button>
+      </div>
+      <button type="button" class="btn-copy-panel" title="Copy the visible body to the clipboard">Copy</button>
+    </div>
+    <div role="tabpanel" id="body-pretty" aria-labelledby="body-tab-pretty">
+      <pre class="body-detail"><code><%= pretty_json %></code></pre>
+    </div>
+    <div role="tabpanel" id="body-raw" aria-labelledby="body-tab-raw" hidden>
+      <pre class="body-detail body-raw"><code><%= @webhook.body_text %></code></pre>
+    </div>
+  </div>
+<% else %>
+  <p class="flash alert">This body is not valid JSON, so it is shown as it was sent</p>
+  <pre class="body-detail body-raw"><code><%= @webhook.body_text %></code></pre>
+<% end %>
+
+<h2>Request headers</h2>
+<p class="muted">
+  As presented by the web server and any proxies in front of it.
+  <code>action_dispatch.request.path_parameters</code> is not a header, but the parameters
+  the router matched for the request.
+</p>
+<%= admin_table(["Header", "Value"], @webhook.header_rows) do |name, value|
+  [tag.code(name), tag.code(value, class: "header-value")]
+end %>

data/lib/webhukhs/admin.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "assiette"
+require_relative "../webhukhs"
+require_relative "admin/engine"
+require_relative "admin/view_helper"
+require_relative "admin/received_webhook_presenter"
+require_relative "admin/application_controller"
+require_relative "admin/received_webhooks_controller"
+
+# Public namespace for Webhukhs runtime and configuration.
+module Webhukhs
+  # Optional, read-only admin UI for received webhooks. It is not loaded by `require "webhukhs"` -
+  # require "webhukhs/admin" and mount {Webhukhs::Admin::Engine} yourself, behind your own authentication.
+  module Admin
+  end
+end

data/lib/webhukhs/base_handler.rb

@@ -2,18 +2,20 @@
 
 require_relative "jobs/processing_job"
 
+# Namespace for webhook ingestion and processing classes.
 module Webhukhs
+  # Base class for webhook handlers.
   class BaseHandler
     # `handle` accepts the ActionDispatch HTTP request and saves the webhook for later processing. It then
     # enqueues an ActiveJob which will perform the processing using `process`.
     #
-    # @param action_dispatch_request[ActionDispatch::Request] the request from the controller
+    # @param action_dispatch_request [ActionDispatch::Request] request from the controller
     # @return [void]
     def handle(action_dispatch_request)
-      handler_module_name = is_a?(Webhukhs::BaseHandler) ? self.class.name : to_s
+      handler_module_name = self.class.name
       handler_event_id = extract_event_id_from_request(action_dispatch_request)
 
-      webhook = Webhukhs::ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
+      webhook = ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
       webhook.save!
 
       enqueue(webhook)
@@ -42,7 +44,7 @@ module Webhukhs
     # body of the webhook request, but also the full (as-full-as-possible) clone of the original ActionDispatch::Request
     # that you can use.
     #
-    # @param received_webhook[Webhukhs::ReceivedWebhook]
+    # @param received_webhook [Webhukhs::ReceivedWebhook] persisted webhook to process
     # @return [void]
     def process(received_webhook)
     end
@@ -60,9 +62,9 @@ module Webhukhs
     # If this method returns `false`, the webhook will be marked as `failed_validation` in the database. If this
     # method returns `true`, the `process` method of the handler is going to be called.
     #
-    # @see Webhukhs::ReceivedWebhook#request
-    # @param action_dispatch_request[ActionDispatch::Request] the reconstructed request from the controller
+    # @param action_dispatch_request [ActionDispatch::Request] reconstructed request from the stored webhook
     # @return [Boolean]
+    # @see Webhukhs::ReceivedWebhook#request
     def valid?(action_dispatch_request)
       true
     end
@@ -71,6 +73,7 @@ module Webhukhs
     # an event ID we use it for deduplication. A duplicate webhook is not going to be
     # stored in the database if it is already present there.
     #
+    # @param action_dispatch_request [ActionDispatch::Request] request used to derive a stable event identifier
     # @return [String]
     def extract_event_id_from_request(action_dispatch_request)
       SecureRandom.uuid

data/lib/webhukhs/controllers/receive_webhooks_controller.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 module Webhukhs
+  # Receives incoming webhook HTTP requests and dispatches handlers.
   class ReceiveWebhooksController < ActionController::API
+    # Raised when a configured handler exists but is currently inactive.
     class HandlerInactive < StandardError
     end
 
+    # Raised when no handler is configured for the service id.
     class UnknownHandler < StandardError
     end
 
+    # Persists and schedules processing for an incoming webhook request.
+    #
+    # @return [void]
     def create
       Rails.error.set_context(**Webhukhs.configuration.error_context)
       handler = lookup_handler(service_id)
@@ -15,27 +21,40 @@ module Webhukhs
       handler.handle(request)
       render(json: {ok: true, error: nil})
     rescue UnknownHandler => e
-      Rails.error.report(e, handled: true, severity: :error)
+      Rails.error.report(e, severity: :error)
       render_error_with_status("No handler found for #{service_id.inspect}", status: :not_found)
     rescue HandlerInactive => e
-      Rails.error.report(e, handled: true, severity: :error)
+      Rails.error.report(e, severity: :error)
       render_error_with_status("Webhook handler #{service_id.inspect} is inactive", status: :service_unavailable)
     rescue => e
-      raise e unless handler
-      raise e if handler.expose_errors_to_sender?
-      Rails.error.report(e, handled: true, severity: :error)
+      raise unless handler
+      raise if handler.expose_errors_to_sender?
+      Rails.error.report(e, severity: :error)
       render_error_with_status("Internal error (#{e})")
     end
 
+    # Extracts webhook service identifier from route parameters.
+    #
+    # @return [String]
     def service_id
       params.require(:service_id)
     end
 
-    def render_error_with_status(message_str, status: :ok)
-      json = {ok: false, error: message_str}.to_json
+    # Renders standardized error response payload.
+    #
+    # @param message_str [String] human-readable error message
+    # @param status [Symbol] HTTP response status
+    # @return [void]
+    def render_error_with_status(message_str, status: nil)
+      json = {ok: false, error: message_str}
       render(json: json, status: status)
     end
 
+    # Resolves a handler class from configuration for a service id.
+    #
+    # @param service_id_str [String] service identifier from request path
+    # @return [Webhukhs::BaseHandler]
+    # @raise [UnknownHandler] when no active handler is configured for service id
     def lookup_handler(service_id_str)
       active_handlers = Webhukhs.configuration.active_handlers.with_indifferent_access
       # The config can specify a mapping of:

data/lib/webhukhs/engine.rb

@@ -6,6 +6,7 @@ require_relative "models/received_webhook"
 require_relative "base_handler"
 
 module Webhukhs
+  # Rails engine wiring routes, autoloading and generators for Webhukhs.
   class Engine < ::Rails::Engine
     isolate_namespace Webhukhs
 
@@ -16,9 +17,5 @@ module Webhukhs
     generators do
       require_relative "install_generator"
     end
-
-    routes do
-      post "/:service_id" => "received_webhooks#create"
-    end
   end
 end

data/lib/webhukhs/install_generator.rb

@@ -4,26 +4,33 @@ require "rails/generators"
 require "rails/generators/active_record"
 
 module Webhukhs
-  #
   # Rails generator used for setting up Webhukhs in a Rails application.
   # Run it with +bin/rails g webhukhs:install+ in your console.
-  #
   class InstallGenerator < Rails::Generators::Base
     include ActiveRecord::Generators::Migration
 
     source_root File.expand_path("../templates", __FILE__)
 
+    # Creates migration files required by Webhukhs tables.
+    #
+    # @return [void]
     def create_migration_file
       migration_template "create_webhukhs_tables.rb.erb", File.join(db_migrate_path, "create_webhukhs_tables.rb")
       migration_template "add_headers_to_webhukhs_webhooks.rb.erb", File.join(db_migrate_path, "add_headers_to_webhukhs_webhooks.rb")
     end
 
+    # Copies initializer file into host application.
+    #
+    # @return [void]
     def copy_files
       template "webhukhs.rb", File.join("config", "initializers", "webhukhs.rb")
     end
 
     private
 
+    # Declares ActiveRecord migration version.
+    #
+    # @return [String]
     def migration_version
       "[#{ActiveRecord::VERSION::STRING.to_f}]"
     end

data/lib/webhukhs/jobs/processing_job.rb

@@ -3,35 +3,36 @@
 require "active_job/railtie"
 
 module Webhukhs
+  # Background job that validates and processes a persisted webhook.
   class ProcessingJob < ActiveJob::Base
+    # Raised when the job receives an invalid webhook argument.
     class InvalidWebhookArgument < StandardError; end
 
-    discard_on ActiveJob::DeserializationError do |job, error|
-      Rails.error.report(error, context: {
-        job_id: job.job_id,
-        arguments: job.arguments.map(&:inspect)
-      }, severity: :error)
-    end
-
-    discard_on InvalidWebhookArgument do |job, error|
+    discard_on ActiveJob::DeserializationError, InvalidWebhookArgument do |job, error|
       Rails.error.report(error, context: {
         job_id: job.job_id,
         arguments: job.arguments.map(&:inspect)
       }, severity: :error)
     end
 
+    # Runs webhook validation and processing lifecycle.
+    #
+    # @param webhook [Webhukhs::ReceivedWebhook] webhook record to process
+    # @return [void]
     def perform(webhook)
       raise InvalidWebhookArgument, "ProcessingJob received nil webhook argument" if webhook.nil?
-      unless webhook.is_a?(Webhukhs::ReceivedWebhook)
+      unless webhook.instance_of?(ReceivedWebhook)
         raise InvalidWebhookArgument, "ProcessingJob expected Webhukhs::ReceivedWebhook, got #{webhook.class}"
       end
 
       webhook_details_for_logs = "Webhukhs::ReceivedWebhook#%s (handler: %s)" % [webhook.id, webhook.handler]
+
       webhook.with_lock do
         unless webhook.received?
           logger.info { "#{webhook_details_for_logs} is being processed in a different job or has been processed already, skipping." }
           return
         end
+
         webhook.processing!
       end
 
@@ -44,9 +45,9 @@ module Webhukhs
         logger.info { "#{webhook_details_for_logs} did not pass validation by the handler. Marking it `failed_validation`." }
         webhook.failed_validation!
       end
-    rescue => e
-      webhook.error!
-      raise e
+    rescue
+      webhook.error! if webhook.respond_to?(:error!)
+      raise
     end
   end
 end

data/lib/webhukhs/models/received_webhook.rb

@@ -3,6 +3,7 @@
 require "state_machine_enum"
 
 module Webhukhs
+  # ActiveRecord model that stores received webhook requests for async processing.
   class ReceivedWebhook < ActiveRecord::Base
     self.implicit_order_column = "created_at"
     self.table_name = "received_webhooks"
@@ -25,12 +26,14 @@ module Webhukhs
     end
 
     # Store the pertinent data from an ActionDispatch::Request into the webhook.
-    # @param [ActionDispatch::Request]
+    #
+    # @param action_dispatch_request [ActionDispatch::Request] request to persist
+    # @return [void]
     def request=(action_dispatch_request)
       # Filter out all Rack-specific headers such as "rack.input" and the like. We are
       # only interested in the actual HTTP headers presented by the webserver. Mostly...
-      headers = action_dispatch_request.env.filter_map do |(header_name, header_value)|
-        if header_name.is_a?(String) && header_name.upcase == header_name && header_value.is_a?(String)
+      headers = action_dispatch_request.env.filter_map do |header_name, header_value|
+        if header_name.instance_of?(String) && header_name.upcase == header_name && header_value.instance_of?(String)
           [header_name, header_value]
         end
       end.to_h
@@ -47,10 +50,13 @@ module Webhukhs
       # Verify the request body is not too large
       request_body_io = action_dispatch_request.env.fetch("rack.input")
       if request_body_io.size > Webhukhs.configuration.request_body_size_limit
-        raise "Cannot accept the webhook as the request body is larger than #{limit} bytes"
+        raise "Cannot accept the webhook as the request body is larger than #{Webhukhs.configuration.request_body_size_limit} bytes"
       end
 
-      write_attribute("body", request_body_io.read.force_encoding(Encoding::BINARY))
+      # Rails parses a form-encoded body into params before the handler gets the request, and
+      # leaves the stream at its end - we would store an empty body without the rewind
+      request_body_io.rewind
+      write_attribute("body", request_body_io.read.b)
       write_attribute("request_headers", headers)
     ensure
       request_body_io.rewind
@@ -91,25 +97,31 @@ module Webhukhs
     #
     # @return [ActionDispatch::Request]
     def request
-      ActionDispatch::Request.new(request_headers.merge!("rack.input" => StringIO.new(body.to_s.b)))
+      ActionDispatch::Request.new(request_headers.merge("rack.input" => StringIO.new(body.b)))
     end
 
+    # Instantiates the configured handler for this webhook.
+    #
+    # @return [Webhukhs::BaseHandler]
     def handler
       handler_module_name.constantize.new
     end
 
     private
 
+    # Assigns a generated id when database does not auto-increment ids.
+    #
+    # @return [void]
     def ensure_id
       return if id.present?
       # let DB auto-increment handle it
-      return if self.class.columns_hash["id"].type == :integer
+      return if self.class.columns_hash.fetch("id").type == :integer
 
       self.id = if SecureRandom.respond_to?(:uuid_v7)
-        # Requires Ruby 3.3+. This is preferred approach for time-sortable id's.
+        # Ruby 3.3+ UUIDv7 keeps inserts more index-friendly than random UUIDv4.
         SecureRandom.uuid_v7
       else
-        # Ruby < 3.2 fallback - uuid v4
+        # Fallback for Rubies without UUIDv7 support.
         SecureRandom.uuid
       end
     end

data/lib/webhukhs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Webhukhs
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/webhukhs.rb

@@ -5,16 +5,25 @@ require_relative "webhukhs/engine"
 require_relative "webhukhs/jobs/processing_job"
 require "active_support/core_ext/class/attribute"
 
+# Public namespace for Webhukhs runtime and configuration.
 module Webhukhs
+  # Returns singleton configuration object.
+  #
+  # @return [Webhukhs::Configuration]
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Yields global configuration object for setup.
+  #
+  # @yieldparam configuration [Webhukhs::Configuration]
+  # @return [void]
   def self.configure
     yield configuration
   end
 end
 
+# Holds runtime configuration for Webhukhs.
 class Webhukhs::Configuration
   class_attribute :processing_job_class, default: Webhukhs::ProcessingJob
   class_attribute :active_handlers, default: {}