jetstream_bridge 4.0.3 → 4.1.0

data/lib/jetstream_bridge/test_helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative 'test_helpers/mock_nats'
 
 module JetstreamBridge
   # Test helpers for easier testing of JetStream Bridge integrations
@@ -34,13 +35,50 @@ module JetstreamBridge
   #
   module TestHelpers
     class << self
-      # Enable test mode with in-memory event capture
+      # Auto-configure test helpers when RSpec is detected
       #
+      # This method is called automatically when test_helpers.rb is required.
+      # It sets up RSpec configuration to enable test mode for tests tagged with :jetstream.
+      #
+      # @return [void]
+      def auto_configure!
+        return unless defined?(RSpec)
+        return if @configured
+
+        RSpec.configure do |config|
+          config.include JetstreamBridge::TestHelpers
+          config.include JetstreamBridge::TestHelpers::Matchers
+
+          config.before(:each, :jetstream) do
+            JetstreamBridge::TestHelpers.enable_test_mode!
+          end
+
+          config.after(:each, :jetstream) do
+            JetstreamBridge::TestHelpers.reset_test_mode!
+          end
+        end
+
+        @configured = true
+      end
+
+      # Check if auto-configuration has been applied
+      #
+      # @return [Boolean]
+      def configured?
+        @configured ||= false
+      end
+
+      # Enable test mode with in-memory event capture and mock NATS connection
+      #
+      # @param use_mock_nats [Boolean] Whether to use mock NATS connection (default: true)
       # @return [void]
-      def enable_test_mode!
+      def enable_test_mode!(use_mock_nats: true)
         @test_mode = true
         @published_events = []
         @consumed_events = []
+        @mock_nats_enabled = use_mock_nats
+
+        setup_mock_nats if use_mock_nats
       end
 
       # Reset test mode and clear captured events
@@ -50,6 +88,44 @@ module JetstreamBridge
         @test_mode = false
         @published_events = []
         @consumed_events = []
+
+        teardown_mock_nats if @mock_nats_enabled
+        @mock_nats_enabled = false
+      end
+
+      # Setup mock NATS connection
+      #
+      # @return [void]
+      def setup_mock_nats
+        MockNats.reset!
+        @mock_connection = MockNats.create_mock_connection
+        @mock_connection.connect
+
+        # Store the mock for Connection to use
+        JetstreamBridge.instance_variable_set(:@mock_nats_client, @mock_connection)
+      end
+
+      # Teardown mock NATS connection
+      #
+      # @return [void]
+      def teardown_mock_nats
+        MockNats.reset!
+        @mock_connection = nil
+        return unless JetstreamBridge.instance_variable_defined?(:@mock_nats_client)
+
+        JetstreamBridge.remove_instance_variable(:@mock_nats_client)
+      end
+
+      # Get the current mock connection
+      #
+      # @return [MockNats::MockConnection, nil]
+      attr_reader :mock_connection
+
+      # Get the mock storage for direct access in tests
+      #
+      # @return [MockNats::InMemoryStorage]
+      def mock_storage
+        MockNats.storage
       end
 
       # Check if test mode is enabled
@@ -271,5 +347,148 @@ module JetstreamBridge
         end
       end
     end
