jetstream_bridge 4.1.0 → 4.3.0

data/lib/jetstream_bridge/consumer/message_processor.rb

@@ -50,6 +50,7 @@ module JetstreamBridge
   # Orchestrates parse → handler → ack/nak → DLQ
   class MessageProcessor
     UNRECOVERABLE_ERRORS = [ArgumentError, TypeError].freeze
+    ActionResult = Struct.new(:action, :ctx, :error, :delay, keyword_init: true)
 
     attr_reader :middleware_chain
 
@@ -61,12 +62,15 @@ module JetstreamBridge
       @middleware_chain = middleware_chain || ConsumerMiddleware::MiddlewareChain.new
     end
 
-    def handle_message(msg)
-      ctx   = MessageContext.build(msg)
-      event = parse_message(msg, ctx)
-      return unless event
+    def handle_message(msg, auto_ack: true)
+      ctx = MessageContext.build(msg)
+      event, early_action = parse_message(msg, ctx)
+      return apply_action(msg, early_action) if early_action && auto_ack
+      return early_action if early_action
 
-      process_event(msg, event, ctx)
+      result = process_event(msg, event, ctx)
+      apply_action(msg, result) if auto_ack
+      result
     rescue StandardError => e
       backtrace = e.backtrace&.first(5)&.join("\n  ")
       Logging.error(
@@ -74,32 +78,35 @@ module JetstreamBridge
         "deliveries=#{ctx&.deliveries} err=#{e.class}: #{e.message}\n  #{backtrace}",
         tag: 'JetstreamBridge::Consumer'
       )
-      safe_nak(msg, ctx, e)
+      action = ActionResult.new(action: :nak, ctx: ctx, error: e)
+      apply_action(msg, action) if auto_ack
+      action
     end
 
     private
 
     def parse_message(msg, ctx)
       data = msg.data
-      Oj.load(data, mode: :strict)
+      [Oj.load(data, mode: :strict), nil]
     rescue Oj::ParseError => e
       dlq_success = @dlq.publish(msg, ctx,
                                  reason: 'malformed_json', error_class: e.class.name, error_message: e.message)
-      if dlq_success
-        msg.ack
-        Logging.warn(
-          "Malformed JSON → DLQ event_id=#{ctx.event_id} subject=#{ctx.subject} " \
-          "seq=#{ctx.seq} deliveries=#{ctx.deliveries}: #{e.message}",
-          tag: 'JetstreamBridge::Consumer'
-        )
-      else
-        safe_nak(msg, ctx, e)
-        Logging.error(
-          "Malformed JSON, DLQ publish failed, NAKing event_id=#{ctx.event_id}",
-          tag: 'JetstreamBridge::Consumer'
-        )
-      end
-      nil
+      action = if dlq_success
+                 Logging.warn(
+                   "Malformed JSON → DLQ event_id=#{ctx.event_id} subject=#{ctx.subject} " \
+                   "seq=#{ctx.seq} deliveries=#{ctx.deliveries}: #{e.message}",
+                   tag: 'JetstreamBridge::Consumer'
+                 )
+                 ActionResult.new(action: :ack, ctx: ctx)
+               else
+                 Logging.error(
+                   "Malformed JSON, DLQ publish failed, NAKing event_id=#{ctx.event_id}",
+                   tag: 'JetstreamBridge::Consumer'
+                 )
+                 ActionResult.new(action: :nak, ctx: ctx, error: e,
+                                  delay: backoff_delay(ctx, e))
+               end
+      [nil, action]
     end
 
     def process_event(msg, event_hash, ctx)
@@ -113,33 +120,14 @@ module JetstreamBridge
         call_handler(event, event_hash, ctx)
       end
 
-      msg.ack
-      Logging.info(
-        "ACK event_id=#{ctx.event_id} subject=#{ctx.subject} seq=#{ctx.seq} deliveries=#{ctx.deliveries}",
-        tag: 'JetstreamBridge::Consumer'
-      )
+      ActionResult.new(action: :ack, ctx: ctx)
     rescue *UNRECOVERABLE_ERRORS => e
