jetstream_bridge 4.0.4 → 4.2.0

data/lib/jetstream_bridge/test_helpers.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative 'test_helpers/mock_nats'
+require_relative 'test_helpers/matchers'
+require_relative 'test_helpers/fixtures'
+require_relative 'test_helpers/integration_helpers'
 
 module JetstreamBridge
   # Test helpers for easier testing of JetStream Bridge integrations
@@ -34,13 +38,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 +91,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
@@ -134,6 +213,7 @@ module JetstreamBridge
         }
       )
     end
+    module_function :build_jetstream_event
 
     # Simulate triggering an event to a consumer
     #
@@ -152,124 +232,8 @@ module JetstreamBridge
       TestHelpers.record_consumed_event(event.to_h) if TestHelpers.test_mode?
       handler.call(event)
     end
-
-    # RSpec matchers module
-    #
-    # @example Include in RSpec
-    #   RSpec.configure do |config|
-    #     config.include JetstreamBridge::TestHelpers
-    #     config.include JetstreamBridge::TestHelpers::Matchers
-    #   end
-    #
-    module Matchers
-      # Matcher for checking if an event was published
-      #
-      # @param event_type [String] Event type to match
-      # @param payload [Hash] Optional payload attributes to match
-      # @return [HavePublished] Matcher instance
-      #
-      # @example
-      #   expect(JetstreamBridge).to have_published(
-      #     event_type: "user.created",
-      #     payload: { id: 1 }
-      #   )
-      #
-      def have_published(event_type:, payload: {})
-        HavePublished.new(event_type, payload)
-      end
-
-      # Matcher implementation for have_published
-      class HavePublished
-        def initialize(event_type, payload_attributes)
-          @event_type = event_type
-          @payload_attributes = payload_attributes
-        end
-
-        def matches?(_actual)
-          TestHelpers.published_events.any? do |event|
-            matches_event_type?(event) && matches_payload?(event)
-          end
-        end
-
-        def failure_message
-          "expected to have published event_type: #{@event_type.inspect} " \
-            "with payload: #{@payload_attributes.inspect}\n" \
-            "but found events: #{TestHelpers.published_events.map { |e| e['event_type'] }.inspect}"
-        end
-
-        def failure_message_when_negated
-          "expected not to have published event_type: #{@event_type.inspect} " \
-            "with payload: #{@payload_attributes.inspect}"
-        end
-
-        private
-
-        def matches_event_type?(event)
-          event['event_type'] == @event_type || event[:event_type] == @event_type
-        end
-
-        def matches_payload?(event)
-          payload = event['payload'] || event[:payload] || {}
-          @payload_attributes.all? do |key, value|
-            payload_value = payload[key.to_s] || payload[key.to_sym]
-            if value.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
-              value.matches?(payload)
-            else
-              payload_value == value
-            end
-          end
-        end
-      end
-
-      # Matcher for checking publish result
-      #
-      # @example
-      #   result = JetstreamBridge.publish(...)
-      #   expect(result).to be_publish_success
-      #
-      def be_publish_success
-        BePublishSuccess.new
-      end
-
-      # Matcher implementation for be_publish_success
-      class BePublishSuccess
-        def matches?(actual)
-          actual.respond_to?(:success?) && actual.success?
-        end
-
-        def failure_message
-          'expected PublishResult to be successful but it failed'
-        end
-
-        def failure_message_when_negated
-          'expected PublishResult to not be successful but it was'
-        end
-      end
-
-      # Matcher for checking publish failure
-      #
-      # @example
-      #   result = JetstreamBridge.publish(...)
-      #   expect(result).to be_publish_failure
-      #
-      def be_publish_failure
-        BePublishFailure.new
-      end
-
-      # Matcher implementation for be_publish_failure
-      class BePublishFailure
-        def matches?(actual)
-          actual.respond_to?(:failure?) && actual.failure?
-        end
-
-        def failure_message
-          'expected PublishResult to be a failure but it succeeded'
-        end
-
-        def failure_message_when_negated
-          'expected PublishResult to not be a failure but it was'
-        end
-      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,6 +52,46 @@ 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)
           # Handle both object-style and hash-style access for compatibility

