jetstream_bridge 5.1.0 → 7.0.1

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -41,60 +41,68 @@ module JetstreamBridge
     # Bind a subscriber to the existing durable consumer.
     def subscribe!
       if @cfg.push_consumer?
-        subscribe_push!
+        subscribe_push_with_fallback
       else
-        # Always bypass consumer_info to avoid requiring JetStream API permissions at runtime.
-        subscribe_without_verification!
+        subscribe_pull_with_fallback
       end
     end
 
     def subscribe_without_verification!
       # Manually create a pull subscription without calling consumer_info
       # This bypasses the permission check in nats-pure's pull_subscribe
-      nc = resolve_nc
-
-      return build_pull_subscription(nc) if nc.respond_to?(:new_inbox) && nc.respond_to?(:subscribe)
-
-      # Fallback for environments (mocks/tests) where low-level NATS client is unavailable.
-      if @jts.respond_to?(:pull_subscribe)
-        Logging.info(
-          "Using pull_subscribe fallback for consumer #{@durable} (stream=#{stream_name})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return @jts.pull_subscribe(filter_subject, @durable, stream: stream_name)
-      end
-
-      raise JetstreamBridge::ConnectionError,
-            'Unable to create subscription without verification: NATS client not available'
+      create_subscription_with_fallback(
+        description: "pull subscription for consumer #{@durable} (stream=#{stream_name})",
+        primary_check: ->(nc) { nc.respond_to?(:new_inbox) && nc.respond_to?(:subscribe) },
+        primary_action: ->(nc) { build_pull_subscription(nc) },
+        fallback_name: :pull_subscribe,
+        fallback_available: -> { @jts.respond_to?(:pull_subscribe) },
+        fallback_action: -> { @jts.pull_subscribe(filter_subject, @durable, stream: stream_name) }
+      )
     end
 
     def subscribe_push!
       # Push consumers deliver messages directly to a subscription subject
       # No JetStream API calls needed - just subscribe to the delivery subject
-      nc = resolve_nc
       delivery_subject = @cfg.push_delivery_subject
+      queue_group = @cfg.push_consumer_group_name
+
+      create_subscription_with_fallback(
+        description: "push subscription for consumer #{@durable} " \
+                     "(stream=#{stream_name}, delivery=#{delivery_subject}, queue=#{queue_group})",
+        primary_check: ->(nc) { nc.respond_to?(:subscribe) },
+        primary_action: lambda do |nc|
+          sub = nc.subscribe(delivery_subject, queue: queue_group)
+          Logging.info(
+            "Created push subscription for consumer #{@durable} " \
+            "(stream=#{stream_name}, delivery=#{delivery_subject}, queue=#{queue_group})",
+            tag: 'JetstreamBridge::Consumer'
+          )
+          sub
+        end,
+        fallback_name: :subscribe,
+        fallback_available: -> { @jts.respond_to?(:subscribe) },
+        fallback_action: -> { @jts.subscribe(delivery_subject, queue: queue_group) }
+      )
+    end
 
-      if nc.respond_to?(:subscribe)
-        sub = nc.subscribe(delivery_subject)
-        Logging.info(
-          "Created push subscription for consumer #{@durable} " \
-          "(stream=#{stream_name}, delivery=#{delivery_subject})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return sub
-      end
-
-      # Fallback for test environments
-      if @jts.respond_to?(:subscribe)
-        Logging.info(
-          "Using JetStream subscribe fallback for push consumer #{@durable} (stream=#{stream_name})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return @jts.subscribe(delivery_subject)
-      end
+    def subscribe_push_with_fallback
+      subscribe_push!
+    rescue JetstreamBridge::ConnectionError, StandardError => e
+      Logging.warn(
+        "Push subscription failed (#{e.class}: #{e.message}); falling back to pull subscription for #{@durable}",
+        tag: 'JetstreamBridge::Consumer'
+      )
+      subscribe_without_verification!
+    end
 
-      raise JetstreamBridge::ConnectionError,
-            'Unable to create push subscription: NATS client not available'
+    def subscribe_pull_with_fallback
+      subscribe_without_verification!
+    rescue JetstreamBridge::ConnectionError, StandardError => e
+      Logging.warn(
+        "Pull subscription failed (#{e.class}: #{e.message}); falling back to push subscription for #{@durable}",
+        tag: 'JetstreamBridge::Consumer'
+      )
+      subscribe_push!
     end
 
     private
@@ -107,12 +115,15 @@ module JetstreamBridge
         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) }
+        ack_wait: Duration.to_seconds(JetstreamBridge.config.ack_wait),
+        backoff: Duration.normalize_list_to_seconds(JetstreamBridge.config.backoff)
       }
 
