jetstream_bridge 4.4.0 → 4.5.0

data/lib/jetstream_bridge/core/health_checker.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative 'logging'
+
+module JetstreamBridge
+  # Health checking service for JetStream Bridge
+  #
+  # Responsible for:
+  # - Connection health monitoring
+  # - Stream information gathering
+  # - Performance metrics collection
+  # - Rate limiting health check requests
+  class HealthChecker
+    # Rate limit window for uncached health checks in seconds
+    RATE_LIMIT_WINDOW = 5
+
+    def initialize(connection_manager, config)
+      @connection_manager = connection_manager
+      @config = config
+      @rate_limiter_mutex = Mutex.new
+      @last_uncached_check = nil
+    end
+
+    # Perform comprehensive health check
+    #
+    # @param skip_cache [Boolean] Force fresh health check (rate limited)
+    # @return [Hash] Health status including connection, stream, performance, config, and version
+    def check(skip_cache: false)
+      enforce_rate_limit! if skip_cache
+
+      start_time = Time.now
+
+      connection_health = fetch_connection_health(skip_cache)
+      stream_info = fetch_stream_info if should_fetch_stream_info?(connection_health)
+      rtt_ms = measure_nats_rtt if should_measure_rtt?(connection_health)
+
+      health_check_duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+      {
+        healthy: overall_healthy?(connection_health, stream_info),
+        connection: connection_health,
+        stream: stream_info || default_stream_info,
+        performance: {
+          nats_rtt_ms: rtt_ms,
+          health_check_duration_ms: health_check_duration_ms
+        },
+        config: config_summary,
+        version: JetstreamBridge::VERSION
+      }
+    rescue StandardError => e
+      {
+        healthy: false,
+        connection: {
+          state: :failed,
+          connected: false
+        },
+        error: "#{e.class}: #{e.message}"
+      }
+    end
+
+    private
+
+    def enforce_rate_limit!
+      @rate_limiter_mutex.synchronize do
+        now = Time.now
+        if @last_uncached_check
+          time_since = now - @last_uncached_check
+          if time_since < RATE_LIMIT_WINDOW
+            raise HealthCheckFailedError,
+                  "Health check rate limit exceeded. Please wait #{(RATE_LIMIT_WINDOW - time_since).ceil} second(s)"
+          end
+        end
+        @last_uncached_check = now
+      end
+    end
+
+    def fetch_connection_health(skip_cache)
+      if @connection_manager
+        @connection_manager.health_check(skip_cache: skip_cache)
+      else
+        {
+          connected: false,
+          state: :disconnected,
+          connected_at: nil,
+          last_error: 'Not connected',
+          last_error_at: nil
+        }
+      end
+    end
+
+    def should_fetch_stream_info?(connection_health)
+      connection_health[:connected] && !@config.disable_js_api
+    end
+
+    def should_measure_rtt?(connection_health)
+      connection_health[:connected] && !@config.disable_js_api
+    end
+
+    def overall_healthy?(connection_health, stream_info)
+      return false unless connection_health[:connected]
+      return true if @config.disable_js_api
+
+      stream_info&.fetch(:exists, false) || false
+    end
+
+    def default_stream_info
+      { exists: nil, name: @config.stream_name }
+    end
+
+    def config_summary
+      {
+        app_name: @config.app_name,
+        destination_app: @config.destination_app,
+        use_outbox: @config.use_outbox,
+        use_inbox: @config.use_inbox,
+        use_dlq: @config.use_dlq,
+        disable_js_api: @config.disable_js_api
+      }
+    end
+
+    def fetch_stream_info
+      return nil unless @connection_manager
+
+      jts = @connection_manager.jetstream
+      return nil unless jts
+
+      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
+      return nil unless @connection_manager
+
+      nc = @connection_manager.nats_client
+      return nil unless nc
+
+      # Prefer native RTT API when available
+      if nc.respond_to?(:rtt)
+        rtt_value = normalize_ms(nc.rtt)
+        return rtt_value if rtt_value
+      end
+
+      # Fallback: measure ping/pong via flush
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      nc.flush(1)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      normalize_ms(duration)
+    rescue StandardError => e
+      Logging.warn(
+        "Failed to measure NATS RTT: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::HealthChecker'
+      )
+      nil
+    end
+
+    def normalize_ms(value)
+      return nil if value.nil?
+      return nil unless value.respond_to?(:to_f)
+
+      numeric = value.to_f
+      # Heuristic: sub-1 values are likely seconds; convert them to ms
+      ms = numeric < 1 ? numeric * 1000 : numeric
+      ms.round(2)
+    end
+  end
+end

data/lib/jetstream_bridge/core.rb

@@ -4,5 +4,3 @@
 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/facade.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative 'core/config'
