hooksmith 0.2.0 → 1.0.0

data/lib/hooksmith/dispatcher.rb

@@ -3,18 +3,28 @@
 module Hooksmith
   # Dispatcher routes incoming webhook payloads to the appropriate processor.
   #
+  # Uses string keys internally to prevent Symbol DoS attacks when processing
+  # untrusted webhook input from external sources.
+  #
   # @example Dispatch a webhook event:
   #   Hooksmith::Dispatcher.new(provider: :stripe, event: :charge_succeeded, payload: payload).run!
   #
   class Dispatcher
+    # @return [String] the provider name
+    attr_reader :provider
+    # @return [String] the event name
+    attr_reader :event
+    # @return [Hash] the webhook payload
+    attr_reader :payload
+
     # Initializes a new Dispatcher.
     #
     # @param provider [Symbol, String] the provider (e.g., :stripe)
     # @param event [Symbol, String] the event (e.g., :charge_succeeded)
     # @param payload [Hash] the webhook payload data.
     def initialize(provider:, event:, payload:)
-      @provider = provider.to_sym
-      @event    = event.to_sym
+      @provider = provider.to_s
+      @event    = event.to_s
       @payload  = payload
     end
 
@@ -22,54 +32,81 @@ module Hooksmith
     #
     # Instantiates each processor registered for the given provider and event,
     # then selects the ones that can handle the payload using the can_handle? method.
-    # - If no processors qualify, logs a warning.
+    # - If no processors qualify, logs a warning (or raises NoProcessorError in strict mode).
     # - If more than one qualifies, raises MultipleProcessorsError.
     # - Otherwise, processes the event with the single matching processor.
     #
-    # @raise [MultipleProcessorsError] if multiple processors qualify.
+    # @raise [Hooksmith::MultipleProcessorsError] if multiple processors qualify.
+    # @raise [Hooksmith::NoProcessorError] if no processors qualify (strict mode only).
+    # @raise [Hooksmith::ProcessorError] if the processor raises an error.
+    # @return [Object, nil] the result of the processor, or nil if no processor matched.
     def run!
-      # Optionally record the incoming event before processing.
-      Hooksmith::EventRecorder.record!(provider: @provider, event: @event, payload: @payload, timing: :before)
+      Hooksmith::Instrumentation.instrument('dispatch', provider: @provider, event: @event) do
+        dispatch_webhook
+      end
+    end
 
-      # Fetch all processors registered for this provider and event.
-      entries = Hooksmith.configuration.processors_for(@provider, @event)
+    private
+
+    def dispatch_webhook
+      record_event(:before)
+      matching = find_matching_processors
+
+      return handle_no_processor if matching.empty?
+
+      handle_multiple_processors(matching) if matching.size > 1
+
+      execute_processor(matching.first)
+    rescue Hooksmith::Error
+      raise
+    rescue StandardError => e
+      publish_error(e)
+      Hooksmith.logger.error("Error processing #{@provider} event #{@event}: #{e.message}")
+      raise e
+    end
 
-      # Instantiate each processor and filter by condition.
-      matching_processors = entries.map do |entry|
+    def find_matching_processors
+      entries = Hooksmith.configuration.processors_for(@provider, @event)
+      entries.filter_map do |entry|
         processor = Object.const_get(entry[:processor]).new(@payload)
         processor if processor.can_handle?(@payload)
-      end.compact
-
-      if matching_processors.empty?
-        Hooksmith.logger.warn("No processor registered for #{@provider} event #{@event} could handle the payload")
-        return
       end
+    end
 
-      # If more than one processor qualifies, raise an error.
-      raise MultipleProcessorsError.new(@provider, @event, @payload) if matching_processors.size > 1
+    def handle_no_processor
+      Hooksmith::Instrumentation.publish('no_processor', provider: @provider, event: @event)
+      Hooksmith.logger.warn("No processor registered for #{@provider} event #{@event} could handle the payload")
+      nil
+    end
 
-      # Exactly one matching processor.
-      result = matching_processors.first.process!
+    def handle_multiple_processors(matching)
+      processor_names = matching.map { |p| p.class.name }
+      Hooksmith::Instrumentation.publish(
+        'multiple_processors',
+        provider: @provider, event: @event, processor_count: matching.size
+      )
+      raise MultipleProcessorsError.new(@provider, @event, @payload, processor_names:)
+    end
 