-      # Add deliver_subject for push consumers
-      config[:deliver_subject] = @cfg.push_delivery_subject if @cfg.push_consumer?
+      # Add deliver_subject and deliver_group for push consumers
+      if @cfg.push_consumer?
+        config[:deliver_subject] = @cfg.push_delivery_subject
+        config[:deliver_group] = @cfg.push_consumer_group_name
+      end
 
       config
     end
@@ -125,73 +136,6 @@ module JetstreamBridge
       )
     end
 
-    # ---- cfg access/normalization (struct-like or hash-like) ----
-
-    def get(cfg, key)
-      cfg.respond_to?(key) ? cfg.public_send(key) : cfg[key]
-    end
-
-    def sval(cfg, key)
-      v = get(cfg, key)
-      v = v.to_s if v.is_a?(Symbol)
-      v&.to_s&.downcase
-    end
-
-    def ival(cfg, key)
-      v = get(cfg, key)
-      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)
-      raw = get(cfg, key)
-      duration_to_seconds(raw)
-    end
-
-    # Normalize array of durations to integer milliseconds.
-    def darr_secs(cfg, key)
-      raw = get(cfg, key)
-      Array(raw).map { |d| duration_to_seconds(d) }
-    end
-
-    # ---- duration coercion ----
-
-    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 → 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)
-        millis = Duration.to_millis(val, default_unit: :auto)
-        seconds_from_millis(millis)
-      when Float
-        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
-        millis = Duration.to_millis(val) # default_unit ignored when unit given
-        seconds_from_millis(millis)
-      else
-        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
-
     def log_runtime_skip
       Logging.info(
         "Skipping consumer provisioning/verification for #{@durable} at runtime to avoid JetStream API usage. " \
@@ -213,5 +157,23 @@ module JetstreamBridge
       builder = PullSubscriptionBuilder.new(@jts, @durable, stream_name, filter_subject)
       builder.build(nats_client)
     end
+
+    def create_subscription_with_fallback(description:, primary_check:, primary_action:, fallback_name:,
+                                          fallback_available:, fallback_action:)
+      nc = resolve_nc
+
+      return primary_action.call(nc) if nc && primary_check.call(nc)
+
+      if fallback_available.call
+        Logging.info(
+          "Using #{fallback_name} fallback for #{description}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        return fallback_action.call
+      end
+
+      raise JetstreamBridge::ConnectionError,
+            "Unable to create #{description}: NATS client not available"
+    end
   end
 end

data/lib/jetstream_bridge/core/config.rb

@@ -114,6 +114,10 @@ module JetstreamBridge
     # Only used when consumer_mode is :push
     # @return [String, nil]
     attr_accessor :delivery_subject
+    # Queue group / deliver_group for push consumers (optional, defaults to durable_name or app_name)
+    # Only used when consumer_mode is :push. Determines how push consumers load-balance.
+    # @return [String, nil]
+    attr_accessor :push_consumer_group
 
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
@@ -142,6 +146,7 @@ module JetstreamBridge
       # Consumer mode
       @consumer_mode = :pull
       @delivery_subject = nil
+      @push_consumer_group = nil
     end
 
     # Apply a configuration preset
@@ -223,11 +228,26 @@ module JetstreamBridge
       "#{destination_subject}.worker"
     end
 
+    # Queue group for push consumers. Controls deliver_group and queue subscription.
+    #
+    # @return [String] Queue group name
+    # @raise [InvalidSubjectError, MissingConfigurationError] If derived components invalid
+    def push_consumer_group_name
+      group = push_consumer_group
+      group = durable_name if group.to_s.strip.empty?
+      group = app_name if group.to_s.strip.empty?
+
+      validate_subject_component!(group, 'push_consumer_group')
+      group
+    end
+
     # Check if using pull consumer mode.
     #
     # @return [Boolean]
     def pull_consumer?
       consumer_mode.to_sym == :pull
+    rescue NoMethodError
+      false
     end
 
     # Check if using push consumer mode.
@@ -235,6 +255,8 @@ module JetstreamBridge
     # @return [Boolean]
     def push_consumer?
       consumer_mode.to_sym == :push
+    rescue NoMethodError
+      false
     end
 
     # Validate all configuration settings.
@@ -252,6 +274,7 @@ module JetstreamBridge
       validate_numeric_constraints!(errors)
       validate_backoff!(errors)
       validate_consumer_mode!(errors)
+      validate_push_consumer!(errors)
 
       raise ConfigurationError, "Configuration errors: #{errors.join(', ')}" if errors.any?
 
@@ -298,5 +321,13 @@ module JetstreamBridge
 
       errors << 'consumer_mode must be :pull or :push' unless [:pull, :push].include?(consumer_mode.to_sym)
     end
+
+    def validate_push_consumer!(errors)
+      return unless push_consumer?
+
+      push_consumer_group_name
+    rescue ConfigurationError => e
+      errors << e.message
+    end
   end
 end

data/lib/jetstream_bridge/core/connection.rb

@@ -44,6 +44,9 @@ module JetstreamBridge
     }.freeze
 
     VALID_NATS_SCHEMES = %w[nats nats+tls].freeze
+    REFRESH_RETRY_BASE_DELAY = 0.01
+    REFRESH_RETRY_MAX_DELAY = 30.0
+    REFRESH_RETRY_MAX_ATTEMPTS = 30
 
     # Class-level mutex for thread-safe connection initialization
     # Using class variable to avoid race condition in mutex creation
@@ -238,36 +241,10 @@ module JetstreamBridge
           tag: 'JetstreamBridge::Connection'
         )
 
