Adaptadores de provedores

O adaptador do provedor é uma camada isolada de integração (anti-corrupção layer, LCA) que traduz o contrato externo do provedor (provedor de jogos, gateway de pagamento, KYC/AML, gerenciamento de risco, notação, etc.) para a língua interna de domínio e de volta. Ele mostra domínios de APIs instáveis, anomalias de rede, evoluções de esquemas e políticas de segurança.

1. Dekupling: Nenhum payload externo «cru» entra no núcleo.

2. Confiabilidade: Gerencie falhas (timeouts, retries, DLQ, circuito breaker).

3. Coerência: Idempotação, ordem da chave, messejagem transacional.

4. Operação: métricas, trailing, limites, isolamento por tenente e residency.

1) Área de responsabilidade do adaptador

Contratos: descrição de esquemas externos/endpoint; mapping → comandos/eventos internos.
Transporte: REST/gRPC/WebSocket/SQS/Kafka/SFTP; pool de conexões, backpressure.
Segurança: mTLS, OAuth2, HMAC, chaves/certificados per tenant/region, rotação de segredos.
Confiabilidade: temporizadores, retais com jitter, circuito breaker, dedução.
Idempotidade: 'Idempotency-Key '/' request _ id', armazenamento de respostas/estatais.
Observabilidade: métricas SLO, logs estruturais, rastreamento.
Versioning: suporta várias versões de circuitos/endpointos.
Operações: ficheflags, canários, areias, certificação.

2) Onde aplicar (exemplos de contextos)

Game/RGS: início/encerramento da rodada, apostas/ganhos, tokens sessões, estatais do provedor.
Payments/PSP: depósitos/conclusões, webhooks estatais, chargeback, 3-D Secure.
KYC/AML: verificações, verificações de sanções/RER, monitoramento de transações.
Risk/Fraud: compilação, desencadeadores, recomendações de bloqueio.
Comms: e-mail/SMS/push, limites de distribuição, modelos.

Cada tipo tem sua máquina de eventos state e SLA - o adaptador é obrigado a normalizá-lo.

3) Contrato e mapping (interno ↔ externo)

• Digitamos o Published Language dentro do adaptador e nunca puxamos para fora o campo do provedor.
• Todas as mensagens são 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts'.
• Suporta várias versões de esquemas externos via mapers.

yaml mapping:
provider: "AcmeRGS"
version: "v3"
inbound:
SpinResultV3 -> Round. Resulted
BonusWinV3  -> Bonus. Wagered outbound:
StartRound  -> POST /v3/sessions/{id}/start
Stake    -> POST /v3/spins compat:
accepts: ["v2","v3"]
emits:  ["v3"]

4) Idempotidade e ordem

Request de-dup: 'Idempotency-Key: <operation _ id>' nas solicitações; estorim '(op _ id → status final/resposta)' s TTL.
Webhook de-dup: tabela 'inbox (provider, event _ id)' como PK.
Ordem da chave: Serializando chamadas e processando por 'aggregate _ id' (por exemplo, 'round _ id' ou 'psp _ tx _ id').
Outbox/Inboxing: Messejing transaccional em ambas as bordas da linha de montagem.

5) Confiabilidade: timeouts, retrações, circuito breaker

Temporizações: curtas de cliente-side (p95-orientado), separadas para connect/read.
Retrai: somente em retryable (5xx/timeout/429), backoff exponencial + full jitter, limite de tentativas e deadline compartilhado.
Circuito Breaker: abrir quando os erros/laticínios crescem; graceful descradation (por exemplo, desativar os fichas RGS secundários e colocar «espera de resultados»).
DLQ: Mensagens «venenosas» com uma rica meta-informação, redrave segura.

yaml reliability:
timeout_ms:
connect: 1000 read:  1500 retry:
max_attempts: 6 initial_backoff_ms: 200 max_backoff_ms: 8000 jitter: full retry_on: [TIMEOUT, 5xx, 429]
circuit_breaker:
failure_rate_threshold: 20%   # за окно slow_call_threshold_ms: 1500 half_open_max_calls: 10

6) Rate limits, quotas, competição

Cumpra os limites do provedor (RPS, burst, concurency).
Implemente o WFQ/DRR (fairness) para garantir que o cliente «barulhento» não coma o orçamento.
Respeite 'Retry-After '/' X-RateLimit -' títulos.
Filas internas + backpressure no produtor.

7) Segurança e conformidade

Transporte: mTLS, TLS 1. 2 +, cipher suites atuais, certificados pinning sempre que possível.
Autenticação: OAuth2 clientes-credentals/MTLS, HMAC (hashs corporais assinados + timestamp), API chaves.
Minimização PII: apenas os campos necessários; camuflagem/redação em logs e DLQ.
Segredos: KMS/HashiCorp Vault, rotação automática, isolamento per tenant/region.
Complacência: PCI DSS para PSP, armazenamento de tokens em vez de PAN, GDPR/leis locais de dados.

8) Multi tenante e região multi

