pigeon-rb 0.1.0

data/lib/pigeon/publisher.rb

@@ -0,0 +1,524 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+require_relative "metrics/collector"
+
+module Pigeon
+  # Publisher class for storing messages in the outbox
+  class Publisher
+    # Mock outbox message class for testing
+    class MockOutboxMessage < Pigeon::Models::OutboxMessage
+      def save?
+        true
+      end
+
+      def self.create(attributes = {})
+        new(attributes)
+      end
+    end
+
+    # Initialize a new publisher
+    def initialize
+      @metrics = Pigeon.config.metrics_collector || Pigeon::Metrics::Collector.new
+    end
+
+    # Publish a message to Kafka via the outbox pattern
+    # @param topic [String] Kafka topic
+    # @param payload [Hash, String] Message payload
+    # @param key [String, nil] Optional message key
+    # @param headers [Hash, nil] Optional message headers
+    # @param sync [Boolean] Whether to attempt immediate publishing
+    # @param partition [Integer, nil] Optional specific partition
+    # @param correlation_id [String, nil] Optional correlation ID for tracing
+    # @param max_retries [Integer, nil] Optional override for max retries
+    # @param schema_name [String, Symbol, nil] Optional schema name for validation
+    # @param schema [Hash, String, nil] Optional schema for validation
+    # @param encrypt [Boolean] Whether to encrypt the payload
+    # @param encryption_key [String, nil] Optional encryption key
+    # @param sensitive_fields [Array<String, Symbol>, nil] Optional sensitive fields to mask in logs
+    # @return [Pigeon::Models::OutboxMessage] The created outbox message record
+    def publish(topic:, payload:, **options)
+      Pigeon::Tracing.trace_publish(
+        topic: topic,
+        payload: payload,
+        key: options[:key],
+        headers: options[:headers],
+        correlation_id: options[:correlation_id]
+      ) do |span, _context, trace_headers|
+        start_time = Time.now
+        correlation_id = prepare_publish_context(topic, payload, options, span)
+        serialized_payload = prepare_payload(payload, options)
+        merged_headers = merge_trace_headers(options[:headers], trace_headers)
+
+        message_attributes = build_message_attributes(
+          topic: topic,
+          key: options[:key],
+          headers: merged_headers,
+          partition: options[:partition],
+          payload: serialized_payload,
+          correlation_id: correlation_id,
+          max_retries: options[:max_retries]
+        )
+
+        outbox_message = create_outbox_message_in_transaction(message_attributes)
+        handle_publish_result(outbox_message, serialized_payload, topic, start_time, span, options)
+
+        outbox_message
+      end
+    end
+
+    # Publish a message directly to Kafka without using the outbox pattern
+    # This is useful for non-critical messages where at-least-once delivery is not required
+    # @param topic [String] Kafka topic
+    # @param payload [Hash, String] Message payload
+    # @param key [String, nil] Optional message key
+    # @param headers [Hash, nil] Optional message headers
+    # @param partition [Integer, nil] Optional specific partition
+    # @param schema_name [String, Symbol, nil] Optional schema name for validation
+    # @param schema [Hash, String, nil] Optional schema for validation
+    # @param encrypt [Boolean] Whether to encrypt the payload
+    # @param encryption_key [String, nil] Optional encryption key
+    # @param sensitive_fields [Array<String, Symbol>, nil] Optional sensitive fields to mask in logs
+    # @param correlation_id [String, nil] Optional correlation ID for tracing
+    # @return [Boolean] Whether the publish was successful
+    def publish_direct(topic:, payload:, **options)
+      Pigeon::Tracing.trace_publish(
+        topic: topic,
+        payload: payload,
+        key: options[:key],
+        headers: options[:headers],
+        correlation_id: options[:correlation_id]
+      ) do |span, _context, trace_headers|
+        execute_direct_publish(topic, payload, options, span, trace_headers)
+      end
+    rescue Pigeon::Serializer::ValidationError, ArgumentError => e
+      handle_validation_error(e, topic)
+    rescue StandardError => e
+      handle_direct_publish_error(e, topic)
+    end
+
+    private
+
+    # Prepare publish context
+    # @param topic [String] Kafka topic
+    # @param payload [Hash, String] Message payload
+    # @param options [Hash] Publishing options
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [String] Correlation ID
+    def prepare_publish_context(topic, payload, options, span)
+      validate_publish_params(topic, payload)
+      correlation_id = options[:correlation_id] || SecureRandom.uuid
+      masked_payload = mask_sensitive_fields(payload, options[:sensitive_fields])
+
+      span&.add_attributes("messaging.correlation_id" => correlation_id)
+      log_publish_attempt(topic, masked_payload, correlation_id)
+      validate_payload?(payload, options[:schema_name], options[:schema])
+
+      correlation_id
+    end
+
+    # Prepare payload for publishing
+    # @param payload [Hash, String] Message payload
+    # @param options [Hash] Publishing options
+    # @return [String] Prepared payload
+    def prepare_payload(payload, options)
+      should_encrypt = determine_encryption_setting(options[:encrypt])
+      serialized_payload = serialize_payload(payload)
+      serialized_payload = encrypt_payload(serialized_payload, options[:encryption_key]) if should_encrypt
+      serialized_payload
+    end
+
+    # Merge trace headers with provided headers
+    # @param headers [Hash, nil] Provided headers
+    # @param trace_headers [Hash, nil] Trace headers
+    # @return [Hash] Merged headers
+    def merge_trace_headers(headers, trace_headers)
+      merged_headers = headers ? headers.dup : {}
+      merged_headers.merge!(trace_headers) if trace_headers
+      merged_headers
+    end
+
+    # Handle publish result
+    # @param outbox_message [Pigeon::Models::OutboxMessage, nil] Created message
+    # @param serialized_payload [String] Serialized payload
+    # @param topic [String] Kafka topic
+    # @param start_time [Time] Start time
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @param options [Hash] Publishing options
+    # @return [void]
+    def handle_publish_result(outbox_message, serialized_payload, topic, start_time, span, options)
+      if outbox_message
+        record_successful_publish_metrics(serialized_payload, topic, start_time)
+        span&.add_attributes("messaging.message_id" => outbox_message.id.to_s)
+        handle_sync_publishing(outbox_message, options[:sync], topic, options[:correlation_id])
+      else
+        record_failed_publish_metrics(topic, span)
+      end
+    end
+
+    # Record successful publish metrics
+    # @param serialized_payload [String] Serialized payload
+    # @param topic [String] Kafka topic
+    # @param start_time [Time] Start time
+    # @return [void]
+    def record_successful_publish_metrics(serialized_payload, topic, start_time)
+      @metrics.increment(:messages_published_to_outbox_total, 1, { topic: topic })
+
+      if serialized_payload.respond_to?(:bytesize)
+        payload_size = serialized_payload.bytesize
+        @metrics.histogram(:message_size_bytes, payload_size, { topic: topic })
+      end
+
+      publish_time = Time.now - start_time
+      @metrics.histogram(:message_publish_duration_seconds, publish_time, { topic: topic })
+    end
+
+    # Record failed publish metrics
+    # @param topic [String] Kafka topic
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [void]
+    def record_failed_publish_metrics(topic, span)
+      @metrics.increment(:messages_publish_failures_total, 1, { topic: topic })
+      span&.record_exception(StandardError.new("Failed to create outbox message"))
+      span&.status = OpenTelemetry::Trace::Status.error("Failed to create outbox message") if span
+    end
+
+    # Execute direct publish
+    # @param topic [String] Kafka topic
+    # @param payload [Hash, String] Message payload
+    # @param options [Hash] Publishing options
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @param trace_headers [Hash] Trace headers
+    # @return [Boolean] Success status
+    def execute_direct_publish(topic, payload, options, span, trace_headers)
+      start_time = Time.now
+      prepare_publish_context(topic, payload, options, span)
+      serialized_payload = prepare_payload(payload, options)
+      merged_headers = merge_trace_headers(options[:headers], trace_headers)
+
+      message_options = build_direct_message_options(
+        topic: topic,
+        key: options[:key],
+        headers: merged_headers,
+        partition: options[:partition]
+      )
+
+      record_direct_message_size(serialized_payload, topic)
+      Pigeon.karafka_producer.produce_sync(serialized_payload, **message_options)
+      record_direct_publish_success(topic, start_time)
+
+      true
+    end
+
+    # Record direct message size
+    # @param serialized_payload [String] Serialized payload
+    # @param topic [String] Kafka topic
+    # @return [void]
+    def record_direct_message_size(serialized_payload, topic)
+      return unless serialized_payload.respond_to?(:bytesize)
+
+      payload_size = serialized_payload.bytesize
+      @metrics.histogram(:direct_message_size_bytes, payload_size, { topic: topic })
+    end
+
+    # Record direct publish success
+    # @param topic [String] Kafka topic
+    # @param start_time [Time] Start time
+    # @return [void]
+    def record_direct_publish_success(topic, start_time)
+      @metrics.increment(:messages_published_direct_total, 1, { topic: topic })
+      publish_time = Time.now - start_time
+      @metrics.histogram(:message_publish_direct_duration_seconds, publish_time, { topic: topic })
+    end
+
+    # Handle validation error
+    # @param error [StandardError] Validation error
+    # @param topic [String] Kafka topic
+    # @return [void]
+    def handle_validation_error(error, topic)
+      @metrics.increment(:messages_validation_errors_total, 1, {
+                           topic: topic,
+                           error: error.class.name
+                         })
+      raise error
+    end
+
+    # Handle direct publish error
+    # @param error [StandardError] Publish error
+    # @param topic [String] Kafka topic
+    # @return [Boolean] Always false
+    def handle_direct_publish_error(error, topic)
+      @metrics.increment(:messages_published_direct_error_total, 1, {
+                           topic: topic,
+                           error: error.class.name
+                         })
+
+      Pigeon.config.logger.error("Failed to publish message directly: #{error.message}")
+      false
+    end
+
+    def validate_publish_params(topic, payload)
+      raise ArgumentError, "Topic is required" if topic.nil? || topic.empty?
+      raise ArgumentError, "Payload is required" if payload.nil?
+    end
+
+    def determine_encryption_setting(encrypt)
+      encrypt.nil? ? Pigeon.config.encrypt_payload : encrypt
+    end
+
+    def build_message_attributes(attributes)
+      {
+        topic: attributes[:topic],
+        key: attributes[:key],
+        headers: attributes[:headers] || {},
+        partition: attributes[:partition],
+        payload: attributes[:payload],
+        status: "pending",
+        correlation_id: attributes[:correlation_id],
+        max_retries: attributes[:max_retries] || Pigeon.config.max_retries
+      }
+    end
+
+    def build_direct_message_options(topic:, key:, headers:, partition:)
+      options = { topic: topic }
+      options[:key] = key if key
+      options[:headers] = headers if headers && !headers.empty?
+      options[:partition] = partition if partition
+      options
+    end
+
+    def handle_sync_publishing(outbox_message, sync, topic, correlation_id)
+      return unless sync
+
+      begin
+        start_time = Time.now
+        success = publish_to_kafka(outbox_message)
+
+        if success
+          outbox_message.mark_as_published
+          log_sync_success(topic, correlation_id)
+
+          # Record successful sync publication
+          @metrics.increment(:messages_published_sync_succeeded_total, 1, { topic: topic })
+
+          # Record sync publication latency
+          publish_time = Time.now - start_time
+          @metrics.histogram(:message_publish_sync_duration_seconds, publish_time, { topic: topic })
+        else
+          log_sync_failure(topic, correlation_id)
+
+          # Record failed sync publication
+          @metrics.increment(:messages_published_sync_failed_total, 1, { topic: topic })
+        end
+      rescue StandardError => e
+        log_sync_error(e, correlation_id)
+
+        # Record failed sync publication due to error
+        @metrics.increment(:messages_published_sync_error_total, 1, {
+                             topic: topic,
+                             error: e.class.name
+                           })
+
+        # Message remains in the outbox for async processing
+      end
+    end
+
+    def log_sync_success(topic, correlation_id)
+      logger = Pigeon.config.logger
+
+      if logger.respond_to?(:with_context)
+        # Create a logger with correlation ID context
+        logger = logger.with_context(
+          correlation_id: correlation_id,
+          topic: topic
+        )
+
+        logger.info("Message published synchronously", {
+                      action: "publish_sync",
+                      status: "success"
+                    })
+      else
+        # Fallback for standard loggers
+        logger.info("Message published synchronously to topic: #{topic} (correlation_id: #{correlation_id})")
+      end
+    end
+
+    def log_sync_failure(topic, correlation_id)
+      logger = Pigeon.config.logger
+
+      if logger.respond_to?(:with_context)
+        # Create a logger with correlation ID context
+        logger = logger.with_context(
+          correlation_id: correlation_id,
+          topic: topic
+        )
+
+        logger.error("Failed to publish message synchronously", {
+                       action: "publish_sync",
+                       status: "failure"
+                     })
+      else
+        # Fallback for standard loggers
+        logger.error("Failed to publish message synchronously to topic: #{topic} (correlation_id: #{correlation_id})")
+      end
+    end
+
+    def log_sync_error(error, correlation_id)
+      logger = Pigeon.config.logger
+
+      if logger.respond_to?(:with_context)
+        # Create a logger with correlation ID context
+        logger = logger.with_context(
+          correlation_id: correlation_id
+        )
+
+        logger.error("Failed to publish message synchronously",
+                     {
+                       action: "publish_sync",
+                       status: "error",
+                       error_class: error.class.name,
+                       error_message: error.message
+                     },
+                     error)
+      else
+        # Fallback for standard loggers
+        logger.error("Failed to publish message synchronously: #{error.message} (correlation_id: #{correlation_id})")
+      end
+    end
+
+    # Create outbox message in a transaction
+    # @param attributes [Hash] Message attributes
+    # @return [Pigeon::Models::OutboxMessage, nil] The created outbox message record
+    def create_outbox_message_in_transaction(attributes)
+      if defined?(ActiveRecord) && ActiveRecord::Base.respond_to?(:transaction)
+        # Use ActiveRecord transaction
+        ActiveRecord::Base.transaction do
+          Pigeon.create_outbox_message(attributes)
+        end
+      elsif defined?(ROM) && ROM.env.respond_to?(:transaction)
+        # Use ROM transaction
+        ROM.env.transaction do
+          Pigeon.create_outbox_message(attributes)
+        end
+      elsif defined?(RSpec)
+        # No transaction support or in test environment, use mock implementation
+        # In test environment, use the mock implementation
+        MockOutboxMessage.create(attributes)
+      else
+        # No transaction support, just create the message
+        Pigeon.create_outbox_message(attributes)
+      end
+    rescue StandardError => e
+      Pigeon.config.logger.error("Failed to create outbox message: #{e.message}")
+      nil
+    end
+
+    # Publish a message to Kafka
+    # @param message [Pigeon::Models::OutboxMessage] Outbox message to publish
+    # @return [Boolean] Whether the publish was successful
+    def publish_to_kafka(message)
+      # Prepare message options
+      message_options = { topic: message.topic }
+      message_options[:key] = message.key if message.key
+      message_options[:headers] = message.headers if message.headers && !message.headers.empty?
+      message_options[:partition] = message.partition if message.partition
+
+      # Use Karafka producer to send the message
+      Pigeon.karafka_producer.produce_sync(message.payload, **message_options)
+      true
+    rescue StandardError => e
+      if message.respond_to?(:error_message=)
+        message.error_message = "#{e.class}: #{e.message}"
+        message.save if message.respond_to?(:save)
+      end
+      raise e # Re-raise the error to be caught by the caller
+    end
+
+    # Validate payload against schema
+    # @param payload [Hash, String] Payload to validate
+    # @param schema_name [String, Symbol, nil] Schema name for validation
+    # @param schema [Hash, String, nil] Schema for validation
+    # @return [Boolean] Whether the payload is valid
+    # @raise [Pigeon::Serializer::ValidationError] If the payload is invalid
+    def validate_payload?(payload, schema_name, schema)
+      return true unless Pigeon.config.schema_validation_enabled
+      return true if schema_name.nil? && schema.nil?
+
+      if schema_name
+        Pigeon::Serializer.validate_with_registered_schema(payload, schema_name)
+      elsif schema
+        Pigeon::Serializer.validate(payload, schema)
+      end
+
+      true
+    end
+
+    # Serialize payload for publishing
+    # @param payload [Hash, String] Payload to serialize
+    # @return [String] Serialized payload
+    def serialize_payload(payload)
+      Pigeon::Serializer.serialize(payload)
+    end
+
+    # Encrypt payload for publishing
+    # @param payload [String] Serialized payload
+    # @param encryption_key [String, nil] Optional encryption key
+    # @return [Hash, String] Encrypted payload or original payload if encryption is disabled
+    def encrypt_payload(payload, encryption_key = nil)
+      Pigeon::Encryption.encrypt(payload, encryption_key)
+    end
+
+    # Mask sensitive fields in the payload for logging
+    # @param payload [Hash, String] Payload to mask
+    # @param sensitive_fields [Array<String, Symbol>, nil] Optional sensitive fields to mask
+    # @return [Hash, String] Masked payload
+    def mask_sensitive_fields(payload, sensitive_fields = nil)
+      # Use provided sensitive fields or get them from the configuration
+      fields_to_mask = sensitive_fields || Pigeon.config.sensitive_fields
+      return payload if fields_to_mask.nil? || fields_to_mask.empty?
+
+      Pigeon::Encryption.mask_payload(payload, fields_to_mask)
+    end
+
+    # Log the publish attempt with masked payload
+    # @param topic [String] Kafka topic
+    # @param payload [Hash, String] Masked payload
+    # @param correlation_id [String] Correlation ID
+    # @return [void]
+    def log_publish_attempt(topic, payload, correlation_id)
+      logger = Pigeon.config.logger
+
+      # Create a logger with correlation ID context if supported
+      if logger.respond_to?(:with_context)
+        logger = logger.with_context(
+          correlation_id: correlation_id,
+          topic: topic
+        )
+
+        # Log the basic information with context
+        logger.info("Publishing message", {
+                      action: "publish",
+                      sync: false
+                    })
+
+        # Log the payload if debug level is enabled
+        if logger.debug?
+          payload_str = payload.is_a?(String) ? payload : payload.to_json
+          logger.debug("Message payload", {
+                         payload: payload_str
+                       })
+        end
+      else
+        # Fallback for standard loggers
+        logger.info("Publishing message to topic: #{topic} (correlation_id: #{correlation_id})")
+
+        # Log the payload if debug level is enabled
+        if logger.respond_to?(:debug?) && logger.debug?
+          payload_str = payload.is_a?(String) ? payload : payload.to_json
+          logger.debug("Message payload: #{payload_str}")
+        end
+      end
+    end
+  end
+end

