Basic rate-limiting middleware for Express. Use to limit repeated requests to public endpoints such as account creation and password reset.
Note: this module does not share state with other processes/servers. If you need a more robust solution, I recommend checking out the excellent strict-rate-limiter
$ npm install --save express-rate-limit
- windowMs: milliseconds - how long to keep records of requests in memory. Defaults to
60000
(1 minute). - delayAfter: max number of connections during
windowMs
before starting to delay responses. Defaults to1
. Set to0
to disable delaying. - delayMs: milliseconds - how long to delay the response, multiplied by (number of recent hits -
delayAfter
). Defaults to1000
(1 second). Set to0
to disable delaying. - max: max number of connections during
windowMs
milliseconds before sending a 429 response. Defaults to5
. Set to0
to disable. - message: Error message returned when
max
is exceeded. Defaults to'Too many requests, please try again later.'
- statusCode: HTTP status code returned when
max
is exceeded. Defaults to429
. - handler: The function to execute once the max limit is exceeded. It receives the request and the response objects. The "next" param is available if you need to pass to the next middleware. Defaults:
function (req, res, /*next*/) {
res.format({
html: function(){
res.status(options.statusCode).end(options.message);
},
json: function(){
res.status(options.statusCode).json({ message: options.message });
}
});
}
The delayAfter
and delayMs
options were written for human-facing pages such as login and password reset forms.
For public APIs, setting these to 0
(disabled) and relying on only windowMs
and max
for rate-limiting usually makes the most sense.
For an API-only server where the rate-limiter should be applied to all requests:
var rateLimit = require('express-rate-limit');
app.enable('trust proxy'); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
// default options shown below
var limiter = rateLimit({/* config */});
// apply this globally
app.use(limiter);
For a "regular" web server (e.g. anything that uses express.static()
), where the rate-limiter should only apply to certain requests:
var rateLimit = require('express-rate-limit');
app.enable('trust proxy'); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
var limiter = rateLimit({/* config */});
// apply to all requests that begin with /api/
app.use('/api/', limiter);
// apply to an individual endpoint
app.post('/create-account', limiter, function(req, res) {
// ...
}
// optionally set up an endpoint to reset the rate limit for an IP
var limiter2 = rateLimit({/* altConfig */); // we can't use the same rateLimit instance on the reset endpoint, but we probably do want it limited.
app.post('/reset-rate-limit', limiter2, function(req, res) {
// validate that requester has filled out a captcha properly or whatever and then...
limiter.resetIp(req.ip);
// ...
}
- resetIp(ip): Resets the rate limiting for a given ip.
v2 uses a less precise but less resource intensive method of tracking hits from a given IP. v2 also adds the limiter.resetIp()
API and removes the global: true
option.
MIT © Nathan Friedly