jetstream_bridge 3.0.1 → 4.0.0

data/lib/jetstream_bridge/{outbox_event.rb → models/outbox_event.rb}

@@ -38,28 +38,22 @@ module JetstreamBridge
                 presence: true,
                 if: -> { self.class.has_column?(:payload) }
 
-      # Preferred path when event_id exists
       validates :event_id,
                 presence: true,
                 uniqueness: true,
                 if: -> { self.class.has_column?(:event_id) }
 
-      # Fallback legacy fields when event_id is absent
       validates :resource_type,
                 presence: true,
-                if: lambda {
-                  !self.class.has_column?(:event_id) && self.class.has_column?(:resource_type)
-                }
+                if: -> { self.class.has_column?(:resource_type) }
 
       validates :resource_id,
                 presence: true,
-                if: lambda {
-                  !self.class.has_column?(:event_id) && self.class.has_column?(:resource_id)
-                }
+                if: -> { self.class.has_column?(:resource_id) }
 
       validates :event_type,
                 presence: true,
-                if: -> { !self.class.has_column?(:event_id) && self.class.has_column?(:event_type) }
+                if: -> { self.class.has_column?(:event_type) }
 
       validates :subject,
                 presence: true,
@@ -72,25 +66,80 @@ module JetstreamBridge
       # ---- Defaults that do not require schema at load time ----
       before_validation do
         now = Time.now.utc
-        self.status ||= 'pending' if self.class.has_column?(:status) && status.blank?
+        self.status ||= JetstreamBridge::Config::Status::PENDING if self.class.has_column?(:status) && status.blank?
         self.enqueued_at ||= now if self.class.has_column?(:enqueued_at) && enqueued_at.blank?
         self.attempts = 0 if self.class.has_column?(:attempts) && attempts.nil?
       end
 
-      # ---- Helpers ----
+      # ---- Query Scopes ----
+      scope :pending, -> { where(status: JetstreamBridge::Config::Status::PENDING) if has_column?(:status) }
+      scope :publishing, -> { where(status: JetstreamBridge::Config::Status::PUBLISHING) if has_column?(:status) }
+      scope :sent, -> { where(status: JetstreamBridge::Config::Status::SENT) if has_column?(:status) }
+      scope :failed, -> { where(status: JetstreamBridge::Config::Status::FAILED) if has_column?(:status) }
+      scope :stale, lambda {
+        pending.where('created_at < ?', 1.hour.ago) if has_column?(:created_at) && has_column?(:status)
+      }
+      scope :by_resource_type, lambda { |type|
+        where(resource_type: type) if has_column?(:resource_type)
+      }
+      scope :by_event_type, lambda { |type|
+        where(event_type: type) if has_column?(:event_type)
+      }
+      scope :recent, lambda { |limit = 100|
+        order(created_at: :desc).limit(limit) if has_column?(:created_at)
+      }
+
+      # ---- Class Methods ----
+      class << self
+        # Retry failed events
+        #
+        # @param limit [Integer] Maximum number of events to retry
+        # @return [Integer] Number of events reset for retry
+        def retry_failed(limit: 100)
+          return 0 unless has_column?(:status)
+
+          failed.limit(limit).update_all(
+            status: JetstreamBridge::Config::Status::PENDING,
+            attempts: 0,
+            last_error: nil
+          )
+        end
+
+        # Clean up old sent events
+        #
+        # @param older_than [ActiveSupport::Duration] Age threshold
+        # @return [Integer] Number of records deleted
+        def cleanup_sent(older_than: 7.days)
+          return 0 unless has_column?(:status) && has_column?(:sent_at)
+
+          sent.where('sent_at < ?', older_than.ago).delete_all
+        end
+      end
+
+      # ---- Instance Methods ----
       def mark_sent!
         now = Time.now.utc
-        self.status  = 'sent' if self.class.has_column?(:status)
-        self.sent_at = now    if self.class.has_column?(:sent_at)
+        self.status  = JetstreamBridge::Config::Status::SENT if self.class.has_column?(:status)
+        self.sent_at = now if self.class.has_column?(:sent_at)
         save!
       end
 
       def mark_failed!(err_msg)
-        self.status     = 'failed' if self.class.has_column?(:status)
-        self.last_error = err_msg  if self.class.has_column?(:last_error)
+        self.status     = JetstreamBridge::Config::Status::FAILED if self.class.has_column?(:status)
+        self.last_error = err_msg if self.class.has_column?(:last_error)
         save!
       end
 
+      def retry!
+        return false unless self.class.has_column?(:status)
+
+        update!(
+          status: JetstreamBridge::Config::Status::PENDING,
+          attempts: 0,
+          last_error: nil
+        )
+      end
+
       def payload_hash
         v = self[:payload]
         case v
