limitus
v3.0.0
Published
Limitus makes rate limiting your anything a snap.
Downloads
84
Readme
Limitus
Limitus is a (very) fast solution to rate limiting your application. It is agnostic as far as persistence goes - all you need to run it is a key value store (see examples for implementations using a plain hashmap and Redis).
Example
const Limitus = require('limitus');
const limiter = new Limitus();
/* create a "login" bucket */
limiter.rule('login', { max: 5, interval: 1000 * 60 * 5 });
/* in your application... */
app.post('/login', function (req, res) {
limiter.dropLogin({ ip: req.ip })
.then(function () {
// do the login
})
.catch(Limitus.Rejected, function () {
req.status(400).json('Too many requests!')
});
});
Usage
Class: Limitus()
The Limitus class is exported by this module. Options can take the following values:
overflow
- Record the next limit value even after the rate limit was passed - "punishing" clients who continue to request even after being notified of their rate limit exceeding. This is only useful in "continuous" mode. Defaults tofalse
.
limitus.rule(name, rule)
Creates a new "rule". The name should be a string, the rule should be an object with the max
number of requests in an interval
. You can also pass the mode
, which can be one of the following:
interval
Heaps requests into a stack. If the stack is over the max, requests are denied. At the end of the interval, the stack is reset back to zero.continuous
Keeps a running "count". Making a request adds one to the count, and the count is decreased at a rate of (interval / max).- Any function that accepts a
rule
(an object with a max and interval) and returns an object with the keys:limited
- boolean, whether this request should be denied.next
- a string for the next saved value to take.expiration
- time until it's safe to remove the "next" record from storage.
limiter.rule('login', { max: 5, interval: 1000 * 60 * 5 });
limitus.drop(bucket, identifier[, rule][, calback]) -> Promise
Add a "drop" in the specified bucket. The bucket
should be a string, such as "login". The identifier
should be an object for which you want to identify the client. If you previously created a rule matching the name, you don't need to pass the rule
argument. Otherwise, it is required. Also, if you did create a rule before, it is aliased as drop[Rule]
.
If you pass a callback, it gets called potentially with an err
. If no callback is passed, it returns a Promise which is resolved if the limit has not been hit, or is rejected with Limitus.Rejected if the rate limit has been exceeded.
.
limiter.dropLogin({ ip: req.ip })
.then(function () {
// do the login
})
.catch(Limitus.Rejected, function () {
req.status(400).json('Too many requests!')
});
// Or:
limiter.dropLogin({ ip: req.ip }, function (err) { ... });
// If you did not specify a rule:
limiter.drop('login', { ip: req.ip }, { max: 5, interval: 1000 * 60 * 5 }); // -> Promise
// If you already did, it's aliased:
limiter.drop('login', { ip: req.ip }); // -> Promise
limiter.dropLogin({ ip: req.ip }); // -> Promise
limitus.checkLimited(bucket, identifier[, rule][, calback]) -> Promise
This has the same function signature and behaviour as .drop
, except this will not count that request towards the total. This can be used if you want, say, rate limit a method but only want to count successful results of that methods towards the limit. You can check the limit prior to calling the function, then call .drop() afterwards.
limitus.extend(store)
Extends the limitus instance, mostly useful for settings the store. The store
should be an object that provides following methods:
.set(key, value, expiration, callback)
is used to save data to the store. Key and values are strings, the expiration is given in milliseconds. The callback should be called with no arguments on success, or a single error argument on failure..get(key, callback)
should return a previously stored key (or null/undefined) as the second argument in the callback, or pass a single error on failure.
limiter.extend({
set: function (key, value, expiration, callback) {
redis.setex(key, value, Math.ceil(expiration / 1000), callback);
},
get: function (key, callback) {
redis.get(key, callback);
}
});
Class: Limitus.Rejected
This is the error thrown when a rate limit is exceeded
Performance
Running on io.js in callback mode, Limitus runs an overhead of around 1.5 μs (0.0015 milliseconds). Promise mode and older Node versions may be slightly slower, so use what you think is best:
$ node bench.jsnode bench.js
callbacks: continuous mode x 682,714 ops/sec ±2.78% (88 runs sampled)
promises: continuous mode x 517,370 ops/sec ±2.31% (86 runs sampled)
callbacks: interval mode x 639,222 ops/sec ±2.34% (88 runs sampled)
promises: interval mode x 481,796 ops/sec ±2.88% (87 runs sampled)