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
// }
});
Install Pacer with npm:
npm install pacer
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
// }
});
Create a pacer with the passed in options
object:
var pacer = createPacer({ /* ... */ });
Consume a token for a specified consumer.
consumerId = String
callback = function (consumer) {
consumer = {
id: String,
limit: Number,
remaining: Number,
reset: Number,
allowed: Boolean
}
}
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
}
}
Query the tokens for a specified consumer.
consumerId = String
callback = function (consumer) {
consumer = {
id: String,
limit: Number,
remaining: Number,
reset: Number,
allowed: Boolean
}
}
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
}
}
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
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
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
Pacer is licensed under the MIT license.
Copyright © 2015, Rowan Manning