limitd is a simple daemon for rate limiting highly available applications.
This repository contains the client library for node.js.
Install
npm install limitd-client --save
Example usage
const LimitdClient = require('limitd-client');
const limitd = new LimitdClient('limitd://localhost:9001');
//express middleware
app.use(function (req, res, next) {
limitd.take('user', req.username, function (err, resp) {
if (err) return next(err);
res.set({
'X-RateLimit-Limit': resp.limit,
'X-RateLimit-Remaining': resp.remaining,
'X-RateLimit-Reset': resp.reset
});
if (resp.conformant) return next();
// The 429 status code indicates that the user has sent too many
// requests in a given amount of time ("rate limiting").
res.send('429');
});
})
API
limitd.take(type, key, count?, callback)
Take if available count
amount of tokens from the bucket with key key
of type type
.
count defaults to 1.
The callback will be call either with an Error object or a Response object.
-
response.conformant
: boolean indicating if the traffic is conformant or not. -
response.limit
: indicates the size of this bucket. -
response.remaining
: the amount of remaining tokens in the bucket. -
response.reset
: a unix timestamp indicating when the bucket is going to be full again. -
response.delayed
: always false for TAKE requests.
limitd.wait(type, key, count?, callback)
Take or Wait for count
amount of tokens from the bucket with key key
of type type
.
count defaults to 1.
The callback will be call either with an Error object or a Response object.
-
response.delayed
: boolean indicating if this request was delayed due to insufficient tokens in the bucket. -
response.limit
: indicates the size of this bucket. -
response.remaining
: the amount of remaining tokens in the bucket. -
response.reset
: a unix timestamp indicating when the bucket is going to be full again. -
response.conformant
: always true for WAIT requests.
limitd.put(type, key, count?, callback) (alias reset)
Force put count
amount of tokens in the bucket with key key
of type type
.
count defaults to the size of the bucket.
The callback will be call either with an Error object or a Response object.
-
response.limit
: indicates the size of this bucket. -
response.remaining
: the amount of remaining tokens in the bucket. -
response.reset
: a unix timestamp indicating when the bucket is going to be full again.
This is useful for buckets that are not automatically filled or when the application needs to force a reset.
Events
-
connect
: emitted when the client connects to the server. -
disconnect([err])
: emitted when the client disconnects from the server. -
error
: emitted in case of errors -
reconnect(n, delay)
: emitted when attempting to restablish the connection. See reconnect-core. -
trip(err, failures, cooldown)
: emitted when the circuit-breaker mechanism trips. -
ready
: emitted when the client is ready to send requests. -
response
: emitted when the client receives a response. Useful for metrics and debug.
Note: Events on the shard client have the same signature but the last parameter is the instance of the client.
Sharding
Sharding is implemented in the client-side by providing a list of limitd servers.
Example
const LimitdClient = require('limitd-client');
const limitd = new LimitdClient({
shard: {
hosts: [ 'limitd://host-1', 'limitd://host-2' ]
}
});
limitd.take('ip', 'test', (err, resp) => console.dir(resp));
Alternatively you can have a DNS record and use autodiscovery:
const LimitdClient = require('limitd-client');
const limitd = new LimitdClient({
shard: {
autodiscovery: 'limitds.internal.company.com'
}
});
limitd.take('ip', 'test', (err, resp) => console.dir(resp));
This record will be poll every 5 minutes.
License
MIT 2015 - AUTH0 INC.