README
api-rate-limiting
Express middleware that will limit API calls as configured.
Requirements
- redis should be installed on deployment machine.
How to use it
- Install it with npm.
- Pass a configuration object to it and enjoy
An example:
var express = require('express'),
rateLimiter = require('api-rate-limiting'),
app = express();
app.use('*', rateLimiter(configuration));
How does it work
This middleware will try to distribute API calls per user to be as uniform as possible. In example if we allow 10 calls per 100 seconds middleware will allow 1 call per 10 seconds. Since this rule is too strict we introduce a burst variable that will describe how many API calls should the middleware allow even in cases that would violate uniform distribution of API calls.
So if we configure the middleware to allow 10 calls per 100 seconds with burst of 10 that means that all 10 calls can be served as soon as possible, but the remaining time of 100 seconds the user will get a 429 too many requests error.
Configuration
Configuration object should have following attributes:
calls::Integer
time::Integer
unit::String (seconds|minutes|hours|days)
burst::Integer - optional
getUserLimitations::Function - optional
redisCreateArguments::Array - optional
uniqueField::Object - optional
cookieParser::Object - optional
Object uniqueField has following attributes
section::String (header|cookie|ip)
name::String
This object will tell the middleware where to search for the field that will identify the user. In example if we provide:
"uniqueField" : {
"section" : 'header',
"name" : 'token'
}
The middleware will check for token field in headers. That basically mean that any user identified by token field in header will be treated as above configured.
If unique field's section is set to be cookie then the middleware will try to parse cookies in exactly the same way as cookie-parser library.
Object cookieParser has 'section' and 'secret' fields that are used as described here
redisCreateAguments is an array of arguments that will be passed to createClient() function. Arguments will be passed as described here
Different rates per user
If different consumers of API have different rates user can pass a function to middleware that will be called when necessary. The function should asynchronously pass rates of an user back to middleware.
Arguments passed to getUserLimitations function:
- token - user's unique identifier
- callback - function that will be called to pass back user-specific configuration to middleware
Callback function should be called with 2 arguments:
- error
- configuration object
Example object
calls::Integer
time::Integer
unit::String (seconds|minutes|hours|days)
burst::Integer - optional
Configuration example
This is an example of a valid configuration object.
{
"calls" : 10,
"time" : 100,
"unit" : 'seconds',
"burst": 10,
"uniqueField" : {
"section" : 'header',
"name" : 'token'
}
}
This configuration will mean that our API should handle 10 calls per 100 seconds. User will be identified by a token attribute in header section.
Logging
The middleware will inform the rest of application about important things that happen using event
rate-limiting-info
The event will bring two arguments
- severity
- message object
In that way user can log any events with proper importance
var events = require('events'),
eventEmitter = new events.EventEmitter();
eventEmitter.on('rate-limiting-info', function(severity, message) {
//log your stuff
});