release: merge v0.0.1-beta.2

Author: amtiYo

.env.example

@@ -9,6 +9,13 @@ DEEPGRAM_API_KEY=
 # TELEGRAM_API_BASE=http://telegram-bot-api:8081
 TELEGRAM_API_BASE=https://api.telegram.org
 
+# Required when TELEGRAM_API_BASE is self-hosted. Such a server runs with
+# --local: getFile answers with an absolute path and nothing is served over
+# HTTP, so its data directory must be mounted. Mount only this bot's own
+# subdirectory — the others are named after other bots' tokens.
+# BOT_API_FILES_DIR=/var/lib/telegram-bot-api
+TELEGRAM_READY_WAIT=30s
+
 # Local compose overrides this. For shared core-postgres use the voicy_core role.
 DATABASE_URL=postgres://voicy:voicy@postgres:5432/voicy?sslmode=disable
 

.github/workflows/ci.yml

@@ -88,4 +88,10 @@ jobs:
           cp .env.example .env
           docker compose config >/dev/null
           cp .env.example deploy/ws04/.env
-          VOICY_IMAGE=ghcr.io/freshlabdev/voicy:test docker compose -f deploy/ws04/compose.yaml config >/dev/null
+          # The production stack mounts this bot's own directory on the shared
+          # Bot API server, and that path is the token, so validation needs a
+          # value to interpolate.
+          VOICY_IMAGE=ghcr.io/freshlabdev/voicy:test \
+            TELEGRAM_BOT_TOKEN=000:ci-validation-only \
+            BOT_API_HOST_DIR=/opt/stacks/telegram-bot-api/files \
+            docker compose -f deploy/ws04/compose.yaml config >/dev/null

.github/workflows/release.yml

@@ -43,7 +43,10 @@ jobs:
           cp .env.example .env
           docker compose config >/dev/null
           cp .env.example deploy/ws04/.env
-          VOICY_IMAGE=ghcr.io/freshlabdev/voicy:test docker compose -f deploy/ws04/compose.yaml config >/dev/null
+          VOICY_IMAGE=ghcr.io/freshlabdev/voicy:test \
+            TELEGRAM_BOT_TOKEN=000:ci-validation-only \
+            BOT_API_HOST_DIR=/opt/stacks/telegram-bot-api/files \
+            docker compose -f deploy/ws04/compose.yaml config >/dev/null
 
   database:
     name: Verify database behavior

AGENTS.md

@@ -8,8 +8,13 @@ Keep Voicy minimal, private by default, and production-minded.
 - PostgreSQL is the only durable store. Domain tables live in a `voicy`
   schema. Telegram identity and presence are delegated to shared `core`
   (`core.touch('voicy', …)`).
-- Telegram uses a first-party HTTP client in `internal/telegram`. Long polling
-  only.
+- Telegram goes through `github.com/FreshLabDev/tg`, the client shared by the
+  bot family. Voicy keeps no private HTTP client: transport, retries, token
+  redaction, rich and ephemeral messages, and local Bot API files all live
+  there. Long polling only.
+- `Preflight` runs before the bot starts and names the methods Voicy cannot
+  work without. A server that lacks them is a startup failure, never a bot
+  that polls and answers nothing.
 
 ## Product Boundaries
 

CHANGELOG.md

@@ -8,6 +8,63 @@ GitHub Releases.
 
 ## Unreleased
 
+## v0.0.1-beta.2 - 2026-09-08
+
+Voicy's Telegram client is no longer its own, and it will not start against a
+server that cannot serve it.
+
+### Changed
+
+- Telegram now goes through `github.com/FreshLabDev/tg`, the client shared by
+  the bot family, and `internal/telegram` is gone. The transport, retries,
+  token redaction, rich messages and the 10.3 ephemeral contract were the same
+  code in three bots and had already drifted apart; they now have one home.
+  Nothing about Voicy's behaviour changes with them.
+- `internal/media.Of` replaces `telegram.Message.Media()`. Go cannot put a
+  method on another package's type, and the order in which attachments are
+  preferred — speech first — was always a Voicy decision rather than a
+  Telegram one.
+- `voicy_telegram_errors_total` now also counts transport failures (DNS,
+  connect, reset). They were invisible before, because only a parsed API error
+  reached the counter.
+
+### Added
+
+- A preflight at startup. Voicy names the methods it cannot work without —
+  `sendRichMessage` and `editEphemeralMessageText` — and refuses to start when
+  the Bot API server does not implement them. A server behind the bot answers
+  `404 method not found` to every rich message, which used to mean a bot that
+  polled happily and answered nothing at all.
+- `BOT_API_FILES_DIR`, required when `TELEGRAM_API_BASE` is self-hosted, and
+  `TELEGRAM_READY_WAIT` (default 30s) for a server that is still booting.
+
+### Fixed
+
+- Media on a self-hosted Bot API server is read from disk again. Such a server
+  runs with `--local`, and a `--local` server serves no files over HTTP at all:
+  its `/file/bot<token>/…` route answers 404 in every version. Fetching over
+  the network, introduced in v0.0.1-alpha.10, could therefore never work. Only
+  this bot's own directory is mounted — the parent holds one directory per bot
+  named after that bot's token — and the mount is verified at startup instead
+  of failing on the first voice message.
+
+### Operations
+
+- The WS04 stack mounts the bot's own media directory on the Bot API server
+  and runs as uid 101, the user that server writes as. `BOT_API_HOST_DIR` and
+  `BOT_API_FILES_DIR` name that directory on the host and in the container.
+  Files are removed after transcription, which a local server never does on
+  its own.
+- The mount needs Compose's long volume syntax *with* a `bind` option. Both
+  paths contain the bot token, a token contains a colon, and Compose flattens
+  an option-less long mount back into `source:target:rw`, which the daemon
+  then splits in the wrong places.
+- Production runs against `telegram-bot-api-next`, the FreshLab-built Bot API
+  10.3 server, while the older shared server keeps the bots that have not
+  moved. Moving a bot between servers is: stop it, `logOut` on the server it
+  leaves, then start it on the new one. A running bot re-registers itself
+  within a second, so the stop is not optional.
+
 ## v0.0.1-beta.1 - 2026-09-06
 
 Voicy speaks the sixteen languages the bot family shares, transcribes audio

