jetstream_bridge 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52210d5d38366eed432001bc5ae522574a09fa73e5327e6509fc2a3983d7e2f5
-  data.tar.gz: fc9b02992b70a4584396177226cb1c21a83a87c96384d227825d6ffa9dcab958
+  metadata.gz: 0e0d3ee00b372ffe54ceca93b81a7c573385f6b85f16f584f15e8c5eef82cd44
+  data.tar.gz: b56fa1bc39e3b598719bced5b0be60172cd953214bee399c00341fd1f2d00906
 SHA512:
-  metadata.gz: bbb2379b20b45f15f5fded1bd4da19a0b5b2e12ba6df321e66b6a15bf00bb2be292dc8b4ec379d0223508c145689d8374531512d757a72cb397474d1794339ef
-  data.tar.gz: 119109cd2c60ab8885f8a47d33d7fb9e4e74a91ee39217bc1cfcbf13e6e4d5e64ebb7bfe8b7b1fcc4f4df39c72f12972b2e675d85e85a869c40d1ef92b106b8d
+  metadata.gz: 342b6b3431d3768b843060402ededa4dcca39100c1d0c005153a3ea4f758a9ab6aff9a09e5d608444acbb332766cfb926f3c1555afb8d9df882cfcdb7a8b405f
+  data.tar.gz: eb257f387a461444121cb304c36e9fa3ce13062c81a8bc43c0cda4e6f6c706c2efa8cc7a4cf3fdfc721cedeab1d11f0ca8bb00e943644c01575d051f5e143c19

data/.idea/dictionaries/project.xml

@@ -1,6 +1,7 @@
 <component name="ProjectDictionaryState">
   <dictionary name="project">
     <words>
+      <w>acks</w>
       <w>activesupport</w>
       <w>backoffs</w>
       <w>dedup</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.6.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

@@ -13,6 +13,8 @@ Includes durable consumers, backpressure, retries, **DLQ**, optional **Inbox/Out
 * ⚙️ 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
 
 ---
@@ -30,6 +32,36 @@ 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
@@ -88,25 +120,25 @@ On first connection, Jetstream Bridge **ensures** a single stream exists for you
 
 It’s **overlap-safe**:
 
-* Skips adding subjects already covered by existing wildcards.
-* Pre-filters subjects that belong to *other* streams to avoid `BadRequest: subjects overlap with an existing stream`.
-* Retries once on concurrent races, then logs and continues safely.
+* 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)
 
-Inbox/Outbox are **optional**. The library detects columns at runtime and only sets those that exist, so you can start minimal and evolve later.
+Inbox/Outbox are **optional**. The library detects columns at runtime and only sets what exists, so you can start minimal and evolve later.
 
-### Minimal schemas (recommended starting point)
+### Generator-created tables (recommended)
 
 ```ruby
-# db/migrate/xxxx_create_outbox_events.rb
-create_table :outbox_events do |t|
-  t.string  :event_id, null: false, index: { unique: true }
+# jetstream_outbox_events
+create_table :jetstream_outbox_events do |t|
+  t.string  :event_id, null: false
   t.string  :subject,  null: false
-  t.jsonb   :payload,  null: false, default: {}   # stored envelope or payload
-  t.jsonb   :headers,  null: false, default: {}   # e.g., { "Nats-Msg-Id": ... }
+  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
@@ -114,26 +146,30 @@ create_table :outbox_events do |t|
   t.datetime :sent_at
   t.timestamps
 end
-
-# db/migrate/xxxx_create_inbox_events.rb
-create_table :inbox_events do |t|
-  t.string   :event_id, index: { unique: true }   # dedupe key (preferred)
-  t.string   :subject,  null: false
-  t.jsonb    :payload,  null: false, default: {}
-  t.jsonb    :headers,  null: false, default: {}
+add_index :jetstream_outbox_events, :event_id, unique: true
+add_index :jetstream_outbox_events, :status
+
+# jetstream_inbox_events
+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.string   :status,      null: false, default: "received" # received|processing|processed|failed
   t.text     :last_error
   t.datetime :received_at
   t.datetime :processed_at
   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'
+add_index :jetstream_inbox_events, :status
 ```
 
-> Already have tables named differently (e.g., `jetstream_outbox_events`)?
-> Set `config.outbox_model` / `config.inbox_model` to your AR class names.
+> Already have different table names? Point the config to your AR classes via `config.outbox_model` / `config.inbox_model`.
 
 ---
 
@@ -152,11 +188,11 @@ publisher.publish(
 )
 ```
 
-* If **Outbox** is enabled, the publish call:
+If **Outbox** is enabled, the publish call:
 
-    * Upserts an outbox row by `event_id`
-    * Publishes with `Nats-Msg-Id` (idempotent)
-    * Marks status `sent` or records `failed` with `last_error`
+* Upserts an outbox row by `event_id`
+* Publishes with `Nats-Msg-Id` (idempotent)
+* Marks status `sent` or records `failed` with `last_error`
 
 ---
 
@@ -164,7 +200,7 @@ publisher.publish(
 
 ```ruby
 JetstreamBridge::Consumer.new(
-  durable_name: "#{Rails.env}-peerapp-consumers",
+  durable_name: "#{Rails.env}-peerapp-events",
   batch_size:   25
 ) do |event, subject, deliveries|
   # Your idempotent domain logic here
