feat(telegram): bot support relay — per-user forum topics
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 12s
CI / integration (pull_request) Successful in 16s
CI / ui (pull_request) Successful in 56s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m20s

Users who DM the bot anything but /start are relayed into a private
forum supergroup, one topic per user. Operators (the chat's admins)
reply in the topic and the bot copies it back to the user; an info card
opening each topic carries a Block/Unblock toggle and a Clear button.
State is a small JSON file on a new /data volume — the bot host has no
database. Off by default (TELEGRAM_SUPPORT_CHAT_ID=0): the prod bot is
unchanged until the operator sets the chat id and adds the bot as a
forum admin.

- internal/support: concurrency-safe JSON store (topic map, block list,
  relayed message ids) with field-targeted mutators and atomic save
- bot/support.go: relay both ways via copyMessage, short-TTL admin
  cache, callback buttons, per-user topic-create lock, loop guard
  (skip the bot's own posts), reopen a deleted topic on the next message
- config + compose + CI/prod-deploy: TELEGRAM_SUPPORT_CHAT_ID per
  contour + TELEGRAM_SUPPORT_STATE_DIR; bot-state named volume; /data
  pre-owned by UID 65532 so a fresh volume is writable under distroless
- docs: ARCHITECTURE §15 + decision record, FUNCTIONAL (+ru), README
This commit is contained in:
Ilia Denisov
2026-06-23 17:47:00 +02:00
parent e6277dcd43
commit 6a602aefae
18 changed files with 1465 additions and 7 deletions
@@ -42,6 +42,16 @@ type BotConfig struct {
// (TELEGRAM_CHAT_ID, optional; 0 disables chat gating). The bot must be an admin
// there with the "Ban users" right, and "chat_member" in its allowed updates.
ChatID int64
// SupportChatID is the chat id of the private forum supergroup the bot relays
// direct user messages into — one forum topic per user — and reads operator
// replies from (TELEGRAM_SUPPORT_CHAT_ID, optional; 0 disables the support relay).
// The bot must be an administrator there with the manage-topics and
// delete-messages rights. Distinct from ChatID (the moderated discussion chat).
SupportChatID int64
// SupportStateDir is the directory holding the support relay's JSON state file
// (TELEGRAM_SUPPORT_STATE_DIR, default /data). It must be writable by the
// container user (UID 65532) and backed by a persistent volume.
SupportStateDir string
// PromoBotToken is the API token of the optional standalone promo bot run in this
// container — a second bot whose only job is to answer /start with a button that
// opens the main bot's Mini App (TELEGRAM_PROMO_BOT_TOKEN, optional; empty disables
@@ -135,6 +145,7 @@ func LoadBot() (BotConfig, error) {
PromoBotToken: os.Getenv("TELEGRAM_PROMO_BOT_TOKEN"),
BotUsername: strings.TrimPrefix(os.Getenv("TELEGRAM_BOT_USERNAME"), "@"),
BotLinkURL: os.Getenv("TELEGRAM_BOT_LINK"),
SupportStateDir: envOr("TELEGRAM_SUPPORT_STATE_DIR", "/data"),
LogLevel: envOr("TELEGRAM_LOG_LEVEL", "info"),
BotLink: BotLinkClientConfig{
GatewayAddr: os.Getenv("TELEGRAM_GATEWAY_ADDR"),
@@ -152,6 +163,9 @@ func LoadBot() (BotConfig, error) {
if cfg.ChatID, err = envInt64("TELEGRAM_CHAT_ID", 0); err != nil {
return BotConfig{}, err
}
if cfg.SupportChatID, err = envInt64("TELEGRAM_SUPPORT_CHAT_ID", 0); err != nil {
return BotConfig{}, err
}
if cfg.SendRatePerSecond, err = envInt("TELEGRAM_SEND_RATE_PER_SECOND", defaultSendRatePerSecond); err != nil {
return BotConfig{}, err
}
@@ -151,6 +151,48 @@ func TestLoadBotChatAndPromo(t *testing.T) {
})
}
// TestLoadBotSupportRelay verifies the support-relay chat id parses, the state
// directory defaults to /data, and the relay is disabled (chat id 0) by default.
func TestLoadBotSupportRelay(t *testing.T) {
t.Run("parsed", func(t *testing.T) {
setBotRequired(t)
t.Setenv("TELEGRAM_SUPPORT_CHAT_ID", "-1001234567890")
t.Setenv("TELEGRAM_SUPPORT_STATE_DIR", "/srv/state")
c, err := LoadBot()
if err != nil {
t.Fatalf("LoadBot: %v", err)
}
if c.SupportChatID != -1001234567890 {
t.Errorf("SupportChatID = %d, want -1001234567890", c.SupportChatID)
}
if c.SupportStateDir != "/srv/state" {
t.Errorf("SupportStateDir = %q, want /srv/state", c.SupportStateDir)
}
})
t.Run("defaults", func(t *testing.T) {
setBotRequired(t)
c, err := LoadBot()
if err != nil {
t.Fatalf("LoadBot: %v", err)
}
if c.SupportChatID != 0 {
t.Errorf("SupportChatID = %d, want 0 (relay disabled)", c.SupportChatID)
}
if c.SupportStateDir != "/data" {
t.Errorf("SupportStateDir = %q, want /data", c.SupportStateDir)
}
})
t.Run("malformed chat id rejected", func(t *testing.T) {
setBotRequired(t)
t.Setenv("TELEGRAM_SUPPORT_CHAT_ID", "not-a-number")
if _, err := LoadBot(); err == nil {
t.Fatal("LoadBot: expected an error for a malformed support chat id, got nil")
}
})
}
// TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported set
// fails validation (the validator path).
func TestLoadRejectsUnsupportedExporter(t *testing.T) {