0018 · Domain events: unit of work, outbox, pluggable transport
Status: Accepted (2026-10-12). Spec: PLAN.md § Phase 13. Backlog: T-23 (T-29 is part of it).
Rollout: 13.1 (puerto-core events and ports), 13.2 (puerto-sqlx unit of work, outbox, db
transport store), 13.3 (generated events.rs / units of work) and 13.4 (puerto-events, the
worker/ binary, generate consumer) and 13.5 (puerto-kafka) done. The port signatures § 4
left open are settled in PLAN.md § 13.1; what the Kafka adapter settled (one record per batch,
consumer groups prefixed like topics) in § 13.5.
Context
Section titled “Context”A Puerto write use case calls repository.save(&entity) and returns. Nothing else learns that it
happened, so every reaction (send a mail, update a projection, notify another service) has to be
called from inside the use case. When one is added later, every existing write use case has to
change, which is the refactor Puerto exists to prevent. Mailer, jobs, webhooks and audit (the
pieces left after ADR-0017) all need the same thing: something to react to.
document-api (in nexe-document) runs this architecture in production. Every write goes through
a per-context Unit of Work that saves the aggregate and a DomainEvent row in an outbox table in
one Postgres transaction. An OutboxWorker relays unpublished rows in order to NATS JetStream,
stopping at the first failure. Consumers implement a MessageHandler that answers Ack, Nak or
DeadLetter. A pure function (delivery_policy::decide) applies a delivery cap and a growing
backoff, and nothing is retired without a dead_letters row (its ADR-0009). Three things in it do
not carry over to a generator:
- The consumer side is bound to JetStream. The relay talks to an
EventPublisherport, but the consume loop isasync_natscode. Puerto has to serve projects with no broker at all, and projects on Kafka. - The event payload is the domain model, serialised with serde. That puts serde on every entity and value object, and a change to the model silently changes a public contract.
- One global
DomainEventenum that every context’s events are lifted into. In a generated project it would be one more file regenerated from every entity, and it would couple them.
Decision
Section titled “Decision”1. Events require a database, and are opt-in
Section titled “1. Events require a database, and are opt-in”puerto new --db --events db|kafka writes [project] events = "db" (or "kafka"). --events
without --db is refused, and so is events without db in puerto validate. The outbox only
works inside a real transaction. An in-memory bus would look the same and guarantee nothing when
the process dies. A project without events is generated exactly as today.
2. Every write goes through a per-entity Unit of Work
Section titled “2. Every write goes through a per-entity Unit of Work”business/src/domain/<entity>/unit_of_work.rs holds two ports:
#[async_trait]pub trait ProductUnitOfWork: Send { async fn save(&mut self, entity: &Product) -> Result<(), RepositoryError>; async fn record(&mut self, event: ProductEvent) -> Result<(), RepositoryError>; async fn commit(self: Box<Self>) -> Result<(), RepositoryError>;}
#[async_trait]pub trait ProductUnitOfWorkFactory: Send + Sync { async fn begin(&self) -> Result<Box<dyn ProductUnitOfWork>, RepositoryError>;}- Dropping a UoW without calling
commitrolls it back, because a sqlxTransactiondoes. There is norollbackmethod: an early?is the rollback. - In an
eventsproject the repository port losessaveand only reads. A write that skips the outbox then fails to compile. That is the only check that holds when an agent writes the next use case. - The CRUD
create/update/deleteuse cases takeuow_factory, plusrepositorywhen they read first. Each records{Entity}Event::Created/Updated/Deletedbeforecommit. - One aggregate per transaction (the DDD consistency boundary). A use case that must write two aggregates atomically is hand-written against a hand-written UoW port. The generator does not model cross-aggregate transactions in v1.
3. The event payload is its own contract, not the model
Section titled “3. The event payload is its own contract, not the model”business/src/domain/<entity>/events.rs is fully generated from puerto.toml and regenerated
like bootstrap.rs:
{Entity}Snapshothas primitive fields,#[derive(Serialize, Deserialize)]and the same shape as the DTO (value objects unwrapped, the id aUuid). It is built from the entity.enum {Entity}Event { Created(Snapshot), Updated(Snapshot), Deleted(Snapshot), … }. Custom events declared in puerto.toml (events = ["product_published"]) add variants that carry the same snapshot.- It implements
puerto_core::DomainEvent:event_type()("product_created", past tense, snake_case),aggregate_type()("product"),aggregate_id(),schema_version()(1) andpayload()(JSON).
The domain models and value objects stay serde-free. business gains serde/serde_json, and
only events.rs uses them, in the same way DTOs isolate the HTTP contract (ADR-0012). There is no
global event enum. A consumer decodes the snapshot type of the event it subscribed to.
4. One envelope, two ports, the transport is an adapter
Section titled “4. One envelope, two ports, the transport is an adapter”puerto-core holds the transport-neutral parts (ADR-0017 § 2: ports in core):
EventEnvelope:id(the outbox row id, used as the dedup key downstream),event_type,aggregate_type,aggregate_id,schema_version,occurred_at,payload, plusheaders.headersis a string map, socorrelation_idtoday andtenant_idlater (T-25) need no new field. It is#[non_exhaustive], with a constructor.EventHandler:async fn handle(&self, event: &EventEnvelope) -> HandlerOutcome, withHandlerOutcome::{Ack, Retry, DeadLetter { reason, detail }}.- The delivery policy, as
document-apihas it: a puredecide(outcome, attempt, max)plus a growing backoff (1 s, 5 s, 15 s, 60 s, 300 s, max 5 deliveries). Every transport applies the same function, so its tests and mutants cover all of them. - The transport ports the worker drives: a publisher (the relay’s output) and a subscription (a consumer’s input). How they are shaped is settled in 13.1, with the code.
The adapters live in their own crates, so a project only pays for the one it uses:
| Transport | Crate | Relay “publishes” by | A consumer reads | Retry / dead letter |
|---|---|---|---|---|
db |
puerto-sqlx (events module) |
inserting one event_deliveries row per subscribed consumer, in the same transaction that marks the outbox row published |
claiming its rows with FOR UPDATE SKIP LOCKED |
attempts, next_attempt_at and status = 'dead' on the delivery row |
kafka |
puerto-kafka (rdkafka) |
producing to topic <project>.<aggregate_type>, keyed by aggregate_id, the envelope fields in headers |
a consumer group named after the consumer, offsets committed by hand after the outcome | retried in-process with the same backoff (this blocks the partition and keeps the order), then a dead_letters row in Postgres and a commit |
RabbitMQ and NATS can come later as one crate each, implementing the same two ports, without changing any generated code.
5. The relay and the consumers run in a second binary: worker/
Section titled “5. The relay and the consumers run in a second binary: worker/”An events project gets a worker crate next to presentation. Like the API, it is the
composition root of its own process, so it scales and is deployed separately:
worker/src/main.rs(written once):puerto_events::Worker::new(config).run(build_worker).worker/src/generated/registry.rs(AUTO-GENERATED from puerto.toml[[consumer]]entries): wires the relay, the transport and every consumer.worker/src/consumers/<name>.rs(written once bypuerto generate consumer, then the user’s own): anEventHandlerthat decodes the snapshot and calls a use case, with tests.- The relay holds a Postgres advisory lock, so with several worker replicas exactly one relays
and the outbox order is kept. Consumers scale with replicas. Per-aggregate order is guaranteed
by Kafka’s partition key; on the
dbtransport it is guaranteed only with one replica per consumer. - The worker serves
/healthonWORKER_PORT(puerto_web::health) and shuts down gracefully on SIGTERM (ADR-0008). A loop that stops turning shows up as not ready.
The loops (relay, consume, health, shutdown) are identical in every project, so they live in a
new runtime crate puerto-events (tokio, tracing), generic over the core ports.
6. Delivery is at-least-once, so handlers must be idempotent
Section titled “6. Delivery is at-least-once, so handlers must be idempotent”No transport here guarantees exactly-once. The envelope id is stable across redeliveries. The
generated consumer stub says so, and its test delivers the same envelope twice. A dropped message
always leaves a dead-letter record, and a failed dead-letter write means the message is delivered
again (document-api’s ADR-0009, adopted unchanged).
Alternatives rejected
Section titled “Alternatives rejected”- The repository writes the events (
save(&entity, &events)). It is simpler for one aggregate, but there is no place to grow into a multi-write transaction, and “every write emits an event” lives in each adapter instead of in the use case, where tests can see it. - A generic
UnitOfWorkinpuerto-core(save<T>(&mut self, entity: &T)). That is not object-safe behindArc<dyn …>. A generated per-entity port is plain, mockable and readable. - Serialising the domain model (
document-api’s choice). See Context. - Running the relay and consumers inside the API process. It is simpler to deploy, but the API and the workers can then only scale together, and a slow consumer competes with requests for the pool. A dev-only in-process flag can come later without changing this design.
- NATS/RabbitMQ first. Postgres serves the “no broker” case, and Kafka the most common broker. The ports are what keeps the others cheap.
Consequences
Section titled “Consequences”- An
eventsproject’s writes cannot skip the outbox without a compile error, and a reaction is added as a consumer without touching the use case that emits the event. - Mailer (Phase 14), jobs, webhooks and audit become consumers plus configuration rather than edits to write use cases.
businessdepends onserde/serde_json.puerto-coregrows ports and the delivery policy (async-trait,serde_json,uuid,chrono), so ADR-0017’s dependency table for it is extended.- New runtime crates
puerto-eventsandpuerto-kafka, released in lockstep (ADR-0017 § 4).rdkafkaneedscmakeand a C toolchain, which only Kafka projects and Puerto’s CI pay for. - On the
dbtransport, a consumer registered later receives only the events relayed after it is deployed. Backfilling from the outbox is future work.