jetstream_bridge 2.2.1 → 2.4.0

data/Gemfile.lock

@@ -1,268 +0,0 @@
-PATH
-  remote: .
-  specs:
-    jetstream_bridge (2.2.1)
-      activerecord (>= 6.0)
-      activesupport (>= 6.0)
-      nats-pure (~> 2.4)
-      rails (>= 6.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    actioncable (8.0.2)
-      actionpack (= 8.0.2)
-      activesupport (= 8.0.2)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-      zeitwerk (~> 2.6)
-    actionmailbox (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-    actionmailer (8.0.2)
-      actionpack (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-      rails-dom-testing (~> 2.2)
-    actionpack (8.0.2)
-      actionview (= 8.0.2)
-      activesupport (= 8.0.2)
-      nokogiri (>= 1.8.5)
-      rack (>= 2.2.4)
-      rack-session (>= 1.0.1)
-      rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.2)
-      rails-html-sanitizer (~> 1.6)
-      useragent (~> 0.16)
-    actiontext (8.0.2)
-      actionpack (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.6.0)
-      nokogiri (>= 1.8.5)
-    actionview (8.0.2)
-      activesupport (= 8.0.2)
-      builder (~> 3.1)
-      erubi (~> 1.11)
-      rails-dom-testing (~> 2.2)
-      rails-html-sanitizer (~> 1.6)
-    activejob (8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.3.6)
-    activemodel (8.0.2)
-      activesupport (= 8.0.2)
-    activerecord (8.0.2)
-      activemodel (= 8.0.2)
-      activesupport (= 8.0.2)
-      timeout (>= 0.4.0)
-    activestorage (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activesupport (= 8.0.2)
-      marcel (~> 1.0)
-    activesupport (8.0.2)
-      base64
-      benchmark (>= 0.3)
-      bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.3.1)
-      connection_pool (>= 2.2.5)
-      drb
-      i18n (>= 1.6, < 2)
-      logger (>= 1.4.2)
-      minitest (>= 5.1)
-      securerandom (>= 0.3)
-      tzinfo (~> 2.0, >= 2.0.5)
-      uri (>= 0.13.1)
-    ast (2.4.3)
-    base64 (0.3.0)
-    benchmark (0.4.1)
-    bigdecimal (3.2.2)
-    builder (3.3.0)
-    bundler-audit (0.9.2)
-      bundler (>= 1.2.0, < 3)
-      thor (~> 1.0)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
-    crass (1.0.6)
-    date (3.4.1)
-    diff-lcs (1.6.2)
-    drb (2.2.3)
-    erubi (1.13.1)
-    globalid (1.2.1)
-      activesupport (>= 6.1)
-    i18n (1.14.7)
-      concurrent-ruby (~> 1.0)
-    io-console (0.8.0)
-    irb (1.15.2)
-      pp (>= 0.6.0)
-      rdoc (>= 4.0.0)
-      reline (>= 0.4.2)
-    json (2.13.2)
-    language_server-protocol (3.17.0.5)
-    lint_roller (1.1.0)
-    logger (1.7.0)
-    loofah (2.24.0)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.12.0)
-    mail (2.8.1)
-      mini_mime (>= 0.1.1)
-      net-imap
-      net-pop
-      net-smtp
-    marcel (1.0.4)
-    mini_mime (1.1.5)
-    mini_portile2 (2.8.9)
-    minitest (5.25.5)
-    nats-pure (2.5.0)
-      base64
-      concurrent-ruby (~> 1.0)
-      json
-      securerandom
-      uri
-    net-imap (0.5.6)
-      date
-      net-protocol
-    net-pop (0.1.2)
-      net-protocol
-    net-protocol (0.2.2)
-      timeout
-    net-smtp (0.5.1)
-      net-protocol
-    nio4r (2.7.4)
-    nokogiri (1.18.7)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
-    nokogiri (1.18.7-arm64-darwin)
-      racc (~> 1.4)
-    parallel (1.27.0)
-    parser (3.3.9.0)
-      ast (~> 2.4.1)
-      racc
-    pp (0.6.2)
-      prettyprint
-    prettyprint (0.2.0)
-    prism (1.4.0)
-    psych (5.2.3)
-      date
-      stringio
-    racc (1.8.1)
-    rack (3.1.13)
-    rack-session (2.1.0)
-      base64 (>= 0.1.0)
-      rack (>= 3.0.0)
-    rack-test (2.2.0)
-      rack (>= 1.3)
-    rackup (2.2.1)
-      rack (>= 3)
-    rails (8.0.2)
-      actioncable (= 8.0.2)
-      actionmailbox (= 8.0.2)
-      actionmailer (= 8.0.2)
-      actionpack (= 8.0.2)
-      actiontext (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activemodel (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      bundler (>= 1.15.0)
-      railties (= 8.0.2)
-    rails-dom-testing (2.2.0)
-      activesupport (>= 5.0.0)
-      minitest
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.6.2)
-      loofah (~> 2.21)
-      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
-    railties (8.0.2)
-      actionpack (= 8.0.2)
-      activesupport (= 8.0.2)
-      irb (~> 1.13)
-      rackup (>= 1.0.0)
-      rake (>= 12.2)
-      thor (~> 1.0, >= 1.2.2)
-      zeitwerk (~> 2.6)
-    rainbow (3.1.1)
-    rake (13.2.1)
-    rdoc (6.13.1)
-      psych (>= 4.0.0)
-    regexp_parser (2.11.2)
-    reline (0.6.1)
-      io-console (~> 0.5)
-    rspec (3.13.1)
-      rspec-core (~> 3.13.0)
-      rspec-expectations (~> 3.13.0)
-      rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
-      rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.5)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.13.0)
-    rspec-support (3.13.5)
-    rubocop (1.79.2)
-      json (~> 2.3)
-      language_server-protocol (~> 3.17.0.2)
-      lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
-      parser (>= 3.3.0.2)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
-      parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-packaging (0.6.0)
-      lint_roller (~> 1.1.0)
-      rubocop (>= 1.72.1, < 2.0)
-    rubocop-performance (1.25.0)
-      lint_roller (~> 1.1)
-      rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
-    ruby-progressbar (1.13.0)
-    securerandom (0.4.1)
-    stringio (3.1.6)
-    thor (1.3.2)
-    timeout (0.4.3)
-    tzinfo (2.0.6)
-      concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.3)
-    useragent (0.16.11)
-    websocket-driver (0.7.7)
-      base64
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
-    zeitwerk (2.7.2)
-
-PLATFORMS
-  arm64-darwin-24
-  ruby
-  x86_64-linux
-
-DEPENDENCIES
-  bundler-audit (>= 0.9.1)
-  jetstream_bridge!
-  rake (>= 13.0)
-  rspec (>= 3.12)
-  rubocop (~> 1.66)
-  rubocop-packaging (~> 0.5)
-  rubocop-performance (~> 1.21)
-
-BUNDLED WITH
-   2.6.3

