event_engine-delivery 0.1.0

data/app/models/event_engine/outbox_event.rb

@@ -0,0 +1,123 @@
+module EventEngine
+  # Represents an event persisted in the outbox table. Events are written here
+  # before being published through a transport, implementing the outbox pattern
+  # for reliable delivery.
+  #
+  # @!attribute [rw] event_name
+  #   @return [String] the event name (e.g. "cow_fed")
+  # @!attribute [rw] event_type
+  #   @return [String] the event type (e.g. "domain")
+  # @!attribute [rw] event_version
+  #   @return [Integer] the schema version
+  # @!attribute [rw] payload
+  #   @return [Hash] the event payload data
+  # @!attribute [rw] metadata
+  #   @return [Hash, nil] optional contextual metadata
+  # @!attribute [rw] idempotency_key
+  #   @return [String, nil] unique key for deduplication
+  # @!attribute [rw] attempts
+  #   @return [Integer] number of publish attempts
+  # @!attribute [rw] published_at
+  #   @return [Time, nil] when the event was successfully published
+  # @!attribute [rw] dead_lettered_at
+  #   @return [Time, nil] when the event was dead-lettered
+  # @!attribute [rw] occurred_at
+  #   @return [Time] when the event occurred
+  class OutboxEvent < ApplicationRecord
+    self.table_name = "event_engine_outbox_events"
+
+    attr_readonly :event_name, :event_type, :event_version, :payload,
+                  :metadata, :occurred_at, :idempotency_key
+
+    validates :event_name, presence: true
+    validates :event_type, presence: true
+    validates :payload, presence: true
+    validates :idempotency_key, uniqueness: true, allow_nil: true
+
+    # @!scope class
+    # @!method active
+    #   Events that have not been dead-lettered.
+    #   @return [ActiveRecord::Relation]
+    scope :active, -> { where(dead_lettered_at: nil) }
+
+    # @!scope class
+    # @!method dead_lettered
+    #   Events that have been dead-lettered after exceeding max attempts.
+    #   @return [ActiveRecord::Relation]
+    scope :dead_lettered, -> { where.not(dead_lettered_at: nil) }
+
+    # @!scope class
+    # @!method ordered
+    #   Events ordered by creation time (FIFO).
+    #   @return [ActiveRecord::Relation]
+    scope :ordered, -> { order(:created_at) }
+
+    # @!scope class
+    # @!method retryable(max_attempts)
+    #   Events with fewer attempts than the maximum.
+    #   @param max_attempts [Integer]
+    #   @return [ActiveRecord::Relation]
+    scope :retryable, ->(max_attempts) { where("attempts < ?", max_attempts) }
+
+    # @!scope class
+    # @!method unpublished
+    #   Events not yet published.
+    #   @return [ActiveRecord::Relation]
+    scope :unpublished, -> { where(published_at: nil) }
+
+    # @!scope class
+    # @!method published_before(time)
+    #   Events published before a given time (for cleanup).
+    #   @param time [Time]
+    #   @return [ActiveRecord::Relation]
+    scope :published_before, ->(time) { where("published_at < ?", time) }
+
+    # @!scope class
+    # @!method cleanable
+    #   Published events that are not dead-lettered (safe to delete).
+    #   @return [ActiveRecord::Relation]
+    scope :cleanable, -> { where.not(published_at: nil).where(dead_lettered_at: nil) }
+
+    scope :for_aggregate, ->(type, id) { where(aggregate_type: type, aggregate_id: id).ordered }
+
+    def self.next_aggregate_version(type, id)
+      max = where(aggregate_type: type, aggregate_id: id).maximum(:aggregate_version)
+      (max || 0) + 1
+    end
+
+    # Marks the event as dead-lettered.
+    #
+    # @return [void]
+    def dead_letter!
+      update!(dead_lettered_at: Time.current)
+    end
+
+    # Whether the event has been dead-lettered.
+    #
+    # @return [Boolean]
+    def dead_lettered?
+      dead_lettered_at.present?
+    end
+
+    # Resets the event for retry by clearing attempts and dead-letter status.
+    #
+    # @return [void]
+    def retry!
+      update!(attempts: 0, dead_lettered_at: nil, last_error_message: nil, last_error_class: nil)
+    end
+
+    # Increments the attempt counter.
+    #
+    # @return [void]
+    def increment_attempts!
+      update!(attempts: (attempts || 0) + 1)
+    end
+
+    # Marks the event as successfully published.
+    #
+    # @return [void]
+    def mark_published!
+      update!(published_at: Time.current)
+    end
+  end
+end

