jetstream_bridge 7.0.0 → 7.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 471b7dd68739c9de058cbaeedb800dbb5c0e1eadaa2d54602eee34d8469f2668
-  data.tar.gz: 7d16630ce0e83b6d6fb1ab6f9e6c5151a6aa5df7467810f950fd984e035bb9f0
+  metadata.gz: b438f568ca21ece1da4e01f0fcea10ab2a2ec893e56a988a54808108f3e46830
+  data.tar.gz: d7733a1316e720b74d7ac3e887e48aeb49923a7aa555612249ee9ca90e0e3c65
 SHA512:
-  metadata.gz: d58a47de952678819cd5681b750907ca9d56be3bf9799d5e6f614acd828c9d86da80c7be1006280cbfa42c88ebe8fd6a804da829b5f73672dd59766955df1d16
-  data.tar.gz: f963140e8a639fc285b633f112df806ff3638e3d83f1b834702d91a47d4a2f28c704071c8ae2f3d763c6d750aa708e12babe33872dbb3778d53058965cd987e0
+  metadata.gz: 197a224969a88b1a3df0652a7c42f1597e9b31068574ae4706f8d54710acc5597a1b45ef9deef164ad69c1b41155e7086d2b79d9e794dafd09fb1039247d55a9
+  data.tar.gz: 224e1a0a69233c419a296fc0184de56a414b2a409f7d6a17bf82a831f746193ee7f87f46bd712dc24f23b1f707494978979594ff84cddd451a0810f3a7a3083b

data/docs/ARCHITECTURE.md

@@ -29,51 +29,27 @@ JetStream Bridge provides reliable, production-ready message passing between Rub
 
 ### Architecture Diagram
 
