REST, gRPC және iGaming веб-хактар: үлгілер және анти-үлгілер

Мақаланың толық мәтіні

💡 18+. Азық-түлік және инженерлік командалар үшін техникалық материал iGaming. Ойынға шақыру емес. «Платформа» дегеніміз PAM/әмиян/касса/бонустар/RG. «Провайдер» - RGS/live/джекпоттар/агрегаторлар.

1) Хаттамалар картасы: кім не үшін жауап береді

REST - HTTP/JSON бойынша әмбебап синхронды сұраулар. Мөлдір кэш, қарапайым жөндеу, B2B интеграциясы және әкімшілік-API үшін ыңғайлы.

gRPC - HTTP/2 үстінен жоғары өнімді екілік RPC: төмен жасырындылық, ағындар, қатаң схемалар. Ыстық ақша жолдары (wallet/settle), ішкі сервистер және ұзақ өмір сүретін ағымдар (live) үшін жақсы.

Вебхактар - алушыдан жіберушіге кері қоңыраулар (callback). Оқиғалар үшін пайдаланылады («ақша түсті», «лимит жұмыс істеді»), онда бастамашы әрқашан нәтижені күткен адам емес.

Алтын ереже:

Ақша синхронды RPC (REST/gRPC) бойынша жүреді. Телеметрия және бизнес-оқиғалар - асинхронды (вебхактар + оқиғалар шинасы).

2) Үлгілік жолдар және ұсынылған арналар

Жол	Ұсынылған	Неге
`bets. authorize` (hold)	gRPC (ішкі )/REST (B2B)	минималды жасырындылық, қатаң SLA
`bets. settle` → `wallet. credit`	gRPC синхронды + шина оқиғасы	ақша = ACID; оқиғалар = байқалушылық
`cashier. deposit/withdraw`	REST + сәйкестік	PSP интеграциясы, трейсинг
`RG check / stop`	gRPC/REST синхронды	тоқтату сигналдары бір сәтте іске қосылуы тиіс
`bonus. issue/consume`	REST синхронды	бизнес-логика, қалыпты SLA
`jackpot. trigger/payout`	gRPC/REST + оқиға	ақша келісімшарты + аудит
Телеметрия, аналитика, аллергия	Вебхактар + шина (Kafka/Pulsar)	тұрақтылық пен ауқым
Live статусы/каталогтары	gRPC streaming / Server-Sent Events	сауалнамалар мен лагтарды барынша азайту

3) Келісімшарт-бағытталған дизайн

3. 1 REST (үзіктер)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1, X-Trace-Id: tr_a1b2
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

Қателер (бірыңғай схема):


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

3. 2 gRPC (protobuf, жеңілдетілген)

proto syntax = "proto3";
package wallet. v1;

message Money { int64 minor_units = 1; string currency = 2; } // cents message AuthorizeBetReq { string session_id=1; string bet_id=2; string round_id=3; Money amount=4; string idempotency_key=5; }
message AuthorizeBetRes { string status=1; string hold_id=2; }

service Wallet {
rpc AuthorizeBet(AuthorizeBetReq) returns (AuthorizeBetRes);
rpc SettleBet(SettleReq) returns (SettleRes);
}

3. 3 Вебхактар (жазылым үлгісі)


POST https://provider. example/webhooks
{
"topic":"wallet. credit. ok",  "callback_url":"https://rgs. example/journal",  "secret":"", "version":"1. 2"
}

Жеткізу:


POST https://rgs. example/journal
Headers: X-Signature: sha256=..., X-Trace-Id: tr_a1b2
{
"event_type":"wallet. credit. ok",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "payload":{"player_id":"p_19f3","amount":{"minor_units":1460,"currency":"EUR"}}
}

4) Үйлесімділік және келісімділік

Write-операцияларында әрқашан 'X-Idempotency-Key' (REST/gRPC metadata) талап етіңіз. Қайталау → сол жауап.

Кілттің композициясы бизнес параметрлеріне байланыстырылған (мысалы, 'bet _ id + amount').

Ұзақ процестерге арналған сағалар (authorize → commit/lock → settle → credit).

Outbox/CDC: оқиғалар транзакцияның жанында атомарлық түрде тіркеледі және сырттан жарияланады.

5) Нұсқалау және үйлесімділік

REST - '/v1/... '+' Deprecation/Sunset '- тұтқалар; gRPC — `package wallet. v1`; оқиғалар - 'schema _ version' денелерде + схемалар тізілімі.

SemVer: minor - optional өрістері/жаңа endpoints; major - жаңа жол/пакет, көші-қон оқиғаларының «қос хаты».

major-нұсқасыз ақша мәртебесінің семантикасын ешқашан өзгертпеңіз.

6) Көлік қауіпсіздігі

mTLS барлық S2S; вебхуктер үшін - дененің қолы (HMAC/EdDSA) + timestamp және дәлдік терезелері.

Сатып алуды шектеу (OAuth2 CC) және per brand/region кілттерін сегменттеу.

Zero-trust: желілік саясаткерлер, қысқа мерзімді токендер, Vault/HSM, WORM-сыни әрекеттердің аудиті.

7) Бақылау және SLO

