jetstream_bridge 4.5.0 → 4.5.2

data/docs/TESTING.md

@@ -28,28 +28,31 @@ RSpec.describe MyService do
   include JetstreamBridge::TestHelpers::Matchers
 
   before do
-    # Reset state
+    # Reset singleton to ensure clean state
+    JetstreamBridge::Connection.instance_variable_set(:@singleton__instance__, nil)
     JetstreamBridge.reset!
 
     # Enable test mode - automatically sets up mock NATS
     JetstreamBridge::TestHelpers.enable_test_mode!
 
     JetstreamBridge.configure do |config|
+      config.stream_name = 'jetstream-bridge-stream'
       config.app_name = 'my_app'
       config.destination_app = 'worker'
-      config.stream_name = 'test-stream'
     end
 
-    # Setup mock stream
+    # Setup mock stream and stub topology
     mock_jts = JetstreamBridge::TestHelpers.mock_connection.jetstream
     mock_jts.add_stream(
-      name: 'test-stream',
-      subjects: ['my_app.sync.worker', 'worker.sync.my_app']
+      name: 'test-jetstream-bridge-stream',
+      subjects: ['test.>']
     )
+    allow(JetstreamBridge::Topology).to receive(:ensure!)
   end
 
   after do
     JetstreamBridge::TestHelpers.reset_test_mode!
+    JetstreamBridge::Connection.instance_variable_set(:@singleton__instance__, nil)
   end
 
   it 'publishes events through the full stack' do
@@ -263,20 +266,27 @@ end.to raise_error(NATS::JetStream::Error, 'consumer not found')
 ```ruby
 before do
   JetstreamBridge.reset!
-  JetstreamBridge::TestHelpers.enable_test_mode!
+
+  mock_conn = JetstreamBridge::TestHelpers::MockNats.create_mock_connection
+  mock_jts = mock_conn.jetstream
+
+  allow(NATS::IO::Client).to receive(:new).and_return(mock_conn)
+  allow(JetstreamBridge::Connection).to receive(:connect!).and_call_original
+
+  # Setup stream
+  mock_jts.add_stream(
+    name: 'test-jetstream-bridge-stream',
+    subjects: ['test.>']
+  )
+
+  # Allow topology check to succeed
+  allow(JetstreamBridge::Topology).to receive(:ensure!)
 
   JetstreamBridge.configure do |config|
+    config.stream_name = 'jetstream-bridge-stream'
     config.app_name = 'api'
     config.destination_app = 'worker'
-    config.stream_name = 'test-stream'
   end
-
-  # Setup mock stream
-  mock_jts = JetstreamBridge::TestHelpers.mock_connection.jetstream
-  mock_jts.add_stream(
-    name: 'test-stream',
-    subjects: ['api.sync.worker', 'worker.sync.api']
-  )
 end
 
 it 'publishes through JetstreamBridge' do
@@ -286,9 +296,9 @@ it 'publishes through JetstreamBridge' do
     payload: { id: 1, name: 'Test' }
   )
 
-  expect(result.success?).to be true
+  expect(result).to be_publish_success
   expect(result.event_id).to be_present
-  expect(result.subject).to eq('api.sync.worker')
+   expect(result.subject).to eq('api.sync.worker')
 
   # Verify in storage
   storage = JetstreamBridge::TestHelpers.mock_storage
@@ -296,11 +306,12 @@ it 'publishes through JetstreamBridge' do
 end
 ```
 
