nats_pubsub 1.0.0

data/lib/nats_pubsub/core/message_context.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Core
+    # Unified message context
+    #
+    # Consolidates all message metadata into a single, well-typed context object.
+    #
+    # @!attribute [r] event_id
+    #   @return [String] Unique event identifier (UUID)
+    # @!attribute [r] subject
+    #   @return [String] Full NATS subject
+    # @!attribute [r] topic
+    #   @return [String] Extracted topic from subject
+    # @!attribute [r] trace_id
+    #   @return [String, nil] Optional distributed tracing ID
+    # @!attribute [r] correlation_id
+    #   @return [String, nil] Optional correlation ID for request tracking
+    # @!attribute [r] occurred_at
+    #   @return [Time] Timestamp when the event occurred
+    # @!attribute [r] deliveries
+    #   @return [Integer] Number of delivery attempts
+    # @!attribute [r] stream
+    #   @return [String, nil] JetStream stream name
+    # @!attribute [r] stream_seq
+    #   @return [Integer, nil] JetStream stream sequence number
+    # @!attribute [r] producer
+    #   @return [String, nil] Application that produced the event
+    # @!attribute [r] domain
+    #   @return [String, nil] Legacy: domain field (for backward compatibility)
+    # @!attribute [r] resource
+    #   @return [String, nil] Legacy: resource field (for backward compatibility)
+    # @!attribute [r] action
+    #   @return [String, nil] Legacy: action field (for backward compatibility)
+    #
+    # @example Using in a subscriber
+    #   class EmailSubscriber < NatsPubsub::Subscriber
+    #     subscribe_to 'notifications.email'
+    #
+    #     def handle(message, context)
+    #       puts "Processing event #{context.event_id}"
+    #       puts "Trace ID: #{context.trace_id}"
+    #       puts "Delivery attempt: #{context.deliveries}"
+    #     end
+    #   end
+    #
+    class MessageContext
+      attr_reader :event_id, :subject, :topic, :trace_id, :correlation_id,
+                  :occurred_at, :deliveries, :stream, :stream_seq, :producer,
+                  :domain, :resource, :action
+
+      # Initialize a new message context
+      #
+      # @param event_id [String] Unique event identifier
+      # @param subject [String] Full NATS subject
+      # @param topic [String] Extracted topic
+      # @param trace_id [String, nil] Distributed tracing ID
+      # @param correlation_id [String, nil] Request correlation ID
+      # @param occurred_at [Time] Event timestamp
+      # @param deliveries [Integer] Number of delivery attempts
+      # @param stream [String, nil] JetStream stream name
+      # @param stream_seq [Integer, nil] JetStream stream sequence
+      # @param producer [String, nil] Producer application name
+      # @param domain [String, nil] Legacy domain field
+      # @param resource [String, nil] Legacy resource field
+      # @param action [String, nil] Legacy action field
+      def initialize(
+        event_id:,
+        subject:,
+        topic:,
+        trace_id: nil,
+        correlation_id: nil,
+        occurred_at:,
+        deliveries:,
+        stream: nil,
+        stream_seq: nil,
+        producer: nil,
+        domain: nil,
+        resource: nil,
+        action: nil
+      )
+        @event_id = event_id
+        @subject = subject
+        @topic = topic
+        @trace_id = trace_id
+        @correlation_id = correlation_id
+        @occurred_at = occurred_at
+        @deliveries = deliveries
+        @stream = stream
+        @stream_seq = stream_seq
+        @producer = producer
+        @domain = domain
+        @resource = resource
+        @action = action
+
+        freeze
+      end
+
+      # Create context from legacy metadata hash
+      #
+      # @param metadata [Hash] Legacy metadata hash
+      # @return [MessageContext] New context instance
+      #
+      # @example
+      #   context = MessageContext.from_metadata(metadata)
+      #
+      def self.from_metadata(metadata)
+        # Extract topic from subject
+        subject = metadata[:subject] || metadata['subject']
+        topic = extract_topic_from_subject(subject)
+
+        new(
+          event_id: metadata[:event_id] || metadata['event_id'],
+          subject: subject,
+          topic: topic,
+          trace_id: metadata[:trace_id] || metadata['trace_id'],
+          correlation_id: metadata[:correlation_id] || metadata['correlation_id'],
+          occurred_at: parse_time(metadata[:occurred_at] || metadata['occurred_at']),
+          deliveries: metadata[:deliveries] || metadata['deliveries'] || 1,
+          stream: metadata[:stream] || metadata['stream'],
+          stream_seq: metadata[:stream_seq] || metadata['stream_seq'],
+          producer: metadata[:producer] || metadata['producer'],
+          domain: metadata[:domain] || metadata['domain'],
+          resource: metadata[:resource] || metadata['resource'],
+          action: metadata[:action] || metadata['action']
+        )
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          event_id: event_id,
+          subject: subject,
+          topic: topic,
+          trace_id: trace_id,
+          correlation_id: correlation_id,
+          occurred_at: occurred_at,
+          deliveries: deliveries,
+          stream: stream,
+          stream_seq: stream_seq,
+          producer: producer,
+          domain: domain,
+          resource: resource,
+          action: action
+        }
+      end
+
+      alias to_hash to_h
+
+      private
+
+      # Extract topic from NATS subject
+      #
+      # @param subject [String] Full NATS subject
+      # @return [String] Extracted topic
+      #
+      # @example
+      #   extract_topic_from_subject('production.myapp.notifications.email')
+      #   # => 'notifications.email'
+      #
+      def self.extract_topic_from_subject(subject)
+        return '' if subject.nil? || subject.empty?
+
+        parts = subject.split('.')
+        # Remove env and app_name (first two parts)
+        parts[2..-1]&.join('.') || ''
+      end
+
+      # Parse time from various formats
+      #
+      # @param value [Time, String, Integer, nil] Time value
+      # @return [Time] Parsed time
+      def self.parse_time(value)
+        case value
+        when Time
+          value
+        when String
+          Time.parse(value)
+        when Integer
+          Time.at(value)
+        else
+          Time.now
+        end
+      rescue StandardError
+        Time.now
+      end
+
+      private_class_method :extract_topic_from_subject, :parse_time
+    end
+  end
+end