data/lib/pigeon/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails"
+require "pigeon"
+
+module Pigeon
+  # Rails integration for Pigeon
+  class Railtie < Rails::Railtie
+    initializer "pigeon.configure" do |app|
+      # Set up default logger to use Rails logger
+      Pigeon.configure do |config|
+        config.logger = Rails.logger
+      end
+
+      app.config.paths["lib/generators"] ||= []
+      app.config.paths["lib/generators"] << File.expand_path("generators/rails", __dir__)
+    end
+
+    # Add rake tasks
+    rake_tasks do
+      load "pigeon/tasks/pigeon.rake"
+    end
+
+    # Add ActiveJob integration
+    config.after_initialize do
+      require "pigeon/active_job_integration" if defined?(ActiveJob)
+    end
+  end
+end

data/lib/pigeon/schema.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Pigeon
+  # Schema-related functionality for Pigeon
+  module Schema
+    # Register a JSON schema for validation
+    # @param name [String, Symbol] Schema name
+    # @param schema [Hash, String] JSON schema
+    # @return [void]
+    def self.register_schema(name, schema)
+      Configuration.register_schema(name, schema)
+    end
+
+    # Get a registered schema
+    # @param name [String, Symbol] Schema name
+    # @return [Hash, String, nil] JSON schema or nil if not found
+    def self.schema(name)
+      Configuration.schema(name)
+    end
+
+    # Register a sensitive field for masking
+    # @param field [String, Symbol] Field name
+    # @return [void]
+    def self.register_sensitive_field(field)
+      Configuration.register_sensitive_field(field)
+    end
+
+    # Register multiple sensitive fields for masking
+    # @param fields [Array<String, Symbol>] Field names
+    # @return [void]
+    def self.register_sensitive_fields(fields)
+      Configuration.register_sensitive_fields(fields)
+    end
+  end
+end

