nats_pubsub 1.0.0

data/lib/nats_pubsub/core/connection.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'nats/io/client'
+require 'singleton'
+require 'oj'
+require_relative 'duration'
+require_relative 'logging'
+require_relative 'config'
+require_relative '../topology/topology'
+
+module NatsPubsub
+  # Singleton connection to NATS.
+  class Connection
+    include Singleton
+
+    DEFAULT_CONN_OPTS = {
+      reconnect: true,
+      reconnect_time_wait: 2,
+      max_reconnect_attempts: 10,
+      connect_timeout: 5
+    }.freeze
+
+    class << self
+      # Thread-safe delegator to the singleton instance.
+      # Returns a live JetStream context.
+      def connect!
+        @__mutex ||= Mutex.new
+        @__mutex.synchronize { instance.connect! }
+      end
+
+      # Optional accessors if callers need raw handles
+      def nc
+        instance.__send__(:nc)
+      end
+
+      def jetstream
+        instance.__send__(:jetstream)
+      end
+    end
+
+    # Idempotent: returns an existing, healthy JetStream context or establishes one.
+    # NOTE: This method only establishes the connection. Topology setup is separate.
+    # Call NatsPubsub.ensure_topology! explicitly after connection if needed.
+    def connect!
+      return @jts if connected?
+
+      servers = nats_servers
+      raise ConfigurationError, 'No NATS URLs configured' if servers.empty?
+
+      establish_connection(servers)
+
+      Logging.info(
+        "Connected to NATS (#{servers.size} server#{'s' unless servers.size == 1}): " \
+        "#{sanitize_urls(servers).join(', ')}",
+        tag: 'NatsPubsub::Connection'
+      )
+
+      @jts
+    end
+
+    private
+
+    def connected?
+      @nc&.connected?
+    end
+
+    def nats_servers
+      NatsPubsub.config.nats_urls
+                .to_s
+                .split(',')
+                .map(&:strip)
+                .reject(&:empty?)
+    end
+
+    def establish_connection(servers)
+      @nc = NATS::IO::Client.new
+      @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS))
+
+      # Create JetStream context
+      @jts = @nc.jetstream
+
+      # --- Compatibility shim: ensure JetStream responds to #nc for older/newer clients ---
+      return if @jts.respond_to?(:nc)
+
+      nc_ref = @nc
+      @jts.define_singleton_method(:nc) { nc_ref }
+    end
+
+    # Expose for class-level helpers (not part of public API)
+    attr_reader :nc
+
+    def jetstream
+      @jts
+    end
+
+    # Mask credentials in NATS URLs:
+    # - "nats://user:pass@host:4222" -> "nats://user:***@host:4222"
+    # - "nats://token@host:4222"     -> "nats://***@host:4222"
+    def sanitize_urls(urls)
+      urls.map { |u| Logging.sanitize_url(u) }
+    end
+  end
+end

