redis-bucket
A Redis-backed rate limiter, based on the
leaky-bucket algorithm.
Implemented using a purely EVAL-based solution, which provides the following
advantages:
- It is optimized for cases where multiple instances of a service share common
rate-limiting metrics, since the counts are shared via a single store.
- It supports multiple simultaneous metrics, allowing for tiered rates.
- It works with hosted Redis solutions that may not support custom modules.
Requirements
- Development - Node.js and a running Redis instance
for testing.
- Runtime - A Redis client supporting EVAL; EVALSHA is recommended but not
required.
Example
import * as express from 'express';
import * as redis from 'redis';
import * as limiter from 'redis-bucket';
const client = redis.createClient({});
client.on('error', () => {});
const limit = limiter.create({
capacity: { window: 60, min: 10, max: 20 },
backoff: x => 2 ** x,
async eval(script: string, keys: string[], argv: unknown[]) {
return client.eval(script, { keys, arguments: argv.map(String) });
},
async evalsha(sha: string, keys: string[], argv: unknown[]) {
return client.evalSha(sha, { keys, arguments: argv.map(String) });
},
});
const app = express();
app.get('/', async (req, res) => {
const result = await limit(req.query.user);
if (result.allow) {
res.sendStatus(200);
} else {
res.set('Retry-After', result.wait);
res.sendStatus(429);
}
});
app.listen(8080);
API
create(config)
Creates a test function to perform rate limiting against a
given set of metrics. Takes a configuration object containing the following
options:
eval
- A callback to execute an EVAL call on Redis.evalsha
(default none) - A callback to execute an EVALSHA call on Redis.prefix
(default none) - A string prefix to apply to all Redis keys used
by this instance.backoff
(default linear) - The backoff scaling function used for
retries.capacity
- A capacity metric (or array thereof) to limit by (see
below).rate
- A rate metric (or array thereof) to limit by (see
below).
test(key, [cost])
Tests whether the given action should be allowed according to the rate limits.
Returns a Result
object. Takes the following arguments:
key
- A string specifying the instance to be tested. Limits will only be
applied to a given key against itself.cost
(default 1) - The capacity cost of this action (see
below).
Result
An object representing the result of a test. Contains the following parameters:
allow
- Whether or not this action should be allowed according to the rate
limits.free
- The current remaining capacity before actions will be rejected; 0
if allow is false.wait
- How long the caller should wait before trying again, in seconds; 0
if allow is true.
Specifying Limits
The allowable limits for a given instance of the rate-limiter can be specified
in two ways. Note that 'capacity' is an abstract value; typically it represents
a number of actions, but it can also indicate an overall net 'cost' of actions.
Capacity Limits
Capacity limits are specified using three values:
window
- The time window over which these limits are considered, in
seconds.min
- The minimum capacity that is guaranteed over this time window,
assuming a perfectly uniform call pattern (see note below).max
- The maximum capacity that the system can handle over this time
window. This value is absolute; callers will be limited in such a way to
enforce this. It must be sufficiently greater than the minimum capacity to
cover the highest cost the test function will be called with.
Note: If the maximum capacity is set as low as possible (in other words,
just greater than the minimum capacity), the caller must request capacity in a
perfectly uniform manner in order to receive the minimum capacity. This
restriction becomes increasingly loose as the maximum capacity increases,
disappearing when the maximum capacity is twice the minimum capacity (at which
point the minimum capacity becomes guaranteed independent of the call pattern).
Rate Limits
Rate limits are specified using two values:
flow
- The rate at which capacity becomes available, per second. In a
fully-stressed system, calls will be limited to exactly this rate.burst
- The amount of leeway in capacity the system can support. This is
the amount of capacity that can be utilized before rate-limiting is applied.
It must be at least equal to the highest cost the test function will be
called with.
Contributing
This project has adopted the
Microsoft Open Source Code of Conduct.
For more information see the
Code of Conduct FAQ or
contact opencode@microsoft.com with any
additional questions or comments.