Провайдерлердин адаптерлери

Провайдердин адаптеры - интеграциянын обочолонгон катмары (анти-коррупциялык layer, ACL), ал жеткирүүчүнүн тышкы келишимин (оюн провайдери, төлөм шлюзу, KYC/AML, тобокелдик-скоринг, нотификация ж.б.) ички домен тилине жана кайра которот. Ал туруксуз API, тармактык аномалиялар, схемалар жана коопсуздук саясатынын эволюция домен экраны.

1. Декуплинг: эч кандай "чийки" тышкы payload ядро түшөт.

2. Ишенимдүүлүк: мүчүлүштүктөрдү (timeouts, retries, DLQ, circuit breaker) башкаруу.

3. Шайкештик: идемпотенттүүлүк, ачкыч тартиби, транзакциялык месседжинг.

4. Эксплуатация: метрика, трейсинг, лимиттер, per-tenant изоляция жана residency.

1) Adapter жоопкерчилик аймагы

Келишимдер: тышкы схемалардын/эндпоинттердин сүрөттөлүшү; mapping → ички командалар/окуялар.
Транспорт: REST/gRPC/WebSocket/SQS/Kafka/SFTP; байланыш бассейни, backpressure.
Коопсуздук: mTLS, OAuth2, HMAC, ачкычтар/per tenant/аймак күбөлүктөрү, сырларды айлантуу.
Ишенимдүүлүк: Таймауттар, Джиттер менен ретрациялар, circuit breaker, дедупликация.
Демпотенттик: 'Idempotency-Key '/' request _ id', жоопторду/статустарды сактоо.
Байкоо: SLO метрика, структуралык Логи, жол.
Версиялоо: схемалар/эндпоинттердин бир нече версияларын колдоо.
Операциялар: физикалык фонддор, канареалык релиздер, кумдуктар, сертификация.

2) Кайда колдонулат (контексттердин мисалдары)

Game/RGS: раунддун башталышы/жабылышы, коюмдар/утуштар, сессиялардын токендери, провайдердин статустары.
Payments/PSP: депозиттер/корутундулар, webhooks статусу, chargeback, 3-D Secure.
KYC/AML: текшерүү, уруксат/RER-текшерүү, бүтүмдөрдү мониторинг.
Тобокелдик/Fraud: эсеби, триггерлер, бөгөт коюу сунуштар.
Comms: электрондук почта/SMS/push, почта чеги, шаблондор.

Ар бир түрү окуялар жана SLA өзүнүн мамлекеттик машина бар - адаптер аны нормалдаштырууга милдеттүү.

3) Келишим жана mapping (ички тышкы)

• Адаптердин ичине Published Language киргизип, провайдердин талаасын эч качан сүйрөбөйбүз.
• Бардык билдирүүлөр 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts' болуп саналат.
• Биз 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) Идемпотенттүүлүк жана тартип

Request de-dup: 'Idempotency-Key: <operation_id>' суроо-талап; storim '(op_id → акыркы абалы/жооп)' менен TTL.
Webhook de-dup: стол 'inbox (provider, event_id)' катары PK.
Ачкыч тартиби: 'aggregate _ id' (мисалы, 'round _ id' же 'psp _ tx _ id') боюнча чалууларды жана дарылоону сериалдаштыруу.
Outbox/Inboxing: конвейердин эки четинде транзакциялык билдирүү.

5) Ишенимдүүлүк: Таймауттар, Retrailer, circuit breaker

Таймауттар: кыска client-side (p95-багытталган), connect/окуу үчүн өзүнчө.
Retrains: гана retryable (5xx/timeout/429), экспоненциалдуу backoff + full jitter, аракет чеги жана жалпы мөөнөтү.
Circuit Breaker: каталар/жашыруун көбөйгөндө ачуу; graceful degradation (мисалы, экинчи даражадагы RGS чүчүкулак өчүрүү, койду "натыйжасы күтүү").
DLQ: бай мета-маалымат менен "уулуу" билдирүүлөр, коопсуз редрайв.

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, квота, атаандаштык

Провайдердин чектөөлөрүн сактаңыз (RPS, burst, concurency).
"Ызы-чуу" кардар бюджетти жеп эмес, ошондуктан per-tenant WFQ/DRR (fairness) ишке ашыруу.
урмат 'Retry-After '/' X-RateLimit-' аталыштары.
Ички кезек + продюсер боюнча backpressure.

7) Коопсуздук жана шайкештик

Транспорт: mTLS, TLS 1. 2 +, актуалдуу cipher suites, pinning күбөлүктөр мүмкүн.
Аутентификация: OAuth2 client-credentials/MTLS, HMAC (кол коюлган хэш орган + timestamp), API ачкычтары.
PII-минималдаштыруу: гана зарыл талаалар; блогдордо жана DLQ маскировка/өзгөртүүлөр.
Secrets: KMS/HashiCorp Vault, автоматтык айлануу, изоляция per tenant/аймак.
Комплаенс: PSP үчүн PCI DSS, PAN ордуна токендерди сактоо, GDPR/жергиликтүү маалымат мыйзамдары.

8) Көп-тенант жана көп-аймак