+
+    # Test fixtures for common event scenarios
+    #
+    # @example Create a user.created event
+    #   event = JetstreamBridge::TestHelpers::Fixtures.user_created_event(id: 123)
+    #
+    module Fixtures
+      # Build a user.created event
+      #
+      # @param attrs [Hash] Event attributes
+      # @option attrs [Integer] :id User ID
+      # @option attrs [String] :email User email
+      # @option attrs [String] :name User name
+      # @option attrs [Hash] :payload Additional payload data
+      # @return [Models::Event] Event object
+      def self.user_created_event(attrs = {})
+        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
+      #
+      # @param count [Integer] Number of events to create
+      # @param type [String] Event type
+      # @return [Array<Models::Event>] Array of event objects
+      def self.sample_events(count = 3, type: 'test.event')
+        Array.new(count) do |i|
+          build_jetstream_event(
+            event_type: type,
+            payload: { id: i + 1, sequence: i }
+          )
+        end
+      end
+
+      # Build a generic event with custom attributes
+      #
+      # @param event_type [String] Event type
+      # @param payload [Hash] Event payload
+      # @param attrs [Hash] Additional event attributes
+      # @return [Models::Event] Event object
+      def self.event(event_type:, payload: {}, **attrs)
+        build_jetstream_event(
+          event_type: event_type,
+          payload: payload,
+          **attrs
+        )
+      end
+
+      # Helper method to build events
+      # @private
+      def self.build_jetstream_event(event_type:, payload:, event_id: nil, trace_id: nil, occurred_at: nil, **metadata)
+        # Delegate to main module method to avoid duplication
+        TestHelpers.build_jetstream_event(
+          event_type: event_type,
+          payload: payload,
+          event_id: event_id,
+          trace_id: trace_id,
+          occurred_at: occurred_at,
+          **metadata
+        )
+      end
+    end
+
+    # Integration test helpers for end-to-end testing
+    module IntegrationHelpers
+      # Publish an event and wait for it to appear in mock storage
+      #
+      # @param event_attrs [Hash] Event attributes to publish
+      # @param timeout [Integer] Maximum seconds to wait
+      # @return [Models::PublishResult] Publish result
+      # @raise [Timeout::Error] If event doesn't appear within timeout
+      def publish_and_wait(event_attrs, timeout: 1)
+        result = JetstreamBridge.publish(**event_attrs)
+
+        deadline = Time.now + timeout
+        until Time.now > deadline
+          storage = JetstreamBridge::TestHelpers.mock_storage
+          break if storage.messages.any? { |m| m[:header]['nats-msg-id'] == result.event_id }
+
+          sleep 0.01
+        end
+
+        result
+      end
+
+      # Consume events from mock storage
+      #
+      # @param batch_size [Integer] Number of events to consume
+      # @yield [event] Block to handle each event
+      # @return [Array<Hash>] Consumed events
+      def consume_events(batch_size: 10, &handler)
+        storage = JetstreamBridge::TestHelpers.mock_storage
+        messages = storage.messages.first(batch_size)
+
+        messages.each do |msg|
+          event = JetstreamBridge::Models::Event.from_nats_message(
+            OpenStruct.new(
+              subject: msg[:subject],
+              data: msg[:data],
+              header: msg[:header],
+              metadata: OpenStruct.new(
+                sequence: OpenStruct.new(stream: msg[:sequence]),
+                num_delivered: msg[:delivery_count],
+                stream: 'test-stream',
+                consumer: 'test-consumer'
+              )
+            )
+          )
+
+          handler&.call(event)
+          JetstreamBridge::TestHelpers.record_consumed_event(event.to_h)
+        end
+
+        JetstreamBridge::TestHelpers.consumed_events
+      end
+
+      # Wait for a specific number of messages in mock storage
+      #
+      # @param count [Integer] Expected message count
+      # @param timeout [Integer] Maximum seconds to wait
+      # @return [Boolean] true if count reached, false if timeout
+      def wait_for_messages(count, timeout: 2)
+        deadline = Time.now + timeout
+        storage = JetstreamBridge::TestHelpers.mock_storage
+
+        until Time.now > deadline
+          return true if storage.messages.size >= count
+
+          sleep 0.01
+        end
+
+        false
+      end
+    end
   end
 end
+
+# Auto-configure when loaded (only if RSpec is available)
+JetstreamBridge::TestHelpers.auto_configure! if defined?(RSpec)

data/lib/jetstream_bridge/topology/overlap_guard.rb

@@ -7,6 +7,12 @@ require_relative '../core/logging'
 module JetstreamBridge
   # Checks for overlapping subjects.
   class OverlapGuard
+    # Cache for stream metadata to reduce N+1 API calls
+    @cache_mutex = Mutex.new
+    @stream_cache = {}
+    @cache_expires_at = Time.at(0)
+    CACHE_TTL = 60 # seconds
+
     class << self
       # Raise if any desired subjects conflict with other streams.
       def check!(jts, target_name, new_subjects)
@@ -46,9 +52,52 @@ module JetstreamBridge
       end
 
       def list_streams_with_subjects(jts)
