jetstream_bridge 2.10.0 → 3.0.1

data/lib/jetstream_bridge/core/connection_factory.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'connection'
+require_relative '../errors'
+
+module JetstreamBridge
+  module Core
+    # Factory for creating and managing NATS connections
+    class ConnectionFactory
+      # Connection options builder
+      class ConnectionOptions
+        DEFAULT_OPTS = {
+          reconnect: true,
+          reconnect_time_wait: 2,
+          max_reconnect_attempts: 10,
+          connect_timeout: 5
+        }.freeze
+
+        attr_accessor :servers, :reconnect, :reconnect_time_wait,
+                      :max_reconnect_attempts, :connect_timeout,
+                      :name, :user, :pass, :token
+        attr_reader :additional_opts
+
+        def initialize(servers: nil, **opts)
+          @servers = normalize_servers(servers) if servers
+          @additional_opts = {}
+
+          DEFAULT_OPTS.merge(opts).each do |key, value|
+            if respond_to?(:"#{key}=")
+              send(:"#{key}=", value)
+            else
+              @additional_opts[key] = value
+            end
+          end
+        end
+
+        def self.build(opts = {})
+          new(**opts)
+        end
+
+        def to_h
+          base = {
+            reconnect: @reconnect,
+            reconnect_time_wait: @reconnect_time_wait,
+            max_reconnect_attempts: @max_reconnect_attempts,
+            connect_timeout: @connect_timeout
+          }
+
+          base[:servers] = @servers if @servers
+          base[:name] = @name if @name
+          base[:user] = @user if @user
+          base[:pass] = @pass if @pass
+          base[:token] = @token if @token
+
+          base.merge(@additional_opts)
+        end
+
+        private
+
+        def normalize_servers(servers)
+          Array(servers)
+            .flat_map { |s| s.to_s.split(',') }
+            .map(&:strip)
+            .reject(&:empty?)
+        end
+      end
+
+      class << self
+        # Create connection options from config
+        def build_options(config = JetstreamBridge.config)
+          servers = config.nats_urls
+          raise ConnectionNotEstablishedError, 'No NATS URLs configured' if servers.to_s.strip.empty?
+
+          ConnectionOptions.new(
+            servers: servers,
+            name: "#{config.app_name}-#{config.env}"
+          )
+        end
+
+        # Create a new NATS client
+        def create_client(options = nil)
+          opts = options || build_options
+          client = NATS::IO::Client.new
+          client.connect(opts.to_h)
+          client
+        end
+
+        # Create JetStream context with health monitoring
+        def create_jetstream(client)
+          jts = client.jetstream
+
+          # Ensure JetStream responds to #nc for compatibility
+          jts.define_singleton_method(:nc) { client } unless jts.respond_to?(:nc)
+
+          jts
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/core/debug_helper.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative 'logging'
+
+module JetstreamBridge
+  # Debug helper for troubleshooting JetStream Bridge operations
+  module DebugHelper
+    class << self
+      # Print comprehensive debug information about the current setup
+      def debug_info
+        info = {
+          config: config_debug,
+          connection: connection_debug,
+          stream: stream_debug,
+          health: JetstreamBridge.health_check
+        }
+
+        Logging.info('=== JetStream Bridge Debug Info ===', tag: 'JetstreamBridge::Debug')
+        info.each do |section, data|
+          Logging.info("#{section.to_s.upcase}:", tag: 'JetstreamBridge::Debug')
+          log_hash(data, indent: 2)
+        end
+        Logging.info('=== End Debug Info ===', tag: 'JetstreamBridge::Debug')
+
+        info
+      end
+
+      private
+
+      def config_debug
+        cfg = JetstreamBridge.config
+        {
+          env: cfg.env,
+          app_name: cfg.app_name,
+          destination_app: cfg.destination_app,
+          stream_name: cfg.stream_name,
+          source_subject: begin
+            cfg.source_subject
+          rescue StandardError
+            'ERROR'
+          end,
+          destination_subject: begin
+            cfg.destination_subject
+          rescue StandardError
+            'ERROR'
+          end,
+          dlq_subject: begin
+            cfg.dlq_subject
+          rescue StandardError
+            'ERROR'
+          end,
+          durable_name: cfg.durable_name,
+          nats_urls: cfg.nats_urls,
+          max_deliver: cfg.max_deliver,
+          ack_wait: cfg.ack_wait,
+          backoff: cfg.backoff,
+          use_outbox: cfg.use_outbox,
+          use_inbox: cfg.use_inbox,
+          use_dlq: cfg.use_dlq,
+          outbox_model: cfg.outbox_model,
+          inbox_model: cfg.inbox_model
+        }
+      end
+
+      def connection_debug
+        conn = Connection.instance
+        {
+          connected: conn.connected?,
+          connected_at: conn.connected_at&.iso8601,
+          nc_present: !conn.instance_variable_get(:@nc).nil?,
+          jts_present: !conn.instance_variable_get(:@jts).nil?
+        }
+      rescue StandardError => e
+        { error: "#{e.class}: #{e.message}" }
+      end
+
+      def stream_debug
+        return { error: 'Not connected' } unless Connection.instance.connected?
+
+        jts = Connection.jetstream
+        cfg = JetstreamBridge.config
+        info = jts.stream_info(cfg.stream_name)
+
+        {
+          name: cfg.stream_name,
+          exists: true,
+          subjects: info.config.subjects,
+          retention: info.config.retention,
+          storage: info.config.storage,
+          max_consumers: info.config.max_consumers,
+          messages: info.state.messages,
+          bytes: info.state.bytes,
+          first_seq: info.state.first_seq,
+          last_seq: info.state.last_seq
+        }
+      rescue StandardError => e
+        {
+          name: JetstreamBridge.config.stream_name,
+          exists: false,
+          error: "#{e.class}: #{e.message}"
+        }
+      end
+
+      def log_hash(hash, indent: 0)
+        prefix = ' ' * indent
+        hash.each do |key, value|
+          if value.is_a?(Hash)
+            Logging.info("#{prefix}#{key}:", tag: 'JetstreamBridge::Debug')
+            log_hash(value, indent: indent + 2)
+          elsif value.is_a?(Array)
+            Logging.info("#{prefix}#{key}: #{value.inspect}", tag: 'JetstreamBridge::Debug')
+          else
+            Logging.info("#{prefix}#{key}: #{value}", tag: 'JetstreamBridge::Debug')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/core/duration.rb

