jetstream_bridge 2.9.0 → 3.0.0

data/lib/jetstream_bridge/core/config.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require_relative '../errors'
+
 module JetstreamBridge
   class Config
     attr_accessor :destination_app, :nats_urls, :env, :app_name,
                   :max_deliver, :ack_wait, :backoff,
                   :use_outbox, :use_inbox, :inbox_model, :outbox_model,
-                  :use_dlq
+                  :use_dlq, :logger
 
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
@@ -22,6 +24,7 @@ module JetstreamBridge
       @use_dlq      = true
       @outbox_model = 'JetstreamBridge::OutboxEvent'
       @inbox_model  = 'JetstreamBridge::InboxEvent'
+      @logger       = nil
     end
 
     # Single stream name per env
@@ -33,20 +36,53 @@ module JetstreamBridge
     # Producer publishes to:   {env}.{app}.sync.{dest}
     # Consumer subscribes to:  {env}.{dest}.sync.{app}
     def source_subject
+      validate_subject_component!(env, 'env')
+      validate_subject_component!(app_name, 'app_name')
+      validate_subject_component!(destination_app, 'destination_app')
       "#{env}.#{app_name}.sync.#{destination_app}"
     end
 
     def destination_subject
+      validate_subject_component!(env, 'env')
+      validate_subject_component!(app_name, 'app_name')
+      validate_subject_component!(destination_app, 'destination_app')
       "#{env}.#{destination_app}.sync.#{app_name}"
     end
 
     # DLQ
     def dlq_subject
+      validate_subject_component!(env, 'env')
       "#{env}.sync.dlq"
     end
 
     def durable_name
       "#{env}-#{app_name}-workers"
     end
+
+    # Validate configuration settings
+    def validate!
+      errors = []
+      errors << 'destination_app is required' if destination_app.to_s.strip.empty?
+      errors << 'nats_urls is required' if nats_urls.to_s.strip.empty?
+      errors << 'env is required' if env.to_s.strip.empty?
+      errors << 'app_name is required' if app_name.to_s.strip.empty?
+      errors << 'max_deliver must be >= 1' if max_deliver.to_i < 1
+      errors << 'backoff must be an array' unless backoff.is_a?(Array)
+      errors << 'backoff must not be empty' if backoff.is_a?(Array) && backoff.empty?
+
+      raise ConfigurationError, "Configuration errors: #{errors.join(', ')}" if errors.any?
+
+      true
+    end
+
+    private
+
+    def validate_subject_component!(value, name)
+      str = value.to_s
+      if str.match?(/[.*>]/)
+        raise InvalidSubjectError, "#{name} cannot contain NATS wildcards (., *, >): #{value.inspect}"
+      end
+      raise MissingConfigurationError, "#{name} cannot be empty" if str.strip.empty?
+    end
   end
 end

data/lib/jetstream_bridge/core/connection.rb

@@ -9,7 +9,21 @@ require_relative 'config'
 require_relative '../topology/topology'
 
 module JetstreamBridge
-  # Singleton connection to NATS.
+  # Singleton connection to NATS with thread-safe initialization.
+  #
+  # This class manages a single NATS connection for the entire application,
+  # ensuring thread-safe access in multi-threaded environments like Rails
+  # with Puma or Sidekiq.
+  #
+  # Thread Safety:
+  # - Connection initialization is synchronized with a mutex
+  # - The singleton pattern ensures only one connection instance exists
+  # - Safe to call from multiple threads/workers simultaneously
+  #
+  # Example:
+  #   # Safe from any thread
+  #   jts = JetstreamBridge::Connection.connect!
+  #   jts.publish(...)
   class Connection
     include Singleton
 
@@ -23,6 +37,10 @@ module JetstreamBridge
     class << self
       # Thread-safe delegator to the singleton instance.
       # Returns a live JetStream context.
+      #
+      # Safe to call from multiple threads - uses mutex for synchronization.
+      #
+      # @return [NATS::JetStream::JS] JetStream context
       def connect!
         @__mutex ||= Mutex.new
         @__mutex.synchronize { instance.connect! }
@@ -56,13 +74,34 @@ module JetstreamBridge
       # Ensure topology (streams, subjects, overlap guard, etc.)
       Topology.ensure!(@jts)
 
+      @connected_at = Time.now.utc
       @jts
     end
 
+    # Public API for checking connection status
+    # @return [Boolean] true if NATS client is connected and JetStream is healthy
+    def connected?
+      @nc&.connected? && @jts && jetstream_healthy?
+    end
+
+    # Public API for getting connection timestamp
+    # @return [Time, nil] timestamp when connection was established
+    def connected_at
+      @connected_at
+    end
+
     private
 
