jetstream_bridge 4.4.0 → 4.5.0

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -2,13 +2,13 @@
 
 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.
@@ -34,19 +34,20 @@ module JetstreamBridge
   #   JetstreamBridge.publish(event_type: "user.created", payload: { id: 1 })
   #
   class Publisher
-    # Initialize a new Publisher instance.
+    # Initialize a new Publisher instance with dependency injection.
     #
-    # 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
-
+    # @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
       @retry_strategy = retry_strategy || PublisherRetryStrategy.new
+      @envelope_builder = EventEnvelopeBuilder
     end
 
     # Publishes an event to NATS JetStream.
@@ -107,12 +108,17 @@ module JetstreamBridge
     #     logger.error "Failed to publish: #{result.error.message}"
     #   end
     #
-    def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **options)
+    def publish(event_type:, payload:, resource_type: nil, subject: nil, **)
       ensure_destination_app_configured!
 
-      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)
+      envelope = @envelope_builder.build(
+        event_type: event_type,
+        payload: payload,
+        resource_type: resource_type,
+        **
+      )
+
+      resolved_subject = subject || @config.source_subject
 
       do_publish(resolved_subject, envelope)
     rescue ArgumentError
@@ -128,6 +134,61 @@ module JetstreamBridge
       )
     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
+      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
+
     # Internal publish method that routes to appropriate publish strategy.
     #
     # Routes to outbox-based publishing if use_outbox is enabled, otherwise
@@ -138,7 +199,7 @@ module JetstreamBridge
     # @return [Models::PublishResult] Result object
     # @api private
     def do_publish(subject, envelope)
-      if JetstreamBridge.config.use_outbox
+      if @config.use_outbox
         publish_via_outbox(subject, envelope)
       else
         with_retries { publish_to_nats(subject, envelope) }
@@ -147,52 +208,20 @@ module JetstreamBridge
 
     private
 
-    # 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
-
-    def keyword_or_hash_params?(params)
-      params[:event_type] || params[:payload] || params[:event_or_hash].is_a?(Hash)
-    end
-
-    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
+    # 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]
 
-      resolved_subject = params[:subject] || params[:options][:subject] || JetstreamBridge.config.source_subject
-      [envelope, resolved_subject]
-    end
+      missing = required_fields.select { |field| envelope[field].nil? || envelope[field].to_s.strip.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
+      return if missing.empty?
 
-      normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
+      raise ArgumentError, "Envelope missing required fields: #{missing.join(', ')}"
     end
 
     def ensure_destination_app_configured!
-      return unless JetstreamBridge.config.destination_app.to_s.empty?
+      return unless @config.destination_app.to_s.empty?
 
       raise ArgumentError, 'destination_app must be configured'
     end
@@ -231,7 +260,7 @@ module JetstreamBridge
 
     # ---- Outbox path ----
     def publish_via_outbox(subject, envelope)
-      klass = ModelUtils.constantize(JetstreamBridge.config.outbox_model)
+      klass = ModelUtils.constantize(@config.outbox_model)
 
       unless ModelUtils.ar_class?(klass)
         Logging.warn(
@@ -288,64 +317,5 @@ 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
   end
 end

data/lib/jetstream_bridge/rails/integration.rb

@@ -2,7 +2,6 @@
 
 require_relative '../core/model_codec_setup'
 require_relative '../core/logging'
-require_relative '../core/connection'
 
 module JetstreamBridge
   module Rails
@@ -38,8 +37,7 @@ module JetstreamBridge
           return
         end
 
-        JetstreamBridge.config.validate!
-        JetstreamBridge.startup!
+        JetstreamBridge.connect!
         log_started!
         log_development_connection_details! if rails_development?
         register_shutdown_hook!
@@ -105,7 +103,12 @@ module JetstreamBridge
       end
 
       def log_development_connection_details!
-        conn_state = JetstreamBridge::Connection.instance.state
+        health = begin
+          JetstreamBridge.health
+        rescue StandardError
+          nil
+        end
+        conn_state = health&.dig(:connection, :state) || 'unknown'
         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}")
@@ -116,7 +119,7 @@ module JetstreamBridge
       def register_shutdown_hook!
         return if @shutdown_hook_registered
 
-        at_exit { JetstreamBridge.shutdown! }
+        at_exit { JetstreamBridge.disconnect! }
         @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 (explicit startup!)
+  # - Startup: Connection is established after user initializers load (connect!)
   # - Shutdown: Connection is closed when Rails shuts down (at_exit hook)
   # - Restart: Puma/Unicorn workers get fresh connections on fork
   #
@@ -33,10 +33,11 @@ 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     - Check connection status'
+      ::Rails.logger.info '  JetstreamBridge.health           - Check connection status'
+      ::Rails.logger.info '  JetstreamBridge.healthy?         - Simple boolean health check'
       ::Rails.logger.info '  JetstreamBridge.stream_info      - View stream details'
       ::Rails.logger.info '  JetstreamBridge.connected?       - Check if connected'
-      ::Rails.logger.info '  JetstreamBridge.shutdown!        - Gracefully disconnect'
+      ::Rails.logger.info '  JetstreamBridge.disconnect!      - Gracefully disconnect'
       ::Rails.logger.info '  JetstreamBridge.reconnect!       - Reconnect (useful after configuration changes)'
     end
 

data/lib/jetstream_bridge/tasks/install.rake

@@ -62,7 +62,6 @@ namespace :jetstream_bridge do
       JetstreamBridge.config.validate!
       puts '✓ Configuration is valid'
       puts "\nCurrent settings:"
-      puts "  Environment: #{JetstreamBridge.config.env}"
       puts "  App Name: #{JetstreamBridge.config.app_name}"
       puts "  Destination: #{JetstreamBridge.config.destination_app}"
       puts "  Stream: #{JetstreamBridge.config.stream_name}"

data/lib/jetstream_bridge/topology/topology.rb

@@ -6,8 +6,13 @@ require_relative 'stream'
 
 module JetstreamBridge
   class Topology
-    def self.ensure!(jts)
+    def self.ensure!(jts, force: false)
       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.4.0'
+  VERSION = '4.5.0'
 end