jetstream_bridge 4.4.1 → 4.5.1

data/lib/jetstream_bridge/core/connection.rb

@@ -58,8 +58,8 @@ module JetstreamBridge
       # Safe to call from multiple threads - uses class-level mutex for synchronization.
       #
       # @return [NATS::JetStream::JS] JetStream context
-      def connect!
-        @@connection_lock.synchronize { instance.connect! }
+      def connect!(verify_js: nil)
+        @@connection_lock.synchronize { instance.connect!(verify_js: verify_js) }
       end
 
       # Optional accessors if callers need raw handles
@@ -73,7 +73,8 @@ module JetstreamBridge
     end
 
     # Idempotent: returns an existing, healthy JetStream context or establishes one.
-    def connect!
+    def connect!(verify_js: nil)
+      verify_js = config_auto_provision if verify_js.nil?
       # Check if already connected without acquiring mutex (for performance)
       return @jts if @jts && @nc&.connected?
 
@@ -81,7 +82,7 @@ module JetstreamBridge
       raise 'No NATS URLs configured' if servers.empty?
 
       @state = State::CONNECTING
-      establish_connection_with_retry(servers)
+      establish_connection_with_retry(servers, verify_js: verify_js)
 
       Logging.info(
         "Connected to NATS (#{servers.size} server#{'s' unless servers.size == 1}): " \
@@ -89,9 +90,6 @@ module JetstreamBridge
         tag: 'JetstreamBridge::Connection'
       )
 
-      # Ensure topology (streams, subjects, overlap guard, etc.)
-      Topology.ensure!(@jts)
-
       @connected_at = Time.now.utc
       @state = State::CONNECTED
       @jts
@@ -124,8 +122,8 @@ module JetstreamBridge
         now = Time.now.to_i
         return @cached_health_status if !skip_cache && @last_health_check && (now - @last_health_check) < 30
 
-        # Perform actual health check
-        @cached_health_status = jetstream_healthy?
+        # Perform actual health check (management APIs optional)
+        @cached_health_status = jetstream_healthy?(verify_js: config_auto_provision)
         @last_health_check = now
         @cached_health_status
       end
@@ -151,7 +149,10 @@ module JetstreamBridge
 
     private
 
-    def jetstream_healthy?
+    def jetstream_healthy?(verify_js:)
+      # Lightweight health when management APIs are disabled
+      return ping_only_health unless verify_js
+
       # Verify JetStream responds to simple API call
       @jts.account_info
       true
@@ -163,6 +164,20 @@ module JetstreamBridge
       false
     end
 
