hooksmith 0.1.2 → 1.0.0

data/lib/hooksmith/instrumentation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Provides ActiveSupport::Notifications instrumentation for webhook processing.
+  #
+  # This module emits events at key points in the webhook lifecycle, enabling
+  # metrics collection, tracing, and debugging without modifying core code.
+  #
+  # @example Subscribe to all Hooksmith events
+  #   ActiveSupport::Notifications.subscribe(/hooksmith/) do |name, start, finish, id, payload|
+  #     duration = finish - start
+  #     Rails.logger.info "#{name} took #{duration}s"
+  #   end
+  #
+  # @example Subscribe to specific events
+  #   ActiveSupport::Notifications.subscribe('dispatch.hooksmith') do |*args|
+  #     event = ActiveSupport::Notifications::Event.new(*args)
+  #     StatsD.timing('hooksmith.dispatch', event.duration, tags: ["provider:#{event.payload[:provider]}"])
+  #   end
+  #
+  # == Available Events
+  #
+  # * `dispatch.hooksmith` - Emitted when a webhook is dispatched
+  #   - payload: { provider:, event:, payload:, processor:, result: }
+  #
+  # * `process.hooksmith` - Emitted when a processor executes
+  #   - payload: { provider:, event:, processor:, result: }
+  #
+  # * `no_processor.hooksmith` - Emitted when no processor matches
+  #   - payload: { provider:, event: }
+  #
+  # * `multiple_processors.hooksmith` - Emitted when multiple processors match
+  #   - payload: { provider:, event:, processor_count: }
+  #
+  # * `error.hooksmith` - Emitted when an error occurs
+  #   - payload: { provider:, event:, error:, error_class: }
+  #
+  module Instrumentation
+    NAMESPACE = 'hooksmith'
+
+    module_function
+
+    # Instruments a block with the given event name.
+    #
+    # @param event_name [String] the event name (without namespace)
+    # @param payload [Hash] the event payload
+    # @yield the block to instrument
+    # @return [Object] the result of the block
+    def instrument(event_name, payload = {}, &block)
+      return yield unless notifications_available?
+
+      full_name = "#{event_name}.#{NAMESPACE}"
+      ActiveSupport::Notifications.instrument(full_name, payload, &block)
+    end
+
+    # Publishes an event without a block.
+    #
+    # @param event_name [String] the event name (without namespace)
+    # @param payload [Hash] the event payload
+    def publish(event_name, payload = {})
+      return unless notifications_available?
+
+      full_name = "#{event_name}.#{NAMESPACE}"
+      ActiveSupport::Notifications.publish(full_name, payload)
+    end
+
+    # Checks if ActiveSupport::Notifications is available.
+    #
+    # @return [Boolean] true if available
+    def notifications_available?
+      defined?(ActiveSupport::Notifications)
+    end
+
+    # Subscribes to a Hooksmith event.
+    #
+    # @param event_name [String, Regexp, nil] the event name, pattern, or nil for all events
+    # @yield [name, start, finish, id, payload] the event callback
+    # @return [Object] the subscription object
+    def subscribe(event_name = nil, &block)
+      return unless notifications_available?
+
+      pattern = build_subscription_pattern(event_name)
+      ActiveSupport::Notifications.subscribe(pattern, &block)
+    end
+
+    # Unsubscribes from a Hooksmith event.
+    #
+    # @param subscriber [Object] the subscription object from subscribe
+    def unsubscribe(subscriber)
+      return unless notifications_available?
+
+      ActiveSupport::Notifications.unsubscribe(subscriber)
+    end
+
+    private
+
+    # Builds the subscription pattern based on the event name type.
+    #
+    # @param event_name [String, Regexp, nil] the event name or pattern
+    # @return [String, Regexp] the subscription pattern
+    def build_subscription_pattern(event_name)
+      case event_name
+      when nil
+        /\.#{NAMESPACE}$/
+      when Regexp
+        event_name
+      else
+        "#{event_name}.#{NAMESPACE}"
+      end
+    end
+  end
+end