@@ -109,7 +158,7 @@ module JetstreamBridge
     # Shim: loud failure if AR isn't present but someone calls the model.
     class OutboxEvent
       class << self
-        def method_missing(method_name, *_args, &_block)
+        def method_missing(method_name, *_args, &)
           raise_missing_ar!('Outbox', method_name)
         end
 

data/lib/jetstream_bridge/models/publish_result.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module Models
+    # Result object returned from publish operations
+    #
+    # @example Checking result status
+    #   result = JetstreamBridge.publish(event_type: "user.created", payload: { id: 1 })
+    #   if result.success?
+    #     puts "Published with event_id: #{result.event_id}"
+    #   else
+    #     puts "Failed: #{result.error.message}"
+    #   end
+    class PublishResult
+      attr_reader :event_id, :subject, :error, :duplicate
+
+      # @param success [Boolean] Whether the publish was successful
+      # @param event_id [String] The event ID that was published
+      # @param subject [String] The NATS subject the event was published to
+      # @param error [Exception, nil] Any error that occurred
+      # @param duplicate [Boolean] Whether NATS detected this as a duplicate
+      def initialize(success:, event_id:, subject:, error: nil, duplicate: false)
+        @success = success
+        @event_id = event_id
+        @subject = subject
+        @error = error
+        @duplicate = duplicate
+        freeze
+      end
+
+      # @return [Boolean] True if the publish was successful
+      def success?
+        @success
+      end
+
+      # @return [Boolean] True if the publish failed
+      def failure?
+        !@success
+      end
+
+      # @return [Boolean] True if NATS detected this as a duplicate message
+      def duplicate?
+        @duplicate
+      end
+
+      # @return [Hash] Hash representation of the result
+      def to_h
+        {
+          success: @success,
+          event_id: @event_id,
+          subject: @subject,
+          duplicate: @duplicate,
+          error: @error&.message
+        }
+      end
+
+      alias to_hash to_h
+
+      def inspect
+        "#<#{self.class.name} success=#{@success} event_id=#{@event_id} duplicate=#{@duplicate}>"
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/models/subject.rb

@@ -3,11 +3,21 @@
 module JetstreamBridge
   module Models
     # 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"
+    #
+    # @example Parsing a subject string
+    #   subject = Subject.parse("production.api.sync.worker")
+    #   subject.env         # => "production"
+    #   subject.source_app  # => "api"
+    #   subject.dest_app    # => "worker"
     class Subject
       WILDCARD_SINGLE = '*'
       WILDCARD_MULTI = '>'
       SEPARATOR = '.'
