Üpjün ediji adapterleri

Üpjün edijiniň adapteri - üpjün edijiniň daşarky şertnamasyny (oýun üpjün edijisi, töleg şlýuzy, KYC/AML, töwekgelçilik-skoring, bellikler we ş.m.) içerki domen diline we tersine geçirýän izolirlenen integrasiýa gatlagy (anti-corruption layer, ACL). Durnuksyz API-lerden, tor anomaliýalaryndan, shemalaryň ewolýusiýalaryndan we howpsuzlyk syýasatlaryndan domeni ekranlaşdyrýar.

1. Dekupling: hiç bir "çig" daşarky töleg ýadro girmeýär.

2. Ygtybarlylyk: şowsuzlyklary dolandyryň (timeouts, retries, DLQ, circuit breaker).

3. Ylalaşyklylyk: idempotentlik, açar boýunça tertip, geleşik habarnamasy.

4. Ekspluatasiýa: metrikler, treýsing, çäkler, per-tenant izolýasiýa we residency.

1) Adapteriň jogapkärçilik zolagy

Şertnamalar: daşarky shemalaryň/endpointleriň beýany; mapping → içerki buýruklar/wakalar.
Ulag: REST/gRPC/WebSocket/SQS/Kafka/SFTP; Baglanyşyk howuzy, backpressure.
Howpsuzlyk: mTLS, OAuth2, HMAC, açarlar/per tenant/region şahadatnamalary, syrlaryň aýlanmagy.
Ygtybarlylygy: Taýmautlar, jitter bilen retrailer, circuit breaker, de-duplikasiýa.
Idempotentlik: 'Idempotency-Key '/' request _ id', jogaplary/statuslary saklamak.
Syn edilişi: SLO metrikleri, gurluş ýazgylary, ýollar.
Wersiýalaşdyrmak: shemalaryň/endpointleriň birnäçe wersiýalaryny goldamak.
Amallar: fiçeflaglar, kanareýa relizleri, sandyk gutulary, sertifikatlaşdyrmak.

2) Nirede ulanylýar (kontekstleriň mysallary)

Game/RGS: tapgyryň başlamagy/ýapylmagy, jedeller/ýeňişler, sessiýanyň bellikleri, üpjün edijiniň statusy.
Payments/PSP: depozitler/netijeler, webhooks statuslary, chargeback, 3-D Secure.
KYC/AML: tassyklamalar, sanksiýalar/RER-barlaglar, amallara gözegçilik.
Töwekgelçilik/Fraud: skoring, triggerler, blokirleme teklipleri.
Comms: e-mail/SMS/push, poçta çäkleri, şablonlar.

Her bir görnüşiň wakalaryň öz döwlet maşyny bar we SLA - adapter ony kadalaşdyrmaga borçludyr.

3) Şertnama we mapping (içerki daşarky)

• Adapteriň içinde "Published Language" -ni girizýäris we hiç haçan üpjün edijiniň meýdanyndan çykarmaýarys.
• Ähli habarlarda 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts' bar.
• Mapperler arkaly daşarky shemalaryň birnäçe wersiýasyny goldaýarys.

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) Idempotentlik we tertip

Request de-dup: 'Idempotency-Key: <operation_id>' soraglarda; storim '(op_id → soňky status/jogap)' TTL bilen.
Webhook de-dup: tablisa 'inbox (provider, event_id)' PK hökmünde.
Açar tertibi: 'aggregate _ id' (mysal üçin 'round _ id' ýa-da 'psp _ tx _ id') boýunça çagyryşlary seriýalaýarys.
Outbox/Inboxing: konweýeriň iki gyrasynda geleşik habarnamasy.

5) Ygtybarlylyk: wagt, retrailer, circuit breaker

Wagtlar: connect/read üçin aýratyn gysga client-side (p95-ugrukdyrylan).
Retrailer: diňe retryable (5xx/timeout/429), eksponensial backoff + full jitter, synanyşyk çäkleri we umumy möhlet.
Circuit Breaker: ýalňyşlyklar/gizlinlik ýokarlananda açmak; graceful degradation (mysal üçin, ikinji derejeli RGS çiplerini öçürmek, netijä garaşmak).
DLQ: baý meta-maglumatlary bolan "zäherli" habarlar, howpsuz redaktirleme.

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, kwotalar, bäsdeşlik ukyby

Üpjün edijiniň çäklendirmelerini berjaý ediň (RPS, burst, concurency).
"Şowhunly" müşderi býudjetini iýmezligi üçin WFQ/DRR (fairness) per-tenant amala aşyryň.
'Retry-After '/' X-RateLimit-' sözbaşylaryna hormat goýuň.
Önümçide içerki nobatlar + backpressure.

7) Howpsuzlyk we laýyklyk

Ulag: mTLS, TLS 1. 2 +, degişli cipher suites, pinning şahadatnamalary mümkin boldugyça.
Autentication: OAuth2 client-credentials/MTLS, HMAC (gol çekilen beden heşleri + timestamp), API açarlary.
PII-minimallaşdyrmak: diňe zerur meýdanlar; bloglarda we DLQ-de gizlemek/redaktirlemek.
Syrlar: KMS/HashiCorp Vault, awtomatiki aýlanma, izolýasiýa per tenant/region.
Gabat gelmek: PSP üçin PCI DSS, PAN, GDPR ýerine bellikleri saklamak/ýerli maglumat kanunlary.

8) Köp tenant we köp sebit

