Адаптери провайдерів

Адаптер провайдера - ізольований шар інтеграції (anti-corruption layer, ACL), який переводить зовнішній контракт постачальника (ігровий провайдер, платіжний шлюз, KYC/AML, ризик-скоринг, нотифікації тощо) у внутрішню доменну мову і назад. Він екранує домен від нестабільних API, мережевих аномалій, еволюцій схем і політик безпеки.

1. Декуплінг: ніякий «сирий» зовнішній payload не потрапляє в ядро.

2. Надійність: керуйте збоями (timeouts, retries, DLQ, circuit breaker).

3. Узгодженість: ідемпотентність, порядок за ключем, транзакційний меседжинг.

4. Експлуатація: метрики, трейсинг, ліміти, пертенантна ізоляція і residency.

1) Зона відповідальності адаптера

Контракти: опис зовнішніх схем/ендпоінтів; маппінг → внутрішні команди/події.
Транспорт: 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>' в запитах; сторім'( op_id → фінальний статус/відповідь)'з TTL.
Webhook de-dup: таблиця'inbox (provider, event_id)'як PK.
Порядок за ключем: серіалізуємо виклики і обробку по'aggregate _ id'( наприклад,'round _ id'або'psp _ tx _ id').
Outbox/Inboxing: транзакційний меседжинг на обох краях конвеєра.

5) Надійність: таймаути, ретраї, circuit breaker

Таймаути: короткі client-side (p95-орієнтовані), окремі для connect/read.
Ретраї: тільки на 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.
Комплаєнс: PCI DSS для PSP, зберігання токенів замість 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. Флап вебхуків: перейти на 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 з ідемпотентністю, контролем помилок і спостережуваністю робить інтеграції передбачуваними, знижує вартість змін у провайдера і захищає від «збоїв по ланцюжку». Проектуйте адаптери як самостійні, керовані компоненти - і ваш «зовнішній світ» перестане ламати внутрішню архітектуру.