data/lib/nats_pubsub/core/presets.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Core
+    # Configuration presets for common environments
+    #
+    # Provides pre-configured settings optimized for different deployment scenarios.
+    #
+    # @example Development preset
+    #   NatsPubsub.configure do |config|
+    #     Presets.development(config, app_name: 'my-service')
+    #   end
+    #
+    # @example Production preset
+    #   NatsPubsub.configure do |config|
+    #     Presets.production(
+    #       config,
+    #       app_name: 'my-service',
+    #       nats_urls: ENV.fetch('NATS_CLUSTER_URLS').split(',')
+    #     )
+    #   end
+    #
+    module Presets
+      # Development preset optimized for local development
+      #
+      # Features:
+      # - Lower concurrency for easier debugging
+      # - Shorter timeouts for faster feedback
+      # - DLQ enabled for error visibility
+      # - Debug logging
+      #
+      # @param config [Config] Configuration object
+      # @param options [Hash] Additional options
+      # @option options [String] :app_name Application name (required)
+      # @option options [String, Array<String>] :nats_urls NATS server URLs (default: 'nats://localhost:4222')
+      #
+      # @example
+      #   NatsPubsub.configure do |config|
+      #     Presets.development(config, app_name: 'my-service')
+      #   end
+      #
+      def self.development(config, **options)
+        validate_required_options!(options, :app_name)
+
+        config.app_name = options[:app_name]
+        config.nats_urls = options.fetch(:nats_urls, 'nats://localhost:4222')
+        config.env = options.fetch(:env, 'development')
+
+        # Lower concurrency for easier debugging
+        config.concurrency = 5
+
+        # Faster feedback during development
+        config.max_deliver = 3
+        config.ack_wait = 15_000 # 15 seconds
+        config.backoff = [1_000, 3_000, 5_000] # Shorter backoff
+
+        # DLQ enabled for visibility
+        config.use_dlq = true
+
+        # Inbox/Outbox typically not needed in dev
+        config.use_inbox = false
+        config.use_outbox = false
+
+        config
+      end
+
+      # Production preset optimized for reliability and performance
+      #
+      # Features:
+      # - Higher concurrency for throughput
+      # - Longer timeouts for network latency
+      # - Aggressive retry strategy
+      # - DLQ enabled for operational safety
+      # - Info-level logging
+      #
+      # @param config [Config] Configuration object
+      # @param options [Hash] Additional options
+      # @option options [String] :app_name Application name (required)
+      # @option options [String, Array<String>] :nats_urls NATS server URLs (required)
+      #
+      # @example
+      #   NatsPubsub.configure do |config|
+      #     Presets.production(
+      #       config,
+      #       app_name: 'my-service',
+      #       nats_urls: ENV.fetch('NATS_CLUSTER_URLS').split(',')
+      #     )
+      #   end
+      #
+      def self.production(config, **options)
+        validate_required_options!(options, :app_name, :nats_urls)
+
+        config.app_name = options[:app_name]
+        config.nats_urls = options[:nats_urls]
+        config.env = options.fetch(:env, 'production')
+
+        # Higher concurrency for throughput
+        config.concurrency = 20
+
+        # More aggressive retry strategy
+        config.max_deliver = 5
+        config.ack_wait = 30_000 # 30 seconds
+        config.backoff = [1_000, 5_000, 15_000, 30_000, 60_000] # Exponential backoff
+
+        # DLQ enabled for operational safety
+        config.use_dlq = true
+
+        # Consider enabling for transactional guarantees
+        config.use_inbox = options.fetch(:use_inbox, false)
+        config.use_outbox = options.fetch(:use_outbox, false)
+
+        config
+      end
+
+      # Staging preset balanced between development and production
+      #
+      # Features:
+      # - Moderate concurrency
+      # - Production-like retry strategy
+      # - DLQ enabled
+      # - Debug logging for troubleshooting
+      #
+      # @param config [Config] Configuration object
+      # @param options [Hash] Additional options
+      # @option options [String] :app_name Application name (required)
+      # @option options [String, Array<String>] :nats_urls NATS server URLs (required)
+      #
+      # @example
+      #   NatsPubsub.configure do |config|
+      #     Presets.staging(
+      #       config,
+      #       app_name: 'my-service',
+      #       nats_urls: 'nats://staging-nats:4222'
+      #     )
+      #   end
+      #
+      def self.staging(config, **options)
+        validate_required_options!(options, :app_name, :nats_urls)
+
+        config.app_name = options[:app_name]
+        config.nats_urls = options[:nats_urls]
+        config.env = options.fetch(:env, 'staging')
+
+        # Moderate concurrency
+        config.concurrency = 10
+
+        # Production-like retry strategy
+        config.max_deliver = 5
+        config.ack_wait = 30_000
+        config.backoff = [1_000, 5_000, 15_000, 30_000, 60_000]
+
+        # DLQ enabled
+        config.use_dlq = true
+
+        # Inbox/Outbox optional
+        config.use_inbox = options.fetch(:use_inbox, false)
+        config.use_outbox = options.fetch(:use_outbox, false)
+
+        config
+      end
+
+      # Testing preset optimized for unit and integration tests
+      #
+      # Features:
+      # - Minimal concurrency
+      # - Very short timeouts for fast tests
+      # - No retries for deterministic behavior
+      # - DLQ disabled
+      #
+      # @param config [Config] Configuration object
+      # @param options [Hash] Additional options
+      # @option options [String] :app_name Application name (required)
+      # @option options [String, Array<String>] :nats_urls NATS server URLs (default: 'nats://localhost:4222')
+      #
+      # @example
+      #   NatsPubsub.configure do |config|
+      #     Presets.testing(config, app_name: 'test-service')
+      #   end
+      #
+      def self.testing(config, **options)
+        validate_required_options!(options, :app_name)
+
+        config.app_name = options[:app_name]
+        config.nats_urls = options.fetch(:nats_urls, 'nats://localhost:4222')
+        config.env = options.fetch(:env, 'test')
+
+        # Minimal concurrency
+        config.concurrency = 1
+
+        # No retries for deterministic behavior
+        config.max_deliver = 1
+        config.ack_wait = 5_000 # 5 seconds
+        config.backoff = []
+
+        # DLQ disabled for simpler testing
+        config.use_dlq = false
+
+        # Inbox/Outbox disabled
+        config.use_inbox = false
+        config.use_outbox = false
+
+        config
+      end
+
+      # Validate required options
+      #
+      # @param options [Hash] Options hash
+      # @param required [Array<Symbol>] Required option keys
+      # @raise [ArgumentError] If required options are missing
+      #
+      # @api private
+      def self.validate_required_options!(options, *required)
+        missing = required - options.keys
+        return if missing.empty?
+
+        raise ArgumentError, "Missing required options: #{missing.join(', ')}"
+      end
+
+      private_class_method :validate_required_options!
+    end
+  end
+end

