jetstream_bridge 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8e7cce25c596230a2d068e4f3aca0bfdc7d5156c9fb724e34f094e97d8909f
-  data.tar.gz: 21c66a2c19cf8e6d49017efd53dd53f7d1ae2654bac2b0df3e9f6b8d137e11e9
+  metadata.gz: 2f7e89386a56dac571dddec4c9d5283a975a8354d17d8f953ba148d390d55652
+  data.tar.gz: 64d5a7ea6bfdf863ea6a24d7d922cfaca565247605860cd999d6c2a8c893f48d
 SHA512:
-  metadata.gz: 312c184a87c6d2b70e711c666b74f2a79a4c9d9afc29faf53776f46a906eab83e6ed2103d68e9f12e09cdb8b082c078f405769eeb13630adf998f9a498f82793
-  data.tar.gz: caeca3948e682aefb27f3de0617fba8d2558edb2c4a798ad732f16463a23a1bf586295918cb8a91cfddfef25b3b6b3df049a9ab84986b377f4da4f91080c9d67
+  metadata.gz: c95e0b2a4b829637f6c790cf13e710f814d085298949aadd141220d065cedc47dcd44a46fe8576b0cd280cd343cfd2a959ab4abb842fd0434cb817f9d70f9021
+  data.tar.gz: ebd5322b78df46177d3395c08674a822fd0cbf2a7111b7fbd7b4405f08ccaa7308d602ed0bcab862f4589730fe3a78c8b611c83d3eb0771eca199da31c0dc118

data/CHANGELOG.md

@@ -5,430 +5,185 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [4.4.0] - 2025-11-24
+## [4.5.0] - 2026-01-22
+
+### Added
+
+- Dedicated `HealthChecker` service for comprehensive health monitoring
+- `ConsumerHealthMonitor` for long-running consumer health tracking
+- Stream name configuration now required (no more auto-generated defaults)
 
 ### Changed
 
-- **RTT Measurement** - Enhanced NATS round-trip time measurement with fallback support
-  - Added automatic unit normalization (seconds to milliseconds) for RTT values
-  - Implemented fallback RTT measurement using `flush` for NATS clients without native `rtt` method
-  - Supports both nats-pure and other NATS client implementations
-  - Better compatibility across different NATS client versions
+- Refactored architecture with `Facade` pattern for cleaner API delegation
+- Consolidated connection management into `ConnectionManager`
+- Extracted health checking logic from connection layer into dedicated service
+- Simplified documentation focusing on library features over implementation details
+
+### Removed
+
+- Removed `Connection` (refactored to `ConnectionManager`)
+- Removed `BridgeHelpers` module (functionality distributed to appropriate layers)
+- Removed auto-generated stream names (explicit configuration required)
+
+## [4.4.1] - 2026-01-16
+
+### Fixed
+
+- Fixed Rails generator constant qualification to prevent NameError during load
+
+## [4.4.0] - 2025-11-24
+
+### Changed
 
-- **Rails Integration** - Improved Rake task detection reliability
-  - Changed from `defined?(::Rake)` check to `$PROGRAM_NAME` inspection
-  - More reliable detection of Rake execution context
-  - Prevents false positives when Rake is loaded but not executing
+- Enhanced NATS round-trip time measurement with automatic fallback for clients without native `rtt` method
+- Improved Rails Rake task detection using `$PROGRAM_NAME` inspection
 
 ### Fixed
 
-- **Test Coverage** - Comprehensive test suite improvements
-  - Added complete test coverage for Rails integration lifecycle methods
-  - Added tests for test helper matchers (`have_published`, `be_publish_success`, `be_publish_failure`)
-  - Added tests for fixture builders (`sample_event`, `sample_events`, `event`)
-  - Added test for RTT fallback behavior when client lacks `rtt` method
-  - Added spec file for `bridge_helpers` module
+- Expanded test coverage for Rails integration and test helpers
 
 ## [4.3.0] - 2025-11-24
 
 ### Added
 
-- **Connection Diagnostics** - Exposed reconnection error tracking for health checks
-  - `last_reconnect_error` and `last_reconnect_error_at` now publicly accessible
-  - Enables better monitoring and diagnostics of connection issues
-  - Added test coverage for diagnostic accessor visibility
+- Exposed reconnection error tracking via `last_reconnect_error` and `last_reconnect_error_at` for better diagnostics
 
 ### Changed
 