data/app/views/layouts/event_engine/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Event engine</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "event_engine/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+EventEngine::Delivery::Engine.routes.draw do
+end

data/db/migrate/20251216190654_create_event_engine_outbox_events.rb

@@ -0,0 +1,9 @@
+class CreateEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :event_engine_outbox_events do |t|
+      t.string :event_name
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20251216194009_add_event_type_to_event_engine_outbox_events.rb

@@ -0,0 +1,5 @@
+class AddEventTypeToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :event_type, :string, null: false
+  end
+end

data/db/migrate/20251216201941_add_payload_to_event_engine_outbox_events.rb

@@ -0,0 +1,9 @@
+class AddPayloadToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    if connection.adapter_name.downcase.include?("postgres")
+      add_column :event_engine_outbox_events, :payload, :jsonb, null: false
+    else
+      add_column :event_engine_outbox_events, :payload, :json, null: false
+    end
+  end
+end

data/db/migrate/20251216203339_add_published_at_to_event_engine_outbox_events.rb

@@ -0,0 +1,5 @@
+class AddPublishedAtToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :published_at, :datetime
+  end
+end

data/db/migrate/20251216213819_add_idempotency_key_to_event_engine_outbox_events.rb

@@ -0,0 +1,6 @@
+class AddIdempotencyKeyToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :idempotency_key, :string
+    add_index  :event_engine_outbox_events, :idempotency_key, unique: true
+  end
+end

data/db/migrate/20251217155422_add_attempts_to_event_engine_outbox_events.rb

@@ -0,0 +1,5 @@
+class AddAttemptsToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :attempts, :integer, null: false, default: 0
+  end
+end

data/db/migrate/20251217174013_add_dead_lettered_at_to_event_engine_outbox_events.rb

@@ -0,0 +1,5 @@
+class AddDeadLetteredAtToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :dead_lettered_at, :datetime
+  end
+end

data/db/migrate/20251220213944_add_event_version_to_outbox_events.rb

@@ -0,0 +1,20 @@
+class AddEventVersionToOutboxEvents < ActiveRecord::Migration[7.1]
+  def up
+    # 1. Add column allowing NULLs
+    add_column :event_engine_outbox_events, :event_version, :integer
+
+    # 2. Backfill existing rows
+    execute <<~SQL
+      UPDATE event_engine_outbox_events
+      SET event_version = 1
+      WHERE event_version IS NULL
+    SQL
+
+    # 3. Enforce NOT NULL constraint
+    change_column_null :event_engine_outbox_events, :event_version, false
+  end
+
+  def down
+    remove_column :event_engine_outbox_events, :event_version
+  end
+end

data/db/migrate/20251221193107_add_occurred_at_and_metadata_to_outbox_events.rb

@@ -0,0 +1,6 @@
+class AddOccurredAtAndMetadataToOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :occurred_at, :datetime, null: false
+    add_column :event_engine_outbox_events, :metadata, :json
+  end
+end

data/db/migrate/20260127000000_add_indexes_to_event_engine_outbox_events.rb

@@ -0,0 +1,8 @@
+class AddIndexesToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_index :event_engine_outbox_events, :published_at
+    add_index :event_engine_outbox_events, :dead_lettered_at
+    add_index :event_engine_outbox_events, [:published_at, :dead_lettered_at, :created_at],
+              name: "idx_outbox_events_publishable"
+  end
+end

data/db/migrate/20260212000001_add_constraints_and_indexes_to_event_engine_outbox_events.rb

@@ -0,0 +1,6 @@
+class AddConstraintsAndIndexesToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    change_column_null :event_engine_outbox_events, :event_name, false
+    add_index :event_engine_outbox_events, :created_at
+  end
+end