data/lib/nats_pubsub/core/retry_strategy.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'nats/io/client'
+require_relative 'logging'
+
+module NatsPubsub
+  # Handles retry logic with exponential backoff for operations.
+  # Extracted from Publisher to follow Single Responsibility Principle.
+  class RetryStrategy
+    DEFAULT_RETRIES = 3
+
+    # Build list of retriable errors dynamically to handle different NATS versions
+    RETRIABLE_ERRORS = begin
+      errors = [NATS::IO::Timeout, NATS::IO::Error]
+      errors << NATS::IO::NoServersError if defined?(NATS::IO::NoServersError)
+      errors << NATS::IO::StaleConnectionError if defined?(NATS::IO::StaleConnectionError)
+      errors << NATS::IO::SocketTimeoutError if defined?(NATS::IO::SocketTimeoutError)
+      errors.freeze
+    end
+
+    # Execute a block with retry logic
+    #
+    # @param retries [Integer] Number of retry attempts
+    # @param operation_name [String] Name of the operation for logging
+    # @yield Block to execute with retries
+    # @return [Object] Result of the block
+    # @raise [StandardError] If all retries are exhausted
+    def self.execute(retries: DEFAULT_RETRIES, operation_name: 'operation', &block)
+      new(retries: retries, operation_name: operation_name).execute(&block)
+    end
+
+    def initialize(retries: DEFAULT_RETRIES, operation_name: 'operation')
+      @retries = retries
+      @operation_name = operation_name
+    end
+
+    def execute
+      attempt = 0
+      begin
+        yield
+      rescue *RETRIABLE_ERRORS => e
+        attempt += 1
+        if attempt <= @retries
+          backoff_time = calculate_backoff(attempt)
+          Logging.warn(
+            "#{@operation_name} failed (attempt #{attempt}/#{@retries}): #{e.class} #{e.message}. " \
+            "Retrying in #{backoff_time}s...",
+            tag: 'NatsPubsub::RetryStrategy'
+          )
+          sleep backoff_time
+          retry
+        end
+        Logging.error(
+          "#{@operation_name} failed after #{@retries} retries: #{e.class} #{e.message}",
+          tag: 'NatsPubsub::RetryStrategy'
+        )
+        raise
+      end
+    end
+
+    private
+
+    # Calculate exponential backoff time
+    # @param attempt [Integer] Current attempt number
+    # @return [Float] Sleep duration in seconds
+    def calculate_backoff(attempt)
+      # Exponential backoff: 0.1s, 0.2s, 0.4s, 0.8s, etc.
+      [0.1 * (2**(attempt - 1)), 5.0].min # Cap at 5 seconds
+    end
+  end
+end