-```markdown
-┌─────────────────┐                    ┌─────────────────┐
-│   Application   │                    │   Application   │
-│   "api"         │                    │   "worker"      │
-├─────────────────┤                    ├─────────────────┤
-│                 │                    │                 │
-│  Publisher      │                    │  Publisher      │
-│  (Optional      │                    │  (Optional      │
-│   Outbox)       │                    │   Outbox)       │
-│                 │                    │                 │
-└────────┬────────┘                    └────────┬────────┘
-         │                                      │
-         │ Publish to:                          │ Publish to:
-         │ api.sync.worker                      │ worker.sync.api
-         │                                      │
-         └──────────────┐          ┌────────────┘
-                        │          │
-                        ▼          ▼
-                 ┌──────────────────────┐
-                 │   NATS JetStream     │
-                 │                      │
-                 │  Stream: "my-stream" │
-                 │  Subjects:           │
-                 │   - api.sync.worker  │
-                 │   - worker.sync.api  │
-                 │   - api.sync.dlq     │
-                 │   - worker.sync.dlq  │
-                 │                      │
-                 │  Consumers:          │
-                 │   - api-workers      │
-                 │   - worker-workers   │
-                 └──────────────────────┘
-                        │          │
-         ┌──────────────┘          └────────────┐
-         │                                      │
-         │ Subscribe to:                        │ Subscribe to:
-         │ worker.sync.api                      │ api.sync.worker
-         │                                      │
-┌────────▼────────┐                    ┌────────▼────────┐
-│  Consumer       │                    │  Consumer       │
-│  (Optional      │                    │  (Optional      │
-│   Inbox)        │                    │   Inbox)        │
-│                 │                    │                 │
-│  DLQ Handler    │                    │  DLQ Handler    │
-└─────────────────┘                    └─────────────────┘
+```mermaid
+flowchart LR
+  subgraph AppA["Application \"api\""]
+    api_pub["Publisher\n(Optional Outbox)"]
+    api_cons["Consumer\n(Optional Inbox)\nDLQ Handler"]
+  end
+
+  subgraph Stream["NATS JetStream\nStream: \"my-stream\""]
+    subjects["Subjects:\n- api.sync.worker\n- worker.sync.api\n- api.sync.dlq\n- worker.sync.dlq"]
+    consumers["Consumers:\n- api-workers\n- worker-workers"]
+  end
+
+  subgraph AppB["Application \"worker\""]
+    worker_pub["Publisher\n(Optional Outbox)"]
+    worker_cons["Consumer\n(Optional Inbox)\nDLQ Handler"]
+  end
+
+  api_pub -- "Publish: api.sync.worker" --> Stream
+  worker_pub -- "Publish: worker.sync.api" --> Stream
+  Stream -- "Subscribe: worker.sync.api" --> api_cons
+  Stream -- "Subscribe: api.sync.worker" --> worker_cons
 ```
 
 ---
@@ -216,19 +192,21 @@ Orchestrates stream and consumer provisioning:
 
 **One stream per application pair** (or shared stream for multiple apps):
 
-```markdown
-Stream: "jetstream-bridge-stream"
-├── Subjects:
-│   ├── api.sync.worker      (api publishes, worker consumes)
-│   ├── worker.sync.api      (worker publishes, api consumes)
-│   ├── api.sync.dlq         (api's dead letter queue)
-│   └── worker.sync.dlq      (worker's dead letter queue)
-│
-├── Retention: workqueue      (messages deleted after ack)
-├── Storage: file             (persistent on disk)
-└── Consumers:
-    ├── api-workers           (filters: worker.sync.api)
-    └── worker-workers        (filters: api.sync.worker)
+```mermaid
+flowchart TD
+  stream["Stream: jetstream-bridge-stream"]
+  stream --> retention["Retention: workqueue"]
+  stream --> storage["Storage: file"]
+
+  stream --> subjects["Subjects"]
+  subjects --> subj1["api.sync.worker\n(api publishes → worker consumes)"]
+  subjects --> subj2["worker.sync.api\n(worker publishes → api consumes)"]
+  subjects --> subj3["api.sync.dlq\n(api dead letter queue)"]
+  subjects --> subj4["worker.sync.dlq\n(worker dead letter queue)"]
+
+  stream --> consumers["Consumers"]
+  consumers --> c1["api-workers\n(filters worker.sync.api)"]
+  consumers --> c2["worker-workers\n(filters api.sync.worker)"]
 ```
 
 ### Subject Pattern
@@ -315,120 +293,31 @@ Overlap detection ensures messages route to exactly one stream.
 
 ### Publishing Flow
 
-```markdown
-┌──────────────────────────────────────────────────────────────┐
-│ 1. Application calls JetstreamBridge.publish(...)           │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 2. Publisher builds envelope                                 │
-│    - Generate event_id (UUID)                                │
-│    - Extract resource_id from payload                        │
-│    - Add timestamps, producer, schema_version                │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 3. [OPTIONAL] Outbox pattern                                 │
-│    - OutboxRepository.record_publish_attempt()               │
-│    - State: "publishing"                                     │
-│    - Database transaction commits                            │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 4. Publish to NATS JetStream                                 │
-│    - Subject: {app_name}.sync.{destination_app}              │
-│    - Header: nats-msg-id = event_id (deduplication)          │
-│    - Retry with exponential backoff on transient errors      │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 5. [OPTIONAL] Outbox update                                  │
-│    - Success: OutboxRepository.record_publish_success()      │
-│    - Failure: OutboxRepository.record_publish_failure()      │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 6. Return PublishResult                                      │
-│    - success: true/false                                     │
-│    - event_id: UUID                                          │
-│    - duplicate: true/false (if seen before)                  │
-└──────────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+  p1["1. Application calls JetstreamBridge.publish(...)"]
+  p2["2. Publisher builds envelope\n- Generate event_id (UUID)\n- Extract resource_id from payload\n- Add timestamps, producer, schema_version"]
+  p3["3. Optional Outbox pattern\n- record_publish_attempt\n- State: \"publishing\"\n- Database transaction commits"]
+  p4["4. Publish to NATS JetStream\n- Subject: {app_name}.sync.{destination_app}\n- Header: nats-msg-id = event_id\n- Retry with exponential backoff"]
+  p5["5. Optional Outbox update\n- record_publish_success\n- record_publish_failure"]
+  p6["6. Return PublishResult\n- success flag\n- event_id\n- duplicate?"]
+  p1 --> p2 --> p3 --> p4 --> p5 --> p6
 ```
 
 ### Consuming Flow
 
-```markdown
-┌──────────────────────────────────────────────────────────────┐
-│ 1. Application creates Consumer.new { |event| ... }          │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 2. SubscriptionManager ensures durable consumer              │
-│    - Consumer: {app_name}-workers                            │
-│    - Filter: {destination_app}.sync.{app_name}               │
-│    - Create if not exists (idempotent)                       │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 3. Subscribe to consumer                                     │
-│    - Pull mode: $JS.API.CONSUMER.MSG.NEXT.{stream}.{durable}│
-│    - Push mode: {delivery_subject}                           │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 4. Consumer.run! starts main loop                            │
-│    - Fetch batch of messages                                 │
-│    - Process each message sequentially                       │
-│    - Idle backoff when no messages (0.05s → 1.0s)            │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 5. [OPTIONAL] Inbox deduplication check                      │
-│    - InboxRepository.find_or_build(event_id)                 │
-│    - If already processed → skip and ack                     │
-│    - If new → InboxRepository.persist_pre()                  │
-│    - State: "processing"                                     │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 6. MessageProcessor.handle_message()                         │
-│    - Parse JSON envelope → Event object                      │
-│    - Run middleware chain                                    │
-│    - Call user handler block                                 │
-│    - Return ActionResult (:ack or :nak)                      │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 7. Error handling                                            │
-│    - Unrecoverable (ArgumentError, TypeError) → DLQ + ack    │
-│    - Recoverable (StandardError) → nak with backoff          │
-│    - Malformed JSON → DLQ + ack                              │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 8. [OPTIONAL] Inbox update                                   │
-│    - Success: InboxRepository.persist_post()                 │
-│    - Failure: InboxRepository.persist_failure()              │
-└──────────────────────┬───────────────────────────────────────┘
-                       │
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│ 9. Acknowledge message                                       │
-│    - :ack → msg.ack (removes from stream)                    │
-│    - :nak → msg.nak(delay: backoff) (requeue for retry)     │
-└──────────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+  c1["1. Application creates Consumer.new { |event| ... }"]
+  c2["2. SubscriptionManager ensures durable consumer\n- {app_name}-workers\n- Filter: {destination_app}.sync.{app_name}\n- Create if missing (idempotent)"]
+  c3["3. Subscribe to consumer\n- Pull: $JS.API.CONSUMER.MSG.NEXT.{stream}.{durable}\n- Push: {delivery_subject}"]
+  c4["4. Consumer.run! main loop\n- Fetch batch of messages\n- Process sequentially\n- Idle backoff 0.05s → 1.0s"]
+  c5["5. Optional inbox deduplication\n- find_or_build(event_id)\n- Skip if processed\n- persist_pre marks processing"]
+  c6["6. MessageProcessor.handle_message\n- Parse envelope → Event\n- Run middleware chain\n- Call user handler\n- Return :ack or :nak"]
+  c7["7. Error handling\n- Unrecoverable → DLQ + ack\n- Recoverable → nak with backoff\n- Malformed JSON → DLQ + ack"]
+  c8["8. Optional inbox update\n- persist_post\n- persist_failure"]
+  c9["9. Acknowledge message\n- :ack → msg.ack\n- :nak → msg.nak(delay: backoff)"]
+  c1 --> c2 --> c3 --> c4 --> c5 --> c6 --> c7 --> c8 --> c9
 ```
 
 ---
@@ -1067,8 +956,9 @@ end
 
 **Exponential backoff when no messages:**
 
-```markdown
-0.05s → 0.1s → 0.2s → 0.4s → 0.8s → 1.0s (max)
+```mermaid
+flowchart LR
+  t1["0.05s"] --> t2["0.1s"] --> t3["0.2s"] --> t4["0.4s"] --> t5["0.8s"] --> t6["1.0s (max)"]
 ```
 
 **Benefit:** Reduces CPU and network usage during idle periods

data/docs/PRODUCTION.md

@@ -44,8 +44,15 @@ production:
 
 **Total Formula:**
 
-```markdown
-Total Connections = (Web Workers × Threads) + (Consumers × 3) + 10 buffer
+```mermaid
+flowchart LR
+  ww["Web workers × threads"]
+  cons["Consumers × 3"]
+  buffer["+ 10 buffer"]
+  ww --> sum
+  cons --> sum
+  buffer --> sum
+  sum["Total connections"]
 ```
 
 ### Example Calculation

data/docs/RESTRICTED_PERMISSIONS.md

@@ -410,24 +410,17 @@ end
 
 ### Deploy the Updated Gem
 
-If you're working on the jetstream_bridge gem itself:
+Use the published gem in your application (no local path):
 
-```bash
-# Build the gem
-gem build jetstream_bridge.gemspec
-
-# Install locally for testing
-gem install ./jetstream_bridge-7.0.0.gem
-
-# Or update in your application's Gemfile.lock
-bundle update jetstream_bridge
+```ruby
+# Gemfile
+gem "jetstream_bridge", "~> 7.0"
 ```
 
-If this is a local modification, you can point your Gemfile to the local path:
+Then update:
 
-```ruby
-# Gemfile (temporary for testing)
-gem 'jetstream_bridge', path: '/path/to/local/jetstream_bridge'
+```bash
+bundle update jetstream_bridge
 ```
 
 ### Restart the Service

data/lib/generators/jetstream_bridge/migrations/migrations_generator.rb

@@ -28,13 +28,23 @@ module JetstreamBridge
 
       # -- Rails::Generators::Migration plumbing --
       def self.next_migration_number(dirname)
-        if ActiveRecord::Base.timestamped_migrations
+        if timestamped_migrations?
           Time.now.utc.strftime('%Y%m%d%H%M%S')
         else
           format('%.3d', current_migration_number(dirname) + 1)
         end
       end
 
+      def self.timestamped_migrations?
+        if ActiveRecord::Base.respond_to?(:timestamped_migrations)
+          ActiveRecord::Base.timestamped_migrations
+        elsif ActiveRecord::Migration.respond_to?(:timestamped_migrations)
+          ActiveRecord::Migration.timestamped_migrations
+        else
+          true
+        end
+      end
+
       private
 
       def migration_exists?(dirname, file_name)

data/lib/jetstream_bridge/config_helpers/lifecycle.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module ConfigHelpers
+    module Lifecycle
+      module_function
+
+      def setup(logger: nil, rails_app: nil)
+        app = rails_app
+        app ||= Rails.application if defined?(Rails) && Rails.respond_to?(:application)
+
+        # Gracefully no-op when Rails isn't available (e.g., non-Rails runtimes or early boot)
+        return unless app
+
+        effective_logger = logger || default_rails_logger(app)
+
+        app.config.after_initialize do
+          JetstreamBridge.startup!
+          effective_logger&.info('JetStream Bridge connected successfully')
+        rescue StandardError => e
+          effective_logger&.error("Failed to connect to JetStream: #{e.message}")
+        end
+
+        Kernel.at_exit { JetstreamBridge.shutdown! }
+      end
+
+      def default_rails_logger(app = nil)
+        return app.logger if app.respond_to?(:logger)
+
+        defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/config_helpers.rb

@@ -2,6 +2,8 @@
 
 require_relative 'core/logging'
 require_relative 'core/config'
+require_relative 'core/consumer_mode_resolver'
+require_relative 'config_helpers/lifecycle'
 
 module JetstreamBridge
   # Convenience helpers to keep example configuration lean and consistent.
@@ -52,28 +54,8 @@ module JetstreamBridge
     end
 
     # Wire JetstreamBridge lifecycle into Rails boot/shutdown.
-    #
-    # Safe to call multiple times; startup! is idempotent.
-    #
-    # @param logger [Logger,nil] Logger to use for lifecycle messages
-    # @return [void]
     def setup_rails_lifecycle(logger: nil, rails_app: nil)
-      app = rails_app
-      app ||= Rails.application if defined?(Rails) && Rails.respond_to?(:application)
-
-      # Gracefully no-op when Rails isn't available (e.g., non-Rails runtimes or early boot)
-      return unless app
-
-      effective_logger = logger || default_rails_logger(app)
-
-      app.config.after_initialize do
-        JetstreamBridge.startup!
-        effective_logger&.info('JetStream Bridge connected successfully')
-      rescue StandardError => e
-        effective_logger&.error("Failed to connect to JetStream: #{e.message}")
-      end
-
-      Kernel.at_exit { JetstreamBridge.shutdown! }
+      Lifecycle.setup(logger: logger, rails_app: rails_app)
     end
 
     def restrictive?(mode)
@@ -90,10 +72,31 @@ module JetstreamBridge
       config.auto_provision = !restrictive?(mode)
       config.use_outbox = use_outbox
       config.use_inbox = use_inbox
-      config.consumer_mode = overrides.fetch(:consumer_mode, config.consumer_mode || :pull)
+      config.consumer_mode = resolve_consumer_mode(app_name, overrides)
     end
     private_class_method :apply_base_settings
 
+    # Resolve consumer_mode with priority:
+    # 1) explicit override passed to configure_bidirectional
+    # 2) per-app env via CONSUMER_MODES map or CONSUMER_MODE_<APP_NAME>
+    # 3) shared env CONSUMER_MODE
+    # 4) existing config value or :pull
+    def resolve_consumer_mode(app_name, overrides)
+      explicit = overrides[:consumer_mode] if overrides.key?(:consumer_mode)
+      config_default = begin
+        JetstreamBridge.config&.consumer_mode
+      rescue StandardError
+        nil
+      end
+
+      ConsumerModeResolver.resolve(
+        app_name: app_name,
+        override: explicit,
+        fallback: config_default || :pull
+      )
+    end
+    private_class_method :resolve_consumer_mode
+
     def apply_reliability_defaults(config, overrides)
       config.max_deliver = overrides.fetch(:max_deliver, DEFAULT_MAX_DELIVER)
       config.ack_wait = overrides.fetch(:ack_wait, DEFAULT_ACK_WAIT)
@@ -111,12 +114,5 @@ module JetstreamBridge
       end
     end
     private_class_method :apply_overrides
-
-    def default_rails_logger(app = nil)
-      return app.logger if app.respond_to?(:logger)
-
-      defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
-    end
-    private_class_method :default_rails_logger
   end
 end

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -58,6 +58,83 @@ module JetstreamBridge
     TracingMiddleware = ConsumerMiddleware::TracingMiddleware
     TimeoutMiddleware = ConsumerMiddleware::TimeoutMiddleware
 
+    class << self
+      def register_consumer_for_signals(consumer)
+        signal_registry_mutex.synchronize do
+          signal_consumers << consumer
+          install_signal_handlers_once
+        end
+      end
+
+      def unregister_consumer_for_signals(consumer)
+        signal_registry_mutex.synchronize { signal_consumers.delete(consumer) }
+      end
+
+      def reset_signal_handlers!
+        signal_registry_mutex.synchronize { signal_consumers.clear }
+        @signal_handlers_installed = false
+        @previous_signal_handlers = {}
+      end
+
+      private
+
+      def signal_consumers
+        @signal_consumers ||= []
+      end
+
+      def signal_registry_mutex
+        @signal_registry_mutex ||= Mutex.new
+      end
+
+      def install_signal_handlers_once
+        return if @signal_handlers_installed
+
+        %w[INT TERM].each { |sig| install_signal_handler(sig) }
+        @signal_handlers_installed = true
+      end
+
+      def install_signal_handler(sig)
+        previous = nil
+        handler = nil
+        handler = proc do
+          broadcast_signal(sig)
+          invoke_previous_handler(previous, sig, handler)
+        rescue StandardError
+          # Trap contexts must stay minimal; swallow any unexpected errors
+        end
+        previous = Signal.trap(sig, &handler)
+        previous_signal_handlers[sig] = previous
+      rescue ArgumentError => e
+        Logging.debug("Could not set up signal handlers: #{e.message}", tag: 'JetstreamBridge::Consumer')
+      end
+
+      def broadcast_signal(sig)
+        consumers = nil
+        signal_registry_mutex.synchronize { consumers = signal_consumers.dup }
+        consumers.each do |consumer|
+          next unless consumer.respond_to?(:lifecycle_state)
+
+          consumer.lifecycle_state.signal!(sig)
+        end
+      rescue StandardError
+        # Trap safety: never raise
+      end
+
+      def invoke_previous_handler(previous, sig, current_handler = nil)
+        return if previous.nil? || previous == 'DEFAULT' || previous == 'SYSTEM_DEFAULT'
+        return if previous == 'IGNORE'
+        return if current_handler && previous.equal?(current_handler)
+
+        previous.call(sig) if previous.respond_to?(:call)
+      rescue StandardError
+        # Never bubble from trap context
+      end
+
+      def previous_signal_handlers
+        @previous_signal_handlers ||= {}
+      end
+    end
+
     # @return [String] Durable consumer name
     attr_reader :durable
     # @return [Integer] Batch size for message fetching
@@ -252,6 +329,8 @@ module JetstreamBridge
     #
     def stop!
       @lifecycle_state.stop!
+      # Allow other consumers to continue receiving signals without stale references
+      self.class.unregister_consumer_for_signals(self)
       Logging.info("Consumer #{@durable} shutdown requested", tag: 'JetstreamBridge::Consumer')
     end
 
@@ -394,15 +473,8 @@ module JetstreamBridge
     end
 
     def setup_signal_handlers
-      %w[INT TERM].each do |sig|
-        Signal.trap(sig) do
-          # CRITICAL: Only set flags in trap context, no I/O or mutex operations
-          # Logging and other operations are unsafe from signal handlers
-          @lifecycle_state.signal!(sig)
-        end
-      end
-    rescue ArgumentError => e
-      # Signal handlers may not be available in all environments (e.g., threads)
+      self.class.register_consumer_for_signals(self)
+    rescue StandardError => e
       Logging.debug("Could not set up signal handlers: #{e.message}", tag: 'JetstreamBridge::Consumer')
     end
 

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -41,10 +41,9 @@ 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
 
@@ -65,25 +64,47 @@ module JetstreamBridge
       # Push consumers deliver messages directly to a subscription subject
       # No JetStream API calls needed - just subscribe to the delivery subject
       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})",