-- **Connection Lifecycle** - Improved topology management during startup
-  - `startup!` now explicitly ensures topology is created during initialization
-  - `connect_and_ensure_stream!` properly ensures topology after connecting
-  - `fetch_stream_info` now ensures connection is established before querying
-  - More reliable initialization sequence for non-Rails applications
-
-- **Rails Integration** - Changed console autostart behavior
-  - Rails console now autostarts JetStream Bridge by default (previously skipped)
-  - Simplified autostart logic by removing console detection as skip condition
-  - Autostart remains disabled only for rake tasks (unless forced with `JETSTREAM_BRIDGE_FORCE_AUTOSTART`)
-  - Better developer experience in Rails console for immediate testing
-
-- **Documentation** - Clarified connection initialization behavior
-  - Added notes explaining that `configure` only sets options and does not connect
-  - Documented when connection actually occurs (Rails: after initialization; non-Rails: call `startup!`)
-  - Improved explanation of `lazy_connect` behavior in Rails environments
-  - Added guidance for non-Rails applications to call `startup!` explicitly
+- Improved topology management during startup and connection initialization
+- Rails console now autostarts JetStream Bridge by default (autostart remains disabled for rake tasks)
+- Updated documentation to clarify connection initialization behavior
 
 ### Fixed
 
-- **Test Coverage** - Added missing test scenarios
-  - Added tests for topology ensuring in `startup!` and `connect_and_ensure_stream!`
-  - Added tests for connection initialization in `stream_info`
-  - Updated Rails integration specs to reflect new console behavior
+- Expanded test coverage for topology management and Rails integration
 
 ## [4.2.0] - 2025-11-24
 
 ### Added
 
-- **Modular Code Organization** - Restructured codebase with dedicated modules
-  - New `JetstreamBridge::Core` module for core utilities (connection, logging, model utils, helpers)
-  - New `JetstreamBridge::Rails` module for Rails-specific integration
-  - Improved separation of concerns and code discoverability
-  - Better namespace organization for future extensibility
-
-- **Enhanced Test Helpers** - Comprehensive testing utilities split into focused modules
-  - `JetstreamBridge::TestHelpers::Fixtures` - Convenient fixture generation for events and messages
-  - `JetstreamBridge::TestHelpers::IntegrationHelpers` - Full NATS message simulation for integration tests
-  - `JetstreamBridge::TestHelpers::Matchers` - RSpec matchers for event publishing assertions
-  - Improved test doubles with realistic NATS message structure
-  - Better support for testing event-driven Rails applications
-
-- **Getting Started Guide** - New comprehensive guide in `docs/GETTING_STARTED.md`
-  - Quick installation and setup instructions
-  - Publishing and consuming examples
-  - Rails integration patterns
-  - Links to advanced documentation
+- Restructured codebase with `JetstreamBridge::Core` and `JetstreamBridge::Rails` modules
+- Enhanced test helpers with fixtures, integration helpers, and RSpec matchers
+- New Getting Started guide in `docs/GETTING_STARTED.md`
 
 ### Changed
 
-- **Rails Integration** - Reorganized Rails-specific code
-  - Moved from single `lib/jetstream_bridge/railtie.rb` to dedicated `lib/jetstream_bridge/rails/` directory
-  - `JetstreamBridge::Rails::Railtie` - Rails lifecycle integration
-  - `JetstreamBridge::Rails::Integration` - Autostart logic and Rails environment detection
-  - Cleaner separation between gem core and Rails integration
-
-- **Documentation** - Restructured README for clarity
-  - Condensed README focusing on quick start and highlights
-  - Moved detailed guides to dedicated docs directory
-  - Improved navigation with links to specialized documentation
-  - More concise examples and clearer feature descriptions
-
-- **Gemspec** - Enhanced package configuration
-  - Added `docs/**/*.md` to distributed files
-  - Added `extra_rdoc_files` for better documentation
-  - Updated description to emphasize production-readiness
+- Reorganized Rails integration code into dedicated directory structure
+- Restructured README for clarity with focus on quick start
+- Enhanced gemspec with documentation files
 
 ### Fixed
 
-- **Code Quality** - Resolved all RuboCop style violations
-  - Fixed string literal consistency issues
-  - Improved code formatting and indentation
-  - Reduced complexity in conditional assignments
-  - Updated RuboCop configuration for new file structure
+- Resolved all RuboCop style violations
 
 ## [4.1.0] - 2025-11-23
 
 ### Added
 
