Pacer

A flexible, fault-tolerant, Redis-based rate-limiter for Node.js.

var createPacer = require('pacer');

var pacer = createPacer({
    limit: 5,  // Allow 5 requests...
    reset: 10  // ...every 10 seconds
});

pacer.consume('consumer-identifier', function (consumer) {
    // consumer == {
    //     id: 'consumer-identifier',
    //     limit: 5,
    //     remaining: 4,
    //     reset: 10,
    //     allowed: true
    // }
});

Table Of Contents

• Install
• Getting Started
• Usage
• Options
• Examples
• Contributing
• License

Install

Install Pacer with npm:

npm install pacer

Getting Started

Require in and Pacer:

var createPacer = require('pacer');

Create a Pacer instance, passing in some options:

var pacer = createPacer({
    limit: 5,  // Allow 5 requests...
    reset: 10  // ...every 10 seconds
});

Consume a token for the 'foo' consumer. The consumer identifier can be any string you like, for example the request IP, or a username.

pacer.consume('foo', function (consumer) {
    // consumer == {
    //     id: 'foo',
    //     limit: 5,
    //     remaining: 4,
    //     reset: 10,
    //     allowed: true
    // }
});

Consumer can also be an object, allowing you to specify a custom limit and reset time for them. This could be used to provide different tiers of rate limiting depending on the user that is accessing your application.

pacer.consume({
    id: 'foo',
    limit: 10,  // Allow 10 requests...
    reset: 5    // ...every 5 seconds
}, function (consumer) {
    // consumer == {
    //     id: 'consumer-identifier',
    //     limit: 10,
    //     remaining: 9,
    //     reset: 5,
    //     allowed: true
    // }
});

If you don't wish to consume a token but want to query how many tokens a consumer has remaining, you can use the query method. This works with string or object consumers.

pacer.query('foo', function (consumer) {
    // consumer == {
    //     id: 'foo',
    //     limit: 5,
    //     remaining: 5,
    //     reset: 10,
    //     allowed: true
    // }
});

Usage

Create a pacer with the passed in options object:

var pacer = createPacer({ /* ... */ });

Consuming

pacer.consume(consumerId, callback)

Consume a token for a specified consumer.

consumerId = String
callback = function (consumer) {
    consumer = {
        id: String,
        limit: Number,
        remaining: Number,
        reset: Number,
        allowed: Boolean
    }
}

pacer.consume(consumer, callback)

Consume a token for a specified consumer using a custom limit and reset time.

consumer = {
    id: String,
    limit: Number,
    reset: Number
}
callback = function (consumer) {
    consumer = {
        id: String,
        limit: Number,
        remaining: Number,
        reset: Number,
        allowed: Boolean
    }
}

Querying

pacer.query(consumerId, callback)

Query the tokens for a specified consumer.

consumerId = String
callback = function (consumer) {
    consumer = {
        id: String,
        limit: Number,
        remaining: Number,
        reset: Number,
        allowed: Boolean
    }
}

pacer.query(consumer, callback)

Query the tokens for a specified consumer using a custom limit and reset time.

consumer = {
    id: String,
    limit: Number,
    reset: Number
}
callback = function (consumer) {
    consumer = {
        id: String,
        limit: Number,
        remaining: Number,
        reset: Number,
        allowed: Boolean
    }
}

Options

allowOnError (boolean)

Whether to allow access for all consumers if the Redis server errors or is down. Defaults to true.

limit (number)

The maximum number of tokens a consumer can use. Defaults to 100.

redisHost (string)

The host Redis is running on. Defaults to 'localhost'.

redisIndex (number)

The Redis database index to use. Defaults to 0.

redisPort (number)

The port Redis is running on. Defaults to 6379.

reset (number)

The amount of time (in seconds) before tokens for a consumer are reset to their maximum. Defaults to 3600.

Examples

Pacer comes with a few examples which demonstrate how you can integrate it with your applications:

Basic Example

A simple command-line interface which consumes a rate-limiting token for the given consumer every time it's called.

node example/basic myconsumerid

Query Example

A simple command-line interface which queries the rate-limiting tokens for the given consumer every time it's called, without consuming one.

node example/query myconsumerid

Basic Connect Example

A connect application which consumes a rate-limiting token for the client IP whenever a request it made.

node example/connect-basic

Then open http://localhost:3000/ in your browser.

Connect With Varying Rates Example

A connect application which consumes a rate-limiting token for the client IP whenever a request it made. Google Chrome users get a higher rate limit and a faster reset time, to demonstrate varying rates for different consumer types.

node example/connect-varying-rates

Then open http://localhost:3000/ in your browser.

Contributing

To contribute to Pacer, clone this repo locally and commit your code on a separate branch.

Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:

make ci

License

Pacer is licensed under the MIT license.
Copyright © 2015, Rowan Manning