+        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)
+          sub = nc.subscribe(delivery_subject, queue: queue_group)
           Logging.info(
             "Created push subscription for consumer #{@durable} " \
-            "(stream=#{stream_name}, delivery=#{delivery_subject})",
+            "(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) }
+        fallback_action: -> { @jts.subscribe(delivery_subject, queue: queue_group) }
       )
     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
+
+    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
 
     def build_consumer_config(durable, filter_subject)
@@ -98,8 +119,11 @@ module JetstreamBridge
         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

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|
@@ -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/provisioner.rb

@@ -6,6 +6,7 @@ require_relative 'consumer/subscription_manager'
 require_relative 'core/logging'
 require_relative 'core/config'
 require_relative 'core/connection'
+require_relative 'core/consumer_mode_resolver'
 
 module JetstreamBridge
   # Dedicated provisioning orchestrator to keep connection concerns separate.
@@ -23,6 +24,8 @@ module JetstreamBridge
       # @param nats_url [String] NATS connection URL
       # @param logger [Logger] Logger used for progress output
       # @param shared_config [Hash] Additional config applied to both directions
+      # @param consumer_modes [Hash,nil] Per-app consumer modes { 'system_a' => :pull, 'system_b' => :push }
+      # @param consumer_mode [Symbol] Legacy/shared consumer mode for both directions (overridden by consumer_modes)
       #
       # @return [void]
       def provision_bidirectional!(
@@ -31,14 +34,26 @@ module JetstreamBridge
         stream_name: 'sync-stream',
         nats_url: ENV.fetch('NATS_URL', 'nats://nats:4222'),
         logger: Logger.new($stdout),
+        consumer_modes: nil,
+        consumer_mode: :pull,
         **shared_config
       )