data/lib/pigeon/security.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pigeon
+  # Security-related functionality for Pigeon
+  module Security
+    # Encrypt a payload
+    # @param payload [String] Payload to encrypt
+    # @param encryption_key [String, nil] Optional encryption key
+    # @return [Hash] Encrypted payload with metadata
+    def self.encrypt(payload, encryption_key = nil)
+      Encryption.encrypt(payload, encryption_key)
+    end
+
+    # Decrypt a payload
+    # @param encrypted_payload [Hash] Encrypted payload with metadata
+    # @param encryption_key [String, nil] Optional encryption key
+    # @return [String] Decrypted payload
+    def self.decrypt(encrypted_payload, encryption_key = nil)
+      Encryption.decrypt(encrypted_payload, encryption_key)
+    end
+
+    # Mask sensitive data in a payload
+    # @param payload [Hash, String] Payload to mask
+    # @param sensitive_fields [Array<String, Symbol>] Fields to mask
+    # @return [Hash, String] Masked payload
+    def self.mask_payload(payload, sensitive_fields = nil)
+      Encryption.mask_payload(payload, sensitive_fields || Core.config.sensitive_fields)
+    end
+  end
+end

data/lib/pigeon/serializer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require "json-schema" if Gem::Specification.find_all_by_name("json-schema").any?
+
+module Pigeon
+  # Serializer module for handling payload serialization and validation
+  module Serializer
+    # Serialize a payload to JSON
+    # @param payload [Hash, Array, String] Payload to serialize
+    # @return [String] Serialized JSON string
+    def self.serialize(payload)
+      return payload if payload.is_a?(String)
+
+      ::JSON.generate(payload)
+    rescue StandardError => e
+      raise SerializationError, "Failed to serialize payload: #{e.message}"
+    end
+
+    # Deserialize a JSON string to a Ruby object
+    # @param json_string [String] JSON string to deserialize
+    # @param symbolize_names [Boolean] Whether to symbolize hash keys
+    # @return [Hash, Array] Deserialized Ruby object
+    def self.deserialize(json_string, symbolize_names: false)
+      return json_string unless json_string.is_a?(String)
+      return {} if json_string.empty?
+
+      ::JSON.parse(json_string, symbolize_names: symbolize_names)
+    rescue StandardError => e
+      raise DeserializationError, "Failed to deserialize JSON: #{e.message}"
+    end
+
+    # Validate a payload against a JSON schema
+    # @param payload [Hash, Array, String] Payload to validate
+    # @param schema [Hash, String] JSON schema to validate against
+    # @return [Boolean] Whether the payload is valid
+    # @raise [ValidationError] If the payload is invalid
+    def self.validate(payload, schema)
+      # Skip validation if json-schema gem is not available
+      unless defined?(::JSON::Validator)
+        Pigeon.config.logger.warn("json-schema gem not available, skipping validation")
+        return true
+      end
+
+      # Parse the payload if it's a string
+      payload_obj = payload.is_a?(String) ? deserialize(payload) : payload
+
+      # Parse the schema if it's a string
+      schema_obj = schema.is_a?(String) ? deserialize(schema) : schema
+
+      # Validate the payload against the schema
+      ::JSON::Validator.validate!(schema_obj, payload_obj)
+      true
+    rescue ::JSON::Schema::ValidationError => e
+      raise ValidationError, "Payload validation failed: #{e.message}"
+    rescue StandardError => e
+      raise ValidationError, "Schema validation error: #{e.message}"
+    end
+
+    # Validate a payload against a registered schema
+    # @param payload [Hash, Array, String] Payload to validate
+    # @param schema_name [String, Symbol] Name of the registered schema
+    # @return [Boolean] Whether the payload is valid
+    # @raise [ValidationError] If the payload is invalid or schema not found
+    def self.validate_with_registered_schema(payload, schema_name)
+      schema = Pigeon.config.schemas[schema_name.to_sym]
+      raise ValidationError, "Schema '#{schema_name}' not found" unless schema
+
+      validate(payload, schema)
+    end
+
+    # Custom error classes
+    class SerializationError < StandardError; end
+    class DeserializationError < StandardError; end
+    class ValidationError < StandardError; end
+  end
+end