Skip to content

Domain events

Sooner or later something has to happen because something else happened: send a welcome mail when a customer signs up, update a projection when an order is paid, tell another service. If each reaction is a call inside the use case, every new reaction means editing a use case that already works, and a failure halfway leaves the database and the world disagreeing.

Puerto solves it with the transactional outbox. Every write records an event in the same database transaction as the data, and a second process delivers it, at least once, to whoever subscribed. The use case does not know who listens.

puerto nuevo --nombre tienda --db --eventos db # or --eventos kafka

Events need --db: the guarantee comes from the transaction. ADR-0018 has the whole design.

API process
crear_producto
uow = uow_factory.begin()
uow.guardar(&producto) ┐
uow.registrar(Creado(snapshot)) ├ one transaction:
uow.commit() ┘ the productos row + the outbox row
worker process
relay reads the outbox in order and hands each event to the transport
db: one entregas_eventos row per subscribed consumer
kafka: topic tienda.producto, keyed by the product id
consumidores manejar(evento) → Ack | Reintentar | Descartar

If the process dies before commit, neither the product nor the event exists. If it dies after, both do, and the worker will deliver the event when it runs.

In an events project each entity gets a unit of work, and its repository loses guardar:

contextos/producto/dominio/src/repositorio.rs
pub trait RepositorioProducto: Send + Sync {
async fn buscar_todos(
&self,
pagina: PeticionPagina,
) -> Result<Pagina<Producto>, ErrorRepositorio>;
async fn buscar_por_id(&self, id: IdProducto) -> Result<Option<Producto>, ErrorRepositorio>;
// Sin `guardar`: las escrituras pasan por `UnitOfWorkFactoryProducto`, que registra sus
// eventos.
}

So a write that skips the outbox is not a bug you find in production. It does not compile:

error[E0599]: no method named `guardar` found for struct `Arc<(dyn RepositorioProducto + 'static)>` in the current scope

The generated create, update and delete use cases already write through it:

contextos/producto/aplicacion/src/crear_producto.rs (excerpt)
let mut uow = self.uow_factory.begin().await.inspect_err(fallido)?;
uow.guardar(&entidad).await.inspect_err(fallido)?;
uow.registrar(EventoProducto::Creado(SnapshotProducto::from_entidad(
&entidad,
)))
.await
.inspect_err(fallido)?;
uow.commit().await.inspect_err(fallido)?;

Dropping the unit of work without commit rolls everything back, so an early ? is the rollback. One aggregate per transaction: a use case that must write two atomically is written by hand against a port of your own.

contextos/producto/dominio/src/eventos.rs is regenerated from puerto.toml. It holds the event enum and a snapshot: the entity as the API shows it, primitives only, with value objects unwrapped.

contextos/producto/dominio/src/eventos.rs (excerpt)
pub const PRODUCTO_CREADO: &str = "producto_creado";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotProducto {
pub id: Uuid,
pub nombre: String,
pub precio: i64,
pub sku: String,
}
pub enum EventoProducto {
Creado(SnapshotProducto),
Actualizado(SnapshotProducto),
Borrado(SnapshotProducto),
}

The domain model never touches serde. Consumers decode the snapshot, so renaming a field changes a public contract, and it shows up in eventos.rs, where it can be reviewed.

puerto generar evento Producto producto_publicado
output
✓ Event 'producto_publicado' added to Producto: EventoProducto::Publicado
contextos/producto/dominio/src/eventos.rs regenerated.
Record it from a use case: uow.registrar(EventoProducto::Publicado(SnapshotProducto::from_entidad(&entidad)))

Event types are snake_case and past tense: something that already happened.

The event is recorded by a use case you write. puerto generar caso-de-uso Producto publicar_producto gives PublicarProductoImpl the repository, to read, and the unit of work factory, to write. The body reads the product, applies the rule, and writes it with its event:

contextos/producto/aplicacion/src/publicar_producto.rs (excerpt)
pub struct ParamsPublicarProducto {
pub id: IdProducto,
}
#[async_trait]
impl PublicarProducto for PublicarProductoImpl {
async fn ejecutar(&self, params: ParamsPublicarProducto) -> Result<Producto, ErrorProducto> {
tracing::info!(id = %params.id, "publicar_producto: inicio");
let mut entidad = self
.repositorio
.buscar_por_id(params.id)
.await?
.ok_or(ErrorProducto::NoEncontrado)?;
if entidad.precio <= 0 {
return Err(ErrorProducto::Validacion("precio_no_positivo".into()));
}
entidad.actualizado_en = chrono::Utc::now();
let mut uow = self.uow_factory.begin().await?;
uow.guardar(&entidad).await?;
uow.registrar(EventoProducto::Publicado(SnapshotProducto::from_entidad(
&entidad,
)))
.await?;
uow.commit().await?;
tracing::info!(id = %entidad.id, "publicar_producto: fin");
Ok(entidad)
}
}

Its tests need no database. UnitOfWorkFactoryGrabadora, next to the port in dominio_producto::unit_of_work::dobles, records what each unit of work saved and recorded, and whether it committed:

