jetstream_bridge 4.0.4 → 4.2.0

data/lib/jetstream_bridge/core/connection.rb

@@ -27,6 +27,15 @@ module JetstreamBridge
   class Connection
     include Singleton
 
+    # Connection states for observability
+    module State
+      DISCONNECTED = :disconnected
+      CONNECTING = :connecting
+      CONNECTED = :connected
+      RECONNECTING = :reconnecting
+      FAILED = :failed
+    end
+
     DEFAULT_CONN_OPTS = {
       reconnect: true,
       reconnect_time_wait: 2,
@@ -36,16 +45,21 @@ module JetstreamBridge
 
     VALID_NATS_SCHEMES = %w[nats nats+tls].freeze
 
+    # Class-level mutex for thread-safe connection initialization
+    # Using class variable to avoid race condition in mutex creation
+    # rubocop:disable Style/ClassVars
+    @@connection_lock = Mutex.new
+    # rubocop:enable Style/ClassVars
+
     class << self
       # Thread-safe delegator to the singleton instance.
       # Returns a live JetStream context.
       #
-      # Safe to call from multiple threads - uses mutex for synchronization.
+      # Safe to call from multiple threads - uses class-level mutex for synchronization.
       #
       # @return [NATS::JetStream::JS] JetStream context
       def connect!
-        @__mutex ||= Mutex.new
-        @__mutex.synchronize { instance.connect! }
+        @@connection_lock.synchronize { instance.connect! }
       end
 
       # Optional accessors if callers need raw handles
@@ -60,12 +74,14 @@ module JetstreamBridge
 
     # Idempotent: returns an existing, healthy JetStream context or establishes one.
     def connect!
-      return @jts if connected?
+      # Check if already connected without acquiring mutex (for performance)
+      return @jts if @jts && @nc&.connected?
 
       servers = nats_servers
       raise 'No NATS URLs configured' if servers.empty?
 
-      establish_connection(servers)
+      @state = State::CONNECTING
+      establish_connection_with_retry(servers)
 
       Logging.info(
         "Connected to NATS (#{servers.size} server#{'s' unless servers.size == 1}): " \
@@ -77,22 +93,59 @@ module JetstreamBridge
       Topology.ensure!(@jts)
 
       @connected_at = Time.now.utc
+      @state = State::CONNECTED
       @jts
+    rescue StandardError
+      @state = State::FAILED
+      cleanup_connection!
+      raise
     end
 
     # Public API for checking connection status
+    #
+    # Uses cached health check result to avoid excessive network calls.
+    # Cache expires after 30 seconds.
+    #
+    # Thread-safe: Cache updates are synchronized to prevent race conditions.
+    #
+    # @param skip_cache [Boolean] Force fresh health check, bypass cache
     # @return [Boolean] true if NATS client is connected and JetStream is healthy
-    def connected?
+    def connected?(skip_cache: false)
       return false unless @nc&.connected?
       return false unless @jts
 
-      jetstream_healthy?
+      # Use cached result if available and fresh
+      now = Time.now.to_i
+      return @cached_health_status if !skip_cache && @last_health_check && (now - @last_health_check) < 30
+
+      # Thread-safe cache update to prevent race conditions
+      @@connection_lock.synchronize do
+        # Double-check after acquiring lock (another thread may have updated)
+        now = Time.now.to_i
+        return @cached_health_status if !skip_cache && @last_health_check && (now - @last_health_check) < 30
+
+        # Perform actual health check
+        @cached_health_status = jetstream_healthy?
+        @last_health_check = now
+        @cached_health_status
+      end
     end
 
     # Public API for getting connection timestamp
     # @return [Time, nil] timestamp when connection was established
     attr_reader :connected_at
 
+    # Get current connection state
+    #
+    # @return [Symbol] Current connection state (see State module)
+    def state
+      return State::DISCONNECTED unless @nc
+      return State::FAILED if @last_reconnect_error && !@nc.connected?
+      return State::RECONNECTING if @reconnecting
+
+      @nc.connected? ? (@state || State::CONNECTED) : State::DISCONNECTED
+    end
+
     private
 
     def jetstream_healthy?
@@ -118,19 +171,60 @@ module JetstreamBridge
       servers
     end
 
+    def establish_connection_with_retry(servers)
+      attempts = 0
+      max_attempts = JetstreamBridge.config.connect_retry_attempts
+      retry_delay = JetstreamBridge.config.connect_retry_delay
+
+      begin
+        attempts += 1
+        establish_connection(servers)
+      rescue ConnectionError => e
+        if attempts < max_attempts
+          delay = retry_delay * attempts
+          Logging.warn(
+            "Connection attempt #{attempts}/#{max_attempts} failed: #{e.message}. " \
+            "Retrying in #{delay}s...",
+            tag: 'JetstreamBridge::Connection'
+          )
+          sleep(delay)
+          retry
+        else
+          Logging.error(
+            "Failed to establish connection after #{attempts} attempts",
+            tag: 'JetstreamBridge::Connection'
+          )
+          cleanup_connection!
+          raise
+        end
+      end
+    end
+
     def establish_connection(servers)
-      @nc = NATS::IO::Client.new
+      # Use mock NATS client if explicitly enabled for testing
+      # This allows test helpers to inject a mock without affecting normal operation
+      @nc = if defined?(JetstreamBridge::TestHelpers) &&
+               JetstreamBridge::TestHelpers.respond_to?(:test_mode?) &&
+               JetstreamBridge::TestHelpers.test_mode? &&
+               JetstreamBridge.instance_variable_defined?(:@mock_nats_client)
+              JetstreamBridge.instance_variable_get(:@mock_nats_client)
+            else
+              NATS::IO::Client.new
+            end
 
       # Setup reconnect handler to refresh JetStream context
       @nc.on_reconnect do
+        @reconnecting = true
         Logging.info(
           'NATS reconnected, refreshing JetStream context',
           tag: 'JetstreamBridge::Connection'
         )
         refresh_jetstream_context
+        @reconnecting = false
       end
 
       @nc.on_disconnect do |reason|
+        @state = State::DISCONNECTED
         Logging.warn(
           "NATS disconnected: #{reason}",
           tag: 'JetstreamBridge::Connection'
@@ -144,7 +238,14 @@ module JetstreamBridge
         )
       end
 
-      @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS))
+      # Only connect if not already connected (mock may be pre-connected)
+      # Note: For test helpers mock, skip connect. For RSpec mocks, always call connect
+      skip_connect = @nc.connected? &&
+                     defined?(JetstreamBridge::TestHelpers) &&
+                     JetstreamBridge::TestHelpers.respond_to?(:test_mode?) &&
+                     JetstreamBridge::TestHelpers.test_mode?
+
+      @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS)) unless skip_connect
 
       # Verify connection is established
       verify_connection!
