nats_pubsub 1.0.0

data/lib/nats_pubsub/publisher/fluent_batch.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # FluentBatch provides a modern, chainable API for batch publishing
+  #
+  # @example Basic usage
+  #   result = NatsPubsub.batch do |b|
+  #     b.add 'user.created', { id: 1, name: 'Alice' }
+  #     b.add 'user.created', { id: 2, name: 'Bob' }
+  #     b.add 'notification.sent', { user_id: 1 }
+  #     b.with_options trace_id: 'batch-123'
+  #   end.publish
+  #
+  #   puts "Published #{result.succeeded}/#{result.total} messages"
+  #
+  class FluentBatch
+    # @!attribute [r] items
+    #   @return [Array<Hash>] The batch items
+    attr_reader :items
+
+    # @!attribute [r] options
+    #   @return [Hash] Shared options for all messages
+    attr_reader :options
+
+    # Initialize a new batch publisher
+    #
+    # @param publisher [Publisher] Optional publisher instance
+    def initialize(publisher = nil)
+      @publisher = publisher || NatsPubsub::Publisher.new
+      @items = []
+      @options = {}
+    end
+
+    # Add a message to the batch
+    #
+    # @param topic [String] Topic to publish to
+    # @param message [Hash] Message payload
+    # @return [self] For chaining
+    #
+    # @example
+    #   batch.add('user.created', { id: 1, name: 'Alice' })
+    def add(topic, message)
+      @items << { topic: topic, message: message }
+      self
+    end
+
+    # Set options for all messages in the batch
+    #
+    # @param options [Hash] Options to apply to all messages
+    # @option options [String] :trace_id Distributed tracing ID
+    # @option options [String] :correlation_id Request correlation ID
+    # @option options [String] :event_id Event ID
+    # @option options [Time] :occurred_at Event timestamp
+    # @return [self] For chaining
+    #
+    # @example
+    #   batch.with_options(trace_id: 'trace-123', correlation_id: 'req-456')
+    def with_options(**options)
+      @options.merge!(options)
+      self
+    end
+
+    # Publish all messages in the batch
+    #
+    # Messages are published in parallel for performance.
+    #
+    # @return [BatchResult] Result with success/failure details
+    #
+    # @example
+    #   result = batch.publish
+    #   puts "Succeeded: #{result.succeeded}, Failed: #{result.failed}"
+    def publish
+      start_time = Time.now
+
+      return empty_result if @items.empty?
+
+      logger&.debug "Publishing batch of #{@items.size} messages"
+
+      # Publish all items in parallel using threads
+      results = publish_parallel
+
+      succeeded = results.count { |r| r[:success] }
+      failed = results.count { |r| !r[:success] }
+
+      duration = ((Time.now - start_time) * 1000).round(2)
+
+      logger&.info "Batch publish completed: #{succeeded}/#{@items.size} succeeded, #{failed} failed (#{duration}ms)"
+
+      BatchResult.new(
+        total: @items.size,
+        succeeded: succeeded,
+        failed: failed,
+        results: results,
+        duration: duration
+      )
+    end
+
+    # Clear all items from the batch
+    #
+    # @return [self] For chaining
+    def clear
+      @items = []
+      self
+    end
+
+    # Get the number of items in the batch
+    #
+    # @return [Integer] Number of items
+    def size
+      @items.size
+    end
+
+    alias count size
+    alias length size
+
+    private
+
+    # Publish items in parallel using threads
+    #
+    # @return [Array<Hash>] Array of result hashes
+    def publish_parallel
+      threads = @items.map.with_index do |item, index|
+        Thread.new do
+          publish_single_item(item, index)
+        rescue StandardError => e
+          {
+            topic: item[:topic],
+            success: false,
+            error: e.message,
+            index: index
+          }
+        end
+      end
+
+      threads.map(&:value)
+    end
+
+    # Publish a single item
+    #
+    # @param item [Hash] Item to publish
+    # @param index [Integer] Index in the batch
+    # @return [Hash] Result hash
+    def publish_single_item(item, index)
+      @publisher.publish(
+        topic: item[:topic],
+        message: item[:message],
+        **@options
+      )
+
+      {
+        topic: item[:topic],
+        success: true,
+        event_id: @options[:event_id],
+        index: index
+      }
+    rescue StandardError => e
+      logger&.error "Batch publish failed for topic #{item[:topic]}: #{e.message}"
+
+      {
+        topic: item[:topic],
+        success: false,
+        error: e.message,
+        index: index
+      }
+    end
+
+    # Get logger from config
+    #
+    # @return [Logger, nil] Logger instance
+    def logger
+      NatsPubsub.config.logger
+    end
+
+    # Create empty result
+    #
+    # @return [BatchResult] Empty result
+    def empty_result
+      BatchResult.new(
+        total: 0,
+        succeeded: 0,
+        failed: 0,
+        results: [],
+        duration: 0.0
+      )
+    end
+  end
+
+  # Result of a batch publish operation
+  #
+  # @!attribute [r] total
+  #   @return [Integer] Total number of messages
+  # @!attribute [r] succeeded
+  #   @return [Integer] Number of successful messages
+  # @!attribute [r] failed
+  #   @return [Integer] Number of failed messages
+  # @!attribute [r] results
+  #   @return [Array<Hash>] Detailed results for each message
+  # @!attribute [r] duration
+  #   @return [Float] Duration in milliseconds
+  #
+  class BatchResult
+    attr_reader :total, :succeeded, :failed, :results, :duration
+
+    # Initialize a new batch result
+    #
+    # @param total [Integer] Total number of messages
+    # @param succeeded [Integer] Number of successful messages
+    # @param failed [Integer] Number of failed messages
+    # @param results [Array<Hash>] Detailed results
+    # @param duration [Float] Duration in milliseconds
+    def initialize(total:, succeeded:, failed:, results:, duration:)
+      @total = total
+      @succeeded = succeeded
+      @failed = failed
+      @results = results
+      @duration = duration
+    end
+
+    # Check if all messages succeeded
+    #
+    # @return [Boolean] True if all succeeded
+    def success?
+      failed.zero?
+    end
+
+    # Check if any messages failed
+    #
+    # @return [Boolean] True if any failed
+    def failure?
+      failed.positive?
+    end
+
+    # Get failed results
+    #
+    # @return [Array<Hash>] Failed results
+    def failures
+      results.reject { |r| r[:success] }
+    end
+
+    # Get successful results
+    #
+    # @return [Array<Hash>] Successful results
+    def successes
+      results.select { |r| r[:success] }
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash] Hash representation
+    def to_h
+      {
+        total: total,
+        succeeded: succeeded,
+        failed: failed,
+        results: results,
+        duration: duration
+      }
+    end
+
+    alias to_hash to_h
+  end
+end

