umbot
    Preparing search index...

    Function rateLimiter

    • Создаёт middleware для ограничения частоты входящих запросов (rate limiting) на уровне платформы.

      Для чего используется: Некоторые платформы (например, Max, Telegram, VK, Viber — их адаптеры задают limit = 30) имеют ограничение на количество отправляемых запросов в секунду. Данный middleware защищает от превышения этого лимита, автоматически задерживая запросы, если они поступают слишком часто.

      Как это работает:

      • Лимит берётся из свойства limit адаптера платформы (platformAdapter.limit). Если свойство не задано или равно 0, ограничение не применяется.
      • Для каждой комбинации {platform}:{userId} ведётся отдельная очередь и счётчик запросов.
      • Счётчик обнуляется при первом запросе спустя секунду после предыдущего сброса, что позволяет соблюдать лимит в секундном (фиксированном) окне.
      • Если лимит исчерпан, запрос помещается в очередь и будет выполнен, когда появится свободное «окно».
      • Очередь имеет максимальный размер (maxQueueSize); при переполнении выбрасывается исключение RateLimitQueueOverflowError, а в ctx.platformOptions.rateLimitOverflow выставляется флаг: исключение перехватывается ядром как «обработка прервана» (платформа получит 200), поэтому флаг — способ понять, что запрос отклонён из-за перегрузки.
      • Запросы в очереди выполняются с равномерной задержкой (⌈1000/limit⌉ − 1 мс), чтобы не превышать лимит.
      • Неактивные записи (без запросов дольше inactivityTimeout) автоматически удаляются из памяти.

      Важные особенности:

      • Middleware применяется только к входящим запросам (webhook). Для исходящих уведомлений ограничение нужно реализовывать непосредственно в адаптерах платформ.
      • Счётчик ведётся отдельно для каждой пары {platform}:{userId}, то есть ограничивается частота запросов одного пользователя, а не суммарная нагрузка на бота.
      • Запрос, попавший в очередь, задерживается минимум на секунду. У платформ есть свой таймаут на ответ вебхука (у Алисы — около 2.9 секунд, MAX_TIME_REQUEST), поэтому включайте middleware осознанно: при срабатывании лимита платформа может не дождаться ответа.
      • Функцию необходимо вызвать при подключении: bot.use(rateLimiter()).
      • Все внутренние таймеры используют unref(), поэтому не блокируют завершение процесса.

      Parameters

      • maxQueueSize: number = 100

        Максимальное количество ожидающих запросов в очереди для одного ключа (по умолчанию 100). При превышении очередь перестаёт принимать новые запросы и выбрасывается исключение.

      • inactivityTimeout: number = 60000

        Время в миллисекундах, после которого запись (очередь + счётчик) удаляется, если не было активности. По умолчанию 60000 (1 минута).

      • OptionalgetKey: (ctx: BotController) => string

        Ключ счётчика для запроса. По умолчанию {platform}:{userId}. На платформах без подписи вебхука (Алиса, Маруся, SmartApp) и без заданного секрета userId задаёт отправитель: меняя его, атакующий обходит лимит на пользователя. Ключ ctx => ctx.appType ?? '' ограничивает суммарную нагрузку на платформу.

      Returns (ctx: BotController, next: MiddlewareNext) => Promise<void>

      Middleware-функцию для использования в bot.use().

      import { rateLimiter } from 'umbot/middleware';

      // Подключаем middleware с параметрами по умолчанию
      bot.use(rateLimiter());

      // Или с кастомными настройками
      bot.use(rateLimiter(200, 120000));

      // Общий лимит на платформу, а не на пользователя
      bot.use(rateLimiter(100, 60000, (ctx) => ctx.appType ?? ''));

      Чтобы лимит заработал для вашей платформы, добавьте в соответствующий адаптер публичное поле limit:

      export class TelegramAdapter extends BasePlatformAdapter {
        public limit = 30;
        // ...
      }

    Settings

    Member Visibility