express-rate-limit 2.13.1 → 2.14.2

package/README.md

@@ -1,4 +1,4 @@
-#  Express Rate Limit
+# Express Rate Limit
 
 [![Build Status](https://secure.travis-ci.org/nfriedly/express-rate-limit.png?branch=master)](http://travis-ci.org/nfriedly/express-rate-limit)
 [![NPM version](http://badge.fury.io/js/express-rate-limit.png)](https://npmjs.org/package/express-rate-limit "View this project on NPM")
@@ -12,18 +12,17 @@ If you need a more robust solution, I recommend using an addon store or trying o
 
 ### Stores
 
-* Memory Store _(default, built-in)_ - stores hits in-memory in the Node.js process. Does not share state with other servers or processes.
-* [Redis Store](https://npmjs.com/package/rate-limit-redis)
-* [Memcached Store](https://npmjs.org/package/rate-limit-memcached)
+- Memory Store _(default, built-in)_ - stores hits in-memory in the Node.js process. Does not share state with other servers or processes.
+- [Redis Store](https://npmjs.com/package/rate-limit-redis)
+- [Memcached Store](https://npmjs.org/package/rate-limit-memcached)
 
 ### Alternate Rate-limiters
 
 This module was designed to only handle the basics and didn't even support external stores initially. These other options all are excellent pieces of software and may be more appropriate for some situations:
 
-* [strict-rate-limiter](https://www.npmjs.com/package/strict-rate-limiter)
-* [express-brute](https://www.npmjs.com/package/express-brute)
-* [rate-limiter](https://www.npmjs.com/package/express-limiter)
-
+- [strict-rate-limiter](https://www.npmjs.com/package/strict-rate-limiter)
+- [express-brute](https://www.npmjs.com/package/express-brute)
+- [rate-limiter](https://www.npmjs.com/package/express-limiter)
 
 ## Install
 
@@ -36,12 +35,12 @@ $ npm install --save express-rate-limit
 For an API-only server where the rate-limiter should be applied to all requests:
 
 ```js
-var RateLimit = require('express-rate-limit');
+var RateLimit = require("express-rate-limit");
 
-app.enable('trust proxy'); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
+app.enable("trust proxy"); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
 
 var limiter = new RateLimit({
-  windowMs: 15*60*1000, // 15 minutes
+  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
 });
@@ -53,73 +52,78 @@ app.use(limiter);
 For a "regular" web server (e.g. anything that uses `express.static()`), where the rate-limiter should only apply to certain requests:
 
 ```js
-var RateLimit = require('express-rate-limit');
+var RateLimit = require("express-rate-limit");
 
-app.enable('trust proxy'); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
+app.enable("trust proxy"); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
 
 var apiLimiter = new RateLimit({
-  windowMs: 15*60*1000, // 15 minutes
+  windowMs: 15 * 60 * 1000, // 15 minutes
   max: 100,
   delayMs: 0 // disabled
 });
 
 // only apply to requests that begin with /api/
-app.use('/api/', apiLimiter);
-
+app.use("/api/", apiLimiter);
 ```
 
 Create multiple instances to apply different rules to different routes:
 
 ```js
-var RateLimit = require('express-rate-limit');
+var RateLimit = require("express-rate-limit");
 
-app.enable('trust proxy'); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
+app.enable("trust proxy"); // only if you're behind a reverse proxy (Heroku, Bluemix, AWS if you use an ELB, custom Nginx setup, etc)
 
 var apiLimiter = new RateLimit({
-  windowMs: 15*60*1000, // 15 minutes
+  windowMs: 15 * 60 * 1000, // 15 minutes
   max: 100,
   delayMs: 0 // disabled
 });
-app.use('/api/', apiLimiter);
+app.use("/api/", apiLimiter);
 
 var createAccountLimiter = new RateLimit({
-  windowMs: 60*60*1000, // 1 hour window
+  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
+  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"
+  message:
+    "Too many accounts created from this IP, please try again after an hour"
 });
-app.post('/create-account', createAccountLimiter, function(req, res) {
- //...
+app.post("/create-account", createAccountLimiter, function(req, res) {
+  //...
 });
 ```
 
-A `req.rateLimit` property is added to all requests with the `limit`, `current`, and `remaining` number of requests for usage in your application code.
+A `req.rateLimit` property is added to all requests with the `limit`, `current`, and `remaining` number of requests for usage in your application code and, if the store provides it, a resetTime Date object.
 
 ## 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 to `1`. Set to `0` to disable delaying.  
-* **delayMs**: milliseconds - how long to delay the response, multiplied by (number of recent hits - `delayAfter`).  Defaults to `1000` (1 second). Set to `0` to disable delaying.
-* **max**: max number of connections during `windowMs` milliseconds before sending a 429 response. Defaults to `5`. Set to `0` 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 to `429`.
-* **headers**: Enable headers for request limit (`X-RateLimit-Limit`) and current usage (`X-RateLimit-Remaining`) on all responses and time to wait before retrying (`Retry-After`) when `max` is exceeded.
-* **skipFailedRequests**: when `true` failed requests (response status >= 400) won't be counted. Defaults to `false`.
-* **skipSuccessfulRequests**: when `true` successful requests (response status < 400) won't be counted. Defaults to `false`.
-* **keyGenerator**: Function used to generate keys. By default user IP address (req.ip) is used. Defaults:
+- **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 to `1`. Set to `0` to disable delaying.
+- **delayMs**: milliseconds - how long to delay the response, multiplied by (number of recent hits - `delayAfter`). Defaults to `1000` (1 second). Set to `0` to disable delaying.
+- **max**: max number of connections during `windowMs` milliseconds before sending a 429 response. Defaults to `5`. Set to `0` 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 to `429`.
+- **headers**: Enable headers for request limit (`X-RateLimit-Limit`) and current usage (`X-RateLimit-Remaining`) on all responses and time to wait before retrying (`Retry-After`) when `max` is exceeded.
+- **skipFailedRequests**: when `true` failed requests (response status >= 400) won't be counted. Defaults to `false`.
+- **skipSuccessfulRequests**: when `true` successful requests (response status < 400) won't be counted. Defaults to `false`.
+- **keyGenerator**: Function used to generate keys. By default user IP address (req.ip) is used. Defaults:
+
 ```js
 function (req /*, res*/) {
     return req.ip;
 }
 ```
-* **skip**: Function used to skip requests. Returning true from the function will skip limiting for that request. Defaults:
+
+- **skip**: Function used to skip requests. Returning true from the function will skip limiting for that request. Defaults:
+
 ```js
 function (/*req, res*/) {
     return false;
 }
 ```
-* **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:
+
+- **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:
+
 ```js
 function (req, res, /*next*/) {
   if (options.headers) {
@@ -135,70 +139,78 @@ function (req, res, /*next*/) {
   });
 }
 ```
-* **onLimitReached**: Function to listen each time the limit is reached. You can use it to debug/log. Defaults:
+
+- **onLimitReached**: Function to listen each time the limit is reached. You can use it to debug/log. Defaults:
+
 ```js
 function (req, res, options) {
   /* empty */
 }
 ```
-* **store**: The storage to use when persisting rate limit attempts. By default, the [MemoryStore](lib/memory-store.js) is used. It must implement the following in order to function:
+
+- **store**: The storage to use when persisting rate limit attempts. By default, the [MemoryStore](lib/memory-store.js) is used. It must implement the following in order to function:
+
 ```js
 function SomeStore() {
-    /**
-      * Increments the value in the underlying store for the given key.
-      * @method function
-      * @param {string} key - The key to use as the unique identifier passed
-      *                     down from RateLimit.
-      * @param {Store~incrCallback} cb - The callback issued when the underlying
-      *                                store is finished.
-      */
-    this.incr = function(key, cb) {
-      // ...
-    };
-
-    /**
-      * Decrements the value in the underlying store for the given key. Used only when skipFailedRequests is true
-      * @method function
-      * @param {string} key - The key to use as the unique identifier passed
-      *                     down from RateLimit.
-      */
-    this.decrement = function(key) {
-      // ...
-    };
-
-    /**
-     * This callback is called by the underlying store when an answer to the
-     * increment is available.
-     * @callback Store~incrCallback
-     * @param {?object} err - The error from the underlying store, or null if no
-     *                      error occurred.
-     * @param {number} value - The current value of the counter
-     */
-
-    /**
-     * Resets a value with the given key.
-     * @method function
-     * @param  {[type]} key - The key to reset
-     */
-    this.resetKey = function(key) {
-      // ...
-    };
-};
+  /**
+   * Increments the value in the underlying store for the given key.
+   * @method function
+   * @param {string} key - The key to use as the unique identifier passed
+   *                     down from RateLimit.
+   * @param {Store~incrCallback} cb - The callback issued when the underlying
+   *                                store is finished.
+   *
+   * The callback should be triggered with three values:
+   *  - error (usually null)
+   *  - hitCount for this IP
+   *  - resetTime - JS Date object (optional, but necessary for X-RateLimit-Reset header)
+   */
+  this.incr = function(key, cb) {
+    // ...
+  };
+
+  /**
+   * Decrements the value in the underlying store for the given key. Used only when skipFailedRequests is true
+   * @method function
+   * @param {string} key - The key to use as the unique identifier passed
+   *                     down from RateLimit.
+   */
+  this.decrement = function(key) {
+    // ...
+  };
+
+  /**
+   * This callback is called by the underlying store when an answer to the
+   * increment is available.
+   * @callback Store~incrCallback
+   * @param {?object} err - The error from the underlying store, or null if no
+   *                      error occurred.
+   * @param {number} value - The current value of the counter
+   */
+
+  /**
+   * Resets a value with the given key.
+   * @method function
+   * @param  {[type]} key - The key to reset
+   */
+  this.resetKey = function(key) {
+    // ...
+  };
+}
 ```
 
-  Avaliable data stores are:
-   * MemoryStore: _(default)_ Simple in-memory option. Does not share state when app has multiple processes or servers.
-   * [rate-limit-redis](https://npmjs.com/package/rate-limit-redis): A [Redis](http://redis.io/)-backed store, more suitable for large or demanding deployments.
-   * [rate-limit-memcached](https://npmjs.org/package/rate-limit-memcached): A [Memcached](https://memcached.org/)-backed store.
+Available data stores are:
 
+- MemoryStore: _(default)_ Simple in-memory option. Does not share state when app has multiple processes or servers.
+- [rate-limit-redis](https://npmjs.com/package/rate-limit-redis): A [Redis](http://redis.io/)-backed store, more suitable for large or demanding deployments.
+- [rate-limit-memcached](https://npmjs.org/package/rate-limit-memcached): A [Memcached](https://memcached.org/)-backed store.
 
 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.
 
-
 ## Instance API
 
-* **resetKey(key)**: Resets the rate limiting for a given key. (Allow users to complete a captcha or whatever to reset their rate limit, then call this method.)
+- **resetKey(key)**: Resets the rate limiting for a given key. (Allow users to complete a captcha or whatever to reset their rate limit, then call this method.)
 
 ## v2 changes
 

package/lib/express-rate-limit.js

@@ -78,10 +78,13 @@ function RateLimit(options) {
       if (options.headers) {
         res.setHeader("X-RateLimit-Limit", options.max);
         res.setHeader("X-RateLimit-Remaining", req.rateLimit.remaining);
-        if (resetTime) {
+        if (resetTime instanceof Date) {
           // if we have a resetTime, also provide the current date to help avoid issues with incorrect clocks
           res.setHeader("Date", new Date().toGMTString());
-          res.setHeader("X-RateLimit-Reset", resetTime);
+          res.setHeader(
+            "X-RateLimit-Reset",
+            Math.ceil(resetTime.getTime() / 1000)
+          );
         }
       }
 

package/lib/memory-store.js

@@ -1,7 +1,9 @@
 "use strict";
 
 function calculateNextResetTime(windowMs) {
-  return Math.ceil((Date.now() + windowMs) / 1000);
+  var d = new Date();
+  d.setMilliseconds(d.getMilliseconds() + windowMs);
+  return d;
 }
 
 function MemoryStore(windowMs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-rate-limit",
-  "version": "2.13.1",
+  "version": "2.14.2",
   "description": "Basic IP rate-limiting middleware for Express. Use to limit repeated requests to public APIs and/or endpoints such as password reset.",
   "homepage": "https://github.com/nfriedly/express-rate-limit",
   "author": {