+        modes = build_consumer_mode_map(app_a, app_b, consumer_modes, consumer_mode)
+
         [
           { app_name: app_a, destination_app: app_b },
           { app_name: app_b, destination_app: app_a }
         ].each do |direction|
+          direction_mode = modes[direction[:app_name]] || consumer_mode
           logger&.info "Provisioning #{direction[:app_name]} -> #{direction[:destination_app]}"
-          configure_direction(direction, stream_name, nats_url, logger, shared_config)
+          configure_direction(
+            direction,
+            stream_name: stream_name,
+            nats_url: nats_url,
+            logger: logger,
+            consumer_mode: direction_mode,
+            shared_config: shared_config
+          )
 
           begin
             JetstreamBridge.startup!
@@ -49,7 +64,28 @@ module JetstreamBridge
         end
       end
 
-      def configure_direction(direction, stream_name, nats_url, logger, shared_config)
+      def build_consumer_mode_map(app_a, app_b, consumer_modes, fallback_mode)
+        app_a_key = app_a.to_s
+        app_b_key = app_b.to_s
+        normalized_fallback = ConsumerModeResolver.normalize(fallback_mode)
+
+        if consumer_modes
+          normalized = consumer_modes.transform_keys(&:to_s).transform_values do |v|
+            ConsumerModeResolver.normalize(v)
+          end
+          normalized[app_a_key] ||= normalized_fallback
+          normalized[app_b_key] ||= normalized_fallback
+          return normalized
+        end
+
+        {
+          app_a_key => ConsumerModeResolver.resolve(app_name: app_a_key, fallback: normalized_fallback),
+          app_b_key => ConsumerModeResolver.resolve(app_name: app_b_key, fallback: normalized_fallback)
+        }
+      end
+      private :build_consumer_mode_map
+
+      def configure_direction(direction, stream_name:, nats_url:, logger:, consumer_mode:, shared_config:)
         JetstreamBridge.configure do |cfg|
           cfg.nats_urls = nats_url
           cfg.app_name = direction[:app_name]
