jetstream_bridge 5.1.0 → 7.0.1

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.persist_pre()                          │
-│    - 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.persist_success()             │
-│    - Failure: OutboxRepository.persist_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
 ```
 
 ---
@@ -437,7 +326,7 @@ Overlap detection ensures messages route to exactly one stream.
 
 ### Outbox Pattern (Publisher Side)
 
-**Purpose:** Guarantee at-least-once delivery by persisting events to database before publishing.
+**Purpose:** Guarantee at-most-once delivery by persisting events to database before publishing.
 
 **Configuration:**
 
@@ -486,6 +375,50 @@ config.inbox_model = 'JetstreamBridge::InboxEvent'
 - `processed` - Successfully processed
 - `failed` - Failed processing
 
+**Schema Requirements:**
+
+Generate the inbox events table migration:
+
+```bash
+rails generate jetstream_bridge:migration
+rails db:migrate
+```
+
+**Required Fields:**
+
+| Field | Type | Nullable | Description |
+| ----- | ---- | -------- | ----------- |
+| `event_id` | string | NO | Unique event identifier for deduplication |
+| `event_type` | string | NO | Type of event (e.g., 'created', 'updated') |
+| `payload` | text | NO | Full event payload as JSON |
+| `status` | string | NO | Processing status (received/processing/processed/failed) |
+| `processing_attempts` | integer | NO | Number of processing attempts (default: 0) |
+| `created_at` | timestamp | NO | When the record was created |
+| `updated_at` | timestamp | NO | When the record was last updated |
+
+**Optional Fields (useful for debugging and querying):**
+
+| Field | Type | Nullable | Description |
+| ----- | ---- | -------- | ----------- |
+| `resource_type` | string | YES | Type of resource (e.g., 'organization', 'user') |
+| `resource_id` | string | YES | ID of the resource being synced |
+| `subject` | string | YES | NATS subject the message was received on |
+| `headers` | jsonb | YES | NATS message headers |
+| `stream` | string | YES | JetStream stream name |
+| `stream_seq` | bigint | YES | Stream sequence number (fallback deduplication key) |
+| `deliveries` | integer | YES | Number of delivery attempts from NATS |
+| `error_message` | text | YES | Error message if processing failed |
+| `received_at` | timestamp | YES | When the event was first received |
+| `processed_at` | timestamp | YES | When the event was successfully processed |
+| `failed_at` | timestamp | YES | When the event failed processing |
+
+**Indexes:**
+
+- `event_id` - Unique index for fast deduplication
+- `status` - Index for querying by processing status
+- `created_at` - Index for time-based queries
+- `(stream, stream_seq)` - Unique composite index for fallback deduplication
+
 **Deduplication:**
 
 - Uses `event_id` for primary deduplication
@@ -508,6 +441,24 @@ inbox.processed_at # => 2024-01-01 00:00:00
 # Skip processing, already done
 ```
 
+**Field Population:**
+
+The InboxRepository automatically extracts and sets fields from the message payload:
+
+```ruby
+# Extracted from message body
+event_type: msg.body['type'] || msg.body['event_type']
+resource_type: msg.body['resource_type']
+resource_id: msg.body['resource_id']
+
+# NATS metadata
+subject: msg.subject
+headers: msg.headers
+stream: msg.stream
+stream_seq: msg.seq
+deliveries: msg.deliveries
+```
+
 ### Dead Letter Queue (DLQ)
 
 **Purpose:** Route unrecoverable messages to separate subject for manual intervention.
@@ -1005,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/GETTING_STARTED.md

