[UNMAINTAINED] A flexible, fau

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

NOTE: This project is no longer being maintained. If you're interested in taking over maintenance, please contact me.

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.

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

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

The Redis database index to use. Defaults to 0.

The port Redis is running on. Defaults to 6379.

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

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

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.

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.

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