Configuração de chaves/endpoint por tenante/região.
Data residency: Os desafios são feitos a partir de uma região «doméstica»; A Região Cruzada é só uma unidade.
Isolamento: pool de conexões próprias e limites per tenant.

yaml tenants:
T1:
region: eu-central provider_keys:
acme_rgs: { client_id: "...", cert_ref: "vault://..." }
psp_foo: { hmac_key_ref: "kms://..." }
endpoints:
acme_rgs: "https://eu. api. acme-rgs. com"
psp_foo: "https://eu. api. psp-foo. com"
T2:
region: sa-east
...

9) Observabilidade: métricas, logs, trailing

• Sucesso/erro por classe (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency pelo método.
• Rate-limit ativação, abertura/encerramento breaker, DLQ-rate, redrive-sucess.
• Logs estruturais: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt',' backoff _ ms '.
• Tracing: um 'trace _ id', span 'serialize' send 'receive map publish', tags 'schema _ versão', 'region'.

10) Versionização e feijoada

Suporte paralelo v1/v2 contrato externo; migração: canário/por tenente.
Qualquer nova fiação do provedor, atrás da bandeira; alternar sem lançamento.
Tratado de Evolução: aditivo-first, validação rigorosa de esquemas (JSON Schema/Proto).

11) Playbooks (runbooks)

1. Escala 429/limites: inclua o trottling global, respeite «Retry-After», redistribua as janelas entre os tenentes.
2. Crescimento dos temporizadores: reduzir concurrency, aumentar os temporizadores com cuidado, abrir breaker, ativar a degradação do fic.
3. Schema mismatch: congelar redrave, incluir mapper compatível, fazer backfill/reprocessamento.
4. Flip webhoop: ir para o modo pull/recôncil, aplicar inbox-deadup.
5. O incidente do provedor é mudar para a caixa de areia/DC de reserva (se houver) e ativar as operações «postergadas».

12) Testes

Testes contratuais: producer/consumer contra ficstures do provedor fixados.
Testes de caos: atrasos, drop, out-of-order, duplicados, resposta parcial, quebra de conexão.
Performance: estresse nos aspos burst; medição p95/p99, comportamento breaker.
Idempotidade: a repetição das mesmas 'operation _ id' não cria efeitos adicionais.
E2E em barras de areia: guiões happy-path/chargeback/disputas/cancelamento/recall.

13) Opções de implementação (deployment patterns)

Adaptador de serviço individual: + isolamento, lançamentos independentes; - rede de suprimento.
Sidecar/plugin: + localidade de chamadas; - mais difícil de gerenciar versões.
Biblioteca: + simples incorporação; - alto coupling e versões compartilhadas.

Recomendação: adaptador de serviço com API clara e seu ciclo de lançamento.

14) Exemplo de adaptador API (pseudo)

http
POST /adapters/psp/authorize
Headers:
X-Tenant: T1
Idempotency-Key: op-uuid
Body:
{ "amount":"10. 00","currency":"EUR","method":"card","card_token":"tok_..." }

→ 202 Accepted
{
"operation_id":"op-uuid",
"status":"PENDING",
"as_of":"2025-10-31T12:00:00Z"
}

• Webhook com 'provider _ event _ id' n' inbox '(PK em' (provider, event _ id) ') mapping evento de domínio' '.

15) Erros típicos

Arrastar o circuito externo «cru» para o domínio → a conectividade rígida e as migrações caras.
Falta de idempotidade e inbox/outbox → duplicações de efeitos e estados fantasmas.
Retrai sem jitter/limites → tempestade e ban por rate limit.
O único pool global sem fairness → um tenante «põe» todos.
Logs sem edição PII/ID não podem ser investigados por incidentes ou risco de complacência.
Sem canarinhos/bandeiras → o lançamento quebra todos.
Ignorar 'Retry-After' e os horários de serviço do provedor.

16) Folha de cheque antes de vender

• O mapping dos circuitos externos → a língua interna; versões e compatibilidade invertida.
• Idempotidade de solicitações/webhooks ('operation _ id', 'inbox').
• Timouts, retrações com full-jitter, circuito breaker, DLQ e redrave seguro.
• Rate limits и fairness per tenant; Respeito a 'Retry-After'.
• mTLS/OAuth/HMAC, rotação de segredos, minimização PII, auditoria de acesso.
• Isolamento regional e data residency; configs per tenant/region.
• Métricas p95/p99, erro de classe, breaker/429/DLQ-rate; Trailing.
• Banco de areia e testes contratuais; rollout canarinho e fichicheflags.
• Playbooks incidentes e treinamento on-call.
• Documentação: SLA, limites, esquemas, processos de evolução.

Conclusão

Os adaptadores são um escudo e um tradutor entre o seu domínio e o mundo exterior. A ACL forte, com idumpotência, controle de erros e observabilidade, torna previsível a integração, reduz o custo de mudança do provedor e protege contra «falhas de cadeia». Concebam os adaptadores como componentes independentes, controláveis - e o seu «mundo exterior» deixará de quebrar a arquitetura interna.