jetstream_bridge 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e2b2c796fab5fd06b35517459688fa9497130af361455ef16719e4cffcdaef5
-  data.tar.gz: 5464863f1c55c4798db4607dfb7cdd9ade28933685d02231ae56cedf2b113312
+  metadata.gz: 0e0d3ee00b372ffe54ceca93b81a7c573385f6b85f16f584f15e8c5eef82cd44
+  data.tar.gz: b56fa1bc39e3b598719bced5b0be60172cd953214bee399c00341fd1f2d00906
 SHA512:
-  metadata.gz: 108cde827d26a8840448163af5cce84c5b9f16d6952ce35b0e228c1f9314caf4a822cf196c760fa6e7bf2fe1e6dafc4f89d893ff927a157d7a8420a230ecae4e
-  data.tar.gz: b546a279f3b3fa7cd7481fa4c13c81da37c923262b76ba714a1ef828192ae08f74d5b2e65d13145bbc05795b9dd5c54b067eee4ece161e69e7965ed09c975e65
+  metadata.gz: 342b6b3431d3768b843060402ededa4dcca39100c1d0c005153a3ea4f758a9ab6aff9a09e5d608444acbb332766cfb926f3c1555afb8d9df882cfcdb7a8b405f
+  data.tar.gz: eb257f387a461444121cb304c36e9fa3ce13062c81a8bc43c0cda4e6f6c706c2efa8cc7a4cf3fdfc721cedeab1d11f0ca8bb00e943644c01575d051f5e143c19

data/.idea/dictionaries/project.xml

@@ -1,8 +1,10 @@
 <component name="ProjectDictionaryState">
   <dictionary name="project">
     <words>
+      <w>acks</w>
       <w>activesupport</w>
       <w>backoffs</w>
+      <w>dedup</w>
       <w>esub</w>
       <w>msgs</w>
       <w>pipefail</w>

data/.idea/jetstream_bridge.iml