-- **Enhanced Subject Validation** - Strengthened subject component validation for security
-  - Validates against control characters, null bytes, tabs, and excessive spaces
-  - Enforces maximum subject component length of 255 characters
-  - Prevents injection attacks via malformed subject components
-  - Provides clear error messages with invalid character details
-
-- **Health Check Rate Limiting** - Prevents abuse of health check endpoint
-  - Limits uncached health checks to once every 5 seconds per process
-  - Cached health checks (30s TTL) bypass rate limit
-  - Returns helpful error message with wait time when rate limit exceeded
-  - Thread-safe implementation with mutex synchronization
-
-- **Consumer Reconnection Backoff** - Exponential backoff for consumer recovery
-  - Starts at 0.1s and doubles with each retry up to 30s maximum
-  - Resets counter on successful reconnection
-  - Logs detailed reconnection attempts with backoff timing
-  - Prevents excessive NATS API calls during connection issues
-
-- **OverlapGuard Performance Cache** - 60-second TTL cache for stream metadata
-  - Reduces N+1 API calls when checking stream overlaps
-  - Thread-safe cache implementation with mutex
-  - Falls back to cached data on fetch errors
-  - Includes `clear_cache!` method for testing
-
-- **Consumer Memory Monitoring** - Health checks for long-running consumers
-  - Logs health status every 10 minutes (iterations, memory, uptime)
-  - Warns when memory usage exceeds 1GB
-  - Suggests garbage collection when heap grows large (>100k live objects)
-  - Cross-platform memory monitoring (Linux/macOS)
-
-- **Production Deployment Guide** - Comprehensive documentation in docs/PRODUCTION.md
-  - Database connection pool sizing guidelines
-  - NATS HA configuration examples
-  - Consumer tuning recommendations
-  - Monitoring and alerting best practices
-  - Kubernetes deployment examples with health probes
-  - Security hardening recommendations
-  - Performance optimization techniques
+- Enhanced subject validation to prevent injection attacks
+- Health check rate limiting (1 uncached request per 5 seconds)
+- Exponential backoff for consumer reconnection (0.1s to 30s)
+- 60-second TTL cache for OverlapGuard stream metadata
+- Consumer memory monitoring with automatic health logging
+- Production deployment guide in `docs/PRODUCTION.md`
 
 ### Changed
 
-- **Health Check API** - Added optional `skip_cache` parameter
-  - `JetstreamBridge.health_check(skip_cache: true)` forces fresh check
-  - Default behavior unchanged (uses 30s cache)
-  - Rate limited when `skip_cache` is true
+- Added `skip_cache` parameter to health check API
 
 ### Fixed
 
-- **Test Suite** - Fixed test failures in OverlapGuard specs
-  - Added cache clearing in test setup to prevent interference
-  - All 1220 tests passing with 93.32% line coverage
+- Fixed OverlapGuard test failures with proper cache clearing
 
 ## [4.0.4] - 2025-11-23
 
 ### Fixed
 
-- **NATS Compatibility** - Fix connection failure with nats-pure 2.5.0
-  - Handle both object-style and hash-style access for stream_info responses
-  - Fixes "undefined method 'streams' for Hash" error during connection establishment
-  - Adds compatibility checks using `respond_to?` for config and state attributes
-  - Updated 4 files: jetstream_bridge.rb, topology/stream.rb, topology/overlap_guard.rb, debug_helper.rb
-  - Maintains backward compatibility with older nats-pure versions
+- Fixed nats-pure 2.5.0 compatibility with hash-style stream_info responses
 
 ## [4.0.3] - 2025-11-23
 
 ### Added
 
-- **Connection Validation** - Comprehensive NATS URL validation on initialization
-  - Validates URL format, scheme (nats/nats+tls), host presence, and port range (1-65535)
-  - Verifies NATS connection established after connect
-  - Verifies JetStream availability with account info check
-  - Helpful error messages for common misconfigurations
-  - All validation errors include specific guidance for fixes
-
-- **Connection Logging** - Detailed logging throughout connection lifecycle
-  - Debug logs for URL validation progress and verification steps
-  - Info logs for successful validation and JetStream stats (streams, consumers, memory, storage)
-  - Error logs for all validation failures with specific details
-  - Automatic credential sanitization in all log messages
-  - Human-readable resource usage formatting (bytes to KB/MB/GB)
+- Comprehensive NATS URL validation on initialization
+- Detailed connection lifecycle logging with credential sanitization
 
 ### Fixed
 