data/lib/hooksmith/jobs/dispatcher_job.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Jobs
+    # ActiveJob for asynchronous webhook processing.
+    #
+    # This job wraps the Dispatcher to process webhooks in the background,
+    # allowing your webhook endpoint to respond quickly while processing
+    # happens asynchronously.
+    #
+    # @example Basic usage in a controller
+    #   class WebhooksController < ApplicationController
+    #     def stripe
+    #       Hooksmith::Jobs::DispatcherJob.perform_later(
+    #         provider: 'stripe',
+    #         event: params[:type],
+    #         payload: params.to_unsafe_h
+    #       )
+    #       head :ok
+    #     end
+    #   end
+    #
+    # @example With custom queue
+    #   Hooksmith::Jobs::DispatcherJob.set(queue: :webhooks).perform_later(...)
+    #
+    # @example With retry configuration (in your application)
+    #   # config/initializers/hooksmith.rb
+    #   Hooksmith::Jobs::DispatcherJob.retry_on StandardError, wait: :polynomially_longer, attempts: 5
+    #
+    class DispatcherJob < ActiveJob::Base
+      queue_as :default
+
+      # Performs the webhook dispatch asynchronously.
+      #
+      # @param provider [String, Symbol] the webhook provider name
+      # @param event [String, Symbol] the event type
+      # @param payload [Hash] the webhook payload
+      # @param options [Hash] additional options
+      # @option options [Boolean] :skip_idempotency_check (false) skip duplicate checking
+      # @return [Object] the result from the processor
+      def perform(provider:, event:, payload:, **options)
+        provider = provider.to_s
+        event = event.to_s
+
+        if check_idempotency?(options)
+          key = Hooksmith::Idempotency.extract_key(provider:, payload:)
+          if key && Hooksmith::Idempotency.already_processed?(provider:, key:)
+            Hooksmith.logger.info("Skipping duplicate webhook: #{provider}/#{event} (key=#{key})")
+            return nil
+          end
+        end
+
+        Hooksmith::Dispatcher.new(provider:, event:, payload:).run!
+      end
+
+      private
+
+      def check_idempotency?(options)
+        !options[:skip_idempotency_check]
+      end
+    end
+  end
+end

data/lib/hooksmith/rails/webhooks_controller.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Rails
+    # A concern for Rails controllers that handle webhooks.
+    #
+    # This concern provides standardized webhook handling with:
+    # - Automatic request verification (if configured)
+    # - Consistent response codes (200 for success, 400 for bad request, 500 for errors)
+    # - Error logging and instrumentation
+    # - Skip CSRF protection for webhook endpoints
+    #
+    # @example Basic usage
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h)
+    #     end
+    #   end
+    #
+    # @example With custom error handling
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h) do |result|
+    #         # Custom success handling
+    #         render json: { processed: true, result: result }
+    #       end
+    #     rescue Hooksmith::VerificationError => e
+    #       render json: { error: 'Invalid signature' }, status: :unauthorized
+    #     end
+    #   end
+    #
+    # @example Async processing with ActiveJob
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook_async(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h)
+    #     end
+    #   end
+    #
+    module WebhooksController
+      extend ActiveSupport::Concern
+
+      included do
+        skip_before_action :verify_authenticity_token, raise: false
+        before_action :verify_webhook_signature, if: :hooksmith_verification_enabled?
+      end
+
+      # Handles a webhook synchronously.
+      #
+      # @param provider [String, Symbol] the webhook provider
+      # @param event [String, Symbol] the event type
+      # @param payload [Hash] the webhook payload
+      # @yield [result] optional block for custom success handling
+      # @yieldparam result [Object] the result from the processor
+      # @return [void]
+      def handle_webhook(provider:, event:, payload:)
+        result = Hooksmith::Dispatcher.new(provider:, event:, payload:).run!
+
+        if block_given?
+          yield(result)
+        else
+          head :ok
+        end
+      rescue Hooksmith::MultipleProcessorsError => e
+        Hooksmith.logger.error("Webhook error: #{e.message}")
+        head :internal_server_error
+      rescue StandardError => e
+        Hooksmith.logger.error("Webhook processing failed: #{e.message}")
+        head :internal_server_error
+      end
+
+      # Handles a webhook asynchronously using ActiveJob.
+      #
+      # Requires Hooksmith::Jobs::DispatcherJob to be available.
+      #
+      # @param provider [String, Symbol] the webhook provider
+      # @param event [String, Symbol] the event type
+      # @param payload [Hash] the webhook payload
+      # @param queue [Symbol, String] the queue to use (default: :default)
+      # @return [void]
+      def handle_webhook_async(provider:, event:, payload:, queue: :default)
+        unless defined?(Hooksmith::Jobs::DispatcherJob)
+          raise 'Hooksmith::Jobs::DispatcherJob is not available. Ensure ActiveJob is loaded.'
+        end
+
+        Hooksmith::Jobs::DispatcherJob.set(queue:).perform_later(
+          provider: provider.to_s,
+          event: event.to_s,
+          payload: payload.as_json
+        )
+
+        head :ok
+      end
+
+      private
+
+      # Verifies the webhook signature using the provider's configured verifier.
+      #
+      # Override this method to customize verification behavior.
+      #
+      # @return [void]
+      # @raise [Hooksmith::VerificationError] if verification fails
+      def verify_webhook_signature
+        provider = hooksmith_provider_name
+        return unless provider
+
+        verifier = Hooksmith.configuration.verifier_for(provider)
+        return unless verifier&.enabled?
+
+        hooksmith_request = Hooksmith::Request.new(
+          headers: request.headers.to_h,
+          body: request.raw_post
+        )
+
+        verifier.verify!(hooksmith_request)
+      rescue Hooksmith::VerificationError => e
+        Hooksmith.logger.warn("Webhook verification failed for #{provider}: #{e.message}")
+        head :unauthorized
+      end
+
+      # Returns the provider name for the current action.
+      #
+      # Override this method to customize provider detection.
+      # By default, uses the action name.
+      #
+      # @return [String, nil] the provider name
+      def hooksmith_provider_name
+        action_name
+      end
+
+      # Checks if webhook verification is enabled for the current provider.
+      #
+      # Override this method to customize when verification runs.
+      #
+      # @return [Boolean] true if verification should run
+      def hooksmith_verification_enabled?
+        return false unless Hooksmith.configuration.respond_to?(:verifier_for)
+
+        provider = hooksmith_provider_name
+        return false unless provider
+
+        verifier = Hooksmith.configuration.verifier_for(provider)
+        verifier&.enabled? || false
+      end
+    end
+  end
+end