-      dlq_success = @dlq.publish(msg, ctx,
-                                 reason: 'unrecoverable', error_class: e.class.name, error_message: e.message)
-      if dlq_success
-        msg.ack
-        Logging.warn(
-          "DLQ (unrecoverable) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
-          "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{e.class}: #{e.message}",
-          tag: 'JetstreamBridge::Consumer'
-        )
-      else
-        safe_nak(msg, ctx, e)
-        Logging.error(
-          "Unrecoverable error, DLQ publish failed, NAKing event_id=#{ctx.event_id}",
-          tag: 'JetstreamBridge::Consumer'
-        )
-      end
+      dlq_action(msg, ctx, e, reason: 'unrecoverable')
     rescue StandardError => e
-      ack_or_nak(msg, ctx, e)
+      ack_or_nak_action(msg, ctx, e)
     end
 
-    def ack_or_nak(msg, ctx, error)
+    def ack_or_nak_action(msg, ctx, error)
       max_deliver = JetstreamBridge.config.max_deliver.to_i
       if ctx.deliveries >= max_deliver
         # Only ACK if DLQ publish succeeds
@@ -149,36 +137,78 @@ module JetstreamBridge
                                    error_message: error.message)
 
         if dlq_success
-          msg.ack
           Logging.warn(
             "DLQ (max_deliver) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
             "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{error.class}: #{error.message}",
             tag: 'JetstreamBridge::Consumer'
           )
+          ActionResult.new(action: :ack, ctx: ctx)
         else
-          # NAK to retry DLQ publish
-          safe_nak(msg, ctx, error)
           Logging.error(
             "DLQ publish failed at max_deliver, NAKing event_id=#{ctx.event_id} " \
             "seq=#{ctx.seq} deliveries=#{ctx.deliveries}",
             tag: 'JetstreamBridge::Consumer'
           )
+          ActionResult.new(action: :nak, ctx: ctx, error: error,
+                           delay: backoff_delay(ctx, error))
         end
       else
-        safe_nak(msg, ctx, error)
         Logging.warn(
           "NAK event_id=#{ctx.event_id} subject=#{ctx.subject} seq=#{ctx.seq} " \
           "deliveries=#{ctx.deliveries} err=#{error.class}: #{error.message}",
           tag: 'JetstreamBridge::Consumer'
         )
+        ActionResult.new(action: :nak, ctx: ctx, error: error,
+                         delay: backoff_delay(ctx, error))
       end
     end
 
-    def safe_nak(msg, ctx = nil, error = nil)
+    def dlq_action(msg, ctx, error, reason:)
+      dlq_success = @dlq.publish(msg, ctx,
+                                 reason: reason, error_class: error.class.name, error_message: error.message)
+      if dlq_success
+        Logging.warn(
+          "DLQ (#{reason}) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
+          "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{error.class}: #{error.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        ActionResult.new(action: :ack, ctx: ctx)
+      else
+        Logging.error(
+          "DLQ publish failed (#{reason}), NAKing event_id=#{ctx.event_id}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        ActionResult.new(action: :nak, ctx: ctx, error: error,
+                         delay: backoff_delay(ctx, error))
+      end
+    end
+
+    def apply_action(msg, action_result)
+      return unless action_result
+
+      case action_result.action
+      when :ack
+        msg.ack
+        log_ack(action_result)
+      when :nak
+        safe_nak(msg, action_result.ctx, action_result.error, delay: action_result.delay)
+      end
+      action_result
+    end
+
+    def log_ack(result)
+      ctx = result.ctx
+      Logging.info(
+        "ACK event_id=#{ctx&.event_id} subject=#{ctx&.subject} seq=#{ctx&.seq} deliveries=#{ctx&.deliveries}",
+        tag: 'JetstreamBridge::Consumer'
+      )
+    end
+
+    def safe_nak(msg, ctx = nil, error = nil, delay: nil)
       # Use backoff strategy with error context if available
       if ctx && error && msg.respond_to?(:nak_with_delay)
-        delay = @backoff.delay(ctx.deliveries.to_i, error)
-        msg.nak_with_delay(delay)
+        nak_delay = delay || @backoff.delay(ctx.deliveries.to_i, error)
+        msg.nak_with_delay(nak_delay)
       else
         msg.nak
       end
@@ -209,5 +239,11 @@ module JetstreamBridge
     def call_handler(event, _event_hash, _ctx)
       @handler.call(event)
     end
+
+    def backoff_delay(ctx, error)
+      return nil unless ctx && error
+
+      @backoff.delay(ctx.deliveries.to_i, error)
+    end
   end
 end

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -80,8 +80,9 @@ module JetstreamBridge
         ack_policy: 'explicit',
         deliver_policy: 'all',
         max_deliver: JetstreamBridge.config.max_deliver,
-        ack_wait: Duration.to_millis(JetstreamBridge.config.ack_wait),
-        backoff: Array(JetstreamBridge.config.backoff).map { |d| Duration.to_millis(d) }
+        # 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) }
       }
     end
 
