jetstream_bridge 4.5.0 → 4.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7e89386a56dac571dddec4c9d5283a975a8354d17d8f953ba148d390d55652
-  data.tar.gz: 64d5a7ea6bfdf863ea6a24d7d922cfaca565247605860cd999d6c2a8c893f48d
+  metadata.gz: '08ea80256539bb801e52672dc900d0e858b4a22fcc76e0958dfa1341e908dcc8'
+  data.tar.gz: 6fd4e80d372f8c9c022dfe0992356a73784f517d0a18d78e65ec78a01652443d
 SHA512:
-  metadata.gz: c95e0b2a4b829637f6c790cf13e710f814d085298949aadd141220d065cedc47dcd44a46fe8576b0cd280cd343cfd2a959ab4abb842fd0434cb817f9d70f9021
-  data.tar.gz: ebd5322b78df46177d3395c08674a822fd0cbf2a7111b7fbd7b4405f08ccaa7308d602ed0bcab862f4589730fe3a78c8b611c83d3eb0771eca199da31c0dc118
+  metadata.gz: 5b3a853557c531acac60a559673f95e2daab985ec43adf9b711108d2541fef59e109b894e070459a9259a4a3ccceedc15812e1768ce3a41d47b0087ec40a4a65
+  data.tar.gz: 76de67fbf04fdc62bab5c952238403a91f430396a20c738d9863aae4dbc2faed364cf9686791ddc566ffb7fb9a82acb2afef780f3dbbcbdb62d9287d6b58fea6

data/CHANGELOG.md

@@ -5,185 +5,436 @@ 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.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
-
-- 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
+- **Rails Generators** - Qualify Rails constants to avoid `JetstreamBridge::Rails::Generators` NameError during generator load
 
 ## [4.4.0] - 2025-11-24
 
 ### Changed
 
-- Enhanced NATS round-trip time measurement with automatic fallback for clients without native `rtt` method
-- Improved Rails Rake task detection using `$PROGRAM_NAME` inspection
+- **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
+
+- **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
 
 ### Fixed
 
-- Expanded test coverage for Rails integration and test helpers
+- **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
 
 ## [4.3.0] - 2025-11-24
 
 ### Added
 
-- Exposed reconnection error tracking via `last_reconnect_error` and `last_reconnect_error_at` for better diagnostics
+- **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
 
 ### Changed
 
-- 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
+- **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
 
 ### Fixed
 
-- Expanded test coverage for topology management and Rails integration
+- **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
 
 ## [4.2.0] - 2025-11-24
 
 ### Added
 
-- 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`
+- **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
 
 ### Changed
 
-- Reorganized Rails integration code into dedicated directory structure
-- Restructured README for clarity with focus on quick start
-- Enhanced gemspec with documentation files
+- **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
 
 ### Fixed
 
-- Resolved all RuboCop style violations
+- **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
 
 ## [4.1.0] - 2025-11-23
 
 ### Added
 
-- 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`
+- **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
 
 ### Changed
 
-- Added `skip_cache` parameter to health check API
+- **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
 
 ### Fixed
 
-- Fixed OverlapGuard test failures with proper cache clearing
+- **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
 
 ## [4.0.4] - 2025-11-23
 
 ### Fixed
 
-- Fixed nats-pure 2.5.0 compatibility with hash-style stream_info responses
+- **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
 
 ## [4.0.3] - 2025-11-23
 
 ### Added
 
-- Comprehensive NATS URL validation on initialization
-- Detailed connection lifecycle logging with credential sanitization
+- **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)
 
 ### Fixed
 
-- Fixed health check returning `nil` instead of `false` when disconnected
+- **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
 
 ### Changed
 
-- Moved inline RuboCop rules to centralized `.rubocop.yml`
+- **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
 
 ## [4.0.2] - 2025-11-23
 
 ### Fixed
 
-- Prevented retention policy change errors by skipping updates when policy differs
+- **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
 
 ## [4.0.1] - 2025-11-23
 
 ### Fixed
 
-- Updated version references in documentation
+- **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
 
 ## [4.0.0] - 2025-11-23
 
 ### Breaking Changes
 
-- Changed DLQ subject pattern from `{env}.sync.dlq` (shared) to `{env}.{app_name}.sync.dlq` (per-app) for better isolation and monitoring
+- **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
 
 ### Migration Guide
 
-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
+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
 
-### Changed
+### Documentation
 
-- Enhanced README with corrected handler signatures and DLQ examples
-- Added YARD documentation with 60%+ API coverage
-- Achieved RuboCop compliance across entire codebase
+- **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
+
+- **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
 
 ## [3.0.0] - 2025-11-23
 
 ### Added
 
-- 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
+#### 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
 
 ### Changed
 
-- 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
+#### 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
 
 ### Refactored
 
-- Consolidated consumer architecture
-- Streamlined inbox/outbox model handling
-- Removed deprecated code (BackoffStrategy, ConsumerConfig, MessageContext)
+- **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)
 
 ## [2.10.0] and earlier
 

data/README.md

@@ -34,7 +34,7 @@ Production-ready NATS JetStream bridge for Ruby/Rails with outbox, inbox, DLQ, a
 
 ```ruby
 # Gemfile
-gem "jetstream_bridge", "~> 4.0"
+gem "jetstream_bridge", "~> 4.5"
 ```
 
 ```bash
@@ -43,18 +43,7 @@ bin/rails g jetstream_bridge:install
 bin/rails db:migrate
 ```
 
-```ruby
-# config/initializers/jetstream_bridge.rb
-JetstreamBridge.configure do |config|
-  config.nats_urls       = ENV.fetch("NATS_URLS", "nats://localhost:4222")
-  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
-```
+The install generator creates the initializer, migrations, and optional health check scaffold. For full configuration options and non-Rails boot flows, see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).
 
 Publish:
 
@@ -75,6 +64,7 @@ consumer.run!
 
 - [Getting Started](docs/GETTING_STARTED.md)
 - [Production Guide](docs/PRODUCTION.md)
+- [Restricted Permissions & Provisioning](docs/RESTRICTED_PERMISSIONS.md)
 - [Testing with Mock NATS](docs/TESTING.md)
 
 ## License

data/docs/GETTING_STARTED.md

@@ -6,7 +6,7 @@ This guide covers installation, Rails setup, configuration, and basic publish/co
 
 ```ruby
 # Gemfile
-gem "jetstream_bridge", "~> 4.0"
+gem "jetstream_bridge", "~> 4.5"
 ```
 
 ```bash
@@ -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.stream_name     = ENV.fetch("JETSTREAM_STREAM_NAME", "jetstream-bridge-stream")
   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,19 +51,15 @@ JetstreamBridge.configure do |config|
   config.max_deliver = 5
   config.ack_wait    = "30s"
   config.backoff     = %w[1s 5s 15s 30s 60s]
-
-  # 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
+
+# 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).
 ```
 
-Rails starts JetStream Bridge automatically after initialization. For non-Rails apps, call `JetstreamBridge.connect!` or rely on auto-connect on first publish/subscribe.
+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.
 
 ## Publish