(new): v1.2 release

README_RU.md

@@ -261,7 +261,10 @@ plugin.Scene("signup").
 Раннеры — фоновые задачи, которые выполняются вместе с bot runtime. Они регистрируются до запуска бота и автоматически запускаются при старте.
 
 ```go
-import "time"
+import (
+    "context"
+    "time"
+)
 
 // Одноразовый раннер — запускается один раз в горутине при старте (по умолчанию).
 bot.AddRunner(
@@ -272,8 +275,8 @@ bot.AddRunner(
 
 // Периодический раннер — запускается каждые 10 минут в горутине.
 bot.AddRunner(
-    laniakea.NewRunner("refresh-stats", func(b *laniakea.Bot[*MyDB]) error {
-        return b.GetAppData().RefreshStats()
+    laniakea.NewContextRunner("refresh-stats", func(ctx context.Context, b *laniakea.Bot[*MyDB]) error {
+        return b.GetAppData().RefreshStats(ctx)
     }).Every(10 * time.Minute),
 )
 
@@ -289,6 +292,9 @@ bot.AddRunner(
 - `Async(bool) *Runner[T]` — если `true` (по умолчанию), запускается в горутине; если `false`, блокирует запуск runtime.
 - `Every(time.Duration) *Runner[T]` — задаёт интервал повторного запуска. Ноль (по умолчанию) означает одноразовый запуск; положительное значение — периодический. Периодические раннеры требуют `Async(true)`.
 
+Для I/O и блокирующей работы предпочитайте `NewContextRunner`. Его context
+отменяется при остановке polling или webhook runtime, поэтому shutdown может завершиться.
+
 ### tgapi: API и Uploader
 
 В `tgapi` есть два клиента:
@@ -298,6 +304,13 @@ bot.AddRunner(
 
 Для продвинутых сценариев `tgapi.NewRequest(...)` и `tgapi.NewUploaderRequest(...)` остаются публичными low-level escape hatch API. Они менее безопасны, чем типизированные helper-методы: вызывающая сторона сама отвечает за корректное имя Telegram-метода и совместимые типы параметров/ответа.
 
+Автоматические повторы после ответа Telegram `429` по умолчанию ограничены
+тремя; предел настраивается через `NewAPIOpts(...).SetMaxRetries(...)`.
+Multipart upload кодируется потоком без второй полной копии request body в
+памяти. Для download неизвестного размера используйте
+`OpenFileByLinkWithContext` либо задайте явный предел через
+`GetFileByLinkLimitWithContext`.
+
 ## 🧩 Промежуточные слои (Middleware)
 Middleware — это функции, которые выполняются перед обработчиком команды. Они идеально подходят для сквозных задач, таких как логирование, контроль доступа, ограничение скорости запросов или модификация контекста.
 
@@ -347,7 +360,9 @@ func adminOnlyMiddleware(ctx *laniakea.MessageContext, db *MyDB) bool {
 
 ## ⚙️ Расширенная настройка
 - **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `laniakea.NewInlineKeyboardJSON`, `laniakea.NewInlineKeyboardBase64` или `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` задаёт payload format по умолчанию, а `InlineKeyboard.SetPayloadType(...)` переопределяет его для конкретной клавиатуры.
+- **Валидация клавиатур**: Вызывайте `InlineKeyboard.GetValidated()` перед отправкой недоверенных или динамически собранных callback payload; Telegram ограничивает `callback_data` диапазоном 1–64 байта.
 - **Ограничение запросов**: Передайте настроенный `utils.RateLimiter` через `BotOpts` для корректной обработки лимитов Telegram.
+- **Observer**: Во время runtime callbacks observer выполняются асинхронно и по порядку через ограниченную очередь. Медленный observer не блокирует handlers; при переполнении события отбрасываются с редкими предупреждениями, а shutdown обрабатывает уже поставленные в очередь события.
 - **Локализация**: `L10n` безопасен для конкурентного использования после подключения к боту.
 - **Пользовательские update handlers**: Используйте `plugin.AddUpdateHandler(...)` для Telegram update types вне command/payload flow.
 - **Жизненный цикл**: `RunWithContext(...)` и `RunWebhookWithContext(...)` не вызывают `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.