vpnbot-xray-patches/docs/2026-08-07-release-telegram-alert-plan.md

Telegram-уведомления о безопасно остановившемся выпуске Xray

Задача

Автоматический выпуск уже безопасно останавливается до появления proven, если патчи не накладываются, сборка или тесты падают, candidate слишком долго не проходит пилот либо canary не подтверждает активный отзыв доступа. Сейчас это состояние видно в Forgejo Actions, systemd и root-only JSON промоутера, но оператор должен сам регулярно проверять все три места.

Нужен отдельный наблюдатель, который быстро сообщает в Telegram только о состояниях, требующих реакции:

1. workflow автоматического candidate-выпуска завершился ошибкой или был отменён;
2. опубликованный candidate не получил соответствующий proven дольше допустимого времени;
3. production-canary завершился ошибкой, включая отдельную повышенную критичность, если не удался и возврат на предыдущий proven.

Сам наблюдатель не должен изменять релизы, canary, конфигурацию Xray или парк узлов. Его единственная запись во внешнюю систему — операторское сообщение в Telegram.

Источники истины

• Структурированное состояние Forgejo Actions владеет результатом candidate.yml. Сначала наблюдатель читает публичный Actions API. Если Forgejo показывает запуски в web-интерфейсе, но API возвращает пустой workflow_runs, используется ограниченный read-only fallback: страница именно candidate.yml выбирает последний запуск main, а detail-страница отдаёт встроенный JSON state.run. Иконки и локализованный HTML-текст не считаются доказательством результата. Успешный запуск закрывает ранее зарегистрированный сбой; незавершённый запуск считается pending только до общего stall-порога, после чего становится проблемой runner.
• Forgejo Releases API и манифест candidate владеют связью candidate -> proven. Задержка считается от published_at, а не от времени локального опроса. Уже опубликованный proven немедленно снимает задержку.
• /var/lib/vpnbot-xray-release-promoter/*.json владеет результатом живого пилота. Фазы failed_rolled_back и failed_rollback_failed являются canary-инцидентами. Фазы повторной установки, проверки и продвижения — переходные: во время них прежнее уведомление ещё нельзя объявлять восстановленным.
• /var/lib/vpnbot-xray-release-alert/state.json владеет только жизненным циклом операторских уведомлений: что уже отправлялось, когда была последняя попытка и когда состояние действительно восстановилось. Он не становится источником истины для самого выпуска.

Архитектура

Один root-only systemd timer раз в пять минут запускает один oneshot-процесс. Процесс берёт неблокирующую файловую блокировку, получает общий снимок Forgejo, читает локальные состояния промоутера и вычисляет три независимых условия:

• patch_pipeline;
• candidate_stalled;
• canary_failed.

Для каждого условия возможны три результата:

• problem — подтверждён новый или продолжающийся инцидент;
• healthy — источник истины подтверждает восстановление;
• pending — идёт новый workflow или повторный пилот, поэтому прежний инцидент пока нельзя закрывать.

waiting, queued или другой переходный статус не может оставаться безмолвным бесконечно. После общего stall-порога наблюдатель публикует операторскую проблему с идентификатором запуска и предлагает проверить регистрацию runner, его состояние online и обязательную метку linux.

У каждого инцидента есть детерминированная сигнатура: идентификатор Actions- запуска либо набор candidate-тегов и стадий. Новая сигнатура создаёт обновление аварии, та же сигнатура не порождает повторное сообщение при каждом опросе.

Доставка и дедупликация

Перед сетевой попыткой наблюдатель атомарно сохраняет её время. После подтверждённого ответа Telegram Bot API он сохраняет message_id и время успешной доставки. Это даёт следующие правила:

• первое сообщение отправляется один раз при переходе в проблему;
• после неоднозначной сетевой ошибки немедленного шторма повторов нет: новая попытка разрешается только после отдельного интервала повторной доставки;
• для долгого неустранённого инцидента допускается редкое напоминание;
• сообщение о восстановлении отправляется только после подтверждённого healthy и само повторяется безопасно, пока Telegram не подтвердит доставку;
• смена одной неуспешной попытки выпуска другой не создаёт ложную пару «восстановлено -> снова сломано», а обновляет действующий класс инцидента.

Telegram Bot API не предоставляет ключ идемпотентности для sendMessage, поэтому абсолютно исключить дубль при редком сценарии «Telegram принял сообщение, но ответ потерялся» невозможно. Долговечное время попытки и большой интервал повтора ограничивают этот случай одним редким повтором, а обычные systemd-запуски полностью дедуплицируются.

Сетевой путь до Telegram

На production-хосте нет IPv6-маршрута, а часть IPv4-адресов Telegram заблокирована: прямой urlopen тратил весь таймаут на мёртвый IPv4 и падал ENETUNREACH на IPv6, поэтому ни авария, ни восстановление не доставлялись. Наблюдатель не заводит собственной сетевой политики и не импортирует код бота: он читает тот же контракт, что и все процессы, владеющие ботом (_BOT_IDENTITY в deployment/service_env_profiles.py VPnBot), из того же root-only runtime-env, откуда берёт токен:

• VPNBOT_TELEGRAM_IP_FAMILY — семейство адресов (пусто/ipv4 по умолчанию, auto, ipv6); неизвестное значение — отказ telegram_egress_config_invalid;
• VPNBOT_TELEGRAM_API_FALLBACK_IPV4S — резервные IPv4 Bot API;
• VPNBOT_TELEGRAM_EGRESS_HEALTH_PATH — путь проекции relay (по умолчанию /run/vpnbot-node-manager/telegram-egress.json, владелец — node manager).

Порядок маршрутов повторяет бота (telegram_egress.py, telegram_client.py): свежая (не старше 45 с по updated_at_monotonic) проекция со здоровыми портами api.telegram.org — только эти loopback-relay; иначе резервные IPv4, затем DNS выбранного семейства. Меняется только TCP-адрес: TLS несёт SNI api.telegram.org и проверяет его сертификат.

Следующий маршрут пробуется только если соединение не установилось (TCP или TLS) — запрос ещё не ушёл. Если запрос ушёл, а полного ответа нет, это telegram_delivery_ambiguous, и в этом запуске он не повторяется: у sendMessage нет ключа идемпотентности. Коды отказа: telegram_no_route, telegram_connect_failed, telegram_delivery_ambiguous, telegram_http_status, telegram_response_invalid, telegram_rejected.

Безопасность

• Токен бота не копируется в новый файл. Наблюдатель читает только VPNBOT_BOT_TOKEN из существующего root-only runtime-env VPnBot.
• Chat ID, URL API, интервалы и пути лежат в отдельном root-only /etc/vpnbot-xray-release-alert.env.
• Состояние и lock имеют режим 0600, каталог состояния — 0700.
• Forgejo-релизы и Actions публичного patch-репозитория читаются без write-токена промоутера.
• systemd запрещает повышение привилегий, запись в систему и запись в домашние каталоги; разрешён только каталог состояния наблюдателя.
• Некорректный JSON, небезопасный путь, неизвестная структура API или ошибка чтения не переводятся в «всё исправилось». Процесс завершается ошибкой, а предыдущее активное состояние остаётся сохранённым.

Проверка и выпуск

1. Unit-тестами проверить классификацию Actions, пустой публичный API при существующем структурированном web-run, зависший runner, задержку candidate, canary-фазы, незакрытие инцидента во время retry, дедупликацию, напоминание и восстановление.
2. Прогнать полную существующую проверку репозитория патчей и сборку поверх официального Xray.
3. Опубликовать один commit в Forgejo и дождаться успешных ci.yml и candidate.yml.
4. Установить service/timer на production, создать только конфигурационный env без секретов и отправить явно помеченное тестовое сообщение оператору.
5. Запустить обычную проверку в текущем здоровом состоянии: новых аварийных сообщений быть не должно, unit должен завершиться успешно, состояние должно зафиксировать три здоровых условия.
6. Обновить проектный навык сопровождения Xray: зафиксировать новые unit, runtime-пути, значения состояний и команды проверки.