event_engine-delivery 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11a0ab2cbc92fee65fae05651dc9908743196fae615427bb0bfbcfab5b2c97d0
-  data.tar.gz: 0104a00e5c2ca4434500ddd21690b08188cfe66fb6b298db34ace0276af8bd66
+  metadata.gz: 8855fa65e34aece1ee20813207c5092e0aae8cf133fabaed432e61fcb63cd75a
+  data.tar.gz: 369f3e3db3efd94a6879b15af7d4c22097814e015d3ee6317ab772cd242efb95
 SHA512:
-  metadata.gz: 9fba2892fbf51bf6b50ce2cfd5b7dc585b71053e02a2e06ee83c7facff638171b829d58cbf04538545e0a4656d64b36ddabb3a2fd3e8ac38d7375bc98995f215
-  data.tar.gz: 8066c109de6d3e75875ca276eff90e302a24f2c3eaf0695a9ef6cecf3c399414fc13899261d0d6568389e2398506ba7fb2c93d7cfa37caea0f955b45118fad8a
+  metadata.gz: b52d6548f25680b293362c4980e1244194b32f34fcbee376fc866cc3dc0e61962ad220d2b56465c712f35a47821a93fb358b184fea633532e88f677f30ff9bda
+  data.tar.gz: 85cf4fdf4762a80df6cdf465717757148c30e16cb49d3f02fb745fc268581bcf16eee62afb1432c4d70ef860bc2c765b16409b446da987473733262364f4cdae

data/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project are documented here, following
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-23
+
+### Changed
+- Delivery registers itself as the processor for the `durable` and `broker` process
+  types, in place of a handler registered for every event. An event reaches the
+  outbox only when the host's rules route it to `durable` or `broker`.
+- A `durable` event is delivered to its subscribers when no transport is configured.
+
+## [0.1.0] - 2026-09-21
+
 ### Added
 - Initial gem scaffold: mountable `EventEngine::Delivery` Rails engine depending on
   `event_engine`.

data/README.md

