Koa Rate Limit Middleware

Common errors

• TypeError: db is not a Map instance or Redis client

  cause The `db` option was either omitted or provided an invalid type for the configured `driver`.
  fix Ensure `db` is an instance of `Map` when `driver: 'memory'` or an `ioredis` client instance when `driver: 'redis'`.

• Error: Cannot find module 'ioredis'

  cause The `ioredis` package is required for the Redis driver but was not installed in the project's dependencies.
  fix Install `ioredis` explicitly: `npm install ioredis`.

• ReferenceError: Koa is not defined

  cause The Koa framework itself was not imported or installed, which is necessary for the middleware to function within a Koa application.
  fix Install `koa` and import it using `const Koa = require('koa');` at the top of your application file.

Warnings

• breaking Version 6.0.0 and above of `koa-ratelimit` explicitly require Node.js v18 or newer. Deployments on older Node.js environments will fail with engine incompatibility errors.
  Fix: Upgrade your Node.js runtime to version 18 or a later compatible version before upgrading to `koa-ratelimit@6`.
• gotcha The `Retry-After` HTTP header is automatically set in 429 'Too Many Requests' responses since `v5.1.0` when a limit is exceeded and an error is thrown. This provides clients with a standardized time (in seconds) to wait before retrying. Ensure your client-side error handling is prepared to interpret this header.
  Fix: Clients consuming your API should read the `Retry-After` header from 429 responses and respect the specified delay before making subsequent requests.
• gotcha The `onLimited` callback function, which allows custom logic to execute when a request is rate-limited, was fixed in `v6.0.0` to ensure correct functionality. If you were using this callback in earlier `v5.x` versions, its behavior might have been inconsistent or broken.
  Fix: If upgrading from an earlier `v5.x` version, review and re-test any custom logic within your `onLimited` callback to ensure it behaves as expected after the `v6.0.0` update.
• gotcha The `db` option is mandatory and must be an appropriate instance for the chosen `driver` (`Map` for 'memory', `ioredis` client for 'redis'). Providing an incorrect or uninitialized `db` will lead to runtime errors when the middleware attempts to store or retrieve rate limit data.
  Fix: Always initialize `db` correctly, e.g., `db: new Map()` for memory or `db: new Redis()` (assuming `ioredis`) for Redis.

Install

• npm install koa-ratelimit npm
• yarn add koa-ratelimit yarn
• pnpm add koa-ratelimit pnpm

Imports

• ratelimit
  wrong:

  import ratelimit from 'koa-ratelimit';

  correct:

  const ratelimit = require('koa-ratelimit');

  As of v6.0.0, the package's primary export for common usage remains a CommonJS default export. While Node.js v18+ supports ESM, the provided examples and typical usage patterns still rely on `require()`.
• Koa
  wrong:

  import Koa from 'koa';

  correct:

  const Koa = require('koa');

  Koa itself is typically imported via `require()` in most Koa middleware examples, maintaining consistency with CommonJS module loading.
• Redis
  wrong:

  import { Redis } from 'ioredis';

  correct:

  const Redis = require('ioredis');

  The `ioredis` client, used for the Redis driver, is usually imported as a default export via `require()`.

Quickstart

This quickstart demonstrates how to set up `koa-ratelimit` with a Redis backend to limit requests by IP address, including custom error messages, headers, and a whitelist.

const Koa = require('koa');
const ratelimit = require('koa-ratelimit');
const Redis = require('ioredis');
const app = new Koa();

// Initialize Redis client for rate limiting storage
const redisClient = new Redis();

// Apply rate limit middleware
app.use(ratelimit({
  driver: 'redis',
  db: redisClient, // Pass the ioredis client instance
  duration: 60000, // 1 minute
  errorMessage: 'You have sent too many requests. Please try again later.',
  id: (ctx) => ctx.ip, // Identify clients by their IP address
  headers: {
    remaining: 'X-Rate-Limit-Remaining',
    reset: 'X-Rate-Limit-Reset',
    total: 'X-Rate-Limit-Total'
  },
  max: 100, // Max 100 requests per minute
  disableHeader: false,
  whitelist: (ctx) => {
    // Example: allow localhost to bypass rate limiting
    return ctx.ip === '127.0.0.1';
  },
  onLimited: (ctx) => {
    console.log(`Rate limited IP: ${ctx.ip} for path ${ctx.path}`);
  }
}));

// Response middleware for successful requests
app.use(async (ctx) => {
  ctx.body = 'Hello, Koa! This is an un-rate-limited response.';
});

// Start the server
app.listen(3000,
  () => console.log('Koa server listening on http://localhost:3000')
);