data/lib/nats_pubsub/publisher/outbox_publisher.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative '../core/logging'
+require_relative '../models/model_utils'
+require_relative 'outbox_repository'
+require_relative 'publish_result'
+
+module NatsPubsub
+  # Service object responsible for publishing messages through the Outbox pattern
+  # Extracts outbox publishing logic from Publisher following Single Responsibility Principle
+  #
+  # The Outbox pattern ensures reliable message delivery by:
+  # 1. Persisting the message to the database before publishing
+  # 2. Publishing to NATS
+  # 3. Marking as sent in the database
+  #
+  # This prevents message loss if the application crashes between publishing and commit
+  class OutboxPublisher
+    # Publish a message using the Outbox pattern
+    #
+    # @param subject [String] NATS subject
+    # @param envelope [Hash] Message envelope
+    # @param event_id [String] Event ID
+    # @param publisher_block [Proc] Block that performs the actual publish
+    # @return [PublishResult] Result object
+    def self.publish(subject:, envelope:, event_id:, &publisher_block)
+      new(subject: subject, envelope: envelope, event_id: event_id, publisher_block: publisher_block).publish
+    end
+
+    def initialize(subject:, envelope:, event_id:, publisher_block:)
+      @subject = subject
+      @envelope = envelope
+      @event_id = event_id
+      @publisher_block = publisher_block
+    end
+
+    def publish
+      # Validate outbox model configuration
+      klass = ModelUtils.constantize(NatsPubsub.config.outbox_model)
+
+      unless ModelUtils.ar_class?(klass)
+        Logging.warn(
+          "Outbox model #{klass} is not an ActiveRecord model; publishing directly.",
+          tag: 'NatsPubsub::OutboxPublisher'
+        )
+        return @publisher_block.call
+      end
+
+      # Use repository pattern for database operations
+      repo = OutboxRepository.new(klass)
+      record = repo.find_or_build(@event_id)
+
+      # Skip if already sent (idempotency)
+      if repo.already_sent?(record)
+        Logging.info(
+          "Outbox already sent event_id=#{@event_id}; skipping publish.",
+          tag: 'NatsPubsub::OutboxPublisher'
+        )
+        return PublishResult.success(event_id: @event_id, subject: @subject)
+      end
+
+      # Persist pre-publish state
+      repo.persist_pre(record, @subject, @envelope)
+
+      # Attempt to publish
+      result = @publisher_block.call
+
+      # Update record based on result
+      if result.success?
+        repo.persist_success(record)
+      else
+        repo.persist_failure(record, result.details || 'Publish failed')
+      end
+
+      result
+    rescue StandardError => e
+      # Persist exception if repository and record are available
+      repo.persist_exception(record, e) if defined?(repo) && defined?(record)
+
+      # Return failure result
+      Logging.error(
+        "Outbox publish failed: #{e.class} #{e.message}",
+        tag: 'NatsPubsub::OutboxPublisher'
+      )
+      PublishResult.failure(
+        reason: :exception,
+        details: "#{e.class}: #{e.message}",
+        subject: @subject,
+        error: e
+      )
+    end
+
+    private
+
+    attr_reader :subject, :envelope, :event_id, :publisher_block
+  end
+end

