Saga Pattern no Node.js: transações distribuídas

Saga Pattern no Node.js coordena processos de negócio que atravessam vários serviços ou bancos sem usar uma transação distribuída. Cada etapa executa uma transação local e, se algo falhar, ações de compensação desfazem ou neutralizam efeitos anteriores.

Uma saga é apropriada para fluxos como pedido, pagamento, estoque e entrega. Ela não oferece rollback perfeito; compensações representam novas ações de negócio.

Exemplo de fluxo

1. criar pedido;
2. reservar estoque;
3. autorizar pagamento;
4. confirmar pedido;
5. solicitar entrega.

Se o pagamento falhar, a saga libera estoque e cancela o pedido.

Coreografia

Na coreografia, cada serviço reage a eventos e publica o próximo fato.

PedidoCriado -> EstoqueReservado -> PagamentoAprovado -> PedidoConfirmado

O modelo tem baixo acoplamento direto, mas o fluxo pode ficar difícil de visualizar.

Orquestração

Na orquestração, um componente central envia comandos e acompanha respostas.

export class CheckoutSaga {
  async iniciar({ pedidoId }) {
    await this.estado.criar({ pedidoId, etapa: 'reservar_estoque' });
    await this.commands.enviar('ReservarEstoque', { pedidoId });
  }

  async onEstoqueReservado(event) {
    await this.estado.avancar(event.pedidoId, 'autorizar_pagamento');
    await this.commands.enviar('AutorizarPagamento', {
      pedidoId: event.pedidoId
    });
  }
}

O orquestrador deixa o processo explícito, mas se torna um componente crítico.

Estado persistido

Não mantenha a saga apenas em memória. Persista ID, etapa, status, tentativas, deadlines e dados necessários.

CREATE TABLE sagas (
  id uuid PRIMARY KEY,
  business_key text UNIQUE NOT NULL,
  state text NOT NULL,
  status text NOT NULL,
  data jsonb NOT NULL,
  version integer NOT NULL,
  updated_at timestamptz NOT NULL
);

Compensações

Compensar não significa apagar a história. Um pagamento capturado pode exigir estorno. Uma reserva de estoque precisa ser liberada. Um e-mail enviado não pode ser “desenviado”.

• ReservarEstoque → LiberarEstoque;
• CapturarPagamento → EstornarPagamento;
• CriarEntrega → CancelarEntrega.

Idempotência

Comandos e eventos podem ser repetidos. Use IDs estáveis e chaves de negócio.

await pagamentos.autorizar({
  idempotencyKey: `saga:${sagaId}:authorize`,
  pedidoId,
  valor
});

Mensagens fora de ordem

Valide etapa e versão antes de aplicar uma resposta. Eventos antigos devem ser ignorados ou registrados para análise.

Timeouts

Cada etapa precisa de deadline. Um scheduler pode localizar sagas vencidas e iniciar retry ou compensação.

SELECT * FROM sagas
WHERE status = 'running'
  AND deadline_at < now()
FOR UPDATE SKIP LOCKED;

Retries

Repita apenas falhas transitórias. Uma recusa de pagamento é resultado de negócio, não erro técnico. Diferencie timeout, indisponibilidade e resposta definitiva.

Outbox

Alterar o estado da saga e enviar o próximo comando exige entrega confiável. Grave comando ou evento em Outbox na mesma transação.

Veja Outbox Pattern no Node.js.

Concorrência

Duas mensagens podem tentar avançar a mesma saga. Use versão otimista ou lock por registro.

UPDATE sagas
SET state = $1, version = version + 1
WHERE id = $2 AND version = $3;

Observabilidade

Registre sagaId, chave de negócio, etapa, comando, evento, tentativa e duração. Crie painéis para sagas em execução, falhas, compensações e deadlines vencidos.

Auditoria

Mantenha histórico de transições. Isso ajuda suporte e investigação de processos longos.

Testes

• caminho de sucesso;
• falha em cada etapa;
• compensação parcial;
• mensagem duplicada;
• mensagem fora de ordem;
• timeout;
• queda após persistir estado;
• reprocessamento manual.

Coreografia ou orquestração?

Coreografia funciona bem em fluxos pequenos e naturalmente orientados a eventos. Orquestração é preferível quando há muitas etapas, compensações complexas ou necessidade de visualizar estado.

Quando usar

Use sagas quando uma operação cruza limites transacionais e precisa de coordenação de negócio. Não use para substituir uma transação local simples.

Erros comuns

• orquestrador apenas em memória;
• compensação tratada como rollback técnico;
• sem idempotência;
• retry de erro permanente;
• sem timeout;
• estado sem versionamento;
• coreografia impossível de rastrear;
• não oferecer intervenção manual.

Conclusão

Saga Pattern no Node.js coordena transações locais em processos distribuídos. O padrão exige estado persistido, compensações explícitas, idempotência e observabilidade.

Escolha coreografia para fluxos simples e orquestração quando o processo precisa ser controlado. Combine Saga com eventos, Outbox e contratos versionados.

Leia Event-Driven Architecture no Node.js e consulte o padrão Saga.