-- **Health Check** - Fixed `healthy` field returning `nil` instead of `false` when disconnected
-  - Changed `stream_info[:exists]` to `stream_info&.fetch(:exists, false)` for proper nil handling
-  - Ensures boolean values always returned for monitoring systems
+- Fixed health check returning `nil` instead of `false` when disconnected
 
 ### Changed
 
-- **Code Organization** - Moved all inline RuboCop rules to centralized `.rubocop.yml`
-  - Removed inline comments from 5 files (logging.rb, model_utils.rb, inbox_event.rb, outbox_event.rb, inbox_message.rb)
-  - Added exclusions to `.rubocop.yml` for metrics and naming rules
-  - Cleaner codebase with all style exceptions in one location
+- Moved inline RuboCop rules to centralized `.rubocop.yml`
 
 ## [4.0.2] - 2025-11-23
 
 ### Fixed
 
-- **Stream Updates** - Prevent retention policy change errors (NATS error 10052)
-  - Skip all stream updates when retention policy differs from expected 'workqueue'
-  - Prevents "stream configuration update can not change retention policy to/from workqueue" error
-  - Logs warning when stream has mismatched retention policy but skips update
-  - Ensures compatibility with existing streams that have different retention policies
+- Prevented retention policy change errors by skipping updates when policy differs
 
 ## [4.0.1] - 2025-11-23
 
 ### Fixed
 
-- **Documentation** - Updated version references in README and YARD documentation
-  - Installation instructions now reference version 4.0
-  - Health check example output shows correct version
-  - YARD documentation reflects current version
+- Updated version references in documentation
 
 ## [4.0.0] - 2025-11-23
 
 ### Breaking Changes
 
-- **Per-app Dead Letter Queue (DLQ)** - DLQ subject pattern changed for better isolation
-  - **Old pattern**: `{env}.sync.dlq` (shared across all apps)
-  - **New pattern**: `{env}.{app_name}.sync.dlq` (isolated per app)
-  - **Example**: `production.api.sync.dlq` instead of `production.sync.dlq`
-
-### Benefits
-
-- **Isolation**: Failed messages from different services don't mix
-- **Easier Monitoring**: Track DLQ metrics per service
-- **Simpler Debugging**: Identify which service is having issues
-- **Independent Processing**: Each team can manage their own DLQ consumer
+- Changed DLQ subject pattern from `{env}.sync.dlq` (shared) to `{env}.{app_name}.sync.dlq` (per-app) for better isolation and monitoring
 
 ### Migration Guide
 
-1. **Drain existing DLQ**: Process or archive messages from the old shared DLQ (`{env}.sync.dlq`)
-2. **Deploy update**: Each app will automatically create its own DLQ subject on next deployment
-3. **Update monitoring**: Adjust dashboards to track per-app DLQ subjects (`{env}.{app_name}.sync.dlq`)
-4. **Update DLQ consumers**: Update DLQ consumer configuration to use app-specific subjects
+1. Drain existing DLQ messages from `{env}.sync.dlq`
+2. Deploy update (each app creates its own DLQ subject automatically)
+3. Update monitoring dashboards to track per-app DLQ subjects
+4. Update DLQ consumer configuration
 
-### Documentation
-
-- **Enhanced README** - Comprehensive documentation improvements
-  - Fixed consumer handler signature (single `event` parameter, not three)
-  - Added complete DLQ consumer examples with Rake task
-  - Added thread-safety documentation for Publisher
-  - Updated all subject pattern references
-  - Added DLQ monitoring examples
-- **YARD documentation** - Professional API documentation
-  - Added `.yardopts` configuration for consistent doc generation
-  - 60%+ documentation coverage across public APIs
-  - Configured RubyDoc.info integration
-  - Added Rake tasks for generating docs (`rake yard`)
-
-### Code Quality
+### Changed
 
-- **RuboCop compliance** - Zero offenses across entire codebase
-  - Configured appropriate exclusions for test files and acceptable patterns
-  - Fixed all auto-correctable style violations
-  - Added clear comments for non-correctable patterns
+- Enhanced README with corrected handler signatures and DLQ examples
+- Added YARD documentation with 60%+ API coverage
+- Achieved RuboCop compliance across entire codebase
 
 ## [3.0.0] - 2025-11-23
 
 ### Added
 