Өтпелі 'trace _ id' REST, gRPC metadata және вебхуктарда.

Метриктер: p50/p95/p99 latency, error rate кодтары бойынша, throughput, lag кезектер.

SLO-минимум (бағдарлар):

Wallet p95 '<150 мс' (Authorize/Settle), REST көпшілік B2B p95 '<300 мс', Вебхактар жеткізілді '<5 мин' 99-шы перцентиль, «Жоғалған/қайталанған сеттлменттер» = 0.

8) Ретраи, backoff және жеткізу тәртібі

REST/gRPC: экспоненциалды backoff, джиттер, ұзақтық шегі (deadline/timeout).

Вебхактар: '2xx' дейін қайталап жеткізу; ('player _ id/round _ id') кілті бойынша тәртіпті сақтау немесе қабылдағышта дедупликация.

Анти-дауылдар: параллель ретрайлардың лимиті, circuit breaker, rate limit.

9) Интеграция паттерндері

Паттерн А: «Ақша синхронды, оқиғалар асинхронды»

1. RGS → Wallet (gRPC/REST) `authorize` → `settle/credit`.

2. Параллель жарияланады 'bet. settled ', ал провайдер вебхук түбіртегін алады.

Оған қоса: жылдам ақша, бақылау. Минус: екі контур керек.

B үлгісі: «Streaming live»

gRPC streaming арқылы Live Bridge өзегі (үстел күйі, үстел терезесі).

Ақша операциялары - жеке unary RPC; оқиғалар - шинаға/вебхокке.

Плюс: тірі мәртебелердің ең аз кідіруі.

C үлгісі: «B2B көпшілік REST»

Каталогтар/бонустар/аффилиаттар/есептер - cursor-pagination, сүзгілер, ETag бар REST.

Плюс: серіктестердің қарапайым интеграциясы.

10) Қарсы үлгілер (қызыл жалаулар)

Ақша операциялары тек вебхактар арқылы (синхронды растаусыз).

Жоқ 'Idempotency-Key' → екі дебет/кредит.

Оқиғаларды outbox/CDC тексеріп шығу арқылы жариялау (оқиғалар жоғалады).

Қолтаңбасы/уақытша белгісі жоқ вебхактар → алмастыру.

Бір арнада әр түрлі өңірлердің PII/ақшаларын 'region/tenant' тегінсіз араластыру.

Вебхуктардағы үлкен binary payload (ретрациялар мен лимиттерді бұзады).

Нөлдік деградация: веб-хуктардың құлдырауы ақшаны есептеуге кедергі келтіреді.

gRPC deadline жоқ және backoff жоқ - байланысқан қосылыстар, ресурстардың таусылуы.

11) Чек парақтары

Сәулетші/платформа

gRPC/REST бойынша ақша, оқиғалар - вебхукилер/шина.
Барлық ақша жолдарында Outbox/CDC.
`/vN` и schema registry; Deprecation/Sunset процесі.
mTLS + вебхук қолтаңбалары; per brand/region секректері.
SLO-дашбордтар p95/p99, error rate, webhook-lag.
DR/xaoc-жаттығулар: дубль-жеткізу, out-of-order, аймақтың үйіндісі.

Провайдер/RGS

Жіберемін 'X-Trace-Id' және 'X-Idempotency-Key'.
Ретраи backoff және дедупликациясы бар; вебхуктарды қайта жеткізуге дайын.
Келісімшарттардың нұсқаларын жаңартамын; «Deprecation/Sunset» дегенге жауап беремін.
Қателер мен уақыт кодтары бойынша логтар/метриктер.

12) Өткір кейстерге арналған шағын шешімдер

Safari/ITP және third-party шектеулері: ақша - хостта (REST/gRPC), iFrame-контент 'postMessage' арқылы қатынасады; iFrame емес, хосттың вебхуттары.

Мультибренд: тақырыптар мен оқиғалардағы 'tenant _ id/brand _ id/license' тегтері; кілттер/сертификаттар бөлек.

Үлкен жарқылдаулар (турнирлер): вебхуктер алдында - DLQ бар буфер/кезек; артық жүктеу кезінде - «no new sessions »/» pause non-core hooks».

13) SLO-бағытталған алерттердің мысалдары

Wallet. Authorize p95> 150 мс қатарынан 5 мин.

'DUPLICATE/IDEMPOTENCY _ MISMATCH' қателері> 0. 10 минут ішінде 5%

Webhook lag p99> 180 c 'bet. settled`.

Consumer lag в Kafka> 30 с үшін 'wallet. credit.`.

14) Қорытынды

REST, gRPC және iGaming вебхоктары - бұл бірін-бірі алмастыратын технологиялар емес, бір операциялық модельдің бөліктері.

REST/gRPC ақша инварианттарын сақтайды: төмен жасырындылық, іспеттілік, қатаң SLA.

Вебхактар/шина ашықтық пен масштабты қамтамасыз етеді: оқиғалар, телеметрия, интеграция.

Outbox/CDC, нұсқалау, қолтаңбалар және бақылау қосыңыз - және ақша жылдам және қауіпсіз қозғалатын, оқиғалар жоғалмайтын және жаңартулар ауыртпалықсыз өтетін архитектураны алыңыз.