🐢 Троттлинг

Ограничивайте частоту хендлеров, чтобы пользователи не заваливали бота. В Raito есть глобальный лимит, лимиты на отдельный хендлер и три режима области действия.

Глобальный троттлинг

add_throttling() ставит один лимит на все сообщения и колбэк-запросы:

raito = Raito(dispatcher, "handlers")
raito.add_throttling(1.2, mode="user")

Теперь один и тот же пользователь может вызывать любой хендлер не чаще раза в 1,2 секунды. Режим по умолчанию "chat".

Лимиты на хендлер

Для конкретного хендлера примените @rt.limiter:

from aiogram import filters, types
from raito import rt


@router.message(filters.Command("export"))
@rt.limiter(rate_limit=5.0, mode="user")
async def export(message: types.Message) -> None:
    ...

Его режим по умолчанию "user". Хендлер с @rt.limiter использует только собственный лимит и обходит глобальный, поэтому одну тяжёлую команду можно сделать строже (или мягче) остальных, не трогая общее правило.

Режимы

Режим	Кулдаун общий для…
"user"	одного пользователя (во всех чатах).
"chat"	одного чата (кулдаун общий для всех участников).
"bot"	всех сразу: единый глобальный кулдаун на всего бота.

Поведение и ограничения

• Заглушённый апдейт молча отбрасывается: хендлер не вызывается, а пользователь не получает ошибки. Держите лимиты достаточно короткими, чтобы это не выглядело поломкой.

• Лимиты держатся на cachetools.TTLCache; add_throttling принимает max_size (по умолчанию 10_000), ограничивая число отслеживаемых ключей.

• Лимит на хендлер запоминается по его идентичности, поэтому частота фиксируется при первом использовании: смена rate_limit для того же хендлера на лету вступит в силу только после перезапуска.