data/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Mike Attara
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

data/README.md

@@ -1,302 +0,0 @@
-# Jetstream Bridge
-
-**Production-safe realtime data bridge** between systems using **NATS JetStream**.
-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), 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
-
----
-
-## 📦 Install
-
-```ruby
-# Gemfile
-gem "jetstream_bridge", "~> 2.0"
-```
-
-```bash
-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
-  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"] # required
-
-  # Consumer tuning
-  config.max_deliver = 5
-  config.ack_wait    = "30s"
-  config.backoff     = %w[1s 5s 15s 30s 60s]
-
-  # Reliability features (opt-in)
-  config.use_outbox = true
-  config.use_inbox  = true
-  config.use_dlq    = true
-
-  # Models (override if you use custom AR classes/table names)
-  config.outbox_model = "JetstreamBridge::OutboxEvent"
-  config.inbox_model  = "JetstreamBridge::InboxEvent"
-end
-```
-
-> **Defaults:**
->
-> * `stream_name` → `#{env}-jetstream-bridge-stream`
-> * `dlq_subject` → `#{env}.data.sync.dlq`
-
----
-
-## 📡 Subject Conventions
-
-| Direction     | Subject Pattern           |
-|---------------|---------------------------|
-| **Publish**   | `{env}.{app}.sync.{dest}` |
-| **Subscribe** | `{env}.{dest}.sync.{app}` |
-| **DLQ**       | `{env}.sync.dlq`          |
-
-* `{app}`: `app_name`
-* `{dest}`: `destination_app`
-* `{env}`: `env`
-
----
-
-## 🧱 Stream Topology (auto-ensure and overlap-safe)
-
-On first connection, Jetstream Bridge **ensures** a single stream exists for your `env` and that it covers:
-
-* `source_subject` (`{env}.{app}.sync.{dest}`)
-* `destination_subject` (`{env}.{dest}.sync.{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)
-
-Inbox/Outbox are **optional**. The library detects columns at runtime and only sets what exists, so you can start minimal and evolve later.
-
-### Generator-created tables (recommended)
-
-```ruby
-# 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: {}
-  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
-
-# 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.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 different table names? Point the config to your AR classes via `config.outbox_model` / `config.inbox_model`.
-
----
-
-## 📤 Publish Events
-
-```ruby
-publisher = JetstreamBridge::Publisher.new
-publisher.publish(
-  resource_type: "user",
-  event_type:    "created",
-  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
-)
-```
-
-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`
-
----
-
-## 📥 Consume Events
-
-```ruby
-JetstreamBridge::Consumer.new(
-  durable_name: "#{Rails.env}-#{app_name}-workers",
-  batch_size:   25
-) do |event, subject, deliveries|
-  # Your idempotent domain logic here
-  # `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
-
-```json
-{
-  "event_id":       "01H1234567890ABCDEF",
-  "schema_version": 1,
-  "event_type":     "created",
-  "producer":       "myapp",
-  "resource_type":  "user",
-  "resource_id":    "01H1234567890ABCDEF",
-  "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>`
-* **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 consumers independently of 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
-* **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. Add the gem & run `bundle install`
-2. `bin/rails g jetstream_bridge:install`
-3. `bin/rails db:migrate`
-4. Start publishing/consuming!
-
----
-
-## 📄 License
-
-[MIT License](LICENSE)

data/jetstream_bridge.gemspec

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/jetstream_bridge/version'
-
-Gem::Specification.new do |spec|
-  spec.name                  = 'jetstream_bridge'
-  spec.version               = JetstreamBridge::VERSION
-  spec.authors               = ['Mike Attara']
-  spec.email                 = ['mpyebattara@gmail.com']
-
-  # Clear, value-focused copy
-  spec.summary     = 'Reliable realtime bridge over NATS JetStream for Rails/Ruby apps'
-  spec.description = <<~DESC.strip
-    Publisher/Consumer utilities for NATS JetStream with environment-scoped subjects,
-    overlap guards, DLQ routing, retries/backoff, and optional Inbox/Outbox patterns.
-    Includes topology setup helpers for production-safe operation.
-  DESC
-
-  spec.license     = 'MIT'
-  spec.homepage    = 'https://github.com/attaradev/jetstream_bridge'
-
-  # Ruby & RubyGems requirements
-  spec.required_ruby_version     = '>= 2.7.0'
-  spec.required_rubygems_version = '>= 3.3.0'
-
-  # 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'
-  }
-
-  # Safer file list for published gem
-  # (falls back to Dir[] if not in a git repo — e.g., CI tarballs)
-  spec.files = if system('git rev-parse --is-inside-work-tree > /dev/null 2>&1')
-                 `git ls-files -z`.split("\x0").reject { |f| f.start_with?('spec/fixtures/') }
-               else
-                 Dir['lib/**/*', 'README*', 'CHANGELOG*', 'LICENSE*']
-               end
-
-  spec.require_paths = ['lib']
-
-  # Runtime dependencies
-  spec.add_dependency 'activerecord',  '>= 6.0'
-  spec.add_dependency 'activesupport', '>= 6.0'
-  spec.add_dependency 'nats-pure',     '~> 2.4'
-  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-packaging',   '~> 0.5'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.21'
-end