Stage 15: dual Telegram bots & language-gated variants

Service-agnostic refinement of the owner's idea: the sign-in service returns a
set of supported game languages with the user identity, and the lobby gates the
New Game variant choice by it (en -> English; ru -> Russian + Эрудит).

- Connector hosts two bots in one container (one per service language, each its
  own token + game channel; the same telegram_id spans both). ValidateInitData
  tries each token and returns the validating bot's service_language +
  supported_languages. Per-language config (TELEGRAM_BOT_TOKEN_EN/_RU, channels).
- supported_languages rides the Session (fbs, session-scoped, not persisted); the
  UI offers only the matching variants on New Game — gating only the START of a
  new game (auto-match + friend invite), not accept/open/play; backend does not
  enforce.
- service_language persisted (accounts.service_language, migration 00010, written
  every login, last-login-wins) and routes the user-facing Notify push back
  through the right bot (push-target coalesces with preferred_language).
- Admin SendToUser/SendToGameChannel gain an operator-chosen language selector in
  the console (unrelated to ValidateInitData).
- Non-Telegram logins carry the gateway default set
  (GATEWAY_DEFAULT_SUPPORTED_LANGUAGES, all variants).

Wire (committed regen): ValidateInitDataResponse +service_language
+supported_languages; Session +supported_languages; SendToUser/SendToGameChannel
+language. Docs (ARCHITECTURE/FUNCTIONAL/_ru/READMEs) + PLAN updated; stage marked done.

gateway/internal/transcode/encode.go