-        # Retry JetStream context refresh with exponential backoff
-        max_attempts = 3
-        attempts = 0
-        success = false
-
-        while attempts < max_attempts && !success
-          attempts += 1
-          begin
-            refresh_jetstream_context
-            success = true
-          rescue StandardError => e
-            if attempts < max_attempts
-              delay = 0.5 * (2**(attempts - 1)) # 0.5s, 1s, 2s
-              Logging.warn(
-                "JetStream context refresh attempt #{attempts}/#{max_attempts} failed: #{e.message}. " \
-                "Retrying in #{delay}s...",
-                tag: 'JetstreamBridge::Connection'
-              )
-              sleep(delay)
-            else
-              Logging.error(
-                "Failed to refresh JetStream context after #{attempts} attempts. " \
-                'Will retry on next reconnect.',
-                tag: 'JetstreamBridge::Connection'
-              )
-            end
-          end
-        end
+        success = refresh_jetstream_with_retry?
 
         @reconnecting = false
+        start_refresh_retry_loop unless success
       end
 
       @nc.on_disconnect do |reason|
@@ -304,7 +281,7 @@ module JetstreamBridge
       if verify_js
         verify_jetstream!
         if config_auto_provision
-          Topology.ensure!(@jts)
+          Topology.provision!(@jts)
           Logging.info(
             'Topology ensured after connection (auto_provision=true).',
             tag: 'JetstreamBridge::Connection'
@@ -461,7 +438,7 @@ module JetstreamBridge
 
       # Re-ensure topology after reconnect when allowed
       if config_auto_provision
-        Topology.ensure!(@jts)
+        Topology.provision!(@jts)
       else
         Logging.info(
           'Skipping topology provisioning after reconnect (auto_provision=false).',
@@ -504,11 +481,95 @@ module JetstreamBridge
       raise
     end
 
+    def refresh_jetstream_with_retry?(max_attempts: 3, base_delay: 0.5)
+      attempts = 0
+      while attempts < max_attempts
+        attempts += 1
+        begin
+          refresh_jetstream_context
+          return true
+        rescue StandardError => e
+          if attempts < max_attempts
+            delay = refresh_retry_sleep_duration(attempts, base: base_delay)
+            Logging.warn(
+              "JetStream context refresh attempt #{attempts}/#{max_attempts} failed: #{e.message}. " \
+              "Retrying in #{delay}s...",
+              tag: 'JetstreamBridge::Connection'
+            )
+            sleep(delay)
+          else
+            Logging.error(
+              "Failed to refresh JetStream context after #{attempts} attempts. " \
+              'Starting background retry loop.',
+              tag: 'JetstreamBridge::Connection'
+            )
+          end
+        end
+      end
+
+      false
+    end
+
+    def start_refresh_retry_loop(initial_delay: REFRESH_RETRY_BASE_DELAY, max_attempts: REFRESH_RETRY_MAX_ATTEMPTS)
+      return if @refresh_retry_thread&.alive?
+      return unless @nc
+
+      @refresh_retry_thread = Thread.new do
+        Thread.current.report_on_exception = false
+        attempts = 0
+        delay = initial_delay
+
+        while @nc&.connected?
+          sleep(delay)
+          attempts += 1
+          break if max_attempts && attempts > max_attempts
+
+          begin
+            refresh_jetstream_context
+            Logging.info(
+              "JetStream context refreshed via background retry after #{attempts} attempt#{'s' if attempts != 1}",
+              tag: 'JetstreamBridge::Connection'
+            )
+            break
+          rescue StandardError => e
+            if defined?(RSpec::Mocks::ExpiredTestDoubleError) &&
+               e.is_a?(RSpec::Mocks::ExpiredTestDoubleError)
+              Logging.debug(
+                'Stopping background JetStream refresh due to expired test double',
+                tag: 'JetstreamBridge::Connection'
+              )
+              break
+            end
+            delay = refresh_retry_sleep_duration(attempts + 1)
+            Logging.warn(
+              "Background JetStream refresh attempt #{attempts} failed: #{e.message}. " \
+              "Retrying in #{delay}s...",
+              tag: 'JetstreamBridge::Connection'
+            )
+          end
+        end
+      ensure
+        @refresh_retry_thread = nil
+      end
+    rescue StandardError => e
+      Logging.debug(
+        "Could not start refresh retry loop: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+    end
+
+    def refresh_retry_sleep_duration(attempt, base: REFRESH_RETRY_BASE_DELAY)
+      [base * (2**(attempt - 1)), REFRESH_RETRY_MAX_DELAY].min
+    end
+
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc
 
     def jetstream
-      @jts
+      return @jts if @jts
+
+      raise ConnectionNotEstablishedError,
+            'JetStream context unavailable (refresh pending or failed)'
     end
 
     # Mask credentials in NATS URLs:
@@ -539,6 +600,11 @@ module JetstreamBridge
         @jts = nil
       end
 
+      if @refresh_retry_thread&.alive?
+        @refresh_retry_thread.kill
+        @refresh_retry_thread = nil
+      end
+
       # Always invalidate health check cache
       @cached_health_status = nil
       @last_health_check = nil

data/lib/jetstream_bridge/core/consumer_mode_resolver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module ConsumerModeResolver
+    VALID_MODES = [:pull, :push].freeze
+
+    module_function
+
+    # Resolve consumer mode for a given app.
+    #
+    # Priority:
+    # 1) explicit override (symbol/string)
+    # 2) env map CONSUMER_MODES="app:mode,..."
+    # 3) per-app env CONSUMER_MODE_<APP_NAME>
+    # 4) shared env CONSUMER_MODE
+    # 5) fallback (default :pull)
+    def resolve(app_name:, override: nil, fallback: :pull)
+      return normalize(override) if override
+
+      from_env = env_for(app_name)
+      return from_env if from_env
+
+      normalize(fallback)
+    end
+
+    def env_for(app_name)
+      from_map(app_name) || app_specific(app_name) || shared
+    end
+
+    def from_map(app_name)
+      env_map = ENV.fetch('CONSUMER_MODES', nil)
+      return nil if env_map.to_s.strip.empty?
+
+      pairs = env_map.split(',').each_with_object({}) do |pair, memo|
+        key, mode = pair.split(':', 2).map { |p| p&.strip }
+        memo[key] = mode if key && mode
+      end
+
+      normalize(pairs[app_name.to_s]) if pairs.key?(app_name.to_s)
+    end
+
+    def app_specific(app_name)
+      key = "CONSUMER_MODE_#{app_name.to_s.upcase}"
+      return nil unless ENV.key?(key)
+
+      normalize(ENV.fetch(key, nil))
+    end
+
+    def shared
+      return nil unless ENV['CONSUMER_MODE']
+
+      normalize(ENV.fetch('CONSUMER_MODE', nil))
+    end
+
+    def normalize(mode)
+      return nil if mode.nil? || mode.to_s.strip.empty?
+
+      m = mode.to_s.downcase.to_sym
+      return m if VALID_MODES.include?(m)
+
+      raise ArgumentError, "Invalid consumer mode #{mode.inspect}. Use :pull or :push."
+    end
+  end
+end

data/lib/jetstream_bridge/core/duration.rb

@@ -64,6 +64,31 @@ module JetstreamBridge
       vals.map { |v| to_millis(v, default_unit: default_unit) }
     end
 
+    # Convert duration-like value to seconds (rounding up, min 1s).
+    #
+    # Retains the nanosecond heuristic used in SubscriptionManager:
+    # extremely large integers (>= 1_000_000_000) are treated as nanoseconds
+    # when default_unit is :auto.
+    def to_seconds(val, default_unit: :auto)
+      return nil if val.nil?
+
+      millis = if val.is_a?(Integer) && default_unit == :auto && val >= 1_000_000_000
+                 to_millis(val, default_unit: :ns)
+               else
+                 to_millis(val, default_unit: default_unit)
+               end
+
+      seconds_from_millis(millis)
+    end
+
+    # Normalize an array of durations into integer seconds.
+    def normalize_list_to_seconds(values, default_unit: :auto)
+      vals = Array(values)
+      return [] if vals.empty?
+
+      vals.map { |v| to_seconds(v, default_unit: default_unit) }
+    end
+
     # --- internal helpers ---
 
     def int_to_ms(num, default_unit:)
@@ -100,5 +125,10 @@ module JetstreamBridge
 
       (num * mult).round
     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/models/inbox_event.rb

@@ -11,7 +11,7 @@ end
 module JetstreamBridge
   if defined?(ActiveRecord::Base)
     class InboxEvent < ActiveRecord::Base
-      self.table_name = 'jetstream_inbox_events'
+      self.table_name = 'jetstream_bridge_inbox_events'
 
       class << self
         # Safe column presence check that never boots a connection during class load.

data/lib/jetstream_bridge/models/outbox_event.rb

@@ -11,7 +11,7 @@ end
 module JetstreamBridge
   if defined?(ActiveRecord::Base)
     class OutboxEvent < ActiveRecord::Base
-      self.table_name = 'jetstream_outbox_events'
+      self.table_name = 'jetstream_bridge_outbox_events'
 
       class << self
         # Safe column presence check that never boots a connection during class load.