hooksmith 0.1.2 → 1.0.0

data/lib/hooksmith/configuration.rb

@@ -3,24 +3,41 @@
 # Provides a DSL for registering webhook processors by provider and event.
 #
 module Hooksmith
-  # Configuration holds the registry of all processors.
+  # Configuration holds the registry of all processors, verifiers, and idempotency settings.
+  #
+  # The registry uses string keys internally to prevent Symbol DoS attacks
+  # when processing untrusted webhook input. Provider and event names from
+  # external sources are converted to strings, not symbols.
   class Configuration
-    # @return [Hash] a registry mapping provider symbols to arrays of processor entries.
+    # @return [Hash] a registry mapping provider strings to arrays of processor entries.
     attr_reader :registry
+    # @return [Hash] a registry mapping provider strings to verifier instances.
+    attr_reader :verifiers
+    # @return [Hash] a registry mapping provider strings to idempotency key extractors.
+    attr_reader :idempotency_keys
+    # @return [Hooksmith::Config::EventStore] configuration for event persistence
+    attr_reader :event_store_config
 
     def initialize
-      # Registry structure: { provider_symbol => [{ event: event_symbol, processor: ProcessorClass }, ...] }
+      # Registry structure: { "provider" => [{ event: "event", processor: "ProcessorClass" }, ...] }
+      # Uses strings to prevent Symbol DoS from untrusted webhook input
       @registry = Hash.new { |hash, key| hash[key] = [] }
+      @verifiers = {}
+      @idempotency_keys = {}
+      @event_store_config = Hooksmith::Config::EventStore.new
     end
 
     # Groups registrations under a specific provider.
     #
     # @param provider_name [Symbol, String] the provider name (e.g., :stripe)
-    # @yield [ProviderConfig] a block yielding a ProviderConfig object
+    # @yield [Hooksmith::Config::Provider] a block yielding a Provider object
     def provider(provider_name)
-      provider_config = ProviderConfig.new(provider_name)
+      provider_config = Hooksmith::Config::Provider.new(provider_name)
       yield(provider_config)
-      registry[provider_name.to_sym].concat(provider_config.entries)
+      provider_key = provider_name.to_s
+      registry[provider_key].concat(provider_config.entries)
+      @verifiers[provider_key] = provider_config.verifier if provider_config.verifier
+      @idempotency_keys[provider_key] = provider_config.idempotency_key if provider_config.idempotency_key
     end
 
     # Direct registration of a processor.
@@ -29,7 +46,7 @@ module Hooksmith
     # @param event [Symbol, String] the event name
     # @param processor_class_name [String] the processor class name
     def register_processor(provider, event, processor_class_name)
-      registry[provider.to_sym] << { event: event.to_sym, processor: processor_class_name }
+      registry[provider.to_s] << { event: event.to_s, processor: processor_class_name }
     end
 
     # Returns all processor entries for a given provider and event.
@@ -38,28 +55,50 @@ module Hooksmith
     # @param event [Symbol, String] the event name
     # @return [Array<Hash>] the array of matching entries.
     def processors_for(provider, event)
-      registry[provider.to_sym].select { |entry| entry[:event] == event.to_sym }
+      registry[provider.to_s].select { |entry| entry[:event] == event.to_s }
+    end
+
+    # Returns the verifier for a given provider.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @return [Hooksmith::Verifiers::Base, nil] the verifier or nil if not configured
+    def verifier_for(provider)
+      @verifiers[provider.to_s]
     end
-  end
 
-  # ProviderConfig is used internally by the DSL to collect processor registrations.
-  class ProviderConfig
-    # @return [Symbol, String] the provider name.
-    attr_reader :provider
-    # @return [Array<Hash>] list of entries registered.
-    attr_reader :entries
+    # Registers a verifier for a provider directly.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param verifier [Hooksmith::Verifiers::Base] the verifier instance
+    def register_verifier(provider, verifier)
+      @verifiers[provider.to_s] = verifier
+    end
 
-    def initialize(provider)
-      @provider = provider
-      @entries = []
+    # Returns the idempotency key extractor for a given provider.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @return [Proc, nil] the idempotency key extractor or nil if not configured
+    def idempotency_key_for(provider)
+      @idempotency_keys[provider.to_s]
     end
 