@@ -59,8 +95,11 @@ module JetstreamBridge
           cfg.use_outbox = false
           cfg.use_inbox = false
           cfg.logger = logger if logger
+          cfg.consumer_mode = consumer_mode
 
           shared_config.each do |key, value|
+            next if key.to_sym == :consumer_mode
+
             setter = "#{key}="
             cfg.public_send(setter, value) if cfg.respond_to?(setter)
           end

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '7.0.0'
+  VERSION = '7.0.2'
 end

data/lib/jetstream_bridge.rb

@@ -129,6 +129,7 @@ module JetstreamBridge
     def reset!
       @config = nil
       @connection_initialized = false
+      Consumer.reset_signal_handlers! if defined?(Consumer)
     end
 
     # Initialize the JetStream Bridge connection and topology

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.0.2
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-30 00:00:00.000000000 Z
+date: 2026-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -137,6 +137,7 @@ files:
 - lib/generators/jetstream_bridge/migrations/templates/create_jetstream_outbox_events.rb.erb
 - lib/jetstream_bridge.rb
 - lib/jetstream_bridge/config_helpers.rb
+- lib/jetstream_bridge/config_helpers/lifecycle.rb
 - lib/jetstream_bridge/consumer/consumer.rb
 - lib/jetstream_bridge/consumer/consumer_state.rb
 - lib/jetstream_bridge/consumer/dlq_publisher.rb
@@ -153,6 +154,7 @@ files:
 - lib/jetstream_bridge/core/config_preset.rb
 - lib/jetstream_bridge/core/connection.rb
 - lib/jetstream_bridge/core/connection_factory.rb
+- lib/jetstream_bridge/core/consumer_mode_resolver.rb
 - lib/jetstream_bridge/core/debug_helper.rb
 - lib/jetstream_bridge/core/duration.rb
 - lib/jetstream_bridge/core/logging.rb