express-rate-limit 7.3.0 → 7.4.0

package/dist/index.cjs

@@ -227,8 +227,8 @@ var validations = {
     keys.push(prefixedKey);
   },
   /**
-   * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-   * major release.
+   * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+   * changing in the next major release.
    *
    * @param limit {number} - The maximum number of hits per client.
    *
@@ -259,8 +259,8 @@ var validations = {
     }
   },
   /**
-   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-   * major release.
+   * Warns the user that the `onLimitReached` option is deprecated and
+   * will be removed in the next major release.
    *
    * @param onLimitReached {any | undefined} - The maximum number of hits per client.
    *
@@ -291,9 +291,11 @@ var validations = {
     }
   },
   /**
-   * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+   * Checks the options.validate setting to ensure that only recognized
+   * validations are enabled or disabled.
    *
-   * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+   * If any unrecognized values are found, an error is logged that
+   * includes the list of supported vaidations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -312,13 +314,21 @@ var validations = {
     }
   },
   /**
-   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   * Checks to see if the instance was created inside of a request handler,
+   * which would prevent it from working correctly, with the default memory
+   * store (or any other store with localKeys.)
    */
-  creationStack() {
+  creationStack(store) {
     const { stack } = new Error(
       "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
     );
     if (stack?.includes("Layer.handle [as handle_request]")) {
+      if (!store.localKeys) {
+        throw new ValidationError(
+          "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
+          "express-rate-limit instance should *usually* be created at app initialization, not when responding to a request."
+        );
+      }
       throw new ValidationError(
         "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
         `express-rate-limit instance should be created at app initialization, not when responding to a request.`
@@ -617,6 +627,7 @@ var parseOptions = (passedOptions) => {
         response.send(message);
       }
     },
+    passOnStoreError: false,
     // Allow the default options to be overriden by the options passed to the middleware.
     ...notUndefinedOptions,
     // `standardHeaders` is resolved into a draft version above, use that.
@@ -644,7 +655,7 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
-  config.validations.creationStack();
+  config.validations.creationStack(config.store);
   config.validations.unsharedStore(config.store);
   if (typeof config.store.init === "function")
     config.store.init(options);
@@ -657,7 +668,23 @@ var rateLimit = (passedOptions) => {
       }
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
-      const { totalHits, resetTime } = await config.store.increment(key);
+      let totalHits = 0;
+      let resetTime;
+      try {
+        const incrementResult = await config.store.increment(key);
+        totalHits = incrementResult.totalHits;
+        resetTime = incrementResult.resetTime;
+      } catch (error) {
+        if (config.passOnStoreError) {
+          console.error(
+            "express-rate-limit: error from store, allowing request without rate-limiting.",
+            error
+          );
+          next();
+        } else {
+          throw error;
+        }
+      }
       config.validations.positiveHits(totalHits);
       config.validations.singleCount(request, config.store, key);
       const retrieveLimit = typeof config.limit === "function" ? config.limit(request, response) : config.limit;

package/dist/index.d.cts

@@ -60,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -78,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -96,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**
@@ -398,6 +402,10 @@ export type Options = {
 	 * be removed from the library in the foreseeable future.
 	 */
 	max?: number | ValueDeterminingMiddleware<number>;
+	/**
+	 * If the Store generates an error, allow the request to pass.
+	 */
+	passOnStoreError: boolean;
 };
 /**
  * The extended request object that includes information about the client's

package/dist/index.d.mts

@@ -60,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -78,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -96,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**
@@ -398,6 +402,10 @@ export type Options = {
 	 * be removed from the library in the foreseeable future.
 	 */
 	max?: number | ValueDeterminingMiddleware<number>;
+	/**
+	 * If the Store generates an error, allow the request to pass.
+	 */
+	passOnStoreError: boolean;
 };
 /**
  * The extended request object that includes information about the client's

package/dist/index.d.ts

@@ -60,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -78,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -96,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**
@@ -398,6 +402,10 @@ export type Options = {
 	 * be removed from the library in the foreseeable future.
 	 */
 	max?: number | ValueDeterminingMiddleware<number>;
+	/**
+	 * If the Store generates an error, allow the request to pass.
+	 */
+	passOnStoreError: boolean;
 };
 /**
  * The extended request object that includes information about the client's

package/dist/index.mjs

@@ -199,8 +199,8 @@ var validations = {
     keys.push(prefixedKey);
   },
   /**
-   * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-   * major release.
+   * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+   * changing in the next major release.
    *
    * @param limit {number} - The maximum number of hits per client.
    *
@@ -231,8 +231,8 @@ var validations = {
     }
   },
   /**
-   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-   * major release.
+   * Warns the user that the `onLimitReached` option is deprecated and
+   * will be removed in the next major release.
    *
    * @param onLimitReached {any | undefined} - The maximum number of hits per client.
    *
@@ -263,9 +263,11 @@ var validations = {
     }
   },
   /**
-   * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+   * Checks the options.validate setting to ensure that only recognized
+   * validations are enabled or disabled.
    *
-   * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+   * If any unrecognized values are found, an error is logged that
+   * includes the list of supported vaidations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -284,13 +286,21 @@ var validations = {
     }
   },
   /**
-   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   * Checks to see if the instance was created inside of a request handler,
+   * which would prevent it from working correctly, with the default memory
+   * store (or any other store with localKeys.)
    */
-  creationStack() {
+  creationStack(store) {
     const { stack } = new Error(
       "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
     );
     if (stack?.includes("Layer.handle [as handle_request]")) {
+      if (!store.localKeys) {
+        throw new ValidationError(
+          "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
+          "express-rate-limit instance should *usually* be created at app initialization, not when responding to a request."
+        );
+      }
       throw new ValidationError(
         "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
         `express-rate-limit instance should be created at app initialization, not when responding to a request.`
@@ -589,6 +599,7 @@ var parseOptions = (passedOptions) => {
         response.send(message);
       }
     },
+    passOnStoreError: false,
     // Allow the default options to be overriden by the options passed to the middleware.
     ...notUndefinedOptions,
     // `standardHeaders` is resolved into a draft version above, use that.
@@ -616,7 +627,7 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
-  config.validations.creationStack();
+  config.validations.creationStack(config.store);
   config.validations.unsharedStore(config.store);
   if (typeof config.store.init === "function")
     config.store.init(options);
@@ -629,7 +640,23 @@ var rateLimit = (passedOptions) => {
       }
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
-      const { totalHits, resetTime } = await config.store.increment(key);
+      let totalHits = 0;
+      let resetTime;
+      try {
+        const incrementResult = await config.store.increment(key);
+        totalHits = incrementResult.totalHits;
+        resetTime = incrementResult.resetTime;
+      } catch (error) {
+        if (config.passOnStoreError) {
+          console.error(
+            "express-rate-limit: error from store, allowing request without rate-limiting.",
+            error
+          );
+          next();
+        } else {
+          throw error;
+        }
+      }
       config.validations.positiveHits(totalHits);
       config.validations.singleCount(request, config.store, key);
       const retrieveLimit = typeof config.limit === "function" ? config.limit(request, response) : config.limit;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "7.3.0",
+	"version": "7.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.",
 	"author": {
 		"name": "Nathan Friedly",

package/readme.md

@@ -45,23 +45,24 @@ The rate limiter comes with a built-in memory store, and supports a variety of
 All function options may be async. Click the name for additional info and
 default values.
 
-| Option                                                                                                             | Type                             | Remarks                                                                                         |
-| ------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| [`windowMs`](https://express-rate-limit.mintlify.app/reference/configuration#windowms)                             | `number`                         | How long to remember requests for, in milliseconds.                                             |
-| [`limit`](https://express-rate-limit.mintlify.app/reference/configuration#limit)                                   | `number` \| `function`           | How many requests to allow.                                                                     |
-| [`message`](https://express-rate-limit.mintlify.app/reference/configuration#message)                               | `string` \| `json` \| `function` | Response to return after limit is reached.                                                      |
-| [`statusCode`](https://express-rate-limit.mintlify.app/reference/configuration#statuscode)                         | `number`                         | HTTP status code after limit is reached (default is 429).                                       |
-| [`legacyHeaders`](https://express-rate-limit.mintlify.app/reference/configuration#legacyheaders)                   | `boolean`                        | Enable the `X-Rate-Limit` header.                                                               |
-| [`standardHeaders`](https://express-rate-limit.mintlify.app/reference/configuration#standardheaders)               | `'draft-6'` \| `'draft-7'`       | Enable the `Ratelimit` header.                                                                  |
-| [`requestPropertyName`](https://express-rate-limit.mintlify.app/reference/configuration#requestpropertyname)       | `string`                         | Add rate limit info to the `req` object.                                                        |
-| [`skipFailedRequests`](https://express-rate-limit.mintlify.app/reference/configuration#skipfailedrequests)         | `boolean`                        | Uncount 4xx/5xx responses.                                                                      |
-| [`skipSuccessfulRequests`](https://express-rate-limit.mintlify.app/reference/configuration#skipsuccessfulrequests) | `boolean`                        | Uncount 1xx/2xx/3xx responses.                                                                  |
-| [`keyGenerator`](https://express-rate-limit.mintlify.app/reference/configuration#keygenerator)                     | `function`                       | Identify users (defaults to IP address).                                                        |
-| [`handler`](https://express-rate-limit.mintlify.app/reference/configuration#handler)                               | `function`                       | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
-| [`skip`](https://express-rate-limit.mintlify.app/reference/configuration#skip)                                     | `function`                       | Return `true` to bypass the limiter for the given request.                                      |
-| [`requestWasSuccessful`](https://express-rate-limit.mintlify.app/reference/configuration#requestwassuccessful)     | `function`                       | Used by `skipFailedRequests` and `skipSuccessfulRequests`.                                      |
-| [`validate`](https://express-rate-limit.mintlify.app/reference/configuration#validate)                             | `boolean` \| `object`            | Enable or disable built-in validation checks.                                                   |
-| [`store`](https://express-rate-limit.mintlify.app/reference/configuration#store)                                   | `Store`                          | Use a custom store to share hit counts across multiple nodes.                                   |
+| Option                     | Type                             | Remarks                                                                                         |
+| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [`windowMs`]               | `number`                         | How long to remember requests for, in milliseconds.                                             |
+| [`limit`]                  | `number` \| `function`           | How many requests to allow.                                                                     |
+| [`message`]                | `string` \| `json` \| `function` | Response to return after limit is reached.                                                      |
+| [`statusCode`]             | `number`                         | HTTP status code after limit is reached (default is 429).                                       |
+| [`handler`]                | `function`                       | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
+| [`legacyHeaders`]          | `boolean`                        | Enable the `X-Rate-Limit` header.                                                               |
+| [`standardHeaders`]        | `'draft-6'` \| `'draft-7'`       | Enable the `Ratelimit` header.                                                                  |
+| [`store`]                  | `Store`                          | Use a custom store to share hit counts across multiple nodes.                                   |
+| [`passOnStoreError`]       | `boolean`                        | Allow (`true`) or block (`false`, default) traffic if the store becomes unavailable.            |
+| [`keyGenerator`]           | `function`                       | Identify users (defaults to IP address).                                                        |
+| [`requestPropertyName`]    | `string`                         | Add rate limit info to the `req` object.                                                        |
+| [`skip`]                   | `function`                       | Return `true` to bypass the limiter for the given request.                                      |
+| [`skipSuccessfulRequests`] | `boolean`                        | Uncount 1xx/2xx/3xx responses.                                                                  |
+| [`skipFailedRequests`]     | `boolean`                        | Uncount 4xx/5xx responses.                                                                      |
+| [`requestWasSuccessful`]   | `function`                       | Used by `skipSuccessfulRequests` and `skipFailedRequests`.                                      |
+| [`validate`]               | `boolean` \| `object`            | Enable or disable built-in validation checks.                                                   |
 
 ## Thank You
 
@@ -111,3 +112,33 @@ Then you can pick up any issue and fix/implement it!
 
 MIT © [Nathan Friedly](http://nfriedly.com/),
 [Vedant K](https://github.com/gamemaker1)
+
+[`windowMs`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#windowms
+[`limit`]: https://express-rate-limit.mintlify.app/reference/configuration#limit
+[`message`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#message
+[`statusCode`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#statuscode
+[`handler`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#handler
+[`legacyHeaders`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#legacyheaders
+[`standardHeaders`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#standardheaders
+[`store`]: https://express-rate-limit.mintlify.app/reference/configuration#store
+[`passOnStoreError`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#passOnStoreError
+[`keyGenerator`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#keygenerator
+[`requestPropertyName`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#requestpropertyname
+[`skip`]: https://express-rate-limit.mintlify.app/reference/configuration#skip
+[`skipSuccessfulRequests`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#skipsuccessfulrequests
+[`skipFailedRequests`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#skipfailedrequests
+[`requestWasSuccessful`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#requestwassuccessful
+[`validate`]:
+	https://express-rate-limit.mintlify.app/reference/configuration#validate