-    def connected?
-      @nc&.connected?
+    def jetstream_healthy?
+      # Verify JetStream responds to simple API call
+      @jts.account_info
+      true
+    rescue StandardError => e
+      Logging.warn(
+        "JetStream health check failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+      false
     end
 
     def nats_servers
@@ -75,6 +114,30 @@ module JetstreamBridge
 
     def establish_connection(servers)
       @nc = NATS::IO::Client.new
+
+      # Setup reconnect handler to refresh JetStream context
+      @nc.on_reconnect do
+        Logging.info(
+          'NATS reconnected, refreshing JetStream context',
+          tag: 'JetstreamBridge::Connection'
+        )
+        refresh_jetstream_context
+      end
+
+      @nc.on_disconnect do |reason|
+        Logging.warn(
+          "NATS disconnected: #{reason}",
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
+
+      @nc.on_error do |err|
+        Logging.error(
+          "NATS error: #{err}",
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
+
       @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS))
 
       # Create JetStream context
@@ -87,6 +150,20 @@ module JetstreamBridge
       @jts.define_singleton_method(:nc) { nc_ref }
     end
 
+    def refresh_jetstream_context
+      @jts = @nc.jetstream
+      nc_ref = @nc
+      @jts.define_singleton_method(:nc) { nc_ref } unless @jts.respond_to?(:nc)
+
+      # Re-ensure topology after reconnect
+      Topology.ensure!(@jts)
+    rescue StandardError => e
+      Logging.error(
+        "Failed to refresh JetStream context: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+    end
+
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc
 

data/lib/jetstream_bridge/core/connection_factory.rb

@@ -0,0 +1,102 @@
+# 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
+          unless jts.respond_to?(:nc)
+            jts.define_singleton_method(:nc) { client }
+          end
+
+          jts
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/core/debug_helper.rb

@@ -0,0 +1,107 @@
+# 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: (cfg.source_subject rescue 'ERROR'),
+          destination_subject: (cfg.destination_subject rescue 'ERROR'),
+          dlq_subject: (cfg.dlq_subject rescue 'ERROR'),
+          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 > 0 && 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/logging.rb

@@ -1,20 +1,31 @@
 # frozen_string_literal: true
 
 require 'uri'
+require 'logger'
 
 module JetstreamBridge
-  # Logging helpers that route to Rails.logger when available,
-  # falling back to STDOUT.
+  # Logging helpers that route to the configured logger when available,
+  # falling back to Rails.logger or STDOUT.
   module Logging
     module_function
 
+    def logger
+      JetstreamBridge.config.logger ||
+        (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) ||
+        default_logger
+    end
+
+    def default_logger
+      @default_logger ||= Logger.new($stdout)
+    end
+
     def log(level, msg, tag: nil)
       message = tag ? "[#{tag}] #{msg}" : msg
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.public_send(level, message)
-      else
-        puts "[#{level.to_s.upcase}] #{message}"
-      end
+      logger.public_send(level, message)
+    end
+
+    def debug(msg, tag: nil)
+      log(:debug, msg, tag: tag)
     end
 
     def info(msg, tag: nil)
@@ -29,6 +40,7 @@ module JetstreamBridge
       log(:error, msg, tag: tag)
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def sanitize_url(url)
       uri = URI.parse(url)
       return url unless uri.user || uri.password
@@ -55,5 +67,6 @@ module JetstreamBridge
         "#{scheme}://#{masked}@"
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end

data/lib/jetstream_bridge/core/model_utils.rb

@@ -14,10 +14,13 @@ module JetstreamBridge
       defined?(ActiveRecord::Base) && klass <= ActiveRecord::Base
     end
 
+    # rubocop:disable Naming/PredicatePrefix
     def has_columns?(klass, *cols)
       return false unless ar_class?(klass)
+
       cols.flatten.all? { |c| klass.column_names.include?(c.to_s) }
     end
+    # rubocop:enable Naming/PredicatePrefix
 
     def assign_known_attrs(record, attrs)
       attrs.each do |k, v|
@@ -30,9 +33,7 @@ module JetstreamBridge
     def find_or_init_by_best(klass, *keysets)
       keysets.each do |keys|
         next if keys.nil? || keys.empty?
-        if has_columns?(klass, keys.keys)
-          return klass.find_or_initialize_by(keys)
-        end
+        return klass.find_or_initialize_by(keys) if has_columns?(klass, keys.keys)
       end
       klass.new
     end

data/lib/jetstream_bridge/core/retry_strategy.rb

@@ -0,0 +1,135 @@
+# 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 => 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