data/lib/hooksmith/request.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Wrapper for incoming webhook request data.
+  #
+  # This class provides a consistent interface for accessing request data
+  # regardless of the underlying web framework (Rails, Rack, etc.).
+  #
+  # @example Creating a request from Rails controller
+  #   request = Hooksmith::Request.new(
+  #     headers: request.headers.to_h,
+  #     body: request.raw_post,
+  #     method: request.request_method,
+  #     path: request.path
+  #   )
+  #
+  # @example Creating a request from Rack env
+  #   request = Hooksmith::Request.from_rack_env(env)
+  #
+  class Request
+    # @return [Hash] the request headers
+    attr_reader :headers
+    # @return [String] the raw request body
+    attr_reader :body
+    # @return [String] the HTTP method (GET, POST, etc.)
+    attr_reader :method
+    # @return [String] the request path
+    attr_reader :path
+    # @return [Hash] the parsed payload (optional, for convenience)
+    attr_reader :payload
+
+    # Initializes a new Request.
+    #
+    # @param headers [Hash] the request headers
+    # @param body [String] the raw request body
+    # @param method [String] the HTTP method
+    # @param path [String] the request path
+    # @param payload [Hash] the parsed payload (optional)
+    def initialize(headers:, body:, method: 'POST', path: '/', payload: nil)
+      @headers = normalize_headers(headers)
+      @body = body.to_s
+      @method = method.to_s.upcase
+      @path = path.to_s
+      @payload = payload
+    end
+
+    # Creates a Request from a Rack environment hash.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Request] a new Request instance
+    def self.from_rack_env(env)
+      headers = extract_headers_from_rack(env)
+      body = env['rack.input']&.read || ''
+      env['rack.input']&.rewind
+
+      new(
+        headers:,
+        body:,
+        method: env['REQUEST_METHOD'],
+        path: env['PATH_INFO']
+      )
+    end
+
+    # Gets a header value by name (case-insensitive).
+    #
+    # @param name [String] the header name
+    # @return [String, nil] the header value or nil if not found
+    def header(name)
+      normalized_name = normalize_header_name(name)
+      @headers[normalized_name]
+    end
+
+    # Alias for {#header}.
+    #
+    # @param name [String] the header name
+    # @return [String, nil] the header value or nil if not found
+    def [](name)
+      header(name)
+    end
+
+    # Extracts headers from a Rack environment hash.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Hash] the extracted headers
+    def self.extract_headers_from_rack(env)
+      env.select { |k, _| k.start_with?('HTTP_') || %w[CONTENT_TYPE CONTENT_LENGTH].include?(k) }
+    end
+    private_class_method :extract_headers_from_rack
+
+    private
+
+    # Normalizes headers to use consistent key format.
+    #
+    # @param headers [Hash] the raw headers
+    # @return [Hash] normalized headers
+    def normalize_headers(headers)
+      return {} unless headers.is_a?(Hash)
+
+      headers.transform_keys { |k| normalize_header_name(k) }
+    end
+
+    # Normalizes a header name to a consistent format.
+    #
+    # @param name [String] the header name
+    # @return [String] the normalized header name
+    def normalize_header_name(name)
+      name.to_s.upcase.tr('-', '_').sub(/^HTTP_/, '')
+    end
+  end
+end