contextos/producto/aplicacion/src/publicar_producto.rs (excerpt)
#[cfg(test)]
mod tests {
use super::*;
use dominio_producto::pruebas::madres::MadreProducto;
use dominio_producto::repositorio::dobles::MockRepositorioProducto;
use dominio_producto::unit_of_work::dobles::UnitOfWorkFactoryGrabadora;
use puerto_nucleo::EventoDominio;
fn caso_de_uso_con(
producto: Producto,
uow_factory: &UnitOfWorkFactoryGrabadora,
) -> PublicarProductoImpl {
let mut repositorio_doble = MockRepositorioProducto::new();
repositorio_doble
.expect_buscar_por_id()
.returning(move |_| Ok(Some(producto.clone())));
PublicarProductoImpl {
repositorio: Arc::new(repositorio_doble),
uow_factory: Arc::new(uow_factory.clone()),
}
}
#[tokio::test]
async fn deberia_registrar_producto_publicado_cuando_el_producto_tiene_precio() {
// Preparar
let producto = MadreProducto::new().con_precio(1999).construir();
let uow_factory = UnitOfWorkFactoryGrabadora::new();
let caso_de_uso = caso_de_uso_con(producto.clone(), &uow_factory);
// Actuar
let resultado = caso_de_uso
.ejecutar(ParamsPublicarProducto { id: producto.id })
.await;
// Comprobar
assert!(resultado.is_ok());
let grabado = uow_factory.grabado();
assert!(grabado.confirmado);
assert_eq!(grabado.eventos.len(), 1);
assert_eq!(grabado.eventos[0].tipo_evento(), "producto_publicado");
}
}

For the error paths, UnitOfWorkFactoryGrabadora::fallando_en(FallarEn::Guardar, ErrorRepositorio::Duplicado) fails at the step you name; a rejected write leaves grabado().eventos empty and confirmado false.

  1. Generate one.

    puerto generar consumidor avisar_producto_nuevo --tras producto_creado,producto_publicado
    output
    ✓ Consumer 'avisar_producto_nuevo' added, on: producto_creado, producto_publicado
    presentacion/worker/src/consumidores/avisar_producto_nuevo.rs — yours: make it idempotent, it can see an event twice.
    presentacion/worker/src/generado/registro.rs regenerated. Run it with `make worker`.
  2. Write what it does. The stub is a ManejadorEvento that decodes the snapshot and acknowledges:

    presentacion/worker/src/consumidores/avisar_producto_nuevo.rs (excerpt)
    #[async_trait]
    impl ManejadorEvento for AvisarProductoNuevo {
    async fn manejar(&self, evento: &SobreEvento) -> ResultadoManejo {
    match evento.tipo_evento.as_str() {
    PRODUCTO_CREADO => match evento.decodificar::<SnapshotProducto>() {
    Ok(producto) => {
    tracing::info!(
    id_evento = %evento.id,
    id_producto = %producto.id,
    "avisar_producto_nuevo: producto_creado"
    );
    ResultadoManejo::Ack
    }
    Err(err) => ResultadoManejo::descartar(MOTIVO_PAYLOAD_INVALIDO, err.detalle),
    },
    // …
    _ => ResultadoManejo::Ack,
    }
    }
    }

    Answer ResultadoManejo::Ack when done, Reintentar for a failure that may pass (a timeout, a service that is down), and ResultadoManejo::descartar(…) for one that never will.

  3. Make it idempotent. Delivery is at least once: after a crash or a redeploy the same event can arrive twice, with the same evento.id. Check whether the work was already done, keyed on evento.id, before doing it again. The generated tests deliver the same envelope twice for that reason.

  4. Run the worker.

    make worker # relays the outbox, runs the consumers; health on :8081

presentacion/worker/src/generado/registro.rs wires the relay and one loop per consumer from the [[consumidor]] blocks in puerto.toml; it is regenerated, never edited. Event types are generated constants, so removing an event that a consumer listens to breaks the worker’s build instead of silently starving the consumer.

Every transport applies the same delivery policy, from puerto-nucleo:

Delivery that failed 1st 2nd 3rd 4th 5th
Then wait 1 s wait 5 s wait 15 s wait 60 s dead letter

A Reintentar on the last allowed delivery (MAX_DELIVERIES, 5 by default) retires the event with a row in descartados; raise the cap and the waits continue at 300 s. Nothing is dropped without a dead letter, and if writing it fails, the event is delivered again. A handler that panics counts as a Reintentar.

make eventos/descartados # the 20 most recent: consumer, event type, attempts, reason

No broker. The relay inserts one entregas_eventos row per subscribed consumer in the same transaction that marks the outbox row published, and each consumer claims its rows with FOR UPDATE SKIP LOCKED. Order per aggregate holds with one worker replica per consumer. A consumer added later receives the events relayed after it is deployed.

The relay takes a Postgres advisory lock, so with several replicas exactly one relays and the outbox order holds. Consumers scale with replicas. Each worker serves /health and /health/ready on WORKER_PORT: it is ready while every loop has finished a pass that did not fail within its interval, so a database that is down shows up as not ready.

Variable Default
WORKER_PORT 8081 health probes
RELAY_BATCH_SIZE 100 outbox rows per relay pass
RELAY_POLL_INTERVAL_MS 500 relay sleep when idle
CONSUMER_POLL_INTERVAL_MS 500 consumer sleep when idle
MAX_DELIVERIES 5 attempts before the dead letter
RETRY_MAX_DELAY_MS the policy’s caps the backoff (tests use 0)