JetStream Bridge Logo

CI Status Coverage Status Gem Version Downloads License

Production-ready NATS JetStream bridge for Ruby/Rails with outbox, inbox, DLQ, and overlap-safe stream provisioning.

Highlights

  • Transactional outbox and idempotent inbox (optional) for exactly-once pipelines.
  • Durable pull consumers with retries, backoff, and DLQ routing.
  • Auto stream/consumer provisioning with overlap protection.
  • Rails-native: generators, migrations, health check, and eager-loading safety.
  • Mock NATS for fast, no-infra testing.

Quick Start

# Gemfile
gem "jetstream_bridge", "~> 4.0"

bundle install
bin/rails g jetstream_bridge:install
bin/rails db:migrate

# config/initializers/jetstream_bridge.rb
JetstreamBridge.configure do |config|
  config.nats_urls       = ENV.fetch("NATS_URLS", "nats://localhost:4222")
  config.env             = ENV.fetch("RAILS_ENV", "development")
  config.app_name        = "my_app"
  config.destination_app = "worker_app"
  config.use_outbox = true
  config.use_inbox  = true
  config.use_dlq    = true
end

# Note: configure only sets options; it does not connect. In Rails the Railtie
# starts the bridge after initialization. In non-Rails apps call
# `JetstreamBridge.startup!` (or rely on auto-connect on first publish/subscribe).

Publish:

JetstreamBridge.publish(event_type: "user.created", resource_type: "user", payload: { id: 1 })

Consume:

consumer = JetstreamBridge::Consumer.new do |event|
  User.upsert({ id: event.payload["id"] })
end
consumer.run!

Documentation

License

MIT