+        # Use cached data if available and fresh
+        @cache_mutex.synchronize do
+          now = Time.now
+          if now < @cache_expires_at && @stream_cache.key?(:data)
+            Logging.debug(
+              'Using cached stream metadata',
+              tag: 'JetstreamBridge::OverlapGuard'
+            )
+            return @stream_cache[:data]
+          end
+
+          # Fetch fresh data
+          Logging.debug(
+            'Fetching fresh stream metadata from NATS',
+            tag: 'JetstreamBridge::OverlapGuard'
+          )
+          result = fetch_streams_uncached(jts)
+          @stream_cache = { data: result }
+          @cache_expires_at = now + CACHE_TTL
+          result
+        end
+      rescue StandardError => e
+        Logging.warn(
+          "Failed to fetch stream metadata: #{e.class} #{e.message}",
+          tag: 'JetstreamBridge::OverlapGuard'
+        )
+        # Return cached data on error if available, otherwise empty array
+        @cache_mutex.synchronize { @stream_cache[:data] || [] }
+      end
+
+      # Clear the cache (useful for testing)
+      def clear_cache!
+        @cache_mutex.synchronize do
+          @stream_cache = {}
+          @cache_expires_at = Time.at(0)
+        end
+      end
+
+      # Fetch stream metadata without caching (for internal use)
+      def fetch_streams_uncached(jts)
         list_stream_names(jts).map do |name|
           info = jts.stream_info(name)
-          { name: name, subjects: Array(info.config.subjects || []) }
+          # Handle both object-style and hash-style access for compatibility
+          config_data = info.config
+          subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
+          { name: name, subjects: Array(subjects || []) }
         end
       end
 

data/lib/jetstream_bridge/topology/stream.rb

@@ -127,28 +127,36 @@ module JetstreamBridge
       private
 
       def ensure_update(jts, name, info, desired_subjects)
-        existing = StreamSupport.normalize_subjects(info.config.subjects || [])
+        # Handle both object-style and hash-style access for compatibility
+        config_data = info.config
+        subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
+        existing = StreamSupport.normalize_subjects(subjects || [])
         to_add   = StreamSupport.missing_subjects(existing, desired_subjects)
 
         # Retention is immutable; if different, skip all updates to avoid 10052 error.
-        have_ret = info.config.retention.to_s.downcase
+        retention = config_data.respond_to?(:retention) ? config_data.retention : config_data[:retention]
+        have_ret = retention.to_s.downcase
         if have_ret != RETENTION
           StreamSupport.log_retention_mismatch(name, have: have_ret, want: RETENTION)
           return
         end
 
-        add_subjects(jts, name, existing, to_add) if to_add.any?
+        # Add subjects if needed and return (logging is handled in add_subjects)
+        if to_add.any?
+          add_subjects(jts, name, existing, to_add)
+          return
+        end
 
         # Storage can be updated; do it without passing retention.
-        have_storage = info.config.storage.to_s.downcase
+        storage = config_data.respond_to?(:storage) ? config_data.storage : config_data[:storage]
+        have_storage = storage.to_s.downcase
         if have_storage != STORAGE
           apply_update(jts, name, existing, storage: STORAGE)
           StreamSupport.log_config_updated(name, storage: STORAGE)
           return
         end
 
-        return if to_add.any?
-
+        # If we reach here, nothing was updated
         StreamSupport.log_already_covered(name)
       end
 

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '4.0.3'
+  VERSION = '4.1.0'
 end

data/lib/jetstream_bridge.rb

@@ -31,9 +31,10 @@ require_relative 'jetstream_bridge/models/outbox_event'
 # - Built-in health checks and monitoring
 # - Middleware support for cross-cutting concerns
 # - Rails integration with generators and migrations
+# - Graceful startup/shutdown lifecycle management
 #
 # @example Quick start
-#   # Configure
+#   # Configure (automatically starts connection)
 #   JetstreamBridge.configure do |config|
 #     config.nats_urls = "nats://localhost:4222"
 #     config.env = "development"
@@ -50,9 +51,13 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #   )
 #
 #   # Consume events
-#   JetstreamBridge.subscribe do |event|
+#   consumer = JetstreamBridge.subscribe do |event|
 #     puts "Received: #{event.type} - #{event.payload.to_h}"
-#   end.run!
+#   end
+#   consumer.run!
+#
+#   # Graceful shutdown
+#   at_exit { JetstreamBridge.shutdown! }
 #
 # @see Publisher For publishing events
 # @see Consumer For consuming events
@@ -65,14 +70,52 @@ module JetstreamBridge
       @config ||= Config.new
     end
 
