~/studies/work 2026-11-13 · published 2026-11-21
Durable execution, explicada através do nagare
O que um journal, o replay determinístico, um inbox e um outbox realmente fazem em um engine de workflows durável, e por que at-least-once mais fronteiras idempotentes é o que exactly-once significa na prática.
- workflow
- durable-execution
- journal
- inbox
- outbox
- ~/project/versatile-sh
O problema
Um workflow que chama três serviços pode cair entre a segunda e a terceira chamada. O trabalho de um engine durável é tornar essa queda entediante: a execução retoma de onde estava, e as chamadas que já aconteceram não acontecem de novo.
nagare é o engine de workflows durável em que trabalho. Um workflow é um grafo JSON com nove tipos de nó. Todo efeito colateral é uma chamada de uma operação sobre uma conexão. Este post explica os quatro mecanismos que tornam uma queda entediante, usando os próprios ADRs do engine como fonte: o journal, o replay determinístico, o inbox e o outbox. Não há benchmarks aqui. Os números estão em outro post, What exactly-once over a journal costs.
O journal
Um journal é uma lista append-only de entradas por execução. Cada coisa durável que o interpretador faz pega o próximo número de sequência: um passo, uma leitura do relógio, um id gerado, um sleep, um wait, uma mensagem recebida, o início de uma execução filha.
Um passo é um comando nomeado. Sua key é montada com o nó, quantas vezes o nó foi visitado e a tentativa, por exemplo `<node>#<visit>@<attempt>`. A mesma string, prefixada com o id da execução, é a idempotency key entregue a quem responde à chamada.
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 1As keys fazem parte do contrato de replay. Mudar uma é uma mudança incompatível do interpretador, e o ADR diz que ela sai como uma build nova que drena a antiga em vez de remendar execuções estacionadas.
Replay determinístico
Depois de uma queda o engine não restaura um snapshot de memória. Ele roda o interpretador de novo desde o início. Cada chamada durável consulta o journal primeiro: se existe uma entrada naquela posição, o resultado registrado é devolvido e nada executa. Só a primeira posição sem entrada executa de verdade.
Isso só funciona se o interpretador faz a mesma sequência de chamadas toda vez. Por isso o interpretador é determinístico por regra. Dentro do pacote do interpretador não há `time.Now`, nem `math/rand`, nem goroutines, nem `select`, nem iteração de maps sem ordenar, nem I/O, nem globais. O tempo e os ids vêm do contexto durável, então são registrados uma vez e reproduzidos.
O journal verifica isso em runtime. Se o replay pede uma chamada cujo kind ou key difere da entrada registrada, a execução falha com um erro de não determinismo em vez de seguir sobre uma história errada.
Os retries seguem a mesma regra. Cada tentativa é seu próprio passo, o backoff é um sleep durável e o retry nativo do engine fica desligado. Um único interpretador é dono da semântica de retry, então todos os engines atrás do port se comportam igual.
Inbox e outbox
O journal cobre o que acontece dentro de uma execução. As bordas precisam do mesmo tratamento. Um callback que chega enquanto o engine está fora não pode se perder, e um evento que uma execução emite não pode se perder nem ser publicado duas vezes.
Para o que entra, o ADR-0012 diz: persistir e depois confirmar. Todo webhook, callback, sinal e evento é inserido em uma tabela e respondido na hora. A key é tenant, source e message id, única entre réplicas. Uma mensagem nova responde 202 e uma duplicada responde 200. O handler nunca chama o engine. Um dispatcher entrega depois, em ordem por ordering key, at least once. Antes dessa mudança, uma queda do engine devolvia 5xx a um chamador que nunca reenviaria.
O que sai é o espelho. Acrescentar eventos de uma execução escreve os eventos, a projeção do read-model e as linhas do outbox em uma transação, protegida pelo último número de sequência. Um relay publica as linhas nos sinks depois, também at least once. O id do evento é montado com tenant, stream e sequência, então um consumidor pode descartar repetidos. Quando o id de uma execução é reutilizado após uma exclusão, um epoch é adicionado ao id para que a história nova não colida com a antiga (ADR-0015).
O que exactly-once significa aqui
O README é direto: o engine não é exactly-once. A entrega é at least once em todo lugar, e cada fronteira é idempotente em vez disso. Um passo pode rodar duas vezes se o processo morre depois da chamada e antes do registro. Sob o journal remoto esse caso é explícito: o passo roda de novo depois que o lease expira.
- Duplicados de entrada são absorvidos pela message key única e pelo próprio dedupe do inbox do engine para sinais.
- Um passo repetido carrega a mesma idempotency key, então um callee que a respeita aplica o efeito uma vez.
- Um flush de eventos retentado nunca duplica eventos, porque o append é idempotente por sequência esperada.
- Repetições de saída carregam o mesmo id de evento, então um consumidor que deduplica nele vê cada evento uma vez.
Então exactly-once é uma propriedade dos efeitos, obtida registrando os resultados uma vez e tornando cada repetição inofensiva. Depende de o callee respeitar a key. O engine pode provar o próprio lado com um ledger de efeitos colaterais na suíte de testes, onde uma key duplicada falha um caso. Ele não pode provar um callee que não controla.
Mais uma guarda impede que um zumbi desfaça isso: as execuções são alugadas com um fence. Toda escrita do journal carrega o id da execução e o fence, e uma escrita com fence obsoleto não muda nada.