@@ -255,11 +356,17 @@ module JetstreamBridge
       # Verify JetStream is enabled by checking account info
       account_info = @jts.account_info
 
+      # Handle both object-style and hash-style access for compatibility
+      streams = account_info.respond_to?(:streams) ? account_info.streams : account_info[:streams]
+      consumers = account_info.respond_to?(:consumers) ? account_info.consumers : account_info[:consumers]
+      memory = account_info.respond_to?(:memory) ? account_info.memory : account_info[:memory]
+      storage = account_info.respond_to?(:storage) ? account_info.storage : account_info[:storage]
+
       Logging.info(
-        "JetStream verified - Streams: #{account_info.streams}, " \
-        "Consumers: #{account_info.consumers}, " \
-        "Memory: #{format_bytes(account_info.memory)}, " \
-        "Storage: #{format_bytes(account_info.storage)}",
+        "JetStream verified - Streams: #{streams}, " \
+        "Consumers: #{consumers}, " \
+        "Memory: #{format_bytes(memory)}, " \
+        "Storage: #{format_bytes(storage)}",
         tag: 'JetstreamBridge::Connection'
       )
     rescue NATS::IO::NoRespondersError
@@ -292,13 +399,40 @@ module JetstreamBridge
 
       # Re-ensure topology after reconnect
       Topology.ensure!(@jts)
+
+      # Invalidate health check cache on successful reconnect
+      @cached_health_status = nil
+      @last_health_check = nil
+
+      # Clear error state on successful reconnect
+      @last_reconnect_error = nil
+      @last_reconnect_error_at = nil
+      @state = State::CONNECTED
+
+      Logging.info(
+        'JetStream context refreshed successfully after reconnect',
+        tag: 'JetstreamBridge::Connection'
+      )
     rescue StandardError => e
+      # Store error state for diagnostics
+      @last_reconnect_error = e
+      @last_reconnect_error_at = Time.now
+      @state = State::FAILED
+      cleanup_connection!(close_nc: false)
       Logging.error(
         "Failed to refresh JetStream context: #{e.class} #{e.message}",
         tag: 'JetstreamBridge::Connection'
       )
+
+      # Invalidate health check cache to force re-check
+      @cached_health_status = false
+      @last_health_check = Time.now.to_i
     end
 