-#### Production-Ready Features
-
-- **Health checks** - Comprehensive health check API via `JetstreamBridge.health_check`
-  - NATS connection status monitoring
-  - Stream existence and subject verification
-  - Configuration validation
-  - Returns structured health data for monitoring systems
-- **Health check generator** - Rails generator for creating health check endpoints
-  - `rails g jetstream_bridge:health_check` creates controller and route
-  - Automatic route injection into `config/routes.rb`
-  - Returns appropriate HTTP status codes (200/503)
-- **Auto-reconnection** - Automatic recovery from connection failures
-  - Exponential backoff retry strategy
-  - Configurable retry limits and delays
-  - Connection state tracking with timestamps
-- **Connection factory** - Centralized connection management
-  - Singleton pattern for connection handling
-  - Thread-safe connection access
-  - Public `connected?` and `connected_at` accessors
-
-#### Error Handling
-
-- **Comprehensive error hierarchy** - Well-organized exception classes
-  - `ConfigurationError` - Base for configuration issues
-  - `ConnectionError` - Base for connection problems
-  - `PublishError` - Base for publishing failures
-  - `ConsumerError` - Base for consumption issues
-  - `TopologyError` - Base for stream/subject topology errors
-  - `DlqError` - Base for dead-letter queue operations
-  - All inherit from `JetstreamBridge::Error`
-
-#### Developer Experience
-
-- **Debug helper** - Comprehensive debugging utility via `JetstreamBridge::DebugHelper`
-  - Configuration dump
-  - Connection status
-  - Stream information
-  - Subject validation
-  - Model availability checks
-- **Rake tasks** - CLI tools for operations
-  - `rake jetstream_bridge:health` - Check health and connection status
-  - `rake jetstream_bridge:validate` - Validate configuration
-  - `rake jetstream_bridge:test_connection` - Test NATS connection
-  - `rake jetstream_bridge:debug` - Show comprehensive debug information
-- **Value objects** - Type-safe domain models
-  - `EventEnvelope` - Structured event representation
-  - `Subject` - Subject pattern validation and parsing
-
-#### Testing & Quality
-
-- **Comprehensive test suite** - 248 RSpec tests covering all core functionality
-  - Configuration validation specs
-  - Connection factory specs with edge cases (48 new tests added)
-    - Server URL normalization (single, comma-separated, arrays, whitespace)
-    - Authentication options (user, pass, token)
-    - NATS URL validation (nil, empty, whitespace-only)
-    - JetStream context creation and nc accessor
-  - Event envelope specs with full coverage (18 new tests added)
-    - Initialization edge cases (trace ID, Time objects, resource ID extraction)
-    - Hash serialization and deserialization
-    - Deep immutability validation
-    - Equality and hashing behavior
-    - Error handling for invalid timestamps
-  - Retry strategy specs
-  - Model specs
-  - Error hierarchy specs
-- **Subject validation** - Prevents NATS wildcards in configuration
-  - Validates `env`, `app_name`, and `destination_app` don't contain `.`, `*`, or `>`
-  - Clear error messages for invalid subjects
-- **Bug fixes in implementation** - Fixed `EventEnvelope.from_h` to properly handle deserialization
-  - Removed invalid `schema_version` parameter
-  - Added missing `resource_id` parameter
+- Comprehensive health check API and Rails generator for monitoring endpoints
+- Auto-reconnection with exponential backoff and connection state tracking
+- Centralized connection factory with thread-safe access
+- Well-organized error hierarchy with specific exception classes
+- Debug helper utility with configuration and connection diagnostics
+- Rake tasks for health checks, validation, and connection testing
+- Type-safe value objects (EventEnvelope, Subject)
+- Comprehensive test suite with 248+ RSpec tests
+- Subject validation to prevent NATS wildcards
 
 ### Changed
 
