jetstream_bridge 3.0.2 → 4.0.0

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -7,33 +7,185 @@ 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'
 
 module JetstreamBridge
-  # Publishes to "{env}.{app}.sync.{dest}".
+  # Publishes events to NATS JetStream with reliability features.
+  #
+  # Publishes events to "{env}.{app}.sync.{dest}" subject pattern.
+  # Supports optional transactional outbox pattern for guaranteed delivery.
+  #
+  # @example Basic publishing
+  #   publisher = JetstreamBridge::Publisher.new
+  #   result = publisher.publish(
+  #     resource_type: "user",
+  #     event_type: "created",
+  #     payload: { id: 1, email: "ada@example.com" }
+  #   )
+  #   puts "Published: #{result.event_id}" if result.success?
+  #
+  # @example Publishing with custom retry strategy
+  #   custom_strategy = MyRetryStrategy.new(max_attempts: 5)
+  #   publisher = JetstreamBridge::Publisher.new(retry_strategy: custom_strategy)
+  #   result = publisher.publish(event_type: "user.created", payload: { id: 1 })
+  #
+  # @example Using convenience method
+  #   JetstreamBridge.publish(event_type: "user.created", payload: { id: 1 })
+  #
   class Publisher
+    # Initialize a new Publisher instance.
+    #
+    # @param retry_strategy [RetryStrategy, nil] Optional custom retry strategy for handling transient failures.
+    #   Defaults to PublisherRetryStrategy with exponential backoff.
+    # @raise [ConnectionError] If unable to connect to NATS server
     def initialize(retry_strategy: nil)
       @jts = Connection.connect!
       @retry_strategy = retry_strategy || PublisherRetryStrategy.new
     end
 
-    # @return [Boolean]
-    def publish(resource_type:, event_type:, payload:, **options)
+    # Publishes an event to NATS JetStream.
+    #
+    # Supports multiple usage patterns for flexibility:
+    #
+    # 1. Structured parameters (recommended):
+    #    publish(resource_type: 'user', event_type: 'created', payload: { id: 1, name: 'Ada' })
+    #
+    # 2. Hash/envelope with dot notation (auto-infers resource_type):
+    #    publish(event_type: 'user.created', payload: {...})
+    #
+    # 3. Complete envelope (advanced):
+    #    publish({ event_type: 'created', resource_type: 'user', payload: {...}, event_id: '...' })
+    #
+    # When use_outbox is enabled, events are persisted to database first for reliability.
+    # The event_id is used for deduplication via NATS message ID header.
+    #
+    # @param event_or_hash [Hash, nil] Complete event envelope (if using pattern 3)
+    # @param resource_type [String, nil] Resource type (e.g., 'user', 'order'). Required for pattern 1.
+    # @param event_type [String, nil] Event type (e.g., 'created', 'user.created'). Required for all patterns.
+    # @param payload [Hash, nil] Event payload data. Required for all patterns.
+    # @param subject [String, nil] Optional NATS subject override. Defaults to config.source_subject.
+    # @param options [Hash] Additional options:
+    #   - event_id [String] Custom event ID (auto-generated if not provided)
+    #   - trace_id [String] Distributed trace ID
+    #   - occurred_at [Time, String] Event timestamp (defaults to current time)
+    #
+    # @return [Models::PublishResult] Result object containing:
+    #   - success [Boolean] Whether publish succeeded
+    #   - event_id [String] The published event ID
+    #   - subject [String] NATS subject used
+    #   - error [Exception, nil] Error if publish failed
+    #   - duplicate [Boolean] Whether NATS detected as duplicate
+    #
+    # @raise [ArgumentError] If required parameters are missing or invalid
+    #
+    # @example Structured parameters
+    #   result = publisher.publish(
+    #     resource_type: "user",
+    #     event_type: "created",
+    #     payload: { id: 1, email: "ada@example.com" }
+    #   )
+    #   puts "Published: #{result.event_id}" if result.success?
+    #
+    # @example With options
+    #   result = publisher.publish(
+    #     event_type: "user.created",
+    #     payload: { id: 1 },
+    #     event_id: "custom-id-123",
+    #     trace_id: request_id,
+    #     occurred_at: Time.now.utc
+    #   )
+    #
+    # @example Error handling
+    #   result = publisher.publish(event_type: "order.created", payload: { id: 1 })
+    #   if result.failure?
+    #     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)
       ensure_destination!
