Общие протоколы взаимодействия

1) Зачем экосистеме единые протоколы

Экосистема состоит из операторов, студий/RGS, агрегаторов, PSP/APM, KYC/AML-провайдеров, аффилиатов и аналитических сервисов. Общие протоколы взаимодействия исключают «зоопарк» интеграций, ускоряют онбординг, снижают стоимость поддержки и риски инцидентов, а еще — обеспечивают совместимость при масштабировании (горизонтальном, вертикальном и диагональном).

Цели: совместимость «из коробки», предсказуемые SLO, безопасность данных, воспроизводимые миграции.

2) Слой транспорта и форматы

HTTP/2/3, gRPC — для синхронных API с низкой латентностью; WebSocket — для потоковых событий/лидербордов; WebRTC (SRTP/QUIC) — для аудио/видео лайв-контента.

• JSON — внешние B2B API и вебхуки (читаемость).
• Protobuf/Avro — внутренняя шина/глубокие интеграции (сжатие/эволюция схем).
• Сжатие/биндинг: gzip/br для JSON; zstd для Protobuf/Avro.
• Локаль/время: ISO-8601 в UTC, суммы — в минимальных денежных единицах (integer).

3) Аутентификация, авторизация, доверие

OAuth2/OIDC для клиентских/партнерских приложений (short-lived токены, PKCE, scopes).
mTLS для S2S между доверенными зонами; JWS/HMAC — подпись запросов и вебхуков.
RBAC/ABAC: роли и атрибуты (юрисдикция, тенант, риск-уровень).
Ключи и ротация: KMS/Vault, короткий срок жизни, автоматическая ротация (в т.ч. JWKS).
Egress-контроль, allow-list доменов и ASN, DNSSEC/DoT/DoH в чувствительных зонах.
Tenant isolation: per-tenant ключи, квоты, лимиты, namespace-ы в шине.

4) Контракты API (REST/gRPC) — каноника

Версионирование: `/v{n}` в URI для REST; `package.vN` для gRPC. Minor-эволюция — безломная; breaking-изменения — через новую major. Депрекация по политике (см. §12).
Идемпотентность: `Idempotency-Key` на POST/PUT/PATCH денежных/критичных операций; сохранение на N часов.
Пагинация: курсоры (`nextPageToken`), не `offset/limit`; консистентные сортировки.
Лимиты: `429 Too Many Requests` + заголовки квот (`X-RateLimit-`), джиттер в ретраях.
Ошибки: машиночитаемые коды/подкоды, `correlationId`, карта полей валидации.
Таймауты и ретраи: экспоненциальная задержка + джиттер; не ретраить небезопасные ошибки.
Политика совместимости: неизменность смысла полей; новые поля — опциональны.

5) Событийная модель и шина (EDA)

Регистратор схем (Schema Registry): контракт на каждое событие, эволюция с backward-совместимостью.

• `click`, `session`, `bet`/`spin`, `round_start`/`round_result`,
• `deposit`/`withdrawal`, `psp_auth`, `kyc_status`, `fraud_signal`,
• `reward_granted`, `leaderboard_update`, `feature_toggle`.
• Ключи партиций: `playerId`, `campaignId`, `tableId`, `operatorId` (выбор по домену).
• Доставка: at-least-once c бизнес-идемпотентностью; для денежных итогов — сага/txn-outbox.
• Порядок: «гарантированный порядок внутри ключа», кросс-ключи — через оркестрацию.
• Семантика времени: `eventTime` + `ingestTime`; дедуп по `(eventId|idempotencyKey)`.

6) Вебхуки и гарантии доставки

Подпись: JWS/HMAC с `t` (timestamp) и `kid`, проверка окна ±5 минут, воспроигрываемость запрещена.
Ретраи: backoff с джиттером до T минут, фиксация попыток, переотправка только при 5xx/timeout.
Идемпотентность: `eventId` + подпись тела; обработка «по крайней мере один раз».
Реестр событий вебхуков: повторная выборка истории при рассинхронизации.
Безопасность: mTLS по мере возможности, allow-list IP/ASN, CSRF не применим к серверным колбэкам.

7) Данные и приватность (Privacy-by-Design)

PII-минимизация: токенизация идентификаторов (`playerId` псевдонимизируется), разделение доменов данных.
Контракты данных: DPA/DPIA, цели, сроки хранения, трансграничные потоки (Whitelist стран).
Политики аудита/линейджа: кто/когда/зачем; неизменяемые логи (WORM).
Правила RG/этики: запрет агрессивных офферов для уязвимых сегментов; четкая правовая база.

8) Согласованность и транзакции

Сильная консистентность — кошелек/балансы/выплаты.
Eventual — витрины, лидерборды, телеметрия.
Саги для распределенных бизнес-транзакций; компенсации для отмен.
Exactly-once по бизнес-смыслу: идемпотентные ключи и детерминированные обработчики.

9) Наблюдаемость и SLO

Трейсинг: сквозной `traceId` от клика/вебхука до выплаты/награды; propagation (`W3C traceparent`).
Метрики: p50/p95/p99 API, лаг брокера, CR платежей/KYC, лидерборды E2E.
Логи: структурированные, без ПДн; маскирование токенов/ключей.
SLO-листы: логин p95 ≤ 300–500 мс; депозит p95 ≤ 1.5–2.0 с; ставка/спин p95 ≤ 150–250 мс; доставка событий ≥ 99.9%.