-      # Optionally record the event after successful processing.
-      Hooksmith::EventRecorder.record!(provider: @provider, event: @event, payload: @payload, timing: :after)
+    def execute_processor(processor)
+      result = Hooksmith::Instrumentation.instrument(
+        'process',
+        provider: @provider, event: @event, processor: processor.class.name
+      ) { processor.process! }
 
+      record_event(:after)
       result
-    rescue StandardError => e
-      Hooksmith.logger.error("Error processing #{@provider} event #{@event}: #{e.message}")
-      raise e
     end
-  end
 
-  # Raised when multiple processors can handle the same event.
-  class MultipleProcessorsError < StandardError
-    # Initializes the error with details about the provider, event, and payload.
-    #
-    # @param provider [Symbol] the provider name.
-    # @param event [Symbol] the event name.
-    # @param payload [Hash] the webhook payload.
-    def initialize(provider, event, payload)
-      super("Multiple processors found for #{provider} event #{event}. Payload: #{payload}")
+    def record_event(timing)
+      Hooksmith::EventRecorder.record!(provider: @provider, event: @event, payload: @payload, timing:)
+    end
+
+    def publish_error(error)
+      Hooksmith::Instrumentation.publish(
+        'error',
+        provider: @provider, event: @event, error: error.message, error_class: error.class.name
+      )
     end
   end
 end

