Pacer
A flexible, fault-tolerant, Redis-based rate-limiter for Node.js.
var createPacer = ; var pacer = ; pacer;
Table Of Contents
Install
Install Pacer with npm:
npm install pacer
Getting Started
Require in and Pacer:
var createPacer = ;
Create a Pacer instance, passing in some options:
var pacer = ;
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;
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;
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;
Usage
Create a pacer with the passed in options
object:
var pacer = ;
Consuming
pacer.consume(consumerId, callback)
Consume a token for a specified consumer.
consumerId = String { 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 { 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 { 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 { 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