@@ -71,7 +71,14 @@ module JetstreamBridge
     def int_to_ms(num, default_unit:)
       case default_unit
       when :auto
-        # Preserve existing heuristic for compatibility
+        # Preserve existing heuristic for compatibility but log deprecation warning
+        if defined?(Logging) && num.positive? && num < 1_000
+          Logging.debug(
+            "Duration :auto heuristic treating #{num} as seconds. " \
+            "Consider specifying default_unit: :s or :ms for clarity.",
+            tag: 'JetstreamBridge::Duration'
+          )
+        end
         num >= 1_000 ? num : num * 1_000
       else
         coerce_numeric_to_ms(num.to_f, default_unit)

data/lib/jetstream_bridge/core/retry_strategy.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative 'logging'
+
+begin
+  require 'nats/io/client'
+rescue LoadError
+  # NATS not available, PublisherRetryStrategy won't work but that's ok for tests
+end
+
+module JetstreamBridge
+  # Base retry strategy interface
+  class RetryStrategy
+    class RetryExhausted < StandardError; end
+
+    def initialize(max_attempts:, backoffs: [], transient_errors: [])
+      @max_attempts = max_attempts
+      @backoffs = backoffs
+      @transient_errors = transient_errors
+    end
+
+    # Execute block with retry logic
+    # @yield Block to execute with retry
+    # @return Result of the block
+    # @raise RetryExhausted if all attempts fail
+    def execute(context: nil)
+      attempts = 0
+      last_error = nil
+
+      loop do
+        attempts += 1
+        begin
+          return yield
+        rescue *retryable_errors => e
+          last_error = e
+          raise e if attempts >= @max_attempts
+
+          delay = calculate_delay(attempts, e)
+          log_retry(attempts, e, delay, context)
+          sleep delay
+        end
+      end
+    rescue StandardError => e
+      raise unless retryable?(e)
+
+      raise RetryExhausted, "Failed after #{attempts} attempts: #{e.message}"
+    end
+
+    protected
+
+    def calculate_delay(attempt, _error)
+      @backoffs[attempt - 1] || @backoffs.last || 1.0
+    end
+
+    def retryable_errors
+      @transient_errors.empty? ? [StandardError] : @transient_errors
+    end
+
+    def retryable?(error)
+      retryable_errors.any? { |klass| error.is_a?(klass) }
+    end
+
+    def log_retry(attempt, error, delay, context)
+      ctx_info = context ? " [#{context}]" : ''
+      Logging.warn(
+        "Retry #{attempt}/#{@max_attempts}#{ctx_info}: #{error.class} - #{error.message}, " \
+        "waiting #{delay}s",
+        tag: 'JetstreamBridge::RetryStrategy'
+      )
+    end
+  end
+
+  # Exponential backoff retry strategy
+  class ExponentialBackoffStrategy < RetryStrategy
+    def initialize(max_attempts: 3, base_delay: 0.1, max_delay: 60, multiplier: 2, transient_errors: [], jitter: true)
+      @base_delay = base_delay
+      @max_delay = max_delay
+      @multiplier = multiplier
+      @jitter = jitter
+      backoffs = compute_backoffs(max_attempts)
+      super(max_attempts: max_attempts, backoffs: backoffs, transient_errors: transient_errors)
+    end
+
+    protected
+
+    def calculate_delay(attempt, _error)
+      @backoffs[attempt - 1] || @backoffs.last || @base_delay
+    end
+
+    private
+
+    def compute_backoffs(max_attempts)
+      (0...max_attempts).map do |i|
+        delay = @base_delay * (@multiplier**i)
+        if @jitter
+          # Add up to 10% jitter, but ensure we don't exceed max_delay
+          jitter_amount = delay * 0.1 * rand
+          delay = [delay + jitter_amount, @max_delay].min
+        else
+          delay = [delay, @max_delay].min
+        end
+        delay
+      end
+    end
+  end
+
+  # Linear backoff retry strategy
+  class LinearBackoffStrategy < RetryStrategy
+    def initialize(max_attempts: 3, delays: [0.25, 1.0, 2.0], transient_errors: [])
+      super(max_attempts: max_attempts, backoffs: delays, transient_errors: transient_errors)
+    end
+  end
+
+  # Publisher-specific retry strategy
+  class PublisherRetryStrategy < LinearBackoffStrategy
+    TRANSIENT_ERRORS = begin
+      errs = []
+      if defined?(NATS::IO)
+        errs << NATS::IO::Timeout if defined?(NATS::IO::Timeout)
+        errs << NATS::IO::Error if defined?(NATS::IO::Error)
+        errs << NATS::IO::NoServersError if defined?(NATS::IO::NoServersError)
+        errs << NATS::IO::SocketTimeoutError if defined?(NATS::IO::SocketTimeoutError)
+        errs << Errno::ECONNREFUSED
+      end
+      errs
+    end.freeze
+
+    def initialize(max_attempts: 2)
+      super(
+        max_attempts: max_attempts,
+        delays: [0.25, 1.0],
+        transient_errors: TRANSIENT_ERRORS
+      )
+    end
+  end
+end

