Перейти к основному содержимому

Lifecycle бота

stateDiagram-v2
    [*] --> active: POST /api/bots
    active --> suspended: owner Suspend
    suspended --> active: owner Resume
    active --> deleted: owner Delete
    deleted --> [*]

Бот создаётся сразу в active (промежуточного draft нет). Значения draft и revoked объявлены в enum состояний, но в текущей реализации никогда не присваиваются — авто-перехода в revoked по факту утечки токена платформа не делает (см. ниже).

Состояния​

draft

Зарезервированное значение enum — в текущей реализации не используется. Бот сразу создаётся в active, промежуточного draft-состояния нет.

active

Нормальное состояние. Все API-вызовы работают, webhook events доставляются.

suspended

Временно выключен. Токен проходит проверку подписи, но любое действие бота возвращает 403 Forbidden (detail="bot is suspended"). Webhook delivery приостановлено. Можно вернуть в active.

revoked

Зарезервированное значение enum — в текущей реализации не присваивается (нет авто-отзыва по утечке токена). Если бы бот оказался в этом состоянии, его действия так же давали бы 403 Forbidden. Компрометация обрабатывается ручной ротацией токена.

deleted

Soft-deleted (state=deleted, есть deleted_at). Не виден в listings; токены отозваны (revoked_at), любое действие бота → 403 Forbidden. Через ~30 дней — hard-purge (cron) с физическим удалением строк.

Переходы​

Owner Suspend​

POST /api/bots/{bot_user_id}/suspend
Authorization: Bearer <owner_jwt>

→ state=suspended. Все токены сразу инвалидны.

Owner Resume​

POST /api/bots/{bot_user_id}/resume
Authorization: Bearer <owner_jwt>

→ обратно в active.

Token rotation (не lifecycle, но рядом)​

POST /api/bots/{bot_user_id}/tokens/rotate
Authorization: Bearer <owner_jwt>

Старый token revoked, новый plaintext возвращается. Использовать когда:

  • Подозрение на leak
  • Регулярная ротация по политике безопасности
  • Compromised dev environment

Автоматические действия платформы​

TriggerЧто происходит
5 неуспешных доставок webhook подрядWebhook auto-suspended на 24 часа (токен не трогается)
Owner пытается удалить свой аккаунт при живых ботахБлокируется на уровне БД: FK owner_user_id = ondelete=RESTRICT. Каскадного удаления ботов вместе с владельцем нет — сначала нужно удалить ботов вручную.

Автоматического отзыва токена по факту утечки платформа не выполняет: нет интеграции с GitHub Secret Scanning и нет OAuth-refresh-rotation для ботов. При компрометации токена ротируйте его вручную — POST /api/bots/{bot_user_id}/tokens/rotate (см. static-токены).

Что происходит с webhook'ами​

При suspended / revoked / deleted:

  • Pending delivery'и в очереди — отменяются
  • Новые events не доставляются
  • При возврате в active (только из suspended) — webhook delivery возобновляется

При delete (это soft-delete, не физическое удаление):

  • Бот помечается state=deleted + deleted_at=now (строка bots остаётся в БД)
  • Все токены инвалидируются (revoked_at проставляется через revoke_all_for_bot)
  • BotMembership / BotWebhooks / BotAuditLog остаются в БД до hard-purge
  • Физическое каскадное удаление этих строк (ON DELETE CASCADE) срабатывает только при hard-purge (cron, ~30 дней), когда удаляется сама строка bots, а не в момент DELETE

Notification owner'у​

Будут (T2-7.2): email на каждое:

  • Suspend / Resume / Delete (юзер сам инициировал, но напоминание)
  • Webhook auto-suspended (после 5 failed delivery cycles)

Сейчас — только лог в audit, без notification.