@@ -93,8 +94,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: d_ms(cfg, :ack_wait), # integer ms
-        backoff_ms: darr_ms(cfg, :backoff) # array of integer ms
+        ack_wait_secs: d_secs(cfg, :ack_wait), # integer seconds
+        backoff_secs: darr_secs(cfg, :backoff) # array of integer seconds
       }
     end
 
@@ -156,40 +157,48 @@ module JetstreamBridge
     # - Integers/Floats:
     #     * Server may return large integers in **nanoseconds** → detect and convert.
     #     * Otherwise, we delegate to Duration.to_millis (heuristic/explicit).
-    def d_ms(cfg, key)
+    def d_secs(cfg, key)
       raw = get(cfg, key)
-      duration_to_ms(raw)
+      duration_to_seconds(raw)
     end
 
     # Normalize array of durations to integer milliseconds.
-    def darr_ms(cfg, key)
+    def darr_secs(cfg, key)
       raw = get(cfg, key)
-      Array(raw).map { |d| duration_to_ms(d) }
+      Array(raw).map { |d| duration_to_seconds(d) }
     end
 
     # ---- duration coercion ----
 
-    def duration_to_ms(val)
+    def duration_to_seconds(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 → ms.
-        return (val / 1_000_000.0).round if val >= 1_000_000_000
+        # (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
 
         # otherwise rely on Duration’s :auto heuristic (int <1000 => seconds, >=1000 => ms)
-        Duration.to_millis(val, default_unit: :auto)
+        millis = Duration.to_millis(val, default_unit: :auto)
+        seconds_from_millis(millis)
       when Float
-        Duration.to_millis(val, default_unit: :auto) # treated as seconds
+        millis = Duration.to_millis(val, default_unit: :auto)
+        seconds_from_millis(millis)
       when String
         # Strings include unit (ns/us/ms/s/m/h/d) handled by Duration
-        Duration.to_millis(val) # default_unit ignored when unit given
+        millis = Duration.to_millis(val) # default_unit ignored when unit given
+        seconds_from_millis(millis)
       else
-        return Duration.to_millis(val.to_f, default_unit: :auto) if val.respond_to?(:to_f)
+        return duration_to_seconds(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
+    end
   end
 end

data/lib/jetstream_bridge/core/bridge_helpers.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'logging'
+require_relative 'connection'
+
+module JetstreamBridge
+  module Core
+    # Internal helper methods extracted from the main JetstreamBridge module
+    # to keep the public API surface focused.
+    module BridgeHelpers
+      private
+
+      # Ensure connection is established before use
+      # Automatically connects on first use if not already connected
+      # Thread-safe and idempotent
+      def connect_if_needed!
+        return if @connection_initialized
+
+        startup!
+      end
+
+      # 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
+        # Ensure we have an active connection before querying stream info
+        connect_if_needed!
+
+        jts = Connection.jetstream
+        raise ConnectionNotEstablishedError, 'NATS connection not established' 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
+        # 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_config_option!(cfg, key, val)
+        setter = :"#{key}="
+        raise ArgumentError, "Unknown configuration option: #{key}" unless cfg.respond_to?(setter)
+
+        cfg.public_send(setter, val)
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/core/connection.rb

@@ -97,6 +97,7 @@ module JetstreamBridge
       @jts
     rescue StandardError
       @state = State::FAILED
+      cleanup_connection!
       raise
     end
 
@@ -134,6 +135,9 @@ module JetstreamBridge
     # @return [Time, nil] timestamp when connection was established
     attr_reader :connected_at
 
+    # Last reconnection error metadata (exposed for health checks/diagnostics)
+    attr_reader :last_reconnect_error, :last_reconnect_error_at
+
     # Get current connection state
     #
     # @return [Symbol] Current connection state (see State module)
@@ -193,6 +197,7 @@ module JetstreamBridge
             "Failed to establish connection after #{attempts} attempts",
             tag: 'JetstreamBridge::Connection'
           )
+          cleanup_connection!
           raise
         end
       end
@@ -416,7 +421,7 @@ module JetstreamBridge
       @last_reconnect_error = e
       @last_reconnect_error_at = Time.now
       @state = State::FAILED
-
+      cleanup_connection!(close_nc: false)
       Logging.error(
         "Failed to refresh JetStream context: #{e.class} #{e.message}",
         tag: 'JetstreamBridge::Connection'
@@ -427,10 +432,6 @@ module JetstreamBridge
       @last_health_check = Time.now.to_i
     end
 
-    # Get last reconnection error for diagnostics
-    # @return [StandardError, nil] Last error during reconnection
-    attr_reader :last_reconnect_error, :last_reconnect_error_at
-
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc
 
@@ -444,5 +445,20 @@ module JetstreamBridge
     def sanitize_urls(urls)
       urls.map { |u| Logging.sanitize_url(u) }
     end
+
+    def cleanup_connection!(close_nc: true)
+      begin
+        # Avoid touching RSpec doubles used in unit tests
+        is_rspec_double = defined?(RSpec::Mocks::Double) && @nc.is_a?(RSpec::Mocks::Double)
+        @nc.close if !is_rspec_double && close_nc && @nc.respond_to?(:close) && @nc.connected?
+      rescue StandardError
+        # ignore cleanup errors
+      end
+      @nc = nil
+      @jts = nil
+      @cached_health_status = nil
+      @last_health_check = nil
+      @connected_at = nil
+    end
   end
 end

data/lib/jetstream_bridge/core.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Core building blocks for JetstreamBridge
+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/models/inbox_event.rb

@@ -174,8 +174,8 @@ module JetstreamBridge
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_inbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_inbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end

data/lib/jetstream_bridge/models/outbox_event.rb

@@ -169,8 +169,8 @@ module JetstreamBridge
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_outbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_outbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -36,14 +36,16 @@ module JetstreamBridge
   class Publisher
     # Initialize a new Publisher instance.
     #
-    # Note: The NATS connection should already be established via JetstreamBridge.configure.
-    # If not, this will attempt to connect, but it's recommended to call configure first.
+    # Note: The NATS connection should already be established via JetstreamBridge.startup!
+    # or automatically on first use. This assumes the connection is already established.
     #
     # @param retry_strategy [RetryStrategy, nil] Optional custom retry strategy for handling transient failures.
     #   Defaults to PublisherRetryStrategy with exponential backoff.
-    # @raise [ConnectionError] If unable to connect to NATS server
+    # @raise [ConnectionError] If unable to get JetStream connection
     def initialize(retry_strategy: nil)
-      @jts = Connection.jetstream || Connection.connect!
+      @jts = Connection.jetstream
+      raise ConnectionError, 'JetStream connection not available. Call JetstreamBridge.startup! first.' unless @jts
+
       @retry_strategy = retry_strategy || PublisherRetryStrategy.new
     end
 
@@ -106,7 +108,7 @@ module JetstreamBridge
     #   end
     #
     def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **options)
-      ensure_destination!
+      ensure_destination_app_configured!
 
       params = { event_or_hash: event_or_hash, resource_type: resource_type, event_type: event_type,
                  payload: payload, subject: subject, options: options }
@@ -189,7 +191,7 @@ module JetstreamBridge
       normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
     end
 
-    def ensure_destination!
+    def ensure_destination_app_configured!
       return unless JetstreamBridge.config.destination_app.to_s.empty?
 
       raise ArgumentError, 'destination_app must be configured'

data/lib/jetstream_bridge/rails/integration.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative '../core/model_codec_setup'
+require_relative '../core/logging'
+require_relative '../core/connection'
+
+module JetstreamBridge
+  module Rails
+    # Rails-specific lifecycle helpers for JetStream Bridge.
+    #
+    # Keeps the Railtie thin and makes lifecycle decisions easy to test and reason about.
+    module Integration
+      module_function
+
+      # Configure logger to use Rails.logger when available.
+      def configure_logger!
+        JetstreamBridge.configure do |config|
+          config.logger ||= ::Rails.logger if defined?(::Rails.logger)
+        end
+      end
+
+      # Attach ActiveRecord hooks for serializer setup on reload.
+      def attach_active_record_hooks!
+        ActiveSupport.on_load(:active_record) do
+          ActiveSupport::Reloader.to_prepare { JetstreamBridge::ModelCodecSetup.apply! }
+        end
+      end
+
+      # Validate config, enable test mode if appropriate, and start the bridge unless auto-start is disabled.
+      def boot_bridge!
+        auto_enable_test_mode!
+
+        if autostart_disabled?
+          message = "Auto-start skipped (reason: #{autostart_skip_reason}; " \
+                    'enable via lazy_connect=false, unset JETSTREAM_BRIDGE_DISABLE_AUTOSTART, ' \
+                    'or set JETSTREAM_BRIDGE_FORCE_AUTOSTART=1)'
+          Logging.info(message, tag: 'JetstreamBridge::Railtie')
+          return
+        end
+
+        JetstreamBridge.config.validate!
+        JetstreamBridge.startup!
+        log_started!
+        log_development_connection_details! if rails_development?
+        register_shutdown_hook!
+      end
+
+      # Auto-enable test mode in test environment when NATS is not configured.
+      def auto_enable_test_mode!
+        return unless auto_enable_test_mode?
+
+        Logging.info(
+          '[JetStream Bridge] Auto-enabling test mode (NATS_URLS not set)',
+          tag: 'JetstreamBridge::Railtie'
+        )
+
+        require_relative '../test_helpers'
+        JetstreamBridge::TestHelpers.enable_test_mode!
+      end
+
+      def auto_enable_test_mode?
+        rails_test? &&
+          ENV['NATS_URLS'].to_s.strip.empty? &&
+          !(defined?(JetstreamBridge::TestHelpers) &&
+            JetstreamBridge::TestHelpers.respond_to?(:test_mode?) &&
+            JetstreamBridge::TestHelpers.test_mode?)
+      end
+
+      def autostart_disabled?
+        return false if force_autostart?
+
+        JetstreamBridge.config.lazy_connect ||
+          env_disables_autostart? ||
+          rake_task?
+      end
+
+      def autostart_skip_reason
+        return 'lazy_connect enabled' if JetstreamBridge.config.lazy_connect
+        return 'JETSTREAM_BRIDGE_DISABLE_AUTOSTART set' if env_disables_autostart?
+        return 'rake task' if rake_task?
+
+        'unknown'
+      end
+
+      def env_disables_autostart?
+        value = ENV.fetch('JETSTREAM_BRIDGE_DISABLE_AUTOSTART', nil)
+        return false if value.nil?
+
+        normalized = value.to_s.strip.downcase
+        return false if normalized.empty?
+
+        !%w[false 0 no off].include?(normalized)
+      end
+
+      def force_autostart?
+        value = ENV.fetch('JETSTREAM_BRIDGE_FORCE_AUTOSTART', nil)
+        return false if value.nil?
+
+        normalized = value.to_s.strip.downcase
+        %w[true 1 yes on].include?(normalized)
+      end
+
+      def log_started!
+        active_logger&.info('[JetStream Bridge] Started successfully')
+      end
+
+      def log_development_connection_details!
+        conn_state = JetstreamBridge::Connection.instance.state
+        active_logger&.info("[JetStream Bridge] Connection state: #{conn_state}")
+        active_logger&.info("[JetStream Bridge] Connected to: #{JetstreamBridge.config.nats_urls}")
+        active_logger&.info("[JetStream Bridge] Stream: #{JetstreamBridge.config.stream_name}")
+        active_logger&.info("[JetStream Bridge] Publishing to: #{JetstreamBridge.config.source_subject}")
+        active_logger&.info("[JetStream Bridge] Consuming from: #{JetstreamBridge.config.destination_subject}")
+      end
+
+      def register_shutdown_hook!
+        return if @shutdown_hook_registered
+
+        at_exit { JetstreamBridge.shutdown! }
+        @shutdown_hook_registered = true
+      end
+
+      def rails_test?
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.test?
+      end
+
+      def rails_development?
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.development?
+      end
+
+      def rails_console?
+        !!defined?(::Rails::Console)
+      end
+
+      def rake_task?
+        !!defined?(::Rake) || File.basename($PROGRAM_NAME) == 'rake'
+      end
+
+      def active_logger
+        if defined?(::Rails) && ::Rails.respond_to?(:logger)
+          ::Rails.logger
+        else
+          Logging.logger
+        end
+      end
+    end
+  end
+end