jetstream_bridge 4.5.0 → 4.5.2

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

@@ -2,18 +2,18 @@
 
 require 'oj'
 require 'securerandom'
+require_relative '../core/connection'
 require_relative '../core/logging'
 require_relative '../core/config'
 require_relative '../core/model_utils'
 require_relative '../core/retry_strategy'
 require_relative '../models/publish_result'
 require_relative 'outbox_repository'
-require_relative 'event_envelope_builder'
 
 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
@@ -34,20 +34,19 @@ module JetstreamBridge
   #   JetstreamBridge.publish(event_type: "user.created", payload: { id: 1 })
   #
   class Publisher
-    # Initialize a new Publisher instance with dependency injection.
+    # Initialize a new Publisher instance.
     #
-    # @param connection [NATS::JetStream::JS] JetStream connection
-    # @param config [Config] Configuration instance
-    # @param retry_strategy [RetryStrategy, nil] Optional custom retry strategy
-    # @raise [ArgumentError] If required dependencies are missing
-    def initialize(connection:, config:, retry_strategy: nil)
-      raise ArgumentError, 'connection is required' unless connection
-      raise ArgumentError, 'config is required' unless config
-
-      @jts = connection
-      @config = config
+    # Note: The NATS connection should already be established via JetstreamBridge.startup!
+    # or automatically on first use. This assumes the connection is already established.
+    #
+    # @param retry_strategy [RetryStrategy, nil] Optional custom retry strategy for handling transient failures.
+    #   Defaults to PublisherRetryStrategy with exponential backoff.
+    # @raise [ConnectionError] If unable to get JetStream connection
+    def initialize(retry_strategy: nil)
+      @jts = Connection.jetstream
+      raise ConnectionError, 'JetStream connection not available. Call JetstreamBridge.startup! first.' unless @jts
+
       @retry_strategy = retry_strategy || PublisherRetryStrategy.new
-      @envelope_builder = EventEnvelopeBuilder
     end
 
     # Publishes an event to NATS JetStream.
@@ -108,76 +107,16 @@ module JetstreamBridge
     #     logger.error "Failed to publish: #{result.error.message}"
     #   end
     #
-    def publish(event_type:, payload:, resource_type: nil, subject: nil, **)
+    def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **options)
       ensure_destination_app_configured!
 
-      envelope = @envelope_builder.build(
-        event_type: event_type,
-        payload: payload,
-        resource_type: resource_type,
-        **
-      )
-
-      resolved_subject = subject || @config.source_subject
+      params = { event_or_hash: event_or_hash, resource_type: resource_type, event_type: event_type,
+                 payload: payload, subject: subject, options: options }
+      envelope, resolved_subject = route_publish_params(params)
 
       do_publish(resolved_subject, envelope)
-    rescue ArgumentError
-      # Re-raise validation errors for invalid parameters
-      raise
-    rescue StandardError => e
-      # Return failure result for publishing errors
-      Models::PublishResult.new(
-        success: false,
-        event_id: envelope&.[]('event_id') || 'unknown',
-        subject: resolved_subject || 'unknown',
-        error: e
-      )
-    end
-
-    # Publish a complete event envelope (advanced usage)
-    #
-    # Provides full control over the envelope structure. Use this when you need
-    # to manually construct the envelope or preserve all fields from an external source.
-    #
-    # @param envelope [Hash] Complete event envelope with all required fields
-    # @option envelope [String] 'event_id' Unique event identifier (required)
-    # @option envelope [Integer] 'schema_version' Schema version (required, typically 1)
-    # @option envelope [String] 'event_type' Event type (required)
-    # @option envelope [String] 'producer' Producer name (required)
-    # @option envelope [String] 'resource_type' Resource type (required)
-    # @option envelope [String] 'resource_id' Resource identifier (required)
-    # @option envelope [String] 'occurred_at' ISO8601 timestamp (required)
-    # @option envelope [String] 'trace_id' Trace identifier (required)
-    # @option envelope [Hash] 'payload' Event payload data (required)
-    # @param subject [String, nil] Optional NATS subject override
-    # @return [Models::PublishResult] Result object
-    #
-    # @raise [ArgumentError] If required envelope fields are missing
-    #
-    # @example Publishing a complete envelope
-    #   envelope = {
-    #     'event_id' => SecureRandom.uuid,
-    #     'schema_version' => 1,
-    #     'event_type' => 'user.created',
-    #     'producer' => 'custom-producer',
-    #     'resource_type' => 'user',
-    #     'resource_id' => '123',
-    #     'occurred_at' => Time.now.utc.iso8601,
-    #     'trace_id' => 'trace-123',
-    #     'payload' => { id: 123, name: 'Alice' }
-    #   }
-    #
-    #   result = publisher.publish_envelope(envelope)
-    #   puts "Published: #{result.event_id}"
-    def publish_envelope(envelope, subject: nil)
-      ensure_destination_app_configured!
-      validate_envelope!(envelope)
-
-      resolved_subject = subject || @config.source_subject
-
-      do_publish(resolved_subject, envelope)
-    rescue ArgumentError
-      # Re-raise validation errors for invalid envelope
+    rescue ArgumentError, JetstreamBridge::ConfigurationError
+      # Re-raise validation/configuration errors (e.g., missing destination_app)
       raise
     rescue StandardError => e
       # Return failure result for publishing errors