data/lib/nats_pubsub/core/constants.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # Centralized constants for the library
+  # Extracts magic numbers and strings into named, documented constants
+  module Constants
+    # Timeout-related constants
+    module Timeouts
+      # Default acknowledgment wait time in milliseconds
+      # Time before a message is considered unacknowledged and redelivered
+      ACK_WAIT_DEFAULT = 30_000 # 30 seconds
+
+      # Default idle wait time in milliseconds
+      # Time to wait when no messages are available before polling again
+      IDLE_WAIT_DEFAULT = 100 # 100ms
+
+      # Default connection timeout in seconds
+      CONNECTION_TIMEOUT = 5
+
+      # Default request timeout for management operations
+      MANAGEMENT_TIMEOUT = 10
+    end
+
+    # Retry strategy constants
+    module Retry
+      # Default exponential backoff delays in milliseconds
+      # Used for retrying failed message processing
+      DEFAULT_BACKOFF = [1_000, 5_000, 15_000, 30_000, 60_000].freeze
+
+      # Maximum number of delivery attempts before sending to DLQ
+      MAX_ATTEMPTS = 5
+
+      # Base delay for transient errors (milliseconds)
+      TRANSIENT_BASE_DELAY = 500
+
+      # Base delay for persistent errors (milliseconds)
+      PERSISTENT_BASE_DELAY = 2_000
+
+      # Maximum backoff delay cap (milliseconds)
+      MAX_BACKOFF_CAP = 60_000 # 60 seconds
+    end
+
+    # Dead Letter Queue constants
+    module DLQ
+      # Default retention period for DLQ messages (30 days in nanoseconds)
+      RETENTION_PERIOD = 30 * 24 * 60 * 60 * 1_000_000_000
+
+      # DLQ stream suffix
+      STREAM_SUFFIX = '-dlq'
+
+      # Maximum attempts before moving to DLQ
+      MAX_ATTEMPTS = 3
+    end
+
+    # Stream and consumer configuration constants
+    module Stream
+      # Default stream retention policy
+      RETENTION_POLICY = 'limits' # limits, interest, workqueue
+
+      # Default storage type
+      STORAGE_TYPE = 'file' # file or memory
+
+      # Default max message age (7 days in nanoseconds)
+      MAX_AGE = 7 * 24 * 60 * 60 * 1_000_000_000
+
+      # Default max messages per stream
+      MAX_MESSAGES = 1_000_000
+
+      # Default max bytes per stream (1GB)
+      MAX_BYTES = 1_073_741_824
+    end
+
+    # Consumer configuration constants
+    module Consumer
+      # Default concurrency level
+      DEFAULT_CONCURRENCY = 5
+
+      # Minimum concurrency
+      MIN_CONCURRENCY = 1
+
+      # Maximum concurrency (prevents resource exhaustion)
+      MAX_CONCURRENCY = 1000
+
+      # Default batch size for pull consumers
+      BATCH_SIZE = 10
+
+      # Maximum batch size
+      MAX_BATCH_SIZE = 256
+    end
+
+    # Subject pattern constants
+    module Subject
+      # Wildcard for matching one level
+      SINGLE_LEVEL_WILDCARD = '*'
+
+      # Wildcard for matching multiple levels
+      MULTI_LEVEL_WILDCARD = '>'
+
+      # Subject token separator
+      SEPARATOR = '.'
+
+      # Maximum subject length
+      MAX_LENGTH = 255
+    end
+
+    # Envelope schema constants
+    module Envelope
+      # Current schema version
+      SCHEMA_VERSION = 1
+
+      # Required envelope fields
+      REQUIRED_FIELDS = %w[
+        event_id
+        schema_version
+        producer
+        occurred_at
+      ].freeze
+
+      # Topic envelope required fields
+      TOPIC_REQUIRED_FIELDS = (REQUIRED_FIELDS + %w[topic message]).freeze
+
+      # Event envelope required fields (legacy)
+      EVENT_REQUIRED_FIELDS = (REQUIRED_FIELDS + %w[domain resource action payload]).freeze
+    end
+
+    # Error classification constants
+    module Errors
+      # Errors that should not be retried
+      UNRECOVERABLE_ERRORS = [
+        'ArgumentError',
+        'TypeError',
+        'NoMethodError',
+        'NameError',
+        'SyntaxError'
+      ].freeze
+
+      # Errors indicating malformed messages
+      MALFORMED_ERRORS = [
+        'JSON::ParserError',
+        'Oj::ParseError',
+        'EncodingError'
+      ].freeze
+
+      # Transient errors that should be retried
+      TRANSIENT_ERRORS = [
+        'Timeout::Error',
+        'IOError',
+        'Errno::ECONNREFUSED',
+        'Errno::ETIMEDOUT',
+        'NATS::IO::Timeout',
+        'NATS::IO::Error'
+      ].freeze
+    end
+
+    # Logging constants
+    module Logging
+      # Default log level
+      DEFAULT_LEVEL = :info
+
+      # Log levels
+      LEVELS = %i[debug info warn error fatal].freeze
+
+      # Structured log field names
+      FIELDS = {
+        event_id: 'event_id',
+        trace_id: 'trace_id',
+        subject: 'subject',
+        topic: 'topic',
+        delivery_count: 'delivery_count',
+        elapsed_ms: 'elapsed_ms',
+        error_class: 'error_class',
+        error_message: 'error_message'
+      }.freeze
+    end
+
+    # Health check constants
+    module HealthCheck
+      # Quick check timeout (seconds)
+      QUICK_TIMEOUT = 5
+
+      # Full check timeout (seconds)
+      FULL_TIMEOUT = 30
+
+      # Health check statuses
+      HEALTHY = 'healthy'
+      DEGRADED = 'degraded'
+      UNHEALTHY = 'unhealthy'
+    end
+  end
+end