data/db/migrate/20260212000002_add_error_context_to_event_engine_outbox_events.rb

@@ -0,0 +1,6 @@
+class AddErrorContextToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :last_error_message, :text
+    add_column :event_engine_outbox_events, :last_error_class, :string
+  end
+end

data/db/migrate/20260212000003_add_aggregate_columns_to_event_engine_outbox_events.rb

@@ -0,0 +1,9 @@
+class AddAggregateColumnsToEventEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  def change
+    add_column :event_engine_outbox_events, :aggregate_type, :string
+    add_column :event_engine_outbox_events, :aggregate_id, :string
+    add_column :event_engine_outbox_events, :aggregate_version, :integer
+    add_index :event_engine_outbox_events, [:aggregate_type, :aggregate_id],
+      name: "idx_outbox_events_aggregate"
+  end
+end

data/db/migrate/20260212000005_add_process_type_to_event_engine_outbox_events.rb

@@ -0,0 +1,5 @@
+class AddProcessTypeToEventEngineOutboxEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :event_engine_outbox_events, :process_type, :string
+  end
+end

data/db/migrate/20260921000000_add_subject_and_domain_to_event_engine_outbox_events.rb

@@ -0,0 +1,6 @@
+class AddSubjectAndDomainToEventEngineOutboxEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :event_engine_outbox_events, :subject, :string
+    add_column :event_engine_outbox_events, :domain, :string
+  end
+end

data/lib/event_engine/cloud/api_client.rb

