jetstream_bridge 4.4.0 → 4.5.0

data/lib/jetstream_bridge/consumer/health_monitor.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative '../core/logging'
+
+module JetstreamBridge
+  # Health monitoring for Consumer instances
+  #
+  # Responsible for:
+  # - Periodic health checks
+  # - Memory usage monitoring
+  # - Heap object tracking
+  # - GC recommendations
+  class ConsumerHealthMonitor
+    # Health check interval in seconds (10 minutes)
+    HEALTH_CHECK_INTERVAL = 600
+    # Memory warning threshold in MB
+    MEMORY_WARNING_THRESHOLD_MB = 1000
+    # Heap object count warning threshold
+    HEAP_OBJECT_WARNING_THRESHOLD = 200_000
+
+    def initialize(consumer_name)
+      @consumer_name = consumer_name
+      @start_time = Time.now
+      @last_check = Time.now
+      @iterations = 0
+      @gc_warning_logged = false
+    end
+
+    # Increment iteration counter
+    def increment_iterations
+      @iterations += 1
+    end
+
+    # Check if health check is due and perform if needed
+    #
+    # @return [Boolean] true if check was performed
+    def check_health_if_due
+      now = Time.now
+      time_since_check = now - @last_check
+
+      return false unless time_since_check >= HEALTH_CHECK_INTERVAL
+
+      perform_check(now)
+      true
+    end
+
+    private
+
+    def perform_check(now)
+      @last_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(#{@consumer_name})"
+      )
+
+      warn_if_high_memory(memory_mb)
+      suggest_gc_if_needed
+    rescue StandardError => e
+      Logging.debug(
+        "Health check failed: #{e.class} #{e.message}",
+        tag: "JetstreamBridge::Consumer(#{@consumer_name})"
+      )
+    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 warn_if_high_memory(memory_mb)
+      return unless memory_mb > MEMORY_WARNING_THRESHOLD_MB
+
+      Logging.warn(
+        "High memory usage detected: #{memory_mb}MB",
+        tag: "JetstreamBridge::Consumer(#{@consumer_name})"
+      )
+    end
+
+    def suggest_gc_if_needed
+      return unless defined?(GC) && GC.respond_to?(:stat)
+
+      stats = GC.stat
+      heap_live_slots = stats[:heap_live_slots] || stats['heap_live_slots'] || 0
+
+      return if heap_live_slots < HEAP_OBJECT_WARNING_THRESHOLD || @gc_warning_logged
+
+      @gc_warning_logged = true
+      Logging.warn(
+        "High heap object count detected (#{heap_live_slots}); " \
+        'consider profiling or manual GC in the host app',
+        tag: "JetstreamBridge::Consumer(#{@consumer_name})"
+      )
+    rescue StandardError => e
+      Logging.debug(
+        "GC check failed: #{e.class} #{e.message}",
+        tag: "JetstreamBridge::Consumer(#{@consumer_name})"
+      )
+    end
+  end
+end

data/lib/jetstream_bridge/consumer/message_processor.rb

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

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -10,6 +10,8 @@ module JetstreamBridge
       @jts     = jts
       @durable = durable
       @cfg     = cfg
+      return if @cfg.disable_js_api
+
       @desired_cfg      = build_consumer_config(@durable, filter_subject)
       @desired_cfg_norm = normalize_consumer_config(@desired_cfg)
     end
@@ -27,6 +29,11 @@ module JetstreamBridge
     end
 
     def ensure_consumer!
+      if @cfg.disable_js_api
+        Logging.info("JS API disabled; assuming consumer #{@durable} exists", tag: 'JetstreamBridge::Consumer')
+        return
+      end
+
       info = consumer_info_or_nil
       return create_consumer! unless info
 
@@ -41,11 +48,17 @@ module JetstreamBridge
 
     # Bind a pull subscriber to the existing durable.
     def subscribe!