data/lib/nats_pubsub/core/duration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# NatsPubsub
+#
+module NatsPubsub
+  # Utility for parsing human-friendly durations into milliseconds.
+  #
+  # Defaults to an :auto heuristic for Integer/Float values to preserve
+  # backward compatibility:
+  #   - Integers < 1000 are treated as seconds (e.g., 30 -> 30_000ms)
+  #   - Integers >= 1000 are treated as milliseconds (e.g., 1500 -> 1500ms)
+  # Prefer setting `default_unit:` to :s or :ms for unambiguous behavior.
+  #
+  # Examples:
+  #   Duration.to_millis(30)                        #=> 30000   (auto)
+  #   Duration.to_millis(1500)                      #=> 1500    (auto)
+  #   Duration.to_millis("1500")                    #=> 1500    (auto)
+  #   Duration.to_millis(1500, default_unit: :s)    #=> 1_500_000
+  #   Duration.to_millis("30s")                     #=> 30000
+  #   Duration.to_millis("500ms")                   #=> 500
+  #   Duration.to_millis("250us")                   #=> 0
+  #   Duration.to_millis("1h")                      #=> 3_600_000
+  #   Duration.to_millis(1_500_000_000, default_unit: :ns) #=> 1500
+  #
+  # Also:
+  #   Duration.normalize_list_to_millis(%w[1s 5s 15s]) #=> [1000, 5000, 15000]
+  module Duration
+    # multipliers to convert 1 unit into milliseconds
+    MULTIPLIER_MS = {
+      'ns' => 1.0e-6,     # nanoseconds to ms
+      'us' => 1.0e-3,     # microseconds to ms
+      'µs' => 1.0e-3,     # alt microseconds symbol
+      'ms' => 1,          # milliseconds to ms
+      's' => 1_000,       # seconds to ms
+      'm' => 60_000,      # minutes to ms
+      'h' => 3_600_000,   # hours to ms
+      'd' => 86_400_000   # days to ms
+    }.freeze
+
+    NUMBER_RE = /\A\d[\d_]*\z/
+    TOKEN_RE  = /\A(\d[\d_]*(?:\.\d+)?)\s*(ns|us|µs|ms|s|m|h|d)\z/i
+
+    module_function
+
+    # default_unit:
+    #   :auto (heuristic: int<1000 -> seconds, >=1000 -> ms)
+    #   :ns, :us, :ms, :s, :m, :h, :d (explicit)
+    def to_millis(val, default_unit: :auto)
+      case val
+      when Integer then int_to_ms(val, default_unit: default_unit)
+      when Float   then float_to_ms(val, default_unit: default_unit)
+      when String  then string_to_ms(val, default_unit: default_unit)
+      else
+        raise ArgumentError, "invalid duration type: #{val.class}" unless val.respond_to?(:to_f)
+
+        float_to_ms(val.to_f, default_unit: default_unit)
+
+      end
+    end
+
+    # Normalize an array of durations into integer milliseconds.
+    def normalize_list_to_millis(values, default_unit: :auto)
+      vals = Array(values)
+      return [] if vals.empty?
+
+      vals.map { |v| to_millis(v, default_unit: default_unit) }
+    end
+
+    # --- internal helpers ---
+
+    def int_to_ms(num, default_unit:)
+      case default_unit
+      when :auto
+        # Preserve existing heuristic for compatibility
+        num >= 1_000 ? num : num * 1_000
+      else
+        coerce_numeric_to_ms(num.to_f, default_unit)
+      end
+    end
+
+    def float_to_ms(flt, default_unit:)
+      coerce_numeric_to_ms(flt, default_unit)
+    end
+
+    def string_to_ms(str, default_unit:)
+      s = str.strip
+      # Plain number strings are treated like integers so the :auto
+      # heuristic still applies (<1000 => seconds, >=1000 => ms).
+      return int_to_ms(s.delete('_').to_i, default_unit: default_unit) if NUMBER_RE.match?(s)
+
+      m = TOKEN_RE.match(s)
+      raise ArgumentError, "invalid duration: #{str.inspect}" unless m
+
+      num   = m[1].delete('_').to_f
+      unit  = m[2].downcase
+      (num * MULTIPLIER_MS.fetch(unit)).round
+    end
+
+    def coerce_numeric_to_ms(num, unit)
+      case unit
+      when :auto
+        # For floats, :auto treats as seconds (common developer intent)
+        (num * 1_000).round
+      else
+        u = unit.to_s
+        mult = MULTIPLIER_MS[u]
+        raise ArgumentError, "invalid unit for default_unit: #{unit.inspect}" unless mult
+
+        (num * mult).round
+      end
+    end
+  end
+end