@@ -0,0 +1,62 @@
+require "net/http"
+require "json"
+require "uri"
+
+module EventEngine
+  module Cloud
+    # HTTP client for the EventEngine Cloud ingestion API.
+    # Uses +Net::HTTP+ (stdlib) with a 5-second timeout. All errors are
+    # rescued and logged — network failures never propagate to the host app.
+    class ApiClient
+      # @return [Integer] HTTP timeout in seconds
+      TIMEOUT = 5
+
+      # @param api_key [String] the Cloud API key
+      # @param endpoint [String] the Cloud API base URL
+      def initialize(api_key:, endpoint:)
+        @api_key = api_key
+        @endpoint = endpoint
+      end
+
+      # Posts a batch of event entries to the Cloud API.
+      #
+      # @param entries [Array<Hash>] serialized event metadata entries
+      # @return [Boolean] true on success, false on failure
+      def send_batch(entries)
+        post("/events", { entries: entries })
+      end
+
+      # Posts a heartbeat with app and schema info to the Cloud API.
+      #
+      # @param heartbeat [Hash] heartbeat data
+      # @return [Boolean] true on success, false on failure
+      def send_heartbeat(heartbeat)
+        post("/heartbeat", heartbeat)
+      end
+
+      private
+
+      def post(path, body)
+        uri = URI("#{@endpoint}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = TIMEOUT
+        http.read_timeout = TIMEOUT
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request["X-EventEngine-Gem-Version"] = EventEngine::VERSION
+        request.body = JSON.generate(body)
+
+        response = http.request(request)
+        response.code.start_with?("2")
+      rescue StandardError => e
+        EventEngine::Delivery.configuration.logger.error(
+          "[EventEngine::Cloud] API request failed: #{e.class} - #{e.message}"
+        )
+        false
+      end
+    end
+  end
+end

data/lib/event_engine/cloud/batch.rb

@@ -0,0 +1,50 @@
+module EventEngine
+  module Cloud
+    # Thread-safe accumulator for Cloud Reporter entries.
+    # Entries are pushed individually and drained in bulk for flushing.
+    class Batch
+      # @param max_size [Integer] triggers auto-flush when reached
+      def initialize(max_size:)
+        @max_size = max_size
+        @entries = []
+        @mutex = Mutex.new
+      end
+
+      # Adds an entry to the batch.
+      #
+      # @param entry [Hash] serialized event metadata
+      # @return [Integer] current batch size after push
+      def push(entry)
+        @mutex.synchronize do
+          @entries << entry
+          @entries.size
+        end
+      end
+
+      # Removes and returns all entries, emptying the batch.
+      #
+      # @return [Array<Hash>]
+      def drain
+        @mutex.synchronize do
+          entries = @entries.dup
+          @entries.clear
+          entries
+        end
+      end
+
+      # Whether the batch has reached its max size.
+      #
+      # @return [Boolean]
+      def full?
+        @mutex.synchronize { @entries.size >= @max_size }
+      end
+
+      # Returns the current number of entries.
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+    end
+  end
+end

data/lib/event_engine/cloud/reporter.rb

@@ -0,0 +1,155 @@
+module EventEngine
+  module Cloud
+    # Singleton that collects event metadata and sends it to EventEngine Cloud.
+    # Manages the full lifecycle: start, collect via {Subscribers}, batch, flush, shutdown.
+    #
+    # Activated automatically at boot when +cloud_api_key+ is configured.
+    # All errors are rescued — reporter failures never affect the host application.
+    class Reporter
+      class << self
+        # Returns the singleton instance.
+        #
+        # @return [Reporter]
+        def instance
+          @instance ||= new
+        end
+
+        # Resets the singleton, discarding state without flushing.
+        #
+        # @return [void]
+        def reset!
+          if @instance
+            @instance.instance_variable_set(:@running, false)
+            timer = @instance.instance_variable_get(:@timer_thread)
+            timer&.kill
+            @instance = nil
+          end
+        end
+      end
+
+      def initialize
+        @running = false
+        @batch = nil
+        @client = nil
+        @mutex = Mutex.new
+        @timer_thread = nil
+      end
+
+      # Initializes the batch and API client, begins accepting entries.
+      #
+      # @return [void]
+      def start
+        config = EventEngine::Delivery.configuration
+        @batch = Batch.new(max_size: config.cloud_batch_size)
+        @client = ApiClient.new(
+          api_key: config.cloud_api_key,
+          endpoint: config.cloud_endpoint
+        )
+        @running = true
+        @flush_interval = config.cloud_flush_interval
+        start_timer
+
+        logger.info("[EventEngine] Cloud Reporter started — reporting to #{config.cloud_endpoint}")
+      end
+
+      # Flushes remaining entries and stops the reporter.
+      #
+      # @return [void]
+      def shutdown
+        return unless @running
+
+        @running = false
+        stop_timer
+        flush
+
+        logger.info("[EventEngine] Cloud Reporter stopped")
+      end
+
+      # Whether the reporter is currently active.
+      #
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      # Records an emitted event entry.
+      # @param entry [Hash] serialized event metadata
+      # @return [void]
+      def track_emit(entry)
+        push(entry)
+      end
+
+      # Records a published event entry.
+      # @param entry [Hash] serialized event metadata
+      # @return [void]
+      def track_publish(entry)
+        push(entry)
+      end
+
+      # Records a dead-lettered event entry.
+      # @param entry [Hash] serialized event metadata
+      # @return [void]
+      def track_dead_letter(entry)
+        push(entry)
+      end
+
+      # Drains the batch and sends entries to the Cloud API.
+      # Does nothing if the batch is empty. Errors are logged, never raised.
+      #
+      # @return [void]
+      def flush
+        return unless @batch
+
+        entries = @batch.drain
+        return if entries.empty?
+
+        @client.send_batch(entries)
+      rescue StandardError => e
+        EventEngine::Delivery.configuration.logger.error(
+          "[EventEngine::Cloud] Flush failed: #{e.class} - #{e.message}"
+        )
+      end
+
+      # Returns the number of entries currently queued.
+      #
+      # @return [Integer]
+      def batch_size
+        @batch&.size || 0
+      end
+
+      private
+
+      def start_timer
+        @timer_thread = Thread.new do
+          while @running
+            sleep(@flush_interval)
+            begin
+              flush if @running
+            rescue StandardError => e
+              logger.error("[EventEngine::Cloud] Timer thread error: #{e.class} - #{e.message}")
+            end
+          end
+        end
+      end
+
+      def stop_timer
+        return unless @timer_thread
+
+        @timer_thread.join([@flush_interval * 2, 5].min)
+        @timer_thread.kill if @timer_thread.alive?
+        @timer_thread = nil
+      end
+
+      def push(entry)
+        return unless @running && @batch
+
+        @batch.push(entry)
+        flush if @batch.full?
+      end
+
+      def logger
+        EventEngine::Delivery.configuration.logger
+      end
+    end
+  end
+end

data/lib/event_engine/cloud/serializer.rb

@@ -0,0 +1,56 @@
+module EventEngine
+  module Cloud
+    # Converts +ActiveSupport::Notifications+ payloads into metadata-only
+    # entries for the Cloud API. Event payloads and PII are never included.
+    class Serializer
+      # Serializes an event emission notification.
+      #
+      # @param notification_payload [Hash] the AS::Notifications payload
+      # @return [Hash] metadata entry with +:status+ set to +"emitted"+
+      def self.serialize_emit(notification_payload)
+        {
+          event_id: notification_payload[:event_id],
+          event_name: notification_payload[:event_name],
+          event_version: notification_payload[:event_version],
+          idempotency_key: notification_payload[:idempotency_key],
+          aggregate_type: notification_payload[:aggregate_type],
+          aggregate_id: notification_payload[:aggregate_id],
+          aggregate_version: notification_payload[:aggregate_version],
+          status: "emitted",
+          timestamp: Time.current.iso8601
+        }
+      end
+
+      # Serializes a publish notification.
+      #
+      # @param notification_payload [Hash] the AS::Notifications payload
+      # @return [Hash] metadata entry with +:status+ set to +"published"+
+      def self.serialize_publish(notification_payload)
+        {
+          event_id: notification_payload[:event_id],
+          event_name: notification_payload[:event_name],
+          event_version: notification_payload[:event_version],
+          status: "published",
+          timestamp: Time.current.iso8601
+        }
+      end
+
+      # Serializes a dead-letter notification. Includes error details.
+      #
+      # @param notification_payload [Hash] the AS::Notifications payload
+      # @return [Hash] metadata entry with +:status+ set to +"dead_lettered"+
+      def self.serialize_dead_letter(notification_payload)
+        {
+          event_id: notification_payload[:event_id],
+          event_name: notification_payload[:event_name],
+          event_version: notification_payload[:event_version],
+          status: "dead_lettered",
+          attempts: notification_payload[:attempts],
+          error_message: notification_payload[:error_message],
+          error_class: notification_payload[:error_class],
+          timestamp: Time.current.iso8601
+        }
+      end
+    end
+  end
+end

data/lib/event_engine/cloud/subscribers.rb

@@ -0,0 +1,46 @@
+module EventEngine
+  module Cloud
+    # Subscribes to +ActiveSupport::Notifications+ and feeds serialized
+    # event metadata to the {Reporter}.
+    class Subscribers
+      class << self
+        # Subscribes to all EventEngine notifications.
+        #
+        # @param reporter [Reporter] the reporter to send entries to
+        # @return [void]
+        def subscribe!(reporter:)
+          @subscriptions = []
+          @reporter = reporter
+
+          @subscriptions << ActiveSupport::Notifications.subscribe("event_engine.event_emitted") do |*, payload|
+            entry = Serializer.serialize_emit(payload)
+            @reporter.track_emit(entry)
+          end
+
+          @subscriptions << ActiveSupport::Notifications.subscribe("event_engine.event_published") do |*, payload|
+            entry = Serializer.serialize_publish(payload)
+            @reporter.track_publish(entry)
+          end
+
+          @subscriptions << ActiveSupport::Notifications.subscribe("event_engine.event_dead_lettered") do |*, payload|
+            entry = Serializer.serialize_dead_letter(payload)
+            @reporter.track_dead_letter(entry)
+          end
+        end
+
+        # Removes all notification subscriptions.
+        #
+        # @return [void]
+        def unsubscribe!
+          return unless @subscriptions
+
+          @subscriptions.each do |subscription|
+            ActiveSupport::Notifications.unsubscribe(subscription)
+          end
+          @subscriptions = nil
+          @reporter = nil
+        end
+      end
+    end
+  end
+end