Express rate-limiter

Rate limiting middleware for Express applications built on redis

1npm install express-limiter --save

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

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|String|Array.<String> value lookup on the request object. Can be a single value, array or function. See examples for common usages
• 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.
• onRateLimited: Function called when a request exceeds the configured rate limit.

Examples

1// limit by IP address
2limiter({
3  ...
4  lookup: 'connection.remoteAddress'
5  ...
6})
7
8// or if you are behind a trusted proxy (like nginx)
9limiter({
10  lookup: 'headers.x-forwarded-for'
11})
12
13// by user (assuming a user is logged in with a valid id)
14limiter({
15  lookup: 'user.id'
16})
17
18// limit your entire app
19limiter({
20  path: '*',
21  method: 'all',
22  lookup: 'connection.remoteAddress'
23})
24
25// limit users on same IP
26limiter({
27  path: '*',
28  method: 'all',
29  lookup: ['user.id', 'connection.remoteAddress']
30})
31
32// whitelist user admins
33limiter({
34  path: '/delete/thing',
35  method: 'post',
36  lookup: 'user.id',
37  whitelist: function (req) {
38    return !!req.user.is_admin
39  }
40})
41
42// skip sending HTTP limit headers
43limiter({
44  path: '/delete/thing',
45  method: 'post',
46  lookup: 'user.id',
47  whitelist: function (req) {
48    return !!req.user.is_admin
49  },
50  skipHeaders: true
51})
52
53// call a custom limit handler
54limiter({
55  path: '*',
56  method: 'all',
57  lookup: 'connection.remoteAddress',
58  onRateLimited: function (req, res, next) {
59    next({ message: 'Rate limit exceeded', status: 429 })
60  }
61})
62
63// with a function for dynamic-ness
64limiter({
65  lookup: function(req, res, opts, next) {
66    if (validApiKey(req.query.api_key)) {
67      opts.lookup = 'query.api_key'
68      opts.total = 100
69    } else {
70      opts.lookup = 'connection.remoteAddress'
71      opts.total = 10
72    }
73    return next()
74  }
75})
76

as direct middleware

1app.post('/user/update', limiter({ lookup: 'user.id' }), function (req, res) {
2  User.find(req.user.id).update(function (err) {
3    if (err) next(err)
4    else res.send('ok')
5  })
6})

License MIT

Happy Rate Limiting!