event_engine-delivery 0.1.0

data/lib/event_engine/definition_transport_check.rb

@@ -0,0 +1,35 @@
+module EventEngine
+  # Inspects loaded event definitions at boot and logs a non-blocking warning
+  # when a :broker event exists but no real transport is configured (a :broker
+  # event publishes to a broker, so it needs one). This is a soft, early signal;
+  # the hard failure happens at runtime in {OutboxRouter} when such an event is
+  # actually drained.
+  module DefinitionTransportCheck
+    # @param registry [SchemaRegistry] the loaded registry
+    # @param transport [#publish, nil] the configured transport
+    # @param logger [Logger] where to write the warning
+    # @param processing_rules [ProcessingRules] what decides an event's process type
+    # @return [void]
+    def self.run(registry:, transport:, logger:, processing_rules: EventEngine.processing_rules)
+      return if real_transport?(transport)
+
+      broker = registry.events.select { |name| broker?(registry.schema(name), processing_rules) }
+      return if broker.empty?
+
+      logger.warn(
+        "[EventEngine] No transport configured, but these :broker events require one: " \
+        "#{broker.join(', ')}. They will raise when published. Set config.transport."
+      )
+    end
+
+    def self.broker?(schema, processing_rules)
+      processing_rules.for(event_name: schema.event_name, pack: schema.domain) == :broker
+    end
+    private_class_method :broker?
+
+    def self.real_transport?(transport)
+      !transport.nil? && !(transport.respond_to?(:null?) && transport.null?)
+    end
+    private_class_method :real_transport?
+  end
+end

data/lib/event_engine/delivery/configuration.rb

@@ -0,0 +1,65 @@
+module EventEngine
+  module Delivery
+    # Configuration for the delivery layer: transport, outbox publisher behavior,
+    # retention, the dashboard, and the cloud reporter.
+    #
+    # @example
+    #   EventEngine::Delivery.configure do |config|
+    #     config.transport = EventEngine::Transports::Kafka.new(producer: producer)
+    #     config.delivery_adapter = :active_job
+    #   end
+    class Configuration
+      class InvalidConfigurationError < StandardError; end
+
+      attr_accessor :delivery_adapter, :transport, :batch_size, :max_attempts, :retention_period, :dashboard_auth, :logger,
+                    :cloud_api_key, :cloud_endpoint, :cloud_environment, :cloud_app_name, :cloud_batch_size, :cloud_flush_interval
+
+      VALID_DELIVERY_ADAPTERS = %i[inline active_job manual].freeze
+
+      def initialize
+        @delivery_adapter = :inline
+        @transport = ::EventEngine::Transports::NullTransport.new
+        @batch_size = 100
+        @max_attempts = 5
+        @retention_period = nil
+        @dashboard_auth = nil
+        @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+        @cloud_api_key = nil
+        @cloud_endpoint = "https://api.eventengine.dev/v1/ingest"
+        @cloud_environment = nil
+        @cloud_app_name = nil
+        @cloud_batch_size = 50
+        @cloud_flush_interval = 10
+      end
+
+      def cloud_enabled?
+        cloud_api_key.present?
+      end
+
+      def validate!
+        unless VALID_DELIVERY_ADAPTERS.include?(delivery_adapter)
+          raise InvalidConfigurationError,
+            "Invalid delivery_adapter: #{delivery_adapter.inspect}. Must be one of: #{VALID_DELIVERY_ADAPTERS.join(', ')}"
+        end
+
+        if delivery_adapter == :active_job && (transport.nil? || transport.is_a?(::EventEngine::Transports::NullTransport))
+          raise InvalidConfigurationError,
+            "Transport must be configured when using :active_job delivery adapter. " \
+            "Set config.transport in your EventEngine::Delivery initializer."
+        end
+
+        if transport && !transport.respond_to?(:publish)
+          raise InvalidConfigurationError, "Transport must respond to #publish"
+        end
+
+        unless batch_size.is_a?(Integer) && batch_size > 0
+          raise InvalidConfigurationError, "batch_size must be a positive integer, got: #{batch_size.inspect}"
+        end
+
+        unless max_attempts.is_a?(Integer) && max_attempts > 0
+          raise InvalidConfigurationError, "max_attempts must be a positive integer, got: #{max_attempts.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/delivery/engine.rb

