~/studies/work 2026-11-13 · published 2026-11-21

Durable execution, explicada a través de nagare

Qué hacen realmente un journal, el replay determinista, un inbox y un outbox en un engine de workflows durable, y por qué at-least-once más fronteras idempotentes es lo que exactly-once significa en la práctica.

El problema

Un workflow que llama a tres servicios puede caerse entre la segunda y la tercera llamada. El trabajo de un engine durable es hacer que esa caída sea aburrida: la ejecución se reanuda donde estaba, y las llamadas que ya ocurrieron no vuelven a ocurrir.

nagare es el engine de workflows durable en el que trabajo. Un workflow es un grafo JSON con nueve tipos de nodo. Cada efecto secundario es una llamada a una operación sobre una conexión. Este post explica los cuatro mecanismos que hacen aburrida una caída, usando como fuente los propios ADRs del engine: el journal, el replay determinista, el inbox y el outbox. Aquí no hay benchmarks. Los números están en otro post, What exactly-once over a journal costs.

El journal

Un journal es una lista append-only de entradas por ejecución. Cada cosa durable que hace el intérprete toma el siguiente número de secuencia: un paso, una lectura del reloj, un id generado, un sleep, un wait, un mensaje recibido, el inicio de una ejecución hija.

Un paso es un comando con nombre. Su key se construye con el nodo, cuántas veces se entró al nodo y el intento, por ejemplo `<node>#<visit>@<attempt>`. La misma cadena, con el id de la ejecución como prefijo, es la idempotency key que se entrega a quien responde la llamada.

Keys de paso que usa el intérprete (addendum de ADR-0003)text
load                       definition load
create:<node>              child run creation
<node>#<visit>@<attempt>   call attempt
<key>/status<n>            status poll
emit:<seq>                 event flush
<key>~r<n>                 infrastructure retry, n above 1

Las keys son parte del contrato de replay. Cambiar una es un cambio incompatible del intérprete, y el ADR dice que sale como una build nueva que drena la anterior en lugar de parchear ejecuciones aparcadas.

Replay determinista

Tras una caída el engine no restaura un snapshot de memoria. Ejecuta el intérprete otra vez desde el principio. Cada llamada durable consulta primero el journal: si existe una entrada en esa posición, se devuelve el resultado registrado y no se ejecuta nada. Solo la primera posición sin entrada se ejecuta de verdad.

Eso solo funciona si el intérprete hace la misma secuencia de llamadas cada vez. Por eso el intérprete es determinista por regla. Dentro del paquete del intérprete no hay `time.Now`, ni `math/rand`, ni goroutines, ni `select`, ni iteración de maps sin ordenar, ni I/O, ni globales. El tiempo y los ids vienen del contexto durable, así que se registran una vez y se reproducen.

El journal lo verifica en runtime. Si el replay pide una llamada cuyo kind o key difiere de la entrada registrada, la ejecución falla con un error de no determinismo en lugar de continuar sobre una historia equivocada.

Los reintentos siguen la misma regla. Cada intento es su propio paso, el backoff es un sleep durable y el retry nativo del engine está desactivado. Un solo intérprete es dueño de la semántica de reintentos, así que todos los engines detrás del port se comportan igual.

Inbox y outbox

El journal cubre lo que ocurre dentro de una ejecución. Los bordes necesitan el mismo tratamiento. Un callback que llega mientras el engine está caído no debe perderse, y un evento que una ejecución emite no debe perderse ni publicarse dos veces.

Para lo entrante, el ADR-0012 dice: persistir y luego confirmar. Cada webhook, callback, señal y evento se inserta en una tabla y se responde al instante. La key es tenant, source y message id, única entre réplicas. Un mensaje nuevo responde 202 y un duplicado responde 200. El handler nunca llama al engine. Un dispatcher entrega después, en orden por ordering key, at least once. Antes de este cambio, una caída del engine devolvía 5xx a un llamador que nunca reenviaría.

Lo saliente es el espejo. Añadir eventos de una ejecución escribe los eventos, la proyección del read-model y las filas del outbox en una sola transacción, protegida por el último número de secuencia. Un relay publica las filas a los sinks después, también at least once. El id del evento se construye con tenant, stream y secuencia, así que un consumidor puede descartar repetidos. Cuando se reutiliza el id de una ejecución tras un borrado, se añade un epoch al id para que la historia nueva no colisione con la antigua (ADR-0015).

Qué significa exactly-once aquí

El README es directo: el engine no es exactly-once. La entrega es at least once en todas partes, y cada frontera es idempotente en su lugar. Un paso puede ejecutarse dos veces si el proceso muere después de la llamada y antes del registro. Bajo el journal remoto ese caso es explícito: el paso se ejecuta de nuevo cuando expira el lease.

  • Los duplicados entrantes los absorbe la message key única y el propio dedupe del inbox del engine para las señales.
  • Un paso repetido lleva la misma idempotency key, así que un callee que la respete aplica el efecto una vez.
  • Un flush de eventos reintentado nunca duplica eventos, porque el append es idempotente por secuencia esperada.
  • Las repeticiones salientes llevan el mismo id de evento, así que un consumidor que deduplica sobre él ve cada evento una vez.

Así que exactly-once es una propiedad de los efectos, lograda registrando los resultados una vez y haciendo inofensiva cada repetición. Depende de que el callee respete la key. El engine puede probar su propio lado con un ledger de efectos secundarios en la suite de tests, donde una key duplicada hace fallar un caso. No puede probar a un callee que no controla.

Una guarda más impide que un zombi deshaga esto: las ejecuciones se arriendan con un fence. Cada escritura del journal lleva el id de la ejecución y el fence, y una escritura con un fence obsoleto no cambia nada.