webhukhs 0.6.0 → 0.7.0

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,10 @@ 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))
+      write_attribute("body", request_body_io.read.b)
       write_attribute("request_headers", headers)
     ensure
       request_body_io.rewind
@@ -91,25 +94,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.7.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: {}

data/test/base_handler_test.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class EnqueueProbeJob
+  class << self
+    attr_accessor :received_webhook
+  end
+
+  def self.perform_later(webhook)
+    self.received_webhook = webhook
+  end
+end
+
+class HandleProbeHandler < Webhukhs::BaseHandler
+  attr_reader :enqueued_webhook
+
+  def enqueue(webhook)
+    @enqueued_webhook = webhook
+  end
+end
+
+class BaseHandlerTest < ActiveSupport::TestCase
+  cover "Webhukhs::BaseHandler*"
+
+  teardown { Webhukhs::ReceivedWebhook.delete_all }
+
+  test "process is a no-op by default" do
+    assert_nil Webhukhs::BaseHandler.new.process(nil)
+  end
+
+  test "defaults to active, valid and exposing errors" do
+    handler = Webhukhs::BaseHandler.new
+
+    assert_equal true, handler.active?
+    assert_equal true, handler.valid?(nil)
+    assert_equal true, handler.expose_errors_to_sender?
+  end
+
+  test "generates unique UUID event ids by default" do
+    handler = Webhukhs::BaseHandler.new
+
+    first_id = handler.extract_event_id_from_request(nil)
+    second_id = handler.extract_event_id_from_request(nil)
+
+    assert_match(/\A[0-9a-f-]{36}\z/, first_id)
+    assert_match(/\A[0-9a-f-]{36}\z/, second_id)
+    refute_equal first_id, second_id
+  end
+
+  test "handle passes the handler class name into received webhooks" do
+    captured_attributes = nil
+    request = ActionDispatch::Request.new(
+      "rack.input" => StringIO.new("{}"),
+      "REQUEST_METHOD" => "POST",
+      "CONTENT_TYPE" => "application/json",
+      "action_dispatch.request.path_parameters" => {}
+    )
+    webhook = Object.new
+    handler = HandleProbeHandler.new
+
+    def webhook.save!
+    end
+
+    with_overridden_singleton_method(Webhukhs::ReceivedWebhook, :new, ->(**attributes) {
+      captured_attributes = attributes
+      webhook
+    }) do
+      handler.handle(request)
+
+      assert_same webhook, handler.enqueued_webhook
+      assert_equal "HandleProbeHandler", captured_attributes.fetch(:handler_module_name)
+    end
+  end
+
+  test "handle logs duplicate deliveries" do
+    handler = ExtractIdHandler.new
+    request_headers = {
+      "CONTENT_TYPE" => "application/json",
+      "action_dispatch.request.path_parameters" => {}
+    }
+    payload = {event_id: "duplicate-event"}.to_json
+
+    first_request = ActionDispatch::Request.new(request_headers.merge("rack.input" => StringIO.new(payload)))
+    second_request = ActionDispatch::Request.new(request_headers.merge("rack.input" => StringIO.new(payload)))
+
+    handler.handle(first_request)
+
+    with_captured_info_logs(Rails) do |messages|
+      handler.handle(second_request)
+
+      assert_equal ["#{handler.inspect} Webhook duplicate-event is a duplicate delivery and will not be stored."], messages
+    end
+  end
+
+  test "enqueue uses configured processing job classes directly" do
+    original_job_class = Webhukhs.configuration.processing_job_class
+    webhook = Object.new
+
+    Webhukhs.configuration.processing_job_class = EnqueueProbeJob
+    EnqueueProbeJob.received_webhook = nil
+
+    Webhukhs::BaseHandler.new.enqueue(webhook)
+
+    assert_same webhook, EnqueueProbeJob.received_webhook
+  ensure
+    Webhukhs.configuration.processing_job_class = original_job_class
+    EnqueueProbeJob.received_webhook = nil
+  end
+
+  test "enqueue constantizes configured processing job class names" do
+    original_job_class = Webhukhs.configuration.processing_job_class
+    webhook = Object.new
+
+    Webhukhs.configuration.processing_job_class = "EnqueueProbeJob"
+    EnqueueProbeJob.received_webhook = nil
+
+    Webhukhs::BaseHandler.new.enqueue(webhook)
+
+    assert_same webhook, EnqueueProbeJob.received_webhook
+  ensure
+    Webhukhs.configuration.processing_job_class = original_job_class
+    EnqueueProbeJob.received_webhook = nil
+  end
+end

data/test/processing_job_test.rb

@@ -1,10 +1,41 @@
 # frozen_string_literal: true
 
 require "test_helper"
-require_relative "test_app"
+
+class SkipDuringProcessingHandler < Webhukhs::BaseHandler
+  def process(webhook)
+    webhook.skipped!
+  end
+end
+
+class LoggingHandler < Webhukhs::BaseHandler
+  class_attribute :processed_webhook_ids, default: []
+
+  def self.reset!
+    self.processed_webhook_ids = []
+  end
+
+  def to_s = self.class.name
+
+  def valid?(_request) = true
+
+  def process(webhook)
+    self.class.processed_webhook_ids += [webhook.id]
+  end
+end
+
+class InvalidLoggingHandler < LoggingHandler
+  def valid?(_request) = false
+end
 
 class ProcessingJobTest < ActiveJob::TestCase