-      INVALID_CHARS = /[#{Regexp.escape(WILDCARD_SINGLE + WILDCARD_MULTI + SEPARATOR)}]/.freeze
+      INVALID_CHARS = /[#{Regexp.escape(WILDCARD_SINGLE + WILDCARD_MULTI + SEPARATOR)}]/
 
       attr_reader :value, :tokens
 
@@ -29,8 +39,49 @@ module JetstreamBridge
         new("#{env}.#{source}.sync.#{app_name}")
       end
 
-      def self.dlq(env:)
-        new("#{env}.sync.dlq")
+      def self.dlq(env:, app_name:)
+        new("#{env}.#{app_name}.sync.dlq")
+      end
+
+      # Parse a subject string into a Subject object with metadata
+      #
+      # @param string [String] Subject string (e.g., "production.api.sync.worker")
+      # @return [Subject] Parsed subject
+      def self.parse(string)
+        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
+      #
+      # @return [String, nil] Source application
+      def source_app
+        @tokens[1]
+      end
+
+      # Get destination application from subject
+      #
+      # @return [String, nil] Destination application
+      def dest_app
+        @tokens[3]
+      end
+
+      # Check if this is a DLQ subject
+      #
+      # DLQ subjects follow the pattern: {env}.{app}.sync.dlq
+      #
+      # @return [Boolean] True if this is a DLQ subject
+      def dlq?
+        @tokens.length == 4 && @tokens[2] == 'sync' && @tokens[3] == 'dlq'
       end
 
       # Check if this subject matches a pattern
@@ -66,8 +117,9 @@ module JetstreamBridge
       def self.validate_component!(value, name)
         str = value.to_s
         if str.match?(INVALID_CHARS)
+          wildcards = "#{SEPARATOR}, #{WILDCARD_SINGLE}, #{WILDCARD_MULTI}"
           raise ArgumentError,
-                "#{name} cannot contain NATS wildcards (#{SEPARATOR}, #{WILDCARD_SINGLE}, #{WILDCARD_MULTI}): #{value.inspect}"
+                "#{name} cannot contain NATS wildcards (#{wildcards}): #{value.inspect}"
         end
         raise ArgumentError, "#{name} cannot be empty" if str.strip.empty?
 

data/lib/jetstream_bridge/publisher/batch_publisher.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'oj'
+require_relative '../core/logging'
+require_relative '../models/publish_result'
+
+module JetstreamBridge
+  # Batch publisher for efficient bulk event publishing.
+  #
+  # BatchPublisher allows you to queue multiple events and publish them together,
+  # providing detailed results about successes and failures. Each event is published
+  # independently, so partial failures are possible.
+  #
+  # @example Publishing multiple events
+  #   results = JetstreamBridge.publish_batch do |batch|
+  #     users.each do |user|
+  #       batch.add(event_type: "user.created", payload: { id: user.id })
+  #     end
+  #   end
+  #
+  #   puts "Published: #{results.successful_count}, Failed: #{results.failed_count}"
+  #   results.errors.each { |e| logger.error("Failed: #{e[:event_id]}") }
+  #
+  # @example Checking for failures
+  #   results = JetstreamBridge.publish_batch do |batch|
+  #     batch.add(event_type: "order.created", payload: { id: 1 })
+  #     batch.add(event_type: "order.updated", payload: { id: 2 })
+  #   end
+  #
+  #   if results.failure?
+  #     logger.warn "Some events failed to publish"
+  #   end
+  #
+  class BatchPublisher
+    # Result object for batch operations.
+    #
+    # Contains aggregated results from a batch publish operation, including
+    # success/failure counts and detailed error information.
+    #
+    # @example Checking results
+    #   results = JetstreamBridge.publish_batch { |b| ... }
+    #   puts "Success: #{results.successful_count}"
+    #   puts "Failed: #{results.failed_count}"
+    #   puts "Partial: #{results.partial_success?}"
+    #
+    class BatchResult
+      # @return [Array<Models::PublishResult>] All individual publish results
+      attr_reader :results
+      # @return [Integer] Number of successfully published events
+      attr_reader :successful_count
+      # @return [Integer] Number of failed events
+      attr_reader :failed_count
+      # @return [Array<Hash>] Array of error details with event_id and error
+      attr_reader :errors
+
+      # @param results [Array<Models::PublishResult>] Individual publish results
+      # @api private
+      def initialize(results)
+        @results = results
+        @successful_count = results.count(&:success?)
+        @failed_count = results.count(&:failure?)
+        @errors = results.select(&:failure?).map { |r| { event_id: r.event_id, error: r.error } }
+        freeze
+      end
+
+      # Check if all events published successfully.
+      #
+      # @return [Boolean] True if no failures
+      def success?
+        @failed_count.zero?
+      end
+
+      # Check if any events failed to publish.
+      #
+      # @return [Boolean] True if any failures
+      def failure?
+        !success?
+      end
+
+      # Check if some (but not all) events published successfully.
+      #
+      # @return [Boolean] True if both successes and failures exist
+      def partial_success?
+        @successful_count.positive? && @failed_count.positive?
+      end
+
+      def to_h
+        {
+          successful_count: @successful_count,
+          failed_count: @failed_count,
+          total_count: @results.size,
+          errors: @errors
+        }
+      end
+
+      alias to_hash to_h
+    end
+
+    def initialize(publisher = nil)
+      @publisher = publisher || Publisher.new
+      @events = []
+    end
+
+    # Add an event to the batch
+    #
+    # @param event_or_hash [Hash] Event data
+    # @param resource_type [String, nil] Resource type
+    # @param event_type [String, nil] Event type
+    # @param payload [Hash, nil] Payload data
+    # @param options [Hash] Additional options
+    # @return [self] Returns self for chaining
+    def add(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, **options)
+      @events << {
+        event_or_hash: event_or_hash,
+        resource_type: resource_type,
+        event_type: event_type,
+        payload: payload,
+        options: options
+      }
+      self
+    end
+
+    # Publish all events in the batch
+    #
+    # @return [BatchResult] Result containing success/failure counts
+    def publish
+      results = @events.map do |event_data|
+        @publisher.publish(
+          event_data[:event_or_hash],
+          resource_type: event_data[:resource_type],
+          event_type: event_data[:event_type],
+          payload: event_data[:payload],
+          **event_data[:options]
+        )
+      rescue StandardError => e
+        Models::PublishResult.new(
+          success: false,
+          event_id: 'unknown',
+          subject: 'unknown',
+          error: e
+        )
+      end
+
+      BatchResult.new(results)
+    ensure
+      @events.clear
+    end
+
+    # Get number of events queued
+    #
+    # @return [Integer] Number of events in batch
+    def size
+      @events.size
+    end
+
+    alias count size
+    alias length size
+
+    def empty?
+      @events.empty?
+    end
+  end
+end