data/lib/jetstream_bridge/topology/stream.rb

@@ -79,7 +79,7 @@ module JetstreamBridge
     def log_retention_mismatch(name, have:, want:)
       Logging.warn(
         "Stream #{name} retention mismatch (have=#{have.inspect}, want=#{want.inspect}). " \
-        "Retention is immutable; skipping retention change.",
+        'Retention is immutable; skipping retention change.',
         tag: 'JetstreamBridge::Stream'
       )
     end
@@ -141,7 +141,11 @@ module JetstreamBridge
           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.
         storage = config_data.respond_to?(:storage) ? config_data.storage : config_data[:storage]
@@ -152,8 +156,7 @@ module JetstreamBridge
           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.4'
+  VERSION = '4.2.0'
 end

data/lib/jetstream_bridge.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'jetstream_bridge/version'
-require_relative 'jetstream_bridge/core/config'
-require_relative 'jetstream_bridge/core/duration'
-require_relative 'jetstream_bridge/core/logging'
-require_relative 'jetstream_bridge/core/connection'
+require_relative 'jetstream_bridge/core'
 require_relative 'jetstream_bridge/publisher/publisher'
 require_relative 'jetstream_bridge/publisher/batch_publisher'
 require_relative 'jetstream_bridge/consumer/consumer'
@@ -12,8 +9,8 @@ require_relative 'jetstream_bridge/consumer/middleware'
 require_relative 'jetstream_bridge/models/publish_result'
 require_relative 'jetstream_bridge/models/event'
 
-# If you have a Railtie for tasks/eager-loading
-require_relative 'jetstream_bridge/railtie' if defined?(Rails::Railtie)
+# Rails-specific entry point (lifecycle helpers + Railtie)
+require_relative 'jetstream_bridge/rails' if defined?(Rails::Railtie)
 
 # Load gem-provided models from lib/
 require_relative 'jetstream_bridge/models/inbox_event'
@@ -31,6 +28,7 @@ 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
@@ -43,6 +41,9 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #     config.use_inbox = true
 #   end
 #
+#   # Explicitly start connection (or use Rails railtie for automatic startup)
+#   JetstreamBridge.startup!
+#
 #   # Publish events
 #   JetstreamBridge.publish(
 #     event_type: "user.created",
@@ -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
@@ -61,25 +66,55 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #
 module JetstreamBridge
   class << self
+    include Core::BridgeHelpers
+
     def config
       @config ||= Config.new
     end
 
-    def configure(overrides = {})
+    # Configure JetStream Bridge settings
+    #
+    # This method sets configuration WITHOUT automatically establishing a connection.
+    # Connection must be established explicitly via startup! or will be established
+    # automatically on first use (publish/subscribe) or via Rails railtie initialization.
+    #
+    # @example Basic configuration
+    #   JetstreamBridge.configure do |config|
+    #     config.nats_urls = "nats://localhost:4222"
+    #     config.app_name = "my_app"
+    #     config.destination_app = "worker"
+    #   end
+    #   JetstreamBridge.startup!  # Explicitly start connection
+    #
+    # @example With hash overrides
+    #   JetstreamBridge.configure(env: 'production', app_name: 'my_app')
+    #
+    # @param overrides [Hash] Configuration key-value pairs to set
+    # @yield [Config] Configuration object for block-based configuration
+    # @return [Config] The configured instance
+    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_config_option!(cfg, k, v) } unless all_overrides.empty?
       yield(cfg) if block_given?
+
       cfg
     end
 
     # Configure with a preset
     #