@@ -12,17 +12,36 @@ import (
 // created before the table that references it, and no two tables/vectors are
 // under construction at once.
 
-// encodeSession builds a Session payload.
-func encodeSession(s backendclient.SessionResp) []byte {
+// buildSupportedLanguagesVector creates the Session.supported_languages [string]
+// vector from langs. FlatBuffers is built bottom-up, so the caller must invoke this
+// (which itself creates the element strings) before SessionStart and with no table
+// under construction.
+func buildSupportedLanguagesVector(b *flatbuffers.Builder, langs []string) flatbuffers.UOffsetT {
+	offsets := make([]flatbuffers.UOffsetT, len(langs))
+	for i, lang := range langs {
+		offsets[i] = b.CreateString(lang)
+	}
+	fb.SessionStartSupportedLanguagesVector(b, len(langs))
+	for i := len(offsets) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(offsets[i])
+	}
+	return b.EndVector(len(langs))
+}
+
+// encodeSession builds a Session payload. supportedLangs is the service's set of
+// offered game languages, which the UI gates the New Game variant choice by.
+func encodeSession(s backendclient.SessionResp, supportedLangs []string) []byte {
 	b := flatbuffers.NewBuilder(128)
 	token := b.CreateString(s.Token)
 	uid := b.CreateString(s.UserID)
 	name := b.CreateString(s.DisplayName)
+	langs := buildSupportedLanguagesVector(b, supportedLangs)
 	fb.SessionStart(b)
 	fb.SessionAddToken(b, token)
 	fb.SessionAddUserId(b, uid)
 	fb.SessionAddIsGuest(b, s.IsGuest)
 	fb.SessionAddDisplayName(b, name)
+	fb.SessionAddSupportedLanguages(b, langs)
 	b.Finish(fb.SessionEnd(b))
 	return b.FinishedBytes()
 }
@@ -63,8 +82,10 @@ func encodeProfile(p backendclient.ProfileResp) []byte {
 
 // encodeLinkResult builds a LinkResult payload (Stage 11). A switched-session token
 // (a guest initiator whose durable counterpart won) is carried as a nested Session
-// for the client to adopt; it is omitted otherwise.
-func encodeLinkResult(r backendclient.LinkResultResp) []byte {
+// for the client to adopt; it is omitted otherwise. supportedLangs is the variant
+// gating set for that switched session — the link flows run on the web, so it is the
+// gateway's default (non-platform) set.
+func encodeLinkResult(r backendclient.LinkResultResp, supportedLangs []string) []byte {
 	b := flatbuffers.NewBuilder(256)
 	status := b.CreateString(r.Status)
 	secID := b.CreateString(r.SecondaryUserID)
@@ -75,11 +96,13 @@ func encodeLinkResult(r backendclient.LinkResultResp) []byte {
 		token := b.CreateString(r.Token)
 		uid := b.CreateString(r.Profile.UserID)
 		name := b.CreateString(r.Profile.DisplayName)
+		langs := buildSupportedLanguagesVector(b, supportedLangs)
 		fb.SessionStart(b)
 		fb.SessionAddToken(b, token)
 		fb.SessionAddUserId(b, uid)
 		fb.SessionAddIsGuest(b, r.Profile.IsGuest)
 		fb.SessionAddDisplayName(b, name)
+		fb.SessionAddSupportedLanguages(b, langs)
 		sess = fb.SessionEnd(b)
 	}
 	fb.LinkResultStart(b)

gateway/internal/transcode/transcode.go

@@ -75,14 +75,20 @@ type TelegramValidator interface {
 // NewRegistry builds the slice's message-type catalog over the backend client.
 // The Telegram auth op is registered only when a validator is supplied (the
 // connector is configured); otherwise auth.telegram is simply unknown.
-func NewRegistry(backend *backendclient.Client, tg TelegramValidator) *Registry {
+// defaultLanguages is the New Game variant gating set placed on the Session for
+// non-platform logins (web / email / guest) and on a switched link session; an
+// empty argument falls back to all languages (matching the config default).
+func NewRegistry(backend *backendclient.Client, tg TelegramValidator, defaultLanguages ...string) *Registry {
+	if len(defaultLanguages) == 0 {
+		defaultLanguages = []string{"en", "ru"}
+	}
 	r := &Registry{ops: make(map[string]Op)}
 	if tg != nil {
 		r.ops[MsgAuthTelegram] = Op{Handler: authTelegramHandler(backend, tg)}
 	}
-	r.ops[MsgAuthGuest] = Op{Handler: authGuestHandler(backend)}
+	r.ops[MsgAuthGuest] = Op{Handler: authGuestHandler(backend, defaultLanguages)}
 	r.ops[MsgAuthEmailReq] = Op{Handler: authEmailRequestHandler(backend), Email: true}
-	r.ops[MsgAuthEmailLogin] = Op{Handler: authEmailLoginHandler(backend), Email: true}
+	r.ops[MsgAuthEmailLogin] = Op{Handler: authEmailLoginHandler(backend, defaultLanguages), Email: true}
 	r.ops[MsgProfileGet] = Op{Handler: profileHandler(backend), Auth: true}
 	r.ops[MsgGameSubmitPlay] = Op{Handler: submitPlayHandler(backend), Auth: true}
 	r.ops[MsgGameState] = Op{Handler: gameStateHandler(backend), Auth: true}
@@ -101,7 +107,7 @@ func NewRegistry(backend *backendclient.Client, tg TelegramValidator) *Registry
 	r.ops[MsgChatList] = Op{Handler: chatListHandler(backend), Auth: true}
 	r.ops[MsgChatNudge] = Op{Handler: nudgeHandler(backend), Auth: true}
 	registerStage8(r, backend)
-	registerStage11(r, backend, tg)
+	registerStage11(r, backend, tg, defaultLanguages)
 	return r
 }
 
@@ -135,21 +141,21 @@ func authTelegramHandler(backend *backendclient.Client, tg TelegramValidator) Ha
 		if err != nil {
 			return nil, err
 		}
-		sess, err := backend.TelegramAuth(ctx, user.ExternalID, user.LanguageCode, user.Username, user.FirstName)
+		sess, err := backend.TelegramAuth(ctx, user.ExternalID, user.LanguageCode, user.Username, user.FirstName, user.ServiceLanguage)
 		if err != nil {
 			return nil, err
 		}
-		return encodeSession(sess), nil
+		return encodeSession(sess, user.SupportedLanguages), nil
 	}
 }
 
-func authGuestHandler(backend *backendclient.Client) Handler {
+func authGuestHandler(backend *backendclient.Client, supportedLangs []string) Handler {
 	return func(ctx context.Context, _ Request) ([]byte, error) {
 		sess, err := backend.GuestAuth(ctx)
 		if err != nil {
 			return nil, err
 		}
-		return encodeSession(sess), nil
+		return encodeSession(sess, supportedLangs), nil
 	}
 }
 
@@ -163,14 +169,14 @@ func authEmailRequestHandler(backend *backendclient.Client) Handler {
 	}
 }
 
-func authEmailLoginHandler(backend *backendclient.Client) Handler {
+func authEmailLoginHandler(backend *backendclient.Client, supportedLangs []string) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsEmailLoginRequest(req.Payload, 0)
 		sess, err := backend.EmailLogin(ctx, string(in.Email()), string(in.Code()))
 		if err != nil {
 			return nil, err
 		}
-		return encodeSession(sess), nil
+		return encodeSession(sess, supportedLangs), nil
 	}
 }
 

gateway/internal/transcode/transcode_link.go

@@ -22,13 +22,15 @@ const (
 
 // registerStage11 adds the linking & merge operations. The telegram ops need the
 // connector's Login Widget validator, so they are registered only when tg is set.
-func registerStage11(r *Registry, backend *backendclient.Client, tg TelegramValidator) {
+// supportedLangs is the variant gating set for a switched link session (the link
+// flows run on the web, so the gateway default set).
+func registerStage11(r *Registry, backend *backendclient.Client, tg TelegramValidator, supportedLangs []string) {
 	r.ops[MsgLinkEmailRequest] = Op{Handler: linkEmailRequestHandler(backend), Auth: true, Email: true}
-	r.ops[MsgLinkEmailConfirm] = Op{Handler: linkEmailConfirmHandler(backend), Auth: true, Email: true}
-	r.ops[MsgLinkEmailMerge] = Op{Handler: linkEmailMergeHandler(backend), Auth: true, Email: true}
+	r.ops[MsgLinkEmailConfirm] = Op{Handler: linkEmailConfirmHandler(backend, supportedLangs), Auth: true, Email: true}
+	r.ops[MsgLinkEmailMerge] = Op{Handler: linkEmailMergeHandler(backend, supportedLangs), Auth: true, Email: true}
 	if tg != nil {
-		r.ops[MsgLinkTelegram] = Op{Handler: linkTelegramHandler(backend, tg, false), Auth: true}
-		r.ops[MsgLinkTelegramMerge] = Op{Handler: linkTelegramHandler(backend, tg, true), Auth: true}
+		r.ops[MsgLinkTelegram] = Op{Handler: linkTelegramHandler(backend, tg, false, supportedLangs), Auth: true}
+		r.ops[MsgLinkTelegramMerge] = Op{Handler: linkTelegramHandler(backend, tg, true, supportedLangs), Auth: true}
 	}
 }
 
@@ -42,31 +44,31 @@ func linkEmailRequestHandler(backend *backendclient.Client) Handler {
 	}
 }
 
-func linkEmailConfirmHandler(backend *backendclient.Client) Handler {
+func linkEmailConfirmHandler(backend *backendclient.Client, supportedLangs []string) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsLinkEmailConfirm(req.Payload, 0)
 		res, err := backend.LinkEmailConfirm(ctx, req.UserID, string(in.Email()), string(in.Code()))
 		if err != nil {
 			return nil, err
 		}
-		return encodeLinkResult(res), nil
+		return encodeLinkResult(res, supportedLangs), nil
 	}
 }
 
-func linkEmailMergeHandler(backend *backendclient.Client) Handler {
+func linkEmailMergeHandler(backend *backendclient.Client, supportedLangs []string) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsLinkEmailConfirm(req.Payload, 0)
 		res, err := backend.LinkEmailMerge(ctx, req.UserID, string(in.Email()), string(in.Code()))
 		if err != nil {
 			return nil, err
 		}
-		return encodeLinkResult(res), nil
+		return encodeLinkResult(res, supportedLangs), nil
 	}
 }
 
 // linkTelegramHandler validates Login Widget data via the connector and then calls
 // the backend's link or merge endpoint with the trusted Telegram external id.
-func linkTelegramHandler(backend *backendclient.Client, tg TelegramValidator, merge bool) Handler {
+func linkTelegramHandler(backend *backendclient.Client, tg TelegramValidator, merge bool, supportedLangs []string) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsLinkTelegramRequest(req.Payload, 0)
 		user, err := tg.ValidateLoginWidget(ctx, string(in.Data()))
@@ -82,6 +84,6 @@ func linkTelegramHandler(backend *backendclient.Client, tg TelegramValidator, me
 		if err != nil {
 			return nil, err
 		}
-		return encodeLinkResult(res), nil
+		return encodeLinkResult(res, supportedLangs), nil
 	}
 }

gateway/internal/transcode/transcode_telegram_test.go

@@ -47,7 +47,7 @@ func TestTelegramAuthForwardsSeedFields(t *testing.T) {
 	})
 	defer cleanup()
 
-	v := fakeValidator{user: connector.User{ExternalID: "42", Username: "neo", FirstName: "Иван", LanguageCode: "ru"}}
+	v := fakeValidator{user: connector.User{ExternalID: "42", Username: "neo", FirstName: "Иван", LanguageCode: "ru", ServiceLanguage: "ru", SupportedLanguages: []string{"ru"}}}
 	reg := transcode.NewRegistry(backend, v)
 	op, ok := reg.Lookup(transcode.MsgAuthTelegram)
 	if !ok {
@@ -62,9 +62,43 @@ func TestTelegramAuthForwardsSeedFields(t *testing.T) {
 	if string(sess.Token()) != "tok-tg" || string(sess.UserId()) != "u-tg" {
 		t.Fatalf("session decoded wrong: token=%q user=%q", sess.Token(), sess.UserId())
 	}
-	// The validated launch fields are forwarded so the backend can seed a new account.
-	if gotBody["external_id"] != "42" || gotBody["language_code"] != "ru" || gotBody["first_name"] != "Иван" {
-		t.Errorf("forwarded body = %+v, want external_id=42 language_code=ru first_name=Иван", gotBody)
+	// The validating bot's supported languages ride the Session so the UI gates the
+	// New Game variant choice (here: ru -> Russian + Эрудит only).
+	if got := sessionLanguages(sess); len(got) != 1 || got[0] != "ru" {
+		t.Errorf("session supported_languages = %v, want [ru]", got)
+	}
+	// The validated launch fields are forwarded so the backend can seed a new account;
+	// service_language is recorded to route the account's later out-of-app push.
+	if gotBody["external_id"] != "42" || gotBody["language_code"] != "ru" || gotBody["first_name"] != "Иван" || gotBody["service_language"] != "ru" {
+		t.Errorf("forwarded body = %+v, want external_id=42 language_code=ru first_name=Иван service_language=ru", gotBody)
+	}
+}
+
+// sessionLanguages reads the supported_languages vector off a decoded Session.
+func sessionLanguages(s *fb.Session) []string {
+	out := make([]string, s.SupportedLanguagesLength())
+	for i := range out {
+		out[i] = string(s.SupportedLanguages(i))
+	}
+	return out
+}
+
+// TestGuestAuthSeedsDefaultLanguages confirms a non-platform (guest) session carries
+// the gateway's default supported-languages set, so the web client is ungated.
+func TestGuestAuthSeedsDefaultLanguages(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"token":"tok-g","user_id":"u-g","is_guest":true,"display_name":"Guest"}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil, "en", "ru")
+	op, _ := reg.Lookup(transcode.MsgAuthGuest)
+	payload, err := op.Handler(context.Background(), transcode.Request{})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	if got := sessionLanguages(fb.GetRootAsSession(payload, 0)); len(got) != 2 || got[0] != "en" || got[1] != "ru" {
+		t.Errorf("guest session supported_languages = %v, want [en ru]", got)
 	}
 }