+    # Get last reconnection error for diagnostics
+    # @return [StandardError, nil] Last error during reconnection
+    attr_reader :last_reconnect_error, :last_reconnect_error_at
+
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc
 
@@ -312,5 +446,20 @@ module JetstreamBridge
     def sanitize_urls(urls)
       urls.map { |u| Logging.sanitize_url(u) }
     end
+
+    def cleanup_connection!(close_nc: true)
+      begin
+        # Avoid touching RSpec doubles used in unit tests
+        is_rspec_double = defined?(RSpec::Mocks::Double) && @nc.is_a?(RSpec::Mocks::Double)
+        @nc.close if !is_rspec_double && close_nc && @nc.respond_to?(:close) && @nc.connected?
+      rescue StandardError
+        # ignore cleanup errors
+      end
+      @nc = nil
+      @jts = nil
+      @cached_health_status = nil
+      @last_health_check = nil
+      @connected_at = nil
+    end
   end
 end

data/lib/jetstream_bridge/core.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Core building blocks for JetstreamBridge
+require_relative 'core/config'
+require_relative 'core/duration'
+require_relative 'core/logging'
+require_relative 'core/connection'
+require_relative 'core/bridge_helpers'

data/lib/jetstream_bridge/models/inbox_event.rb

@@ -101,15 +101,21 @@ module JetstreamBridge
 
         # Get processing statistics
         #
-        # @return [Hash] Statistics hash
+        # Uses a single aggregated query to avoid N+1 problem.
+        #
+        # @return [Hash] Statistics hash with counts by status
         def processing_stats
           return {} unless has_column?(:status)
 
+          # Single aggregated query instead of 4 separate queries
+          stats_by_status = group(:status).count
+          total_count = stats_by_status.values.sum
+
           {
-            total: count,
-            processed: processed.count,
-            failed: failed.count,
-            pending: unprocessed.count
+            total: total_count,
+            processed: stats_by_status['processed'] || 0,
+            failed: stats_by_status['failed'] || 0,
+            pending: stats_by_status['pending'] || stats_by_status[nil] || 0
           }
         end
       end
@@ -168,8 +174,8 @@ module JetstreamBridge
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_inbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_inbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end

data/lib/jetstream_bridge/models/outbox_event.rb

@@ -169,8 +169,8 @@ module JetstreamBridge
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_outbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_outbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -36,11 +36,16 @@ module JetstreamBridge
   class Publisher
     # Initialize a new Publisher instance.
     #
+    # Note: The NATS connection should already be established via JetstreamBridge.startup!
+    # or automatically on first use. This assumes the connection is already established.
+    #
     # @param retry_strategy [RetryStrategy, nil] Optional custom retry strategy for handling transient failures.
     #   Defaults to PublisherRetryStrategy with exponential backoff.
-    # @raise [ConnectionError] If unable to connect to NATS server
+    # @raise [ConnectionError] If unable to get JetStream connection
     def initialize(retry_strategy: nil)
-      @jts = Connection.connect!
+      @jts = Connection.jetstream
+      raise ConnectionError, 'JetStream connection not available. Call JetstreamBridge.startup! first.' unless @jts
+
       @retry_strategy = retry_strategy || PublisherRetryStrategy.new
     end
 
@@ -103,7 +108,7 @@ module JetstreamBridge
     #   end
     #
     def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **options)
-      ensure_destination!
+      ensure_destination_app_configured!
 
       params = { event_or_hash: event_or_hash, resource_type: resource_type, event_type: event_type,
                  payload: payload, subject: subject, options: options }
@@ -186,7 +191,7 @@ module JetstreamBridge
       normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
     end
 
-    def ensure_destination!
+    def ensure_destination_app_configured!
       return unless JetstreamBridge.config.destination_app.to_s.empty?
 
       raise ArgumentError, 'destination_app must be configured'
@@ -290,7 +295,7 @@ module JetstreamBridge
         'schema_version' => 1,
         'event_type' => event_type,
         'producer' => JetstreamBridge.config.app_name,
-        'resource_id' => (payload['id'] || payload[:id]).to_s,
+        'resource_id' => extract_resource_id(payload),
         'occurred_at' => (options[:occurred_at] || Time.now.utc).iso8601,
         'trace_id' => options[:trace_id] || SecureRandom.hex(8),
         'resource_type' => resource_type,