10) Производительность, квоты, защита от шторма

Rate limiting (token/leaky bucket) на L7 и в меш-политиках.
Backpressure: очереди перед хрупкими апстримами (PSP/KYC).
Outlier-ejection: автоматическое «охлаждение» нестабильных бэкендов.
Circuit-breaker: закрытие потока при превышении порогов ошибок/латентности.
Fair-share: квоты по тенанту/каналу/региону; приоритет критичных доменов.

11) Совместимость SDK и тест-критерии

SDK-набор: HTTP/gRPC клиенты, подпись запросов, ретраи с джиттером, идемпотентность, курсоры.
Контрактные тесты: Postman/Newman/gRPC-conformance, симуляторы PSP/KYC/студий.
Матрица совместимости: версии API/SDK, поддерживаемые схемы, политики депрекации.
Синтетика: генераторы событий и транзакций, «черные ящики» 24/7 для мониторинга.

12) Версионирование и депрекации (Change Management)

Major-релизы раз в N месяцев, с параллельным окном ≥ 6–12 мес.
Minor-изменения — добавление опциональных полей/методов безломно.
Депрекация: анонс → предупреждения в заголовках/ответах → флаг в метриках → выключение по плану.
Миграции схем событий: стратегия «расширения» (add-only) + прокси-адаптеры на границах.

13) Безопасность протоколов

Zero Trust: mTLS везде, короткоживущие креды, принципы наименьших привилегий.
Секрет-скоупы: разделение ключей чтения/записи/администрирования.
Защита от повторов: nonce/временное окно в подписях; запрет переиспользования.
WAF/бот-фильтры: защита от скрейпинга/клик-фрода; низкий false positive.
Вендор-зоны: микросегментация, отдельные VPC/namespace-ы, egress-allow-list.

14) Инциденты и DR

War-room-процедуры: стоп-кнопка для доменов (контент/PSP/KYC), RACI, SLA на трейс-пакет.
DR-сценарии: актив-актив входные точки (Anycast/GSLB), cut-over ≤ 60–90 с, ежеквартальные учения.
RCA: шаблоны без поиска виноватых, связь L3↔L7, апдейты в протокол/SDK/Runbook.

15) Метрики успеха протоколов

Совместимость: доля партнеров, прошедших conformance-тесты; время онбординга (TTO).
Надежность: uptime интеграций, p95 API/шины, доля успешных вебхуков.
Безопасность: инциденты ПДн=0, время ротации ключей, доля mTLS-трафика.
Экономика: cost per rps/txn/event, снижение Cost-to-Serve, время миграций.
Продукт: FTD/ARPU/LTV uplift от стандартизации (меньше протечек KYC/платежей).

16) Анти-паттерны

«Свободная форма» событий: отсутствие схем и версий → разъезд витрин и аналитики.
Единый L7-шлюз без N+1: SPOF и узкое горло для вебхуков/PSP.
Ретраи без лимитов/джиттера: трафик-шторм, дубль транзакций.
Сырые ПДн в обмене: без токенизации/DPIA → регуляторные риски.
Offset-пагинация: пропуски/дубликаты под нагрузкой.
Секреты «навсегда» и статические IP без egress-контроля.
Breaking-изменения без параллельного окна и адаптеров.

17) Чек-лист внедрения

1. Принять канонику API (версионирование, идемпотентность, пагинация, ошибки).
2. Ввести Schema Registry и доменную карту топиков/ключей партиций.
3. Обязать mTLS + JWS/HMAC для S2S и вебхуков; автоматизировать ротацию ключей/JWKS.
4. Настроить лимиты/ретраи/CB/outlier-ejection и квоты per-tenant.
5. Развернуть трейсинг/метрики/логи с единым `traceId`; утвердить SLO-листы.
6. Подписать DPA/DPIA, включить токенизацию и политики хранения/удаления.
7. Создать SDK и conformance-набор; зафиксировать политику депрекации.
8. Провести DR/chaos-учения и war-room-ритуалы; «черный старт» на минимальном наборе.
9. Внедрить каталог протоколов (портал партнера): спек, примеры, симуляторы, песочница.

18) Дорожная карта эволюции

v1 (Foundation): каноника REST/gRPC, базовые схемы событий, подписи вебхуков, mTLS.
v2 (Integration): конвейер миграций, conformance-тесты, SDK, rule-engine для квот/ретраев.
v3 (Automation): автодозирование по SLI, self-service песочницы/симуляторы, адаптеры между версиями.
v4 (Networked Governance): межпартнерский комитет протоколов, общие SLO/кредиты/пенальти, совместные PoP/edge-политики.

Краткое резюме

Общие протоколы взаимодействия — это «язык» экосистемы: единые контракты API и событий, строгая безопасность (mTLS/JWS), идемпотентность и гарантии доставки, наблюдаемость и SLO, управляемые миграции и DR. Следуя канонике, участники быстрее онбордятся, реже падают, проще масштабируются и предсказуемо растут — при соблюдении приватности и требований юрисдикций.