@@ -6,7 +6,7 @@ This guide covers installation, Rails setup, configuration, and basic publish/co
 
 ```ruby
 # Gemfile
-gem "jetstream_bridge", "~> 5.0"
+gem "jetstream_bridge", "~> 7.0"
 ```
 
 ```bash
@@ -33,6 +33,64 @@ Generators create:
 - `db/migrate/*_create_jetstream_inbox_events.rb`
 - `app/controllers/jetstream_health_controller.rb` (health check)
 
+### Database Migrations
+
+The generated migrations create tables for inbox and outbox patterns:
+
+**Outbox Events** (`jetstream_bridge_outbox_events`):
+
+```ruby
+create_table :jetstream_bridge_outbox_events do |t|
+  t.string :event_id, null: false, index: { unique: true }
+  t.string :event_type, null: false
+  t.string :resource_type, null: false
+  t.string :resource_id
+  t.jsonb :payload, default: {}, null: false
+  t.string :subject, null: false
+  t.jsonb :headers, default: {}
+  t.string :status, default: "pending", null: false, index: true
+  t.text :error_message
+  t.integer :publish_attempts, default: 0
+  t.datetime :published_at, index: true
+  t.datetime :failed_at
+  t.timestamps
+end
+```
+
+**Inbox Events** (`jetstream_bridge_inbox_events`):
+
+```ruby
+create_table :jetstream_bridge_inbox_events do |t|
+  t.string :event_id, null: false, index: { unique: true }
+  t.string :event_type
+  t.string :resource_type
+  t.string :resource_id
+  t.jsonb :payload, default: {}, null: false
+  t.string :subject, null: false
+  t.jsonb :headers, default: {}
+  t.string :stream
+  t.bigint :stream_seq, index: true
+  t.integer :deliveries, default: 0
+  t.string :status, default: "received", null: false, index: true
+  t.text :error_message
+  t.integer :processing_attempts, default: 0
+  t.datetime :received_at, index: true
+  t.datetime :processed_at, index: true
+  t.datetime :failed_at
+  t.timestamps
+end
+```
+
+**Key Fields:**
+
+- `event_id`: Unique identifier for deduplication
+- `event_type`: Type of event (e.g., "user.created")
+- `resource_type`/`resource_id`: Entity being synchronized
+- `payload`: Event data (JSON)
+- `status`: Event lifecycle state (pending/processing/processed/failed)
+- `stream_seq`: NATS JetStream sequence number (inbox only)
+- `deliveries`: Delivery attempt count (inbox only)
+
 ## Configuration
 
 ```ruby
@@ -61,6 +119,19 @@ end
 
 Rails autostart runs after initialization (including in console). You can opt out for rake tasks or other tooling with `config.lazy_connect = true` or `JETSTREAM_BRIDGE_DISABLE_AUTOSTART=1`; it will then connect on first publish/subscribe.
 
+### Push consumer mode (restricted credentials)
+
+If your NATS user cannot publish to `$JS.API.*`, switch to push consumers and pre-create the durable consumer:
+
+```ruby
+config.consumer_mode = :push
+# Optional: override delivery subject (defaults to "#{config.destination_subject}.worker")
+# config.delivery_subject = "worker.sync.my_app.worker"
+config.auto_provision = false # pre-create stream/consumer with admin creds
+```
+
+Provision the consumer with NATS CLI (`--deliver <subject>`) or `bundle exec rake jetstream_bridge:provision` using admin credentials. See [docs/RESTRICTED_PERMISSIONS.md](RESTRICTED_PERMISSIONS.md) for the full least-privilege guide.
+
 ## Publish
 
 ```ruby

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
@@ -204,7 +211,7 @@ end
     "use_inbox": true,
     "use_dlq": true
   },
-  "version": "4.0.3"
+  "version": "7.0.0"
 }
 ```
 

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-4.5.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/docs/TESTING.md

@@ -47,7 +47,7 @@ RSpec.describe MyService do
       name: 'test-jetstream-bridge-stream',
       subjects: ['test.>']
     )
-    allow(JetstreamBridge::Topology).to receive(:ensure!)
+    allow(JetstreamBridge::Topology).to receive(:provision!)
   end
 
   after do
@@ -280,7 +280,7 @@ before do
   )
 
   # Allow topology check to succeed
-  allow(JetstreamBridge::Topology).to receive(:ensure!)
+  allow(JetstreamBridge::Topology).to receive(:provision!)
 
   JetstreamBridge.configure do |config|
     config.stream_name = 'jetstream-bridge-stream'
@@ -391,7 +391,7 @@ storage.reset!
 3. **Test both success and failure paths**: Use the mock to simulate errors
 4. **Verify message content**: Check that envelopes are correctly formatted
 5. **Test idempotency**: Verify duplicate detection and redelivery behavior
-6. **Mock topology setup**: Remember to stub `JetstreamBridge::Topology.ensure!`
+6. **Mock topology setup**: Remember to stub `JetstreamBridge::Topology.provision!`
 
 ## Examples
 

data/lib/generators/jetstream_bridge/migrations/templates/create_jetstream_inbox_events.rb.erb

@@ -3,22 +3,38 @@
 class CreateJetstreamInboxEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :jetstream_inbox_events do |t|
-      t.string   :event_id                              # preferred dedupe key
-      t.string   :subject,     null: false
-      t.jsonb    :payload,     null: false, default: {}
-      t.jsonb    :headers,     null: false, default: {}
-      t.string   :stream
-      t.bigint   :stream_seq
-      t.integer  :deliveries
-      t.string   :status,      null: false, default: 'received' # received|processing|processed|failed
-      t.text     :last_error
-      t.datetime :received_at
-      t.datetime :processed_at
+      # Event identification and deduplication
+      t.string   :event_id,        null: false           # unique event identifier for deduplication
+      t.string   :event_type,      null: false           # type of event (e.g., 'created', 'updated')
+      t.string   :resource_type                          # type of resource (e.g., 'organization', 'user')
+      t.string   :resource_id                            # ID of the resource
+
+      # Event payload and metadata
+      t.text     :payload,         null: false           # full event payload as JSON
+      t.string   :subject                                # NATS subject (optional)
+      t.jsonb    :headers,         default: {}           # NATS message headers (optional)
+
+      # NATS JetStream metadata (optional - useful for debugging)
+      t.string   :stream                                 # JetStream stream name
+      t.bigint   :stream_seq                             # stream sequence number
+      t.integer  :deliveries                             # number of delivery attempts
+
+      # Processing status and error tracking
+      t.string   :status,          null: false, default: 'received' # received|processing|processed|failed
+      t.text     :error_message                          # error message if processing failed
+      t.integer  :processing_attempts, null: false, default: 0 # number of processing attempts
+
+      # Timestamps
+      t.datetime :received_at                            # when the event was first received
+      t.datetime :processed_at                           # when the event was successfully processed
+      t.datetime :failed_at                              # when the event failed processing
       t.timestamps
     end
 
-    add_index :jetstream_inbox_events, :event_id, unique: true, where: 'event_id IS NOT NULL'
-    add_index :jetstream_inbox_events, [:stream, :stream_seq], unique: true, where: 'stream IS NOT NULL AND stream_seq IS NOT NULL'
+    # Indexes for efficient querying and deduplication
+    add_index :jetstream_inbox_events, :event_id, unique: true
     add_index :jetstream_inbox_events, :status
+    add_index :jetstream_inbox_events, :created_at
+    add_index :jetstream_inbox_events, [:stream, :stream_seq], unique: true, where: 'stream IS NOT NULL AND stream_seq IS NOT NULL'
   end
 end

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