data/lib/nats_pubsub/core/error_action.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Core
+    # Error action constants for fine-grained error handling control
+    #
+    # @example Using in a subscriber
+    #   class PaymentSubscriber < NatsPubsub::Subscriber
+    #     subscribe_to 'payment.process'
+    #
+    #     def handle(message, context)
+    #       process_payment(message)
+    #     end
+    #
+    #     def on_error(error, message, context)
+    #       case error
+    #       when ValidationError
+    #         ErrorAction::DISCARD
+    #       when NetworkError, Timeout::Error
+    #         ErrorAction::RETRY
+    #       else
+    #         ErrorAction::DLQ
+    #       end
+    #     end
+    #   end
+    #
+    module ErrorAction
+      # Retry the message with backoff strategy
+      RETRY = :retry
+
+      # Acknowledge and discard the message (no retry)
+      DISCARD = :discard
+
+      # Send message to dead letter queue
+      DLQ = :dlq
+
+      # All valid actions
+      ALL = [RETRY, DISCARD, DLQ].freeze
+
+      # Check if action is valid
+      #
+      # @param action [Symbol] Action to validate
+      # @return [Boolean] True if valid
+      def self.valid?(action)
+        ALL.include?(action)
+      end
+
+      # Get default action
+      #
+      # @return [Symbol] Default action (:retry)
+      def self.default
+        RETRY
+      end
+    end
+
+    # Error context passed to error handlers
+    #
+    # @!attribute [r] error
+    #   @return [Exception] The error that occurred
+    # @!attribute [r] message
+    #   @return [Hash] The message that failed
+    # @!attribute [r] context
+    #   @return [MessageContext] Message context
+    # @!attribute [r] attempt_number
+    #   @return [Integer] Current attempt number (1-based)
+    # @!attribute [r] max_attempts
+    #   @return [Integer] Maximum delivery attempts configured
+    #
+    class ErrorContext
+      attr_reader :error, :message, :context, :attempt_number, :max_attempts
+
+      # Initialize a new error context
+      #
+      # @param error [Exception] The error
+      # @param message [Hash] The message
+      # @param context [MessageContext] Message context
+      # @param attempt_number [Integer] Attempt number
+      # @param max_attempts [Integer] Max attempts
+      def initialize(error:, message:, context:, attempt_number:, max_attempts:)
+        @error = error
+        @message = message
+        @context = context
+        @attempt_number = attempt_number
+        @max_attempts = max_attempts
+
+        freeze
+      end
+
+      # Check if this is the last attempt
+      #
+      # @return [Boolean] True if last attempt
+      def last_attempt?
+        attempt_number >= max_attempts
+      end
+
+      # Check if retries are exhausted
+      #
+      # @return [Boolean] True if exhausted
+      def retries_exhausted?
+        last_attempt?
+      end
+
+      # Get remaining attempts
+      #
+      # @return [Integer] Number of remaining attempts
+      def remaining_attempts
+        [max_attempts - attempt_number, 0].max
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          error: error.class.name,
+          error_message: error.message,
+          message: message,
+          context: context.to_h,
+          attempt_number: attempt_number,
+          max_attempts: max_attempts,
+          last_attempt: last_attempt?,
+          remaining_attempts: remaining_attempts
+        }
+      end
+
+      alias to_hash to_h
+    end
+
+    # Retry strategy configuration
+    #
+    # @!attribute [r] max_attempts
+    #   @return [Integer] Maximum number of retry attempts
+    # @!attribute [r] backoff
+    #   @return [Symbol] Backoff strategy (:exponential, :linear, :fixed)
+    # @!attribute [r] initial_delay
+    #   @return [Integer] Initial delay in milliseconds
+    # @!attribute [r] max_delay
+    #   @return [Integer] Maximum delay in milliseconds
+    # @!attribute [r] multiplier
+    #   @return [Float] Multiplier for exponential backoff
+    #
+    class RetryStrategy
+      attr_reader :max_attempts, :backoff, :initial_delay, :max_delay, :multiplier
+
+      # Default values
+      DEFAULT_MAX_ATTEMPTS = 5
+      DEFAULT_BACKOFF = :exponential
+      DEFAULT_INITIAL_DELAY = 1_000 # 1 second
+      DEFAULT_MAX_DELAY = 60_000 # 60 seconds
+      DEFAULT_MULTIPLIER = 2.0
+
+      # Initialize a new retry strategy
+      #
+      # @param max_attempts [Integer] Maximum attempts
+      # @param backoff [Symbol] Backoff strategy
+      # @param initial_delay [Integer] Initial delay in ms
+      # @param max_delay [Integer] Max delay in ms
+      # @param multiplier [Float] Backoff multiplier
+      def initialize(
+        max_attempts: DEFAULT_MAX_ATTEMPTS,
+        backoff: DEFAULT_BACKOFF,
+        initial_delay: DEFAULT_INITIAL_DELAY,
+        max_delay: DEFAULT_MAX_DELAY,
+        multiplier: DEFAULT_MULTIPLIER
+      )
+        @max_attempts = max_attempts
+        @backoff = backoff
+        @initial_delay = initial_delay
+        @max_delay = max_delay
+        @multiplier = multiplier
+
+        validate!
+        freeze
+      end
+
+      # Calculate delay for an attempt
+      #
+      # @param attempt [Integer] Attempt number (1-based)
+      # @return [Integer] Delay in milliseconds
+      def delay_for_attempt(attempt)
+        delay = case backoff
+                when :exponential
+                  exponential_delay(attempt)
+                when :linear
+                  linear_delay(attempt)
+                when :fixed
+                  initial_delay
+                else
+                  initial_delay
+                end
+
+        [delay, max_delay].min
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          max_attempts: max_attempts,
+          backoff: backoff,
+          initial_delay: initial_delay,
+          max_delay: max_delay,
+          multiplier: multiplier
+        }
+      end
+
+      alias to_hash to_h
+
+      private
+
+      # Calculate exponential delay
+      #
+      # @param attempt [Integer] Attempt number
+      # @return [Integer] Delay in milliseconds
+      def exponential_delay(attempt)
+        (initial_delay * (multiplier**(attempt - 1))).to_i
+      end
+
+      # Calculate linear delay
+      #
+      # @param attempt [Integer] Attempt number
+      # @return [Integer] Delay in milliseconds
+      def linear_delay(attempt)
+        initial_delay * attempt
+      end
+
+      # Validate configuration
+      #
+      # @raise [ArgumentError] If configuration is invalid
+      def validate!
+        raise ArgumentError, 'max_attempts must be positive' unless max_attempts.positive?
+        raise ArgumentError, 'initial_delay must be positive' unless initial_delay.positive?
+        raise ArgumentError, 'max_delay must be positive' unless max_delay.positive?
+        raise ArgumentError, 'multiplier must be positive' unless multiplier.positive?
+
+        valid_backoffs = %i[exponential linear fixed]
+        return if valid_backoffs.include?(backoff)
+
+        raise ArgumentError, "backoff must be one of: #{valid_backoffs.join(', ')}"
+      end
+    end
+
+    # Circuit breaker configuration
+    #
+    # @!attribute [r] enabled
+    #   @return [Boolean] Enable circuit breaker
+    # @!attribute [r] threshold
+    #   @return [Integer] Number of failures before opening
+    # @!attribute [r] timeout
+    #   @return [Integer] Time to keep circuit open in milliseconds
+    # @!attribute [r] half_open_max_calls
+    #   @return [Integer] Number of test calls in half-open state
+    #
+    class CircuitBreakerConfig
+      attr_reader :enabled, :threshold, :timeout, :half_open_max_calls
+
+      # Initialize circuit breaker config
+      #
+      # @param enabled [Boolean] Enable circuit breaker
+      # @param threshold [Integer] Failure threshold
+      # @param timeout [Integer] Timeout in milliseconds
+      # @param half_open_max_calls [Integer] Max calls in half-open state
+      def initialize(enabled: false, threshold: 5, timeout: 60_000, half_open_max_calls: 3)
+        @enabled = enabled
+        @threshold = threshold
+        @timeout = timeout
+        @half_open_max_calls = half_open_max_calls
+
+        freeze
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          enabled: enabled,
+          threshold: threshold,
+          timeout: timeout,
+          half_open_max_calls: half_open_max_calls
+        }
+      end
+
+      alias to_hash to_h
+    end
+  end
+end