express-rate-limit 5.2.3 → 5.4.0

package/README.md

@@ -1,7 +1,7 @@
 # Express Rate Limit
 
-![Node.js CI](https://github.com/nfriedly/express-rate-limit/workflows/Node.js%20CI/badge.svg)
-[![NPM version](http://badge.fury.io/js/express-rate-limit.png)](https://npmjs.org/package/express-rate-limit "View this project on NPM")
+[![Node.js CI](https://github.com/nfriedly/express-rate-limit/workflows/Node.js%20CI/badge.svg)](https://github.com/nfriedly/express-rate-limit/actions)
+[![NPM version](https://img.shields.io/npm/v/express-rate-limit.svg)](https://npmjs.org/package/express-rate-limit "View this project on NPM")
 [![npm downloads](https://img.shields.io/npm/dm/express-rate-limit)](https://www.npmjs.com/package/express-rate-limit)
 
 
@@ -9,12 +9,11 @@ Basic rate-limiting middleware for Express. Use to limit repeated requests to pu
 
 Plays nice with [express-slow-down](https://www.npmjs.com/package/express-slow-down).
 
-Note: this module does not share state with other processes/servers by default.
-If you need a more robust solution, I recommend using an external store:
+Note: this module does not share state with other processes/servers by default. It also buckets all requests to an internal clock rather than starting a new timer for each end-user. It's fine for abuse-prevention but might not produce the desired effect when attempting to strictly enforce API rate-limits or similar. If you need a more robust solution, I recommend using an external store:
 
 ### Stores
 
-- Memory Store _(default, built-in)_ - stores hits in-memory in the Node.js process. Does not share state with other servers or processes.
+- Memory Store _(default, built-in)_ - stores hits in-memory in the Node.js process. Does not share state with other servers or processes, and does not start a separate timer for each end user.
 - [Redis Store](https://npmjs.com/package/rate-limit-redis)
 - [Memcached Store](https://npmjs.org/package/rate-limit-memcached)
 - [Mongo Store](https://www.npmjs.com/package/rate-limit-mongo)
@@ -103,6 +102,8 @@ 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 and, if the store provides it, a `resetTime` Date object. These may be used in your application code to take additional actions or inform the user of their status.
 
+The property name can be configured with the configuration option `requestPropertyName`
+
 ## Configuration options
 
 ### max
@@ -113,6 +114,31 @@ May be a number, or a function that returns a number or a promise. If `max` is a
 
 Defaults to `5`. Set to `0` to disable.
 
+Example of using a function:
+
+```js
+const rateLimit = require("express-rate-limit");
+
+function isPremium(req) {
+  //...
+}
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  
+  // max could also be an async function or return a promise
+  max: function(req, res) {
+    if (isPremium(req)) {
+      return 10;
+    }
+    return 5;
+  }
+});
+
+//  apply to all requests
+app.use(limiter);
+```
+
 ### windowMs
 
 Timeframe for which requests are checked/remembered. Also used in the Retry-After header when the limit is reached.
@@ -187,6 +213,19 @@ function (req, res, options) {
 }
 ```
 
+### requestWasSuccessful
+
+Function that is called when `skipFailedRequests` and/or `skipSuccessfulRequests` are set to `true`.
+May be overridden if, for example, a service sends out a 200 status code on errors.
+
+Defaults to
+
+```js
+function (req, res) {
+    return res.statusCode < 400;
+}
+```
+
 ### skipFailedRequests
 
 When set to `true`, failed requests won't be counted. Request considered failed when:
@@ -218,6 +257,11 @@ function (/*req, res*/) {
 }
 ```
 
+### requestPropertyName
+Parameter to add to `req`-Object. 
+
+Defaults to `rateLimit`.
+
 ### store
 
 The storage to use when persisting rate limit attempts.
@@ -302,4 +346,4 @@ v2 uses a less precise but less resource intensive method of tracking hits from
 
 ## License
 
-MIT © [Nathan Friedly](http://nfriedly.com/)
+MIT © [Nathan Friedly](http://nfriedly.com/)

package/lib/express-rate-limit.js

@@ -10,8 +10,12 @@ function RateLimit(options) {
       statusCode: 429, // 429 status = Too Many Requests (RFC 6585)
       headers: true, //Send custom rate limit header with limit and remaining
       draft_polli_ratelimit_headers: false, //Support for the new RateLimit standardization headers
-      skipFailedRequests: false, // Do not count failed requests (status >= 400)
-      skipSuccessfulRequests: false, // Do not count successful requests (status < 400)
+      // ability to manually decide if request was successful. Used when `skipSuccessfulRequests` and/or `skipFailedRequests` are set to `true`
+      requestWasSuccessful: function (req, res) {
+        return res.statusCode < 400;
+      },
+      skipFailedRequests: false, // Do not count failed requests
+      skipSuccessfulRequests: false, // Do not count successful requests
       // allows to create custom keys (by default user IP is used)
       keyGenerator: function (req /*, res*/) {
         return req.ip;
@@ -23,6 +27,7 @@ function RateLimit(options) {
         res.status(options.statusCode).send(options.message);
       },
       onLimitReached: function (/*req, res, optionsUsed*/) {},
+      requestPropertyName: "rateLimit", // Parameter name appended to req object
     },
     options
   );
@@ -70,7 +75,7 @@ function RateLimit(options) {
 
           Promise.resolve(maxResult)
             .then((max) => {
-              req.rateLimit = {
+              req[options.requestPropertyName] = {
                 limit: max,
                 current: current,
                 remaining: Math.max(max - current, 0),
@@ -79,10 +84,13 @@ function RateLimit(options) {
 
               if (options.headers && !res.headersSent) {
                 res.setHeader("X-RateLimit-Limit", max);
-                res.setHeader("X-RateLimit-Remaining", req.rateLimit.remaining);
+                res.setHeader(
+                  "X-RateLimit-Remaining",
+                  req[options.requestPropertyName].remaining
+                );
                 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("Date", new Date().toUTCString());
                   res.setHeader(
                     "X-RateLimit-Reset",
                     Math.ceil(resetTime.getTime() / 1000)
@@ -91,7 +99,10 @@ function RateLimit(options) {
               }
               if (options.draft_polli_ratelimit_headers && !res.headersSent) {
                 res.setHeader("RateLimit-Limit", max);
-                res.setHeader("RateLimit-Remaining", req.rateLimit.remaining);
+                res.setHeader(
+                  "RateLimit-Remaining",
+                  req[options.requestPropertyName].remaining
+                );
                 if (resetTime) {
                   const deltaSeconds = Math.ceil(
                     (resetTime.getTime() - Date.now()) / 1000
@@ -114,7 +125,7 @@ function RateLimit(options) {
 
                 if (options.skipFailedRequests) {
                   res.on("finish", function () {
-                    if (res.statusCode >= 400) {
+                    if (!options.requestWasSuccessful(req, res)) {
                       decrementKey();
                     }
                   });
@@ -130,7 +141,7 @@ function RateLimit(options) {
 
                 if (options.skipSuccessfulRequests) {
                   res.on("finish", function () {
-                    if (res.statusCode < 400) {
+                    if (options.requestWasSuccessful(req, res)) {
                       options.store.decrement(key);
                     }
                   });
@@ -152,9 +163,13 @@ function RateLimit(options) {
               }
 
               next();
+
+              return null;
             })
             .catch(next);
         });
+
+        return null;
       })
       .catch(next);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-rate-limit",
-  "version": "5.2.3",
+  "version": "5.4.0",
   "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": {
@@ -31,17 +31,18 @@
     "brute-force",
     "attack"
   ],
-  "dependencies": {},
   "devDependencies": {
-    "eslint": "^6.8.0",
-    "eslint-config-prettier": "^6.10.1",
-    "eslint-plugin-prettier": "^3.1.2",
+    "bluebird": "^3.7.2",
+    "eslint": "^7.32.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
     "express": "^4.17.1",
-    "husky": "^4.2.3",
-    "mocha": "^7.1.1",
-    "prettier": "^2.0.4",
-    "pretty-quick": "^2.0.1",
-    "supertest": "^4.0.2"
+    "husky": "^7.0.2",
+    "mocha": "^9.1.2",
+    "prettier": "^2.4.1",
+    "pretty-quick": "^3.1.1",
+    "sinon": "^11.1.2",
+    "supertest": "^6.1.6"
   },
   "scripts": {
     "lint": "eslint .",