What is rate-limiter-flexible?
The rate-limiter-flexible npm package is a powerful and flexible rate limiting library for Node.js. It supports various backends like Redis, MongoDB, and in-memory storage, making it suitable for distributed systems. It helps in controlling the rate of requests to APIs, preventing abuse, and ensuring fair usage.
What are rate-limiter-flexible's main functionalities?
Basic Rate Limiting
This feature allows you to set up basic rate limiting using in-memory storage. The example limits a user to 5 requests per second.
const { RateLimiterMemory } = require('rate-limiter-flexible');
const rateLimiter = new RateLimiterMemory({
points: 5, // 5 points
duration: 1, // Per second
});
rateLimiter.consume('user-key')
.then(() => {
// Allowed
})
.catch(() => {
// Blocked
});
Rate Limiting with Redis
This feature demonstrates how to use Redis as a backend for rate limiting. The example limits a user to 10 requests per minute.
const { RateLimiterRedis } = require('rate-limiter-flexible');
const Redis = require('ioredis');
const redisClient = new Redis();
const rateLimiter = new RateLimiterRedis({
storeClient: redisClient,
points: 10, // 10 points
duration: 60, // Per minute
});
rateLimiter.consume('user-key')
.then(() => {
// Allowed
})
.catch(() => {
// Blocked
});
Rate Limiting with MongoDB
This feature shows how to use MongoDB as a backend for rate limiting. The example limits a user to 5 requests per minute.
const { RateLimiterMongo } = require('rate-limiter-flexible');
const mongoose = require('mongoose');
mongoose.connect('mongodb://localhost:27017/rate-limiter', { useNewUrlParser: true, useUnifiedTopology: true });
const rateLimiter = new RateLimiterMongo({
storeClient: mongoose.connection,
points: 5, // 5 points
duration: 60, // Per minute
});
rateLimiter.consume('user-key')
.then(() => {
// Allowed
})
.catch(() => {
// Blocked
});
Rate Limiting with Bursts
This feature allows for burst handling by blocking the user for a specified duration if they exceed the rate limit. The example blocks a user for 10 seconds if they exceed 10 requests per second.
const { RateLimiterMemory } = require('rate-limiter-flexible');
const rateLimiter = new RateLimiterMemory({
points: 10, // 10 points
duration: 1, // Per second
blockDuration: 10, // Block for 10 seconds if consumed more than points
});
rateLimiter.consume('user-key')
.then(() => {
// Allowed
})
.catch(() => {
// Blocked
});
Other packages similar to rate-limiter-flexible
express-rate-limit
express-rate-limit is a basic rate-limiting middleware for Express applications. It is simpler and less flexible compared to rate-limiter-flexible, but it is easier to set up for basic use cases.
rate-limiter
rate-limiter is another rate limiting library for Node.js. It is less feature-rich compared to rate-limiter-flexible and does not support as many backends, but it is straightforward to use for simple rate limiting needs.
bottleneck
bottleneck is a powerful rate limiting and job scheduling library for Node.js. It offers more advanced features like priority queues and job scheduling, making it more suitable for complex use cases compared to rate-limiter-flexible.
node-rate-limiter-flexible
Flexible rate limiter and anti-DDoS protector works in process
Memory, Cluster, MongoDB, MySQL, PostgreSQL or Redis allows to control requests rate in single process or distributed environment.
It uses fixed window as it is much faster than rolling window.
See comparative benchmarks with other libraries here
:star: It is STARving, don't forget to feed the beast! :star:
Advantages:
Example
const opts = {
points: 6,
duration: 1,
};
const rateLimiter = new RateLimiterMemory(opts);
rateLimiter.consume(remoteAddress, 2)
.then((rateLimiterRes) => {
})
.catch((rateLimiterRes) => {
});
Links
Benchmark
Average latency during test pure NodeJS endpoint in cluster of 4 workers with everything set up on one server.
1000 concurrent clients with maximum 2000 requests per sec during 30 seconds.
1. Memory 0.34 ms
2. Cluster 0.69 ms
3. Redis 2.45 ms
4. Mongo 4.75 ms
500 concurrent clients with maximum 1000 req per sec during 30 seconds
5. PostgreSQL 7.48 ms (with connection pool max 100)
6. MySQL 14.59 ms (with connection pool 100)
Installation
npm i rate-limiter-flexible
yarn add rate-limiter-flexible
Options
-
keyPrefix
Default: 'rlflx'
If you need to create several limiters for different purpose.
Note: for some limiters it should correspond to Storage requirements for tables or collections name,
as keyPrefix
may be used as their name.
-
points
Default: 4
Maximum number of points can be consumed over duration
-
duration
Default: 1
Number of seconds before consumed points are reset
-
execEvenly
Default: false
Delay action to be executed evenly over duration
First action in duration is executed without delay.
All next allowed actions in current duration are delayed by formula msBeforeDurationEnd / (remainingPoints + 2)
It allows to cut off load peaks.
Note: it isn't recommended to use it for long duration, as it may delay action for too long
-
blockDuration
Default: 0
If positive number and consumed more than points in current duration,
block for blockDuration
seconds.
It sets consumed points more than allowed points for blockDuration
seconds, so actions are rejected.
Options specific to Redis, Mongo, MySQL, PostgreSQL
-
storeClient
Required
Have to be redis
, ioredis
, mongodb
, pg
, mysql2
, mysql
or any other related pool or connection.
-
inmemoryBlockOnConsumed
Default: 0
Against DDoS attacks. Blocked key isn't checked by requesting Redis, MySQL or Mongo.
In-memory blocking works in current process memory.
-
inmemoryBlockDuration
Default: 0
Block key for inmemoryBlockDuration
seconds,
if inmemoryBlockOnConsumed
or more points are consumed
-
insuranceLimiter
Default: undefined
Instance of RateLimiterAbstract extended object to store limits,
when database comes up with any error.
All data from insuranceLimiter
is NOT copied to parent limiter, when error gone
Note: insuranceLimiter
automatically setup blockDuration
and execEvenly
to same values as in parent to avoid unexpected behaviour
Options specific to MySQL and PostgreSQL
-
tableName
Default: equals to 'keyPrefix' option
By default, limiter creates table for each unique keyPrefix
.
All limits for all limiters are stored in one table if custom name is set.
-
storeType
Default: storeClient.constructor.name
It is required only for Knex and have to be set to 'knex'
Options specific to MySQL
dbName
Default: 'rtlmtrflx'
Database where limits are stored. It is created during creating a limiter
Options specific to Cluster
timeoutMs
Default: 5000
Timeout for communication between worker and master over IPC.
If master doesn't response in time, promise is rejected with Error
API
RateLimiterRes object
Both Promise resolve and reject returns object of RateLimiterRes
class if there is no any error.
Object attributes:
RateLimiterRes = {
msBeforeNext: 250,
remainingPoints: 0,
consumedPoints: 5,
isFirstInDuration: false,
}
rateLimiter.consume(key, points = 1)
Returns Promise, which:
- resolved with
RateLimiterRes
when point(s) is consumed, so action can be done - rejected only for database limiters if
insuranceLimiter
isn't setup: when some error happened, where reject reason rejRes
is Error object - rejected only for RateLimiterCluster if
insuranceLimiter
isn't setup: when timeoutMs
exceeded, where reject reason rejRes
is Error object - rejected when there is no points to be consumed, where reject reason
rejRes
is RateLimiterRes
object - rejected when key is blocked (if block strategy is set up), where reject reason
rejRes
is RateLimiterRes
object
Arguments:
key
is usually IP address or some unique client idpoints
number of points consumed. default: 1
rateLimiter.get(key)
Get RateLimiterRes
in current duration.
Returns Promise, which:
- resolved with
RateLimiterRes
if key is set - resolved with
null
if key is NOT set or expired - rejected only for database limiters if
insuranceLimiter
isn't setup: when some error happened, where reject reason rejRes
is Error object - rejected only for RateLimiterCluster if
insuranceLimiter
isn't setup: when timeoutMs
exceeded, where reject reason rejRes
is Error object
Arguments:
key
is usually IP address or some unique client id
rateLimiter.penalty(key, points = 1)
Fine key
by points
number of points for one duration.
Note: Depending on time penalty may go to next durations
Returns Promise, which:
- resolved with
RateLimiterRes
- rejected only for database limiters if
insuranceLimiter
isn't setup: when some error happened, where reject reason rejRes
is Error object - rejected only for RateLimiterCluster if
insuranceLimiter
isn't setup: when timeoutMs
exceeded, where reject reason rejRes
is Error object
rateLimiter.reward(key, points = 1)
Reward key
by points
number of points for one duration.
Note: Depending on time reward may go to next durations
Returns Promise, which:
- resolved with
RateLimiterRes
- rejected only for database limiters if
insuranceLimiter
isn't setup: when some error happened, where reject reason rejRes
is Error object - rejected only for RateLimiterCluster if
insuranceLimiter
isn't setup: when timeoutMs
exceeded, where reject reason rejRes
is Error object
rateLimiter.block(key, secDuration)
Block key
for secDuration
seconds
Returns Promise, which:
- resolved with
RateLimiterRes
- rejected only for database limiters if
insuranceLimiter
isn't setup: when some error happened, where reject reason rejRes
is Error object - rejected only for RateLimiterCluster if
insuranceLimiter
isn't setup: when timeoutMs
exceeded, where reject reason rejRes
is Error object
Usage
RateLimiterRedis
Redis >=2.6.12
It supports both redis
and ioredis
clients.
Redis client must be created with offline queue switched off.
const redis = require('redis');
const redisClient = redis.createClient({ enable_offline_queue: false });
const Redis = require('ioredis');
const redisClient = new Redis({
options: {
enableOfflineQueue: false
}
});
const { RateLimiterRedis, RateLimiterMemory } = require('rate-limiter-flexible');
redisClient.on('error', (err) => {
});
const opts = {
storeClient: redisClient,
points: 5,
duration: 5,
execEvenly: false,
blockDuration: 0,
keyPrefix: 'rlflx',
inmemoryBlockOnConsumed: 10,
inmemoryBlockDuration: 30,
};
const rateLimiterRedis = new RateLimiterRedis(opts);
rateLimiterRedis.consume(remoteAddress)
.then((rateLimiterRes) => {
rateLimiterRedis.penalty(remoteAddress, 3)
.then((rateLimiterRes) => {});
rateLimiterRedis.reward(remoteAddress, 2)
.then((rateLimiterRes) => {});
})
.catch((rejRes) => {
if (rejRes instanceof Error) {
} else {
const secs = Math.round(rejRes.msBeforeNext / 1000) || 1;
res.set('Retry-After', String(secs));
res.status(429).send('Too Many Requests');
}
});
RateLimiterRedis benchmark
Endpoint is pure NodeJS endpoint launched in node:10.5.0-jessie
and redis:4.0.10-alpine
Docker containers by PM2 with 4 workers
By bombardier -c 1000 -l -d 30s -r 2000 -t 5s http://127.0.0.1:8000
Test with 1000 concurrent requests with maximum 2000 requests per sec during 30 seconds
Statistics Avg Stdev Max
Reqs/sec 2015.20 511.21 14570.19
Latency 2.45ms 7.51ms 138.41ms
Latency Distribution
50% 1.95ms
75% 2.16ms
90% 2.43ms
95% 2.77ms
99% 5.73ms
HTTP codes:
1xx - 0, 2xx - 53556, 3xx - 0, 4xx - 6417, 5xx - 0
RateLimiterMemory
It manages limits in current process memory, so keep it in mind when use it in cluster
const rateLimiter = new RateLimiterMemory(
{
keyPrefix: 'rlflx',
points: 1,
duration: 5,
execEvenly: false,
});
RateLimiterUnion
Combine 2 or more rate limiters to act as single
Any rate limiters from this rate-limiter-flexible
can be united
Useful for authorization, which must be protected from password brute force
For example, not more than once per second and only 5 points per minute
keyPrefix
is necessary as resolved and rejected results depend on it
const limiter1 = new RateLimiterMemory({
keyPrefix: 'limit1',
points: 1,
duration: 1,
});
const limiter2 = new RateLimiterMemory({
keyPrefix: 'limit2',
points: 5,
duration: 60,
});
const rateLimiterUnion = new RateLimiterUnion(limiter1, limiter2);
rateLimiterUnion.consume(remoteAddress)
.then((res) => {
res['limit1'].remainingPoints;
res['limit2'].remainingPoints;
})
.catch((rej) => {
});
Express middleware
const rateLimiterMiddleware = (req, res, next) => {
rateLimiter.consume(req.connection.remoteAddress)
.then(() => {
next();
})
.catch((rejRes) => {
res.status(429).send('Too Many Requests');
});
};
Koa middleware
app.use(async (ctx, next) => {
try {
await rateLimiter.consume(ctx.ip)
next()
} catch (rejRes) {
ctx.status = 429
ctx.body = 'Too Many Requests'
}
})
Contribution
Appreciated, feel free!
Make sure you've launched npm run eslint
before creating PR, all errors have to be fixed.
You can try to run npm run eslint-fix
to fix some issues.
Any new limiter with storage have to be extended from RateLimiterStoreAbstract
.
It has to implement at least 3 methods:
_getRateLimiterRes
parses raw data from store to RateLimiterRes
object_upsert
inserts or updates limits data by key and returns raw data_get
returns raw data by key
All other methods depends on store. See RateLimiterRedis
or RateLimiterPostgres
for example.