+      opts = { stream: stream_name }
+      if @cfg.disable_js_api
+        opts[:bind] = true
+      else
+        opts[:config] = desired_consumer_cfg
+      end
+
       @jts.pull_subscribe(
         filter_subject,
         @durable,
-        stream: stream_name,
-        config: desired_consumer_cfg
+        **opts
       )
     end
 
@@ -80,9 +93,9 @@ module JetstreamBridge
         ack_policy: 'explicit',
         deliver_policy: 'all',
         max_deliver: JetstreamBridge.config.max_deliver,
-        # JetStream expects seconds (the client multiplies by nanoseconds).
-        ack_wait: duration_to_seconds(JetstreamBridge.config.ack_wait),
-        backoff: Array(JetstreamBridge.config.backoff).map { |d| duration_to_seconds(d) }
+        # JetStream expects nanoseconds for ack_wait/backoff.
+        ack_wait: duration_to_nanos(JetstreamBridge.config.ack_wait),
+        backoff: Array(JetstreamBridge.config.backoff).map { |d| duration_to_nanos(d) }
       }
     end
 
@@ -94,8 +107,8 @@ module JetstreamBridge
         ack_policy: sval(cfg, :ack_policy), # string
         deliver_policy: sval(cfg, :deliver_policy), # string
         max_deliver: ival(cfg, :max_deliver), # integer
-        ack_wait_secs: d_secs(cfg, :ack_wait), # integer seconds
-        backoff_secs: darr_secs(cfg, :backoff) # array of integer seconds
+        ack_wait_nanos: nanos(cfg, :ack_wait),
+        backoff_nanos: nanos_arr(cfg, :backoff)
       }
     end
 
@@ -151,54 +164,58 @@ module JetstreamBridge
       v.to_i
     end
 
-    # Normalize duration-like field to **milliseconds** (Integer).
-    # Accepts:
-    # - Strings:"500ms""30s" "2m", "1h", "250us", "100ns"
-    # - Integers/Floats:
-    #     * Server may return large integers in **nanoseconds** → detect and convert.
-    #     * Otherwise, we delegate to Duration.to_millis (heuristic/explicit).
-    def d_secs(cfg, key)
+    # ---- duration coercion ----
+
+    def nanos(cfg, key)
       raw = get(cfg, key)
-      duration_to_seconds(raw)
+      duration_to_nanos(raw)
     end
 
-    # Normalize array of durations to integer milliseconds.
-    def darr_secs(cfg, key)
+    def nanos_arr(cfg, key)
       raw = get(cfg, key)
-      Array(raw).map { |d| duration_to_seconds(d) }
+      Array(raw).map { |d| duration_to_nanos(d) }
     end
 
-    # ---- duration coercion ----
-
-    def duration_to_seconds(val)
+    def duration_to_nanos(val)
       return nil if val.nil?
 
       case val
       when Integer
-        # Heuristic: extremely large integers are likely **nanoseconds** from server
-        # (e.g., 30s => 30_000_000_000 ns). Convert ns → seconds.
-        return (val / 1_000_000_000.0).round if val >= 1_000_000_000
+        # Heuristic: extremely large integers are likely already nanoseconds
+        return val if val >= 1_000_000_000 # >= 1s in nanos
 
-        # otherwise rely on Duration’s :auto heuristic (int <1000 => seconds, >=1000 => ms)
         millis = Duration.to_millis(val, default_unit: :auto)
-        seconds_from_millis(millis)
+        (millis * 1_000_000).to_i
       when Float
         millis = Duration.to_millis(val, default_unit: :auto)
-        seconds_from_millis(millis)
+        (millis * 1_000_000).to_i
       when String
-        # Strings include unit (ns/us/ms/s/m/h/d) handled by Duration
-        millis = Duration.to_millis(val) # default_unit ignored when unit given
-        seconds_from_millis(millis)
+        millis = Duration.to_millis(val) # unit-aware
+        (millis * 1_000_000).to_i
       else
