jetstream_bridge 4.0.4 → 4.2.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,85 @@
+# 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
+        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_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/config.rb

@@ -86,6 +86,15 @@ module JetstreamBridge
     # Applied preset name
     # @return [Symbol, nil]
     attr_reader :preset_applied
+    # Number of retry attempts for initial connection
+    # @return [Integer]
+    attr_accessor :connect_retry_attempts
+    # Delay between connection retry attempts (in seconds)
+    # @return [Integer]
+    attr_accessor :connect_retry_delay
+    # Enable lazy connection (connect on first use instead of during configure)
+    # @return [Boolean]
+    attr_accessor :lazy_connect
 
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
@@ -104,6 +113,11 @@ module JetstreamBridge
       @inbox_model  = 'JetstreamBridge::InboxEvent'
       @logger       = nil
       @preset_applied = nil
+
+      # Connection management
+      @connect_retry_attempts = 3
+      @connect_retry_delay = 2
+      @lazy_connect = false
     end
 
     # Apply a configuration preset
@@ -219,11 +233,20 @@ module JetstreamBridge
     private
 
     def validate_subject_component!(value, name)
-      str = value.to_s
-      if str.match?(/[.*>]/)
-        raise InvalidSubjectError, "#{name} cannot contain NATS wildcards (., *, >): #{value.inspect}"
+      str = value.to_s.strip
+      raise MissingConfigurationError, "#{name} cannot be empty" if str.empty?
+
+      # NATS subject tokens must not contain wildcards, spaces, or control characters
+      # Valid characters: alphanumeric, hyphen, underscore
+      if str.match?(/[.*>\s\x00-\x1F\x7F]/)
+        raise InvalidSubjectError,
+              "#{name} contains invalid NATS subject characters (wildcards, spaces, or control chars): #{value.inspect}"
       end
-      raise MissingConfigurationError, "#{name} cannot be empty" if str.strip.empty?
+
+      # NATS has a practical subject length limit
+      return unless str.length > 255
+
+      raise InvalidSubjectError, "#{name} exceeds maximum length (255 characters): #{str.length}"
     end
   end
 end