+require_relative 'core/connection_manager'
+require_relative 'core/health_checker'
+require_relative 'core/logging'
+require_relative 'publisher/publisher'
+require_relative 'consumer/consumer'
+require_relative 'topology/topology'
+
+module JetstreamBridge
+  # Facade that coordinates all subsystems
+  #
+  # Responsible for:
+  # - Managing configuration
+  # - Managing connection lifecycle
+  # - Creating publishers and consumers
+  # - Delegating health checks
+  class Facade
+    attr_reader :config
+
+    def initialize
+      @config = Config.new
+      @connection_manager = nil
+      @publisher = nil
+      @health_checker = nil
+    end
+
+    # Configure JetStream Bridge
+    #
+    # @yield [Config] Configuration object
+    # @return [Config] The configured instance
+    def configure
+      yield(@config) if block_given?
+      @config
+    end
+
+    # Connect to NATS and ensure topology
+    #
+    # @return [void]
+    def connect!
+      ensure_connection_manager!
+      @connection_manager.connect!
+      Logging.info('JetStream Bridge connected successfully', tag: 'JetstreamBridge')
+    end
+
+    # Disconnect from NATS
+    #
+    # @return [void]
+    def disconnect!
+      return unless @connection_manager
+
+      @connection_manager.disconnect!
+      Logging.info('JetStream Bridge disconnected', tag: 'JetstreamBridge')
+    end
+
+    # Reconnect to NATS
+    #
+    # @return [void]
+    def reconnect!
+      Logging.info('Reconnecting to NATS...', tag: 'JetstreamBridge')
+      disconnect!
+      connect!
+    end
+
+    # Publish an event
+    #
+    # @param event_type [String] Event type
+    # @param payload [Hash] Event payload
+    # @param options [Hash] Additional options
+    # @return [Models::PublishResult] Result object
+    def publish(event_type:, payload:, **)
+      connect_if_needed!
+      publisher.publish(event_type: event_type, payload: payload, **)
+    end
+
+    # Publish a complete event envelope (advanced)
+    #
+    # @param envelope [Hash] Complete event envelope
+    # @param subject [String, nil] Optional subject override
+    # @return [Models::PublishResult] Result object
+    def publish_envelope(envelope, subject: nil)
+      connect_if_needed!
+      publisher.publish_envelope(envelope, subject: subject)
+    end
+
+    # Subscribe to events
+    #
+    # @param handler [Proc, #call, nil] Message handler
+    # @param options [Hash] Consumer options
+    # @yield [event] Optional block as handler
+    # @return [Consumer] Consumer instance
+    def subscribe(handler = nil, **, &block)
+      connect_if_needed!
+      create_consumer(handler || block, **)
+    end
+
+    # Check if connected to NATS
+    #
+    # @param skip_cache [Boolean] Force fresh check
+    # @return [Boolean] true if connected and healthy
+    def connected?(skip_cache: false)
+      return false unless @connection_manager
+
+      @connection_manager.connected?(skip_cache: skip_cache)
+    rescue StandardError
+      false
+    end
+
+    # Get comprehensive health status (unified method)
+    #
+    # Provides complete system health information including connection state,
+    # stream info, performance metrics, and configuration.
+    #
+    # Rate limited to prevent abuse (max 1 uncached check per 5 seconds).
+    #
+    # @param skip_cache [Boolean] Force fresh health check (rate limited)
+    # @return [Hash] Health status including NATS connection, stream, and version
+    #
+    # @example
+    #   health = facade.health
+    #   puts "Healthy: #{health[:healthy]}"
+    #   puts "Connected: #{health[:connection][:connected]}"
+    #   puts "Stream exists: #{health[:stream][:exists]}"
+    #   puts "RTT: #{health[:performance][:nats_rtt_ms]}ms"
+    def health(skip_cache: false)
+      health_checker.check(skip_cache: skip_cache)
+    end
+
+    # Backward compatibility: Alias for health method
+    #
+    # @deprecated Use {#health} instead
+    # @param skip_cache [Boolean] Force fresh health check
+    # @return [Hash] Health status
+    def health_check(skip_cache: false)
+      health(skip_cache: skip_cache)
+    end
+
+    # Check if system is healthy (convenience method)
+    #
+    # @return [Boolean] true if connected and stream exists (or JS API disabled)
+    #
+    # @example
+    #   if facade.healthy?
+    #     puts "System is healthy and ready"
+    #   end
+    def healthy?
+      health[:healthy]
+    rescue StandardError
+      false
+    end
+
+    # Get stream information
+    #
+    # @return [Hash] Stream information
+    def stream_info
+      health_checker.send(:fetch_stream_info)
+    end
+
+    private
+
+    def ensure_connection_manager!
+      return if @connection_manager
+
+      @config.validate!
+      @connection_manager = ConnectionManager.new(@config)
+    end
+
+    def connect_if_needed!
+      return if @connection_manager&.connected?
+
+      connect!
+    end
+
+    # Get or create publisher instance (cached)
+    def publisher
+      @publisher ||= begin
+        ensure_connection_manager!
+        Publisher.new(
+          connection: @connection_manager.jetstream,
+          config: @config
+        )
+      end
+    end
+
+    # Create a new consumer instance (not cached - each subscription is independent)
+    def create_consumer(handler, durable_name: nil, batch_size: nil)
+      ensure_connection_manager!
+      Consumer.new(
+        handler,
+        connection: @connection_manager.jetstream,
+        config: @config,
+        durable_name: durable_name,
+        batch_size: batch_size
+      )
+    end
+
+    # Get or create health checker instance (cached)
+    def health_checker
+      @health_checker ||= begin
+        # Try to ensure connection manager, but don't fail if config is invalid
+        # HealthChecker will handle the nil connection_manager gracefully
+        begin
+          ensure_connection_manager!
+        rescue ConfigurationError
+          # Config not valid yet, health checker will report as unhealthy
+        end
+        HealthChecker.new(@connection_manager, @config)
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/publisher/event_envelope_builder.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module JetstreamBridge
+  # Builds event envelopes for publishing
+  #
+  # Single responsibility: Convert event parameters into a valid envelope hash.
+  # All envelope construction logic is centralized here.
+  class EventEnvelopeBuilder
+    # Build an event envelope from parameters
+    #
+    # @param event_type [String] Event type (e.g., 'created', 'user.created')
+    # @param payload [Hash] Event payload data
+    # @param resource_type [String, nil] Resource type (inferred from event_type if nil)
+    # @param options [Hash] Optional envelope fields
+    # @option options [String] :event_id Custom event ID (auto-generated if not provided)
+    # @option options [String] :producer Producer name (defaults to app_name from config)
+    # @option options [String, Time] :occurred_at Event timestamp (defaults to current time)
+    # @option options [String] :trace_id Distributed trace ID (auto-generated if not provided)
+    # @option options [String] :resource_id Resource ID (extracted from payload if not provided)
+    # @option options [Integer] :schema_version Schema version (defaults to 1)
+    #
+    # @return [Hash] Complete event envelope
+    # @raise [ArgumentError] If required parameters are missing
+    def self.build(event_type:, payload:, resource_type: nil, **options)
+      new(event_type, payload, resource_type, options).build
+    end
+
+    def initialize(event_type, payload, resource_type, options)
+      @event_type = event_type.to_s
+      @payload = payload
+      @resource_type = resource_type
+      @options = options
+
+      validate_required!
+    end
+
+    def build
+      {
+        'event_id' => event_id,
+        'schema_version' => schema_version,
+        'event_type' => @event_type,
+        'producer' => producer,
+        'resource_type' => resource_type,
+        'resource_id' => resource_id,
+        'occurred_at' => occurred_at,
+        'trace_id' => trace_id,
+        'payload' => @payload
+      }
+    end
+
+    private
+
+    def validate_required!
+      raise ArgumentError, 'event_type is required' if @event_type.empty?
+      raise ArgumentError, 'payload is required' if @payload.nil?
+    end
+
+    def event_id
+      @options[:event_id] || SecureRandom.uuid
+    end
+
+    def schema_version
+      @options[:schema_version] || 1
+    end
+
+    def producer
+      @options[:producer] || JetstreamBridge.config.app_name
+    end
+
+    def resource_type
+      @resource_type || infer_resource_type || 'event'
+    end
+
+    def infer_resource_type
+      # Extract from "user.created" -> "user"
+      @event_type.split('.').first if @event_type.include?('.')
+    end
+
+    def resource_id
+      @options[:resource_id] || extract_resource_id_from_payload
+    end
+
+    def extract_resource_id_from_payload
+      return '' unless @payload.respond_to?(:[])
+
+      payload_normalized = @payload.transform_keys(&:to_s) if @payload.respond_to?(:transform_keys)
+      payload_normalized ||= @payload
+
+      (payload_normalized['id'] || payload_normalized[:id] ||
+       payload_normalized['resource_id'] || payload_normalized[:resource_id]).to_s
+    end
+
+    def occurred_at
+      value = @options[:occurred_at]
+      return Time.now.utc.iso8601 if value.nil?
+      return value.iso8601 if value.is_a?(Time)
+
+      Time.parse(value.to_s).iso8601
+    rescue ArgumentError
+      Time.now.utc.iso8601
+    end
+
+    def trace_id
+      @options[:trace_id] || SecureRandom.hex(8)
+    end
+  end
+end