oniyi-limiter
v0.0.9A limiter/throttling implementation in redis
Install
$ npm install --save oniyi-limiter
Getting Started
Construct a new instance of OniyiLimiter as shown in the following example and call the throttle
method whenever you want to execute a call against the represented resource.
var OniyiLimiter = require('oniyi-limiter');
var myLimiter = new OniyiLimiter('my-limiter');
myLimiter.throttle(function(err, bucket){
if (err) {
// you should not execute any code because there was either a system error or no tokens left in the bucket
return;
}
console.log('This call was throttled. My bucket now looks like this: %j', bucket);
// {remaining: 9, limit: 10, reset: 1425969050096}
});
// Alternatively with options:
var myLimiter = new OniyiLimiter({
id: 'my-limiter',
limit: 2000,
duration: 180000
});
Methods
new OniyiLimiter(options)
This is the constructor to instantiate a new limiter.
The first argument can be either a id
or an options
object. The only required option is id
; all others are optional.
id
- a unique String identifying the resource you want to limit access to. This string is also used to construct the redis key under which our bucket hash is stored.limit
- the number of tokens available in a bucket perduration
(defaults to2500
). IfOniyiLimiter.throttle
is called more often than this number during the validity of one slingle bucket, aBucketEmptyError
will be passed to the callback function.duration
- the number of milliseconds a bucket is valid (defaults to60000
)useLocalFallback
- a true / false switch to indicate weatherOniyiLimiter
should use a local (in-memory) fallback for managing the bucket in case the redis client is not connected (defaults tofalse
).redisClient
- an instance of node redis clientredis
- an object of options that can be passed to make-redis-client in order to create a redis client (defautls to{}
and thus tries to connect tolocalhost
on port6379
).
createBucket(callback)
This method is used to create a new bucket for it's OniyiLimiter
instance. That means, it will create a new bucket with the configured limit
as size and Date.now()
+ duration
as expiry date in redis.
However, if there is an existing bucket in redis for this instance already, it will not be overwritten and an error will be passed to callback instead.
This method does not automatically execute a throttle
command. It simply creates a new bucket if possible and passes it to the callback function.
myLimiter.createBucket(function(err, bucket){
if (err) {
console.log(err);
// { [BucketExistsError: my-limiter - A bucket exists already]
// name: 'BucketExistsError',
// message: 'my-limiter - A bucket exists already' }
return;
}
console.log(bucket);
// {remaining: 10, limit: 10, reset: 1425969050096}
});
createBucket
returns a q
promise that resolves with the created bucket or rejects with a proper reason accordingly.
var promise = myLimiter.createBucket();
promise.then(function(bucket){
console.log(bucket);
// {remaining: 10, limit: 10, reset: 1425969050096}
}, function(reason){
console.log(reason);
// { [BucketExistsError: my-limiter - A bucket exists already]
// name: 'BucketExistsError',
// message: 'my-limiter - A bucket exists already' }
});
Note: It is not recommended to use this method directly. Please only use throttle
instead. It will check for bucket availability and create new buckets if required.
throttle(callback)
This method will check for an available token in the current bucket of it's instance of OniyiLimiter
. If no bucket exists, it will create one and then execute the callback. If a bucket exists and is not empty, throttle
will reduce the remaining
number of tokens by one and call the callback function.
If any error occurs or there are no tokens left in the active bucket, an error will be passed to the callback function.
myLimiter.throttle(function(err, bucket){
if (err) {
console.log(err);
// { [BucketEmptyError: my-limiter - All {10} tokens from this bucket have been used. Retry after Sat Apr 11 2015 22:13:35 GMT+0900 (KST)]
// name: 'BucketEmptyError',
// message: 'my-limiter - All {10} tokens from this bucket have been used. Retry after Sat Apr 11 2015 22:13:35 GMT+0900 (KST)' }
return;
}
console.log(bucket);
// {remaining: 9, limit: 10, reset: 1425969050096}
});
Note: if the callback function receives an error, it should not execute the code that was supposed to be throttled.
throttle
also returns a promise that either resolves with the bucket or is rejected with an according error.
var promise = myLimiter.throttle();
promise.then(function(bucket){
console.log(bucket);
// {remaining: 9, limit: 10, reset: 1425969050096}
}, function(reason){
console.log(reason);
// { [BucketEmptyError: my-limiter - All {10} tokens from this bucket have been used. Retry after Sat Apr 11 2015 22:13:35 GMT+0900 (KST)]
// name: 'BucketEmptyError',
// message: 'my-limiter - All {10} tokens from this bucket have been used. Retry after Sat Apr 11 2015 22:13:35 GMT+0900 (KST)' }
return;
});
DEPRECATED: getBucket
This method is deprecated as of version 0.0.9. Please use throttle
instead.
Debugging
Set the environment variable DEBUG
to a value that contains oniyi-limiter
and it'll start talking to you.
Future plans
In order to support API transactions, it should be possible to request multiple tokens at once. This will allow to secure enough resources to complete a whole transaction... or postpone it to the next bucket if the number of available tokens isn't sufficient to complete the transaction.
License
MIT © Benjamin Kroeger