Node.js atomic and non-atomic counters, rate limiting tools, protection from DoS and brute-force attacks at scale
npm install rate-limiter-flexible
!npm
[![node version][node-image]][node-url]

[node-image]: https://img.shields.io/badge/node.js-%3E=_20.0-green.svg?style=flat-square
[node-url]: http://nodejs.org/download/

rate-limiter-flexible counts and limits the number of actions by key and protects from DoS and brute force attacks at any scale.
It works with _Valkey_, _Redis_, _Prisma_, _DynamoDB_, process _Memory_, _Cluster_ or _PM2_, _Memcached_, _MongoDB_, _MySQL_, _SQLite_, and _PostgreSQL_.
Memory limiter also works in the browser.
Atomic increments. All operations in memory or distributed environment use atomic increments against race conditions.
Fast. Average request takes 0.7ms in Cluster and 2.5ms in Distributed application. See benchmarks.
Flexible. Combine limiters, block key for some duration, delay actions, manage failover with insurance options, configure smart key blocking in memory and many others.
Ready for growth. It provides a unified API for all limiters. Whenever your application grows, it is ready. Prepare your limiters in minutes.
Friendly. No matter which node package you prefer: valkey-glide or iovalkey, redis or ioredis, sequelize/typeorm or knex, memcached, native driver or mongoose. It works with all of them.
In-memory blocks. Avoid extra requests to store with inMemoryBlockOnConsumed.
Deno compatible See this example
It uses a fixed window, as it is much faster than a rolling window.
See comparative benchmarks with other libraries here
npm i --save rate-limiter-flexible
yarn add rate-limiter-flexible
javascript
import { RateLimiterMemory } from "rate-limiter-flexible";
// or import directly
import RateLimiterMemory from "rate-limiter-flexible/lib/RateLimiterMemory.js";
`Basic Example
Points can be consumed by IP address, user ID, authorisation token, API route or any other string.
`javascript
const opts = {
points: 6, // 6 points
duration: 1, // Per second
};const rateLimiter = new RateLimiterMemory(opts);
rateLimiter.consume(remoteAddress, 2) // consume 2 points
.then((rateLimiterRes) => {
// 2 points consumed
})
.catch((rateLimiterRes) => {
// Not enough points to consume
});
`#### RateLimiterRes object
The Promise's
resolve and reject callbacks both return an instance of the RateLimiterRes class if there is no error.
Object attributes:
`javascript
RateLimiterRes = {
msBeforeNext: 250, // Number of milliseconds before next action can be done
remainingPoints: 0, // Number of remaining points in current duration
consumedPoints: 5, // Number of consumed points in current duration
isFirstInDuration: false, // action is first in current duration
}
`You may want to set HTTP headers for the response:
`javascript
const headers = {
"Retry-After": rateLimiterRes.msBeforeNext / 1000,
"X-RateLimit-Limit": opts.points,
"X-RateLimit-Remaining": rateLimiterRes.remainingPoints,
"X-RateLimit-Reset": Math.ceil((Date.now() + rateLimiterRes.msBeforeNext) / 1000)
}
`$3
* no race conditions
* no production dependencies
* TypeScript declaration bundled
* Block Strategy against really powerful DoS attacks (like 100k requests per sec) Read about it and benchmarking here
* Insurance Strategy as emergency solution if database/store is down Read about Insurance Strategy here
* works in Cluster or PM2 without additional software See RateLimiterCluster benchmark and detailed description here
* useful get, set, block, delete, penalty and reward methodsFull documentation is on Wiki
$3
* Express middleware
* Koa middleware
* Hapi plugin
* GraphQL graphql-rate-limit-directive
* NestJS nestjs-rate-limiter
* Fastify based NestJS app try nestjs-fastify-rate-limiterSome copy/paste examples on Wiki:
* Minimal protection against password brute-force
* Login endpoint protection
* Apply Block Strategy
* Setup Insurance Strategy
* Websocket connection prevent flooding
* Dynamic block duration
* Authorized users specific limits
* Different limits for different parts of application
* Third-party API, crawler, bot rate limiting
$3
* express-brute Bonus: race conditions fixed, prod deps removed
* limiter Bonus: multi-server support, respects queue order, native promises$3
* Drizzle Atomic and non-atomic counters.
* DynamoDb
* Etcd Atomic and non-atomic counters.
* Memcached
* Memory
* Mongo (with sharding support)
* MySQL (support Sequelize and Knex)
* Postgres (support Sequelize, TypeORM and Knex)
* Prisma
* Redis Atomic and non-atomic counters.
* SQLite
* Valkey: iovalkey or ValkeyGlide
* RateLimiterCluster (PM2 cluster docs read here)
* BurstyRateLimiter Traffic burst support
* RateLimiterUnion Combine 2 or more limiters to act as single
* RLWrapperBlackAndWhite Black and White lists
* RLWrapperTimeouts Timeouts
* RateLimiterQueue Rate limiter with FIFO queue
* AWS SDK v3 Client Rate Limiter Prevent punishing rate limit.
$3
See releases for detailed changelog.
Basic Options
* points
Default: 4
Maximum number of points that can be consumed over duration* duration
Default: 1
Number of seconds before consumed points are reset.
Points are never reset if duration is set to 0.* storeClient
Required for store limiters Must be
@valkey/valkey-glide, iovalkey, redis, ioredis, memcached, mongodb, pg, mysql2, mysql or any other related pool or connection.$3
* keyPrefix Make keys unique among different limiters.
* blockDuration Block for N seconds, if consumed more than points.
* inMemoryBlockOnConsumed Avoid extra requests to store.
* inMemoryBlockDuration
* insuranceLimiter Make it more stable with less efforts.
* storeType Have to be set to knex, if you use it.
* dbName Where to store points.
* tableName Table/collection.
* tableCreated Is table already created in MySQL, SQLite or PostgreSQL.
* clearExpiredByTimeout For MySQL, SQLite and PostgreSQL.See full list of options.
API
Read detailed description on Wiki.
* consume(key, points = 1) Consume points by key.
* get(key) Get
RateLimiterRes or null.
* set(key, points, secDuration) Set points by key.
* block(key, secDuration) Block key for secDuration seconds.
* delete(key) Reset consumed points.
* deleteInMemoryBlockedAll
* penalty(key, points = 1) Increase number of consumed points in current duration.
* reward(key, points = 1) Decrease number of consumed points in current duration.
* getKey(key) Get internal prefixed key.Contributions
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 must be extended from
RateLimiterStoreAbstract.
It has to implement 4 methods:
* _getRateLimiterRes parses raw data from store to RateLimiterRes object.
* _upsert may be atomic or non-atomic upsert (increment). It inserts or updates the value by key and returns raw data.
If it doesn't make an atomic upsert (increment), the class should be suffixed with NonAtomic, e.g. RateLimiterRedisNonAtomic.
It must support forceExpire mode to overwrite key expiration time.
* _get returns raw data by key or null if there is no key.
* _delete deletes all key-related data and returns true on deleted, false if key is not found.All other methods depends on the store. See
RateLimiterRedis or RateLimiterPostgres` for examples.Note: all changes should be covered by tests.