data/lib/hooksmith/verifiers/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Verifiers
+    # Base class for webhook request verifiers.
+    #
+    # Verifiers are responsible for authenticating incoming webhook requests
+    # before they are processed. Each provider can have its own verifier
+    # configured to handle provider-specific authentication schemes.
+    #
+    # @abstract Subclass and override {#verify!} to implement custom verification.
+    #
+    # @example Creating a custom verifier
+    #   class MyCustomVerifier < Hooksmith::Verifiers::Base
+    #     def verify!(request)
+    #       token = request.headers['X-Custom-Token']
+    #       raise Hooksmith::VerificationError, 'Invalid token' unless valid_token?(token)
+    #     end
+    #
+    #     private
+    #
+    #     def valid_token?(token)
+    #       token == @options[:expected_token]
+    #     end
+    #   end
+    #
+    class Base
+      # @return [Hash] options passed to the verifier
+      attr_reader :options
+
+      # Initializes the verifier with options.
+      #
+      # @param options [Hash] verifier-specific options
+      def initialize(**options)
+        @options = options
+      end
+
+      # Verifies the incoming webhook request.
+      #
+      # @param request [Hooksmith::Request] the incoming request to verify
+      # @raise [Hooksmith::VerificationError] if verification fails
+      # @return [void]
+      def verify!(request)
+        raise NotImplementedError, 'Subclasses must implement #verify!'
+      end
+
+      # Returns whether the verifier is configured and should be used.
+      #
+      # @return [Boolean] true if the verifier should be applied
+      def enabled?
+        true
+      end
+
+      protected
+
+      # Performs a constant-time string comparison to prevent timing attacks.
+      #
+      # @param expected [String] expected string
+      # @param actual [String] actual string
+      # @return [Boolean] true if strings are equal
+      def secure_compare(expected, actual)
+        return false if expected.nil? || actual.nil?
+        return false if expected.bytesize != actual.bytesize
+
+        # Use OpenSSL's secure comparison if available (Ruby 2.5+)
+        if OpenSSL.respond_to?(:secure_compare)
+          OpenSSL.secure_compare(expected, actual)
+        else
+          # Fallback to manual constant-time comparison
+          left = expected.unpack('C*')
+          right = actual.unpack('C*')
+          result = 0
+          left.zip(right) { |x, y| result |= x ^ y }
+          result.zero?
+        end
+      end
+    end
+  end
+end

data/lib/hooksmith/verifiers/bearer_token.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Hooksmith
+  module Verifiers
+    # Bearer token webhook verifier.
+    #
+    # This verifier validates webhook requests using a simple bearer token
+    # in the Authorization header or a custom header.
+    #
+    # @example Basic bearer token verification
+    #   verifier = Hooksmith::Verifiers::BearerToken.new(
+    #     token: ENV['WEBHOOK_TOKEN']
+    #   )
+    #
+    # @example Custom header
+    #   verifier = Hooksmith::Verifiers::BearerToken.new(
+    #     token: ENV['WEBHOOK_TOKEN'],
+    #     header: 'X-Webhook-Token'
+    #   )
+    #
+    class BearerToken < Base
+      # Default header for bearer tokens
+      DEFAULT_HEADER = 'Authorization'
+
+      # Initializes the bearer token verifier.
+      #
+      # @param token [String] the expected token value
+      # @param header [String] the header containing the token (default: Authorization)
+      # @param strip_bearer_prefix [Boolean] whether to strip 'Bearer ' prefix (default: true)
+      def initialize(token:, header: DEFAULT_HEADER, strip_bearer_prefix: true, **options)
+        super(**options)
+        @token = token
+        @header = header
+        @strip_bearer_prefix = strip_bearer_prefix
+      end
+
+      # Verifies the bearer token in the request.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @raise [Hooksmith::VerificationError] if verification fails
+      # @return [void]
+      def verify!(request)
+        provided_token = extract_token(request)
+
+        if provided_token.nil? || provided_token.empty?
+          raise VerificationError.new('Missing authentication token', reason: 'missing_token')
+        end
+
+        return if secure_compare(@token, provided_token)
+
+        raise VerificationError.new('Invalid authentication token', reason: 'invalid_token')
+      end
+
+      # Returns whether the verifier is properly configured.
+      #
+      # @return [Boolean] true if token is present
+      def enabled?
+        !@token.nil? && !@token.empty?
+      end
+
+      private
+
+      # Extracts the token from the request headers.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @return [String, nil] the extracted token
+      def extract_token(request)
+        raw_token = request.header(@header)
+        return nil if raw_token.nil?
+
+        token = raw_token.to_s.strip
+        token = token.sub(/\ABearer\s+/i, '') if @strip_bearer_prefix
+        token.empty? ? nil : token
+      end
+    end
+  end
+end