Adattatori di provider

L'adattatore del provider è un livello di integrazione isolato (anti-corruption layer, ACL) che traduce il contratto esterno del fornitore (provider di giochi, gateway di pagamento, KYC/AML, rischio-scorrimento, notifica, ecc.) in una lingua di dominio interna e di ritorno. Mostra il dominio da API instabili, anomalie di rete, evoluzioni di schemi e regole di sicurezza.

1. Decoupling: nessun payload esterno «crudo» entra nel nucleo.

2. Affidabilità: gestione dei guasti (timeouts, retries, DLQ, circuito breaker).

3. Coerenza: Idampotenza, ordine della chiave, messejing transazionale.

4. Utilizzo: metriche, tracking, limiti, isolamento per tenanti e residency.

1) Area di responsabilità dell'adattatore

Contratti: descrizione di schemi/endpoint esterni; mapping per comandi/eventi interni.
Trasporti: REST/gRPC/WebSocket/SQS/Kafka/SFTP; pool di connessioni, backpressure.
Sicurezza: mTLS, OAuth2, HMAC, chiavi/certificati per tenant/region, rotazione dei segreti.
Affidabilità: timeout, retrai con jitter, circuito breaker, deduplicazione.
Idempotenza: 'Idempotency-Key '/' richiest _ id', memorizzazione delle risposte/stati.
Osservabilità: metriche SLO, fogli strutturali, tracciabilità.
Versioning: supporta più versioni di diagrammi/endpoint.
Operazioni: ficcoflagi, rilasci canarini, cassette di sabbia, certificazione.

2) Dove si applicano (esempi di contesti)

Game/RGS: avvio/chiusura del round, puntate/vincite, token sessioni, stato del provider.
Payments/PSP: depositi/conclusioni, webhooks states, conformeback, 3-D Secure.
KYC/AML: controlli, sanzioni/controlli RER, monitoraggio delle transazioni.
Risk/Fraud: scorciatoie, trigger, suggerimenti di blocco.
Comms: e-mail/SMS/push, limiti di distribuzione, modelli.

Ogni tipo ha la propria macchina degli eventi state e SLA - l'adattatore è obbligato a normalizzarla.

3) Contratto e mapping (interno-esterno)

• Immettiamo Published Language all'interno dell'adattatore e non trasciniamo mai fuori i campi del provider.
• Tutti i messaggi contengono «tenant _ id», «region», «provider _ id», «operation _ id», «variante _ ts».
• Supporta più versioni di diagrammi esterni tramite i mapper.

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) Idampotenza e ordine

Ricorest de-dup: 'Idempotency-Key: <operation _ id>' nelle query; storim '(op _ id) stato/risposta finale)' con TTL.
Webhook de-dup: tabella «inbox (provider, event _ id)» come PK.
Ordine chiave: serializzare le chiamate e l'elaborazione per «aggregate _ id» (ad esempio, «round _ id» o «psp _ tx _ id»).
Outbox/Inboxing - Messejing transazionale su entrambi i bordi della catena di montaggio.

5) Affidabilità: timeout, retrai, circuito breaker

Timeout: client-side brevi (p95), separati per connect/read.
Retrai: solo su retryable (5xx/timeout/429), backoff esponenziale + full jitter, limite di tentativi e deadline condivisa.
Circuito Breaker: apri quando crescono errori/latitanza; graceful degradation (ad esempio, disattivare i fili secondari RGS, impostare «in attesa del risultato»).
DLQ: messaggi «velenosi» con una ricca meta-informazione, una redrave sicura.

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, quote, competitività

Rispettare i vincoli del provider (RPS, burst, concurency).
Implementare un WFQ/DRR per tenente (fairness) in modo che il client «rumoroso» non mangi il budget.
Rispettate il titolo Retry-After/' s.
Code interne + backpressure sul produttore.

7) Sicurezza e conformità

Trasporti: mTLS, TLS 1. 2 +, cipher suite aggiornati, certificati pinning se possibile.
Autenticazione: OAuth2 client-credentials/MTLS, HMAC (hash corporeo firmato + timestamp), API.
Riduzioni PII: solo i campi necessari maschera/redazione in logi e DLQ.
Segreti: KMS/HashiCorp Vault, rotazione automatica, isolamento per tenant/region.
Compendio: PCI DSS per PSP, storage di token al posto di PAN, GDPR/leggi locali sui dati.

8) Multi-tenente e multi-regione

