# Worker — notas para agentes de IA
El segundo proceso de este proyecto (ADR-0018 de Puerto). Las unidades de trabajo de la API
escriben cada evento en la tabla `outbox`, en la misma transacción que la entidad; este proceso
**hace de relay** del outbox al transporte y **ejecuta los consumidores**. Es una raíz de
composición, como `presentacion/api`: aquí no vive lógica de negocio; un consumidor decodifica el
evento y llama a un caso de uso.
## Estructura
```
presentacion/worker/src/
├── main.rs # `ConfigWorker::from_env()` + `Worker::new(config).intentar_ejecutar(…)` (no cambia nunca)
├── generado.rs # `pub mod registro;`
├── generado/registro.rs # GENERADO: el relay y cada `[[consumidor]]`; no lo edites a mano
├── consumidores.rs # `pub mod <consumidor>;`, sin `mod.rs`
└── consumidores/
└── <consumidor>.rs # Tuyo: un `ManejadorEvento`, lo escribe una vez `puerto generar consumidor`
```
## Reglas críticas
- **Añade un consumidor con `puerto generar consumidor <nombre> --tras <tipo_evento>[,…]`**:
declara `[[consumidor]]` en `puerto.toml`, escribe el handler y sus tests, y regenera
`generado/registro.rs`. No cablees nunca uno a mano.
- **Los handlers deben ser idempotentes.** La entrega es al menos una vez: el mismo `evento.id`
puede llegar dos veces. Comprueba si el trabajo ya se hizo (por `evento.id`) antes de volver a
hacerlo.
- **Responde con honestidad**: `Ack` cuando termina; `Reintentar` para un fallo que puede pasar (se
vuelve a entregar con una espera creciente de 1 s → 300 s, `MAX_DELIVERIES` veces);
`ResultadoManejo::descartar(motivo, detalle)` para uno que no pasará nunca. Un payload que no se
decodifica es `MOTIVO_PAYLOAD_INVALIDO`. Nada se tira sin una fila en `descartados`
(`make eventos/descartados`).
- **Lo que necesita un consumidor se construye en su `construir(pool)`**, que `generado/registro.rs`
llama al arrancar: guárdalo en un campo del struct (`cableado::<contexto>::construir(pool)` da los
casos de uso de un contexto, como `Arc<dyn …>`; añade `cableado = { workspace = true }` a
`presentacion/worker/Cargo.toml` la primera vez). Sus tests construyen el struct con dobles
(`dobles::Mock<Caso>`), sin base de datos.
- **Decodifica el snapshot, nunca el modelo de dominio**:
`evento.decodificar::<SnapshotProducto>()`. El snapshot es el contrato público del evento.
{% if kafka -%}
## Transporte Kafka
- El relay publica cada evento en el topic de su agregado, `<KAFKA_TOPIC_PREFIX>.<agregado>`, con
el id del agregado como clave: los eventos de un agregado se consumen en el orden en que
ocurrieron.
- Un consumidor es el grupo de consumidores `<KAFKA_TOPIC_PREFIX>.<consumidor>`. Su offset se
confirma cuando el resultado está resuelto. Un `Reintentar` retiene los registros que vienen
detrás en su partición hasta que se confirma o se descarta; tras un reinicio, sus intentos vuelven
a empezar.
- `make docker-compose/up` arranca Redpanda junto a Postgres; los topics se crean cuando arranca el
worker. Los descartados se quedan en Postgres.
{% endif -%}
## Salud y apagado
Lo sirve el runtime de Puerto, `puerto-eventos`, en `WORKER_PORT` (8081).
- `GET /health`: vida; el proceso responde.
- `GET /health/ready`: disponibilidad; `503` hasta que el relay y cada consumidor terminan una
pasada sin fallos recientes (una base de datos caída se ve aquí).
- Con SIGTERM / Ctrl-C cada bucle termina el lote que está procesando, durante 8 s como mucho.
## Configuración
`WORKER_PORT` (8081), `RELAY_BATCH_SIZE` (100), `RELAY_POLL_INTERVAL_MS` (500),
`CONSUMER_POLL_INTERVAL_MS` (500), `MAX_DELIVERIES` (5), `RETRY_MAX_DELAY_MS` (sin valor: la espera
creciente de arriba), además de `DATABASE_URL`. Un valor presente pero inválido detiene el worker
en el arranque.{% if kafka %}
Kafka: `KAFKA_BROKERS` (`localhost:9092`) y `KAFKA_TOPIC_PREFIX` (el nombre del proyecto).{% endif %}