Shen
Simple IP/API Key rate-limiting middleware.
About
What is Shen Rate Limit?
A simple express rate-limiting, who uses user ip or an specific key to control access on REST APIs.
Getting started
Install
$ npm install --save shen-rate-limit
Features
Key management
With Shen you can manage your KeyChan, adding, removing and cleaning all keys.
- Adding new key:
var rateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var limiter = /*options*/; limiter;
- Removing a key:
var rateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var limiter = /*options*/; limiter;
- Cleaning all keys:
var rateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var limiter = /*options*/; limiter;
IP Whitelist
Shen includes a whitelist system. You can configure which IP won't need to provide an API KEY, and won't consume the rate-limit(This is an array).
Json-based database
Shen includes an json-based. Shen reads a json file, an add all created keys to keychan. Every time a key is added, removed or cleaned, Shen overwritten the json file.
Documentation
Usage
For an API-only server where the rate-limiter should be applied to all requests:
var RateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var limiter = windowMs: 15*60*1000 // 15 minutes max: 100 // limit each IP to 100 requests per windowMs delayMs: 0 // disable delaying - full speed until the max limit is reached ; // apply to all requests app;
For a "regular" web server (e.g. anything that uses express.static()
), where the rate-limiter should only apply to certain requests:
var RateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var apiLimiter = windowMs: 15*60*1000 // 15 minutes max: 100 delayMs: 0 // disabled ; // only apply to requests that begin with /api/ app;
Create multiple instances to apply different rules to different routes:
var RateLimit = ; app; // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc) var apiLimiter = windowMs: 15*60*1000 // 15 minutes max: 100 delayMs: 0 // disabled ; app; var createAccountLimiter = windowMs: 60*60*1000 // 1 hour window delayAfter: 1 // begin slowing down responses after the first request delayMs: 3*1000 // slow down subsequent responses by 3 seconds per request max: 5 // start blocking after 5 requests message: "Too many accounts created from this IP, please try again after an hour" ; app;
Configuration
- windowMs: milliseconds - how long to keep records of requests in memory. Defaults to
60000
(1 minute). - delayAfter: max number of connections during
windowMs
before starting to delay responses. Defaults to1
. Set to0
to disable delaying. - delayMs: milliseconds - how long to delay the response, multiplied by (number of recent hits -
delayAfter
). Defaults to1000
(1 second). Set to0
to disable delaying. - max: max number of connections during
windowMs
milliseconds before sending a 429 response. Defaults to5
. Set to0
to disable. - message: Error message returned when
max
is exceeded. Defaults to'Too many requests, please try again later.'
- statusCode: HTTP status code returned when
max
is exceeded. Defaults to429
. - headers: Enable header to show request limit and current usage
- allowedIp: Whitelisted ip (an array), won't consume Rate limit and won't need an API KEY.
- keyGet: Function used to get user key. By default passed by header X-RateLimit-ApiKey. Defaults:
{ return req;}
- handler: The function to execute once the max limit is exceeded. It receives the request and the response objects. The "next" param is available if you need to pass to the next middleware. Defaults:
{ res;}
- store: The storage to use when persisting rate limit attempts. By default, the MemoryStore is used. It must implement the following in order to function:
{ /** * Increments the value in the underlying store for the given key. * @method function * @param * down from RateLimit. * @param * store is finished. */ this { // ... }; /** * This callback is called by the underlying store when an answer to the * increment is available. * @callback Store~incrCallback * @param * error occurred. * @param */ /** * Resets a value with the given key. * @method function * @param {[type]} key - The key to reset */ this { // ... }; /** * Adds a new key. * @method function * @param {[type]} key - The key to add */ this { // ... }; /** * Remove a key. * @method function * @param {[type]} key - The key to remove */ this { // ... }; /** * Reset all keys. * @method function */ this { // ... };};
Avaliable data stores are:
- MemoryStore: (default)Basic json-based memory, every time servers up, load a json file. Every time a key is add/clean/removed, an json file is overwritten.
The delayAfter
and delayMs
options were written for human-facing pages such as login and password reset forms.
For public APIs, setting these to 0
(disabled) and relying on only windowMs
and max
for rate-limiting usually makes the most sense.
Contributors
License
You can check out the full license here
This project is licensed under the terms of the MIT license.