@@ -199,7 +138,7 @@ module JetstreamBridge
     # @return [Models::PublishResult] Result object
     # @api private
     def do_publish(subject, envelope)
-      if @config.use_outbox
+      if JetstreamBridge.config.use_outbox
         publish_via_outbox(subject, envelope)
       else
         with_retries { publish_to_nats(subject, envelope) }
@@ -208,22 +147,48 @@ module JetstreamBridge
 
     private
 
-    # Validate envelope has all required fields
-    def validate_envelope!(envelope)
-      required_fields = %w[event_id schema_version event_type producer resource_type
-                           resource_id occurred_at trace_id payload]
+    # Routes publish parameters to appropriate envelope builder
+    # @return [Array<Hash, String>] tuple of [envelope, subject]
+    def route_publish_params(params)
+      if structured_params?(params)
+        build_from_structured_params(params)
+      elsif keyword_or_hash_params?(params)
+        build_from_keyword_or_hash(params)
+      else
+        raise ArgumentError, 'Either provide (resource_type:, event_type:, payload:) or an event hash'
+      end
+    end
+
+    def structured_params?(params)
+      params[:resource_type] && params[:event_type] && params[:payload]
+    end
 
-      missing = required_fields.select { |field| envelope[field].nil? || envelope[field].to_s.strip.empty? }
+    def keyword_or_hash_params?(params)
+      params[:event_type] || params[:payload] || params[:event_or_hash].is_a?(Hash)
+    end
 
-      return if missing.empty?
+    def build_from_structured_params(params)
+      envelope = build_envelope(params[:resource_type], params[:event_type], params[:payload], params[:options])
+      resolved_subject = params[:subject] || JetstreamBridge.config.source_subject
+      [envelope, resolved_subject]
+    end
+
+    def build_from_keyword_or_hash(params)
+      envelope = if params[:event_or_hash].is_a?(Hash)
+                   normalize_envelope(params[:event_or_hash], params[:options])
+                 else
+                   build_from_keywords(params[:event_type], params[:payload], params[:options])
+                 end
 
-      raise ArgumentError, "Envelope missing required fields: #{missing.join(', ')}"
+      resolved_subject = params[:subject] || params[:options][:subject] || JetstreamBridge.config.source_subject
+      [envelope, resolved_subject]
     end
 
-    def ensure_destination_app_configured!
-      return unless @config.destination_app.to_s.empty?
+    def build_from_keywords(event_type, payload, options)
+      raise ArgumentError, 'event_type is required' unless event_type
+      raise ArgumentError, 'payload is required' unless payload
 
-      raise ArgumentError, 'destination_app must be configured'
+      normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
     end
 
     def publish_to_nats(subject, envelope)
@@ -260,7 +225,7 @@ module JetstreamBridge
 
     # ---- Outbox path ----
     def publish_via_outbox(subject, envelope)
-      klass = ModelUtils.constantize(@config.outbox_model)
+      klass = ModelUtils.constantize(JetstreamBridge.config.outbox_model)
 
       unless ModelUtils.ar_class?(klass)
         Logging.warn(
@@ -317,5 +282,69 @@ module JetstreamBridge
       )
       raise
     end