README.md

@@ -149,6 +149,8 @@ getFile -> bounded download
 |:--|:--:|:--|:--|
 | `TELEGRAM_BOT_TOKEN` | yes | — | Bot token from BotFather |
 | `TELEGRAM_API_BASE` | no | `https://api.telegram.org` | Bot API server; a self-hosted one lifts the 20 MB media ceiling |
+| `BOT_API_FILES_DIR` | with a self-hosted server | — | That server's media directory as Voicy sees it (its `--files-dir`, or its `--dir` on a server without one). It runs with `--local`, so it hands over files by absolute path and serves none over HTTP; mount only `<dir>/<token>`, and create that directory owned by uid 101 first |
+| `TELEGRAM_READY_WAIT` | no | `30s` | How long startup waits for a self-hosted server that is still booting |
 | `DEEPGRAM_API_KEY` | yes | — | Deepgram project API key |
 | `DATABASE_URL` | yes | — | PostgreSQL URL for `voicy_core`; the service enforces `search_path=voicy` |
 | `HTTP_ADDR` | no | `:8080` | HTTP listen address |

cmd/voicy/main.go

@@ -11,14 +11,14 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/FreshLabDev/tg"
 	"github.com/FreshLabDev/voicy/internal/bot"
 	"github.com/FreshLabDev/voicy/internal/config"
 	"github.com/FreshLabDev/voicy/internal/db"
 	"github.com/FreshLabDev/voicy/internal/deepgram"
 	"github.com/FreshLabDev/voicy/internal/health"
 	"github.com/FreshLabDev/voicy/internal/media"
 	"github.com/FreshLabDev/voicy/internal/metrics"
-	"github.com/FreshLabDev/voicy/internal/telegram"
 )
 
 var (
@@ -54,16 +54,45 @@ func run(log *slog.Logger) error {
 		}
 	}
 