data/lib/hooksmith/errors.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Base error class for all Hooksmith errors.
+  #
+  # All Hooksmith errors inherit from this class, allowing you to rescue
+  # all Hooksmith-related errors with a single rescue clause.
+  #
+  # @example Rescuing all Hooksmith errors
+  #   begin
+  #     Hooksmith::Dispatcher.new(...).run!
+  #   rescue Hooksmith::Error => e
+  #     logger.error("Hooksmith error: #{e.message}")
+  #   end
+  #
+  class Error < StandardError
+    # @return [String, nil] the provider name
+    attr_reader :provider
+    # @return [String, nil] the event name
+    attr_reader :event
+
+    # Initializes a new Error.
+    #
+    # @param message [String] the error message
+    # @param provider [String, Symbol, nil] the provider name
+    # @param event [String, Symbol, nil] the event name
+    def initialize(message = nil, provider: nil, event: nil)
+      @provider = provider&.to_s
+      @event = event&.to_s
+      super(message)
+    end
+  end
+
+  # Raised when webhook request verification fails.
+  #
+  # This error is raised by verifiers when the incoming request
+  # does not pass authentication checks.
+  #
+  # @example Raising a verification error
+  #   raise Hooksmith::VerificationError, 'Invalid signature'
+  #
+  # @example Raising with additional context
+  #   raise Hooksmith::VerificationError.new('Signature mismatch', provider: 'stripe', reason: 'invalid_hmac')
+  #
+  class VerificationError < Error
+    # @return [String, nil] the reason for verification failure
+    attr_reader :reason
+
+    # Initializes a new VerificationError.
+    #
+    # @param message [String] the error message
+    # @param provider [String, nil] the provider name
+    # @param event [String, nil] the event name
+    # @param reason [String, nil] additional reason for failure
+    def initialize(message = 'Webhook verification failed', provider: nil, event: nil, reason: nil)
+      @reason = reason
+      super(message, provider:, event:)
+    end
+  end
+
+  # Raised when no processor is registered for an event.
+  #
+  # This error can be raised when strict mode is enabled and no processor
+  # is found for a given provider/event combination.
+  #
+  # @example
+  #   raise Hooksmith::NoProcessorError.new('stripe', 'unknown_event')
+  #
+  class NoProcessorError < Error
+    # Initializes a new NoProcessorError.
+    #
+    # @param provider [String, Symbol] the provider name
+    # @param event [String, Symbol] the event name
+    def initialize(provider, event)
+      super(
+        "No processor registered for #{provider} event #{event}",
+        provider:,
+        event:
+      )
+    end
+  end
+
+  # Raised when multiple processors can handle the same event.
+  #
+  # This error is raised when more than one processor's `can_handle?`
+  # method returns true for the same webhook event. Hooksmith enforces
+  # exactly-one processor semantics.
+  #
+  # This error intentionally does not include the full payload in the message
+  # to prevent PII exposure in logs and error tracking systems.
+  #
+  # @example
+  #   raise Hooksmith::MultipleProcessorsError.new('stripe', 'charge.succeeded', payload)
+  #
+  class MultipleProcessorsError < Error
+    # @return [Integer] the number of bytes in the payload (for debugging)
+    attr_reader :payload_size
+    # @return [Array<String>] the names of the matching processor classes
+    attr_reader :processor_names
+
+    # Initializes the error with details about the provider and event.
+    #
+    # @param provider [String, Symbol] the provider name
+    # @param event [String, Symbol] the event name
+    # @param payload [Hash] the webhook payload (not included in message to prevent PII exposure)
+    # @param processor_names [Array<String>] the names of the matching processor classes
+    def initialize(provider, event, payload, processor_names: [])
+      @payload_size = payload.to_s.bytesize
+      @processor_names = processor_names
+      super(
+        "Multiple processors found for #{provider} event #{event} (payload_size=#{@payload_size} bytes)",
+        provider:,
+        event:
+      )
+    end
+  end
+
+  # Raised when a processor encounters an error during processing.
+  #
+  # This error wraps the original exception and provides additional context
+  # about which processor failed and for which event.
+  #
+  # @example
+  #   raise Hooksmith::ProcessorError.new(
+  #     'Payment processing failed',
+  #     provider: 'stripe',
+  #     event: 'charge.succeeded',
+  #     processor_class: 'StripeChargeProcessor',
+  #     original_error: original_exception
+  #   )
+  #
+  class ProcessorError < Error
+    # @return [String] the processor class name
+    attr_reader :processor_class
+    # @return [Exception, nil] the original exception
+    attr_reader :original_error
+
+    # Initializes a new ProcessorError.
+    #
+    # @param message [String] the error message
+    # @param provider [String, Symbol] the provider name
+    # @param event [String, Symbol] the event name
+    # @param processor_class [String, Class] the processor class name
+    # @param original_error [Exception, nil] the original exception
+    def initialize(message, provider:, event:, processor_class:, original_error: nil)
+      @processor_class = processor_class.to_s
+      @original_error = original_error
+      super(message, provider:, event:)
+    end
+  end
+
+  # Raised when the event name is not recognized or invalid.
+  #
+  # This error can be raised when strict event validation is enabled
+  # and an unknown event type is received.
+  #
+  # @example
+  #   raise Hooksmith::UnknownEventError.new('stripe', 'invalid.event.type')
+  #
+  class UnknownEventError < Error
+    # Initializes a new UnknownEventError.
+    #
+    # @param provider [String, Symbol] the provider name
+    # @param event [String, Symbol] the event name
+    def initialize(provider, event)
+      super(
+        "Unknown event '#{event}' for provider '#{provider}'",
+        provider:,
+        event:
+      )
+    end
+  end
+
+  # Raised when the payload is invalid or malformed.
+  #
+  # This error can be raised during payload validation when the
+  # webhook data doesn't match expected schema or format.
+  #
+  # @example
+  #   raise Hooksmith::InvalidPayloadError.new(
+  #     'Missing required field: id',
+  #     provider: 'stripe',
+  #     event: 'charge.succeeded'
+  #   )
+  #
+  class InvalidPayloadError < Error
+    # @return [Array<String>] list of validation errors
+    attr_reader :validation_errors
+
+    # Initializes a new InvalidPayloadError.
+    #
+    # @param message [String] the error message
+    # @param provider [String, Symbol, nil] the provider name
+    # @param event [String, Symbol, nil] the event name
+    # @param validation_errors [Array<String>] list of validation errors
+    def initialize(message = 'Invalid webhook payload', provider: nil, event: nil, validation_errors: [])
+      @validation_errors = validation_errors
+      super(message, provider:, event:)
+    end
+  end
+
+  # Raised when event persistence fails.
+  #
+  # This error is raised when the event store is configured but
+  # fails to persist the webhook event.
+  #
+  # @example
+  #   raise Hooksmith::PersistenceError.new(
+  #     'Failed to save webhook event',
+  #     provider: 'stripe',
+  #     event: 'charge.succeeded',
+  #     original_error: ActiveRecord::RecordInvalid.new(...)
+  #   )
+  #
+  class PersistenceError < Error
+    # @return [Exception, nil] the original exception
+    attr_reader :original_error
+
+    # Initializes a new PersistenceError.
+    #
+    # @param message [String] the error message
+    # @param provider [String, Symbol, nil] the provider name
+    # @param event [String, Symbol, nil] the event name
+    # @param original_error [Exception, nil] the original exception
+    def initialize(message = 'Failed to persist webhook event', provider: nil, event: nil, original_error: nil)
+      @original_error = original_error
+      super(message, provider:, event:)
+    end
+  end
+
+  # Raised when configuration is invalid or incomplete.
+  #
+  # This error is raised during configuration validation when
+  # required settings are missing or invalid.
+  #
+  # @example
+  #   raise Hooksmith::ConfigurationError, 'Provider name cannot be blank'
+  #
+  class ConfigurationError < Error; end
+end

