pigeon-rb 0.1.0

data/lib/pigeon/processor.rb

@@ -0,0 +1,798 @@
+# frozen_string_literal: true
+
+require "json"
+require "concurrent"
+require_relative "processor/background_processor"
+require_relative "metrics/collector"
+
+module Pigeon
+  # Processor class for handling outbox messages
+  class Processor
+    include BackgroundProcessor
+
+    # Initialize a new processor
+    # @param auto_start [Boolean] Whether to automatically start processing pending messages on initialization
+    def initialize(auto_start: false)
+      @mutex = Concurrent::ReentrantReadWriteLock.new
+      @processing = Concurrent::AtomicBoolean.new(false)
+      @thread_pool = nil
+      @metrics = Pigeon.config.metrics_collector || Pigeon::Metrics::Collector.new
+      @start_time = Time.now
+
+      # Start processing if auto_start is true
+      start_processing if auto_start
+    end
+
+    # Start processing pending messages in the background
+    # @param batch_size [Integer] Number of messages to process in one batch
+    # @param interval [Integer] Interval in seconds between processing batches
+    # @param thread_count [Integer] Number of threads to use for processing
+    # @return [Boolean] Whether processing was started
+    def start_processing(batch_size: 100, interval: 5, thread_count: 2)
+      result = start_background_processing(batch_size: batch_size, interval: interval, thread_count: thread_count)
+
+      # Record processor start time
+      Pigeon.processor_start_time = Time.now if result
+
+      result
+    end
+
+    # Stop processing pending messages
+    # @return [Boolean] Whether processing was stopped
+    def stop_processing
+      stop_background_processing
+    end
+
+    # Process pending outbox messages
+    # @param batch_size [Integer] Number of messages to process in one batch
+    # @return [Hash] Processing statistics
+    def process_pending(batch_size: 100)
+      Pigeon.last_processing_run = Time.now
+      batch_id = SecureRandom.uuid
+      logger = create_batch_logger(batch_id, batch_size)
+      log_batch_start(logger, batch_id, batch_size)
+      start_time = Time.now
+
+      stats = { processed: 0, succeeded: 0, failed: 0, retried: 0, dead_lettered: 0 }
+
+      Pigeon::Tracing.trace_batch_process(batch_size) do |span|
+        @mutex.with_read_lock do
+          process_pending_and_retry_messages(stats, batch_size, logger, span)
+        end
+
+        finalize_batch_processing(stats, start_time, logger, span)
+      end
+
+      Pigeon.last_successful_processing_run = Time.now if stats[:succeeded].positive?
+      stats
+    end
+
+    # Process a specific outbox message
+    # @param message_id [String, Integer] ID of the message to process
+    # @return [Boolean] Success status
+    def process_message(message_id)
+      Pigeon.config.logger.info("Processing message ID: #{message_id}")
+
+      # Find the message
+      message = Pigeon.find_outbox_message(message_id)
+      return false unless message
+
+      # Process the message
+      result = process_single_message(message)
+      result[:success]
+    end
+
+    # Send a failed message to a dead letter queue
+    # @param message_id [String, Integer] ID of the message to send to DLQ
+    # @param dlq_topic [String, nil] Optional dead letter queue topic (defaults to original topic with .dlq suffix)
+    # @return [Boolean] Success status
+    def send_to_dead_letter_queue(message_id, dlq_topic: nil)
+      message = Pigeon.find_outbox_message(message_id)
+      return false unless message
+
+      send_message_to_dlq(message, dlq_topic)
+    end
+
+    # Clean up old processed messages
+    # @param older_than [ActiveSupport::Duration, Integer] Age threshold for cleanup
+    # @return [Integer] Number of records cleaned up
+    def cleanup_processed(older_than: 7)
+      # This is a placeholder implementation
+      # The actual implementation will be added in task 7.2
+      Pigeon.config.logger.info("Cleaning up processed messages older than #{older_than} days")
+
+      # In the actual implementation, we would:
+      # 1. Delete processed messages older than the specified threshold
+      # 2. Return the number of deleted records
+
+      # Return mock count
+      0
+    end
+
+    private
+
+    # Create batch logger with context
+    # @param batch_id [String] Batch ID
+    # @param batch_size [Integer] Batch size
+    # @return [Logger] Logger with context
+    def create_batch_logger(batch_id, batch_size)
+      logger = Pigeon.config.logger
+      return logger unless logger.respond_to?(:with_context)
+
+      logger.with_context(batch_id: batch_id, batch_size: batch_size)
+    end
+
+    # Log batch start
+    # @param logger [Logger] Logger to use
+    # @param batch_id [String] Batch ID
+    # @param batch_size [Integer] Batch size
+    # @return [void]
+    def log_batch_start(logger, batch_id, batch_size)
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Starting to process pending messages", {
+                      batch_id: batch_id,
+                      batch_size: batch_size
+                    })
+      else
+        logger.info("Processing pending messages, batch size: #{batch_size}")
+      end
+    end
+
+    # Process pending and retry messages
+    # @param stats [Hash] Statistics to update
+    # @param batch_size [Integer] Batch size
+    # @param logger [Logger] Logger to use
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [void]
+    def process_pending_and_retry_messages(stats, batch_size, logger, span)
+      process_message_type("pending", stats, batch_size, logger, span)
+      process_message_type("retry", stats, batch_size, logger, span)
+    end
+
+    # Process messages of a specific type
+    # @param type [String] Message type ("pending" or "retry")
+    # @param stats [Hash] Statistics to update
+    # @param batch_size [Integer] Batch size
+    # @param logger [Logger] Logger to use
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [void]
+    def process_message_type(type, stats, batch_size, logger, span)
+      messages = type == "pending" ? fetch_pending_messages(batch_size) : fetch_retry_ready_messages(batch_size)
+      stats[:processed] += messages.size
+
+      log_fetched_messages(logger, messages.size, type)
+      span&.add_attributes("messaging.#{type}_messages" => messages.size)
+      process_messages_batch(messages, stats)
+    end
+
+    # Log fetched messages
+    # @param logger [Logger] Logger to use
+    # @param count [Integer] Number of messages fetched
+    # @param status [String] Message status
+    # @return [void]
+    def log_fetched_messages(logger, count, status)
+      if logger.respond_to?(:debug) && logger.method(:debug).arity > 1
+        logger.debug("Fetched #{status} messages", { count: count, status: status })
+      else
+        logger.debug("Fetched #{count} #{status} messages")
+      end
+    end
+
+    # Finalize batch processing
+    # @param stats [Hash] Processing statistics
+    # @param start_time [Time] Processing start time
+    # @param logger [Logger] Logger to use
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [void]
+    def finalize_batch_processing(stats, start_time, logger, span)
+      record_processing_metrics(stats)
+      processing_time = Time.now - start_time
+      @metrics.histogram(:processing_batch_duration_seconds, processing_time)
+      update_queue_depth_metric
+      log_processing_stats(stats, logger, processing_time)
+      add_span_attributes(span, stats, processing_time)
+    end
+
+    # Add attributes to span
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @param stats [Hash] Processing statistics
+    # @param processing_time [Float] Processing time
+    # @return [void]
+    def add_span_attributes(span, stats, processing_time)
+      span&.add_attributes({
+                             "messaging.processed" => stats[:processed],
+                             "messaging.succeeded" => stats[:succeeded],
+                             "messaging.failed" => stats[:failed],
+                             "messaging.retried" => stats[:retried],
+                             "messaging.dead_lettered" => stats[:dead_lettered],
+                             "messaging.processing_time_ms" => (processing_time * 1000).round(2)
+                           })
+    end
+
+    # Process messages in thread pool or synchronously
+    # @param messages [Array<Pigeon::Models::OutboxMessage>] Messages to process
+    # @param stats [Hash] Statistics hash to update
+    # @return [void]
+    def process_messages_batch(messages, stats)
+      messages.each do |message|
+        if @thread_pool && @processing.true?
+          # Process in thread pool if available
+          @thread_pool.post do
+            process_result = process_single_message(message)
+            update_stats(stats, process_result)
+          end
+        else
+          # Process synchronously
+          process_result = process_single_message(message)
+          update_stats(stats, process_result)
+        end
+      end
+    end
+
+    # Process a single message
+    # @param message [Pigeon::Models::OutboxMessage] Message to process
+    # @return [Hash] Processing result
+    def process_single_message(message)
+      result = { success: false, retried: false, dead_lettered: false }
+      start_time = Time.now
+      correlation_id = get_correlation_id(message)
+      logger = create_logger_with_context(message, correlation_id)
+
+      mark_message_as_processing(message)
+
+      Pigeon::Tracing.trace_process(message) do |span|
+        log_processing_attempt(logger, message)
+        add_retry_count_to_span(span, message)
+
+        publish_message_to_kafka(message)
+        message.mark_as_published
+
+        processing_time = Time.now - start_time
+        record_successful_processing_metrics(message, processing_time, span)
+        log_successful_processing(logger, message, processing_time)
+
+        result[:success] = true
+      rescue StandardError => e
+        handle_processing_error(message, message.id, e, result, logger)
+        record_failure_metrics(message, Time.now - start_time, span, e)
+      end
+
+      result
+    end
+
+    # Get correlation ID from message or generate a new one
+    # @param message [Pigeon::Models::OutboxMessage] Message to get correlation ID from
+    # @return [String] Correlation ID
+    def get_correlation_id(message)
+      correlation_id = SecureRandom.uuid
+      correlation_id = message.correlation_id || correlation_id if message.respond_to?(:correlation_id)
+      correlation_id
+    end
+
+    # Create a logger with correlation ID context if supported
+    # @param message [Pigeon::Models::OutboxMessage] Message to create logger for
+    # @param correlation_id [String] Correlation ID
+    # @return [Logger] Logger with context
+    def create_logger_with_context(message, correlation_id)
+      logger = Pigeon.config.logger
+      if logger.respond_to?(:with_context)
+        logger.with_context(
+          correlation_id: correlation_id,
+          message_id: message.id,
+          topic: message.topic
+        )
+      else
+        logger
+      end
+    end
+
+    # Log processing attempt
+    # @param logger [Logger] Logger to use
+    # @param message [Pigeon::Models::OutboxMessage] Message being processed
+    # @return [void]
+    def log_processing_attempt(logger, message)
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Processing message", {
+                      status: "processing",
+                      retry_count: message.retry_count
+                    })
+      else
+        logger.info("Processing message #{message.id} (retry count: #{message.retry_count})")
+      end
+    end
+
+    # Add retry count to span
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @param message [Pigeon::Models::OutboxMessage] Message being processed
+    # @return [void]
+    def add_retry_count_to_span(span, message)
+      span&.add_attributes("messaging.retry_count" => message.retry_count)
+    end
+
+    # Record successful processing metrics
+    # @param message [Pigeon::Models::OutboxMessage] Message that was processed
+    # @param processing_time [Float] Processing time in seconds
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @return [void]
+    def record_successful_processing_metrics(message, processing_time, span)
+      @metrics.histogram(:message_processing_duration_seconds, processing_time, { topic: message.topic })
+
+      return unless message.created_at
+
+      message_age = Time.now - message.created_at
+      @metrics.histogram(:message_age_at_processing_seconds, message_age, { topic: message.topic })
+      span&.add_attributes("messaging.age_seconds" => message_age)
+      span&.add_attributes("messaging.processing_time_ms" => (processing_time * 1000).round(2))
+    end
+
+    # Log successful processing
+    # @param logger [Logger] Logger to use
+    # @param message [Pigeon::Models::OutboxMessage] Message that was processed
+    # @param processing_time [Float] Processing time in seconds
+    # @return [void]
+    def log_successful_processing(logger, message, processing_time)
+      processing_time_ms = (processing_time * 1000).round(2)
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Successfully processed message", {
+                      status: "published",
+                      processing_time_ms: processing_time_ms
+                    })
+      else
+        logger.info("Successfully processed message #{message.id} to topic #{message.topic} in #{processing_time_ms}ms")
+      end
+    end
+
+    # Record failure metrics
+    # @param message [Pigeon::Models::OutboxMessage] Message that failed
+    # @param processing_time [Float] Processing time in seconds
+    # @param span [OpenTelemetry::Trace::Span] Tracing span
+    # @param error [StandardError] Error that occurred
+    # @return [void]
+    def record_failure_metrics(message, processing_time, span, error)
+      @metrics.histogram(:message_processing_failure_duration_seconds, processing_time, { topic: message.topic })
+      span&.record_exception(error)
+      span&.status = OpenTelemetry::Trace::Status.error(error.message) if span && defined?(OpenTelemetry::Trace::Status)
+    end
+
+    # Update statistics based on processing result
+    # @param stats [Hash] Statistics hash to update
+    # @param result [Hash] Processing result
+    # @return [void]
+    def update_stats(stats, result)
+      # Use a mutex to ensure thread safety when updating stats
+      @mutex.with_write_lock do
+        if result[:success]
+          stats[:succeeded] += 1
+        else
+          stats[:failed] += 1
+          stats[:retried] += 1 if result[:retried]
+          stats[:dead_lettered] += 1 if result[:dead_lettered]
+        end
+      end
+    end
+
+    # Log processing statistics
+    # @param stats [Hash] Processing statistics
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @param processing_time [Float] Processing time in seconds
+    # @return [void]
+    def log_processing_stats(stats, logger = nil, processing_time = nil)
+      # Use provided logger or default logger
+      logger ||= Pigeon.config.logger
+
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        # Structured logger
+        logger.info("Completed processing batch", {
+                      processed: stats[:processed],
+                      succeeded: stats[:succeeded],
+                      failed: stats[:failed],
+                      retried: stats[:retried],
+                      dead_lettered: stats[:dead_lettered],
+                      processing_time_ms: processing_time ? (processing_time * 1000).round(2) : nil
+                    })
+      else
+        # Standard logger
+        time_info = processing_time ? " in #{(processing_time * 1000).round(2)}ms" : ""
+        logger.info(
+          "Processed #{stats[:processed]} messages#{time_info}: " \
+          "#{stats[:succeeded]} succeeded, " \
+          "#{stats[:failed]} failed, " \
+          "#{stats[:retried]} retried, " \
+          "#{stats[:dead_lettered]} sent to dead letter queue"
+        )
+      end
+    end
+
+    # Record processing metrics
+    # @param stats [Hash] Processing statistics
+    # @return [void]
+    def record_processing_metrics(stats)
+      @metrics.increment(:messages_processed_total, stats[:processed])
+      @metrics.increment(:messages_succeeded_total, stats[:succeeded])
+      @metrics.increment(:messages_failed_total, stats[:failed])
+      @metrics.increment(:messages_retried_total, stats[:retried])
+      @metrics.increment(:messages_dead_lettered_total, stats[:dead_lettered])
+    end
+
+    # Update queue depth metric
+    # @return [void]
+    def update_queue_depth_metric
+      # Count pending messages
+      pending_count = Pigeon.count_outbox_messages_by_status("pending")
+      @metrics.gauge(:outbox_queue_depth, pending_count)
+
+      # Count messages in retry state
+      retry_count = Pigeon.count_outbox_messages_by_status("retry")
+      @metrics.gauge(:outbox_retry_queue_depth, retry_count)
+
+      # Count failed messages
+      failed_count = Pigeon.count_outbox_messages_by_status("failed")
+      @metrics.gauge(:outbox_failed_messages, failed_count)
+    rescue NotImplementedError => e
+      # This is expected in test environments where the adapter doesn't implement count_by_status
+      if Pigeon.config.logger.respond_to?(:debug)
+        Pigeon.config.logger.debug("Skipping queue depth metrics: #{e.message}")
+      end
+    end
+
+    # Fetch pending messages from the database
+    # @param limit [Integer] Maximum number of messages to fetch
+    # @return [Array<Pigeon::Models::OutboxMessage>] Array of pending messages
+    def fetch_pending_messages(limit)
+      Pigeon.find_outbox_messages_by_status("pending", limit)
+    end
+
+    # Fetch messages that are ready for retry
+    # @param limit [Integer] Maximum number of messages to fetch
+    # @return [Array<Pigeon::Models::OutboxMessage>] Array of messages ready for retry
+    def fetch_retry_ready_messages(limit)
+      Pigeon.find_outbox_messages_ready_for_retry(limit)
+    end
+
+    # Mark a message as processing
+    # @param message [Pigeon::Models::OutboxMessage] Message to mark as processing
+    # @return [Boolean] Whether the update was successful
+    def mark_message_as_processing(message)
+      message.status = "processing"
+      message.updated_at = Time.now
+      message.save
+    end
+
+    # Publish a message to Kafka
+    # @param message [Pigeon::Models::OutboxMessage] Message to publish
+    # @return [void]
+    def publish_message_to_kafka(message)
+      message_payload = prepare_message_payload(message)
+      message_options = build_message_options(message)
+      Pigeon.karafka_producer.produce_sync(message_payload, **message_options)
+    end
+
+    # Prepare the message payload for publishing
+    # @param message [Pigeon::Models::OutboxMessage] Message to prepare
+    # @return [String] Prepared payload
+    def prepare_message_payload(message)
+      message.payload.is_a?(String) ? message.payload : message.payload.to_json
+    end
+
+    # Build message options for Kafka
+    # @param message [Pigeon::Models::OutboxMessage] Message to build options for
+    # @return [Hash] Message options
+    def build_message_options(message)
+      options = { topic: message.topic }
+      options[:key] = message.key if message.key
+      options[:headers] = message.headers if message.headers && !message.headers.empty?
+      options[:partition] = message.partition if message.partition
+      options
+    end
+
+    # Handle processing error
+    # @param message [Pigeon::Models::OutboxMessage] Message that failed
+    # @param message_id [String, Integer] ID of the message
+    # @param error [StandardError] Error that occurred
+    # @param result [Hash] Processing result to update
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @return [void]
+    def handle_processing_error(message, message_id, error, result = {}, logger = nil)
+      logger = create_error_logger(message, message_id, logger)
+      error_classification = Pigeon::Configuration.classify_error(error)
+      log_processing_error(logger, message_id, error, error_classification)
+
+      if message.max_retries_exceeded?
+        handle_max_retries_exceeded(message, message_id, error, result, logger)
+      else
+        handle_retry(message, message_id, result, logger)
+      end
+    end
+
+    # Create error logger with context
+    # @param message [Pigeon::Models::OutboxMessage] Message that failed
+    # @param message_id [String, Integer] ID of the message
+    # @param logger [Logger] Existing logger or nil
+    # @return [Logger] Logger with context
+    def create_error_logger(message, message_id, logger)
+      return logger || Pigeon.config.logger unless !logger && Pigeon.config.logger.respond_to?(:with_context)
+
+      context = { message_id: message_id, topic: message.topic }
+      if message.respond_to?(:correlation_id) && message.correlation_id
+        context[:correlation_id] =
+          message.correlation_id
+      end
+      Pigeon.config.logger.with_context(context)
+    end
+
+    # Log processing error
+    # @param logger [Logger] Logger to use
+    # @param message_id [String, Integer] ID of the message
+    # @param error [StandardError] Error that occurred
+    # @param error_classification [String] Error classification
+    # @return [void]
+    def log_processing_error(logger, message_id, error, error_classification)
+      if logger.respond_to?(:error) && logger.method(:error).arity > 1
+        logger.error("Failed to process message",
+                     {
+                       error_class: error.class.name,
+                       error_message: error.message,
+                       error_classification: error_classification
+                     },
+                     error)
+      else
+        logger.error("Failed to process message #{message_id}: #{error.message} (#{error_classification})")
+      end
+    end
+
+    # Handle a message that has exceeded maximum retries
+    # @param message [Pigeon::Models::OutboxMessage] Message that failed
+    # @param message_id [String, Integer] ID of the message
+    # @param error [StandardError] Error that occurred
+    # @param result [Hash] Processing result to update
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @return [void]
+    def handle_max_retries_exceeded(message, message_id, error, result, logger = nil)
+      logger = create_error_logger(message, message_id, logger)
+      message.mark_as_failed(error)
+      log_max_retries_exceeded(logger, message, message_id)
+      send_to_dlq_if_enabled(message, result, logger)
+    end
+
+    # Log max retries exceeded
+    # @param logger [Logger] Logger to use
+    # @param message [Pigeon::Models::OutboxMessage] Message that failed
+    # @param message_id [String, Integer] ID of the message
+    # @return [void]
+    def log_max_retries_exceeded(logger, message, message_id)
+      if logger.respond_to?(:error) && logger.method(:error).arity > 1
+        logger.error("Message has exceeded maximum retries", {
+                       max_retries: message.max_retries,
+                       retry_count: message.retry_count,
+                       status: "failed"
+                     })
+      else
+        logger.error("Message #{message_id} has exceeded maximum retries " \
+                     "(#{message.retry_count}/#{message.max_retries}) and is marked as failed")
+      end
+    end
+
+    # Send to DLQ if enabled
+    # @param message [Pigeon::Models::OutboxMessage] Message to send
+    # @param result [Hash] Processing result to update
+    # @param logger [Logger] Logger to use
+    # @return [void]
+    def send_to_dlq_if_enabled(message, result, logger)
+      return unless Pigeon.config.respond_to?(:dead_letter_queue_enabled) && Pigeon.config.dead_letter_queue_enabled
+
+      result[:dead_lettered] = send_message_to_dlq(message, nil, logger)
+    end
+
+    # Handle a message that needs to be retried
+    # @param message [Pigeon::Models::OutboxMessage] Message to retry
+    # @param message_id [String, Integer] ID of the message
+    # @param result [Hash] Processing result to update
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @return [void]
+    def handle_retry(message, message_id, result, logger = nil)
+      logger = create_error_logger(message, message_id, logger)
+      message.increment_retry_count
+      next_retry = message.next_retry_at
+
+      record_retry_metrics(message, next_retry)
+      log_retry_scheduled(logger, message, message_id, next_retry)
+
+      result[:retried] = true
+    end
+
+    # Record retry metrics
+    # @param message [Pigeon::Models::OutboxMessage] Message being retried
+    # @param next_retry [Time] Next retry time
+    # @return [void]
+    def record_retry_metrics(message, next_retry)
+      @metrics.histogram(:message_retry_count, message.retry_count, { topic: message.topic })
+
+      return unless next_retry
+
+      time_until_retry = next_retry - Time.now
+      @metrics.histogram(:message_next_retry_delay_seconds, time_until_retry, { topic: message.topic })
+    end
+
+    # Log retry scheduled
+    # @param logger [Logger] Logger to use
+    # @param message [Pigeon::Models::OutboxMessage] Message being retried
+    # @param message_id [String, Integer] ID of the message
+    # @param next_retry [Time] Next retry time
+    # @return [void]
+    def log_retry_scheduled(logger, message, message_id, next_retry)
+      time_until_retry = next_retry ? (next_retry - Time.now).round(2) : 0
+
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Message scheduled for retry", {
+                      retry_count: message.retry_count,
+                      next_retry_at: next_retry&.iso8601,
+                      retry_delay_seconds: time_until_retry,
+                      status: "pending"
+                    })
+      else
+        logger.info("Message #{message_id} will be retried at #{next_retry}, retry count: #{message.retry_count}")
+      end
+    end
+
+    # Send a message to the dead letter queue
+    # @param message [Pigeon::Models::OutboxMessage] Message to send to DLQ
+    # @param dlq_topic [String, nil] Optional dead letter queue topic
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @return [Boolean] Whether the message was sent successfully
+    def send_message_to_dlq(message, dlq_topic = nil, logger = nil)
+      logger = create_dlq_logger(message, logger)
+      topic = dlq_topic || "#{message.topic}#{Pigeon.config.dead_letter_queue_suffix}"
+      options = build_dlq_message_options(message, topic)
+      payload = prepare_message_payload(message)
+
+      log_dlq_send_attempt(logger, message, topic)
+      send_to_dlq_topic(message, payload, options, logger)
+    end
+
+    # Create DLQ logger with context
+    # @param message [Pigeon::Models::OutboxMessage] Message being sent to DLQ
+    # @param logger [Logger] Existing logger or nil
+    # @return [Logger] Logger with context
+    def create_dlq_logger(message, logger)
+      return logger || Pigeon.config.logger unless !logger && Pigeon.config.logger.respond_to?(:with_context)
+
+      context = { message_id: message.id, topic: message.topic }
+      if message.respond_to?(:correlation_id) && message.correlation_id
+        context[:correlation_id] =
+          message.correlation_id
+      end
+      Pigeon.config.logger.with_context(context)
+    end
+
+    # Build DLQ message options
+    # @param message [Pigeon::Models::OutboxMessage] Original message
+    # @param topic [String] DLQ topic
+    # @return [Hash] Message options
+    def build_dlq_message_options(message, topic)
+      {
+        topic: topic,
+        key: message.key,
+        headers: build_dlq_headers(message),
+        partition: message.partition
+      }
+    end
+
+    # Log DLQ send attempt
+    # @param logger [Logger] Logger to use
+    # @param message [Pigeon::Models::OutboxMessage] Message being sent
+    # @param topic [String] DLQ topic
+    # @return [void]
+    def log_dlq_send_attempt(logger, message, topic)
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Sending message to dead letter queue", {
+                      dlq_topic: topic,
+                      original_topic: message.topic,
+                      retry_count: message.retry_count,
+                      error_message: message.error_message
+                    })
+      else
+        logger.info("Sending message #{message.id} to dead letter queue topic: #{topic}")
+      end
+    end
+
+    # Build headers for dead letter queue message
+    # @param message [Pigeon::Models::OutboxMessage] Original message
+    # @return [Hash] Headers for DLQ message
+    def build_dlq_headers(message)
+      headers = message.headers.dup || {}
+      headers["x-original-topic"] = message.topic
+      headers["x-error-message"] = message.error_message if message.error_message
+      headers["x-retry-count"] = message.retry_count.to_s
+      headers["x-original-timestamp"] = message.created_at.to_s
+      headers
+    end
+
+    # Send message to DLQ topic
+    # @param message [Pigeon::Models::OutboxMessage] Original message
+    # @param payload [String] Message payload
+    # @param options [Hash] Message options
+    # @param logger [Pigeon::Logging::StructuredLogger] Logger with context
+    # @return [Boolean] Whether the message was sent successfully
+    def send_to_dlq_topic(message, payload, options, logger = nil)
+      logger = create_dlq_topic_logger(message, options, logger)
+      start_time = Time.now
+
+      begin
+        Pigeon.karafka_producer.produce_sync(payload, **options)
+        handle_dlq_success(message, options, Time.now - start_time, logger)
+        true
+      rescue StandardError => e
+        handle_dlq_failure(message, options, e, logger)
+        false
+      end
+    end
+
+    # Create DLQ topic logger with context
+    # @param message [Pigeon::Models::OutboxMessage] Message being sent
+    # @param options [Hash] Message options
+    # @param logger [Logger] Existing logger or nil
+    # @return [Logger] Logger with context
+    def create_dlq_topic_logger(message, options, logger)
+      return logger || Pigeon.config.logger unless !logger && Pigeon.config.logger.respond_to?(:with_context)
+
+      context = {
+        message_id: message.id,
+        topic: message.topic,
+        dlq_topic: options[:topic]
+      }
+      if message.respond_to?(:correlation_id) && message.correlation_id
+        context[:correlation_id] =
+          message.correlation_id
+      end
+      Pigeon.config.logger.with_context(context)
+    end
+
+    # Handle successful DLQ send
+    # @param message [Pigeon::Models::OutboxMessage] Original message
+    # @param options [Hash] Message options
+    # @param dlq_time [Float] Time taken to send
+    # @param logger [Logger] Logger to use
+    # @return [void]
+    def handle_dlq_success(message, options, dlq_time, logger)
+      @metrics.histogram(:dlq_publish_duration_seconds, dlq_time, {
+                           topic: message.topic,
+                           dlq_topic: options[:topic]
+                         })
+
+      if logger.respond_to?(:info) && logger.method(:info).arity > 1
+        logger.info("Successfully sent message to dead letter queue", {
+                      dlq_topic: options[:topic],
+                      processing_time_ms: (dlq_time * 1000).round(2)
+                    })
+      else
+        logger.info("Successfully sent message #{message.id} to dead letter queue topic: #{options[:topic]}")
+      end
+    end
+
+    # Handle failed DLQ send
+    # @param message [Pigeon::Models::OutboxMessage] Original message
+    # @param options [Hash] Message options
+    # @param error [StandardError] Error that occurred
+    # @param logger [Logger] Logger to use
+    # @return [void]
+    def handle_dlq_failure(message, options, error, logger)
+      if logger.respond_to?(:error) && logger.method(:error).arity > 1
+        logger.error("Failed to send message to dead letter queue",
+                     {
+                       dlq_topic: options[:topic],
+                       error_class: error.class.name,
+                       error_message: error.message
+                     },
+                     error)
+      else
+        logger.error("Failed to send message #{message.id} to dead letter queue: #{error.message}")
+      end
+
+      @metrics.increment(:dlq_publish_failures_total, 1, {
+                           topic: message.topic,
+                           dlq_topic: options[:topic],
+                           error: error.class.name
+                         })
+    end
+  end
+end