Node Redis GCRA Library

!Build Status 

This module is an implementation of GCRA for rate limiting based on Redis.

* Installation
* API Documentation
* Initializer
* Instance Functions
* limit
* peek
* reset
* Node-redis usage
* Example
* Inspiration
* License

Installation

``bash
npm install redis-gcra
`

or

`bash
yarn install redis-gcra
`

API Documentation

$3

`javascript
import RedisGCRA from 'redis-gcra';

const limiter = RedisGCRA({
redis: undefined,
keyPrefix: '',
burst: 60,
rate: 1,
period: 1000,
cost: 1
});
`

The redis-gcra module exposes a single function, which returns a limiter instance when called.
It takes the following options:

| Option | Type | Default | Description |
| :----- | :--- | ------- | :---------- |
| redis | ioredis or node-redis instance | | Required. The Redis client to be used. _( If you use node-redis, additional setup work is required; see below. You may also use a Redis-client-like wrapper that exposes the defineCommand method and the Redis del method.)_ |
| keyPrefix | String | | A prefix for any keys that this limiter instance tries to create/access. |
| burst | Number | 60 | The default burst value for this limiter instance. If provided, must be a number greater than or equal to 1. |
| rate | Number | 1 | The default rate value for this limiter instance. If provided, must be a number greater than or equal to 1. |
| period | Number | 1000 | The default period value for this limiter instance (milliseconds). If provided, must be a number greater than or equal to 1. |
| cost | Number | 1 | The default cost value for for this limiter instance. If provided, must be a number greater than or equal to 0. |

$3

#### limit({ key, burst, rate, period, cost })

`javascript
limiter.limit({
key: 'user/myUser@example.com',
burst: 1000,
rate: 1,
period: 1000,
cost: 2
});
`

In order to perform rate limiting, you need to call the limit method. This function will attempt to consume the given cost from the token pool for this key.
If there are not enough tokens available for the given cost, no tokens will be consumed.
It takes the following options:

| Option | Type | Description |
| :----- | :--- | :---------- |
| key | String | Required. The key to limit/throttle on. The actual Redis key will be prefixed with any keyPrefix given when the limiter was created. |
| burst | Number | The maximum number of tokens available (i.e., token regeneration stops when this number is reached). If not provided, defaults to the burst value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |
| rate | Number | The rate at which tokens regenerate over the given period. If not provided, defaults to the rate value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |
| period | Number | The period (in milliseconds) over which tokens are regenerated at rate. If not provided, defaults to the period value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |
| cost | Number | The cost in tokens of this limit call. If not provided, defaults to the cost value provided when the limiter was created. If provided, must be a number greater than or equal to 0. |

The limit call returns a Promise, which will resolve to an object with the following properties:

| Property | Type | Description |
| :------ | :--- | :---------- |
| limited | Boolean | Represents whether the given limit request was fulfilled. |
| remaining | Number | The number of tokens remaining after this limit request. A request may be limited even if there are tokens available, if the cost was higher than the tokens available. If limited is true, remaining will be the number of tokens currently available _without_ the requested cost being subtracted. |
| retryIn | Number | The number of milliseconds to wait until the given request would be allowed. Will always be 0 if limited is false, and greater than 0 if limited is true. If the cost was higher than burst, it is never possible to fulfill the request, and so retryIn will be Infinity. |
| resetIn | Number | The number of milliseconds until the token pool has regenerated to burst. Will be 0 if the token pool is already at the burst value. |

#### peek({ key, burst, rate, period })

`javascript
limiter.peek({
key: 'user/myUser@example.com',
burst: 1000,
rate: 1,
period: 1000
});
`

The peek function allows you to look at the given state of the token pool for the given key. It
will not consume any tokens. It takes the following options:

| Option | Type | Description |
| :----- | :--- | :---------- |
| key | String | Required. The limiter key to peek at. The actual Redis key will be prefixed with any keyPrefix given when the limiter was created. |
| burst | Number | The maximum number of tokens available (i.e., token regeneration stops when this number is reached). If not provided, defaults to the burst value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |
| rate | Number | The rate at which tokens regenerate over the given period. If not provided, defaults to the rate value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |
| period | Number | The period (in milliseconds) over which tokens are regenerated at rate. If not provided, defaults to the period value provided when the limiter was created. If provided, must be a number greater than or equal to 1. |

The peek call returns a Promise, which will resolve to an object with the following properties:

| Property | Type | Description |
| :------- | :--- | :---------- |
| limited | Boolean | Represents if the given key is currently limited. This will be true only if there are no tokens in the pool. |
| remaining | Number | The number of tokens remaining in the given key's token pool. |
| resetIn | Number | The number of milliseconds until the token pool has regenerated to burst. Will be 0 if the token pool is already at the burst value. |

#### reset

`javascript
limiter.reset({
key: 'user/myUser@example.com'
});
`

The reset function allows you to reset the token pool for the given key. In essence, this just
deletes the relevant key in Redis, which means the key is immediately back to having burst tokens
available. It takes the following options:

| Option | Type | Description |
| :----- | :--- | :---------- |
| key | String | Required. The limiter key to reset. The actual Redis key will be prefixed with any keyPrefix given when the limiter was created. |

The reset call returns a Promise, which will resolve to a Boolean. If the result is true, the key was reset. If the result is false, the key did not need to be reset; there were already burst tokens available.

Node-redis usage

To use this module with node-redis, you must include the include the exported RedisGCRA.defineNodeRedisScripts script as part of the scripts definition in your createClient configuration:

`js
import * as Redis from 'redis';
import RedisGCRA from 'redis-gcra';