data/lib/hooksmith/idempotency.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Provides idempotency support for webhook processing.
+  #
+  # Idempotency ensures that processing the same webhook multiple times
+  # (due to retries, network issues, etc.) produces the same result and
+  # doesn't cause duplicate side effects.
+  #
+  # @example Configure idempotency key extraction
+  #   Hooksmith.configure do |config|
+  #     config.provider(:stripe) do |stripe|
+  #       stripe.idempotency_key = ->(payload) { payload['id'] }
+  #       stripe.register(:charge_succeeded, 'StripeChargeProcessor')
+  #     end
+  #   end
+  #
+  # @example Check if event was already processed
+  #   key = Hooksmith::Idempotency.extract_key(provider: :stripe, payload: payload)
+  #   if Hooksmith::Idempotency.already_processed?(provider: :stripe, key: key)
+  #     return # Skip duplicate
+  #   end
+  #
+  module Idempotency
+    module_function
+
+    # Extracts an idempotency key from a webhook payload.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param payload [Hash] the webhook payload
+    # @return [String, nil] the idempotency key or nil if not configured
+    def extract_key(provider:, payload:)
+      extractor = Hooksmith.configuration.idempotency_key_for(provider)
+      return nil unless extractor
+
+      key = extractor.call(payload)
+      key&.to_s
+    rescue StandardError => e
+      Hooksmith.logger.error("Failed to extract idempotency key for #{provider}: #{e.message}")
+      nil
+    end
+
+    # Checks if an event with the given idempotency key was already processed.
+    #
+    # This requires the event store to be enabled and the model to respond to
+    # `exists_with_idempotency_key?` or have a `find_by_idempotency_key` method.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param key [String] the idempotency key
+    # @return [Boolean] true if already processed
+    def already_processed?(provider:, key:)
+      return false if key.nil?
+
+      config = Hooksmith.configuration.event_store_config
+      return false unless config.enabled
+
+      model_class = config.model_class
+      return false unless model_class
+
+      check_duplicate(model_class, provider.to_s, key)
+    rescue StandardError => e
+      Hooksmith.logger.error("Failed to check idempotency for #{provider}: #{e.message}")
+      false
+    end
+
+    # Generates a composite idempotency key from multiple fields.
+    #
+    # @param fields [Array<String, Symbol, nil>] the fields to combine
+    # @param separator [String] the separator between fields
+    # @return [String] the composite key
+    def composite_key(*fields, separator: ':')
+      fields.compact.map(&:to_s).join(separator)
+    end
+
+    # Common idempotency key extractors for popular webhook providers.
+    module Extractors
+      # Stripe uses the event ID as the idempotency key.
+      STRIPE = ->(payload) { payload['id'] || payload[:id] }
+
+      # GitHub uses the delivery ID header (must be passed in payload).
+      GITHUB = ->(payload) { payload['delivery_id'] || payload[:delivery_id] }
+
+      # Generic extractor that looks for common ID fields.
+      GENERIC = lambda do |payload|
+        payload['id'] || payload[:id] ||
+          payload['event_id'] || payload[:event_id] ||
+          payload['webhook_id'] || payload[:webhook_id]
+      end
+    end
+
+    class << self
+      private
+
+      def check_duplicate(model_class, provider, key)
+        if model_class.respond_to?(:exists_with_idempotency_key?)
+          model_class.exists_with_idempotency_key?(provider:, idempotency_key: key)
+        elsif model_class.respond_to?(:find_by_idempotency_key)
+          !model_class.find_by_idempotency_key(provider:, idempotency_key: key).nil?
+        elsif model_class.respond_to?(:exists?)
+          model_class.exists?(provider:, idempotency_key: key)
+        else
+          false
+        end
+      end
+    end
+  end
+end

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