-        return duration_to_seconds(val.to_f) if val.respond_to?(:to_f)
+        return duration_to_nanos(val.to_f) if val.respond_to?(:to_f)
 
         raise ArgumentError, "invalid duration: #{val.inspect}"
       end
     end
 
-    def seconds_from_millis(millis)
-      # Always round up to avoid zero-second waits when sub-second durations are provided.
-      [(millis / 1000.0).ceil, 1].max
+    # Legacy helper used in specs; kept for backward compatibility.
+    def duration_to_seconds(val)
+      return nil if val.nil?
+
+      case val
+      when Integer
+        return (val / 1_000_000_000.0).round if val >= 1_000_000_000 # nanoseconds
+        return val if val < 1000 # seconds
+
+        (val / 1000.0).round # milliseconds as integer
+      when Float
+        val
+      else
+        millis = Duration.to_millis(val, default_unit: :auto)
+        seconds = millis / 1000.0
+        seconds < 1 ? 1 : seconds.round(3)
+      end
     end
   end
 end

data/lib/jetstream_bridge/core/config.rb

@@ -11,7 +11,6 @@ module JetstreamBridge
   # @example Basic configuration
   #   JetstreamBridge.configure do |config|
   #     config.nats_urls = "nats://localhost:4222"
-  #     config.env = "production"
   #     config.app_name = "api_service"
   #     config.destination_app = "worker_service"
   #     config.use_outbox = true
@@ -50,11 +49,7 @@ module JetstreamBridge
     # NATS server URL(s)
     # @return [String]
     attr_accessor :nats_urls
-    # Environment namespace (development, staging, production)
-    # @return [String]
-    attr_accessor :env
     # Application name for subject routing
-    # @return [String]
     attr_accessor :app_name
     # Maximum delivery attempts before moving to DLQ
     # @return [Integer]
@@ -95,12 +90,23 @@ module JetstreamBridge
     # Enable lazy connection (connect on first use instead of during configure)
     # @return [Boolean]
     attr_accessor :lazy_connect
+    # Inbox prefix for request/reply (useful when NATS permissions restrict _INBOX.>)
+    # @return [String, nil]
+    attr_accessor :inbox_prefix
+    # Skip JetStream management API calls (account_info, stream ensure, etc.)
+    # Requires streams/consumers to be pre-provisioned and permissions handled externally.
+    # @return [Boolean]
+    attr_accessor :disable_js_api
+    # Optional durable consumer name
+    attr_writer :durable_name
 
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
-      @env             = ENV['NATS_ENV']  || 'development'
       @app_name        = ENV['APP_NAME']  || 'app'
       @destination_app = ENV.fetch('DESTINATION_APP', nil)
+      @stream_name     = ENV.fetch('STREAM_NAME', nil)
+      @stream_name_set = !@stream_name.nil?
+      @durable_name    = ENV.fetch('DURABLE_NAME', nil)
 
       @max_deliver = 5
       @ack_wait    = '30s'
@@ -118,6 +124,8 @@ module JetstreamBridge
       @connect_retry_attempts = 3
       @connect_retry_delay = 2
       @lazy_connect = false
+      @inbox_prefix = ENV['NATS_INBOX_PREFIX'] || '_INBOX'
+      @disable_js_api = (ENV['JETSTREAM_DISABLE_JS_API'] || 'true') == 'true'
     end
 
     # Apply a configuration preset
@@ -131,85 +139,83 @@ module JetstreamBridge
       self
     end
 
-    # Get the JetStream stream name for this environment.
+    # Get the JetStream stream name (required).
     #
-    # @return [String] Stream name in format "{env}-jetstream-bridge-stream"
-    # @example
-    #   config.env = "production"
-    #   config.stream_name  # => "production-jetstream-bridge-stream"
+    # Side-effect free query. Use validate! to ensure validity.
+    #
+    # @return [String, nil] Stream name
     def stream_name