const redis = Redis.createClient({
scripts: {
...RedisGCRA.defineNodeRedisScripts(Redis),
/ other custom user scripts defined here /
}
});
const limiter = RedisGCRA({ redis });

(...)
`

If you would like to otherwise customize the provided script definition, you can also import the LUA and customize the script definition further (for example, for usage with Typescript).

`js
import * as Redis from 'redis';
import RedisGCRA from 'redis-gcra';

const redis = Redis.createClient({
scripts: {
performGcraRateLimit: Redis.defineScript({
NUMBER_OF_KEYS: 1,
SCRIPT: RedisGCRA.GCRA_LUA,
transformArguments(key, now, burst, rate, period, cost) {
return [key, now.toString(), burst.toString(), rate.toString(), period.toString(), cost.toString()];
},
transformReply(reply) {
return reply;
}
})
}
});

const limiter = RedisGCRA({ redis });

(...)
`

Example

In this example the rate limit bucket has 1000 tokens, recovering at
a speed of 1 token per second.

`js
import { Redis } from 'io-redis';
import RedisGCRA from 'redis-gcra';

const redis = new Redis();
const limiter = RedisGCRA({ redis });

// In order to perform rate limiting, you need to call the 'limit' method.
let result = await limiter.limit({
key: 'user/myUser@example.com',
burst: 1000, // limit on maximum tokens available
rate: 1, // rate at which tokens regenerate per period
period: 1000, // period, in milliseconds, for token regeneration
cost: 2 // cost in tokens for this limit request
});

result.limited; // => false - request should not be limited
result.remaining; // => 998 - remaining number of tokens until limited
result.retryIn; // => 0 - can retry without delay
result.resetIn; // => ~2000 - in approximately 2 seconds tokens will be regenerated to burst limit

// call limit 500 more times in rapid succession and the 500th call will have:
// result = await limiter.limit(....)
result.limited; // => true - request should be limited
result.remaining; // => 0 - remaining number of tokens until limited
result.retryIn; // => 2000 - can retry in approximately 2 seconds
result.resetIn; // => 1000000 - in approximately 1000 seconds tokens will be regenerated to burst limit
`

The implementation utilizes a single key in Redis that matches the key you pass
to the limit method. If you need to reset the rate limiter for a particular key,
call the reset method:

`js
// Let's imagine 'user/myUser@example.com' is limited.
// This will effectively reset the limit for the key:
await limiter.reset({ key: 'user/myUser@example.com' })
// limit is reset
`

You can also retrieve the current state of the rate limiter for a particular key
without actually modifying the state. In order to do that, use the peek
method:

`js
let result = await limiter.peek({
key: 'user/myUser@example.com',
burst: 1000,
rate: 1,
period: 1000
});

result.limited; // => false - request should not be limited
result.remaining; // => 1000 - remaining number of tokens until limited
result.resetIn; // => 0 - "burst" tokens are already available
``

Inspiration

This code was inspired by the Ruby gem redis-gcra.

License

The module is available as open source under the terms of the MIT License.