Configurazione delle chiavi/endpoint per tenante/regione.
Data residency: le chiamate vengono da una regione «domestica» Le regioni crociate sono solo apparecchiature.
Isolamento: pool di connessioni personalizzati e limiti 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) Osservabilità: metriche, loghi, tracking

• Successo/errore per classe (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency secondo il metodo.
• Rate-limit attivazione, apertura/chiusura breaker, DLQ-rate, redrive-success.
• Loghi strutturali: «tenant _ id», «provider _ id», «operation _ id», «endpoint», «status», «attempt», «backoff _ ms».
• Tracing: unico «trace _ id», span «serialize» send «receive» map «publish», tag «schema _ variante», «region».

10) Versioning e ficcoflagi

Supporto parallelo v1/v2 del contratto esterno; migrazione - canaria/per tenanti.
Ogni nuovo fornitore di servizi è dietro la bandiera; cambio senza rilascio.
Contratto di evoluzione: additive-first, convalida rigorosa degli schemi (JSON Schema/Proto).

11) Playbooks (runbooks)

1. Scala 429/limite: abilita il trottling globale, rispetta Retry-After, ridistribuisce le finestre tra i tenenti.
2. La crescita dei timeout è ridurre i concurrency, aumentare i timeout con cautela, aprire breaker, attivare il degrado del fich.
3. Schema mismatch: congelare redrave, attivare mapper compatibili, eseguire backfill/riprocessing.
4. Flap webhoop: vai alla modalità pull/reconcile, applica inbox-deadup.
5. L'incidente del provider è di passare a un cavo di sabbia/DC di riserva (se disponibile), di attivare operazioni «ritardate».

12) Test

Test contrattuali: producer/consumer contro ficstour del provider.
Test di caos: ritardi, drop, out-of-order, duplicati, risposta parziale, interruzione della connessione.
Performance: stress alle prese con i burst; misura p95/p99, comportamento breaker.
Idampotenza: il ripetizione degli stessi «operation _ id» non crea effetti aggiuntivi.
E2E nelle cassette di sabbia: happy-path/changeback/controversie/annullamento/recalk.

13) Opzioni di implementazione (deployment patterns)

Adattatore di servizio separato: + isolamento, rilasci indipendenti; --- rete.
Sidecar/plugin: + località delle chiamate; - più difficile da gestire versioni.
Libreria: + facile da incorporare; - alto cupling e versioni distribuite.

La raccomandazione è una scheda di servizio con API nitida e ciclo di lancio.

14) Modello di adattatore 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 con'provider _ event _ id ' inbox' (PK su '(provider, event _ id)') è un evento di dominio .

15) Errori tipici

Trascinare lo schema esterno «crudo» verso il dominio con connettività rigida e migrazioni costose.
La mancanza di idepotenza e inbox/outbox → le riprese di effetti e stati fantasma.
Retrai senza jitter/limiti, tempesta e ban su rate limit.
L'unico pool globale senza fairness è un tenente che mette tutti.
Non è possibile indagare su incidenti e rischi di compliance senza un PI/ID.
Niente canarie o bandiere, il lancio rompe tutti.
Ignorare Retry-After e gli orari di manutenzione del provider.

16) Foglio di assegno prima della vendita

• Mupping di diagrammi esterni per la lingua interna versioni e compatibilità inversa.
• Idampotenza di query/webhook ('operation _ id', 'inbox').
• Timeout, retrai con full-jitter, circuito breaker, DLQ e redrave sicuro.
• Rate limits и fairness per tenant; Rispetto per Retry-After.
• mTLS/OAuth/HMAC, rotazione dei segreti, minimizzazione PII, controllo degli accessi.
• Isolamento regionale e data residency; configi per tenant/region.
• Metriche p95/p99, errore di classe, breaker/429/DLQ-rate; La roulotte.
• Arenili e test contrattuali; rollout canario e ficcoflagi.
• Playbook incidenti e formazione on-call.
• Documentazione: SLA, limiti, schemi, processi di evoluzione.

Conclusione

Gli adattatori di provider sono uno scudo e un traduttore tra il dominio e il mondo esterno. Una forte ACL con idoneità, controllo degli errori e osservabilità rende prevedibili le integrazioni, riduce i costi di cambiamento del provider e protegge dagli errori di catena. Progettate gli adattatori come componenti autonomi e gestiti e il vostro mondo esterno smette di rompere l'architettura interna.