-      "#{env}-jetstream-bridge-stream"
+      @cached_stream_name || (@stream_name_set ? @stream_name : default_stream_name)
     end
 
     # Get the NATS subject this application publishes to.
     #
-    # Producer publishes to:   {env}.{app}.sync.{dest}
-    # Consumer subscribes to:  {env}.{dest}.sync.{app}
+    # Producer publishes to:   {app}.sync.{dest}
+    # Consumer subscribes to:  {dest}.sync.{app}
+    #
+    # Side-effect free query. Use validate! to ensure validity.
     #
-    # @return [String] Source subject for publishing
-    # @raise [InvalidSubjectError] If components contain NATS wildcards
-    # @raise [MissingConfigurationError] If required components empty
+    # @return [String, nil] Source subject for publishing
     # @example
-    #   config.env = "production"
     #   config.app_name = "api"
     #   config.destination_app = "worker"
-    #   config.source_subject  # => "production.api.sync.worker"
+    #   config.source_subject  # => "api.sync.worker"
     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}"
+      @cached_source_subject || build_source_subject
     end
 
     # Get the NATS subject this application subscribes to.
     #
-    # @return [String] Destination subject for consuming
-    # @raise [InvalidSubjectError] If components contain NATS wildcards
-    # @raise [MissingConfigurationError] If required components empty
+    # Side-effect free query. Use validate! to ensure validity.
+    #
+    # @return [String, nil] Destination subject for consuming
     # @example
-    #   config.env = "production"
     #   config.app_name = "api"
     #   config.destination_app = "worker"
-    #   config.destination_subject  # => "production.worker.sync.api"
+    #   config.destination_subject  # => "worker.sync.api"
     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}"
+      @cached_destination_subject || build_destination_subject
     end
 
     # Get the dead letter queue subject for this application.
     #
     # Each app has its own DLQ for better isolation and monitoring.
     #
-    # @return [String] DLQ subject in format "{env}.{app_name}.sync.dlq"
-    # @raise [InvalidSubjectError] If components contain NATS wildcards
-    # @raise [MissingConfigurationError] If required components are empty
+    # Side-effect free query. Use validate! to ensure validity.
+    #
+    # @return [String, nil] DLQ subject in format "{app_name}.sync.dlq"
     # @example
-    #   config.env = "production"
     #   config.app_name = "api"
-    #   config.dlq_subject  # => "production.api.sync.dlq"
+    #   config.dlq_subject  # => "api.sync.dlq"
     def dlq_subject
-      validate_subject_component!(env, 'env')
-      validate_subject_component!(app_name, 'app_name')
-      "#{env}.#{app_name}.sync.dlq"
+      @cached_dlq_subject || build_dlq_subject
     end
 
     # Get the durable consumer name for this application.
     #
-    # @return [String] Durable name in format "{env}-{app_name}-workers"
+    # @return [String] Durable name in format "{app_name}-workers"
     # @example
-    #   config.env = "production"
     #   config.app_name = "api"
-    #   config.durable_name  # => "production-api-workers"
+    #   config.durable_name  # => "api-workers"
     def durable_name
-      "#{env}-#{app_name}-workers"
+      value = @durable_name
+      return "#{app_name}-workers" if value.to_s.strip.empty?
+
+      value
+    end
+
+    def stream_name=(value)
+      @stream_name_set = true
+      @stream_name = value
     end
 
     # Validate all configuration settings.
     #
     # Checks that required settings are present and valid. Raises errors
-    # for any invalid configuration.
+    # for any invalid configuration. Caches computed subjects after validation.
+    #
+    # This is a command method - performs validation and updates internal state.
+    # Call this once after configuration is complete.
     #
     # @return [true] If configuration is valid
     # @raise [ConfigurationError] If any validation fails