data/lib/jetstream_bridge/rails/integration.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative '../core/model_codec_setup'
+require_relative '../core/logging'
+require_relative '../core/connection'
+
+module JetstreamBridge
+  module Rails
+    # Rails-specific lifecycle helpers for JetStream Bridge.
+    #
+    # Keeps the Railtie thin and makes lifecycle decisions easy to test and reason about.
+    module Integration
+      module_function
+
+      # Configure logger to use Rails.logger when available.
+      def configure_logger!
+        JetstreamBridge.configure do |config|
+          config.logger ||= ::Rails.logger if defined?(::Rails.logger)
+        end
+      end
+
+      # Attach ActiveRecord hooks for serializer setup on reload.
+      def attach_active_record_hooks!
+        ActiveSupport.on_load(:active_record) do
+          ActiveSupport::Reloader.to_prepare { JetstreamBridge::ModelCodecSetup.apply! }
+        end
+      end
+
+      # Validate config, enable test mode if appropriate, and start the bridge unless auto-start is disabled.
+      def boot_bridge!
+        auto_enable_test_mode!
+
+        if autostart_disabled?
+          message = "Auto-start skipped (reason: #{autostart_skip_reason}; " \
+                    'enable via lazy_connect=false, unset JETSTREAM_BRIDGE_DISABLE_AUTOSTART, ' \
+                    'or set JETSTREAM_BRIDGE_FORCE_AUTOSTART=1)'
+          Logging.info(message, tag: 'JetstreamBridge::Railtie')
+          return
+        end
+
+        JetstreamBridge.config.validate!
+        JetstreamBridge.startup!
+        log_started!
+        log_development_connection_details! if rails_development?
+        register_shutdown_hook!
+      end
+
+      # Auto-enable test mode in test environment when NATS is not configured.
+      def auto_enable_test_mode!
+        return unless auto_enable_test_mode?
+
+        Logging.info(
+          '[JetStream Bridge] Auto-enabling test mode (NATS_URLS not set)',
+          tag: 'JetstreamBridge::Railtie'
+        )
+
+        require_relative '../test_helpers'
+        JetstreamBridge::TestHelpers.enable_test_mode!
+      end
+
+      def auto_enable_test_mode?
+        rails_test? &&
+          ENV['NATS_URLS'].to_s.strip.empty? &&
+          !(defined?(JetstreamBridge::TestHelpers) &&
+            JetstreamBridge::TestHelpers.respond_to?(:test_mode?) &&
+            JetstreamBridge::TestHelpers.test_mode?)
+      end
+
+      def autostart_disabled?
+        return false if force_autostart?
+
+        JetstreamBridge.config.lazy_connect ||
+          env_disables_autostart? ||
+          skip_autostart_for_rails_tooling?
+      end
+
+      def autostart_skip_reason
+        return 'lazy_connect enabled' if JetstreamBridge.config.lazy_connect
+        return 'JETSTREAM_BRIDGE_DISABLE_AUTOSTART set' if env_disables_autostart?
+        return 'Rails console' if rails_console?
+        return 'rake task' if rake_task?
+
+        'unknown'
+      end
+
+      def env_disables_autostart?
+        value = ENV.fetch('JETSTREAM_BRIDGE_DISABLE_AUTOSTART', nil)
+        return false if value.nil?
+
+        normalized = value.to_s.strip.downcase
+        return false if normalized.empty?
+
+        !%w[false 0 no off].include?(normalized)
+      end
+
+      def force_autostart?
+        value = ENV.fetch('JETSTREAM_BRIDGE_FORCE_AUTOSTART', nil)
+        return false if value.nil?
+
+        normalized = value.to_s.strip.downcase
+        %w[true 1 yes on].include?(normalized)
+      end
+
+      def log_started!
+        active_logger&.info('[JetStream Bridge] Started successfully')
+      end
+
+      def log_development_connection_details!
+        conn_state = JetstreamBridge::Connection.instance.state
+        active_logger&.info("[JetStream Bridge] Connection state: #{conn_state}")
+        active_logger&.info("[JetStream Bridge] Connected to: #{JetstreamBridge.config.nats_urls}")
+        active_logger&.info("[JetStream Bridge] Stream: #{JetstreamBridge.config.stream_name}")
+        active_logger&.info("[JetStream Bridge] Publishing to: #{JetstreamBridge.config.source_subject}")
+        active_logger&.info("[JetStream Bridge] Consuming from: #{JetstreamBridge.config.destination_subject}")
+      end
+
+      def register_shutdown_hook!
+        return if @shutdown_hook_registered
+
+        at_exit { JetstreamBridge.shutdown! }
+        @shutdown_hook_registered = true
+      end
+
+      def rails_test?
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.test?
+      end
+
+      def rails_development?
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.development?
+      end
+
+      def rails_console?
+        !!defined?(::Rails::Console)
+      end
+
+      def rake_task?
+        !!defined?(::Rake) || File.basename($PROGRAM_NAME) == 'rake'
+      end
+
+      def skip_autostart_for_rails_tooling?
+        rails_console? || rake_task?
+      end
+
+      def active_logger
+        if defined?(::Rails) && ::Rails.respond_to?(:logger)
+          ::Rails.logger
+        else
+          Logging.logger
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/rails/railtie.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'integration'
+
+module JetstreamBridge
+  # Rails integration for JetStream Bridge.
+  #
+  # This Railtie integrates JetStream Bridge with the Rails application lifecycle:
+  # - Configuration: Logger is configured early in the Rails boot process
+  # - Startup: Connection is established after user initializers load (explicit startup!)
+  # - Shutdown: Connection is closed when Rails shuts down (at_exit hook)
+  # - Restart: Puma/Unicorn workers get fresh connections on fork
+  #
+  class Railtie < ::Rails::Railtie
+    # Set up logger to use Rails.logger by default
+    # Note: This only configures the logger, does NOT establish connection
+    initializer 'jetstream_bridge.logger', before: :initialize_logger do
+      JetstreamBridge::Rails::Integration.configure_logger!
+    end
+
+    # Load ActiveRecord model tweaks after ActiveRecord is loaded
+    initializer 'jetstream_bridge.active_record', after: 'active_record.initialize_database' do
+      JetstreamBridge::Rails::Integration.attach_active_record_hooks!
+    end
+
+    # Establish connection after Rails initialization is complete
+    # This runs after all user initializers have loaded
+    config.after_initialize do
+      JetstreamBridge::Rails::Integration.boot_bridge!
+    end
+
+    # Add console helper methods
+    console do
+      ::Rails.logger.info "[JetStream Bridge] Loaded v#{JetstreamBridge::VERSION}"
+      ::Rails.logger.info '[JetStream Bridge] Console helpers available:'
+      ::Rails.logger.info '  JetstreamBridge.health_check     - Check connection status'
+      ::Rails.logger.info '  JetstreamBridge.stream_info      - View stream details'
+      ::Rails.logger.info '  JetstreamBridge.connected?       - Check if connected'
+      ::Rails.logger.info '  JetstreamBridge.shutdown!        - Gracefully disconnect'
+      ::Rails.logger.info '  JetstreamBridge.reconnect!       - Reconnect (useful after configuration changes)'
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path('../tasks/install.rake', __dir__)
+    end
+
+    # Add generators
+    generators do
+      require 'generators/jetstream_bridge/health_check/health_check_generator'
+    end
+  end
+end