data/lib/jetstream_bridge/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  # Base error for all JetStream Bridge errors
+  class Error < StandardError; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+  class InvalidSubjectError < ConfigurationError; end
+  class MissingConfigurationError < ConfigurationError; end
+
+  # Connection errors
+  class ConnectionError < Error; end
+  class ConnectionNotEstablishedError < ConnectionError; end
+  class HealthCheckFailedError < ConnectionError; end
+
+  # Publisher errors
+  class PublishError < Error; end
+  class PublishFailedError < PublishError; end
+  class OutboxError < PublishError; end
+
+  # Consumer errors
+  class ConsumerError < Error; end
+  class HandlerError < ConsumerError; end
+  class InboxError < ConsumerError; end
+
+  # Topology errors
+  class TopologyError < Error; end
+  class StreamNotFoundError < TopologyError; end
+  class SubjectOverlapError < TopologyError; end
+  class StreamCreationFailedError < TopologyError; end
+
+  # DLQ errors
+  class DlqError < Error; end
+  class DlqPublishFailedError < DlqError; end
+
+  # Retry errors (already defined in retry_strategy.rb)
+  # class RetryExhausted < Error; end
+end

data/lib/jetstream_bridge/models/event_envelope.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module JetstreamBridge
+  module Models
+    # Value object representing an event envelope
+    class EventEnvelope
+      SCHEMA_VERSION = 1
+
+      attr_reader :event_id, :schema_version, :event_type, :producer,
+                  :resource_type, :resource_id, :occurred_at, :trace_id, :payload
+
+      def initialize(
+        resource_type:,
+        event_type:,
+        payload:,
+        event_id: nil,
+        occurred_at: nil,
+        trace_id: nil,
+        producer: nil,
+        resource_id: nil
+      )
+        @event_id = event_id || SecureRandom.uuid
+        @schema_version = SCHEMA_VERSION
+        @event_type = event_type.to_s
+        @producer = producer || JetstreamBridge.config.app_name
+        @resource_type = resource_type.to_s
+        @resource_id = resource_id || extract_resource_id(payload)
+        @occurred_at = parse_occurred_at(occurred_at)
+        @trace_id = trace_id || SecureRandom.hex(8)
+        @payload = deep_freeze(payload)
+
+        validate!
+        freeze
+      end
+
+      # Convert to hash for serialization
+      def to_h
+        hash = {
+          event_id: @event_id,
+          schema_version: @schema_version,
+          event_type: @event_type,
+          producer: @producer,
+          resource_type: @resource_type,
+          occurred_at: format_time(@occurred_at),
+          payload: @payload
+        }
+
+        # Only include optional fields if they have values
+        hash[:resource_id] = @resource_id if @resource_id && !@resource_id.to_s.empty?
+        hash[:trace_id] = @trace_id if @trace_id && !@trace_id.to_s.empty?
+
+        hash
+      end
+
+      # Create from hash
+      def self.from_h(hash)
+        new(
+          event_id: hash['event_id'] || hash[:event_id],
+          event_type: hash['event_type'] || hash[:event_type],
+          producer: hash['producer'] || hash[:producer],
+          resource_type: hash['resource_type'] || hash[:resource_type],
+          resource_id: hash['resource_id'] || hash[:resource_id],
+          occurred_at: parse_time(hash['occurred_at'] || hash[:occurred_at]),
+          trace_id: hash['trace_id'] || hash[:trace_id],
+          payload: hash['payload'] || hash[:payload] || {}
+        )
+      end
+
+      def ==(other)
+        other.is_a?(EventEnvelope) && event_id == other.event_id
+      end
+
+      alias eql? ==
+
+      def hash
+        event_id.hash
+      end
+
+      private
+
+      def extract_resource_id(payload)
+        return '' unless payload.respond_to?(:[])
+
+        (payload['id'] || payload[:id]).to_s
+      end
+
+      def validate!
+        raise ArgumentError, 'event_type cannot be blank' if @event_type.empty?
+        raise ArgumentError, 'resource_type cannot be blank' if @resource_type.empty?
+        raise ArgumentError, 'payload cannot be nil' if @payload.nil?
+      end
+
+      def parse_occurred_at(value)
+        return Time.now.utc if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        Time.now.utc
+      end
+
+      def format_time(time)
+        time.is_a?(Time) ? time.iso8601 : time.to_s
+      end
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each do |k, v|
+            deep_freeze(k)
+            deep_freeze(v)
+          end
+          obj.freeze
+        when Array
+          obj.each { |item| deep_freeze(item) }
+          obj.freeze
+        else
+          obj.freeze if obj.respond_to?(:freeze)
+        end
+        obj
+      end
+
+      def self.parse_time(value)
+        return value if value.is_a?(Time)
+        return Time.now.utc if value.nil?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        Time.now.utc
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/models/subject.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module Models
+    # Value object representing a NATS subject
+    class Subject
+      WILDCARD_SINGLE = '*'
+      WILDCARD_MULTI = '>'
+      SEPARATOR = '.'
+      INVALID_CHARS = /[#{Regexp.escape(WILDCARD_SINGLE + WILDCARD_MULTI + SEPARATOR)}]/.freeze
+
+      attr_reader :value, :tokens
+
+      def initialize(value)
+        @value = value.to_s
+        @tokens = @value.split(SEPARATOR)
+        validate!
+        @value.freeze
+        @tokens.freeze
+        freeze
+      end
+
+      # Factory methods
+      def self.source(env:, app_name:, dest:)
+        new("#{env}.#{app_name}.sync.#{dest}")
+      end
+
+      def self.destination(env:, source:, app_name:)
+        new("#{env}.#{source}.sync.#{app_name}")
+      end
+
+      def self.dlq(env:)
+        new("#{env}.sync.dlq")
+      end
+
+      # Check if this subject matches a pattern
+      def matches?(pattern)
+        SubjectMatcher.match?(pattern.to_s, @value)
+      end
+
+      # Check if this subject overlaps with another
+      def overlaps?(other)
+        SubjectMatcher.overlap?(@value, other.to_s)
+      end
+
+      # Check if covered by any pattern in a list
+      def covered_by?(patterns)
+        SubjectMatcher.covered?(Array(patterns).map(&:to_s), @value)
+      end
+
+      def to_s
+        @value
+      end
+
+      def ==(other)
+        @value == (other.is_a?(Subject) ? other.value : other.to_s)
+      end
+
+      alias eql? ==
+
+      def hash
+        @value.hash
+      end
+
+      # Validate a component (env, app_name, etc.) for use in subjects
+      def self.validate_component!(value, name)
+        str = value.to_s
+        if str.match?(INVALID_CHARS)
+          raise ArgumentError,
+                "#{name} cannot contain NATS wildcards (#{SEPARATOR}, #{WILDCARD_SINGLE}, #{WILDCARD_MULTI}): #{value.inspect}"
+        end
+        raise ArgumentError, "#{name} cannot be empty" if str.strip.empty?
+
+        true
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, 'Subject cannot be empty' if @value.empty?
+        raise ArgumentError, 'Subject cannot contain only separators' if @tokens.all?(&:empty?)
+        raise ArgumentError, 'Subject has invalid format (contains spaces or special characters)' if @value.match?(/\s/)
+      end
+
+      # Lazy-load SubjectMatcher to avoid circular dependency
+      def self.subject_matcher
+        require_relative '../topology/subject_matcher' unless defined?(JetstreamBridge::SubjectMatcher)
+        JetstreamBridge::SubjectMatcher
+      end
+
+      SubjectMatcher = subject_matcher
+    end
+  end
+end