Провайдерлер адаптері

Провайдер адаптері - жеткізушінің сыртқы келісімшартын (ойын провайдері, төлем шлюзі, KYC/AML, тәуекел-скоринг, нотификация және т.б.) ішкі домендік тілге және кері аударатын интеграцияның оқшауланған қабаты (anti-corruption layer, ACL). Ол доменді тұрақсыз API, желілік ауытқулар, схемалардың эволюциясы және қауіпсіздік саясаттарынан экрандайды.

1. Декуплинг: ешқандай «шикі» сыртқы payload ядроға түспейді.

2. Сенімділік: ақауларды басқарыңыз (timeouts, retries, DLQ, circuit breaker).

3. Келісімділік: идемпотенттілік, кілт бойынша тәртіп, транзакциялық месседжинг.

4. Пайдалану: метрика, трейсинг, лимиттер, пер-тенанттық оқшаулау және residency.

1) Адаптердің жауапкершілік аймағы

Келісімшарттар: сыртқы схемалардың/эндпоинттердің сипаттамасы; mapping → ішкі командалар/оқиғалар.
Көлік: REST/gRPC/WebSocket/SQS/Kafka/SFTP; қосылымдар пулы, backpressure.
Қауіпсіздік: mTLS, OAuth2, HMAC, кілттер/per tenant/region сертификаттары, құпияларды ротациялау.
Сенімділік: таймауттар, джиттермен ретрайлер, circuit breaker, дедупликация.
Сәйкестігі: 'Idempotency-Key '/' request _ id', жауаптарды/мәртебелерді сақтау.
Байқалуы: SLO метриктері, құрылымдық логтар, трассировка.
Нұсқалау: схемалардың/эндпоинттердің бірнеше нұсқаларын қолдау.
Операциялар: фичефлагтар, канареялық релиздер, құмсалғыштар, сертификаттау.

2) Қайда қолданылады (контекстер мысалдары)

Game/RGS: раундтың басталуы/жабылуы, ставкалар/ұтыстар, сессия белгілері, провайдер мәртебесі.
Payments/PSP: депозиттер/қорытындылар, webhooks мәртебелері, chargeback, 3-D Secure.
KYC/AML: верификация, санкциялық/РЕР-тексерулер, транзакциялар мониторингі.
Risk/Fraud: скоринг, триггерлер, блоктау ұсыныстары.
Comms: e-mail/SMS/push, тарату лимиттері, үлгілер.

Әрбір типтің өз стейт-машинасы бар және SLA-адаптер оны қалыпқа келтіруге міндетті.

3) Келісімшарт және маппинг (ішкі сыртқы)

• Адаптердің ішіне Published Language енгіземіз және провайдердің өрістерін ешқашан сыртқа апармаймыз.
• Барлық хабарларды 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts' алып жүреді.
• Мапперлер арқылы сыртқы схемалардың бірнеше нұсқаларын қолдаймыз.

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) Сенімділік: таймауттар, ретрациялар, circuit breaker

Таймауттар: connect/read үшін жеке қысқа client-side (p95-бағдарлы).
Ретраилер: тек 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).
«Шулы» клиент бюджетті жемеуі үшін 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 ішінде бүркемелеу/редакциялау.
Құпиялар: KMS/HashiCorp Vault, автоматты ротация, оқшаулау per tenant/region.
Комплаенс: 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) Бақылау қабілеті: метрика, логия, трейсинг

• Сыныптар бойынша жетістіктер/қателер (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency әдісі бойынша.
• Rate-limit іске қосылу, breaker, DLQ-rate, redrive-success ашу/жабу.
• Құрылымдық логиндер: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Трейсинг: бірыңғай 'trace _ id', «serialize → send → receive → map → publish», тегтер 'schema _ version', 'region'.

10) Нұсқалау және фичефлагтар

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

11) Плейбуктар (runbooks)

1. Шквал 429/лимиттер: жаһандық троттлингті қосу, 'Retry-After' -ді құрметтеу, терезелерді тенанттар арасында қайта бөлу.
2. Таймауттар өсімі: concurrency азайту, таймауттарды абайлап ұлғайту, breaker ашу, фич деградациясын қосу.
3. Schema mismatch: редрайвды қатыру, сыйысымды мапперді қосу, backfill/репроцессингті орындау.
4. Vebhook флап: pull/reconcile режиміне өту, inbox дедупын қолдану.
5. Провайдердегі инцидент: құмсалғышқа/сақтық DC (бар болса) ауысу, «кейінге қалдырылған» операцияларды белсендіру.

12) Тестілеу

Келісімшарттық тестілер: producer/consumer провайдердің бекітілген фикстураларына қарсы.
Хаос-тесттер: кідірістер, дроптар, out-of-order, телнұсқалар, ішінара жауап беру, қосылыстың үзілуі.
Performance: burst-дәнекерлеудегі стресс; 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)') → маппинг → домендік оқиға 'PaymentAuthorized'.

15) Типтік қателер

«Шикі» сыртқы схеманы доменге сүйрету → қатаң байланыстылық және қымбат көші-қон.
Сәйкессіздік жоқ және inbox/outbox → дубль әсерлері және фантомдық күй.
Ретраи джиттер/лимиттерсіз → дауыл және rate limit бойынша бан.
fairness жоқ жалғыз жаһандық пул → бір тенант барлығын «салады».
PII-редакциясы/сәйкестендіргіші жоқ логтар → инциденттерді және комплаенс қаупін тексеруге болмайды.
Канарейка/жалаушалар жоқ → босату бәрін бірден бұзады.
'Retry-After' және провайдерге қызмет көрсету кестелерін елемеу.

16) Азық-түлік алдындағы чек-парағы

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

Қорытынды

Провайдерлер адаптерлері - бұл домен мен сыртқы әлем арасындағы қалқан мен аудармашы. Демпотенттілігі, қателерді бақылауы және бақылауы бар күшті ACL интеграцияны болжамды етеді, провайдердегі өзгерістердің құнын төмендетеді және «тізбектегі іркілістерден» қорғайды. Адаптерлерді дербес, басқарылатын компоненттер ретінде жобалаңыз - «сыртқы әлеміңіз» ішкі архитектураны бұзуды тоқтатады.