-      envelope = build_envelope(resource_type, event_type, payload, options)
-      subject  = JetstreamBridge.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
+
+    # Internal publish method that routes to appropriate publish strategy.
+    #
+    # Routes to outbox-based publishing if use_outbox is enabled, otherwise
+    # publishes directly to NATS with retry logic.
+    #
+    # @param subject [String] NATS subject to publish to
+    # @param envelope [Hash] Complete event envelope
+    # @return [Models::PublishResult] Result object
+    # @api private
+    def do_publish(subject, envelope)
       if JetstreamBridge.config.use_outbox
         publish_via_outbox(subject, envelope)
       else
         with_retries { publish_to_nats(subject, envelope) }
       end
-    rescue StandardError => e
-      log_error(false, e)
     end
 
     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
+
+      resolved_subject = params[:subject] || params[:options][:subject] || JetstreamBridge.config.source_subject
+      [envelope, resolved_subject]
+    end
+
+    def build_from_keywords(event_type, payload, options)
+      raise ArgumentError, 'event_type is required' unless event_type
+      raise ArgumentError, 'payload is required' unless payload
+
+      normalize_envelope({ 'event_type' => event_type, 'payload' => payload }, options)
+    end
+
     def ensure_destination!
       return unless JetstreamBridge.config.destination_app.to_s.empty?
 
@@ -55,9 +207,21 @@ module JetstreamBridge
           "Publish ack error: #{ack.error}",
           tag: 'JetstreamBridge::Publisher'
         )
+        return Models::PublishResult.new(
+          success: false,
+          event_id: envelope['event_id'],
+          subject: subject,
+          error: StandardError.new(ack.error.to_s),
+          duplicate: duplicate
+        )
       end
 
-      !ack.respond_to?(:error) || ack.error.nil?
+      Models::PublishResult.new(
+        success: true,
+        event_id: envelope['event_id'],
+        subject: subject,
+        duplicate: duplicate
+      )
     end
 
     # ---- Outbox path ----
@@ -81,17 +245,31 @@ module JetstreamBridge
           "Outbox already sent event_id=#{event_id}; skipping publish.",
           tag: 'JetstreamBridge::Publisher'
         )
-        return true
+        return Models::PublishResult.new(
+          success: true,
+          event_id: event_id,
+          subject: subject,
+          duplicate: true
+        )
       end
 
       repo.persist_pre(record, subject, envelope)
 
-      ok = with_retries { publish_to_nats(subject, envelope) }
-      ok ? repo.persist_success(record) : repo.persist_failure(record, 'Publish returned false')
-      ok
+      result = with_retries { publish_to_nats(subject, envelope) }
+      if result.success?
+        repo.persist_success(record)
+      else
+        repo.persist_failure(record, result.error&.message || 'Publish failed')
+      end
+      result
     rescue StandardError => e
       repo.persist_exception(record, e) if defined?(repo) && defined?(record)
-      log_error(false, e)
+      Models::PublishResult.new(
+        success: false,
+        event_id: envelope['event_id'],
+        subject: subject,
+        error: e
+      )
     end
     # ---- /Outbox path ----
 
@@ -99,15 +277,11 @@ module JetstreamBridge
     def with_retries(&)
       @retry_strategy.execute(context: 'Publisher', &)
     rescue RetryStrategy::RetryExhausted => e
-      log_error(false, e)
-    end
-
-    def log_error(val, exc)
       Logging.error(
-        "Publish failed: #{exc.class} #{exc.message}",
+        "Publish failed after retries: #{e.class} #{e.message}",
         tag: 'JetstreamBridge::Publisher'
       )
-      val
+      raise
     end
 
     def build_envelope(resource_type, event_type, payload, options = {})
