Telegraf Throttler

Throttling middleware for Telegraf bot framework, written in Typescript and built with Bottleneck.

Installation

npm install telegraf-throttler
# or
yarn add telegraf-throttler

About

This throttler aims to throttle incoming updates from Telegram, and outgoing calls to the Telegram API. The incoming throttler aims to protect the bot from abuses (e.g. user forwarding tons of messages to the bot to flood it), while the outgoing throttler aims to limit and queue outgoing Telegram API calls to conform to the official Telegram API rate limits.

Configuration

The throttler accepts a single optional argument of the following form:

type ThrottlerOptions = {
  group?: Bottleneck.ConstructorOptions,      // For throttling outgoing group messages
  in?: Bottleneck.ConstructorOptions,         // For throttling incoming messages
  out?: Bottleneck.ConstructorOptions,        // For throttling outgoing private messages
  inKey?: 'from' | 'chat',                    // Throttle inbound by from.id (default) or chat.id
  inThrottlerError?: InThrottlerErrorHandler, // For custom inThrottler error handling
}

The full list of object properties available for Bottleneck.ConstructorOptions can be found at Bottleneck.

If no argument is passed, the throttler created will use the default configuration settings which should be appropriate for most use cases. The default configuration are as follows:

// Outgoing Group Throttler
const groupConfig = {
  maxConcurrent: 1,                // Only 1 job at a time
  minTime: 333,                    // Wait this many milliseconds to be ready, after a job
  reservoir: 20,                   // Number of new jobs that throttler will accept at start
  reservoirRefreshAmount: 20,      // Number of jobs that throttler will accept after refresh
  reservoirRefreshInterval: 60000, // Interval in milliseconds where reservoir will refresh
};

// Incoming Throttler
const inConfig = {
  highWater: 3,                       // Trigger strategy if throttler is not ready for a new job
  maxConcurrent: 1,                   // Only 1 job at a time
  minTime: 333,                       // Wait this many milliseconds to be ready, after a job
  strategy: Bottleneck.strategy.LEAK, // Drop jobs if throttler is not ready
}

// Outgoing Private Throttler
const outConfig = {
  minTime: 25,                    // Wait this many milliseconds to be ready, after a job
  reservoir: 30,                  // Number of new jobs that throttler will accept at start
  reservoirRefreshAmount: 30,     // Number of jobs that throttler will accept after refresh
  reservoirRefreshInterval: 1000, // Interval in milliseconds where reservoir will refresh
};

// Default Error Handler
const defaultErrorHandler = async (ctx, next, error) => {
  return console.warn(`Inbound ${ctx.from?.id || ctx.chat?.id} | ${error.message}`)
};

Example

// Simple use case (Typescript)
import { Telegraf } from 'telegraf';
import { telegrafThrottler } from 'telegraf-throttler';

const bot = new Telegraf(process.env.BOT_TOKEN);

const throttler = telegrafThrottler();
bot.use(throttler);

bot.command('/example', ctx => ctx.reply('I am throttled'));
bot.launch();

// Simple use case (Javascript)
const { Telegraf } = require('telegraf');
const { telegrafThrottler } = require('telegraf-throttler');

const bot = new Telegraf(process.env.BOT_TOKEN);

const throttler = telegrafThrottler();
bot.use(throttler);

bot.command('/example', ctx => ctx.reply('I am throttled'));
bot.launch();

// Custom use case (Typescript)
import { Composer, Context, Middleware, Telegraf } from 'telegraf';
import { telegrafThrottler } from 'telegraf-throttler';

const bot = new Telegraf(process.env.BOT_TOKEN);

const privateThrottler = telegrafThrottler();
const groupThrottler = telegrafThrottler({
  in: { // Aggresively drop inbound messages
    highWater: 0,                       // Trigger strategy if throttler is not ready for a new job
    maxConcurrent: 1,                   // Only 1 job at a time
    minTime: 30000,                      // Wait this many milliseconds to be ready, after a job
  },
  inKey: 'chat', // Throttle inbound messages by chat.id instead
});

const partitioningMiddleware: Middleware<Context> = (ctx, next) => {
  const chatId = Number(ctx.chat?.id);
  return Composer.optional(() => chatId < 0, groupThrottler, privateThrottler)(ctx, next);
};
bot.use(partitioningMiddleware);

bot.command('/example', ctx => ctx.reply('I am seriously throttled!'));
bot.launch();