Node Redis GCRA Library

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

npm install redis-gcra

or

yarn install redis-gcra

API Documentation

RedisGCRA({ redis, keyPrefix, burst, rate, period, cost })

const RedisGCRA = require('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:

Instance Functions

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

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:

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

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

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:

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

reset

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:

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:

const Redis = require('redis');
const RedisGCRA = require('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).

const Redis = require('redis');
const RedisGCRA = require('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.

const Redis     = require('ioredis');
const RedisGCRA = require('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:

// 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:

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.