-	tg := telegram.NewClient(cfg.TelegramBotToken)
-	tg.SetAPIBase(cfg.TelegramAPIBase)
-	if cfg.TelegramAPIBase != config.DefaultTelegramAPIBase {
-		// A local server lifts the cloud API's 20 MB getFile ceiling and returns
-		// files by absolute path on a shared volume.
+	client := tg.New(cfg.TelegramBotToken,
+		tg.WithAPIBase(cfg.TelegramAPIBase),
+		// my_chat_member is what tells shared Core where Voicy lives; Telegram
+		// leaves it out of the default set, so it has to be asked for.
+		tg.WithAllowedUpdates("message", "callback_query", "my_chat_member"),
+		tg.WithLocalFiles(cfg.BotAPIFilesDir),
+		tg.WithLogger(log),
+		tg.WithObserver(func(e tg.Event) {
+			switch {
+			case e.Err == nil:
+			case e.Status == http.StatusTooManyRequests:
+				metrics.TelegramLimited.Inc(e.Method)
+			default:
+				metrics.TelegramErrors.Inc(e.Method)
+			}
+		}),
+	)
+	selfHosted := cfg.TelegramAPIBase != config.DefaultTelegramAPIBase
+	if selfHosted {
+		// A local server lifts the cloud API's 20 MB getFile ceiling and hands
+		// over files by absolute path on its own disk.
 		log.Info("using a self-hosted bot api server", "base", cfg.TelegramAPIBase)
 	}
+	// Voicy without rich messages is a bot that receives a voice message and
+	// answers nothing: every transcript, placeholder and ephemeral reply goes
+	// through them. A server that lacks them is a startup failure, not a
+	// surprise on the first circle.
+	me, err := client.Preflight(ctx, tg.Needs{
+		Methods: []string{"sendRichMessage", "editEphemeralMessageText"},
+		Files:   selfHosted,
+		Wait:    cfg.TelegramReadyWait,
+	})
+	if err != nil {
+		return err
+	}
+	log.Info("telegram preflight passed", "username", me.Username, "bot_api", tg.BotAPI)
 	stt := deepgram.New(cfg.DeepgramAPIKey)
 	store.SetStatsTimezone(cfg.StatsTimezone)
-	b := bot.New(store, tg, stt, log)
+	b := bot.New(store, client, stt, log)
 	b.SetMediaLimits(cfg.MaxMediaBytes, cfg.MaxMediaDuration)
 	b.SetWorkers(cfg.MaxConcurrentJobs)
 	b.SetStatsTTL(cfg.StatsCacheTTL)

deploy/ws04/compose.yaml

@@ -14,12 +14,35 @@ services:
       MIGRATIONS_DIR: /app/migrations
       HTTP_ADDR: :8080
       AUTO_MIGRATE: "true"
+      # Where this bot sees the Bot API server's media. On a server started
+      # with --files-dir (Bot API 10.3+) that is not the working directory.
+      BOT_API_FILES_DIR: ${BOT_API_FILES_DIR:-/var/lib/telegram-bot-api}
+    # The shared Bot API server runs with --local, which means it answers
+    # getFile with an absolute path on its own disk and serves nothing over
+    # HTTP: its /file/bot<token>/... route returns 404 by design. So the
+    # directory has to be mounted — but only this bot's own subdirectory. The
+    # parent holds one subdirectory per bot, each named after that bot's full
+    # token, and mounting it would hand Voicy every other bot's credentials.
+    # Long syntax, not "source:target": a bot token contains a colon and both
+    # paths contain the token, so the short form splits in the wrong places.
+    # The bind option is not decoration either -- without one, Compose flattens
+    # long syntax back into a "source:target:rw" string and the daemon's parser
+    # fails the same way ("invalid volume specification: too many colons").
+    volumes:
+      - type: bind
+        # The directory must already exist and be owned by uid 101, the user
+        # the Bot API server writes as. Docker would otherwise create it as
+        # root, and then neither the server nor this bot could write in it.
+        source: ${BOT_API_HOST_DIR:?BOT_API_HOST_DIR must point at the Bot API server media directory on the host}/${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN must be set for the Bot API files mount}
+        target: ${BOT_API_FILES_DIR:-/var/lib/telegram-bot-api}/${TELEGRAM_BOT_TOKEN}
+        bind:
+          propagation: rprivate
+    # The Bot API server writes as uid 101 with mode 0750. Voicy has to read
+    # those files and delete them afterwards, because a local server never
+    # reclaims what it produced.
+    user: "101:101"
     # telegram_bot_api_net reaches the shared self-hosted Bot API server, the
-    # same one vido uses. Its data directory is deliberately NOT mounted: it
-    # holds one subdirectory per bot named after that bot's token, so mounting
-    # it would hand Voicy every other bot's credentials. Files are fetched from
-    # the server over this network instead, which still lifts the cloud API's
-    # 20 MB ceiling.
+    # same one vido uses.
     networks: [core_net, telegram_bot_api_net]
     logging:
       driver: json-file

docs/architecture.md

@@ -14,8 +14,8 @@ surface. PostgreSQL is its only durable store.
   deleted when the job ends. It is never logged or stored in PostgreSQL.
 - ffmpeg reduces video and oversized media to a mono Opus track before the
   Deepgram request. Without ffmpeg the original is sent instead.
-- Telegram is accessed through the first-party HTTP client in
-  `internal/telegram`. There is no SDK and no webhook mode.
+- Telegram is accessed through `github.com/FreshLabDev/tg`, the client shared
+  by the bot family. There is no SDK and no webhook mode.
 - `TELEGRAM_API_BASE` selects the Bot API server. The shared self-hosted one on
   `telegram_bot_api_net` runs with `TELEGRAM_LOCAL`, so `getFile` answers with an
   absolute path in its data directory. That directory is not mounted into Voicy:
@@ -100,5 +100,4 @@ Markdown when possible, then DM, then an owner-bound deep link as recovery.
 - `internal/deepgram`: prerecorded Listen client and response extraction.
 - `internal/health`: readiness and liveness contract.
 - `internal/settings`: settings registry and cache variants.
-- `internal/telegram`: Bot API HTTP transport.
 - `internal/transcript`: localized panels, rich HTML, splitting, stats.

go.mod

@@ -4,7 +4,10 @@ module github.com/FreshLabDev/voicy
 
 go 1.26.6
 
-require github.com/jackc/pgx/v5 v5.9.2
+require (
+	github.com/FreshLabDev/tg v0.0.1-alpha.1
+	github.com/jackc/pgx/v5 v5.9.2
+)
 
 require (
 	github.com/jackc/pgpassfile v1.0.0 // indirect