-#### Architecture Improvements
-
-- **Consolidated configuration** - Streamlined `Config` class
-  - Removed redundant configuration classes
-  - Centralized validation logic
-  - Better default values
-- **Enhanced generator templates** - Improved initializer template
-  - Better documentation and comments
-  - Organized sections (Connection, Consumer, Reliability, Models, Logging)
-  - Clear indication of required vs optional settings
-- **Simplified consumer initialization** - Cleaner API
-  - Sensible defaults for `durable_name` and `batch_size`
-  - Removed unnecessary configuration classes
-- **Better logging** - Configurable logger with sensible defaults
-  - Respects `config.logger` setting
-  - Falls back to `Rails.logger` in Rails apps
-  - Uses `STDOUT` logger otherwise
-
-#### Bug Fixes
-
-- **Fixed duration parsing** - Correct integer conversion for duration strings
-  - Handles edge cases properly
-  - Added comprehensive tests
-- **Fixed subject format** - Corrected DLQ subject pattern
-  - Changed from `{env}.data.sync.dlq` to `{env}.sync.dlq`
-  - Updated all documentation
-- **Repository improvements**
-  - Transaction safety for all database operations
-  - Pessimistic locking for outbox operations
-  - Race condition protection
-  - Better error handling and logging
+- Consolidated configuration with streamlined Config class
+- Enhanced generator templates with better documentation
+- Simplified consumer initialization with sensible defaults
+- Improved logging with configurable logger and fallbacks
+- Switched to Oj for JSON handling performance
+- Enhanced topology management with better overlap detection
+- Updated README with generators, rake tasks, and operations guide
+
+### Fixed
+
+- Fixed duration parsing for edge cases
+- Corrected DLQ subject pattern
+- Improved repository transaction safety and locking
+- Fixed EventEnvelope deserialization
 
 ### Refactored
 
-- **Consumer architecture** - Consolidated consumer support classes
-  - Merged related functionality
-  - Reduced file count
-  - Clearer separation of concerns
-- **Model handling** - Streamlined inbox/outbox models
-  - Graceful column detection without connection boot
-  - Better validation guards
-  - Simplified attribute handling
-- **JSON handling** - Switched to Oj for performance
-  - Faster JSON parsing/serialization
-  - Consistent JSON handling across the gem
-- **Topology management** - Enhanced stream and subject handling
-  - Improved overlap detection
-  - Better error messages
-  - More robust subject matching
-
-### Documentation Updates
-
-- **Updated README** - Comprehensive documentation updates
-  - Added section for Rails generators and rake tasks
-  - Documented all new health check features
-  - Fixed incorrect subject patterns
-  - Added operations guide
-  - Improved getting started section
-- **Enhanced code comments** - Better inline documentation
-  - YARD-style documentation for public APIs
-  - Clear explanations of complex logic
-  - Usage examples in comments
-- **Generator improvements** - Better user guidance
-  - Clear success messages
-  - Usage instructions after generation
-  - Example configurations
-
-### Internal
-
-- **Removed deprecated code**
-  - Cleaned up unused classes and methods
-  - Removed `BackoffStrategy` (consolidated into retry strategy)
-  - Removed `ConsumerConfig` (merged into main config)
-  - Removed `MessageContext` (functionality integrated)
+- Consolidated consumer architecture
+- Streamlined inbox/outbox model handling
+- Removed deprecated code (BackoffStrategy, ConsumerConfig, MessageContext)
 
 ## [2.10.0] and earlier
 

data/README.md

@@ -47,17 +47,13 @@ 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.stream_name     = "my_app-jetstream-bridge-stream"
   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:

data/docs/GETTING_STARTED.md

@@ -39,9 +39,9 @@ Generators create:
 # 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 = ENV.fetch("DESTINATION_APP")
+  config.stream_name     = "my_app-jetstream-bridge-stream" # required
 
   config.use_outbox = true  # transactional publish
   config.use_inbox  = true  # idempotent consume
@@ -51,15 +51,19 @@ JetstreamBridge.configure do |config|
   config.max_deliver = 5
   config.ack_wait    = "30s"
   config.backoff     = %w[1s 5s 15s 30s 60s]
-end
 
-# Note: `configure` only sets options; it does not connect. Rails will start
-# JetstreamBridge after initialization via the Railtie. For non-Rails or custom
-# boot flows, call `JetstreamBridge.startup!` (or rely on auto-connect on first
-# publish/subscribe).
+  # Optional: Custom inbox prefix if NATS account restricts _INBOX.>
+  # config.inbox_prefix = "$RPC"
+
+  # Optional: Pre-provisioned stream/consumer names
+  # config.durable_name = "my-durable"
+
+  # Optional: Disable JetStream management APIs (requires pre-provisioning)
+  # config.disable_js_api = false
+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.
+Rails starts JetStream Bridge automatically after initialization. For non-Rails apps, call `JetstreamBridge.connect!` or rely on auto-connect on first publish/subscribe.
 
 ## Publish