@@ -173,11 +209,11 @@ JetstreamBridge::Consumer.new(
 end.run!
 ```
 
-* If **Inbox** is enabled, the consumer:
+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)
+* Dedupes by `event_id` (falls back to stream sequence if needed)
+* Records processing state, errors, and timestamps
+* Skips already-processed messages (acks immediately)
 
 ---
 
@@ -216,7 +252,7 @@ You may run a separate process to subscribe and triage messages that exceed `max
 
 * **Consumer lag**: `nats consumer info <stream> <durable>`
 * **DLQ volume**: subscribe/metrics on `{env}.data.sync.dlq`
-* **Outbox backlog**: alert on `outbox_events` with `status != 'sent'` and growing count
+* **Outbox backlog**: alert on `jetstream_outbox_events` with `status != 'sent'` and growing count
 
 ### Scaling
 
@@ -224,6 +260,14 @@ You may run a separate process to subscribe and triage messages that exceed `max
 * 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**: you need idempotent processing and replay safety
@@ -247,8 +291,8 @@ You may run a separate process to subscribe and triage messages that exceed `max
 ## 🚀 Getting Started
 
 1. Add the gem & run `bundle install`
-2. Create the initializer
-3. (Optional) Add Inbox/Outbox migrations and models
+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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module JetstreamBridge
+  module Generators
+    # Migrations generator.
+    class MigrationsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates Inbox/Outbox migrations for JetstreamBridge'
+
+      def create_outbox_migration
+        name = 'create_jetstream_outbox_events'
+        return say_status :skip, "migration #{name} already exists", :yellow if migration_exists?('db/migrate', name)
+
+        migration_template 'create_jetstream_outbox_events.rb.erb', "db/migrate/#{name}.rb"
+      end
+
+      def create_inbox_migration
+        name = 'create_jetstream_inbox_events'
+        return say_status :skip, "migration #{name} already exists", :yellow if migration_exists?('db/migrate', name)
+
+        migration_template 'create_jetstream_inbox_events.rb.erb', "db/migrate/#{name}.rb"
+      end
+
+      # -- Rails::Generators::Migration plumbing --
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime('%Y%m%d%H%M%S')
+        else
+          format('%.3d', current_migration_number(dirname) + 1)
+        end
+      end
+
+      private
+
+      def migration_exists?(dirname, file_name)
+        Dir.glob(File.join(dirname, '[0-9]*_*.rb')).grep(/\d+_#{file_name}\.rb$/).any?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateJetstreamInboxEvents < ActiveRecord::Migration[7.0]
+  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
+      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'
+    add_index :jetstream_inbox_events, :status
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateJetstreamOutboxEvents < ActiveRecord::Migration[7.0]
+  def change
+    create_table :jetstream_outbox_events do |t|
+      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, :event_id, unique: true
+    add_index :jetstream_outbox_events, :status
+  end
+end

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require_relative '../core/connection'
+require_relative '../core/duration'
+require_relative '../core/logging'
+require_relative '../core/config'
+require_relative '../core/model_utils'
+require_relative 'consumer_config'
+require_relative 'message_processor'
+require_relative 'subscription_manager'
+require_relative 'inbox/inbox_processor'
+
+module JetstreamBridge
+  # Subscribes to "{env}.data.sync.{dest}.{app}" and processes messages.
+  class Consumer
+    DEFAULT_BATCH_SIZE = 25
+    FETCH_TIMEOUT_SECS = 5
+    IDLE_SLEEP_SECS    = 0.05
+
+    def initialize(durable_name:, batch_size: DEFAULT_BATCH_SIZE, &block)
+      @handler    = block
+      @batch_size = batch_size
+      @durable    = durable_name
+      @jts        = Connection.connect!
+
+      ensure_destination!
+
+      @sub_mgr = SubscriptionManager.new(@jts, @durable, JetstreamBridge.config)
+      @sub_mgr.ensure_consumer!
+      @psub       = @sub_mgr.subscribe!
+
+      @processor  = MessageProcessor.new(@jts, @handler)
+      @inbox_proc = InboxProcessor.new(@processor) if JetstreamBridge.config.use_inbox
+    end
+
+    def run!
+      Logging.info("Consumer #{@durable} started…", tag: 'JetstreamBridge::Consumer')
+      loop do
+        processed = process_batch
+        sleep(IDLE_SLEEP_SECS) if processed.zero?
+      end
+    end
+
+    private
+
+    def ensure_destination!
+      return unless JetstreamBridge.config.destination_app.to_s.empty?
+
+      raise ArgumentError, 'destination_app must be configured'
+    end
+
+    # Returns number of messages processed; 0 on timeout/idle or after recovery.
+    def process_batch
+      msgs = fetch_messages
+      process_messages(msgs)
+    rescue NATS::Timeout, NATS::IO::Timeout
+      0
+    rescue NATS::JetStream::Error => e
+      handle_js_error(e)
+    end
+
+    # --- helpers ---
+
+    def fetch_messages
+      @psub.fetch(@batch_size, timeout: FETCH_TIMEOUT_SECS)
+    end
+
+    def process_messages(msgs)
+      msgs.sum { |m| process_one(m) }
+    end
+
+    def process_one(m)
+      if @inbox_proc
+        @inbox_proc.process(m) ? 1 : 0
+      else
+        @processor.handle_message(m)
+        1
+      end
+    end
+
+    def handle_js_error(e)
+      if recoverable_consumer_error?(e)
+        Logging.warn("Recovering subscription after error: #{e.class} #{e.message}",
+                     tag: 'JetstreamBridge::Consumer')
+        @sub_mgr.ensure_consumer!
+        @psub = @sub_mgr.subscribe!
+      else
+        Logging.error("Fetch failed: #{e.class} #{e.message}",
+                      tag: 'JetstreamBridge::Consumer')
+      end
+      0
+    end
+
+    def recoverable_consumer_error?(error)
+      msg = error.message.to_s
+      msg =~ /consumer.*(not\s+found|deleted)/i ||
+        msg =~ /no\s+responders/i ||
+        msg =~ /stream.*not\s+found/i
+    end
+  end
+end