Adaptoare furnizor

Adaptor furnizor - un strat izolat de integrare (strat anticorupție, ACL) care traduce un contract de furnizor extern (furnizor de jocuri, gateway de plată, KYC/AML, notificare de risc, notificări etc.) într-un limbaj de domeniu intern și invers. Protejează domeniul de API-uri instabile, anomalii de rețea, evoluții scheme și politici de securitate.

1. Decuplare: Nicio sarcină utilă externă „brută” nu atinge miezul.

2. Fiabilitate: gestionați eșecurile (timeout, retries, DLQ, întrerupător de circuit).

3. Coerență: idempotență, ordine cheie, mesagerie tranzacțională.

4. Funcționare: măsurători, urmărire, limite, izolare prin transfer și rezidență.

1) Zona de responsabilitate a adaptorului

Contracte: descrierea schemelor/obiectivelor externe; maparea → comenzi/evenimente interne.
Transport: REST/gRPC/WebSocket/SQS/Kafka/SFTP; piscină conexiune, backpressure.
Securitate: mTLS, OAuth2, HMAC, chei/certificate per chiriaș/regiune, rotație de secrete.
Fiabilitate: timeout, retroys cu jitter, întrerupător de circuit, deduplication.
Idempotency: 'Idempotency-Key '/' request _ id', stocarea răspunsurilor/stărilor.
Observabilitate: măsurători SLO, busteni structurali, urmărire.
Versioning: suport pentru mai multe versiuni de scheme/endpoints.
Operațiuni: ficheflags, canare, cutii de nisip, certificare.

2) Dacă este cazul (context exemplu)

Joc/RGS: start/închide runda, pariuri/câștiguri, jetoane de sesiune, statusuri furnizor.
Plăți/PSP: depozite/retrageri, statusuri de cărți web, chargeback, 3-D Secure.
KYC/AML: verificări, sancțiuni/verificări POP, monitorizarea tranzacțiilor.
Risc/fraudă: scoring, declanșează, blocarea recomandărilor.
Comms: e-mail/SMS/push, limite de corespondență, șabloane.

Fiecare tip are propria mașină de stat eveniment și SLA - adaptorul este obligat să-l normalizeze.

3) Contract și cartografiere (intern ↔ extern)

• Introducem limba publicată în interiorul adaptorului și nu tragem niciodată câmpurile furnizorului.
• Toate mesajele poartă 'tenant _ id',' region ',' provider _ id', 'operation _ id',' version _ ts'.
• Sprijinim mai multe versiuni de scheme externe prin intermediul mappers.

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) Idempotența și ordinea

Cerere de dezactivare: 'Idempotency-Key: <operation_id>' în cereri; povestea „(op_id → statutul final/răspuns)” cu TTL.
Webhook de-dup: tabelul „inbox (furnizor, event_id)” ca PK.
Ordonați după cheie: serializați apelurile și procesați prin 'aggregate _ id' (de exemplu,' round _ id' sau 'psp _ tx _ id').
Outbox/Inboxing: mesagerie tranzactionala pe ambele margini ale conductei.

5) Fiabilitate: timeout, retrageri, întrerupător de circuit

Timeout: scurt client-side (p95-orientat), separat pentru conectare/citire.
Retractabile: retractabile numai (5xx/timeout/429), backoff exponențial + jitter complet, limita de încercare și termenul total.
Întrerupător de circuit: deschis atunci când erorile/creșterea latenței; degradare grațioasă (de exemplu, dezactivați caracteristicile secundare RGS, setați „așteptați rezultatul”).
DLQ: mesaje „otrăvitoare” cu meta-informații bogate, retrave în condiții de siguranță.

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) Limite de rată, cote, competitivitate

Respectați restricțiile furnizorului (SPR, burst, concurență).
Implementarea per-chiriaș WFQ/DRR (corectitudine), astfel încât clientul „zgomotos” să nu mănânce bugetul.
Respectați anteturile 'Retry-After '/' X-RateLimit-'.
Cozi interne + backpressure pe produs.

7) Siguranță și conformitate

Transport: mTLS, TLS 1. 2 +, suite de cifru curent, certificate de fixare, dacă este posibil.
Autentificare: OAuth2 client-acreditări/MTLS, HMAC (hashes corp semnat + timestamp), chei API.
Minimizare PII: numai câmpuri obligatorii; mascarea/editarea în jurnale și DLQ.
Secrete: KMS/HashiCorp Vault, rotație automată, izolare per chiriaș/regiune.
Conformitate: PCI DSS pentru PSP, stocare token în loc de PAN, GDPR/legile locale privind datele.

8) Multi-chiriaș și multi-regiune

