Ilia Denisov
dcd8de8b00
- pkg/telemetry: shared OTel provider bootstrap (none/stdout/otlp + W3C
propagators + Go runtime metrics); backend/internal/telemetry becomes a thin
facade keeping its gin middleware.
- Telemetry parity: gateway and the Telegram connector gain telemetry runtimes
and config (GATEWAY_/TELEGRAM_ SERVICE_NAME + OTEL_*); otelgrpc instruments the
backend push server, the gateway's backend+connector clients and the connector
server. Default exporter stays none (collector/dashboards are Stage 14).
- Operational metrics (variant attribute on game-scoped ones): game_replay_duration,
game_move_validate_duration, games_started_total, games_abandoned_total,
game_cache_active, chat_messages_total{kind}, gateway edge_request_duration.
Wired via the SetMetrics setter pattern (default no-op meter).
- TODO-3: account.GuestReaper deletes guests with no game seat past
BACKEND_GUEST_RETENTION (default 30d, swept every BACKEND_GUEST_REAP_INTERVAL).
- Tests: pkg/telemetry exporter selection; game/social/edge metric recording via
a manual reader; config (otlp accepted, guest knobs); inttest guest reaper.
- Docs: PLAN.md re-scopes Stage 12 and adds Stage 13 (alphabet-on-wire) + Stage 14
(CI/deploy) with the agreed dictionary-versioning resolution; ARCHITECTURE 11/13,
TESTING, the three READMEs and FUNCTIONAL(+ru) updated.
4.6 KiB
scrabble/platform/telegram — Telegram connector
The Telegram platform side-service. It is the only component that holds the bot
token: it runs the Bot API long-poll loop (Mini App launch + deep-links) and serves
the connector gRPC API that the gateway and backend call over the trusted internal
network. See docs/ARCHITECTURE.md §1/§3/§10/§12.
Responsibilities
- Mini App auth.
ValidateInitDataverifies Telegram Web AppinitData(HMAC under the bot token) and returns the user identity. The gateway calls it during theauth.telegramedge operation, then provisions the session through the backend internal API — so the bot token never leaves this process. - Out-of-app push.
Notifyrenders a backend push event (your_turn, nudge, match_found, and the invitation / friend_request notify sub-kinds) into a localized message with a Mini App launch button and sends it. The gateway calls it only for a recipient with no live in-app stream and thenotifications_in_app_onlyflag off, so the platform push never duplicates in-app delivery. - Bot chat.
/start <payload>(and the chat menu button) reply with a Mini App launch button; a deep-link payload routes the launch to a game / invitation / friend code. - Admin messaging (wired in Stage 10).
SendToUserandSendToGameChannelsend arbitrary text to one user or the configured game channel.
The generic methods (Notify, SendToUser, SendToGameChannel) address a
recipient by the identity external_id (as in the backend identities table), so a
future VK / MAX connector can implement the same service; only ValidateInitData is
Telegram-specific.
gRPC API
pkg/proto/telegram/v1, service Telegram: ValidateInitData,
ValidateLoginWidget, Notify, SendToUser, SendToGameChannel. Generated Go is
committed under pkg. ValidateLoginWidget (Stage 11) verifies Telegram Login
Widget web sign-in data — HMAC under SHA-256(bot_token), distinct from initData
(internal/loginwidget) — for attaching a Telegram identity to an account from a
browser.
Deep-link scheme
Shared verbatim with the UI (ui/src/lib/deeplink.ts). A Mini App start parameter
is a one-character kind prefix plus a value:
| Parameter | Destination |
|---|---|
g<game uuid> |
open that game |
i<invitation uuid> |
open that invitation |
f<6-digit code> |
redeem that friend code |
| empty / unknown | the lobby |
The bot turns a /start <payload> or a notification target into a launch-button URL
<MiniAppURL>?startapp=<payload>.
Configuration
| Env var | Default | Meaning |
|---|---|---|
TELEGRAM_BOT_TOKEN |
— (required) | Bot API token + the initData HMAC secret |
TELEGRAM_MINIAPP_URL |
— (required) | Mini App HTTPS origin (BotFather-registered) |
TELEGRAM_GRPC_ADDR |
:9091 |
connector gRPC listen address |
TELEGRAM_API_BASE_URL |
https://api.telegram.org |
Bot API host override (mock / self-hosted) |
TELEGRAM_TEST_ENV |
false |
route to the Bot API test environment (/bot<token>/test/METHOD) |
TELEGRAM_GAME_CHANNEL_ID |
— | game channel chat id for SendToGameChannel |
TELEGRAM_LOG_LEVEL |
info |
zap log level |
TELEGRAM_SERVICE_NAME |
scrabble-telegram |
OpenTelemetry service.name |
TELEGRAM_OTEL_TRACES_EXPORTER |
none |
none, stdout or otlp (gRPC; endpoint from OTEL_EXPORTER_OTLP_*) |
TELEGRAM_OTEL_METRICS_EXPORTER |
none |
none, stdout or otlp |
The test environment is selected by TELEGRAM_TEST_ENV=true, which suffixes the
Bot API path with /test (the connector appends it to the token, since the client
builds <host>/bot<token>/<method>).
Build, test, run
go build ./platform/telegram/...
go test ./platform/telegram/... # unit tests use an httptest fake Bot API
go run ./platform/telegram/cmd/telegram # needs a real TELEGRAM_BOT_TOKEN
Deploy
The connector runs in its own container with the bot token held only there and
all egress through a VPN sidecar (deploy/docker-compose.yml, mirroring
../../15-puzzle). It needs no public ingress — it long-polls Telegram and answers
internal gRPC at telegram:9091 on the shared edge network. The host reverse proxy
routes public traffic to the gateway port only, which serves the Mini App under
/telegram/. The full multi-service deploy lands with Stage 12.
A real end-to-end Telegram smoke needs a BotFather bot, its token, a public HTTPS Mini App origin, and the connector container; the unit tests cover the wire format, templates, deep-links and the gRPC handlers without a live bot.