Express rate-limiter2

Rate limiting middleware for Express applications built on redis

Based on ded/express-limiter (https://github.com/ded/express-limiter)

1npm install express-limiter2 --save

1var express = require('express')
2var app = express()
3var client = require('redis').createClient()
4
5var limiter = require('express-limiter2')(client, app)
6
7/**
8 * you may also pass it an Express 4.0 `Router`
9 *
10 * router = express.Router()
11 * limiter = require('express-limiter')(client, router)
12 */
13
14limiter({
15  path: '/api/action',
16  method: 'get',
17  lookup: function(req) {
18    return [req.connection.remoteAddress];
19  },
20  // 150 requests per hour
21  total: 150,
22  expire: 1000 * 60 * 60
23})
24
25app.get('/api/action', function (req, res) {
26  res.send(200, 'ok')
27})

API options

1limiter(options)

• path: String optional route path to the request
• method: String optional http method. accepts get, post, put, delete, and of course Express' all
• lookup: function(req) must return a list of string used for redis key. It can be req param, or custom data. See examples for common usages (default lookup is performed on req.path, req.method and req.connection.remoteAddress)
• total: Number allowed number of requests before getting rate limited
• expire: Number amount of time in ms before the rate-limited is reset
• whitelist: function(req) optional param allowing the ability to whitelist. return boolean, true to whitelist, false to passthru to limiter.
• skipHeaders: Boolean whether to skip sending HTTP headers for rate limits ()
• ignoreErrors: Boolean whether errors generated from redis should allow the middleware to call next(). Defaults to false.
• keyFormatter: function(params) optional param to customize key generation for redis. You can specify you prefix, suffix, and the way you join key's parts (See code for default behaviour)
• onRateLimited: function(req, res, next) optional param to define the behaviour of your choice when rate limit is reached

Examples

1// limit by IP address, path and method (default behaviour)
2limiter({
3  ...
4  lookup: function(req) { return [req.path, req.method, req.connection.remoteAddress];}
5  ...
6})
7
8// or if you are behind a trusted proxy (like nginx)
9limiter({
10  lookup: function(req) { return [req.path, req.method, req.headers.x-forwarded-for];}
11})
12
13// by user (assuming a user is logged in with a valid id)
14limiter({
15  lookup: function(req) { return [req.path, req.method, req.user.id]; }
16})
17
18// limit your entire app (quotas are applied on each route/method couple)
19limiter({
20  path: '*',
21  method: 'all',
22  lookup: function(req) {
23    return [req.connection.remoteAddress, req.method, req.path];
24  }
25})
26
27// rate limit your app globally by IP address (not each route/method couple)
28limiter({
29  path: '*',
30  method: 'all',
31  lookup: function(req) {
32    return [req.connection.remoteAddress];
33  }
34})
35
36// limit users on same IP
37limiter({
38  path: '*',
39  method: 'all',
40  lookup: function(req) {
41    return [req.user.id, req.connection.remoteAddress];
42  }
43})
44
45// whitelist user admins
46limiter({
47  path: '/delete/thing',
48  method: 'post',
49  lookup: function(req) {
50    return [req.user.id, req.path, req.method]
51  },
52  whitelist: function (req) {
53    return !!req.user.is_admin
54  }
55})
56
57// skip sending HTTP limit headers
58limiter({
59  path: '/delete/thing',
60  method: 'post',
61  lookup: function(req) {
62    return [req.user.id, req.path, req.method]
63  },
64  whitelist: function (req) {
65    return !!req.user.is_admin
66  },
67  skipHeaders: true
68})
69
70// custom data
71// in some case you may want to rate-limit not a specific route/method
72// but several routes, or several methods, or whatever you want actually
73// use the lookup function to adjust it to your needs
74limiter({
75  path: '/api/*',
76  method: 'all',
77  lookup: function(req) {
78    return [req.user.id, req.connection.remoteAddress, 'api'];
79  }
80})
81
82// custom redis keys
83limiter({
84  path: '/api/*',
85  method: 'get',
86  lookup: function(req) {
87    return [req.user.id, req.path, req.method]
88  },
89  keyFormatter: function(params) {
90    return 'myRateLimit:' + params.join("-");
91  },
92  whitelist: function (req) {
93    return !!req.user.is_admin
94  }
95})
96
97// custom behaviour when rate limited
98limiter({
99  path: '*',
100  method: 'all',
101  lookup: function(req) {
102    return [req.user.id, req.connection.remoteAddress];
103  },
104  onRateLimited: function(req, res, next) {
105    return next({error: {status: 429, message: 'too many requests'}});
106  }
107})
108

as direct middleware

1// app param is now useless
2var limiter = require('express-limiter')(client)
3
4app.post('/user/update', limiter({ lookup: function(req) { return [req.user.id, req.path, req.method]} }), function (req, res) {
5  User.find(req.user.id).update(function (err) {
6    if (err) next(err)
7    else res.send('ok')
8  })
9})
10
11// with custom data
12app.get('/api/*', limiter({
13    lookup: function(req) {
14      return [req.user.id, 'api'];
15    }
16  }), function (req, res) {
17  User.find(req.user.id).update(function (err) {
18    if (err) next(err)
19    else res.send('ok')
20  })
21})

License MIT

Happy Rate Limiting!