@@ -217,21 +223,122 @@ module JetstreamBridge
     #   config.validate!  # Raises if destination_app is missing
     def validate!
       errors = []
+
+      # Validate stream name
+      stream_val = @stream_name_set ? @stream_name : default_stream_name
+      if stream_val.to_s.strip.empty?
+        errors << 'stream_name is required'
+      else
+        begin
+          validate_stream_name!(stream_val)
+        rescue InvalidSubjectError => e
+          errors << e.message
+        end
+      end
+
+      # Validate required fields
       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?
+      errors << 'disable_js_api must be boolean' unless [true, false].include?(disable_js_api)
+
+      # Validate inbox prefix
+      begin
+        validate_inbox_prefix!(inbox_prefix)
+      rescue InvalidSubjectError => e
+        errors << e.message
+      end
+
+      # Validate subject components
+      begin
+        validate_subject_component!(app_name, 'app_name') unless app_name.to_s.strip.empty?
+        validate_subject_component!(destination_app, 'destination_app') unless destination_app.to_s.strip.empty?
+      rescue InvalidSubjectError, MissingConfigurationError => e
+        errors << e.message
+      end
 
       raise ConfigurationError, "Configuration errors: #{errors.join(', ')}" if errors.any?
 
+      # Cache computed values after successful validation
+      cache_computed_values!
+
       true
     end
 
     private
 
+    # Cache computed subjects after validation
+    def cache_computed_values!
+      @cached_stream_name = @stream_name_set ? @stream_name : default_stream_name
+      @cached_source_subject = build_source_subject
+      @cached_destination_subject = build_destination_subject
+      @cached_dlq_subject = build_dlq_subject
+    end
+
+    # Build source subject without side effects
+    def build_source_subject
+      build_subject(app_name, 'sync', destination_app)
+    end
+
+    # Build destination subject without side effects
+    def build_destination_subject
+      build_subject(destination_app, 'sync', app_name)
+    end
+
+    # Build DLQ subject without side effects
+    def build_dlq_subject
+      return nil if app_name.to_s.strip.empty?
+
+      build_subject(app_name, 'sync', 'dlq')
+    end
+
+    # Generic subject builder
+    #
+    # @param parts [Array<String>] Subject parts to join
+    # @return [String, nil] Built subject or nil if any required part is empty
+    def build_subject(*parts)
+      # Check if any required parts are empty
+      return nil if parts.any? { |p| p.to_s.strip.empty? }
+
+      parts.join('.')
+    end
+
+    def validate_inbox_prefix!(value)
+      str = value.to_s.strip
+      raise InvalidSubjectError, 'inbox_prefix cannot be empty' if str.empty?
+
+      # Disallow wildcards, spaces, or control characters in inbox prefix
+      return unless str.match?(/[*> \t\r\n\x00-\x1F\x7F]/)
+
+      raise InvalidSubjectError,
+            "inbox_prefix contains invalid characters (wildcards, spaces, or control chars): #{value.inspect}"
+    end
+
+    def validate_override!(name, value)
+      str = value.to_s.strip
+      raise InvalidSubjectError, "#{name} cannot be empty" if str.empty?
+      return unless str.match?(/[ \t\r\n\x00-\x1F\x7F]/)
+
+      raise InvalidSubjectError, "#{name} contains invalid whitespace/control characters: #{value.inspect}"
+    end
+
+    def validate_stream_name!(value)
+      str = value.to_s.strip
+      raise MissingConfigurationError, 'stream_name is required' if str.empty?
+
+      return unless str.match?(/[*> \t\r\n\x00-\x1F\x7F]/)
+
+      raise InvalidSubjectError,
+            "stream_name contains invalid characters (wildcards, whitespace, or control chars): #{value.inspect}"
+    end
+
+    def default_stream_name
+      nil
+    end
+
     def validate_subject_component!(value, name)
       str = value.to_s.strip
       raise MissingConfigurationError, "#{name} cannot be empty" if str.empty?