-    def configure(overrides = {})
+    # Configure JetStream Bridge settings and establish connection
+    #
+    # This method sets configuration and immediately establishes a connection
+    # to NATS, providing fail-fast behavior during application startup.
+    # If NATS is unavailable, the application will fail to start.
+    #
+    # Set config.lazy_connect = true to defer connection until first use.
+    #
+    # @example Basic configuration
+    #   JetstreamBridge.configure do |config|
+    #     config.nats_urls = "nats://localhost:4222"
+    #     config.app_name = "my_app"
+    #     config.destination_app = "worker"
+    #   end
+    #
+    # @example With hash overrides
+    #   JetstreamBridge.configure(env: 'production', app_name: 'my_app')
+    #
+    # @example Lazy connection (defer until first use)
+    #   JetstreamBridge.configure do |config|
+    #     config.nats_urls = "nats://localhost:4222"
+    #     config.lazy_connect = true
+    #   end
+    #
+    # @param overrides [Hash] Configuration key-value pairs to set
+    # @yield [Config] Configuration object for block-based configuration
+    # @return [Config] The configured instance
+    # @raise [ConnectionError] If connection to NATS fails (unless lazy_connect is true)
+    def configure(overrides = {}, **extra_overrides)
+      # Merge extra keyword arguments into overrides hash
+      all_overrides = overrides.nil? ? extra_overrides : overrides.merge(extra_overrides)
+
       cfg = config
-      overrides.each { |k, v| assign!(cfg, k, v) } unless overrides.nil? || overrides.empty?
+      all_overrides.each { |k, v| assign!(cfg, k, v) } unless all_overrides.empty?
       yield(cfg) if block_given?
+
+      # Establish connection immediately for fail-fast behavior (unless lazy_connect is true)
+      startup! unless cfg.lazy_connect
+
       cfg
     end
 
-    # Configure with a preset
+    # Configure with a preset and establish connection
+    #
+    # This method applies a configuration preset and immediately establishes
+    # a connection to NATS, providing fail-fast behavior.
     #
     # @example
     #   JetstreamBridge.configure_for(:production) do |config|
@@ -84,6 +127,7 @@ module JetstreamBridge
     # @param preset [Symbol] Preset name (:development, :test, :production, etc.)
     # @yield [Config] Configuration object
     # @return [Config] Configured instance
+    # @raise [ConnectionError] If connection to NATS fails
     def configure_for(preset)
       configure do |cfg|
         cfg.apply_preset(preset)
@@ -93,6 +137,41 @@ module JetstreamBridge
 
     def reset!
       @config = nil
+      @connection_initialized = false
+    end
+
+    # Initialize the JetStream Bridge connection and topology
+    #
+    # This method is called automatically by `configure`, but can be called
+    # explicitly if needed. It's idempotent and safe to call multiple times.
+    #
+    # @return [void]
+    def startup!
+      return if @connection_initialized
+
+      Connection.connect!
+      @connection_initialized = true
+      Logging.info('JetStream Bridge started successfully', tag: 'JetstreamBridge')
+    end
+
+    # Gracefully shutdown the JetStream Bridge connection
+    #
+    # Closes the NATS connection and cleans up resources. Should be called
+    # during application shutdown (e.g., in at_exit or signal handlers).
+    #
+    # @return [void]
+    def shutdown!
+      return unless @connection_initialized
+
+      begin
+        nc = Connection.nc
+        nc&.close if nc&.connected?
+        Logging.info('JetStream Bridge shut down gracefully', tag: 'JetstreamBridge')
+      rescue StandardError => e
+        Logging.error("Error during shutdown: #{e.message}", tag: 'JetstreamBridge')
+      ensure
+        @connection_initialized = false
+      end
     end
 
     def use_outbox?
@@ -115,21 +194,56 @@ module JetstreamBridge
       Connection.jetstream
     end
 
-    # Health check for monitoring and readiness probes
+    # Active health check for monitoring and readiness probes
+    #
+    # Performs actual operations to verify system health:
+    # - Checks NATS connection (active: calls account_info API)
+    # - Verifies stream exists and is accessible (active: queries stream info)
+    # - Tests NATS round-trip communication (active: RTT measurement)
     #
+    # Rate Limiting: To prevent abuse, uncached health checks are limited to once every 5 seconds.
+    # Cached results (within 30s TTL) bypass this limit via Connection.instance.connected?.
+    #
+    # @param skip_cache [Boolean] Force fresh health check, bypass connection cache (rate limited)
     # @return [Hash] Health status including NATS connection, stream, and version