Tenant/sebit üçin açar/bölek konfigurasiýasy.
Data residency: jaňlar "öý" sebitinden edilýär; kross-sebit - diňe agregatlar.
Izolýasiýa: birikmeleriň öz howuzlary we per tenant çäkleri.

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) Syn edilişi: metrikler, loglar, treýsing

• Synplar boýunça üstünlikler/ýalňyşlyklar (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency usuly boýunça.
• Rate-limit, açmak/ýapmak breaker, DLQ-rate, redrive-success.
• Gurluş loglary: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Trace: bir 'trace _ id', "serialize → send → receive → map → publish", bellikler 'schema _ version', 'region'.

10) Wersiýalaşdyrmak we fiçeflaglar

Daşarky şertnamany paralel v1/v2 saklaň; göçmek - kanar/tenantlar boýunça.
Üpjün edijiniň islendik täze pikiri - baýdagyň aňyrsynda; goýberilmezden geçiş.
Ewolýusiýa şertnamasy: additive-first, shemalaryň berk tassyklamasy (JSON Schema/Proto).

11) Oýun kitaplary (runbooks)

1. Galkynyş 429/çäkleri: global trottling, 'Retry-After' -e hormat goýmak, penjireleri tenantlaryň arasynda paýlamak.
2. Wagtlaryň ösüşi: concurrency azaltmak, wagtlary seresaplylyk bilen köpeltmek, breaker açmak, fiçiň zaýalanmagyny açmak.
3. Shema mismatch: redrave doňdurmak, gabat gelýän mapperi açmak, backfill/gaýtadan işlemek.
4. Vebhuk Fap: pull/reconcile re modeime geçmek, inbox-dedupy ulanmak.
5. Üpjün edijide bolan waka: gum gutusyna/ätiýaçlyk DC (bar bolsa) geçiň, "gijikdirilen" amallary işjeňleşdiriň.

12) Synag

Şertnama synaglary: üpjün edijiniň kesgitlenen fiksturalaryna garşy producer/consumer.
Bulam-bujarlyk synaglary: gijikdirmeler, damjalar, out-of-order, dublikatlar, bölekleýin jogap, baglanyşygyň kesilmegi.
Performance: burst-spike stres; ölçemek p95/p99, breaker özüni alyp barşy.
Idempotentlik: birmeňzeş 'operation _ id' -iň gaýtalanmagy goşmaça täsir döretmeýär.
E2E gutularda: happy-path/chargeback/jedeller/ýatyryş/rekalk ssenarileri.

13) Amala aşyrmagyň wariantlary (deployment patterns)

Aýry-aýry hyzmat adapteri: + izolýasiýa, garaşsyz neşirler; − goşmaça ulgam.
Sidecar/plugin: + jaňlaryň lokalizasiýasy; − wersiýalaryny dolandyrmak has kyn.
Kitaphana: Diňe guruň; − ýokary we dürli görnüşler.

Maslahat: takyk API we öz goýberiş aýlawy bolan hyzmat adapteri.

14) API adapteriniň mysaly (psevdo)

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"
}

• Webhuk 'provider _ event _ id' → 'inbox' (PK on '(provider,event_id)') → mapping → domen olayı 'PaymentAuthorized'.

15) Adaty ýalňyşlyklar

"Çig" daşarky shemany domene süýremek → berk baglanyşyk we gymmat göçmek.
Yhlas ýoklugy we inbox/outbox → iki effektli we fantom ýagdaýlary.
Jittersiz/çäksiz retraýlar → rate limit boýunça tupan we ban.
Fairness bolmadyk ýeke-täk global howuz → bir tenant hemmäni "goýýar".
PII redaksiýasy/kesgitleýjileri bolmadyk loglar → hadysalary we gabat gelmek töwekgelçiligini derňemeli däldir.
Kanareýalar/baýdaklar ýok → goýbermek hemmeleri birbada döwýär.
'Retry-After' we üpjün edijiniň hyzmat meýilnamalaryna üns bermezlik.

16) Azyk önüminden öň çek-sanawy

• Daşarky shemalar → içki dil; wersiýalary we ters laýyklyk.
• Soraglaryň/webhuklaryň deňligi ('operation _ id', 'inbox').
• Wagt, full-jitter, circuit breaker, DLQ we ygtybarly redaktirleme bilen retrauslar.
• Rate limits и fairness per tenant; hormat 'Retry-After'.
• mTLS/OAuth/HMAC, gizlin aýlanyş, PII-minimallaşdyrmak, giriş barlagy.
• Sebitleýin izolýasiýa we data residency; konfigi per tenant/region.
• p95/p99 metrleri, synplar boýunça ýalňyşlyk, breaker/429/DLQ-rate; söwda.
• Sandyk gutulary we şertnama synaglary; kanar rollout we fiçeflaglar.
• Wakalaryň oýun kitaplary we on-call okuw.
• Resminamalar: SLA, çäkler, shemalar, ewolýusiýa prosesleri.

Netije

Üpjün edijileriň adapterleri, domeniňiz bilen daşarky dünýäniň arasyndaky galkan we terjimeçidir. Yhlas, ýalňyşlyklara gözegçilik we gözegçilik bilen güýçli ACL integrasiýany öňünden aýdyp bolýar, üpjün edijiniň üýtgemeginiň bahasyny peseldýär we "zynjyryň kesilmeginden" goraýar. Adapterleri özbaşdak, dolandyrylýan komponentler hökmünde dizaýn ediň we "daşarky dünýäňiz" içerki arhitekturany bozmagy bes eder.