Тенантага/аймакка ачкычтарды/пункттарды конфигурациялоо.
Data residency: Чакырыктар "үй" аймагынан жасалат; кросс-аймак - агрегаттар гана.
Изоляция: өз байланыш пулдары жана 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) Байкоо: метрика, Логи, Trace

• Класстар боюнча ийгиликтер/каталар (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency ыкмасы боюнча.
• Rate-чектөө, ачуу/жабуу breaker, DLQ-rate, redrive-success.
• Структуралык логиндер: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Trace: бирдиктүү 'trace _ id', уктап "serialize → send → receive → map → publish", tags 'schema _ version', 'region'.

10) Версиялоо жана физикалык

v1/v2 тышкы келишимди параллелдүү колдоо; миграция - канареалык/тенанттар боюнча.
Провайдердин ар кандай жаңы өзгөчөлүгү - желектин артында; релизи жок которуу.
Эволюция келишими: additive-first, схемалардын катуу валидациясы (JSON Schema/Proto).

11) Playbooks (runbooks)

1. Scroll 429/чеги: Global Trottling кирет, урматтоо 'Retry-After', Тенанттар ортосунда терезелерди бөлүштүрүү.
2. Таймауттардын өсүшү: concurrency азайтуу, таймауттарды кылдаттык менен көбөйтүү, breaker ачуу, phich деградациясын күйгүзүү.
3. Shema mismatch: redrave тоңдуруп, шайкеш mapper күйгүзүү, backfill/репроцессинг жүргүзүү.
4. Flap Webhook: pull/reconcile режимине өтүү, inbox дедуп колдонуу.
5. Провайдердин окуясы: кум салгычка/резервдик DCге өтүү (бар болсо), "кийинкиге калтырылган" операцияларды активдештирүү.

12) сыноо

Контракттык тесттер: producer/consumer vs белгиленген сунуштоочу фикстуралар.
Башаламандык-тесттер: кечигүүлөр, тамчылар, out-of-order, дубликаттар, жарым-жартылай жооп, байланыш үзүлүшү.
Performance: бурст-спайк боюнча стресс; p95/p99 өлчөө, breaker жүрүм-туруму.
Окшоштук: окшош 'operation _ id' кайталоо кошумча эффекттерди жаратпайт.
E2E: happy-path/chargeback/талаш-тартыштар/жокко чыгаруу/рекальк.

13) Ишке ашыруу параметрлери (deployment patterns)

Өзүнчө кызмат адаптер: + изоляция, көз карандысыз релиздер; − кошумча тармак.
Sidecar/плагин: + чалуу жайгашкан жери; − кыйын нускасын башкаруу.
Китепкана: + жөн гана киргизүү; − жогорку coupling жана ар түрдүү нускалары.

Сунуш: так API жана анын релиз айлампасы менен кызмат адаптер.

14) Мисал API адаптер (псевдо)

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

• Вебхук с 'provider _ event _ id' → 'inbox' (PK на '(provider,event_id)') → mapping → домен окуясы 'PaymentAuthorized'.

15) типтүү каталар

"Чийки" тышкы схеманы доменге сүйрөп → катуу байланыш жана кымбат миграция.
Эч кандай демпотенттик жана inbox/outbox → дубль эффекттери жана фантомдук шарттар.
Jitter/чеги жок Retrais → бороон-чапкын жана тыюу rate limit.
fairness жок жалгыз глобалдык бассейн → бир тенант баарын "салат".
PII редакторлору/идентификаторлору жок Логи → инциденттерди жана комплаенс коркунучун иликтөө мүмкүн эмес.
Эч кандай канарейка/желектер → релиз бир эле учурда баарын бузат.
"Retry-After" жана кызмат көрсөтүүчүнүн тартиби четке кагуу.

16) Азык-түлүктүн алдындагы чек-тизме

• Mapping тышкы схемалар → ички тил; версиялары жана тескери шайкештиги.
• Суроо-талаптардын/вебхуктардын аныктыгы ('operation _ id', 'inbox').
• Таймауттар, full-jitter, circuit breaker, DLQ жана коопсуз редрайв менен retrains.
• Rate limits и fairness per tenant; урмат 'Retry-After'.
• mTLS/OAuth/HMAC, сырларды айлантуу, PII-минималдаштыруу, кирүү аудити.
• Аймактык изоляция жана data residency; конфиги per tenant/region.
• Метрика p95/p99, ката класстары, breaker/429/DLQ-rate; Trace.
• Sandbox жана келишим тесттер; канар rollout жана phicheflags.
• Playbook окуялар жана окутуу on-call.
• Документация: SLA, лимиттер, схемалар, эволюция процесстери.

Корутунду

Провайдерлердин адаптерлери - бул сиздин домен менен тышкы дүйнөнүн ортосундагы калкан жана котормочу. Демпотенттик, каталарды көзөмөлдөө жана байкоо менен күчтүү ACL интеграцияны алдын ала айтууга болот, провайдердин өзгөрүү баасын төмөндөтөт жана "чынжыр үзгүлтүктөрүнөн" коргойт. Адаптерлерди өз алдынча, башкарылуучу компоненттер катары долбоорлоо - жана сиздин "тышкы дүйнөңүз" ички архитектураны бузууну токтотот.