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 kafkaEvents need --db: the guarantee comes from the transaction.
ADR-0018 has the whole design.
How it flows
Section titled “How it flows”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 | DescartarIf 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.
Writes go through the unit of work
Section titled “Writes go through the unit of work”In an events project each entity gets a unit of work, and its repository loses guardar:
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 scopeThe generated create, update and delete use cases already write through it:
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.
The event is a contract, not the model
Section titled “The event is a contract, not the model”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.
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.
Your own events
Section titled “Your own events”puerto generar evento Producto producto_publicado✓ 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:
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:
#[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.
Consumers
Section titled “Consumers”-
Generate one.
puerto generar consumidor avisar_producto_nuevo --tras producto_creado,producto_publicadooutput ✓ Consumer 'avisar_producto_nuevo' added, on: producto_creado, producto_publicadopresentacion/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`. -
Write what it does. The stub is a
ManejadorEventothat 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::Ackwhen done,Reintentarfor a failure that may pass (a timeout, a service that is down), andResultadoManejo::descartar(…)for one that never will. -
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 onevento.id, before doing it again. The generated tests deliver the same envelope twice for that reason. -
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.
Retries and dead letters
Section titled “Retries and dead letters”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, reasonTransports
Section titled “Transports”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 produces to the topic <project>.<aggregate> (tienda.producto), keyed by the
aggregate id, with the envelope fields as headers. Each consumer is a consumer group named
<project>.<consumer>, and offsets are committed after the outcome. A retry is held in process,
which stops the subscription and keeps the order. The outbox and the dead letters stay in
Postgres.
The transport is the puerto-kafka crate. ConfigKafka::from_env reads KAFKA_BROKERS and
KAFKA_TOPIC_PREFIX (the project name by default), and the worker calls
asegurar_topics(&["producto"]) at startup, so the topics exist before the relay publishes.
docker-compose.yml runs Redpanda for development, and building needs cmake and the libcurl
headers.
Running more than one worker
Section titled “Running more than one worker”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) |