node-ratelimiter

Rate limiter for Node.js.

Release Notes

v3.1.0 - #7 - Fix memory adapter & #8 new id retrieval method (no breaking change)

v3.0.0 - Add multiple adapters support (redis, memory, null)

v2.1.2 - #17 by @waleedsamy - Add Travis CI support

v2.1.1 - #13 by @kwizzn - Fixes out-of-sync TTLs after running decr()

v2.1.0 - #12 by @luin - Adding support for ioredis

v2.0.1 - #9 by @ruimarinho - Update redis commands to use array notation.

v2.0.0 - API CHANGE - Change remaining to include current call instead of decreasing it. Decreasing caused an off-by-one problem and caller could not distinguish between last legit call and a rejected call.

Requirements

• Redis 2.6.12+.

Installation

$ npm install node-ratelimiter

Example

Example Connect middleware implementation limiting against a user._id:

1var Limiter = require('node-ratelimiter');
2var redisAdapter = Limiter.redisAdapter;
3
4var limiter = new Limiter({ id: req.user._id }, redisAdapter(redis.createClient()));
5
6limiter.newHit(function(err, limit){
7  if (err) return next(err);
8
9  res.set('X-RateLimit-Limit', limit.total);
10  res.set('X-RateLimit-Remaining', limit.remaining - 1);
11  res.set('X-RateLimit-Reset', limit.reset);
12
13  // all good
14  debug('remaining %s/%s %s', limit.remaining - 1, limit.total, id);
15  if (limit.remaining) return next();
16
17  // not good
18  var delta = (limit.reset * 1000) - Date.now() | 0;
19  var after = limit.reset - (Date.now() / 1000) | 0;
20  res.set('Retry-After', after);
21  res.send(429, 'Rate limit exceeded, retry in ' + ms(delta, { long: true }));
22});

Result Object

• total - max value
• remaining - number of calls left in current duration without decreasing current get
• reset - time in milliseconds until the end of current duration

Options

• id - the identifier to limit against (typically a user id)
• max [Number] - max requests within duration [2500]
• duration [Number] - of limit in milliseconds [3600000]

Adapters

RedisAdapter

Initialize a new adapter with:

1var redis = require('redis');
2var Limiter = require('node-ratelimiter');
3var redisAdapter = Limiter.redisAdapter;
4
5var adapter = redisAdapter(redis.createClient());

MemoryAdapter

This adapter is meant to be used in dev. Do not use it in production.

Initialize a new adapter with:

1var Limiter = require('node-ratelimiter');
2var memoryAdapter = Limiter.memoryAdapter;
3
4var adapter = memoryAdapter();

NullAdapter

This adapter is meant to be used for tests only when you want to disable the rate limiting.

Initialize a new adapter with:

1var Limiter = require('node-ratelimiter');
2var nullAdapter = Limiter.nullAdapter;
3
4var adapter = nullAdapter();

Custom adapter

The adapter passed to the Limiter constructor should be a function accepting the following parameters:

• id [String]: the identifier being limited (for example: an ip address)
• max [Number]: the number of calls accepted before being rate-limited
• duration [Number]: the duration after which the counter will be reset

The function should return an object with the following methods:

• newHit(): registers a new hit and returns the result object

  • total - max value
  • remaining - number of calls left in current duration without decreasing current get
  • reset - time in milliseconds until the end of current duration

• get(): returns the result object without increasing the hit counter

  • total - max value
  • remaining - number of calls left in current duration without decreasing current get
  • reset - time in milliseconds until the end of current duration

License

MIT