level-throttle
v1.0.2
Published
A key-based throttling mechanism for levelup-compliant data stores.
Downloads
6
Readme
level-throttle
level-throttle
is a dead-simple token-bucket-based throttling mechanism
built on levelup
.
level-throttle
was initially designed to provide throttled access
control to API endpoints, but can in fact be used to regulate access to any
resource.
level-throttle
works by simply counting the number of "tokens" remaining in
the "bucket" associated with an arbitrarily-specified "throttle key". Each time
a throttled resource is accessed, a token is removed from the associated
bucket. If the number of tokens in the bucket reaches zero, the consumer has
exhaused access to the throttled resource. The bucket is automatically refilled
when appropriate.
Usage
Initializing
require
and invoke the module while specifying some configuration options:
// boostrap level
var level = require('level');
var db = level('./mydb', { valueEncoding : 'json' });
// initialize the `throttle` function
var throttle = require('level-throttle')({
db : db,
namespace : 'the-app-name' ,
limit : 100,
ttl : 1000 * 60 * 60, // one hour
});
Whereby:
db
is anylevelup
-compliant handle.namespace
is a namespace that should prefix all leveldb keys. This makes it possible to use this module to throttle multiple applications without the risk of interference among applications. It is probably sensible fornamespace
to be the name of the app itself.limit
is the maximum number of throttled calls that may be made withinttl
.ttl
(time-to-live) is the interval after which the bucket should be re-stocked with tokens. Its value must be specified in milliseconds.
An Error
will be thrown if any of the configs are invalid.
Invoking
Next, simply invoke the initialized function:
throttle('some-throttle-key', function(err, tokens) {
// if `tokens` is `0`, respond with an HTTP `429`
});
The function does one thing: it reports the number of tokens remaining in the
bucket for the specified throttle key. If there are 0
tokens remaining, the
user has consumed all of his allocated throttle requests for the ttl
.
Overriding Config
The ttl
and limit
values can optionally be overridden when the function is
invoked, thus making it possible to set different access controls per throttle
key. To do so, simply pass the function a map of override options thusly:
throttle('different-throttle-key', { ttl : 60000, limit: 1337 }, function(err, tokens) {
// this user will be allotted 1337 tokens per minute
});
Bucket TTLs
ttl
values will be passed to the underlying levelup
handle with which
level-throttle
was initialized (db
). This means that, if the handle makes
use of a module like level-ttl to automatically purge expired buckets from
the database, that expiration mechanism will work as expected. The use of such
a module is not required, however.