@@ -4,7 +4,7 @@ The **delivery layer** for [EventEngine](https://github.com/tylercschneider/even
 
 `event_engine` (the core) declares events with a schema-first DSL, compiles them to
 a committed schema, and **dispatches** built events to registered handlers. It does
-not deliver anything on its own. `event_engine-delivery` is the handler that takes an
+not deliver anything on its own. `event_engine-delivery` is the processor that takes an
 emitted event and **gets it delivered reliably**:
 
 - the durability **level ladder** (1 sync → 2 job → 3 outbox → 4 broker),
@@ -21,7 +21,7 @@ when you need durable, reliable delivery.
 > via copy-then-subtract. Most of its classes still live under the top-level
 > `EventEngine::` namespace (e.g. `EventEngine::Transports::Kafka`,
 > `EventEngine::OutboxEvent`, `EventEngine::OutboxPublisher`). The delivery-specific
-> entry points are `EventEngine::Delivery` (config, engine, handler). The examples
+> entry points are `EventEngine::Delivery` (config, engine, processor). The examples
 > below use the namespaces as they exist today.
 
 ---
@@ -87,54 +87,37 @@ end
 
 ## How it hooks into the core
 
-At Rails boot, the delivery engine registers a single handler with the core, for all
-levels:
+At Rails boot, the delivery engine registers itself with the core as the processor
+for the `durable` and `broker` process types:
 
 ```ruby
 # lib/event_engine/delivery/engine.rb
-initializer "event_engine.delivery.register_handler" do
+initializer "event_engine.delivery.register_processor" do
   config.after_initialize do
-    EventEngine.register_handler(Handler.new, levels: :all)
+    processor = Processor.new
+    Processor::PROCESS_TYPES.each { |process_type| EventEngine.register_processor(process_type, processor) }
     Engine.send(:start_cloud_reporter!)
   end
 end
 ```
 
-From then on, every `EventEngine.<event>` call dispatches into
-`EventEngine::Delivery::Handler#call`, which routes by `event_level`.
+The host's rules file decides which events take those roads, for example
+`quote_signed: durable`. `inline` and `background` events are processed by
+`event_engine-subscribers` and never reach this gem.
 
 ---
 
-## Level routing
+## Process type routing
 
-`EventEngine::Delivery::Handler` is the brain. It maps each event's level to a
-delivery strategy:
+`EventEngine::Delivery::Processor#call` writes the event to the outbox, fires
+`event_engine.event_emitted`, and triggers publishing per the configured
+[delivery adapter](#delivery-adapters). When the outbox drains,
+`EventEngine::OutboxRouter` routes by process type:
 
-```ruby
-def call(event)
-  case event.event_level
-  when 1 then dispatch_synchronously(event)  # invoke subscribers now, in-process
-  when 2 then dispatch_in_background(event)  # enqueue DispatchSubscribersJob
-  else        write_and_publish(event)       # 3, 4, and nil → outbox + publish
-  end
-end
-```
-
-- **Level 1** — calls every `EventEngine::Subscriber` registered for the event,
-  synchronously, in the caller's stack.
-- **Level 2** — enqueues `DispatchSubscribersJob`, which invokes the same subscribers
-  in a background job.
-- **Levels 3+ (and `nil`)** — writes an `OutboxEvent` row, fires
-  `event_engine.event_emitted`, and triggers publishing per the configured
-  [delivery adapter](#delivery-adapters). When the outbox drains,
-  `EventEngine::OutboxRouter` differentiates:
-  - **level 3** → invoke in-app subscribers,
-  - **level 4** → publish to the configured **transport** (raises
-    `MissingTransportError` if none/Null),
-  - **level 5** → raises `UnsupportedLevelError` (reserved, unsupported).
-
-> **`nil` levels fall into the outbox path** (the `else` branch). If you didn't set
-> `event_level` on a definition, its events behave like level 3+. Set it explicitly.
+- **durable** → invokes the event's in-app subscribers. No transport is needed.
+- **broker** → publishes to the configured **transport**, raising
+  `MissingTransportError` if none is configured.
+- **sourced** → raises `UnsupportedProcessTypeError`.
 
 ---
 
@@ -470,9 +453,9 @@ app.
 
 ## Customization recipes
 
-**Run delivery and a durable log together.** Add `event_engine-store`. Both register
-handlers at `levels: :all`; every event is delivered *and* recorded. Order is the
-registration order at boot.
+**Run delivery and a durable log together.** Add `event_engine-store`. Delivery
+processes `durable` and `broker` events, and the store's handlers record every
+event whatever its process type.
 
 **Pause delivery during maintenance.** Set `delivery_adapter = :manual`; events keep
 landing in the outbox safely and you drain them with `OutboxPublisher` when ready.

data/Rakefile

@@ -7,3 +7,5 @@ require "bundler/gem_tasks"
 
 task test: "app:test"
 task default: :test
+
+require "the_local/rake"

data/lib/event_engine/delivery/engine.rb

@@ -3,9 +3,10 @@ module EventEngine
     class Engine < ::Rails::Engine
       engine_name "event_engine_delivery"
 
-      initializer "event_engine.delivery.register_handler" do
+      initializer "event_engine.delivery.register_processor" do
         config.after_initialize do
-          EventEngine.register_handler(Handler.new, process_types: :all)
+          processor = Processor.new
+          Processor::PROCESS_TYPES.each { |process_type| EventEngine.register_processor(process_type, processor) }
           Engine.send(:start_cloud_reporter!)
         end
       end

data/lib/event_engine/delivery/processor.rb

@@ -0,0 +1,30 @@
+module EventEngine
+  module Delivery
+    class Processor
+      PROCESS_TYPES = %i[durable broker].freeze
+
+      def call(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
+          OutboxPublisher.new(
+            router: OutboxRouter.new(transport: Delivery.configuration.transport),
+            batch_size: Delivery.configuration.batch_size
+          ).call
+        end
+
+        outbox_event
+      end
+    end
+  end
+end

data/lib/event_engine/delivery/version.rb

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

data/lib/event_engine-delivery.rb

@@ -16,5 +16,5 @@ 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/processor"
 require "event_engine/delivery/engine"

data/the_local/agents/event_engine-delivery-develop.md

@@ -0,0 +1,156 @@
+---
+name: event_engine-delivery-develop
+description: Use PROACTIVELY for testing durable and broker events with the in-memory transport, scheduling outbox publishing with EventEngine::PublishOutboxEventsJob, scheduling outbox cleanup with EventEngine::OutboxCleanupJob or the cleanup task, and listing or retrying dead-lettered events — MUST BE USED instead of hand-writing test transports, outbox polling jobs, outbox delete queries, or console code that resets failed events.
+tools: Read, Write, Edit, Grep
+scope: delivering durable and broker events — writing them to the transactional outbox, publishing them through a transport, and retrying or dead-lettering the ones that fail
+---
+
+This local writes the host code that tests, schedules and repairs outbox
+delivery. It follows these steps exactly, and where a step names a decision it
+asks the developer and does not pick.
+
+## What event_engine-delivery is
+
+The delivery layer for EventEngine. Every `durable` and `broker` event is written
+to an outbox table, and a publish run later reads unpublished rows in order,
+hands `durable` events to their in-app subscribers and sends `broker` events
+through the configured transport. A row that fails to publish counts an attempt,
+and a publish run with an attempt limit dead letters it once the limit is
+reached. Use this local once the gem is installed and the work is testing that
+events leave the app, running the publish or cleanup work on a schedule, or
+dealing with events that failed.
+
+## Interface
+
+- `EventEngine::Transports::InMemoryTransport` — a transport for tests and
+  development. `InMemoryTransport.new` builds it, `publish(event)` stores the
+  event, and `events` returns every stored outbox record in the order published.
+- `EventEngine::PublishOutboxEventsJob` — an Active Job on the `default` queue
+  that takes no arguments and runs one publish run of up to `batch_size`
+  unpublished, non-dead-lettered rows with fewer than `max_attempts` attempts. It
+  dead letters a row whose attempts reach `max_attempts`, and it raises when the
+  configured transport is `nil`.
+- `EventEngine::OutboxCleanupJob` — an Active Job on the `default` queue that
+  takes no arguments and deletes published, non-dead-lettered rows published
+  more than `retention_period` ago. It does nothing when `retention_period` is
+  unset.
+- `bin/rails event_engine:outbox:cleanup` — the same deletion as
+  `OutboxCleanupJob`, run once from the shell, printing how many rows it deleted
+  or why it deleted none.
+- `bin/rails event_engine:dead_letters:list` — prints every dead-lettered row,
+  oldest first, with its id, event name, attempts and the time it was dead
+  lettered.
+- `bin/rails event_engine:dead_letters:retry[EVENT_ID]` — resets one
+  dead-lettered row to zero attempts with no error and no dead-letter mark, so
+  the next publish run picks it up again.
+- `bin/rails event_engine:dead_letters:retry:all` — the same reset for every
+  dead-lettered row.
+
+## How to use it
+
+### Test that events are delivered
+
+1. Confirm the event under test is `durable` or `broker`. Other process types
+   never reach the outbox. Defining the event and emitting it belong to the
+   event_engine-develop local.
+2. In the test setup, keep the current transport and swap in the in-memory one:
+   ```ruby
+   @previous_transport = EventEngine::Delivery.configuration.transport
+   @transport = EventEngine::Transports::InMemoryTransport.new
+   EventEngine::Delivery.configuration.transport = @transport
+   ```
+   In teardown, put it back, since the configuration is shared by the whole
+   process:
+   ```ruby
+   EventEngine::Delivery.configuration.transport = @previous_transport
+   ```
+3. Emit the event, then run a publish run directly so the assertion does not
+   depend on the delivery adapter or on the test's transaction committing:
+   ```ruby
+   EventEngine::PublishOutboxEventsJob.perform_now
+   ```
+4. For a `broker` event, assert on what reached the transport:
+   ```ruby
+   assert_equal ["order_placed"], @transport.events.map(&:event_name)
+   ```
+   Each entry answers `event_name`, `event_version`, `payload`, `metadata`,
+   `idempotency_key` and `occurred_at`.
+5. For a `durable` event, assert on the subscriber's effect instead. `durable`
+   events go to in-app subscribers and never reach the transport, so
+   `@transport.events` stays empty for them.
+
+### Schedule outbox publishing
+
+1. Read `delivery_adapter` from the host's delivery initializer.
+   - `:manual` — nothing publishes on its own, so `PublishOutboxEventsJob` must
+     be scheduled.
+   - `:active_job` — each emit already enqueues the job. A schedule is still
+     needed for rows that failed, because nothing else re-runs them until the
+     next emit.
+   - `:inline` — each emit publishes right after its transaction commits, and
+     that publish applies no attempt limit, so nothing is ever dead lettered by
+     it. A schedule is needed only if the developer wants failed rows dead
+     lettered after `max_attempts`.
+   Ask the developer whether to add a schedule, and how often it runs.
+2. Ask the developer which scheduler the host uses, for example Solid Queue
+   recurring tasks, sidekiq-cron, GoodJob cron or system cron. Look for an
+   existing one in the host before asking. This gem ships no scheduler.
+3. Add one recurring entry that enqueues `EventEngine::PublishOutboxEventsJob`
+   with no arguments, in that scheduler's own format. For system cron, call it
+   through `bin/rails runner "EventEngine::PublishOutboxEventsJob.perform_now"`.
+4. Confirm the configured transport is not `nil`. The job raises when it is.
+
+### Schedule outbox cleanup
+
+1. Read `retention_period` from the host's delivery initializer. If it is unset, cleanup deletes nothing. Setting it belongs to the
+   event_engine-delivery-install local, so ask the developer whether to set one
+   there first, and stop here if they decline.
+2. Ask the developer how often cleanup runs.
+3. Add one recurring entry to the host's scheduler that enqueues
+   `EventEngine::OutboxCleanupJob` with no arguments. For system cron, run
+   `bin/rails event_engine:outbox:cleanup` instead, which also prints what it
+   deleted.
+4. To clean up once by hand, run:
+   ```sh
+   bin/rails event_engine:outbox:cleanup
+   ```
+
+### Handle dead-lettered events
+
+1. List them:
+   ```sh
+   bin/rails event_engine:dead_letters:list
+   ```
+2. Report the list to the developer and ask whether the cause of the failure is
+   fixed. A retried row that fails again is dead lettered again after another
+   `max_attempts` attempts.
+3. Ask the developer whether to retry one row or all of them.
+   - One row, quoting the brackets so the shell does not expand them:
+     ```sh
+     bin/rails "event_engine:dead_letters:retry[42]"
+     ```
+   - All rows:
+     ```sh
+     bin/rails event_engine:dead_letters:retry:all
+     ```
+4. Retrying does not publish. The row is sent by the next publish run, which is
+   the next scheduled `PublishOutboxEventsJob` or the next emitted event under
+   the `:inline` or `:active_job` adapter. To send it at once, run:
+   ```sh
+   bin/rails runner "EventEngine::PublishOutboxEventsJob.perform_now"
+   ```
+
+## Conventions
+
+- Never write to the outbox table, delete from it, or reset its rows by hand.
+  Publishing goes through `PublishOutboxEventsJob`, deletion through
+  `OutboxCleanupJob` or the cleanup task, and resets through the retry tasks.
+- Cleanup never deletes an unpublished row or a dead-lettered row.
+- A dead-lettered row stays in the outbox until it is retried.
+- Never write a test transport of your own. Use `InMemoryTransport`, and restore
+  the previous transport after each test.
+- Out of scope: adding the gem, the outbox migrations, every delivery
+  initializer setting including `retention_period`, and the Kafka transport and
+  producer. Those belong to the
+  event_engine-delivery-install local. Defining events, choosing their process
+  type and emitting them belong to EventEngine itself.

data/the_local/agents/event_engine-delivery-info.md

@@ -0,0 +1,69 @@
+---
+name: event_engine-delivery-info
+description: Use to learn what event_engine-delivery offers — the transactional outbox, durable and broker events, transports, retries, dead letters, and outbox retention.
+tools: Read
+scope: delivering durable and broker events — writing them to the transactional outbox, publishing them through a transport, and retrying or dead-lettering the ones that fail
+---
+
+This local explains event_engine-delivery and makes no changes.
+
+## What event_engine-delivery is
+
+event_engine-delivery is the delivery layer for EventEngine. EventEngine defines
+and emits events, and each event carries a process type. This gem handles the
+two process types that must not be lost: `durable` and `broker`. It writes each
+such event to an outbox table in the same database transaction as the change
+that caused it. It then publishes the event once that transaction commits.
+
+Reach for it when an event has to survive a crash or a rolled-back request, or
+when an event has to leave the app through a message broker. Events with the
+`inline` or `background` process type are not handled here. event_engine-subscribers
+runs those.
+
+## Interface
+
+This local declares no commands. The other two locals own the whole surface:
+
+- **event_engine-delivery-install** owns adding the gem to an app. That covers
+  the outbox migrations, the initializer settings, and connecting a real broker
+  transport.
+- **event_engine-delivery-develop** owns working with the gem once it is
+  installed. That covers the test transport, the jobs that publish and clean up
+  the outbox, and the tasks that list and retry dead-lettered events.
+
+## How to use it
+
+- The gem is not in the app yet, or the app needs a broker connection: use the
+  install local.
+- The gem is installed and you are writing tests, scheduling outbox work, or
+  handling failed events: use the develop local.
+- You are defining an event or choosing its process type: that belongs to
+  EventEngine itself, not this gem.
+
+## Conventions
+
+- **Outbox** — the table every durable and broker event is written to before it
+  is published. A row stays there after publishing until retention removes it.
+- **`durable`** — an event written to the outbox and then handed to its
+  subscribers inside the app. It needs no broker.
+- **`broker`** — an event written to the outbox and then published through the
+  transport. Publishing raises an error when no real transport is configured.
+- **`sourced`** — a process type for event sourcing. This gem does not support
+  it and raises an error when one is routed.
+- **Transport** — the object that sends a broker event out of the app. Any
+  object that responds to `publish(event)` qualifies. The default transport
+  publishes nothing. A Kafka transport ships with the gem and names topics
+  `events.<event_name>`.
+- **Delivery adapter** — when the outbox gets published. `inline` publishes
+  right after the transaction commits. `active_job` publishes from a background
+  job and requires a real transport. `manual` publishes only when something
+  calls for it explicitly.
+- **Batch size** — how many outbox rows one publish run reads. The default is
+  100.
+- **Max attempts** — how many failed publishes an event gets before it is dead
+  lettered. The default is 5. It applies when the outbox is published by the
+  background job. An `inline` publish applies no attempt limit.
+- **Dead letter** — an event that ran out of attempts. It stays in the outbox,
+  marked dead lettered, until someone retries it.
+- **Retention period** — how long a published event stays in the outbox. It is
+  unset by default, and while it is unset nothing is cleaned up.

data/the_local/agents/event_engine-delivery-install.md

@@ -0,0 +1,112 @@
+---
+name: event_engine-delivery-install
+description: Use to hook event_engine-delivery into a project — copying the outbox migrations, writing the EventEngine::Delivery.configure initializer, and connecting Kafka through EventEngine::Transports::Kafka and EventEngine::KafkaProducer.
+tools: Bash, Read, Edit
+scope: delivering durable and broker events — writing them to the transactional outbox, publishing them through a transport, and retrying or dead-lettering the ones that fail
+---
+
+This local follows these steps exactly and invents none. Where a step names a
+decision, it asks the developer and does not pick.
+
+## What event_engine-delivery is
+
+The delivery layer for EventEngine: it writes `durable` and `broker` events to an
+outbox table and publishes them after the transaction commits. Hook it in when an
+app emits events that must not be lost or must leave the app through a broker.
+
+## Interface
+
+- `bin/rails event_engine_delivery:install:migrations` — copies the outbox table
+  migrations into the host's `db/migrate/`.
+- `EventEngine::Delivery.configure` — the block in the host initializer that sets
+  the delivery adapter, transport, batch size, max attempts, retention period,
+  logger and cloud reporting.
+- `EventEngine::Transports::Kafka` — the transport that publishes each broker
+  event to the Kafka topic `events.<event_name>`. Built with
+  `EventEngine::Transports::Kafka.new(producer: producer)`.
+- `EventEngine::KafkaProducer` — wraps a Kafka client for that transport. Built
+  with `EventEngine::KafkaProducer.new(client: client)`. It calls
+  `client.produce(json_string, topic: topic)`, so the client must answer that
+  call.
+
+## How to use it
+
+1. Confirm EventEngine itself is installed in the host. If it is not, stop and
+   use the event_engine-install local first.
+2. Add the gem to the host `Gemfile` and install it:
+   ```ruby
+   gem "event_engine-delivery"
+   ```
+   ```sh
+   bundle install
+   ```
+   The gem brings in `event_engine-subscribers` and holds `json` below version 3.
+   If the host's lockfile already pins `json` 3 or later, report the conflict to
+   the developer and stop.
+3. Copy and run the outbox migrations:
+   ```sh
+   bin/rails event_engine_delivery:install:migrations
+   bin/rails db:migrate
+   ```
+   This creates the `event_engine_outbox_events` table and updates
+   `db/schema.rb`.
+4. Ask the developer which delivery adapter to use:
+   - `:inline` (the default) — publishes right after the transaction commits, in
+     the same process.
+   - `:active_job` — publishes from a background job, which needs a working
+     Active Job backend in the host and a real transport.
+   - `:manual` — publishes only when something calls for it explicitly.
+5. Ask the developer whether the app emits `broker` events. If it does, it needs
+   a real transport, and Kafka is the one this gem ships. Ask which Kafka client
+   the host uses, and confirm that client answers
+   `produce(json_string, topic: topic)`. This gem does not add a Kafka client
+   gem, so the developer adds and configures the client. If the client does not
+   answer that call, report it and stop rather than writing an adapter.
+6. Create `config/initializers/event_engine_delivery.rb`:
+   ```ruby
+   EventEngine::Delivery.configure do |config|
+     config.delivery_adapter = :inline
+
+     # Only when the app emits broker events:
+     # producer = EventEngine::KafkaProducer.new(client: kafka_client)
+     # config.transport = EventEngine::Transports::Kafka.new(producer: producer)
+   end
+   ```
+   Set `delivery_adapter` to the developer's answer from step 4. Uncomment the
+   transport lines when step 5 found broker events, with `kafka_client` replaced
+   by the host's client.
+7. Ask the developer for each remaining setting, and write only the ones that
+   differ from the default:
+   - `config.batch_size` — outbox rows read per publish run. Default `100`.
+   - `config.max_attempts` — failed publishes before an event is dead lettered.
+     Default `5`.
+   - `config.retention_period` — how long published events stay in the outbox,
+     for example `30.days`. Default unset, and while unset nothing is removed.
+   - `config.logger` — default `Rails.logger`.
+   - `config.cloud_api_key`, `config.cloud_environment`, `config.cloud_app_name`
+     — setting an API key turns on reporting to EventEngine Cloud at boot. Ask
+     before setting it, and read the key from credentials or the environment,
+     never a literal.
+8. Boot the app and check the configuration:
+   ```sh
+   bin/rails runner "EventEngine::Delivery.configuration.validate!"
+   ```
+   It raises when the adapter is not one of the three, when `:active_job` has no
+   real transport, when the transport does not answer `publish`, or when
+   `batch_size` or `max_attempts` is not a positive integer. The app does not run
+   this check on its own at boot.
+
+## Conventions
+
+- The gem registers itself with EventEngine as the processor for `durable` and
+  `broker` when the app boots. No routes, mount or processor registration goes in
+  the host, and only events the host's rules route to `durable` or `broker` reach
+  the outbox.
+- Without a real transport, a `broker` event is still written to the outbox, and
+  publishing it raises. `durable` events need no transport.
+- When the gem is upgraded, run `bin/rails event_engine_delivery:install:migrations`
+  and `bin/rails db:migrate` again to pick up new outbox migrations.
+- Out of scope: the test transport, scheduling outbox publishing or cleanup, and
+  listing or retrying dead-lettered events. Those belong to the
+  event_engine-delivery-develop local. Defining events and choosing their process
+  type belong to EventEngine itself.

data/the_local/interface.yml

@@ -0,0 +1,28 @@
+scope: delivering durable and broker events — writing them to the transactional outbox, publishing them through a transport, and retrying or dead-lettering the ones that fail
+
+install:
+  - bin/rails event_engine_delivery:install:migrations
+  - EventEngine::Delivery.configure
+  - EventEngine::Transports::Kafka
+  - EventEngine::KafkaProducer
+
+develop:
+  - EventEngine::Transports::InMemoryTransport
+  - EventEngine::PublishOutboxEventsJob
+  - EventEngine::OutboxCleanupJob
+  - bin/rails event_engine:outbox:cleanup
+  - bin/rails event_engine:dead_letters:list
+  - bin/rails event_engine:dead_letters:retry
+  - bin/rails event_engine:dead_letters:retry:all
+
+sources:
+  - lib/event_engine/delivery.rb
+  - lib/event_engine/delivery/configuration.rb
+  - lib/event_engine/delivery/handler.rb
+  - lib/event_engine/transports/kafka.rb
+  - lib/event_engine/kafka_producer.rb
+  - lib/event_engine/transports/in_memory_transport.rb
+  - app/jobs/event_engine/publish_outbox_events_job.rb
+  - app/jobs/event_engine/outbox_cleanup_job.rb
+  - lib/tasks/event_engine_outbox.rake
+  - lib/tasks/event_engine_dead_letters.rake

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_engine-delivery
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
@@ -135,7 +135,7 @@ files:
 - lib/event_engine/delivery.rb
 - lib/event_engine/delivery/configuration.rb
 - lib/event_engine/delivery/engine.rb
-- lib/event_engine/delivery/handler.rb
+- lib/event_engine/delivery/processor.rb
 - lib/event_engine/delivery/version.rb
 - lib/event_engine/kafka_producer.rb
 - lib/event_engine/locking_strategy.rb
@@ -153,6 +153,10 @@ files:
 - lib/tasks/event_engine_schema.rake
 - lib/tasks/event_engine_schema_check.rake
 - lib/tasks/event_engine_tasks.rake
+- the_local/agents/event_engine-delivery-develop.md
+- the_local/agents/event_engine-delivery-info.md
+- the_local/agents/event_engine-delivery-install.md
+- the_local/interface.yml
 homepage: https://github.com/tylercschneider/event_engine-delivery
 licenses:
 - MIT

data/lib/event_engine/delivery/handler.rb

@@ -1,52 +0,0 @@
-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