+
+    def build_envelope(resource_type, event_type, payload, options = {})
+      {
+        'event_id' => options[:event_id] || SecureRandom.uuid,
+        'schema_version' => 1,
+        'event_type' => event_type,
+        'producer' => JetstreamBridge.config.app_name,
+        'resource_id' => extract_resource_id(payload),
+        'occurred_at' => (options[:occurred_at] || Time.now.utc).iso8601,
+        'trace_id' => options[:trace_id] || SecureRandom.hex(8),
+        'resource_type' => resource_type,
+        'payload' => payload
+      }
+    end
+
+    # Normalize a hash to match envelope structure, allowing partial envelopes
+    def normalize_envelope(hash, options = {})
+      hash = hash.transform_keys(&:to_s)
+      infer_resource_type_if_needed!(hash)
+
+      {
+        'event_id' => envelope_event_id(hash, options),
+        'schema_version' => hash['schema_version'] || 1,
+        'event_type' => hash['event_type'] || raise(ArgumentError, 'event_type is required'),
+        'producer' => hash['producer'] || JetstreamBridge.config.app_name,
+        'resource_id' => hash['resource_id'] || extract_resource_id(hash['payload']),
+        'occurred_at' => envelope_occurred_at(hash, options),
+        'trace_id' => envelope_trace_id(hash, options),
+        'resource_type' => hash['resource_type'] || 'event',
+        'payload' => hash['payload'] || raise(ArgumentError, 'payload is required')
+      }
+    end
+
+    def infer_resource_type_if_needed!(hash)
+      return unless hash['event_type'] && hash['payload'] && !hash['resource_type']
+
+      # Try to infer from dot notation (e.g., 'user.created' -> 'user')
+      parts = hash['event_type'].split('.')
+      hash['resource_type'] = parts[0] if parts.size > 1
+    end
+
+    def envelope_event_id(hash, options)
+      hash['event_id'] || options[:event_id] || SecureRandom.uuid
+    end
+
+    def envelope_occurred_at(hash, options)
+      hash['occurred_at'] || (options[:occurred_at] || Time.now.utc).iso8601
+    end
+
+    def envelope_trace_id(hash, options)
+      hash['trace_id'] || options[:trace_id] || SecureRandom.hex(8)
+    end
+
+    def extract_resource_id(payload)
+      return '' unless payload
+
+      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/rails/integration.rb

@@ -2,6 +2,7 @@
 
 require_relative '../core/model_codec_setup'
 require_relative '../core/logging'
+require_relative '../core/connection'
 
 module JetstreamBridge
   module Rails
@@ -37,7 +38,8 @@ module JetstreamBridge
           return
         end
 
-        JetstreamBridge.connect!
+        JetstreamBridge.config.validate!
+        JetstreamBridge.startup!
         log_started!
         log_development_connection_details! if rails_development?
         register_shutdown_hook!
@@ -103,12 +105,7 @@ module JetstreamBridge
       end
 
       def log_development_connection_details!
-        health = begin
-          JetstreamBridge.health
-        rescue StandardError
-          nil
-        end
-        conn_state = health&.dig(:connection, :state) || 'unknown'
+        conn_state = JetstreamBridge::Connection.instance.state
         active_logger&.info("[JetStream Bridge] Connection state: #{conn_state}")
         active_logger&.info("[JetStream Bridge] Connected to: #{JetstreamBridge.config.nats_urls}")
         active_logger&.info("[JetStream Bridge] Stream: #{JetstreamBridge.config.stream_name}")
@@ -119,7 +116,7 @@ module JetstreamBridge
       def register_shutdown_hook!
         return if @shutdown_hook_registered
 
-        at_exit { JetstreamBridge.disconnect! }
+        at_exit { JetstreamBridge.shutdown! }
         @shutdown_hook_registered = true
       end
 

data/lib/jetstream_bridge/rails/railtie.rb

@@ -7,7 +7,7 @@ module JetstreamBridge
   #
   # This Railtie integrates JetStream Bridge with the Rails application lifecycle:
   # - Configuration: Logger is configured early in the Rails boot process
-  # - Startup: Connection is established after user initializers load (connect!)
+  # - Startup: Connection is established after user initializers load (explicit startup!)
   # - Shutdown: Connection is closed when Rails shuts down (at_exit hook)
   # - Restart: Puma/Unicorn workers get fresh connections on fork
   #
@@ -33,11 +33,10 @@ module JetstreamBridge
     console do
       ::Rails.logger.info "[JetStream Bridge] Loaded v#{JetstreamBridge::VERSION}"
       ::Rails.logger.info '[JetStream Bridge] Console helpers available:'