@@ -123,5 +297,50 @@ module JetstreamBridge
         '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/test_helpers.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module JetstreamBridge
+  # Test helpers for easier testing of JetStream Bridge integrations
+  #
+  # @example RSpec configuration
+  #   require 'jetstream_bridge/test_helpers'
+  #
+  #   RSpec.configure do |config|
+  #     config.include JetstreamBridge::TestHelpers
+  #
+  #     config.before(:each, :jetstream) do
+  #       JetstreamBridge::TestHelpers.enable_test_mode!
+  #     end
+  #
+  #     config.after(:each, :jetstream) do
+  #       JetstreamBridge::TestHelpers.reset_test_mode!
+  #     end
+  #   end
+  #
+  # @example Using in tests
+  #   RSpec.describe UserService, :jetstream do
+  #     it "publishes user created event" do
+  #       service.create_user(name: "Ada")
+  #
+  #       expect(JetstreamBridge).to have_published(
+  #         event_type: "user.created",
+  #         payload: hash_including(name: "Ada")
+  #       )
+  #     end
+  #   end
+  #
+  module TestHelpers
+    class << self
+      # Enable test mode with in-memory event capture
+      #
+      # @return [void]
+      def enable_test_mode!
+        @test_mode = true
+        @published_events = []
+        @consumed_events = []
+      end
+
+      # Reset test mode and clear captured events
+      #
+      # @return [void]
+      def reset_test_mode!
+        @test_mode = false
+        @published_events = []
+        @consumed_events = []
+      end
+
+      # Check if test mode is enabled
+      #
+      # @return [Boolean]
+      def test_mode?
+        @test_mode ||= false
+      end
+
+      # Get all published events captured in test mode
+      #
+      # @return [Array<Hash>] Array of published event hashes
+      def published_events
+        @published_events ||= []
+      end
+
+      # Get all consumed events captured in test mode
+      #
+      # @return [Array<Hash>] Array of consumed event hashes
+      def consumed_events
+        @consumed_events ||= []
+      end
+
+      # Record a published event (called internally)
+      #
+      # @param event [Hash] Event data
+      # @return [void]
+      def record_published_event(event)
+        @published_events ||= []
+        @published_events << event.dup
+      end
+
+      # Record a consumed event (called internally)
+      #
+      # @param event [Hash] Event data
+      # @return [void]
+      def record_consumed_event(event)
+        @consumed_events ||= []
+        @consumed_events << event.dup
+      end
+    end
+
+    # Build a test Event object
+    #
+    # @param event_type [String] Event type (e.g., "user.created")
+    # @param payload [Hash] Event payload
+    # @param event_id [String, nil] Optional event ID
+    # @param trace_id [String, nil] Optional trace ID
+    # @param occurred_at [Time, String, nil] Optional timestamp
+    # @param metadata [Hash] Optional metadata
+    # @return [Models::Event] Event object
+    #
+    # @example
+    #   event = build_jetstream_event(
+    #     event_type: "user.created",
+    #     payload: { id: 1, email: "user@example.com" }
+    #   )
+    #   handler.call(event)
+    #
+    def build_jetstream_event(event_type:, payload:, event_id: nil, trace_id: nil, occurred_at: nil, **metadata)
+      event_hash = {
+        'event_id' => event_id || SecureRandom.uuid,
+        'schema_version' => 1,
+        'event_type' => event_type,
+        'producer' => 'test',
+        'resource_id' => (payload['id'] || payload[:id] || '').to_s,
+        'occurred_at' => (occurred_at || Time.now.utc).iso8601,
+        'trace_id' => trace_id || SecureRandom.hex(8),
+        'resource_type' => event_type.split('.').first || 'event',
+        'payload' => payload
+      }
+
+      Models::Event.new(
+        event_hash,
+        metadata: {
+          subject: metadata[:subject] || 'test.subject',
+          deliveries: metadata[:deliveries] || 1,
+          stream: metadata[:stream] || 'test-stream',
+          sequence: metadata[:sequence] || 1,
+          consumer: metadata[:consumer] || 'test-consumer',
+          timestamp: Time.now
+        }
+      )
+    end
+
+    # Simulate triggering an event to a consumer
+    #
+    # @param event [Models::Event, Hash] Event to trigger
+    # @param handler [Proc, #call] Handler to call with event
+    # @return [void]
+    #
+    # @example
+    #   event = build_jetstream_event(event_type: "user.created", payload: { id: 1 })
+    #   trigger_jetstream_event(event, ->(e) { process_event(e) })
+    #
+    def trigger_jetstream_event(event, handler = nil)
+      handler ||= @handler if defined?(@handler)
+      raise ArgumentError, 'handler is required' unless handler
+
+      TestHelpers.record_consumed_event(event.to_h) if TestHelpers.test_mode?
+      handler.call(event)
+    end
+
+    # RSpec matchers module
+    #
+    # @example Include in RSpec
+    #   RSpec.configure do |config|
+    #     config.include JetstreamBridge::TestHelpers
+    #     config.include JetstreamBridge::TestHelpers::Matchers
+    #   end
+    #
+    module Matchers
+      # Matcher for checking if an event was published
+      #
+      # @param event_type [String] Event type to match
+      # @param payload [Hash] Optional payload attributes to match
+      # @return [HavePublished] Matcher instance
+      #
+      # @example
+      #   expect(JetstreamBridge).to have_published(
+      #     event_type: "user.created",
+      #     payload: { id: 1 }
+      #   )
+      #
+      def have_published(event_type:, payload: {})
+        HavePublished.new(event_type, payload)
+      end
+
+      # Matcher implementation for have_published
+      class HavePublished
+        def initialize(event_type, payload_attributes)
+          @event_type = event_type
+          @payload_attributes = payload_attributes
+        end
+
+        def matches?(_actual)
+          TestHelpers.published_events.any? do |event|
+            matches_event_type?(event) && matches_payload?(event)
+          end
+        end
+
+        def failure_message
+          "expected to have published event_type: #{@event_type.inspect} " \
+            "with payload: #{@payload_attributes.inspect}\n" \
+            "but found events: #{TestHelpers.published_events.map { |e| e['event_type'] }.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected not to have published event_type: #{@event_type.inspect} " \
+            "with payload: #{@payload_attributes.inspect}"
+        end
+
+        private
+
+        def matches_event_type?(event)
+          event['event_type'] == @event_type || event[:event_type] == @event_type
+        end
+
+        def matches_payload?(event)
+          payload = event['payload'] || event[:payload] || {}
+          @payload_attributes.all? do |key, value|
+            payload_value = payload[key.to_s] || payload[key.to_sym]
+            if value.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
+              value.matches?(payload)
+            else
+              payload_value == value
+            end
+          end
+        end
+      end
+
+      # Matcher for checking publish result
+      #
+      # @example
+      #   result = JetstreamBridge.publish(...)
+      #   expect(result).to be_publish_success
+      #
+      def be_publish_success
+        BePublishSuccess.new
+      end
+
+      # Matcher implementation for be_publish_success
+      class BePublishSuccess
+        def matches?(actual)
+          actual.respond_to?(:success?) && actual.success?
+        end
+
+        def failure_message
+          'expected PublishResult to be successful but it failed'
+        end
+
+        def failure_message_when_negated
+          'expected PublishResult to not be successful but it was'
+        end
+      end
+
+      # Matcher for checking publish failure
+      #
+      # @example
+      #   result = JetstreamBridge.publish(...)
+      #   expect(result).to be_publish_failure
+      #
+      def be_publish_failure
+        BePublishFailure.new
+      end
+
+      # Matcher implementation for be_publish_failure
+      class BePublishFailure
+        def matches?(actual)
+          actual.respond_to?(:failure?) && actual.failure?
+        end
+
+        def failure_message
+          'expected PublishResult to be a failure but it succeeded'
+        end
+
+        def failure_message_when_negated
+          'expected PublishResult to not be a failure but it was'
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/version.rb

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