-  teardown { Webhukhs::ReceivedWebhook.delete_all }
+  cover "Webhukhs::ProcessingJob*"
+
+  teardown do
+    Webhukhs::ReceivedWebhook.delete_all
+    LoggingHandler.reset!
+    InvalidLoggingHandler.reset!
+  end
 
   test "discards job and reports error when webhook argument is nil" do
     assert_error_reported(Webhukhs::ProcessingJob::InvalidWebhookArgument) do
@@ -14,6 +45,14 @@ class ProcessingJobTest < ActiveJob::TestCase
     assert_no_enqueued_jobs only: Webhukhs::ProcessingJob
   end
 
+  test "raises a specific error message when webhook argument is nil" do
+    error = assert_raises(Webhukhs::ProcessingJob::InvalidWebhookArgument) do
+      Webhukhs::ProcessingJob.new.perform(nil)
+    end
+
+    assert_equal "ProcessingJob received nil webhook argument", error.message
+  end
+
   test "discards job and reports error when webhook argument is not a ReceivedWebhook" do
     assert_error_reported(Webhukhs::ProcessingJob::InvalidWebhookArgument) do
       Webhukhs::ProcessingJob.perform_now("not a webhook")
@@ -22,6 +61,120 @@ class ProcessingJobTest < ActiveJob::TestCase
     assert_no_enqueued_jobs only: Webhukhs::ProcessingJob
   end
 
+  test "raises a specific error message when webhook argument is not a ReceivedWebhook" do
+    error = assert_raises(Webhukhs::ProcessingJob::InvalidWebhookArgument) do
+      Webhukhs::ProcessingJob.new.perform("not a webhook")
+    end
+
+    assert_equal "ProcessingJob expected Webhukhs::ReceivedWebhook, got String", error.message
+  end
+
+  test "processes webhooks under a lock" do
+    webhook = Webhukhs::ReceivedWebhook.create!(
+      handler_event_id: "lock-test",
+      handler_module_name: "WebhookTestHandler",
+      status: "received",
+      body: {isValid: false}.to_json,
+      request_headers: {
+        "CONTENT_TYPE" => "application/json",
+        "action_dispatch.request.path_parameters" => {}
+      }
+    )
+    with_lock_called = false
+
+    webhook.define_singleton_method(:with_lock) do |&block|
+      with_lock_called = true
+      block.call
+    end
+
+    Webhukhs::ProcessingJob.new.perform(webhook)
+
+    assert_equal true, with_lock_called
+    assert_predicate webhook.reload, :failed_validation?
+  end
+
+  test "logs when processing is skipped because the webhook is not received" do
+    webhook = Webhukhs::ReceivedWebhook.create!(
+      handler_event_id: "skip-log-test",
+      handler_module_name: "LoggingHandler",
+      status: "processing",
+      body: {}.to_json,
+      request_headers: {}
+    )
+    job = Webhukhs::ProcessingJob.new
+    details = "Webhukhs::ReceivedWebhook##{webhook.id} (handler: LoggingHandler)"
+
+    with_captured_info_logs(Webhukhs::ProcessingJob) do |messages|
+      job.perform(webhook)
+
+      assert_equal ["#{details} is being processed in a different job or has been processed already, skipping."], messages
+    end
+  end
+
+  test "logs when processing starts and completes" do
+    webhook = Webhukhs::ReceivedWebhook.create!(
+      handler_event_id: "success-log-test",
+      handler_module_name: "LoggingHandler",
+      status: "received",
+      body: {}.to_json,
+      request_headers: {
+        "CONTENT_TYPE" => "application/json",
+        "action_dispatch.request.path_parameters" => {}
+      }
+    )
+    job = Webhukhs::ProcessingJob.new
+    details = "Webhukhs::ReceivedWebhook##{webhook.id} (handler: LoggingHandler)"
+
+    with_captured_info_logs(Webhukhs::ProcessingJob) do |messages|
+      job.perform(webhook)
+
+      assert_equal ["#{details} starting to process", "#{details} processed"], messages
+    end
+
+    assert_predicate webhook.reload, :processed?
+    assert_equal [webhook.id], LoggingHandler.processed_webhook_ids
+  end
+
+  test "logs when validation fails" do
+    webhook = Webhukhs::ReceivedWebhook.create!(
+      handler_event_id: "failed-validation-log-test",
+      handler_module_name: "InvalidLoggingHandler",
+      status: "received",
+      body: {}.to_json,
+      request_headers: {
+        "CONTENT_TYPE" => "application/json",
+        "action_dispatch.request.path_parameters" => {}
+      }
+    )
+    job = Webhukhs::ProcessingJob.new
+    details = "Webhukhs::ReceivedWebhook##{webhook.id} (handler: InvalidLoggingHandler)"
+
+    with_captured_info_logs(Webhukhs::ProcessingJob) do |messages|
+      job.perform(webhook)
+
+      assert_equal ["#{details} did not pass validation by the handler. Marking it `failed_validation`."], messages
+    end
+
+    assert_predicate webhook.reload, :failed_validation?
+  end
+
+  test "does not overwrite webhook state changed by the handler" do
+    webhook = Webhukhs::ReceivedWebhook.create!(
+      handler_event_id: "skip-test",
+      handler_module_name: "SkipDuringProcessingHandler",
+      status: "received",
+      body: {}.to_json,
+      request_headers: {
+        "CONTENT_TYPE" => "application/json",
+        "action_dispatch.request.path_parameters" => {}
+      }
+    )
+
+    Webhukhs::ProcessingJob.new.perform(webhook)
+
+    assert_predicate webhook.reload, :skipped?
+  end
+
   test "discards job and reports error when webhook record has been deleted (DeserializationError)" do
     webhook = Webhukhs::ReceivedWebhook.create!(
       handler_event_id: "deserialization-test",