Orquestração de Saga

Padrões para gerenciar transações distribuídas e processos de negócios de longa duração sem o two-phase commit.

Entradas e Saídas

O que você fornece:

• Limites e propriedade de serviços (qual serviço é dono de qual etapa)
• Requisitos de transação (quais etapas devem ser atômicas, quais podem ser eventuais)
• Modos de falha para cada etapa (transitório vs. permanente, política de retentativa)
• Requisitos de SLA por etapa (informa a configuração de timeout)
• Infraestrutura de eventos/mensagens existente (Kafka, RabbitMQ, SQS, etc.)

O que esta habilidade produz:

• Definição de saga com etapas ordenadas, comandos de ação e comandos de compensação
• Implementação de orquestrador ou coreografia para o padrão escolhido
• Lógica de compensação para cada serviço participante (idempotente, sempre-sucedida)
• Configuração de timeout de etapa com prazos por etapa
• Configuração de monitoramento: métricas de máquina de estado, detecção de saga travada, recuperação de DLQ

Quando Usar Esta Habilidade

• Coordenar transações multi-serviço sem locks distribuídos
• Implementar transações compensatórias para falhas parciais
• Gerenciar fluxos de trabalho de negócios de longa duração (minutos a horas)
• Lidar com falhas em sistemas distribuídos onde a atomicidade é necessária
• Construir processos de atendimento de pedidos, aprovação ou reserva
• Substituir o frágil two-phase commit por compensação assíncrona

Seção Detalhada: Conceitos Principais

Movido para references/details.md.

Seção Detalhada: Modelos

Movido para references/details.md.

Melhores Práticas

FAZER

• Torne cada etapa idempotente — Comandos podem ser reproduzidos na reconexão do broker
• Projete compensações cuidadosamente — Elas são o caminho de código mais crítico
• Use IDs de correlação — O saga_id deve fluir por cada evento e log
• Implemente timeouts por etapa — Nunca espere indefinidamente por uma resposta do participante
• Registre transições de estado — saga_id, step_name, old_state → new_state a cada mudança
• Teste explicitamente os caminhos de compensação — Injete falhas em cada índice de etapa em testes de integração

NÃO FAZER

• Não assuma conclusão instantânea — Sagas são assíncronas e podem levar minutos
• Não pule o teste de compensação — O caminho de rollback é o mais difícil de acertar
• Não acople serviços diretamente — Use mensagens assíncronas, nunca chamadas síncronas dentro de uma etapa de saga
• Não ignore falhas parciais — Uma etapa que executou parcialmente ainda precisa de compensação
• Não use um timeout global — Cada etapa tem características de latência diferentes

Solução de Problemas

Saga travada no estado COMPENSATING

Uma saga entra em compensação, mas nunca atinge FAILED. Isso significa que um manipulador de compensação está lançando uma exceção não tratada e nunca publica SagaCompensationCompleted. Adicione tratamento de fila de mensagens mortas (DLQ) aos consumidores de compensação e garanta que cada ação de compensação publique um evento de resultado, mesmo quando a operação subjacente já foi revertida.

async def handle_release_reservation(self, command: Dict):
    try:
        await self.release_reservation(command["original_result"]["reservation_id"])
    except ReservationNotFoundError:
        pass  # Already released — treat as success
    # Always publish completion, regardless of outcome
    await self.event_publisher.publish("SagaCompensationCompleted", {
        "saga_id": command["saga_id"],
        "step_name": "reserve_inventory"
    })

Execuções duplicadas de saga na reinicialização

Se o seu serviço orquestrador reiniciar no meio de uma saga, ele pode reproduzir eventos e reexecutar etapas já concluídas. Proteja cada ação de etapa com uma chave de idempotência — veja o Modelo 3 acima.

Saga de coreografia perdendo eventos

Em uma saga baseada em coreografia, um serviço downstream pode perder um evento se estiver offline quando ele foi publicado. Use um broker de mensagens durável (Kafka com replicação, RabbitMQ com persistência) e armazene o estado atual da saga em uma tabela saga_log dedicada para que você possa reproduzir a partir da última etapa conhecida e válida.

Timeout disparando antes que uma etapa lenta, mas válida, seja concluída

Uma etapa como create_shipment pode levar até 15 minutos durante o pico de carga, mas seu timeout global é de 5 minutos, causando compensação espúria. Torne os timeouts de etapa configuráveis por tipo de etapa — veja references/advanced-patterns.md para a implementação TimeoutSagaOrchestrator e o padrão de dicionário STEP_TIMEOUTS.

Ordem de compensação não correspondendo à ordem de execução

…