redis-rate-limiter

Rate-limit any operation, backed by Redis.

• Inspired by ratelimiter
• But uses a fixed-window algorithm
• Great performance (>10000 checks/sec on local redis)
• No race conditions

Very easy to plug into Express or Restify to rate limit your Node.js API.

Usage

Step 1: create a Redis connection

1var redis = require('redis');
2var client = redis.createClient(6379, 'localhost', {enable_offline_queue: false});

Step 2: create your rate limiter

1var rateLimiter = require('redis-rate-limiter');
2var limit = rateLimiter.create({
3  redis: client,
4  key: function(x) { return x.id },
5  rate: '100/minute'
6});

And go

1limit(request, function(err, rate) {
2  if (err) {
3    console.warn('Rate limiting not available');
4  } else {
5    console.log('Rate window: '  + rate.window);  // 60
6    console.log('Rate limit: '   + rate.limit);   // 100
7    console.log('Rate current: ' + rate.current); // 74
8    if (rate.over) {
9      console.error('Over the limit!');
10    }
11  }
12});

Options

redis

A pre-created Redis client. Make sure offline queueing is disabled.

1var client = redis.createClient(6379, 'localhost', {
2  enable_offline_queue: false
3});

key

The key is how requests are grouped for rate-limiting. Typically, this would be a user ID, a type of operation.

You can also specify any custom function:

1// rate-limit each user separately
2key: function(x) { return x.user.id; }
3
4// rate limit per user and operation type
5key: function(x) { return x.user.id + ':' + x.operation; }
6
7// rate limit everyone in the same bucket
8key: function(x) { return 'single-bucket'; }

You can also use the built-in ip shorthand, which gets the remote address from an HTTP request.

1key: 'ip'

window

This is the duration over which rate-limiting is applied, in seconds.

1// rate limit per minute
2window: 60
3
4// rate limit per hour
5window: 3600

Note that this is not a rolling window. If you specify 10 requests / minute, a user would be able to execute 10 requests at 00:59 and another 10 at 01:01. Then they won't be able to make another request until 02:00.

limit

This is the total number of requests a unique key can make during the window.

1limit: 100

rate

Rate is a shorthand notation to combine limit and window.

1rate: '10/second'
2rate: '100/minute'
3rate: '1000/hour'

Or the even shorter

1rate: '10/s'
2rate: '100/m'
3rate: '100/h'

Note: the rate is parsed ahead of time, so this notation doesn't affect performance.

HTTP middleware

This package contains a pre-built middleware, which takes the same options

1var rateLimiter = require('redis-rate-limiter');
2
3var middleware = rateLimiter.middleware({
4  redis: client,
5  key: 'ip',
6  rate: '100/minute'
7});
8
9server.use(middleware);

It rejects any rate-limited requests with a status code of HTTP 429, and an empty body.

Note: if you want to rate limit several routes individually, don't forget to use the route name as part of the key, for example using Restify:

1function ipAndRoute(req) {
2  return req.connection.remoteAddress + ':' + req.route.name;
3}
4
5server.get(
6  {name: 'routeA', path: '/a'},
7  rateLimiter.middleware({redis: client, key: ipAndRoute, rate: '10/minute'}),
8  controllerA
9);
10
11server.get(
12  {name: 'routeB', path: '/b'},
13  rateLimiter.middleware({redis: client, key: ipAndRoute, rate: '20/minute'}),
14  controllerB
15);