-    # Registers a processor for a specific event.
+    # Configure event store persistence.
     #
-    # @param event [Symbol, String] the event name.
-    # @param processor_class_name [String] the processor class name.
-    def register(event, processor_class_name)
-      entries << { event: event.to_sym, processor: processor_class_name }
+    # @yield [Hooksmith::Config::EventStore] a block yielding an EventStore object
+    # @example
+    #   Hooksmith.configure do |config|
+    #     config.event_store do |store|
+    #       store.enabled = true
+    #       store.model_class_name = 'MyApp::WebhookEvent'
+    #       store.record_timing = :before # or :after, or :both
+    #       store.mapper = ->(provider:, event:, payload:) {
+    #         now = Time.respond_to?(:current) ? Time.current : Time.now
+    #         { provider:, event: event.to_s, payload:, received_at: now }
+    #       }
+    #     end
+    #   end
+    def event_store
+      yield(@event_store_config)
     end
   end
 end

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,46 +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!
-      # Fetch all processors registered for this provider and event.
-      entries = Hooksmith.configuration.processors_for(@provider, @event)
+      Hooksmith::Instrumentation.instrument('dispatch', provider: @provider, event: @event) do
+        dispatch_webhook
+      end
+    end
 
-      # Instantiate each processor and filter by condition.
-      matching_processors = entries.map do |entry|
-        processor = Object.const_get(entry[:processor]).new(@payload)
-        processor if processor.can_handle?(@payload)
-      end.compact
+    private
 
-      if matching_processors.empty?
-        Hooksmith.logger.warn("No processor registered for #{@provider} event #{@event} could handle the payload")
-        return
-      end
+    def dispatch_webhook
+      record_event(:before)
+      matching = find_matching_processors
+
+      return handle_no_processor if matching.empty?
 
-      # If more than one processor qualifies, raise an error.
-      raise MultipleProcessorsError.new(@provider, @event, @payload) if matching_processors.size > 1
+      handle_multiple_processors(matching) if matching.size > 1
 
-      # Exactly one matching processor.
-      matching_processors.first.process!
+      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
-  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 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
+    end
+
+    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
+
+    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
+
+    def execute_processor(processor)
+      result = Hooksmith::Instrumentation.instrument(
+        'process',
+        provider: @provider, event: @event, processor: processor.class.name
+      ) { processor.process! }
+
+      record_event(:after)
+      result
+    end
+
+    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/event_recorder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Records webhook events to a configurable persistence model.
+  #
+  # This recorder is resilient: failures to persist are logged and do not
+  # impact the main processing flow.
+  module EventRecorder
+    module_function
+
+    # Record an event if the event store is enabled.
+    #
+    # @param provider [Symbol, String]
+    # @param event [Symbol, String]
+    # @param payload [Hash]
+    # @param timing [Symbol] one of :before or :after
+    def record!(provider:, event:, payload:, timing: :before)
+      config = Hooksmith.configuration.event_store_config
+      return unless config.enabled
+      return unless record_for_timing?(config, timing)
+
+      model_class = config.model_class
+      unless model_class
+        Hooksmith.logger.warn("Event store enabled but model '#{config.model_class_name}' not found")
+        return
+      end
+
+      attributes = safe_map(config, provider:, event:, payload:)
+      model_class.create!(attributes)
+    rescue StandardError => e
+      Hooksmith.logger.error("Failed to record webhook event: #{e.message}")
+    end
+
+    # Determine whether to record depending on the configured timing.
+    def record_for_timing?(config, timing)
+      case config.record_timing
+      when :both then true
+      when :before then timing == :before
+      when :after then timing == :after
+      end
+    end
+    private_class_method :record_for_timing?
+
+    # Safely map attributes using the configured mapper.
+    def safe_map(config, provider:, event:, payload:)
+      mapper = config.mapper
+      mapper.call(provider:, event:, payload:)
+    rescue StandardError => e
+      Hooksmith.logger.error("Event mapper raised: #{e.message}")
+      {}
+    end
+    private_class_method :safe_map
+  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