~/studies/work 2026-11-21

Sagas à mão vs execução durável

Uma comparação de design, sem medições, entre sagas feitas à mão e um motor de workflows duráveis: o que você escreve por conta própria em cada uma e o que continua sendo problema seu nos dois casos.

O que é e o que não é

Nem os docs do nagare, nem os ADRs, nem os estudos de pesquisa que li comparam as duas abordagens, e ninguém mediu uma contra a outra. Este post é uma comparação de design. De propósito, não traz números de benchmark.

A comparação é sobre trabalho, não velocidade: quais peças você escreve e opera por conta própria e quais um motor durável entrega. As afirmações do lado do motor vêm dos ADRs do nagare. O lado à mão é o formato habitual do padrão, não o registro de um sistema específico.

Uma saga à mão

Uma saga divide uma operação de negócio em passos locais, cada um com um passo compensatório que o desfaz. À mão, quase sempre você acaba construindo o mesmo conjunto de peças.

  • Uma tabela de estado que registra a que passo cada instância chegou, escrita na mesma transação que o efeito do passo.
  • Uma forma de entregar o próximo comando depois desse commit, o que costuma significar uma tabela outbox e um relay.
  • Um inbox ou uma chave única por mensagem, porque o relay e o broker entregam pelo menos uma vez.
  • Timers para deadlines e novas tentativas, com armazenamento próprio e um poller.
  • Compensações que, por sua vez, são idempotentes e repetíveis.
  • Um job de recuperação que encontra instâncias travadas no meio e as faz seguir adiante.

Nada disso é difícil isoladamente. O custo é que o fluxo de controle da operação de negócio acaba espalhado entre handlers, tabelas e tipos de mensagem. Para responder onde está uma instância, você lê uma tabela de estado e reconstrói a história.

A mesma coisa em um motor durável

Um motor durável empurra as cinco primeiras peças para baixo do seu código. A tabela de estado é o journal. A entrega depois do commit é um outbox e um inbox que pertencem ao motor. Os timers são sleeps duráveis. A recuperação é replay: a execução retoma a partir do seu histórico registrado.

No nagare o fluxo é um grafo e cada nó termina com um resultado. Um transporte devolve uma falha com um código e uma marca retryable. Uma falha retryable é repetida, e uma final dá o resultado `failed`. A execução então segue pela aresta desse resultado, e se não existir aresta a execução falha. Uma compensação é, portanto, um ramo comum do grafo, alcançável a partir da aresta de falha do passo que ela desfaz (ADR-0003).

Onde uma instância está pode ser lido do seu event log. Os eventos de cada execução são acrescentados em uma só transação junto com o read model e as linhas do outbox, então a história é um histórico armazenado e não uma reconstrução.

O que continua sendo seu nos dois casos

  • O design da compensação. Um motor não sabe como desfazer uma captura de pagamento. Você ainda decide a operação inversa e se ela é sequer possível.
  • Destinatários idempotentes. A entrega é pelo menos uma vez nos dois mundos. No nagare cada passo carrega uma chave construída com run, node, visit e attempt, e ela só ajuda se o serviço que a recebe a respeitar. A chamada de cancelamento também está documentada como at-least-once, então deve tratar uma referência desconhecida ou já finalizada como sucesso.
  • Isolamento. Uma saga não é uma transação: outros leitores podem ver o estado intermediário entre os passos.

O que o motor cobra de você

A execução durável não é livre de custo de design. O código do workflow, ou aqui o interpretador, precisa ser determinístico: sem relógio, aleatoriedade nem I/O fora das chamadas registradas. As chaves de passo viram um contrato, porque o replay se apoia nelas. Uma mudança incompatível no interpretador sai como um build novo que drena as execuções antigas, já que execuções estacionadas não são corrigidas no lugar (ADR-0011).

Você também assume um motor como dependência a operar e, no caso do nagare, uma decisão sobre qual motor fica atrás do port. Essa decisão é o assunto do post sobre o port do motor durável.

Minha regra prática, como hipótese e não como achado: uma saga feita à mão é razoável para dois ou três passos em um serviço que já tem um outbox. Quando timers, esperas por eventos externos, cancelamento e histórico de execução são todos necessários, a lista de peças acima é um motor durável escrito devagar.