@@ -0,0 +1,25 @@
+module EventEngine
+  module Delivery
+    class Engine < ::Rails::Engine
+      engine_name "event_engine_delivery"
+
+      initializer "event_engine.delivery.register_handler" do
+        config.after_initialize do
+          EventEngine.register_handler(Handler.new, process_types: :all)
+          Engine.send(:start_cloud_reporter!)
+        end
+      end
+
+      class << self
+        private
+
+        def start_cloud_reporter!
+          return unless Delivery.configuration.cloud_enabled?
+
+          ::EventEngine::Cloud::Subscribers.subscribe!(reporter: ::EventEngine::Cloud::Reporter.instance)
+          ::EventEngine::Cloud::Reporter.instance.start
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/delivery/handler.rb

@@ -0,0 +1,52 @@
+module EventEngine
+  module Delivery
+    # The delivery handler registered with EventEngine core. Receives a built
+    # Event and handles only durable/broker events: it writes them to the outbox
+    # and publishes them. :inline and :background events are run by
+    # event_engine-subscribers, not here.
+    class Handler
+      def call(event)
+        case process_type_for(event)
+        when :inline, :background then nil # run by event_engine-subscribers
+        else write_and_publish(event)
+        end
+      end
+
+      private
+
+      def process_type_for(event)
+        event.process_type&.to_sym
+      end
+
+      def write_and_publish(event)
+        outbox_event = OutboxWriter.write(event.to_h)
+
+        ActiveSupport::Notifications.instrument("event_engine.event_emitted", {
+          event_name: outbox_event.event_name,
+          event_version: outbox_event.event_version,
+          event_id: outbox_event.id,
+          idempotency_key: outbox_event.idempotency_key,
+          aggregate_type: outbox_event.aggregate_type,
+          aggregate_id: outbox_event.aggregate_id,
+          aggregate_version: outbox_event.aggregate_version
+        })
+
+        Delivery.enqueue do
+          transport = Delivery.configuration.transport
+          unless transport
+            Rails.logger.warn("[EventEngine::Delivery] No transport configured — event written to outbox but not published. " \
+              "Set config.transport in your EventEngine::Delivery initializer to enable publishing.")
+            next
+          end
+
+          OutboxPublisher.new(
+            router: OutboxRouter.new(transport: transport),
+            batch_size: Delivery.configuration.batch_size
+          ).call
+        end
+
+        outbox_event
+      end
+    end
+  end
+end

data/lib/event_engine/delivery/version.rb

@@ -0,0 +1,5 @@
+module EventEngine
+  module Delivery
+    VERSION = "0.1.0"
+  end
+end

data/lib/event_engine/delivery.rb

@@ -0,0 +1,61 @@
+module EventEngine
+  module Delivery
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+    end
+
+    def self.enqueue(&block)
+      adapter = configuration.delivery_adapter || :inline
+
+      case adapter
+      when :inline
+        if block_given?
+          if ActiveRecord::Base.connection.transaction_open?
+            AfterCommitCallback.register(ActiveRecord::Base.connection, &block)
+          else
+            yield
+          end
+        end
+      when :active_job
+        PublishOutboxEventsJob.perform_later
+      when :manual
+        # No automatic delivery. The outbox is drained only by an explicit
+        # OutboxPublisher call (e.g. a scheduled job or operator action).
+        nil
+      else
+        raise ArgumentError, "Unknown delivery adapter: #{adapter}"
+      end
+    end
+
+    class AfterCommitCallback
+      def initialize(&block)
+        @callback = block
+      end
+
+      def committed!(*)
+        @callback.call
+      end
+
+      def before_committed!(*); end
+      def rolledback!(*); end
+
+      def trigger_transactional_callbacks?
+        true
+      end
+
+      def has_transactional_callbacks?
+        true
+      end
+
+      def self.register(connection, &block)
+        connection.current_transaction.add_record(new(&block))
+      end
+    end
+  end
+end