@@ -33,6 +33,7 @@
     <orderEntry type="library" scope="PROVIDED" name="connection_pool (v2.5.3, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="crass (v1.0.6, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="date (v3.4.1, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="drb (v2.2.3, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="erubi (v1.13.1, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="globalid (v1.2.1, rbenv: 3.3.6) [gem]" level="application" />
@@ -75,11 +76,15 @@
     <orderEntry type="library" scope="PROVIDED" name="rdoc (v6.13.1, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="regexp_parser (v2.11.2, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="reline (v0.6.1, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.13.1, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.13.5, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.13.5, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.13.5, rbenv: 3.3.6) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.13.5, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rubocop (v1.79.2, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rubocop-ast (v1.46.0, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rubocop-packaging (v0.6.0, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rubocop-performance (v1.25.0, rbenv: 3.3.6) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rubocop-rake (v0.7.1, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="securerandom (v0.4.1, rbenv: 3.3.6) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="stringio (v3.1.6, rbenv: 3.3.6) [gem]" level="application" />

data/.rubocop.yml

@@ -0,0 +1,102 @@
+# .rubocop.yml — JetstreamBridge gem
+# Focused for a Ruby gem: Packaging, Bundler, Rake, Performance, RSpec.
+
+plugins:
+  - rubocop-performance
+  - rubocop-packaging
+
+# If you keep a generated TODO, uncomment:
+# inherit_from:
+#   - .rubocop_todo.yml
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.7   # match gemspec minimum to avoid false positives
+  Exclude:
+    - 'bin/*'
+    - 'pkg/**/*'
+    - 'tmp/**/*'
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+
+# ---------- Layout & Style ----------
+Layout/LineLength:
+  Max: 100
+  Exclude:
+    - 'spec/**/*'   # allow longer expectation/setup lines
+
+Style/Documentation:
+  Enabled: false    # don’t force top-level docs for every class/module in a gem
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+  ConsistentQuotesInMultiline: true
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: either
+
+# ---------- Metrics (balanced for libs) ----------
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+    - 'tasks/**/*.rake'
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/jetstream_bridge/**/publisher*.rb'
+    - 'lib/jetstream_bridge/**/consumer*.rb'
+
+Metrics/AbcSize:
+  Max: 25
+  Exclude:
+    - 'lib/jetstream_bridge/**/publisher*.rb'
+    - 'lib/jetstream_bridge/**/consumer*.rb'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+# Optional: relax just for low-level I/O integration code
+# (you can delete this once you refactor)
+
+# ---------- Packaging / Gemspec ----------
+# These ship with RuboCop core and rubocop-packaging
+Gemspec/RequiredRubyVersion:
+  Enabled: true   # aligns with your gemspec `required_ruby_version`
+
+Gemspec/DevelopmentDependencies:
+  Enabled: true
+
+Packaging/BundlerSetupInTests:
+  Enabled: true
+
+Packaging/RequireRelativeHardcodingLib:
+  Enabled: true
+
+# ---------- Bundler ----------
+Bundler/DuplicatedGem:
+  Enabled: true
+
+Bundler/InsecureProtocolSource:
+  Enabled: true
+
+Bundler/GemComment:
+  Enabled: false
+
+# ---------- Performance ----------
+Performance/Detect:
+  Enabled: true
+Performance/RedundantMerge:
+  Enabled: true
+Performance/FixedSize:
+  Enabled: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jetstream_bridge (1.5.0)
+    jetstream_bridge (1.7.0)
       activerecord (>= 6.0)
       activesupport (>= 6.0)
       nats-pure (~> 2.4)
@@ -234,9 +234,6 @@ GEM
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-rake (0.7.1)
-      lint_roller (~> 1.1)
-      rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     stringio (3.1.6)
@@ -268,7 +265,6 @@ DEPENDENCIES
   rubocop (~> 1.66)
   rubocop-packaging (~> 0.5)
   rubocop-performance (~> 1.21)
-  rubocop-rake (~> 0.6)
 
 BUNDLED WITH
    2.6.3

data/README.md

@@ -1,18 +1,21 @@
 # Jetstream Bridge
 
 **Production-safe realtime data bridge** between systems using **NATS JetStream**.
-Includes durable consumers, backpressure, retries, **DLQ**, and optional **Inbox/Outbox** for end-to-end reliability.
+Includes durable consumers, backpressure, retries, **DLQ**, optional **Inbox/Outbox**, and **overlap-safe stream provisioning**.
 
 ---
 
 ## ✨ Features
 
-- 🔌 Simple **Publisher** and **Consumer** interfaces
-- 🛡 **Outbox** (reliable send) & **Inbox** (idempotent receive)
-- 🧨 **DLQ** for poison messages
-- ⚙️ Durable `pull_subscribe` with exponential backoff & `max_deliver`
-- 🎯 Configurable **source** and **destination** applications
-- 📊 Built-in observability
+* 🔌 Simple **Publisher** and **Consumer** interfaces
+* 🛡 **Outbox** (reliable send) & **Inbox** (idempotent receive), opt-in
+* 🧨 **DLQ** for poison messages
+* ⚙️ Durable `pull_subscribe` with backoff & `max_deliver`
+* 🎯 Clear **source/destination** subject conventions
+* 🧱 **Overlap-safe stream ensure** (prevents “subjects overlap” BadRequest)
+* 🚂 **Rails generators** for initializer & migrations, plus an install **rake task**
+* ⚡️ **Eager-loaded models** via Railtie (production)
+* 📊 Built-in logging for visibility
 
 ---
 
@@ -29,36 +32,67 @@ bundle install
 
 ---
 
+## 🧰 Rails Generators & Rake Task
+
+From your Rails app:
+
+```bash
+# Create initializer + migrations
+bin/rails g jetstream_bridge:install
+
+# Or run them separately:
+bin/rails g jetstream_bridge:initializer
+bin/rails g jetstream_bridge:migrations
+
+# Rake task (does both initializer + migrations)
+bin/rake jetstream_bridge:install
+```
+
+Then:
+
+```bash
+bin/rails db:migrate
+```
+
+> The generators create:
+>
+> * `config/initializers/jetstream_bridge.rb`
+> * `db/migrate/*_create_jetstream_outbox_events.rb`
+> * `db/migrate/*_create_jetstream_inbox_events.rb`
+
+---
+
 ## 🔧 Configure (Rails)
 
 ```ruby
 # config/initializers/jetstream_bridge.rb
 JetstreamBridge.configure do |config|
-  # NATS Connection
+  # NATS connection
   config.nats_urls       = ENV.fetch("NATS_URLS", "nats://localhost:4222")
-  config.env             = ENV.fetch("NATS_ENV", "development")
-  config.app_name        = ENV.fetch("APP_NAME", "app")
-  config.destination_app = ENV["DESTINATION_APP"]
+  config.env             = ENV.fetch("NATS_ENV",  "development")
+  config.app_name        = ENV.fetch("APP_NAME",  "app")
+  config.destination_app = ENV["DESTINATION_APP"] # required
 
-  # Consumer Tuning
+  # Consumer tuning
   config.max_deliver = 5
   config.ack_wait    = "30s"
   config.backoff     = %w[1s 5s 15s 30s 60s]
 
-  # Reliability Features
+  # Reliability features (opt-in)
   config.use_outbox = true
   config.use_inbox  = true
   config.use_dlq    = true
 
-  # Models (override if custom)
+  # Models (override if you use custom AR classes/table names)
   config.outbox_model = "JetstreamBridge::OutboxEvent"
   config.inbox_model  = "JetstreamBridge::InboxEvent"
 end
 ```
 
-> **Note:**
-> - `stream_name` defaults to `{env}-stream-bridge`
-> - `dlq_subject` defaults to `data.sync.dlq`
+> **Defaults:**
+>
+> * `stream_name` → `#{env}-jetstream-bridge-stream`
+> * `dlq_subject` → `#{env}.data.sync.dlq`
 
 ---
 
@@ -70,50 +104,73 @@ end
 | **Subscribe** | `{env}.data.sync.{dest}.{app}` |
 | **DLQ**       | `{env}.data.sync.dlq`          |
 
-- `{app}`: Your `app_name`
-- `{dest}`: Your `destination_app`
-- `{env}`: Your `env``
+* `{app}`: `app_name`
+* `{dest}`: `destination_app`
+* `{env}`: `env`
 
 ---
 
-## 🗃 Database Setup (Inbox/Outbox)
+## 🧱 Stream Topology (auto-ensure & overlap-safe)
 
-Run the installer:
+On first connection, Jetstream Bridge **ensures** a single stream exists for your `env` and that it covers:
 
-```bash
-rails jetstream_bridge:install --all
-```
+* `source_subject` (`{env}.data.sync.{app}.{dest}`)
+* `destination_subject` (`{env}.data.sync.{dest}.{app}`)
+* `dlq_subject` (if enabled)
+
+It’s **overlap-safe**:
+
+* Skips adding subjects already covered by existing wildcards
+* Pre-filters subjects owned by other streams to avoid `BadRequest: subjects overlap with an existing stream`
+* Retries once on concurrent races, then logs and continues safely
+
+---
+
+## 🗃 Database Setup (Inbox / Outbox)
 
-This creates:
+Inbox/Outbox are **optional**. The library detects columns at runtime and only sets what exists, so you can start minimal and evolve later.
 
-1. **Initializer** (`config/initializers/jetstream_bridge.rb`)
-2. **Migrations** (if enabled):
+### Generator-created tables (recommended)
 
 ```ruby
-# Outbox
+# jetstream_outbox_events
 create_table :jetstream_outbox_events do |t|
-  t.string  :resource_type, null: false
-  t.string  :resource_id,   null: false
-  t.string  :event_type,    null: false
-  t.jsonb   :payload,       null: false, default: {}
-  t.datetime :published_at
-  t.integer  :attempts,     default: 0
-  t.text     :last_error
+  t.string  :event_id, null: false
+  t.string  :subject,  null: false
+  t.jsonb   :payload,  null: false, default: {}
+  t.jsonb   :headers,  null: false, default: {}
+  t.string  :status,   null: false, default: "pending" # pending|publishing|sent|failed
+  t.integer :attempts, null: false, default: 0
+  t.text    :last_error
+  t.datetime :enqueued_at
+  t.datetime :sent_at
   t.timestamps
 end
-add_index :jetstream_outbox_events, [:resource_type, :resource_id]
+add_index :jetstream_outbox_events, :event_id, unique: true
+add_index :jetstream_outbox_events, :status
 
-# Inbox
+# jetstream_inbox_events
 create_table :jetstream_inbox_events do |t|
-  t.string   :event_id,  null: false
-  t.string   :subject,   null: false
+  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
-  t.text     :error
   t.timestamps
 end
-add_index :jetstream_inbox_events, :event_id, unique: true
+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'
+add_index :jetstream_inbox_events, :status
 ```
 
+> Already have different table names? Point the config to your AR classes via `config.outbox_model` / `config.inbox_model`.
+
 ---
 
 ## 📤 Publish Events
@@ -122,33 +179,20 @@ add_index :jetstream_inbox_events, :event_id, unique: true
 publisher = JetstreamBridge::Publisher.new
 publisher.publish(
   resource_type: "user",
-  resource_id:   "01H1234567890ABCDEF",
   event_type:    "created",
-  payload:       { id: "01H...", name: "Ada" }
+  payload:       { id: "01H...", name: "Ada" },  # resource_id inferred from payload[:id] / payload["id"]
+  # optional:
+  # event_id: "uuid-or-ulid",
+  # trace_id: "hex",
+  # occurred_at: Time.now.utc
 )
 ```
 
-> **Ephemeral Mode** (for short-lived scripts):
-> ```ruby
-> JetstreamBridge::Publisher.new(persistent: false).publish(...)
-> ```
+If **Outbox** is enabled, the publish call:
 
----
-
-## 🔄 Outbox (If Enabled)
-
-Events are written to the Outbox table. Flush periodically:
-
-```ruby
-# app/jobs/outbox_flush_job.rb
-class OutboxFlushJob < ApplicationJob
-  def perform
-    JetstreamBridge::Publisher.new.flush_outbox
-  end
-end
-```
-
-Schedule this job to run every minute.
+* Upserts an outbox row by `event_id`
+* Publishes with `Nats-Msg-Id` (idempotent)
+* Marks status `sent` or records `failed` with `last_error`
 
 ---
 
@@ -160,54 +204,95 @@ JetstreamBridge::Consumer.new(
   batch_size:   25
 ) do |event, subject, deliveries|
   # Your idempotent domain logic here
-  UserCreatedHandler.call(event.payload)
+  # `event` is the parsed envelope hash
+  UserCreatedHandler.call(event["payload"])
 end.run!
 ```
 
+If **Inbox** is enabled, the consumer:
+
+* Dedupes by `event_id` (falls back to stream sequence if needed)
+* Records processing state, errors, and timestamps
+* Skips already-processed messages (acks immediately)
+
 ---
 
 ## 📬 Envelope Format
 
-Published events include:
-
 ```json
 {
   "event_id":       "01H1234567890ABCDEF",
   "schema_version": 1,
+  "event_type":     "created",
   "producer":       "myapp",
   "resource_type":  "user",
   "resource_id":    "01H1234567890ABCDEF",
-  "event_type":     "created",
   "occurred_at":    "2025-08-13T21:00:00Z",
   "trace_id":       "abc123",
   "payload":        { "id": "01H...", "name": "Ada" }
 }
 ```
 
+* `resource_id` is inferred from `payload.id` when publishing.
+
+---
+
+## 🧨 Dead-Letter Queue (DLQ)
+
+When enabled, the topology ensures the DLQ subject exists:
+**`{env}.data.sync.dlq`**
+
+You may run a separate process to subscribe and triage messages that exceed `max_deliver` or are NAK’ed to the DLQ.
+
 ---
 
 ## 🛠 Operations Guide
 
 ### Monitoring
-- **Consumer Lag**: `nats consumer info <stream> <durable>`
-- **Outbox Growth**: Alert if `jetstream_outbox_events` grows unexpectedly
-- **DLQ Messages**: Monitor `data.sync.dlq` subscription
+
+* **Consumer lag**: `nats consumer info <stream> <durable>`
+* **DLQ volume**: subscribe/metrics on `{env}.data.sync.dlq`
+* **Outbox backlog**: alert on `jetstream_outbox_events` with `status != 'sent'` and growing count
 
 ### Scaling
-- Run consumers in **separate processes/containers**
-- Scale independently of web workers
+
+* Run consumers in **separate processes/containers**
+* Scale consumers independently from web
+* Tune `batch_size`, `ack_wait`, `max_deliver`, and `backoff`
+
+### Health check
+
+* Force-connect & ensure topology at boot or in a check:
+
+  ```ruby
+  JetstreamBridge.ensure_topology!
+  ```
 
 ### When to Use
-- **Inbox**: When replays or duplicates are possible
-- **Outbox**: When "DB commit ⇒ event published" guarantee is required
+
+* **Inbox**: you need idempotent processing and replay safety
+* **Outbox**: you want “DB commit ⇒ event published (or recorded for retry)” guarantees
+
+---
+
+## 🧩 Troubleshooting
+
+* **`subjects overlap with an existing stream`**
+  The library pre-filters overlapping subjects and retries once. If another team owns a broad wildcard (e.g., `env.data.sync.>`), coordinate subject boundaries.
+
+* **Consumer exists with mismatched filter**
+  The library detects and recreates the durable with the desired filter subject.
+
+* **Repeated redeliveries**
+  Increase `ack_wait`, review handler acks/NACKs, or move poison messages to DLQ.
 
 ---
 
 ## 🚀 Getting Started
 
-1. Install the gem 
-2. Configure the initializer 
-3. Run migrations: `rails db:migrate`
+1. Add the gem & run `bundle install`
+2. `bin/rails g jetstream_bridge:install`
+3. `bin/rails db:migrate`
 4. Start publishing/consuming!
 
 ---

data/jetstream_bridge.gemspec

@@ -25,13 +25,13 @@ Gem::Specification.new do |spec|
 
   # Rich metadata for RubyGems.org
   spec.metadata = {
-    'homepage_uri'         => 'https://github.com/attaradev/jetstream_bridge',
-    'source_code_uri'      => 'https://github.com/attaradev/jetstream_bridge',
-    'changelog_uri'        => 'https://github.com/attaradev/jetstream_bridge/blob/main/CHANGELOG.md',
-    'documentation_uri'    => 'https://github.com/attaradev/jetstream_bridge#readme',
-    'bug_tracker_uri'      => 'https://github.com/attaradev/jetstream_bridge/issues',
-    'github_repo'          => 'ssh://github.com/attaradev/jetstream_bridge',
-    'rubygems_mfa_required'=> 'true'
+    'homepage_uri' => 'https://github.com/attaradev/jetstream_bridge',
+    'source_code_uri' => 'https://github.com/attaradev/jetstream_bridge',
+    'changelog_uri' => 'https://github.com/attaradev/jetstream_bridge/blob/main/CHANGELOG.md',
+    'documentation_uri' => 'https://github.com/attaradev/jetstream_bridge#readme',
+    'bug_tracker_uri' => 'https://github.com/attaradev/jetstream_bridge/issues',
+    'github_repo' => 'ssh://github.com/attaradev/jetstream_bridge',
+    'rubygems_mfa_required' => 'true'
   }
 
   # Safer file list for published gem
@@ -51,11 +51,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'rails',         '>= 6.0'
 
   # Development / quality dependencies
+  spec.add_development_dependency 'bundler-audit',       '>= 0.9.1'
   spec.add_development_dependency 'rake',                '>= 13.0'
   spec.add_development_dependency 'rspec',               '>= 3.12'
   spec.add_development_dependency 'rubocop',             '~> 1.66'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.21'
-  spec.add_development_dependency 'rubocop-rake',        '~> 0.6'
   spec.add_development_dependency 'rubocop-packaging',   '~> 0.5'
-  spec.add_development_dependency 'bundler-audit',       '>= 0.9.1'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.21'
 end

data/lib/generators/jetstream_bridge/initializer/initializer_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module JetstreamBridge
+  module Generators
+    class InitializerGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates config/initializers/jetstream_bridge.rb'
+
+      def create_initializer
+        template 'jetstream_bridge.rb', 'config/initializers/jetstream_bridge.rb'
+      end
+    end
+  end
+end

data/lib/generators/jetstream_bridge/initializer/templates/jetstream_bridge.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Jetstream Bridge configuration
+JetstreamBridge.configure do |config|
+  # NATS Connection
+  config.nats_urls       = ENV.fetch('NATS_URLS', 'nats://localhost:4222')
+  config.env             = ENV.fetch('NATS_ENV',  Rails.env)
+  config.app_name        = ENV.fetch('APP_NAME',  Rails.application.class.module_parent_name.underscore)
+  config.destination_app = ENV['DESTINATION_APP'] # required for cross-app data sync
+
+  # Consumer Tuning
+  config.max_deliver = 5
+  config.ack_wait    = '30s'
+  config.backoff     = %w[1s 5s 15s 30s 60s]
+
+  # Reliability Features
+  config.use_outbox = false
+  config.use_inbox  = false
+  config.use_dlq    = true
+
+  # Models (override if you keep custom AR classes)
+  config.outbox_model = 'JetstreamBridge::OutboxEvent'
+  config.inbox_model  = 'JetstreamBridge::InboxEvent'
+end

data/lib/generators/jetstream_bridge/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module JetstreamBridge
+  module Generators
+    # Install generator.
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Creates JetstreamBridge initializer and migrations'
+      def create_initializer
+        Rails::Generators.invoke('jetstream_bridge:initializer', [], behavior: behavior, destination_root: destination_root)
+      end
+
+      def create_migrations
+        Rails::Generators.invoke('jetstream_bridge:migrations', [], behavior: behavior, destination_root: destination_root)
+      end
+    end
+  end
+end