data/lib/jetstream_bridge/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point for Rails-specific integration (lifecycle helpers + railtie)
+require_relative 'rails/integration'
+require_relative 'rails/railtie' if defined?(Rails::Railtie)

data/lib/jetstream_bridge/tasks/install.rake

@@ -85,7 +85,7 @@ namespace :jetstream_bridge do
     puts '[jetstream_bridge] Testing NATS connection...'
 
     begin
-      jts = JetstreamBridge.ensure_topology!
+      jts = JetstreamBridge.connect_and_ensure_stream!
       puts '✓ Successfully connected to NATS'
       puts '✓ JetStream is available'
       puts '✓ Stream topology ensured'

data/lib/jetstream_bridge/test_helpers/fixtures.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module TestHelpers
+    # Common fixtures for quickly building events in specs.
+    module Fixtures
+      module_function
+
+      # Build a user.created event
+      def user_created_event(attrs = {})
+        JetstreamBridge::TestHelpers.build_jetstream_event(
+          event_type: 'user.created',
+          payload: {
+            id: attrs[:id] || 1,
+            email: attrs[:email] || 'test@example.com',
+            name: attrs[:name] || 'Test User'
+          }.merge(attrs[:payload] || {})
+        )
+      end
+
+      # Build multiple sample events
+      def sample_events(count = 3, type: 'test.event')
+        Array.new(count) do |i|
+          JetstreamBridge::TestHelpers.build_jetstream_event(
+            event_type: type,
+            payload: { id: i + 1, sequence: i }
+          )
+        end
+      end
+
+      # Build a generic event with custom attributes
+      def event(event_type:, payload: {}, **attrs)
+        JetstreamBridge::TestHelpers.build_jetstream_event(
+          event_type: event_type,
+          payload: payload,
+          **attrs
+        )
+      end
+    end
+  end
+end