data/lib/event_engine/kafka_producer.rb

@@ -0,0 +1,16 @@
+require "json"
+
+module EventEngine
+  class KafkaProducer
+    def initialize(client:)
+      @client = client
+    end
+
+    def publish(topic, payload)
+      @client.produce(
+        JSON.generate(payload),
+        topic: topic
+      )
+    end
+  end
+end

data/lib/event_engine/locking_strategy.rb

@@ -0,0 +1,31 @@
+module EventEngine
+  module LockingStrategy
+    # Returns a locking strategy appropriate for the current database adapter.
+    #
+    # @return [NullStrategy, PostgresStrategy]
+    def self.for_current_adapter
+      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+      case adapter
+      when /postgres/
+        PostgresStrategy.new
+      else
+        NullStrategy.new
+      end
+    end
+
+    # No-op strategy for adapters that don't support SKIP LOCKED (e.g. SQLite).
+    class NullStrategy
+      def apply(scope)
+        scope
+      end
+    end
+
+    # Applies FOR UPDATE SKIP LOCKED for PostgreSQL to prevent duplicate
+    # deliveries when multiple publisher processes run concurrently.
+    class PostgresStrategy
+      def apply(scope)
+        scope.lock("FOR UPDATE SKIP LOCKED")
+      end
+    end
+  end
+end

data/lib/event_engine/outbox_publisher.rb

@@ -0,0 +1,89 @@
+module EventEngine
+  # Reads unpublished events from the outbox and dispatches each through the
+  # injected router. Handles retries and dead-lettering on failure.
+  #
+  # Fires +ActiveSupport::Notifications+ for published events, dead letters,
+  # and batch completion.
+  class OutboxPublisher
+    # @param router [#route] dispatches each drained event to its destination
+    # @param batch_size [Integer, nil] max events per batch (nil for unlimited)
+    # @param max_attempts [Integer, nil] max attempts before dead-lettering
+    def initialize(router:, batch_size: nil, max_attempts: nil, locking_strategy: nil)
+      @router = router
+      @batch_size = batch_size
+      @max_attempts = max_attempts
+      @locking_strategy = locking_strategy || LockingStrategy.for_current_adapter
+    end
+
+    # Fetches and publishes a batch of unpublished events.
+    #
+    # @return [void]
+    def call
+      OutboxEvent.transaction do
+        events = batch
+        events.each do |event|
+          publish_event(event)
+        end
+
+        ActiveSupport::Notifications.instrument("event_engine.publish_batch", {
+          count: events.size
+        })
+      end
+    end
+
+    private
+
+    def batch
+      scope = OutboxEvent.unpublished
+                         .active
+                         .ordered
+
+      scope = scope.retryable(@max_attempts) if @max_attempts
+      scope = scope.limit(@batch_size) if @batch_size
+      scope = @locking_strategy.apply(scope)
+
+      scope.to_a
+    end
+
+    def publish_event(event)
+      @router.route(event)
+      event.update!(published_at: Time.current)
+
+      ActiveSupport::Notifications.instrument("event_engine.event_published", {
+        event_name: event.event_name,
+        event_version: event.event_version,
+        event_id: event.id
+      })
+    rescue => e
+      handle_failure(event, e)
+    end
+
+    def handle_failure(event, error)
+      event.increment!(:attempts)
+      event.update!(
+        last_error_message: error.message.truncate(10_000),
+        last_error_class: error.class.name
+      )
+
+      return unless @max_attempts
+      return unless event.attempts >= @max_attempts
+
+      event.update!(dead_lettered_at: Time.current)
+
+      ActiveSupport::Notifications.instrument("event_engine.event_dead_lettered", {
+        event_name: event.event_name,
+        event_version: event.event_version,
+        event_id: event.id,
+        attempts: event.attempts,
+        error_message: error.message,
+        error_class: error.class.name
+      })
+
+      Rails.logger.error(
+        "[EventEngine] Dead-lettered event: event_id=#{event.id}, " \
+        "event_name=#{event.event_name}, attempts=#{event.attempts}, " \
+        "error=#{error.message}"
+      )
+    end
+  end
+end