data/lib/nats_pubsub/core/structured_logger.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module NatsPubsub
+  module Core
+    # Structured logger for machine-parseable JSON logs
+    # Provides consistent logging format with correlation IDs and metadata
+    class StructuredLogger
+      LEVELS = {
+        debug: 0,
+        info: 1,
+        warn: 2,
+        error: 3,
+        fatal: 4
+      }.freeze
+
+      attr_reader :output, :level, :context
+
+      # Initialize a new structured logger
+      #
+      # @param output [IO] Output stream (default: $stdout)
+      # @param level [Symbol] Log level (:debug, :info, :warn, :error, :fatal)
+      # @param context [Hash] Base context included in all log entries
+      def initialize(output: $stdout, level: :info, context: {})
+        @output = output
+        @level = normalize_level(level)
+        @context = context.transform_keys(&:to_s)
+      end
+
+      # Log at debug level
+      def debug(message, metadata = {})
+        log(:debug, message, metadata)
+      end
+
+      # Log at info level
+      def info(message, metadata = {})
+        log(:info, message, metadata)
+      end
+
+      # Log at warn level
+      def warn(message, metadata = {})
+        log(:warn, message, metadata)
+      end
+
+      # Log at error level
+      def error(message, metadata = {})
+        log(:error, message, metadata)
+      end
+
+      # Log at fatal level
+      def fatal(message, metadata = {})
+        log(:fatal, message, metadata)
+      end
+
+      # Create child logger with additional context
+      #
+      # @param child_context [Hash] Additional context
+      # @return [StructuredLogger] New logger with merged context
+      def with_context(child_context)
+        self.class.new(
+          output: output,
+          level: level,
+          context: context.merge(child_context.transform_keys(&:to_s))
+        )
+      end
+
+      private
+
+      # Log a message
+      def log(severity, message, metadata)
+        return if LEVELS[severity] < LEVELS[level]
+
+        log_entry = build_log_entry(severity, message, metadata)
+        output.puts(JSON.generate(log_entry))
+        output.flush
+      rescue StandardError => e
+        # Fallback to plain text if JSON fails
+        output.puts("[#{severity}] #{message} | Error: #{e.message}")
+        output.flush
+      end
+
+      # Build structured log entry
+      def build_log_entry(severity, message, metadata)
+        {
+          timestamp: Time.now.utc.iso8601(3),
+          level: severity.to_s.upcase,
+          message: message,
+          pid: Process.pid,
+          thread_id: Thread.current.object_id
+        }.merge(context)
+         .merge(normalize_metadata(metadata))
+      end
+
+      # Normalize metadata keys to strings
+      def normalize_metadata(metadata)
+        return {} unless metadata.is_a?(Hash)
+
+        metadata.transform_keys(&:to_s)
+      end
+
+      # Normalize log level
+      def normalize_level(lvl)
+        lvl = lvl.to_sym if lvl.is_a?(String)
+        return lvl if LEVELS.key?(lvl)
+
+        :info
+      end
+    end
+
+    # Logger factory for creating structured loggers
+    module LoggerFactory
+      # Create a structured logger from configuration
+      #
+      # @param config [Config] Application configuration
+      # @return [StructuredLogger] Configured logger
+      def self.create_from_config(config)
+        level = config.logger&.level || :info
+
+        StructuredLogger.new(
+          output: $stdout,
+          level: level,
+          context: {
+            app_name: config.app_name,
+            env: config.env
+          }
+        )
+      end
+
+      # Create a logger for a specific component
+      #
+      # @param component [String] Component name
+      # @param config [Config] Application configuration
+      # @return [StructuredLogger] Logger with component context
+      def self.for_component(component, config)
+        create_from_config(config).with_context(component: component)
+      end
+    end
+  end
+end