-### Full Consumer Flow
+### Full Consuming Flow
 
 ```ruby
-it 'consumes messages through JetstreamBridge' do
-  mock_jts = JetstreamBridge::TestHelpers.mock_connection.jetstream
+it 'consumes through JetstreamBridge' do
+  mock_conn = JetstreamBridge::TestHelpers.mock_connection
+  mock_jts = mock_conn.jetstream
 
   # Publish message to destination subject
   mock_jts.publish(
@@ -328,8 +339,8 @@ it 'consumes messages through JetstreamBridge' do
   # Mock subscription
   subscription = mock_jts.pull_subscribe(
     'worker.sync.api',
-    'api-workers',
-    stream: 'test-stream'
+    'test-consumer',
+    stream: 'test-jetstream-bridge-stream'
   )
 
   allow_any_instance_of(JetstreamBridge::SubscriptionManager)
@@ -380,7 +391,7 @@ storage.reset!
 3. **Test both success and failure paths**: Use the mock to simulate errors
 4. **Verify message content**: Check that envelopes are correctly formatted
 5. **Test idempotency**: Verify duplicate detection and redelivery behavior
-6. **Set stream_name**: Always configure `stream_name` in your tests
+6. **Mock topology setup**: Remember to stub `JetstreamBridge::Topology.ensure!`
 
 ## Examples
 

data/lib/generators/jetstream_bridge/health_check/health_check_generator.rb

@@ -41,12 +41,12 @@ module JetstreamBridge
             "connected_at": "2025-11-22T20:00:00Z",
             "stream": {
               "exists": true,
-              "name": "development-jetstream-bridge-stream",
-              "subjects": ["dev.app1.sync.app2"],
+              "name": "jetstream-bridge-stream",
+              "subjects": ["app1.sync.app2"],
               "messages": 42
             },
             "config": {
-              "env": "development",
+              "stream_name": "jetstream-bridge-stream",
               "app_name": "my_app",
               "destination_app": "other_app"
             },

data/lib/generators/jetstream_bridge/initializer/templates/jetstream_bridge.rb

@@ -13,6 +13,9 @@ JetstreamBridge.configure do |config|
   # NATS server URLs (comma-separated for cluster)
   config.nats_urls = ENV.fetch('NATS_URLS', 'nats://localhost:4222')
 
+  # Stream name (required) - managed separately from runtime credentials
+  config.stream_name = ENV.fetch('JETSTREAM_STREAM_NAME', 'jetstream-bridge-stream')
+
   # Application name (used in subject routing)
   config.app_name = ENV.fetch('APP_NAME', Rails.application.class.module_parent_name.underscore)
 

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -2,6 +2,7 @@
 
 require 'oj'
 require 'securerandom'
+require_relative '../core/connection'
 require_relative '../core/duration'
 require_relative '../core/logging'
 require_relative '../core/config'
@@ -9,7 +10,6 @@ require_relative '../core/model_utils'
 require_relative 'message_processor'
 require_relative 'subscription_manager'
 require_relative 'inbox/inbox_processor'
-require_relative 'health_monitor'
 
 module JetstreamBridge
   # Subscribes to destination subject and processes messages via a pull durable consumer.
@@ -48,14 +48,6 @@ module JetstreamBridge
     IDLE_SLEEP_SECS       = 0.05
     # Maximum sleep duration during idle periods (seconds)
     MAX_IDLE_BACKOFF_SECS = 1.0
-    # Maximum number of batches to drain during shutdown
-    MAX_DRAIN_BATCHES = 5
-    # Drain timeout per batch in seconds
-    DRAIN_BATCH_TIMEOUT = 1
-    # Minimum reconnect backoff in seconds
-    MIN_RECONNECT_BACKOFF = 0.1
-    # Maximum reconnect backoff in seconds
-    MAX_RECONNECT_BACKOFF = 30.0
 
     # Alias middleware classes for easier access
     MiddlewareChain = ConsumerMiddleware::MiddlewareChain
@@ -72,51 +64,60 @@ module JetstreamBridge
     # @return [MiddlewareChain] Middleware chain for processing
     attr_reader :middleware_chain
 
-    # Initialize a new Consumer instance with dependency injection.
+    # Initialize a new Consumer instance.
     #
     # @param handler [Proc, #call, nil] Message handler that processes events.
     #   Must respond to #call(event) or #call(event, subject, deliveries).
-    # @param connection [NATS::JetStream::JS] JetStream connection
-    # @param config [Config] Configuration instance
     # @param durable_name [String, nil] Optional durable consumer name override.
+    #   Defaults to config.durable_name.
     # @param batch_size [Integer, nil] Number of messages to fetch per batch.
+    #   Defaults to DEFAULT_BATCH_SIZE (25).
     # @yield [event] Optional block as handler. Receives Models::Event object.
     #
-    # @raise [ArgumentError] If required dependencies are missing
+    # @raise [ArgumentError] If neither handler nor block provided
+    # @raise [ArgumentError] If destination_app not configured
+    # @raise [ConnectionError] If unable to connect to NATS
     #
     # @example With proc handler
     #   handler = ->(event) { puts "Received: #{event.type}" }
-    #   consumer = JetstreamBridge::Consumer.new(handler, connection: jts, config: config)
+    #   consumer = JetstreamBridge::Consumer.new(handler)
     #
     # @example With block
-    #   consumer = JetstreamBridge::Consumer.new(connection: jts, config: config) do |event|
+    #   consumer = JetstreamBridge::Consumer.new do |event|
     #     UserEventHandler.process(event)
     #   end
     #
-    def initialize(handler = nil, connection:, config:, durable_name: nil, batch_size: nil, &block)
+    # @example With custom configuration
+    #   consumer = JetstreamBridge::Consumer.new(
+    #     handler,
+    #     durable_name: "my-consumer",
+    #     batch_size: 10
+    #   )
+    #
+    def initialize(handler = nil, durable_name: nil, batch_size: nil, &block)
       @handler = handler || block
       raise ArgumentError, 'handler or block required' unless @handler
-      raise ArgumentError, 'connection is required' unless connection
-      raise ArgumentError, 'config is required' unless config
-
-      @jts = connection
-      @config = config
 
       @batch_size    = Integer(batch_size || DEFAULT_BATCH_SIZE)
-      @durable       = durable_name || @config.durable_name
+      @durable       = durable_name || JetstreamBridge.config.durable_name
       @idle_backoff  = IDLE_SLEEP_SECS
       @reconnect_attempts = 0
       @running = true
       @shutdown_requested = false
+      @start_time    = Time.now
+      @iterations    = 0
+      @last_health_check = Time.now
+      # Use existing connection (should already be established)
+      @jts = Connection.jetstream
+      raise ConnectionError, 'JetStream connection not available. Call JetstreamBridge.startup! first.' unless @jts
 
       @middleware_chain = MiddlewareChain.new
-      @health_monitor = ConsumerHealthMonitor.new(@durable)
 
       ensure_destination_app_configured!
 
-      @sub_mgr = SubscriptionManager.new(@jts, @durable, @config)
+      @sub_mgr = SubscriptionManager.new(@jts, @durable, JetstreamBridge.config)
       @processor  = MessageProcessor.new(@jts, @handler, middleware_chain: @middleware_chain)
-      @inbox_proc = InboxProcessor.new(@processor) if @config.use_inbox
+      @inbox_proc = InboxProcessor.new(@processor) if JetstreamBridge.config.use_inbox
 
       ensure_subscription!
       setup_signal_handlers
@@ -192,15 +193,17 @@ module JetstreamBridge
     #
     def run!
       Logging.info(
-        "Consumer #{@durable} started (batch=#{@batch_size}, dest=#{@config.destination_subject})…",
+        "Consumer #{@durable} started (batch=#{@batch_size}, dest=#{JetstreamBridge.config.destination_subject})…",
         tag: 'JetstreamBridge::Consumer'
       )
       while @running
         processed = process_batch
         idle_sleep(processed)
 
-        @health_monitor.increment_iterations
-        @health_monitor.check_health_if_due
+        @iterations += 1
+
+        # Periodic health checks every 10 minutes (600 seconds)
+        perform_health_check_if_due
       end
 
       # Drain in-flight messages before exiting
@@ -241,17 +244,16 @@ module JetstreamBridge
 
     private
 
-    def ensure_destination_app_configured!
-      return unless @config.destination_app.to_s.empty?
-
-      raise ArgumentError, 'destination_app must be configured'
-    end
-
     def ensure_subscription!
-      @sub_mgr.ensure_consumer! unless @config.disable_js_api
+      @sub_mgr.ensure_consumer!
       @psub = @sub_mgr.subscribe!
     end
 
+    def ensure_destination_app_configured!
+      # Use subject builder to enforce required components and align with existing validation messages.
+      JetstreamBridge.config.destination_subject
+    end
+
     # Returns number of messages processed; 0 on timeout/idle or after recovery.
     def process_batch
       msgs = fetch_messages
@@ -311,8 +313,10 @@ module JetstreamBridge
     end
 
     def calculate_reconnect_backoff(attempt)
-      # Exponential backoff: 0.1s, 0.2s, 0.4s, 0.8s, 1.6s, ... up to max
-      [MIN_RECONNECT_BACKOFF * (2**(attempt - 1)), MAX_RECONNECT_BACKOFF].min
+      # Exponential backoff: 0.1s, 0.2s, 0.4s, 0.8s, 1.6s, ... up to 30s max
+      base_delay = 0.1
+      max_delay = 30.0
+      [base_delay * (2**(attempt - 1)), max_delay].min
     end
 
     def recoverable_consumer_error?(error)
@@ -352,13 +356,70 @@ module JetstreamBridge
       Logging.debug("Could not set up signal handlers: #{e.message}", tag: 'JetstreamBridge::Consumer')
     end
 
+    def perform_health_check_if_due
+      now = Time.now
+      time_since_check = now - @last_health_check
+
+      return unless time_since_check >= 600 # 10 minutes
+
+      @last_health_check = now
+      uptime = now - @start_time
+      memory_mb = memory_usage_mb
+
+      Logging.info(
+        "Consumer health: iterations=#{@iterations}, " \
+        "memory=#{memory_mb}MB, uptime=#{uptime.round}s",
+        tag: 'JetstreamBridge::Consumer'
+      )
+
+      # Warn if memory usage is high (over 1GB)
+      if memory_mb > 1000
+        Logging.warn(
+          "High memory usage detected: #{memory_mb}MB",
+          tag: 'JetstreamBridge::Consumer'
+        )
+      end
+
+      # Suggest GC if heap is growing significantly
+      suggest_gc_if_needed
+    rescue StandardError => e
+      Logging.debug(
+        "Health check failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Consumer'
+      )
+    end
+
+    def memory_usage_mb
+      # Get memory usage from OS (works on Linux/macOS)
+      rss_kb = `ps -o rss= -p #{Process.pid}`.to_i
+      rss_kb / 1024.0
+    rescue StandardError
+      0.0
+    end
+
+    def suggest_gc_if_needed
+      # Suggest GC if heap has many live slots (Ruby-specific optimization)
+      return unless defined?(GC) && GC.respond_to?(:stat)
+
+      stats = GC.stat
+      heap_live_slots = stats[:heap_live_slots] || stats['heap_live_slots'] || 0
+
+      # Suggest GC if we have over 100k live objects
+      GC.start if heap_live_slots > 100_000
+    rescue StandardError => e
+      Logging.debug(
+        "GC check failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Consumer'
+      )
+    end
+
     def drain_inflight_messages
       return unless @psub
 
       Logging.info('Draining in-flight messages...', tag: 'JetstreamBridge::Consumer')
       # Process any pending messages with a short timeout
-      MAX_DRAIN_BATCHES.times do
-        msgs = @psub.fetch(@batch_size, timeout: DRAIN_BATCH_TIMEOUT)
+      5.times do
+        msgs = @psub.fetch(@batch_size, timeout: 1)
         break if msgs.nil? || msgs.empty?
 
         msgs.each { |m| process_one(m) }

data/lib/jetstream_bridge/consumer/message_processor.rb

@@ -198,7 +198,7 @@ module JetstreamBridge
 
     def log_ack(result)
       ctx = result.ctx
-      Logging.debug(
+      Logging.info(
         "ACK event_id=#{ctx&.event_id} subject=#{ctx&.subject} seq=#{ctx&.seq} deliveries=#{ctx&.deliveries}",
         tag: 'JetstreamBridge::Consumer'
       )