rate-limit-redis

Installation

From the npm registry:

# Using npm
> npm install rate-limit-redis
# Using yarn or pnpm
> yarn/pnpm add rate-limit-redis

From Github Releases:

# Using npm
> npm install https://github.com/express-rate-limit/rate-limit-redis/releases/download/v{version}/rate-limit-redis.tgz
# Using yarn or pnpm
> yarn/pnpm add https://github.com/express-rate-limit/rate-limit-redis/releases/download/v{version}/rate-limit-redis.tgz

Replace {version} with the version of the package that you want to use, e.g.: 3.0.0.

Usage

Importing

This library is provided in ESM as well as CJS forms, and works with both Javascript and Typescript projects.

This package requires you to use Node 16 or above and Redis 2.6.12 or above.

Import it in a CommonJS project (type: commonjs or no type field in package.json) as follows:

const { RedisStore } = require('rate-limit-redis')

Import it in a ESM project (type: module in package.json) as follows:

import { RedisStore } from 'rate-limit-redis'

Examples

To use it with a node-redis client:

import { rateLimit } from 'express-rate-limit'
import { RedisStore } from 'rate-limit-redis'
import { createClient } from 'redis'

// Create a `node-redis` client
const client = createClient({
	// ... (see https://github.com/redis/node-redis/blob/master/docs/client-configuration.md)
})
// Then connect to the Redis server
await client.connect()

// Create and use the rate limiter
const limiter = rateLimit({
	// Rate limiter configuration
	windowMs: 15 * 60 * 1000, // 15 minutes
	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
	legacyHeaders: false, // Disable the `X-RateLimit-*` headers

	// Redis store configuration
	store: new RedisStore({
		sendCommand: (...args: string[]) => client.sendCommand(args),
	}),
})
app.use(limiter)

To use it with a ioredis client:

import { rateLimit } from 'express-rate-limit'
import { RedisStore, type RedisReply } from 'rate-limit-redis'
import RedisClient from 'ioredis'

// Create a `ioredis` client
const client = new RedisClient() // see https://github.com/luin/ioredis#connect-to-redis

// Create and use the rate limiter
const limiter = rateLimit({
	// Rate limiter configuration
	windowMs: 15 * 60 * 1000, // 15 minutes
	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
	legacyHeaders: false, // Disable the `X-RateLimit-*` headers

	// Redis store configuration
	store: new RedisStore({
		sendCommand: (command: string, ...args: string[]) =>
			client.call(command, ...args) as Promise<RedisReply>,
	}),
})
app.use(limiter)

Configuration

sendCommand

The function used to send commands to Redis. The function signature is as follows:

;(...args: string[]) => Promise<RedisReply>

args contains the Redis command name followed by its arguments. For example, sendCommand('SCRIPT', 'LOAD', script) loads a Lua script. The adapter forwards these arguments to your Redis client and returns its reply. RedisReply is exported by rate-limit-redis and includes strings, numbers, booleans, and arrays of those values:

type Data = boolean | number | string
export type RedisReply = Data | Data[]

Clients accept raw commands in different forms. node-redis takes the entire command as an array (client.sendCommand(args)), while ioredis takes the command name followed by separate arguments (client.call(command, ...args)).

The raw command sending function varies from library to library; some are given below:

sendCommandCluster

In cluster mode, node-redis requires a little extra information to help route the command to the correct server. This is an alternative to sendCommand that provides the necessary extra information. The signature is as follows:

({key?: string, isReadOnly: boolean, command: string[]}) => Promise<RedisReply>
// or
(commandDetails: SendCommandClusterDetails) => Promise<RedisReply>

SendCommandClusterDetails is exported by rate-limit-redis. It contains command, an array with the command name and arguments; isReadOnly, which indicates whether the command only reads data; and an optional key, which helps the client choose the cluster node.

export type SendCommandClusterDetails = {
    key?: string
    isReadOnly: boolean
    command: string[]
}

Example usage:

import { rateLimit } from 'express-rate-limit'
import {
	RedisStore,
	type RedisReply,
	type SendCommandClusterDetails,
} from 'rate-limit-redis'
import { createCluster } from 'redis'

// Create a `node-redis` cluster client
const cluster = new createCluster({
	// see https://github.com/redis/node-redis/blob/master/docs/clustering.md
})

// Create and use the rate limiter
const limiter = rateLimit({
	// Rate limiter configuration here

	// Redis store configuration
	store: new RedisStore({
		sendCommandCluster: ({
			key,
			isReadOnly,
			command,
		}: SendCommandClusterDetails) =>
			cluster.sendCommand(key, isReadOnly, command) as Promise<RedisReply>,
	}),
})
app.use(limiter)

ioredis cluster

ioredis needs a bit more complex sendCommandCluster function:

import { rateLimit } from 'express-rate-limit'
import { RedisStore, type RedisReply } from 'rate-limit-redis'
import RedisClient from 'ioredis'

// Create a `ioredis` client
const client = new RedisClient() // see https://github.com/luin/ioredis#connect-to-redis

// Create and use the rate limiter
const limiter = rateLimit({
	// Rate limiter configuration
	windowMs: 15 * 60 * 1000, // 15 minutes
	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
	legacyHeaders: false, // Disable the `X-RateLimit-*` headers

	// Redis store configuration
	store: new RedisStore({
		sendCommandCluster: async ({ command }: SendCommandClusterDetails) => {
			// If SCRIPT LOAD command, send it to all master nodes
			if (command[0] === 'SCRIPT' && command[1] === 'LOAD') {
				const nodes = client.nodes('master')
				const results = await Promise.all(
					nodes.map(async (node) => node.call(command[0], ...command.slice(1))),
				)
				// Return the result from one of them (they should be identical)
				return results[0] as RedisReply
			}
			// All other commands
			const result = await client.call(command[0], ...command.slice(1))
			return result as RedisReply
		},
	}),
})
app.use(limiter)

prefix

The text to prepend to the key in Redict/Redis.

Defaults to rl:.

License

MIT © Wyatt Johnson, Nathan Friedly, Vedant K