+    # This method applies a configuration preset. Connection must be
+    # established separately via startup! or via Rails railtie.
+    #
     # @example
     #   JetstreamBridge.configure_for(:production) do |config|
     #     config.nats_urls = ENV["NATS_URLS"]
     #     config.app_name = "my_app"
     #     config.destination_app = "worker"
     #   end
+    #   JetstreamBridge.startup!  # Explicitly start connection
     #
     # @param preset [Symbol] Preset name (:development, :test, :production, etc.)
     # @yield [Config] Configuration object
@@ -93,6 +128,61 @@ 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
+
+    # Reconnect to NATS
+    #
+    # Closes existing connection and establishes a new one. Useful for:
+    # - Forking web servers (Puma, Unicorn) after worker boot
+    # - Recovering from connection issues
+    # - Configuration changes that require reconnection
+    #
+    # @example In Puma configuration (config/puma.rb)
+    #   on_worker_boot do
+    #     JetstreamBridge.reconnect! if defined?(JetstreamBridge)
+    #   end
+    #
+    # @return [void]
+    # @raise [ConnectionError] If unable to reconnect to NATS
+    def reconnect!
+      Logging.info('Reconnecting to NATS...', tag: 'JetstreamBridge')
+      shutdown! if @connection_initialized
+      startup!
+    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?
@@ -110,11 +200,16 @@ module JetstreamBridge
     # Establishes a connection and ensures stream topology.
     #
     # @return [Object] JetStream context
-    def ensure_topology!
+    def connect_and_ensure_stream!
       Connection.connect!
       Connection.jetstream
     end
 
+    # Backwards-compatible alias for the previous method name
+    def ensure_topology!
+      connect_and_ensure_stream!
+    end
+
     # Active health check for monitoring and readiness probes
     #
     # Performs actual operations to verify system health:
@@ -122,17 +217,29 @@ module JetstreamBridge
     # - 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
 
       # Active check: calls @jts.account_info internally
-      connected = conn_instance.connected?
+      # 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 = fetch_stream_info if connected
+      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
@@ -141,8 +248,13 @@ module JetstreamBridge
 
       {
         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,
@@ -161,6 +273,10 @@ module JetstreamBridge
     rescue StandardError => e
       {
         healthy: false,
+        connection: {
+          state: :failed,
+          connected: false
+        },
         error: "#{e.class}: #{e.message}"
       }
     end
@@ -183,6 +299,8 @@ module JetstreamBridge
 
     # Convenience method to publish events
     #
+    # Automatically establishes connection on first use if not already connected.
+    #
     # Supports three usage patterns:
     #
     # 1. Structured parameters (recommended):
@@ -210,6 +328,7 @@ module JetstreamBridge
     #     logger.error("Publish failed: #{result.error}")
     #   end
     def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **)
+      connect_if_needed!
       publisher = Publisher.new
       publisher.publish(event_or_hash, resource_type: resource_type, event_type: event_type, payload: payload,
                                        subject: subject, **)
@@ -254,6 +373,8 @@ module JetstreamBridge
 
     # Convenience method to start consuming messages
     #
+    # Automatically establishes connection on first use if not already connected.
+    #
     # Supports two usage patterns:
     #
     # 1. With a block (recommended):
@@ -280,6 +401,7 @@ module JetstreamBridge
     # @yield [event] Yields Models::Event object to block
     # @return [Consumer, Thread] Consumer instance or Thread if run: true
     def subscribe(handler = nil, run: false, durable_name: nil, batch_size: nil, &block)
+      connect_if_needed!
       handler ||= block
       raise ArgumentError, 'Handler or block required' unless handler
 
@@ -293,52 +415,5 @@ module JetstreamBridge
         consumer
       end
     end
-
-    private
-
-    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: subjects,
-        messages: messages
-      }
-    rescue StandardError => e
-      {
-        exists: false,
-        name: config.stream_name,
-        error: "#{e.class}: #{e.message}"
-      }
-    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)
-
-      cfg.public_send(setter, val)
-    end
   end
 end