nats_pubsub 1.0.0

data/lib/nats_pubsub/subscribers/error_context.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Subscribers
+    # Immutable value object representing error context for unified error handling.
+    # Provides a consistent interface for capturing and logging error information
+    # throughout the message processing pipeline.
+    #
+    # This class follows the Value Object pattern and encapsulates all error-related
+    # metadata, making error handling more consistent and reducing duplication.
+    #
+    # @example Creating error context from an exception
+    #   begin
+    #     process_message(msg)
+    #   rescue StandardError => e
+    #     error_ctx = ErrorContext.from_exception(e, reason: 'processing_failed')
+    #     puts error_ctx.to_log_string
+    #   end
+    #
+    # @attr_reader error_class [String] Name of the error class
+    # @attr_reader error_message [String] Error message
+    # @attr_reader reason [String] High-level reason for the error (e.g., 'malformed_json', 'max_deliver_exceeded')
+    # @attr_reader backtrace [Array<String>, nil] Optional error backtrace
+    class ErrorContext
+      attr_reader :error_class, :error_message, :reason, :backtrace
+
+      # Initialize a new ErrorContext
+      #
+      # @param error_class [String] Name of the error class
+      # @param error_message [String] Error message
+      # @param reason [String] High-level reason for the error
+      # @param backtrace [Array<String>, nil] Optional error backtrace
+      def initialize(error_class:, error_message:, reason:, backtrace: nil)
+        @error_class = error_class.to_s
+        @error_message = error_message.to_s
+        @reason = reason.to_s
+        @backtrace = backtrace
+        freeze # Make immutable
+      end
+
+      # Build ErrorContext from an exception
+      #
+      # Extracts error information from a Ruby exception object and creates
+      # a structured error context with optional reason and backtrace.
+      #
+      # @param exception [Exception] Ruby exception object
+      # @param reason [String] High-level reason for the error
+      # @param include_backtrace [Boolean] Whether to include the backtrace (default: false)
+      # @return [ErrorContext] Immutable error context
+      def self.from_exception(exception, reason:, include_backtrace: false)
+        new(
+          error_class: exception.class.name,
+          error_message: exception.message,
+          reason: reason,
+          backtrace: include_backtrace ? exception.backtrace : nil
+        )
+      end
+
+      # Build ErrorContext from keyword arguments
+      #
+      # Convenience constructor for cases where you have structured error data
+      # but not an exception object.
+      #
+      # @param error_class [String] Name of the error class
+      # @param error_message [String] Error message
+      # @param reason [String] High-level reason for the error
+      # @return [ErrorContext] Immutable error context
+      def self.build(error_class:, error_message:, reason:)
+        new(
+          error_class: error_class,
+          error_message: error_message,
+          reason: reason
+        )
+      end
+
+      # Format error for logging
+      #
+      # Creates a concise string representation suitable for log messages,
+      # following the pattern: "ErrorClass: message"
+      #
+      # @return [String] Formatted error string
+      def to_log_string
+        "#{error_class}: #{error_message}"
+      end
+
+      # Hash representation for DLQ publishing
+      #
+      # Returns error information as a hash suitable for inclusion
+      # in DLQ message envelopes.
+      #
+      # @return [Hash] Error context as hash
+      def to_dlq_hash
+        {
+          error_class: error_class,
+          error_message: error_message,
+          reason: reason
+        }
+      end
+
+      # Complete hash representation
+      #
+      # @return [Hash] Full context including optional backtrace
+      def to_h
+        hash = {
+          error_class: error_class,
+          error_message: error_message,
+          reason: reason
+        }
+        hash[:backtrace] = backtrace if backtrace
+        hash
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] Human-readable error context
+      def to_s
+        "ErrorContext(reason=#{reason}, error=#{error_class}: #{error_message})"
+      end
+
+      # Check if error is of a specific type
+      #
+      # @param error_classes [Array<Class>] Error classes to check against
+      # @return [Boolean] True if error matches any of the classes
+      def is_a?(*error_classes)
+        error_classes.any? { |klass| error_class == klass.name }
+      end
+
+      # Check if error matches a specific reason
+      #
+      # @param target_reason [String, Symbol] Reason to check
+      # @return [Boolean] True if reason matches
+      def reason?(target_reason)
+        reason == target_reason.to_s
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/error_handler.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../core/error_action'
+require_relative '../core/constants'
+
+module NatsPubsub
+  module Subscribers
+    # Enhanced error handler with ErrorAction support
+    # Integrates per-subscriber error handling strategies
+    class ErrorHandler
+      attr_reader :subscriber, :config
+
+      def initialize(subscriber, config: NatsPubsub.config)
+        @subscriber = subscriber
+        @config = config
+      end
+
+      # Handle an error from message processing
+      #
+      # @param error [Exception] The error that occurred
+      # @param message [Hash] The message payload
+      # @param context [MessageContext] Message metadata
+      # @param attempt_number [Integer] Current delivery attempt
+      # @return [Symbol] Error action to take (:retry, :discard, :dlq)
+      def handle_error(error, message, context, attempt_number)
+        error_context = build_error_context(error, message, context, attempt_number)
+
+        # Try subscriber's custom error handler first
+        action = if subscriber.respond_to?(:on_error)
+                   call_subscriber_error_handler(error_context)
+                 else
+                   determine_default_action(error_context)
+                 end
+
+        # Validate and normalize action
+        normalize_action(action, error_context)
+      end
+
+      private
+
+      # Build error context object
+      def build_error_context(error, message, context, attempt_number)
+        Core::ErrorContext.new(
+          error: error,
+          message: message,
+          context: context,
+          attempt_number: attempt_number,
+          max_attempts: config.max_deliver
+        )
+      end
+
+      # Call subscriber's custom error handler
+      def call_subscriber_error_handler(error_context)
+        subscriber.on_error(error_context)
+      rescue StandardError => e
+        # If custom handler fails, log and use default
+        config.logger&.error(
+          "Subscriber error handler failed: #{e.class} - #{e.message}",
+          subscriber: subscriber.class.name,
+          error: e.class.name
+        )
+        determine_default_action(error_context)
+      end
+
+      # Determine default error action based on error type
+      def determine_default_action(error_context)
+        error = error_context.error
+
+        # Malformed messages -> Discard immediately
+        return Core::ErrorAction::DISCARD if malformed_error?(error)
+
+        # Unrecoverable errors -> DLQ immediately
+        return Core::ErrorAction::DLQ if unrecoverable_error?(error)
+
+        # Last attempt -> DLQ
+        return Core::ErrorAction::DLQ if error_context.last_attempt?
+
+        # Default -> Retry with backoff
+        Core::ErrorAction::RETRY
+      end
+
+      # Check if error indicates malformed message
+      def malformed_error?(error)
+        Constants::Errors::MALFORMED_ERRORS.any? do |error_name|
+          error.class.name.include?(error_name)
+        end
+      end
+
+      # Check if error is unrecoverable
+      def unrecoverable_error?(error)
+        Constants::Errors::UNRECOVERABLE_ERRORS.any? do |error_name|
+          error.class.name.include?(error_name)
+        end
+      end
+
+      # Normalize action to valid ErrorAction constant
+      def normalize_action(action, error_context)
+        return action if Core::ErrorAction.valid?(action)
+
+        config.logger&.warn(
+          "Invalid error action returned: #{action.inspect}, using default",
+          subscriber: subscriber.class.name,
+          valid_actions: Core::ErrorAction::ALL
+        )
+
+        determine_default_action(error_context)
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/graceful_shutdown.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Subscribers
+    # Graceful shutdown manager for subscribers
+    # Handles signal trapping and ensures clean shutdown with message drain
+    class GracefulShutdown
+      DEFAULT_TIMEOUT = 30 # seconds
+
+      attr_reader :worker, :timeout, :logger
+
+      # Initialize graceful shutdown manager
+      #
+      # @param worker [Worker] Worker instance to manage
+      # @param timeout [Integer] Shutdown timeout in seconds
+      # @param logger [Logger] Logger instance
+      def initialize(worker, timeout: DEFAULT_TIMEOUT, logger: nil)
+        @worker = worker
+        @timeout = timeout
+        @logger = logger || NatsPubsub.config.logger
+        @shutting_down = false
+        @shutdown_started_at = nil
+      end
+
+      # Start graceful shutdown process
+      #
+      # @return [Boolean] True if shutdown completed gracefully within timeout
+      def shutdown
+        return false if @shutting_down
+
+        @shutting_down = true
+        @shutdown_started_at = Time.now
+
+        logger&.info('Starting graceful shutdown', timeout: timeout)
+
+        # Stop accepting new messages
+        stop_accepting_messages
+
+        # Wait for in-flight messages
+        completed = wait_for_completion
+
+        # Force terminate if needed
+        force_terminate unless completed
+
+        # Close connections
+        close_connections
+
+        elapsed = (Time.now - @shutdown_started_at).round(1)
+        logger&.info('Graceful shutdown complete', elapsed: elapsed, graceful: completed)
+
+        completed
+      end
+
+      # Check if shutdown is in progress
+      #
+      # @return [Boolean] True if shutdown is in progress
+      def shutting_down?
+        @shutting_down
+      end
+
+      # Install signal handlers for graceful shutdown
+      # Traps SIGTERM and SIGINT
+      def install_signal_handlers
+        %w[TERM INT].each do |signal|
+          Signal.trap(signal) do
+            logger&.info("Received SIG#{signal}, initiating shutdown")
+
+            begin
+              shutdown
+              exit(0)
+            rescue StandardError => e
+              logger&.error('Shutdown failed', error: e.message)
+              exit(1)
+            end
+          end
+        end
+      end
+
+      private
+
+      # Stop accepting new messages
+      def stop_accepting_messages
+        logger&.info('Stopping message acceptance')
+        worker.pause! if worker.respond_to?(:pause!)
+      end
+
+      # Wait for in-flight messages to complete
+      #
+      # @return [Boolean] True if all messages completed within timeout
+      def wait_for_completion
+        deadline = Time.now + timeout
+
+        loop do
+          in_flight = worker.in_flight_count
+
+          if in_flight.zero?
+            logger&.info('All messages processed')
+            return true
+          end
+
+          if Time.now >= deadline
+            logger&.warn('Shutdown timeout reached',
+                         in_flight: in_flight,
+                         timeout: timeout)
+            return false
+          end
+
+          logger&.debug('Waiting for messages',
+                        in_flight: in_flight,
+                        remaining: (deadline - Time.now).round(1))
+          sleep 0.5
+        end
+      end
+
+      # Force terminate remaining messages
+      def force_terminate
+        logger&.warn('Force terminating remaining messages')
+        worker.force_stop! if worker.respond_to?(:force_stop!)
+      end
+
+      # Close connections
+      def close_connections
+        logger&.info('Closing connections')
+        worker.close if worker.respond_to?(:close)
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/inbox/inbox_message.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'oj'
+
+module NatsPubsub
+  module Subscribers
+    # Immutable value object for a single NATS message.
+    class InboxMessage
+      attr_reader :msg, :seq, :deliveries, :stream, :subject, :headers, :body, :raw, :event_id, :now
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def self.from_nats(msg)
+        meta       = (msg.respond_to?(:metadata) && msg.metadata) || nil
+        seq        = meta.respond_to?(:stream_sequence) ? meta.stream_sequence : nil
+        deliveries = meta.respond_to?(:num_delivered)   ? meta.num_delivered   : nil
+        stream     = meta.respond_to?(:stream)          ? meta.stream          : nil
+        consumer   = meta.respond_to?(:consumer)        ? meta.consumer        : nil
+        subject    = msg.subject.to_s
+
+        headers = {}
+        (msg.header || {}).each { |k, v| headers[k.to_s.downcase] = v }
+
+        raw  = msg.data
+        body = begin
+          Oj.load(raw, mode: :strict)
+        rescue Oj::Error
+          {}
+        end
+
+        id = (headers['nats-msg-id'] || body['event_id']).to_s.strip
+        id = "seq:#{seq}" if id.empty?
+
+        new(msg, seq, deliveries, stream, subject, headers, body, raw, id, Time.now.utc, consumer)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(msg, seq, deliveries, stream, subject, headers, body, raw, event_id, now, consumer = nil)
+        @msg        = msg
+        @seq        = seq
+        @deliveries = deliveries
+        @stream     = stream
+        @subject    = subject
+        @headers    = headers
+        @body       = body
+        @raw        = raw
+        @event_id   = event_id
+        @now        = now
+        @consumer   = consumer
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def body_for_store
+        body.empty? ? raw : body
+      end
+
+      def data
+        raw
+      end
+
+      def header
+        headers
+      end
+
+      def metadata
+        @metadata ||= Struct.new(:num_delivered, :sequence, :consumer, :stream)
+                            .new(deliveries, seq, @consumer, stream)
+      end
+
+      def ack(*, **)
+        msg.ack(*, **) if msg.respond_to?(:ack)
+      end
+
+      def nak(*, **)
+        msg.nak(*, **) if msg.respond_to?(:nak)
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/inbox/inbox_processor.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../../core/logging'
+require_relative '../../models/model_utils'
+require_relative 'inbox_message'
+require_relative 'inbox_repository'
+
+module NatsPubsub
+  module Subscribers
+    # Orchestrates AR-backed inbox processing.
+    class InboxProcessor
+      def initialize(message_processor)
+        @processor = message_processor
+      end
+
+      # @return [true,false] processed?
+      def process(msg)
+        klass = ModelUtils.constantize(NatsPubsub.config.inbox_model)
+        return process_direct?(msg, klass) unless ModelUtils.ar_class?(klass)
+
+        msg   = InboxMessage.from_nats(msg)
+        repo  = InboxRepository.new(klass)
+        record = repo.find_or_build(msg)
+
+        if repo.already_processed?(record)
+          msg.ack
+          return true
+        end
+
+        repo.persist_pre(record, msg)
+        @processor.handle_message(msg)
+        repo.persist_post(record)
+        true
+      rescue StandardError => e
+        repo.persist_failure(record, e) if defined?(repo) && defined?(record)
+        Logging.error("Inbox processing failed: #{e.class}: #{e.message}",
+                      tag: 'NatsPubsub::Subscribers::InboxProcessor')
+        false
+      end
+
+      private
+
+      def process_direct?(msg, klass)
+        unless ModelUtils.ar_class?(klass)
+          Logging.warn("Inbox model #{klass} is not an ActiveRecord model; processing directly.",
+                       tag: 'NatsPubsub::Subscribers::InboxProcessor')
+        end
+        @processor.handle_message(msg)
+        true
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/inbox/inbox_repository.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../../models/model_utils'
+require_relative '../../core/logging'
+
+module NatsPubsub
+  module Subscribers
+    # AR-facing operations for inbox rows (find/build/persist).
+    class InboxRepository
+      def initialize(klass)
+        @klass = klass
+      end
+
+      def find_or_build(msg)
+        if ModelUtils.has_columns?(@klass, :event_id)
+          @klass.find_or_initialize_by(event_id: msg.event_id)
+        elsif ModelUtils.has_columns?(@klass, :stream_seq)
+          @klass.find_or_initialize_by(stream_seq: msg.seq)
+        else
+          @klass.new
+        end
+      end
+
+      def already_processed?(record)
+        record.respond_to?(:processed_at) && record.processed_at
+      end
+
+      def persist_pre(record, msg)
+        attrs = {
+          event_id: msg.event_id,
+          subject: msg.subject,
+          payload: ModelUtils.json_dump(msg.body_for_store),
+          headers: ModelUtils.json_dump(msg.headers),
+          stream: msg.stream,
+          stream_seq: msg.seq,
+          deliveries: msg.deliveries,
+          status: 'processing',
+          last_error: nil,
+          received_at: record.respond_to?(:received_at) ? (record.received_at || msg.now) : nil,
+          updated_at: record.respond_to?(:updated_at) ? msg.now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
+
+      def persist_post(record)
+        now = Time.now.utc
+        attrs = {
+          status: 'processed',
+          processed_at: record.respond_to?(:processed_at) ? now : nil,
+          updated_at: record.respond_to?(:updated_at) ? now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
+
+      def persist_failure(record, error)
+        return unless record
+
+        now = Time.now.utc
+        attrs = {
+          status: 'failed',
+          last_error: "#{error.class}: #{error.message}",
+          updated_at: record.respond_to?(:updated_at) ? now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      rescue StandardError => e
+        Logging.warn("Failed to persist inbox failure: #{e.class}: #{e.message}",
+                     tag: 'NatsPubsub::Subscribers::InboxRepository')
+      end
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/message_context.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module NatsPubsub
+  module Subscribers
+    # Immutable value object representing per-message metadata.
+    # Extracted from MessageProcessor to follow Single Responsibility Principle.
+    #
+    # This class encapsulates all metadata associated with a NATS JetStream message,
+    # providing a clean interface for accessing message context throughout the
+    # processing pipeline.
+    #
+    # @example Building context from a NATS message
+    #   context = MessageContext.build(nats_msg)
+    #   puts "Event ID: #{context.event_id}"
+    #   puts "Deliveries: #{context.deliveries}"
+    #
+    # @attr_reader event_id [String] Unique event identifier from message header or generated UUID
+    # @attr_reader deliveries [Integer] Number of times this message has been delivered
+    # @attr_reader subject [String] NATS subject the message was published to
+    # @attr_reader seq [Integer, nil] JetStream sequence number
+    # @attr_reader consumer [String, nil] JetStream consumer name
+    # @attr_reader stream [String, nil] JetStream stream name
+    class MessageContext
+      attr_reader :event_id, :deliveries, :subject, :seq, :consumer, :stream
+
+      # Initialize a new MessageContext
+      #
+      # @param event_id [String] Unique event identifier
+      # @param deliveries [Integer] Number of delivery attempts
+      # @param subject [String] NATS subject
+      # @param seq [Integer, nil] JetStream sequence number
+      # @param consumer [String, nil] JetStream consumer name
+      # @param stream [String, nil] JetStream stream name
+      def initialize(event_id:, deliveries:, subject:, seq: nil, consumer: nil, stream: nil)
+        @event_id = event_id
+        @deliveries = deliveries
+        @subject = subject
+        @seq = seq
+        @consumer = consumer
+        @stream = stream
+        freeze # Make immutable
+      end
+
+      # Build MessageContext from a NATS JetStream message
+      #
+      # Extracts metadata from the NATS message headers and metadata,
+      # falling back to sensible defaults when information is unavailable.
+      #
+      # @param msg [NATS::Msg] NATS JetStream message object
+      # @return [MessageContext] Immutable message context
+      def self.build(msg)
+        new(
+          event_id: msg.header&.[]('nats-msg-id') || SecureRandom.uuid,
+          deliveries: msg.metadata&.num_delivered.to_i,
+          subject: msg.subject,
+          seq: msg.metadata&.sequence,
+          consumer: msg.metadata&.consumer,
+          stream: msg.metadata&.stream
+        )
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] Human-readable context information
+      def to_s
+        "MessageContext(event_id=#{event_id}, subject=#{subject}, seq=#{seq}, deliveries=#{deliveries})"
+      end
+
+      # Hash representation for logging
+      #
+      # @return [Hash] Context as hash
+      def to_h
+        {
+          event_id: event_id,
+          deliveries: deliveries,
+          subject: subject,
+          seq: seq,
+          consumer: consumer,
+          stream: stream
+        }
+      end
+    end
+  end
+end