Funcionalidades

Resiliência & Consistência

4 min de leitura

Idempotência e Circuit Breaker fazem parte do core do Orquestraio — não são opcionais. Esta página documenta ambos os mecanismos.

Idempotência

O campo idempotencyKey garante que a mesma transação nunca seja processada duas vezes, mesmo com falhas de rede e múltiplas tentativas.

Typo corrigido na v0.4.0: idempotecyKey → idempotencyKey. Atualize suas requisições se estiver usando a v0.3.x.

Como Funciona

Quando uma requisição chega com um idempotencyKey:

  1. O Orquestraio verifica no Redis se essa chave já foi processada
  2. Se não existe, processa normalmente e armazena o resultado com TTL de 24h
  3. Se já existe, retorna o resultado cacheado sem chamar o gateway novamente
sequenceDiagram participant C as Cliente participant O as Orquestraio participant R as Redis participant G as Gateway C->>O: POST /v1/payments (idempotencyKey: "order-abc") O->>R: Verificar chave R-->>O: Não existe - processar O->>G: Criar pagamento G-->>O: APPROVED O->>R: Salvar resultado (TTL 24h) O-->>C: 201 APPROVED C->>O: POST /v1/payments (idempotencyKey: "order-abc") O->>R: Verificar chave R-->>O: Existe - retornar cache O-->>C: 201 APPROVED (cached)
Boas práticas: Use UUID v4 gerado no backend, vinculado ao ID do pedido no seu sistema. Nunca reutilize a mesma chave para transações distintas.

Circuit Breaker

Cada gateway tem circuit breaker independente via Resilience4j. Quando a taxa de falha ultrapassa o threshold, o gateway é isolado temporariamente.

Configuração por Gateway

GatewayJanelaThresholdTempo abertoHalf-open
STRIPE10 req50%20s3 calls
MERCADO_PAGO10 req50%15s3 calls
PAYPAL10 req50%20s3 calls

Estados do Circuit Breaker

stateDiagram-v2 [*] --> CLOSED CLOSED --> OPEN : falhas > 50% em 10 req OPEN --> HALF_OPEN : após timeout (20s) HALF_OPEN --> CLOSED : 3 chamadas OK HALF_OPEN --> OPEN : qualquer falha

CLOSED — Gateway funcionando normalmente. Todas as requisições são enviadas.

OPEN — Gateway em falha. Requisições retornam erro imediatamente sem chamar o gateway.

HALF_OPEN — Gateway em teste. Permite 3 chamadas para verificar se voltou ao normal.

Fallback automático: Se o gateway principal estiver OPEN, o SmartRouter tenta automaticamente um gateway alternativo compatível antes de retornar erro ao cliente.

Exemplo de Cenário Real

  1. 10 requisições enviadas para o Stripe
  2. 6 delas falham (timeout, 500, etc.) — 60% de falha
  3. Circuit Breaker muda para OPEN
  4. Próximas requisições retornam erro imediatamente por 20 segundos
  5. Após 20s, muda para HALF_OPEN e permite 3 tentativas
  6. Se as 3 tentativas forem bem-sucedidas, volta para CLOSED

Os estados do Circuit Breaker são logados em execution_history e podem ser monitorados via métricas (Prometheus/Grafana em v0.6).