data/lib/nats_pubsub/publisher/outbox_repository.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative '../core/base_repository'
+require_relative '../models/model_utils'
+require_relative '../core/logging'
+
+module NatsPubsub
+  # Encapsulates AR-backed outbox persistence operations.
+  # Inherits common patterns from BaseRepository.
+  class OutboxRepository < BaseRepository
+    def already_sent?(record)
+      has_attribute?(record, :sent_at) && record.sent_at
+    end
+
+    def persist_pre(record, subject, envelope)
+      now = Time.now.utc
+      event_id = envelope['event_id'].to_s
+
+      attrs = build_pre_publish_attrs(record, event_id, subject, envelope, now)
+      assign_attributes(record, attrs)
+      save_record!(record)
+    end
+
+    def persist_success(record)
+      attrs = { status: 'sent' }
+      attrs[:sent_at] = Time.now.utc if has_attribute?(record, :sent_at)
+      update_with_timestamp(record, attrs)
+    end
+
+    def persist_failure(record, error_msg)
+      attrs = { status: 'failed', last_error: error_msg }
+      update_with_timestamp(record, attrs)
+    end
+
+    def persist_exception(record, error)
+      return unless record
+
+      persist_failure(record, "#{error.class}: #{error.message}")
+    rescue StandardError => e
+      Logging.warn(
+        "Failed to persist outbox failure: #{e.class}: #{e.message}",
+        tag: 'NatsPubsub::Publisher'
+      )
+    end
+
+    # Batch operations for improved performance
+    def mark_batch_as_sent(records)
+      return 0 if records.empty?
+
+      ids = records.map { |r| model_utils.pk_value(r) }.compact
+      return 0 if ids.empty?
+
+      model = model_for(records.first)
+      now = Time.now.utc
+
+      attrs = { status: 'sent', updated_at: now }
+      attrs[:sent_at] = now if model.has_column?(:sent_at)
+
+      model.where(model.primary_key => ids).update_all(attrs)
+    end
+
+    def mark_batch_as_failed(records, error_msg)
+      return 0 if records.empty?
+
+      ids = records.map { |r| model_utils.pk_value(r) }.compact
+      return 0 if ids.empty?
+
+      model = model_for(records.first)
+
+      attrs = {
+        status: 'failed',
+        last_error: error_msg.to_s.truncate(1000),
+        updated_at: Time.now.utc
+      }
+
+      model.where(model.primary_key => ids).update_all(attrs)
+    end
+
+    def cleanup_sent_events(retention_period = 7.days.ago)
+      model = outbox_model
+      return 0 unless model
+
+      scope = model.sent
+      scope = scope.where('sent_at < ?', retention_period) if model.has_column?(:sent_at)
+      scope.delete_all
+    end
+
+    def reset_stale_publishing(threshold = 5.minutes.ago)
+      model = outbox_model
+      return 0 unless model
+
+      attrs = {
+        status: 'pending',
+        last_error: 'Reset from stale publishing state',
+        updated_at: Time.now.utc
+      }
+
+      model.stale_publishing(threshold).update_all(attrs)
+    end
+
+    private
+
+    def build_pre_publish_attrs(record, event_id, subject, envelope, timestamp)
+      attrs = {
+        event_id: event_id,
+        subject: subject,
+        payload: ModelUtils.json_dump(envelope),
+        headers: ModelUtils.json_dump({ 'nats-msg-id' => event_id }),
+        status: 'publishing',
+        last_error: nil
+      }
+      attrs[:attempts] = 1 + (record.attempts || 0) if has_attribute?(record, :attempts)
+      attrs[:enqueued_at] = (record.enqueued_at || timestamp) if has_attribute?(record, :enqueued_at)
+      attrs
+    end
+  end
+end