-    def health_check
+    # @raise [HealthCheckFailedError] If skip_cache requested too frequently
+    def health_check(skip_cache: false)
+      # Rate limit uncached requests to prevent abuse (max 1 per 5 seconds)
+      enforce_health_check_rate_limit! if skip_cache
+
+      start_time = Time.now
       conn_instance = Connection.instance
-      connected = conn_instance.connected?
+
+      # Active check: calls @jts.account_info internally
+      # Pass skip_cache to force fresh check if requested
+      connected = conn_instance.connected?(skip_cache: skip_cache)
       connected_at = conn_instance.connected_at
+      connection_state = conn_instance.state
+      last_error = conn_instance.last_reconnect_error
+      last_error_at = conn_instance.last_reconnect_error_at
+
+      # Active check: queries actual stream from NATS server
+      stream_info = connected ? fetch_stream_info : { exists: false, name: config.stream_name }
+
+      # Active check: measure NATS round-trip time
+      rtt_ms = measure_nats_rtt if connected
 
-      stream_info = fetch_stream_info if connected
+      health_check_duration_ms = ((Time.now - start_time) * 1000).round(2)
 
       {
         healthy: connected && stream_info&.fetch(:exists, false),
-        nats_connected: connected,
-        connected_at: connected_at&.iso8601,
+        connection: {
+          state: connection_state,
+          connected: connected,
+          connected_at: connected_at&.iso8601,
+          last_error: last_error&.message,
+          last_error_at: last_error_at&.iso8601
+        },
         stream: stream_info,
+        performance: {
+          nats_rtt_ms: rtt_ms,
+          health_check_duration_ms: health_check_duration_ms
+        },
         config: {
           env: config.env,
           app_name: config.app_name,
@@ -143,6 +257,10 @@ module JetstreamBridge
     rescue StandardError => e
       {
         healthy: false,
+        connection: {
+          state: :failed,
+          connected: false
+        },
         error: "#{e.class}: #{e.message}"
       }
     end
@@ -278,14 +396,38 @@ module JetstreamBridge
 
     private
 
+    # Enforce rate limit on uncached health checks to prevent abuse
+    # Max 1 uncached request per 5 seconds per process
+    def enforce_health_check_rate_limit!
+      @health_check_mutex ||= Mutex.new
+      @health_check_mutex.synchronize do
+        now = Time.now
+        if @last_uncached_health_check
+          time_since = now - @last_uncached_health_check
+          if time_since < 5
+            raise HealthCheckFailedError,
+                  "Health check rate limit exceeded. Please wait #{(5 - time_since).ceil} second(s)"
+          end
+        end
+        @last_uncached_health_check = now
+      end
+    end
+
     def fetch_stream_info
       jts = Connection.jetstream
       info = jts.stream_info(config.stream_name)
+
+      # Handle both object-style and hash-style access for compatibility
+      config_data = info.config
+      state_data = info.state
+      subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
+      messages = state_data.respond_to?(:messages) ? state_data.messages : state_data[:messages]
+
       {
         exists: true,
         name: config.stream_name,
-        subjects: info.config.subjects,
-        messages: info.state.messages
+        subjects: subjects,
+        messages: messages
       }
     rescue StandardError => e
       {
@@ -295,6 +437,20 @@ module JetstreamBridge
       }
     end
 
+    def measure_nats_rtt
+      # Measure round-trip time using NATS RTT method
+      nc = Connection.nc
+      start = Time.now
+      nc.rtt
+      ((Time.now - start) * 1000).round(2)
+    rescue StandardError => e
+      Logging.warn(
+        "Failed to measure NATS RTT: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge'
+      )
+      nil
+    end
+
     def assign!(cfg, key, val)
       setter = :"#{key}="
       raise ArgumentError, "Unknown configuration option: #{key}" unless cfg.respond_to?(setter)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 4.0.3
+  version: 4.1.0
 platform: ruby
 authors:
 - Mike Attara
@@ -68,16 +68,22 @@ dependencies:
   name: nats-pure
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: oj
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +158,7 @@ files:
 - lib/jetstream_bridge/railtie.rb
 - lib/jetstream_bridge/tasks/install.rake
 - lib/jetstream_bridge/test_helpers.rb
+- lib/jetstream_bridge/test_helpers/mock_nats.rb
 - lib/jetstream_bridge/topology/overlap_guard.rb
 - lib/jetstream_bridge/topology/stream.rb
 - lib/jetstream_bridge/topology/subject_matcher.rb