+    def ping_only_health
+      return false unless @nc&.connected?
+
+      # Flush acts as a ping/pong round-trip without hitting JetStream management subjects
+      @nc.flush(0.5)
+      true
+    rescue StandardError => e
+      Logging.warn(
+        "NATS connectivity check failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+      false
+    end
+
     def nats_servers
       servers = JetstreamBridge.config.nats_urls
                                .to_s
@@ -174,14 +189,14 @@ module JetstreamBridge
       servers
     end
 
-    def establish_connection_with_retry(servers)
+    def establish_connection_with_retry(servers, verify_js:)
       attempts = 0
       max_attempts = JetstreamBridge.config.connect_retry_attempts
       retry_delay = JetstreamBridge.config.connect_retry_delay
 
       begin
         attempts += 1
-        establish_connection(servers)
+        establish_connection(servers, verify_js: verify_js)
       rescue ConnectionError => e
         if attempts < max_attempts
           delay = retry_delay * attempts
@@ -203,7 +218,7 @@ module JetstreamBridge
       end
     end
 
-    def establish_connection(servers)
+    def establish_connection(servers, verify_js:)
       # Use mock NATS client if explicitly enabled for testing
       # This allows test helpers to inject a mock without affecting normal operation
       @nc = if defined?(JetstreamBridge::TestHelpers) &&
@@ -257,7 +272,22 @@ module JetstreamBridge
       @jts = @nc.jetstream
 
       # Verify JetStream is available
-      verify_jetstream!
+      if verify_js
+        verify_jetstream!
+        if config_auto_provision
+          Topology.ensure!(@jts)
+          Logging.info(
+            'Topology ensured after connection (auto_provision=true).',
+            tag: 'JetstreamBridge::Connection'
+          )
+        end
+      else
+        Logging.info(
+          'Skipping JetStream account_info verification (auto_provision=false). ' \
+          'Assuming JetStream is enabled.',
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
 
       # Ensure JetStream responds to #nc
       return if @jts.respond_to?(:nc)
@@ -400,8 +430,15 @@ module JetstreamBridge
       nc_ref = @nc
       @jts.define_singleton_method(:nc) { nc_ref } unless @jts.respond_to?(:nc)
 
-      # Re-ensure topology after reconnect
-      Topology.ensure!(@jts)
+      # Re-ensure topology after reconnect when allowed
+      if config_auto_provision
+        Topology.ensure!(@jts)
+      else
+        Logging.info(
+          'Skipping topology provisioning after reconnect (auto_provision=false).',
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
 
       # Invalidate health check cache on successful reconnect
       @cached_health_status = nil
@@ -460,5 +497,12 @@ module JetstreamBridge
       @last_health_check = nil
       @connected_at = nil
     end
+
+    def config_auto_provision
+      cfg = JetstreamBridge.config
+      cfg.respond_to?(:auto_provision) ? cfg.auto_provision : true
+    rescue StandardError
+      true
+    end
   end
 end

data/lib/jetstream_bridge/core/connection_factory.rb

@@ -9,12 +9,7 @@ module JetstreamBridge
     class ConnectionFactory
       # Connection options builder
       class ConnectionOptions
-        DEFAULT_OPTS = {
-          reconnect: true,
-          reconnect_time_wait: 2,
-          max_reconnect_attempts: 10,
-          connect_timeout: 5
-        }.freeze
+        DEFAULT_OPTS = JetstreamBridge::Connection::DEFAULT_CONN_OPTS
 
         attr_accessor :servers, :reconnect, :reconnect_time_wait,
                       :max_reconnect_attempts, :connect_timeout,
@@ -73,7 +68,7 @@ module JetstreamBridge
 
           ConnectionOptions.new(
             servers: servers,
-            name: "#{config.app_name}-#{config.env}"
+            name: config.app_name
           )
         end
 

data/lib/jetstream_bridge/core/debug_helper.rb

@@ -30,7 +30,6 @@ module JetstreamBridge
       def config_debug
         cfg = JetstreamBridge.config
         {
-          env: cfg.env,
           app_name: cfg.app_name,
           destination_app: cfg.destination_app,
           stream_name: cfg.stream_name,

data/lib/jetstream_bridge/models/subject.rb

@@ -5,12 +5,11 @@ module JetstreamBridge
     # Value object representing a NATS subject
     #
     # @example Creating a subject
-    #   subject = Subject.source(env: "production", app_name: "api", dest: "worker")
-    #   subject.to_s # => "production.api.sync.worker"
+    #   subject = Subject.source(app_name: "api", dest: "worker")
+    #   subject.to_s # => "api.sync.worker"
     #
     # @example Parsing a subject string
-    #   subject = Subject.parse("production.api.sync.worker")
-    #   subject.env         # => "production"
+    #   subject = Subject.parse("api.sync.worker")
     #   subject.source_app  # => "api"
     #   subject.dest_app    # => "worker"
     class Subject
@@ -31,16 +30,16 @@ module JetstreamBridge
       end
 
       # Factory methods
-      def self.source(env:, app_name:, dest:)
-        new("#{env}.#{app_name}.sync.#{dest}")
+      def self.source(app_name:, dest:)
+        new("#{app_name}.sync.#{dest}")
       end
 
-      def self.destination(env:, source:, app_name:)
-        new("#{env}.#{source}.sync.#{app_name}")
+      def self.destination(source:, app_name:)
+        new("#{source}.sync.#{app_name}")
       end
 
-      def self.dlq(env:, app_name:)
-        new("#{env}.#{app_name}.sync.dlq")
+      def self.dlq(app_name:)
+        new("#{app_name}.sync.dlq")
       end
 
       # Parse a subject string into a Subject object with metadata
@@ -51,37 +50,30 @@ module JetstreamBridge
         new(string)
       end
 
-      # Get environment from subject (first token)
-      #
-      # @return [String, nil] Environment
-      def env
-        @tokens[0]
-      end
-
       # Get source application from subject
       #
-      # For regular subjects: {env}.{source_app}.sync.{dest}
-      # For DLQ subjects: {env}.{app_name}.sync.dlq
+      # For regular subjects: {source_app}.sync.{dest}
+      # For DLQ subjects: {app_name}.sync.dlq
       #
       # @return [String, nil] Source application
       def source_app
-        @tokens[1]
+        @tokens[0]
       end
 
       # Get destination application from subject
       #
       # @return [String, nil] Destination application
       def dest_app
-        @tokens[3]
+        @tokens[2]
       end
 
       # Check if this is a DLQ subject
       #
-      # DLQ subjects follow the pattern: {env}.{app}.sync.dlq
+      # DLQ subjects follow the pattern: {app}.sync.dlq
       #
       # @return [Boolean] True if this is a DLQ subject
       def dlq?
-        @tokens.length == 4 && @tokens[2] == 'sync' && @tokens[3] == 'dlq'
+        @tokens.length == 3 && @tokens[1] == 'sync' && @tokens[2] == 'dlq'
       end
 
       # Check if this subject matches a pattern

data/lib/jetstream_bridge/provisioner.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'topology/topology'
+require_relative 'consumer/subscription_manager'
+require_relative 'core/logging'
+require_relative 'core/config'
+require_relative 'core/connection'
+
+module JetstreamBridge
+  # Dedicated provisioning orchestrator to keep connection concerns separate.
+  #
+  # Handles creating/updating stream topology and consumers. Can be used at
+  # deploy-time with admin credentials or during runtime when auto_provision
+  # is enabled.
+  class Provisioner
+    def initialize(config: JetstreamBridge.config)
+      @config = config
+    end
+
+    # Ensure stream (and optionally consumer) exist with desired config.
+    #
+    # @param jts [Object, nil] Existing JetStream context (optional)
+    # @param ensure_consumer [Boolean] Whether to create/align the consumer too
+    # @return [Object] JetStream context used for provisioning
+    def ensure!(jts: nil, ensure_consumer: true)
+      js = jts || Connection.connect!(verify_js: true)
+
+      ensure_stream!(js)
+      ensure_consumer!(js) if ensure_consumer
+
+      Logging.info(
+        "Provisioned stream=#{@config.stream_name} consumer=#{@config.durable_name if ensure_consumer}",
+        tag: 'JetstreamBridge::Provisioner'
+      )
+
+      js
+    end
+
+    # Ensure stream only.
+    #
+    # @param jts [Object, nil] Existing JetStream context (optional)
+    # @return [Object] JetStream context used
+    def ensure_stream!(jts: nil)
+      js = jts || Connection.connect!(verify_js: true)
+      Topology.ensure!(js)
+      Logging.info(
+        "Stream ensured: #{@config.stream_name}",
+        tag: 'JetstreamBridge::Provisioner'
+      )
+      js
+    end
+
+    # Ensure durable consumer only.
+    #
+    # @param jts [Object, nil] Existing JetStream context (optional)
+    # @return [Object] JetStream context used
+    def ensure_consumer!(jts: nil)
+      js = jts || Connection.connect!(verify_js: true)
+      SubscriptionManager.new(js, @config.durable_name, @config).ensure_consumer!(force: true)
+      Logging.info(
+        "Consumer ensured: #{@config.durable_name}",
+        tag: 'JetstreamBridge::Provisioner'
+      )
+      js
+    end
+  end
+end

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -13,7 +13,7 @@ require_relative 'outbox_repository'
 module JetstreamBridge
   # Publishes events to NATS JetStream with reliability features.
   #
-  # Publishes events to "{env}.{app}.sync.{dest}" subject pattern.
+  # Publishes events to "{app}.sync.{dest}" subject pattern.
   # Supports optional transactional outbox pattern for guaranteed delivery.
   #
   # @example Basic publishing
@@ -115,8 +115,8 @@ module JetstreamBridge
       envelope, resolved_subject = route_publish_params(params)
 
       do_publish(resolved_subject, envelope)
-    rescue ArgumentError
-      # Re-raise validation errors for invalid parameters
+    rescue ArgumentError, JetstreamBridge::ConfigurationError
+      # Re-raise validation/configuration errors (e.g., missing destination_app)
       raise
     rescue StandardError => e
       # Return failure result for publishing errors
@@ -191,12 +191,6 @@ module JetstreamBridge
       normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
     end
 
-    def ensure_destination_app_configured!
-      return unless JetstreamBridge.config.destination_app.to_s.empty?
-
-      raise ArgumentError, 'destination_app must be configured'
-    end
-
     def publish_to_nats(subject, envelope)
       headers = { 'nats-msg-id' => envelope['event_id'] }
 
@@ -347,5 +341,10 @@ module JetstreamBridge
       payload = payload.transform_keys(&:to_s) if payload.respond_to?(:transform_keys)
       (payload['id'] || payload[:id] || payload['resource_id'] || payload[:resource_id]).to_s
     end
+
+    def ensure_destination_app_configured!
+      # Leverage subject builder to enforce required components and surface consistent error messaging.
+      JetstreamBridge.config.source_subject
+    end
   end
 end

data/lib/jetstream_bridge/tasks/install.rake

@@ -36,7 +36,7 @@ namespace :jetstream_bridge do
 
     if health[:config]
       puts "\nConfiguration:"
-      puts "  Environment: #{health[:config][:env]}"
+      puts "  Stream: #{health[:config][:stream_name]}"
       puts "  App Name: #{health[:config][:app_name]}"
       puts "  Destination: #{health[:config][:destination_app] || 'NOT SET'}"
       puts "  Outbox: #{health[:config][:use_outbox] ? 'Enabled' : 'Disabled'}"
@@ -62,7 +62,7 @@ namespace :jetstream_bridge do
       JetstreamBridge.config.validate!
       puts '✓ Configuration is valid'
       puts "\nCurrent settings:"
-      puts "  Environment: #{JetstreamBridge.config.env}"
+      puts "  Stream: #{JetstreamBridge.config.stream_name}"
       puts "  App Name: #{JetstreamBridge.config.app_name}"
       puts "  Destination: #{JetstreamBridge.config.destination_app}"
       puts "  Stream: #{JetstreamBridge.config.stream_name}"
@@ -80,6 +80,21 @@ namespace :jetstream_bridge do
     JetstreamBridge::DebugHelper.debug_info
   end
 
+  desc 'Provision stream and consumer (requires JetStream admin permissions)'
+  task provision: :environment do
+    puts '[jetstream_bridge] Provisioning JetStream stream and consumer...'
+
+    begin
+      provisioner = JetstreamBridge::Provisioner.new
+      provisioner.ensure!(ensure_consumer: true)
+      puts "✓ Provisioned stream=#{JetstreamBridge.config.stream_name} consumer=#{JetstreamBridge.config.durable_name}"
+      exit 0
+    rescue StandardError => e
+      puts "✗ Provisioning failed: #{e.message}"
+      exit 1
+    end
+  end
+
   desc 'Test connection to NATS'
   task test_connection: :environment do
     puts '[jetstream_bridge] Testing NATS connection...'

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '4.4.1'
+  VERSION = '4.5.1'
 end

data/lib/jetstream_bridge.rb

@@ -8,6 +8,7 @@ require_relative 'jetstream_bridge/consumer/consumer'
 require_relative 'jetstream_bridge/consumer/middleware'
 require_relative 'jetstream_bridge/models/publish_result'
 require_relative 'jetstream_bridge/models/event'
+require_relative 'jetstream_bridge/provisioner'
 
 # Rails-specific entry point (lifecycle helpers + Railtie)
 require_relative 'jetstream_bridge/rails' if defined?(Rails::Railtie)
@@ -34,7 +35,6 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #   # Configure
 #   JetstreamBridge.configure do |config|
 #     config.nats_urls = "nats://localhost:4222"
-#     config.env = "development"
 #     config.app_name = "my_app"
 #     config.destination_app = "other_app"
 #     config.use_outbox = true
@@ -87,7 +87,7 @@ module JetstreamBridge
     #   JetstreamBridge.startup!  # Explicitly start connection
     #
     # @example With hash overrides
-    #   JetstreamBridge.configure(env: 'production', app_name: 'my_app')
+    #   JetstreamBridge.configure(app_name: 'my_app')
     #
     # @param overrides [Hash] Configuration key-value pairs to set
     # @yield [Config] Configuration object for block-based configuration
@@ -139,6 +139,7 @@ module JetstreamBridge
     def startup!
       return if @connection_initialized
 
+      config.validate!
       connect_and_ensure_stream!
       @connection_initialized = true
       Logging.info('JetStream Bridge started successfully', tag: 'JetstreamBridge')
@@ -200,12 +201,34 @@ module JetstreamBridge
     #
     # @return [Object] JetStream context
     def connect_and_ensure_stream!
-      Connection.connect!
+      config.validate!
+      provision = config.auto_provision
+      Connection.connect!(verify_js: provision)
       jts = Connection.jetstream
-      Topology.ensure!(jts)
+      raise ConnectionNotEstablishedError, 'JetStream connection not available' unless jts
+
+      if provision
+        Provisioner.new(config: config).ensure_stream!(jts: jts)
+      else
+        Logging.info(
+          'auto_provision=false: skipping stream provisioning and JetStream account_info. ' \
+          'Run `bundle exec rake jetstream_bridge:provision` with admin credentials to create/update topology.',
+          tag: 'JetstreamBridge'
+        )
+      end
+
       jts
     end
 
+    # Provision stream/consumer using management credentials (out of band from runtime).
+    #
+    # @param ensure_consumer [Boolean] Whether to create/align the consumer along with the stream.
+    # @return [Object] JetStream context
+    def provision!(ensure_consumer: true)
+      config.validate!
+      Provisioner.new(config: config).ensure!(ensure_consumer: ensure_consumer)
+    end
+
     # Backwards-compatible alias for the previous method name
     def ensure_topology!
       connect_and_ensure_stream!
@@ -229,46 +252,20 @@ module JetstreamBridge
       enforce_health_check_rate_limit! if skip_cache
 
       start_time = Time.now
-      conn_instance = Connection.instance
-
-      # Active check: calls @jts.account_info internally
-      # Pass skip_cache to force fresh check if requested
-      connected = conn_instance.connected?(skip_cache: skip_cache)
-      connected_at = conn_instance.connected_at
-      connection_state = conn_instance.state
-      last_error = conn_instance.last_reconnect_error
-      last_error_at = conn_instance.last_reconnect_error_at
-
-      # Active check: queries actual stream from NATS server
-      stream_info = connected ? fetch_stream_info : { exists: false, name: config.stream_name }
-
-      # Active check: measure NATS round-trip time
-      rtt_ms = measure_nats_rtt if connected
-
-      health_check_duration_ms = ((Time.now - start_time) * 1000).round(2)
+      conn_status = connection_snapshot(Connection.instance, skip_cache: skip_cache)
+      stream_info = stream_status(conn_status[:connected])
+      rtt_ms = measure_nats_rtt if conn_status[:connected]
+      health_check_duration_ms = elapsed_ms(start_time)
 
       {
-        healthy: connected && stream_info&.fetch(:exists, false),
-        connection: {
-          state: connection_state,
-          connected: connected,
-          connected_at: connected_at&.iso8601,
-          last_error: last_error&.message,
-          last_error_at: last_error_at&.iso8601
-        },
+        healthy: health_flag(conn_status[:connected], stream_info),
+        connection: connection_payload(conn_status),
         stream: stream_info,
         performance: {
           nats_rtt_ms: rtt_ms,
           health_check_duration_ms: health_check_duration_ms
         },
-        config: {
-          env: config.env,
-          app_name: config.app_name,
-          destination_app: config.destination_app,
-          use_outbox: config.use_outbox,
-          use_inbox: config.use_inbox,
-          use_dlq: config.use_dlq
-        },
+        config: config_summary,
         version: JetstreamBridge::VERSION
       }
     rescue StandardError => e
@@ -416,5 +413,60 @@ module JetstreamBridge
         consumer
       end
     end
+
+    private
+
+    def connection_snapshot(conn_instance, skip_cache:)
+      {
+        connected: conn_instance.connected?(skip_cache: skip_cache),
+        connected_at: conn_instance.connected_at,
+        state: conn_instance.state,
+        last_error: conn_instance.last_reconnect_error,
+        last_error_at: conn_instance.last_reconnect_error_at
+      }
+    end
+
+    def stream_status(connected)
+      return stream_missing unless connected
+      return skipped_stream_info unless config.auto_provision
+
+      fetch_stream_info
+    end
+
+    def stream_missing
+      { exists: false, name: config.stream_name }
+    end
+
+    def health_flag(connected, stream_info)
+      return connected unless config.auto_provision
+
+      connected && stream_info&.fetch(:exists, false)
+    end
+
+    def connection_payload(status)
+      {
+        state: status[:state],
+        connected: status[:connected],
+        connected_at: status[:connected_at]&.iso8601,
+        last_error: status[:last_error]&.message,
+        last_error_at: status[:last_error_at]&.iso8601
+      }
+    end
+
+    def config_summary
+      {
+        app_name: config.app_name,
+        destination_app: config.destination_app,
+        stream_name: config.stream_name,
+        auto_provision: config.auto_provision,
+        use_outbox: config.use_outbox,
+        use_inbox: config.use_inbox,
+        use_dlq: config.use_dlq
+      }
+    end
+
+    def elapsed_ms(start_time)
+      ((Time.now - start_time) * 1000).round(2)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 4.4.1
+  version: 4.5.1
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
+date: 2026-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -105,7 +105,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4.0'
 description: |-
-  Production-ready publishers/consumers for NATS JetStream with environment-scoped
+  Production-ready publishers/consumers for NATS JetStream with app-scoped
   subjects, overlap guards, DLQ routing, retries/backoff, and optional inbox/outbox
   patterns. Includes health checks, auto-reconnection, graceful shutdown, topology
   setup helpers, and Rails generators.
@@ -123,6 +123,7 @@ files:
 - README.md
 - docs/GETTING_STARTED.md
 - docs/PRODUCTION.md
+- docs/RESTRICTED_PERMISSIONS.md
 - docs/TESTING.md
 - lib/generators/jetstream_bridge/health_check/health_check_generator.rb
 - lib/generators/jetstream_bridge/health_check/templates/health_controller.rb
@@ -160,6 +161,7 @@ files:
 - lib/jetstream_bridge/models/outbox_event.rb
 - lib/jetstream_bridge/models/publish_result.rb
 - lib/jetstream_bridge/models/subject.rb
+- lib/jetstream_bridge/provisioner.rb
 - lib/jetstream_bridge/publisher/batch_publisher.rb
 - lib/jetstream_bridge/publisher/outbox_repository.rb
 - lib/jetstream_bridge/publisher/publisher.rb