Configurarea cheilor/punctelor finale per chiriaș/regiune.
Rezidența datelor: apelurile sunt efectuate din regiunea „acasă”; cross-region - numai agregate.
Izolare: piscine de conectare proprii și limite pentru fiecare chiriaș.

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) Observabilitate: valori, busteni, vectorizare

• Succese/erori pe clase (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latență prin metodă.
• Acționare cu limită de rată, întrerupător de deschidere/închidere, rată DLQ, redrive-succes.
• Jurnale structurale: 'tenant _ id',' provider _ id', 'operation _ id',' endpoint ',' status ',' încercare ',' backoff _ ms'.
• Urmărire: single 'trace _ id', spans' serialize send receive map, publish ", tag-uri 'schema _ version', 'region'.

10) Versioning și phicheflags

Suport v1/v2 al contractului extern în paralel; migraţie - canar/de chiriaşi.
Orice nouă caracteristică a furnizorului se află în spatele steagului; comutare fără eliberare.
Contract de evoluție: validarea riguroasă și aditivă a schemelor (JSON Schema/Proto).

11) Cărți de joc (runbooks)

1. Squall 429/limite: activați accelerarea globală, respectați „Retry-After”, redistribuiți ferestrele între chiriași.
2. Creștere timeout: reduce concurența, crește timpii cu atenție, întrerupător deschis, permite degradarea caracteristicilor.
3. Schema de nepotrivire: înghețați redrive, activați mapper compatibil, backfill/reprocess.
4. Clapeta Webhook: comutați în modul pull/reconcile, aplicați inbox dedup.
5. Incident la furnizor: treceți la sandbox/backup DC (dacă există), activați operațiunile „amânate”.

12) Testarea

Încercări contractuale: producător/consumator împotriva fixării prestatorului fix.
Teste de haos: întârzieri, picături, out-of-order, duplicate, răspuns parțial, deconectare.
Performanță: stres pe vârfuri de explozie; măsurarea p95/p99, comportamentul întrerupătorului.
Idempotența: repetarea aceluiași 'operation _ id' nu creează efecte suplimentare.
Sandbox E2E: scripturi happy-path/chargeback/controverse/anulare/recalc.

13) Modele de implementare

Adaptor de service separat: + izolare, versiuni independente, − rețea suplimentară.
Sidecar/plugin: + localitatea de apeluri, − mai dificil de gestionat versiuni.
Bibliotecă: + ușor de încorporat, − versiuni înalte de cuplare și pestriță.

Recomandare: adaptor de serviciu cu un API clar și ciclul său de eliberare.

14) Adaptor API Exemplu (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 cu 'provider _ event _ id' →' inbox '(PK on' (provider,event_id) ') → maparea evenimentului → domeniu' PaymentAuthorized '.

15) Erori tipice

Trăgând un circuit extern „brut” într-un domeniu → conectivitate strânsă și migrații costisitoare.
Lipsa de idempotență și inbox/outbox → efecte duplicate și stări fantomă.
Retrai fără jitter/limite → furtună și interzicerea limitei ratei.
Singura piscină globală fără corectitudine → un chiriaș „pune” pe toată lumea.
Jurnalele fără identificatori de revizie/ → PII nu pot fi investigate incidente și riscuri de conformitate.
Nu există canari/steaguri → eliberarea rupe toată lumea dintr-o dată.
Ignorarea „Retry-After” și a programelor de întreținere a furnizorilor.

16) Lista de verificare pre-vânzare

• Cartografierea schemelor externe → limbajul intern; versiuni și compatibilitate înapoi.
• Identitatea cererilor/cărților web ('operation _ id',' inbox ').
• Timeout, retraiele cu jitter complet, întrerupător de circuit, DLQ și redrive în condiții de siguranță.
• Limitele ratei и corectitudine per chiriaș; respect pentru „Retry-After”.
• mTLS/OAuth/HMAC, rotație secretă, minimizare PII, audit de acces.
• Izolarea regională și rezidența datelor; configs per chiriaș/regiune.
• p95/p99 metrici, eroare de clasă, breaker/429/DLQ-rate; urmărire.
• Sandboxuri și încercări contractuale; canar rollout și phicheflags.
• playbook-uri incidente și de formare de gardă.
• Documentație: SLA, limite, scheme, procese de evoluție.

Concluzie

Adaptoarele furnizorului sunt un scut și un traducător între domeniul dvs. și lumea exterioară. Un ACL puternic cu idempotență, control al erorilor și observabilitate face integrările previzibile, reduce costul schimbării la furnizor și protejează împotriva „eșecurilor în lanț”. "Adaptoarele de design ca componente independente, ușor de gestionat - și "lumea exterioară" va opri ruperea arhitecturii interne.