new opts file codec

Bot-Options-and-Configuration-RU.md

@@ -17,11 +17,11 @@ English version: [[Bot-Options-and-Configuration]]
 - размер worker pool.
 
 Обычный поток:
-1. собрать `BotOpts` вручную или через `LoadOptsFromEnv()`;
+1. собрать `BotOpts` вручную, через `LoadOptsFromEnv()` или через `LoadBotOptsFile(...)`;
 2. при необходимости донастроить setter methods;
 3. передать в `NewBot(...)`.
 
-## Два способа собрать `BotOpts`
+## Три способа собрать `BotOpts`
 
 ### Вручную
 
@@ -41,6 +41,34 @@ opts := laniakea.LoadOptsFromEnv()
 
 Это удобно для production, containers и CI.
 
+### Из файла
+
+`LoadBotOptsFile(...)` подходит, когда конфиг бота удобнее хранить в отдельном файле.
+
+Из коробки доступно:
+- `BotOptsFileJsonCodec` для JSON.
+
+```go
+codec := laniakea.BotOptsFileJsonCodec{}
+opts, err := laniakea.LoadBotOptsFile(codec, "config.json")
+if err != nil {
+	return err
+}
+```
+
+При необходимости `BotOpts` можно сохранить обратно:
+
+```go
+if err := laniakea.SaveBotOptsFile(codec, "config.json", opts); err != nil {
+	return err
+}
+```
+
+Перед декодированием loader разворачивает плейсхолдеры вроде `{{ TG_TOKEN }}` из environment variables.
+
+Из коробки библиотека пока поддерживает только JSON. Для других форматов можно реализовать свой codec через `BotOptsFileCodec`.
+Если нужен другой формат, например TOML, используй `BotOptsFileJsonCodec` как референсную реализацию собственного codec.
+
 ## Что обязательно
 
 Обязателен только `Token`.
@@ -56,6 +84,22 @@ opts := laniakea.LoadOptsFromEnv()
 - журналирование запросов и логирование в файл выключены
 - строгое декодирование данных callback выключено
 
+## Плейсхолдеры в файлах
+
+`LoadBotOptsFile(...)` разворачивает плейсхолдеры такого вида:
+
+```text
+{{ TG_TOKEN }}
+{{API_URL}}
+```
+
+Это происходит до вызова `codec.FromBytes(...)`.
+
+Такой режим удобен, когда:
+- структуру конфига хочется хранить в репозитории;
+- секреты всё ещё должны приходить из environment;
+- нужен свой codec под другой формат файла.
+
 ## Важные поля
 
 ### `UpdateTypes`

Bot-Options-and-Configuration.md

@@ -18,13 +18,13 @@ Use it when you want to control:
 
 The normal flow is:
 
-1. create `BotOpts` manually or via `LoadOptsFromEnv()`;
+1. create `BotOpts` manually, via `LoadOptsFromEnv()`, or via `LoadBotOptsFile(...)`;
 2. optionally refine it with setter methods;
 3. pass it to `NewBot(...)`.
 
 For runtime configuration after bot creation, see [[Bot-Lifecycle]].
 
-## Two ways to build `BotOpts`
+## Three ways to build `BotOpts`
 
 ### Manual configuration
 
@@ -53,6 +53,39 @@ if err != nil {
 
 This is often the easiest approach for containers, CI, and production services.
 
+### File-based configuration
+
+Use `LoadBotOptsFile(...)` when you want to keep bot configuration in a checked-in or deployment-managed config file.
+
+Built in:
+- `BotOptsFileJsonCodec` for JSON files.
+
+```go
+codec := laniakea.BotOptsFileJsonCodec{}
+opts, err := laniakea.LoadBotOptsFile(codec, "config.json")
+if err != nil {
+	return err
+}
+
+bot, err := laniakea.NewBot[*App](opts)
+if err != nil {
+	return err
+}
+```
+
+You can also persist `BotOpts` back to disk:
+
+```go
+if err := laniakea.SaveBotOptsFile(codec, "config.json", opts); err != nil {
+	return err
+}
+```
+
+Before decoding, the loader expands placeholders like `{{ TG_TOKEN }}` from environment variables.
+
+Only JSON support is built into the library right now. If you want another format, implement `BotOptsFileCodec` yourself.
+Use `BotOptsFileJsonCodec` as the reference implementation for custom codecs such as TOML.
+
 ## Required setting
 
 Only one field is strictly required:
@@ -292,6 +325,22 @@ Related page:
 
 List-valued fields use semicolon-separated values.
 
+## File placeholders supported by `LoadBotOptsFile()`
+
+`LoadBotOptsFile(...)` expands placeholders in the form:
+
+```text
+{{ TG_TOKEN }}
+{{API_URL}}
+```
+
+Expansion happens before `codec.FromBytes(...)` is called.
+
+This is useful when:
+- the config file structure should stay in version control;
+- secrets should still come from environment variables;
+- you want the same codec to work across local and deployed environments.
+
 ## Recommended configurations
 
 ### Minimal local setup
@@ -324,6 +373,7 @@ opts := (&laniakea.BotOpts{}).
 
 - Start with the defaults unless you already know your traffic pattern.
 - Prefer `LoadOptsFromEnv()` for deployment-oriented apps.
+- Prefer `LoadBotOptsFile(...)` when you want structured config files or custom formats.
 - Set `StrictPayloadType` only when you are ready to enforce one payload encoding policy.
 - Increase `MaxWorkers` carefully and based on actual handler workload.
 - Turn on request logging selectively, because it is useful for debugging but noisy in normal operation.