-      ::Rails.logger.info '  JetstreamBridge.health           - Check connection status'
-      ::Rails.logger.info '  JetstreamBridge.healthy?         - Simple boolean health check'
+      ::Rails.logger.info '  JetstreamBridge.health_check     - Check connection status'
       ::Rails.logger.info '  JetstreamBridge.stream_info      - View stream details'
       ::Rails.logger.info '  JetstreamBridge.connected?       - Check if connected'
-      ::Rails.logger.info '  JetstreamBridge.disconnect!      - Gracefully disconnect'
+      ::Rails.logger.info '  JetstreamBridge.shutdown!        - Gracefully disconnect'
       ::Rails.logger.info '  JetstreamBridge.reconnect!       - Reconnect (useful after configuration changes)'
     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,6 +62,7 @@ namespace :jetstream_bridge do
       JetstreamBridge.config.validate!
       puts '✓ Configuration is valid'
       puts "\nCurrent settings:"
+      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}"
@@ -79,27 +80,73 @@ 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...'
 
+    permission_violation = lambda do |err|
+      current = err
+      while current
+        message = current.message.to_s
+        return true if message.include?('Permissions Violation for Publish to "$JS.API')
+        return true if message.match?(/permission(?:s)? violation/i)
+
+        current = current.cause if current.respond_to?(:cause)
+      end
+      false
+    end
+
     begin
+      provision_enabled = JetstreamBridge.config.auto_provision
       jts = JetstreamBridge.connect_and_ensure_stream!
-      puts '✓ Successfully connected to NATS'
-      puts '✓ JetStream is available'
-      puts '✓ Stream topology ensured'
-
-      # Check if we can get account info
-      info = jts.account_info
-      puts "\nAccount Info:"
-      puts "  Memory: #{info.memory}"
-      puts "  Storage: #{info.storage}"
-      puts "  Streams: #{info.streams}"
-      puts "  Consumers: #{info.consumers}"
+
+      if provision_enabled
+        puts '✓ Successfully connected to NATS'
+        puts '✓ JetStream is available'
+        puts '✓ Stream topology ensured'
+
+        # Check if we can get account info
+        info = jts.account_info
+        puts "\nAccount Info:"
+        puts "  Memory: #{info.memory}"
+        puts "  Storage: #{info.storage}"
+        puts "  Streams: #{info.streams}"
+        puts "  Consumers: #{info.consumers}"
+      else
+        nc = jts.nc if jts.respond_to?(:nc)
+        nc ||= JetstreamBridge::Connection.nc
+        nc&.flush(0.5)
+
+        puts '✓ Successfully connected to NATS (ping-only: auto_provision=false)'
+        puts '✓ JetStream client initialized (skipped $JS.API.* calls)'
+        puts "✓ Stream provisioning/verification skipped for '#{JetstreamBridge.config.stream_name}' " \
+             '(assumes pre-provisioned via admin credentials)'
+      end
 
       exit 0
     rescue StandardError => e
       puts "✗ Connection failed: #{e.message}"
+      if permission_violation.call(e)
+        puts "\nHint: current NATS credentials cannot call JetStream API subjects ($JS.API.*). " \
+             'Set config.auto_provision = false and pre-provision using ' \
+             '`bundle exec rake jetstream_bridge:provision` with admin credentials. ' \
+             'See docs/RESTRICTED_PERMISSIONS.md.'
+      end
       puts "\nBacktrace:" if ENV['VERBOSE']
       puts e.backtrace.first(10).map { |line| "  #{line}" }.join("\n") if ENV['VERBOSE']
       exit 1

data/lib/jetstream_bridge/topology/topology.rb

@@ -6,13 +6,8 @@ require_relative 'stream'
 
 module JetstreamBridge
   class Topology
-    def self.ensure!(jts, force: false)
+    def self.ensure!(jts)
       cfg = JetstreamBridge.config
-      if cfg.disable_js_api && !force
-        Logging.info('Topology ensure skipped (JS API disabled).', tag: 'JetstreamBridge::Topology')
-        return
-      end
-
       subjects = [cfg.source_subject, cfg.destination_subject]
       subjects << cfg.dlq_subject if cfg.use_dlq
       Stream.ensure!(jts, cfg.stream_name, subjects)

data/lib/jetstream_bridge/version.rb

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