data/lib/nats_pubsub/publisher/publish_argument_parser.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # Parses and validates arguments for the unified Publisher#publish interface
+  # Extracts complex argument parsing logic following Single Responsibility Principle
+  #
+  # Supports three publishing patterns:
+  # 1. Topic-based: publish(topic, message) or publish(topic:, message:)
+  # 2. Domain/resource/action: publish(domain:, resource:, action:, payload:)
+  # 3. Multi-topic: publish(topics:, message:)
+  class PublishArgumentParser
+    # Parse result containing method to call and arguments
+    ParseResult = Struct.new(:method, :args, :kwargs) do
+      def call(publisher)
+        publisher.public_send(method, *args, **kwargs)
+      end
+    end
+
+    # Parse arguments and determine which publishing method to use
+    #
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    # @return [ParseResult] Parse result with method and arguments
+    # @raise [ArgumentError] if arguments are invalid
+    def self.parse(*args, **kwargs)
+      # Multi-topic publishing
+      if multi_topic?(kwargs)
+        return ParseResult.new(
+          :publish_to_topics,
+          [kwargs[:topics], kwargs[:message]],
+          kwargs.except(:topics, :message)
+        )
+      end
+
+      # Domain/resource/action pattern
+      if domain_resource_action?(kwargs)
+        return ParseResult.new(
+          :publish_event,
+          [kwargs[:domain], kwargs[:resource], kwargs[:action], kwargs[:payload]],
+          kwargs.except(:domain, :resource, :action, :payload)
+        )
+      end
+
+      # Topic-based pattern (positional args)
+      if positional_topic?(args)
+        return ParseResult.new(
+          :publish_to_topic,
+          [args[0], args[1]],
+          kwargs
+        )
+      end
+
+      # Topic-based pattern (keyword args)
+      if keyword_topic?(kwargs)
+        return ParseResult.new(
+          :publish_to_topic,
+          [kwargs[:topic], kwargs[:message]],
+          kwargs.except(:topic, :message)
+        )
+      end
+
+      # Invalid arguments
+      raise ArgumentError,
+            'Invalid arguments. Use publish(topic, message, **opts) or ' \
+            'publish(domain:, resource:, action:, payload:, **opts) or ' \
+            'publish(topics:, message:, **opts)'
+    end
+
+    # Check if arguments match multi-topic pattern
+    #
+    # @param kwargs [Hash] Keyword arguments
+    # @return [Boolean] True if multi-topic pattern
+    def self.multi_topic?(kwargs)
+      kwargs.key?(:topics) && kwargs.key?(:message)
+    end
+    private_class_method :multi_topic?
+
+    # Check if arguments match domain/resource/action pattern
+    #
+    # @param kwargs [Hash] Keyword arguments
+    # @return [Boolean] True if domain/resource/action pattern
+    def self.domain_resource_action?(kwargs)
+      kwargs.key?(:domain) &&
+        kwargs.key?(:resource) &&
+        kwargs.key?(:action) &&
+        kwargs.key?(:payload)
+    end
+    private_class_method :domain_resource_action?
+
+    # Check if arguments match positional topic pattern
+    #
+    # @param args [Array] Positional arguments
+    # @return [Boolean] True if positional topic pattern
+    def self.positional_topic?(args)
+      args.length >= 2
+    end
+    private_class_method :positional_topic?
+
+    # Check if arguments match keyword topic pattern
+    #
+    # @param kwargs [Hash] Keyword arguments
+    # @return [Boolean] True if keyword topic pattern
+    def self.keyword_topic?(kwargs)
+      kwargs.key?(:topic) && kwargs.key?(:message)
+    end
+    private_class_method :keyword_topic?
+  end
+end