data/lib/event_engine/outbox_router.rb

@@ -0,0 +1,58 @@
+module EventEngine
+  # Routes a drained outbox event to its destination based on +process_type+.
+  class OutboxRouter
+    # Raised when routing an event whose process_type has no supported destination.
+    class UnsupportedProcessTypeError < StandardError; end
+
+    # Raised when a :broker event is routed but no transport is configured.
+    class MissingTransportError < StandardError; end
+
+    # @param transport [#publish] the broker transport used for :broker events
+    def initialize(transport:)
+      @transport = transport
+    end
+
+    # Dispatches a drained event to its process_type's destination.
+    #
+    # @param event [OutboxEvent] the drained event
+    # @return [void]
+    def route(event)
+      case process_type_for(event)
+      when :durable then notify_subscribers(event)
+      when :broker then deliver_to_broker(event)
+      when :sourced then raise UnsupportedProcessTypeError, "process_type :sourced (event sourcing) is not supported"
+      else publish(event)
+      end
+    end
+
+    private
+
+    def process_type_for(event)
+      event.process_type&.to_sym
+    end
+
+    def notify_subscribers(record)
+      event = Event.from(record)
+      EventEngine::Subscribers::Registry.subscribers_for(event.event_name).each do |subscriber|
+        subscriber.new.handle(event)
+      end
+    end
+
+    def deliver_to_broker(event)
+      if transport_missing?
+        raise MissingTransportError,
+              "process_type :broker event '#{event.event_name}' requires a transport, but none is configured"
+      end
+
+      publish(event)
+    end
+
+    def transport_missing?
+      @transport.nil? || (@transport.respond_to?(:null?) && @transport.null?)
+    end
+
+    def publish(event)
+      @transport.publish(event)
+    end
+  end
+end

data/lib/event_engine/outbox_writer.rb

@@ -0,0 +1,7 @@
+module EventEngine
+  class OutboxWriter
+    def self.write(attrs)
+      OutboxEvent.create!(attrs)
+    end
+  end
+end

data/lib/event_engine/transports/in_memory_transport.rb

@@ -0,0 +1,27 @@
+module EventEngine
+  module Transports
+    # Stores published events in memory. Useful for development and testing.
+    #
+    # @example
+    #   transport = EventEngine::Transports::InMemoryTransport.new
+    #   transport.publish(event)
+    #   transport.events #=> [event]
+    class InMemoryTransport
+      # @return [Array<OutboxEvent>] all published events
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      # Stores the event in the in-memory array.
+      #
+      # @param event [OutboxEvent]
+      # @return [true]
+      def publish(event)
+        @events << event
+        true
+      end
+    end
+  end
+end

data/lib/event_engine/transports/kafka.rb

@@ -0,0 +1,45 @@
+module EventEngine
+  module Transports
+    # Publishes events to Kafka topics via an injected producer.
+    # Topics are named +events.{event_name}+ by default.
+    #
+    # @example
+    #   producer = EventEngine::KafkaProducer.new(client: kafka_client)
+    #   transport = EventEngine::Transports::Kafka.new(producer: producer)
+    class Kafka
+      # @param producer [KafkaProducer] a producer that responds to +#publish(topic, payload)+
+      def initialize(producer:)
+        @producer = producer
+      end
+
+      # Publishes the event to a Kafka topic.
+      #
+      # @param event [OutboxEvent]
+      # @return [Object] the producer's return value
+      def publish(event)
+        @producer.publish(topic_for(event), payload_for(event))
+      end
+
+      private
+
+      def topic_for(event)
+        "events.#{event.event_name}"
+      end
+
+      def payload_for(event)
+        {
+          event_name: event.event_name,
+          event_type: event.event_type,
+          event_version: event.event_version,
+          idempotency_key: event.idempotency_key,
+          payload: event.payload,
+          metadata: event.metadata,
+          occurred_at: event.occurred_at,
+          aggregate_type: event.aggregate_type,
+          aggregate_id: event.aggregate_id,
+          aggregate_version: event.aggregate_version
+        }
+      end
+    end
+  end
+end

