rate-limiter-flexible counts and limits number of actions by key and protects from DDoS and brute force attacks at any scale.
It works with Redis, process Memory, Cluster or PM2, Memcached, MongoDB, MySQL, PostgreSQL and allows to control requests rate in single process or distributed environment.
Atomic increments. All operations in memory or distributed environment use atomic increments against race conditions.
Traffic bursts. Replace Token Bucket with BurstyRateLimiter
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 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:
memcached, native driver or
mongoose. It works with all of them.
In memory blocks. Avoid extra requests to store with inmemoryBlockOnConsumed.
It uses fixed window as it is much faster than rolling window. See comparative benchmarks with other libraries here
npm i --save rate-limiter-flexible
yarn add rate-limiter-flexible
const opts =points: 6 // 6 pointsduration: 1 // Per second;const rateLimiter = opts;rateLimiter // consume 2 points;
Both Promise resolve and reject return object of
RateLimiterRes class if there is no any error.
RateLimiterRes =msBeforeNext: 250 // Number of milliseconds before next action can be doneremainingPoints: 0 // Number of remaining points in current durationconsumedPoints: 5 // Number of consumed points in current durationisFirstInDuration: false // action is first in current duration
You may want to set next HTTP headers to response:
const headers ="Retry-After": rateLimiterResmsBeforeNext / 1000"X-RateLimit-Limit": optspoints"X-RateLimit-Remaining": rateLimiterResremainingPoints"X-RateLimit-Reset": Date + rateLimiterResmsBeforeNext
- no race conditions
- no production dependencies
- TypeScript declaration bundled
- allow traffic burst with BurstyRateLimiter
- Block Strategy against really powerful DDoS 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
Middlewares and plugins
Some copy/paste examples on Wiki:
- Minimal protection against password brute-force
- Login endpoint protection
- Websocket connection prevent flooding
- Dynamic block duration
- Authorized users specific limits
- Different limits for different parts of application
- Apply Block Strategy
- Setup Insurance Strategy
- Third-party API, crawler, bot rate limiting
Migration from other packages
- express-brute Bonus: race conditions fixed, prod deps removed
- limiter Bonus: multi-server support, respects queue order, native promises
Docs and Examples
- API methods
- BurstyRateLimiter Traffic burst support
- RateLimiterMongo (with sharding support)
- RateLimiterMySQL (support Sequelize and Knex)
- RateLimiterPostgres (support Sequelize and Knex)
- RateLimiterCluster (PM2 cluster docs read here)
- RateLimiterUnion Combine 2 or more limiters to act as single
- RLWrapperBlackAndWhite Black and White lists
- RateLimiterQueue Rate limiter with FIFO queue
See releases for detailed changelog.
Maximum number of points can be consumed over duration
Number of seconds before consumed points are reset.
Never reset points, if
durationis set to 0.
Required for store limiters
Have to be
mysqlor any other related pool or connection.
Other options on Wiki:
- keyPrefix Make keys unique among different limiters.
- blockDuration Block for N seconds, if consumed more than points.
- inmemoryBlockOnConsumed Avoid extra requests to store.
- 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 or PostgreSQL.
- clearExpiredByTimeout For MySQL and PostgreSQL.
Smooth out traffic picks:
Read detailed description on Wiki.
- consume(key, points = 1) Consume points by key.
- get(key) Get
- set(key, points, secDuration) Set points by key.
- block(key, secDuration) Block key for
- delete(key) Reset consumed points.
- 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.
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 ms2. Cluster 0.69 ms3. Redis 2.45 ms4. Memcached 3.89 ms5. Mongo 4.75 ms
500 concurrent clients with maximum 1000 req per sec during 30 seconds
6. PostgreSQL 7.48 ms (with connection pool max 100)7. MySQL 14.59 ms (with connection pool 100)
Note, you can speed up limiters with inmemoryBlockOnConsumed option.
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
It has to implement 4 methods:
_getRateLimiterResparses raw data from store to
_upsertmust be atomic. it inserts or updates value by key and returns raw data. it must support
forceExpiremode to overwrite key expiration time.
_getreturns raw data by key or
nullif there is no key.
_deletedeletes all key related data and returns
falseif key is not found.
All other methods depends on store. See
RateLimiterPostgres for example.
Note: all changes should be covered by tests.