data/lib/event_engine/transports/null_transport.rb

@@ -0,0 +1,27 @@
+module EventEngine
+  module Transports
+    # Default transport that discards events with a warning log.
+    # Used when no transport is explicitly configured.
+    class NullTransport
+      # Logs a warning that the event was discarded.
+      #
+      # @param event [OutboxEvent]
+      # @return [true]
+      def publish(event)
+        logger.warn("[EventEngine::NullTransport] Event '#{event.event_name}' discarded. No transport configured.")
+        true
+      end
+
+      # @return [Boolean] true, since this transport does not deliver anywhere
+      def null?
+        true
+      end
+
+      private
+
+      def logger
+        EventEngine::Delivery.configuration.logger
+      end
+    end
+  end
+end

data/lib/event_engine-delivery.rb

@@ -0,0 +1,20 @@
+require "event_engine"
+
+require "event_engine/delivery/configuration"
+require "event_engine/delivery"
+require "event_engine/transports/in_memory_transport"
+require "event_engine/transports/kafka"
+require "event_engine/transports/null_transport"
+require "event_engine/kafka_producer"
+require "event_engine/locking_strategy"
+require "event_engine/outbox_writer"
+require "event_engine/outbox_router"
+require "event_engine/outbox_publisher"
+require "event_engine/definition_transport_check"
+require "event_engine/cloud/serializer"
+require "event_engine/cloud/batch"
+require "event_engine/cloud/api_client"
+require "event_engine/cloud/subscribers"
+require "event_engine/cloud/reporter"
+require "event_engine/delivery/handler"
+require "event_engine/delivery/engine"

data/lib/generators/event_engine/install_generator.rb

@@ -0,0 +1,45 @@
+require "event_engine/subagents"
+
+module EventEngine
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install EventEngine (schema file, initializer, migrations)"
+
+      def install_migrations
+        rake "event_engine:install:migrations"
+      end
+
+      def create_event_schema
+        template "event_schema.rb", "db/event_schema.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/event_engine.rb"
+      end
+
+      def generate_subagents
+        say ""
+        say "Installing EventEngine Claude Code subagents...", :green
+        EventEngine::Subagents.names.each do |name|
+          create_file ".claude/agents/#{name}.md", EventEngine::Subagents.content_for(name), force: true
+        end
+      end
+
+      def print_next_steps
+        say <<~MSG
+
+          EventEngine installed.
+
+          Next steps:
+            1. Define events in app/event_definitions/
+            2. Run: bin/rails event_engine:schema:dump
+            3. Commit db/event_schema.rb
+            4. Configure transport in config/initializers/event_engine.rb
+
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/event_engine/templates/event_schema.rb

@@ -0,0 +1,10 @@
+# This file is authoritative in production.
+# It is generated from EventDefinitions via:
+#
+#   bin/rails event_engine:schema:dump
+#
+# Do not edit manually.
+
+EventEngine::EventSchema.define do |schema|
+  # schema.register(...)
+end

data/lib/generators/event_engine/templates/initializer.rb

@@ -0,0 +1,14 @@
+EventEngine.configure do |c|
+  # Delivery strategy (:inline or :active_job)
+  # c.delivery_adapter = :active_job
+
+  # Publisher behavior
+  # c.batch_size = 100
+  # c.max_attempts = 5
+
+  # Transport (required for publishing)
+  #
+  # kafka = Kafka.new(seed_brokers: ENV["KAFKA_BROKERS"])
+  # producer = EventEngine::KafkaProducer.new(client: kafka)
+  # c.transport = EventEngine::Transports::Kafka.new(producer: producer)
+end