express-rate-limit 6.8.1 → 6.10.0

package/changelog.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.10.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.10.0)
+
+### Added
+
+- Support for combined `RateLimit` header from the
+  [RateLimit header fields for HTTP standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers)
+  adopted by the IETF. Enable by setting `standardHeaders: 'draft-7'`
+- New `standardHeaders: 'draft-6'` option, treated equivalent to
+  `standardHeaders: true` from previous releases. (`true` and `false` are still
+  supported.)
+- New `RateLimit-Policy` header added when `standardHeaders` is set to
+  `'draft-6'`, `'draft-7'`, or `true`
+- Warning when using deprecated `draft_polli_ratelimit_headers` option
+- Warning when using deprecated `onLimitReached` option
+- Warning when `totalHits` value returned from Store is invalid
+
+## [6.9.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.9.0)
+
+### Added
+
+- New validaion check for double-counted requests
+- Added help link to each ValidationError, directing users to the appropriate
+  wiki page for more info
+
+### Changed
+
+- Miscaleanous documenation improvements
+
 ## [6.8.1](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.8.0) & [6.7.2](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.8.0)
 
 ### Changed

package/dist/index.cjs

@@ -31,6 +31,59 @@ __export(source_exports, {
 });
 module.exports = __toCommonJS(source_exports);
 
+// source/headers.ts
+var getResetSeconds = (resetTime, windowMs) => {
+  let resetSeconds = void 0;
+  if (resetTime) {
+    const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+    resetSeconds = Math.max(0, deltaSeconds);
+  } else if (windowMs) {
+    resetSeconds = Math.ceil(windowMs / 1e3);
+  }
+  return resetSeconds;
+};
+var setLegacyHeaders = (response, info) => {
+  if (response.headersSent)
+    return;
+  response.setHeader("X-RateLimit-Limit", info.limit);
+  response.setHeader("X-RateLimit-Remaining", info.remaining);
+  if (info.resetTime instanceof Date) {
+    response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
+    response.setHeader(
+      "X-RateLimit-Reset",
+      Math.ceil(info.resetTime.getTime() / 1e3)
+    );
+  }
+};
+var setDraft6Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader("RateLimit-Limit", info.limit);
+  response.setHeader("RateLimit-Remaining", info.remaining);
+  if (resetSeconds)
+    response.setHeader("RateLimit-Reset", resetSeconds);
+};
+var setDraft7Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader(
+    "RateLimit",
+    `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
+  );
+};
+var setRetryAfterHeader = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("Retry-After", resetSeconds);
+};
+
 // source/validations.ts
 var import_node_net = require("net");
 var ValidationError = class extends Error {
@@ -38,21 +91,23 @@ var ValidationError = class extends Error {
    * The code must be a string, in snake case and all capital, that starts with
    * the substring `ERR_ERL_`.
    *
-   * The message must be a string, starting with a lowercase character,
+   * The message must be a string, starting with an uppercase character,
    * describing the issue in detail.
    */
   constructor(code, message) {
-    super(
-      `express-rate-limit: ${code} - ${message} See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#${code.toLowerCase()} for more information on this error.`
-    );
+    const url = `https://express-rate-limit.github.io/${code}/`;
+    super(`${message} See ${url} for more information.`);
     __publicField(this, "name");
     __publicField(this, "code");
+    __publicField(this, "help");
     this.name = this.constructor.name;
     this.code = code;
-    this.message = message;
+    this.help = url;
   }
 };
-var Validations = class {
+var ChangeWarning = class extends ValidationError {
+};
+var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
     __publicField(this, "enabled");
@@ -129,6 +184,125 @@ var Validations = class {
       }
     });
   }
+  /**
+   * Ensures totalHits value from store is a positive integer.
+   *
+   * @param hits {any} - The `totalHits` returned by the store.
+   */
+  positiveHits(hits) {
+    this.wrap(() => {
+      if (typeof hits !== "number" || hits < 1 || hits !== Math.round(hits)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_HITS",
+          `The totalHits value returned from the store must be a positive integer, got ${hits}`
+          // eslint-disable-line @typescript-eslint/restrict-template-expressions
+        );
+      }
+    });
+  }
+  /**
+   * Ensures a given key is incremented only once per request.
+   *
+   * @param request {Request} - The Express request object.
+   * @param store {Store} - The store class.
+   * @param key {string} - The key used to store the client's hit count.
+   *
+   * @returns {void}
+   */
+  singleCount(request, store, key) {
+    this.wrap(() => {
+      let storeKeys = _Validations.singleCountKeys.get(request);
+      if (!storeKeys) {
+        storeKeys = /* @__PURE__ */ new Map();
+        _Validations.singleCountKeys.set(request, storeKeys);
+      }
+      const storeKey = store.localKeys ? store : store.constructor.name;
+      let keys = storeKeys.get(storeKey);
+      if (!keys) {
+        keys = [];
+        storeKeys.set(storeKey, keys);
+      }
+      if (keys.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_DOUBLE_COUNT",
+          `The hit count for ${key} was incremented more than once for a single request.`
+        );
+      }
+      keys.push(key);
+    });
+  }
+  /**
+   * Warns the user that the behaviour for `max: 0` is changing in the next
+   * major release.
+   *
+   * @param max {number} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  max(max) {
+    this.wrap(() => {
+      if (max === 0) {
+        throw new ChangeWarning(
+          "WRN_ERL_MAX_ZERO",
+          `Setting max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `draft_polli_ratelimit_headers` option is deprecated
+   * and will be removed in the next major release.
+   *
+   * @param draft_polli_ratelimit_headers {boolean|undefined} - The now-deprecated setting that was used to enable standard headers.
+   *
+   * @returns {void}
+   */
+  draftPolliHeaders(draft_polli_ratelimit_headers) {
+    this.wrap(() => {
+      if (draft_polli_ratelimit_headers) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_DRAFT_POLLI_HEADERS",
+          `The draft_polli_ratelimit_headers configuration option is deprecated and will be removed in express-rate-limit v7, please set standardHeaders: 'draft-6' instead.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
+   * major release.
+   *
+   * @param onLimitReached {function|undefined} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  onLimitReached(onLimitReached) {
+    this.wrap(() => {
+      if (onLimitReached) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_ON_LIMIT_REACHED",
+          `The onLimitReached configuration option is deprecated and will be removed in express-rate-limit v7.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user when the selected headers option requires a reset time but
+   * the store does not provide one.
+   *
+   * @param resetTime {Date | undefined} - The timestamp when the client's hit count will be reset.
+   *
+   * @returns {void}
+   */
+  headersResetTime(resetTime) {
+    this.wrap(() => {
+      if (!resetTime) {
+        throw new ValidationError(
+          "ERR_ERL_HEADERS_NO_RESET",
+          `standardHeaders:  'draft-7' requires a 'resetTime', but the store did not provide one. The 'windowMs' value will be used instead, which may cause clients to wait longer than necessary.`
+        );
+      }
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -136,10 +310,25 @@ var Validations = class {
     try {
       validation.call(this);
     } catch (error) {
-      console.error(error);
+      if (error instanceof ChangeWarning)
+        console.warn(error);
+      else
+        console.error(error);
     }
   }
 };
+/**
+ * Maps the key used in a store for a certain request, and ensures that the
+ * same key isn't used more than once per request.
+ *
+ * The store can be any one of the following:
+ *  - An instance, for stores like the MemoryStore where two instances do not
+ *    share state.
+ *  - A string (class name), for stores where multiple instances
+ *    typically share state, such as the Redis store.
+ */
+__publicField(_Validations, "singleCountKeys", /* @__PURE__ */ new WeakMap());
+var Validations = _Validations;
 
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
@@ -165,6 +354,11 @@ var MemoryStore = class {
      * Reference to the active timer.
      */
     __publicField(this, "interval");
+    /**
+     * Confirmation that the keys incremented in once instance of MemoryStore
+     * cannot affect other instances.
+     */
+    __publicField(this, "localKeys", true);
   }
   /**
    * Method that initializes the store.
@@ -271,6 +465,7 @@ var promisifyStore = (passedStore) => {
     async resetKey(key) {
       return legacyStore.resetKey(key);
     }
+    /* istanbul ignore next */
     async resetAll() {
       if (typeof legacyStore.resetAll === "function")
         return legacyStore.resetAll();
@@ -299,13 +494,20 @@ var parseOptions = (passedOptions) => {
   var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
   const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
+  validations.draftPolliHeaders(
+    notUndefinedOptions.draft_polli_ratelimit_headers
+  );
+  validations.onLimitReached(notUndefinedOptions.onLimitReached);
+  let standardHeaders = (_b = notUndefinedOptions.standardHeaders) != null ? _b : false;
+  if (standardHeaders === true || standardHeaders === void 0 && notUndefinedOptions.draft_polli_ratelimit_headers) {
+    standardHeaders = "draft-6";
+  }
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
-    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
+    legacyHeaders: (_c = passedOptions.headers) != null ? _c : true,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -324,13 +526,15 @@ var parseOptions = (passedOptions) => {
         response
       ) : config.message;
       if (!response.writableEnded) {
-        response.send(message != null ? message : "Too many requests, please try again later.");
+        response.send(message);
       }
     },
     onLimitReached(_request, _response, _optionsUsed) {
     },
-    // Allow the options object to be overriden by the options passed to the middleware.
+    // 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.
+    standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
     store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
@@ -366,39 +570,27 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.positiveHits(totalHits);
+      config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[config.requestPropertyName] = {
+      config.validations.max(maxHits);
+      const info = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
+      augmentedRequest[config.requestPropertyName] = info;
       if (config.legacyHeaders && !response.headersSent) {
-        response.setHeader("X-RateLimit-Limit", maxHits);
-        response.setHeader(
-          "X-RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime instanceof Date) {
-          response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
-          response.setHeader(
-            "X-RateLimit-Reset",
-            Math.ceil(resetTime.getTime() / 1e3)
-          );
-        }
+        setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        response.setHeader("RateLimit-Limit", maxHits);
-        response.setHeader(
-          "RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime) {
-          const deltaSeconds = Math.ceil(
-            (resetTime.getTime() - Date.now()) / 1e3
-          );
-          response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+        if (config.standardHeaders === "draft-6") {
+          setDraft6Headers(response, info, config.windowMs);
+        } else if (config.standardHeaders === "draft-7") {
+          config.validations.headersResetTime(info.resetTime);
+          setDraft7Headers(response, info, config.windowMs);
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {
@@ -434,8 +626,8 @@ var rateLimit = (passedOptions) => {
       }
       config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
+        if (config.legacyHeaders || config.standardHeaders) {
+          setRetryAfterHeader(response, info, config.windowMs);
         }
         config.handler(request, response, next, options);
         return;

package/dist/index.d.cts

@@ -130,7 +130,16 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -175,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
@@ -309,6 +318,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.mts

@@ -130,7 +130,16 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -175,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
@@ -309,6 +318,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.d.ts

@@ -130,7 +130,16 @@ export type Store = {
 	 * Method to shutdown the store, stop timers, and release all resources.
 	 */
 	shutdown?: () => Promise<void> | void;
+	/**
+	 * Flag to indicate that keys incremented in one instance of this store can
+	 * not affect other instances. Typically false if a database is used, true for
+	 * MemoryStore.
+	 *
+	 * Used to help detect double-counting misconfigurations.
+	 */
+	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -175,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *
@@ -309,6 +318,11 @@ export declare class MemoryStore implements Store {
 	 * Reference to the active timer.
 	 */
 	interval?: NodeJS.Timer;
+	/**
+	 * Confirmation that the keys incremented in once instance of MemoryStore
+	 * cannot affect other instances.
+	 */
+	localKeys: boolean;
 	/**
 	 * Method that initializes the store.
 	 *

package/dist/index.mjs

@@ -5,6 +5,59 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 
+// source/headers.ts
+var getResetSeconds = (resetTime, windowMs) => {
+  let resetSeconds = void 0;
+  if (resetTime) {
+    const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+    resetSeconds = Math.max(0, deltaSeconds);
+  } else if (windowMs) {
+    resetSeconds = Math.ceil(windowMs / 1e3);
+  }
+  return resetSeconds;
+};
+var setLegacyHeaders = (response, info) => {
+  if (response.headersSent)
+    return;
+  response.setHeader("X-RateLimit-Limit", info.limit);
+  response.setHeader("X-RateLimit-Remaining", info.remaining);
+  if (info.resetTime instanceof Date) {
+    response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
+    response.setHeader(
+      "X-RateLimit-Reset",
+      Math.ceil(info.resetTime.getTime() / 1e3)
+    );
+  }
+};
+var setDraft6Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader("RateLimit-Limit", info.limit);
+  response.setHeader("RateLimit-Remaining", info.remaining);
+  if (resetSeconds)
+    response.setHeader("RateLimit-Reset", resetSeconds);
+};
+var setDraft7Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader(
+    "RateLimit",
+    `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
+  );
+};
+var setRetryAfterHeader = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("Retry-After", resetSeconds);
+};
+
 // source/validations.ts
 import { isIP } from "net";
 var ValidationError = class extends Error {
@@ -12,21 +65,23 @@ var ValidationError = class extends Error {
    * The code must be a string, in snake case and all capital, that starts with
    * the substring `ERR_ERL_`.
    *
-   * The message must be a string, starting with a lowercase character,
+   * The message must be a string, starting with an uppercase character,
    * describing the issue in detail.
    */
   constructor(code, message) {
-    super(
-      `express-rate-limit: ${code} - ${message} See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#${code.toLowerCase()} for more information on this error.`
-    );
+    const url = `https://express-rate-limit.github.io/${code}/`;
+    super(`${message} See ${url} for more information.`);
     __publicField(this, "name");
     __publicField(this, "code");
+    __publicField(this, "help");
     this.name = this.constructor.name;
     this.code = code;
-    this.message = message;
+    this.help = url;
   }
 };
-var Validations = class {
+var ChangeWarning = class extends ValidationError {
+};
+var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
     __publicField(this, "enabled");
@@ -103,6 +158,125 @@ var Validations = class {
       }
     });
   }
+  /**
+   * Ensures totalHits value from store is a positive integer.
+   *
+   * @param hits {any} - The `totalHits` returned by the store.
+   */
+  positiveHits(hits) {
+    this.wrap(() => {
+      if (typeof hits !== "number" || hits < 1 || hits !== Math.round(hits)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_HITS",
+          `The totalHits value returned from the store must be a positive integer, got ${hits}`
+          // eslint-disable-line @typescript-eslint/restrict-template-expressions
+        );
+      }
+    });
+  }
+  /**
+   * Ensures a given key is incremented only once per request.
+   *
+   * @param request {Request} - The Express request object.
+   * @param store {Store} - The store class.
+   * @param key {string} - The key used to store the client's hit count.
+   *
+   * @returns {void}
+   */
+  singleCount(request, store, key) {
+    this.wrap(() => {
+      let storeKeys = _Validations.singleCountKeys.get(request);
+      if (!storeKeys) {
+        storeKeys = /* @__PURE__ */ new Map();
+        _Validations.singleCountKeys.set(request, storeKeys);
+      }
+      const storeKey = store.localKeys ? store : store.constructor.name;
+      let keys = storeKeys.get(storeKey);
+      if (!keys) {
+        keys = [];
+        storeKeys.set(storeKey, keys);
+      }
+      if (keys.includes(key)) {
+        throw new ValidationError(
+          "ERR_ERL_DOUBLE_COUNT",
+          `The hit count for ${key} was incremented more than once for a single request.`
+        );
+      }
+      keys.push(key);
+    });
+  }
+  /**
+   * Warns the user that the behaviour for `max: 0` is changing in the next
+   * major release.
+   *
+   * @param max {number} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  max(max) {
+    this.wrap(() => {
+      if (max === 0) {
+        throw new ChangeWarning(
+          "WRN_ERL_MAX_ZERO",
+          `Setting max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `draft_polli_ratelimit_headers` option is deprecated
+   * and will be removed in the next major release.
+   *
+   * @param draft_polli_ratelimit_headers {boolean|undefined} - The now-deprecated setting that was used to enable standard headers.
+   *
+   * @returns {void}
+   */
+  draftPolliHeaders(draft_polli_ratelimit_headers) {
+    this.wrap(() => {
+      if (draft_polli_ratelimit_headers) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_DRAFT_POLLI_HEADERS",
+          `The draft_polli_ratelimit_headers configuration option is deprecated and will be removed in express-rate-limit v7, please set standardHeaders: 'draft-6' instead.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
+   * major release.
+   *
+   * @param onLimitReached {function|undefined} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  onLimitReached(onLimitReached) {
+    this.wrap(() => {
+      if (onLimitReached) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_ON_LIMIT_REACHED",
+          `The onLimitReached configuration option is deprecated and will be removed in express-rate-limit v7.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user when the selected headers option requires a reset time but
+   * the store does not provide one.
+   *
+   * @param resetTime {Date | undefined} - The timestamp when the client's hit count will be reset.
+   *
+   * @returns {void}
+   */
+  headersResetTime(resetTime) {
+    this.wrap(() => {
+      if (!resetTime) {
+        throw new ValidationError(
+          "ERR_ERL_HEADERS_NO_RESET",
+          `standardHeaders:  'draft-7' requires a 'resetTime', but the store did not provide one. The 'windowMs' value will be used instead, which may cause clients to wait longer than necessary.`
+        );
+      }
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -110,10 +284,25 @@ var Validations = class {
     try {
       validation.call(this);
     } catch (error) {
-      console.error(error);
+      if (error instanceof ChangeWarning)
+        console.warn(error);
+      else
+        console.error(error);
     }
   }
 };
+/**
+ * Maps the key used in a store for a certain request, and ensures that the
+ * same key isn't used more than once per request.
+ *
+ * The store can be any one of the following:
+ *  - An instance, for stores like the MemoryStore where two instances do not
+ *    share state.
+ *  - A string (class name), for stores where multiple instances
+ *    typically share state, such as the Redis store.
+ */
+__publicField(_Validations, "singleCountKeys", /* @__PURE__ */ new WeakMap());
+var Validations = _Validations;
 
 // source/memory-store.ts
 var calculateNextResetTime = (windowMs) => {
@@ -139,6 +328,11 @@ var MemoryStore = class {
      * Reference to the active timer.
      */
     __publicField(this, "interval");
+    /**
+     * Confirmation that the keys incremented in once instance of MemoryStore
+     * cannot affect other instances.
+     */
+    __publicField(this, "localKeys", true);
   }
   /**
    * Method that initializes the store.
@@ -245,6 +439,7 @@ var promisifyStore = (passedStore) => {
     async resetKey(key) {
       return legacyStore.resetKey(key);
     }
+    /* istanbul ignore next */
     async resetAll() {
       if (typeof legacyStore.resetAll === "function")
         return legacyStore.resetAll();
@@ -273,13 +468,20 @@ var parseOptions = (passedOptions) => {
   var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
   const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
+  validations.draftPolliHeaders(
+    notUndefinedOptions.draft_polli_ratelimit_headers
+  );
+  validations.onLimitReached(notUndefinedOptions.onLimitReached);
+  let standardHeaders = (_b = notUndefinedOptions.standardHeaders) != null ? _b : false;
+  if (standardHeaders === true || standardHeaders === void 0 && notUndefinedOptions.draft_polli_ratelimit_headers) {
+    standardHeaders = "draft-6";
+  }
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
-    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
+    legacyHeaders: (_c = passedOptions.headers) != null ? _c : true,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -298,13 +500,15 @@ var parseOptions = (passedOptions) => {
         response
       ) : config.message;
       if (!response.writableEnded) {
-        response.send(message != null ? message : "Too many requests, please try again later.");
+        response.send(message);
       }
     },
     onLimitReached(_request, _response, _optionsUsed) {
     },
-    // Allow the options object to be overriden by the options passed to the middleware.
+    // 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.
+    standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
     store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
@@ -340,39 +544,27 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.positiveHits(totalHits);
+      config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[config.requestPropertyName] = {
+      config.validations.max(maxHits);
+      const info = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
+      augmentedRequest[config.requestPropertyName] = info;
       if (config.legacyHeaders && !response.headersSent) {
-        response.setHeader("X-RateLimit-Limit", maxHits);
-        response.setHeader(
-          "X-RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime instanceof Date) {
-          response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
-          response.setHeader(
-            "X-RateLimit-Reset",
-            Math.ceil(resetTime.getTime() / 1e3)
-          );
-        }
+        setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        response.setHeader("RateLimit-Limit", maxHits);
-        response.setHeader(
-          "RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime) {
-          const deltaSeconds = Math.ceil(
-            (resetTime.getTime() - Date.now()) / 1e3
-          );
-          response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+        if (config.standardHeaders === "draft-6") {
+          setDraft6Headers(response, info, config.windowMs);
+        } else if (config.standardHeaders === "draft-7") {
+          config.validations.headersResetTime(info.resetTime);
+          setDraft7Headers(response, info, config.windowMs);
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {
@@ -408,8 +600,8 @@ var rateLimit = (passedOptions) => {
       }
       config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
+        if (config.legacyHeaders || config.standardHeaders) {
+          setRetryAfterHeader(response, info, config.windowMs);
         }
         config.handler(request, response, next, options);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.8.1",
+	"version": "6.10.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",
@@ -52,7 +52,7 @@
 		"changelog.md"
 	],
 	"engines": {
-		"node": ">= 14.0.0"
+		"node": ">= 14"
 	},
 	"scripts": {
 		"clean": "del-cli dist/ coverage/ *.log *.tmp *.bak *.tgz",
@@ -63,12 +63,12 @@
 		"lint:code": "xo --ignore test/external/",
 		"lint:rest": "prettier --ignore-path .gitignore --ignore-unknown --check .",
 		"lint": "run-s lint:*",
-		"autofix:code": "npm run lint:code -- --fix",
-		"autofix:rest": "npm run lint:rest -- --write .",
-		"autofix": "run-s autofix:*",
-		"test:lib": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules jest",
+		"format:code": "npm run lint:code -- --fix",
+		"format:rest": "npm run lint:rest -- --write .",
+		"format": "run-s format:*",
+		"test:lib": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules jest --config config/jest.json",
 		"test:ext": "cd test/external/ && bash run-all-tests",
-		"test": "run-s lint test:*",
+		"test": "run-s lint test:lib",
 		"pre-commit": "lint-staged",
 		"prepare": "run-s compile && husky install config/husky"
 	},
@@ -76,9 +76,11 @@
 		"express": "^4 || ^5"
 	},
 	"devDependencies": {
-		"@jest/globals": "29.6.1",
+		"@express-rate-limit/prettier": "1.0.0",
+		"@express-rate-limit/tsconfig": "1.0.0",
+		"@jest/globals": "29.6.2",
 		"@types/express": "4.17.17",
-		"@types/jest": "29.5.2",
+		"@types/jest": "29.5.3",
 		"@types/node": "20.4.0",
 		"@types/supertest": "2.0.12",
 		"cross-env": "7.0.3",
@@ -87,9 +89,10 @@
 		"esbuild": "0.18.11",
 		"express": "4.18.2",
 		"husky": "8.0.3",
-		"jest": "29.6.1",
+		"jest": "29.6.2",
 		"lint-staged": "13.2.3",
 		"npm-run-all": "4.1.5",
+		"ratelimit-header-parser": "0.1.0",
 		"supertest": "6.3.3",
 		"ts-jest": "29.1.1",
 		"ts-node": "10.9.1",
@@ -112,40 +115,13 @@
 			{
 				"files": "test/library/*.ts",
 				"rules": {
-					"@typescript-eslint/no-unsafe-argument": 0
+					"@typescript-eslint/no-unsafe-argument": 0,
+					"@typescript-eslint/no-unsafe-assignment": 0
 				}
 			}
 		]
 	},
-	"prettier": {
-		"semi": false,
-		"useTabs": true,
-		"singleQuote": true,
-		"bracketSpacing": true,
-		"trailingComma": "all",
-		"proseWrap": "always"
-	},
-	"jest": {
-		"preset": "ts-jest/presets/default-esm",
-		"collectCoverage": true,
-		"collectCoverageFrom": [
-			"source/**/*.ts"
-		],
-		"testTimeout": 30000,
-		"testMatch": [
-			"**/test/library/**/*-test.[jt]s?(x)"
-		],
-		"moduleFileExtensions": [
-			"js",
-			"jsx",
-			"json",
-			"ts",
-			"tsx"
-		],
-		"moduleNameMapper": {
-			"^(\\.{1,2}/.*)\\.js$": "$1"
-		}
-	},
+	"prettier": "@express-rate-limit/prettier",
 	"lint-staged": {
 		"{source,test}/**/*.ts": "xo --ignore test/external/ --fix",
 		"**/*.{json,yaml,md}": "prettier --ignore-path .gitignore --ignore-unknown --write "

package/readme.md

@@ -12,21 +12,46 @@ authentication and more to any API in minutes. Learn more at
 
 <div align="center">
 
-[![Tests](https://github.com/express-rate-limit/express-rate-limit/workflows/Test/badge.svg)](https://github.com/express-rate-limit/express-rate-limit/actions)
+[![tests](https://github.com/express-rate-limit/express-rate-limit/actions/workflows/ci.yaml/badge.svg)](https://github.com/express-rate-limit/express-rate-limit/actions/workflows/ci.yaml)
 [![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)
 
-Basic rate-limiting middleware for Express. Use to limit repeated requests to
-public APIs and/or endpoints such as password reset. Plays nice with
+Basic rate-limiting middleware for [Express](http://expressjs.com/). Use to
+limit repeated requests to public APIs and/or endpoints such as password reset.
+Plays nice with
 [express-slow-down](https://www.npmjs.com/package/express-slow-down).
 
 </div>
 
-### Alternate Rate Limiters
+## Use Cases
+
+Depending on your use case, you may need to switch to a different
+[store](#store).
+
+#### Abuse Prevention
+
+The default `MemoryStore` is probably fine.
+
+#### API Rate Limit Enforcement
+
+You likely want to switch to a different [store](#store). As a performance
+optimization, the default `MemoryStore` uses a global time window, so if your
+limit is 10 requests per minute, a single user might be able to get an initial
+burst of up to 20 requests in a row if they happen to get the first 10 in at the
+end of one minute and the next 10 in at the start of the next minute. (After the
+initial burst, they will be limited to the expected 10 requests per minute.) All
+other stores use per-user time windows, so a user will get exactly 10 requests
+regardless.
 
-> 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. See the
-> [`stores` section](#store) below for a list of external stores.
+Additionally, if you have multiple servers or processes (for example, with the
+[node:cluster](https://nodejs.org/api/cluster.html) module), you'll likely want
+to use an external data store to syhcnronize hits
+([redis](https://npmjs.com/package/rate-limit-redis),
+[memcached](https://npmjs.org/package/rate-limit-memcached), [etc.](#store))
+This will guarentee the expected result even if some requests get handled by
+different servers/processes.
+
+### 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
@@ -72,13 +97,13 @@ Import it in a CommonJS project (`type: commonjs` or no `type` field in
 `package.json`) as follows:
 
 ```ts
-const rateLimit = require('express-rate-limit')
+const { rateLimit } = require('express-rate-limit')
 ```
 
 Import it in a ESM project (`type: module` in `package.json`) as follows:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 ```
 
 ### Examples
@@ -87,13 +112,14 @@ To use it in an API-only server where the rate-limiter should be applied to all
 requests:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const limiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 // Apply the rate limiting middleware to all requests
@@ -105,13 +131,14 @@ To use it in a 'regular' web server (e.g. anything that uses
 requests:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const apiLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
+	standardHeaders: 'draft-7', // Set `RateLimit` and `RateLimit-Policy`` headers
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 // Apply the rate limiting middleware to API calls only
@@ -121,13 +148,14 @@ app.use('/api', apiLimiter)
 To create multiple instances to apply different rules to different endpoints:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const apiLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
+	// store: ... , // Use an external store for more precise rate limiting
 })
 
 app.use('/api/', apiLimiter)
@@ -137,8 +165,8 @@ const createAccountLimiter = rateLimit({
 	max: 5, // Limit each IP to 5 create account requests per `window` (here, per hour)
 	message:
 		'Too many accounts created from this IP, please try again after an hour',
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
 })
 
 app.post('/create-account', createAccountLimiter, (request, response) => {
@@ -149,17 +177,23 @@ app.post('/create-account', createAccountLimiter, (request, response) => {
 To use a custom store:
 
 ```ts
-import rateLimit, { MemoryStore } from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
+import RedisStore from 'rate-limit-redis'
+import RedisClient from 'ioredis'
 
-const apiLimiter = rateLimit({
+const redisClient = new RedisClient()
+const rateLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	store: new MemoryStore(),
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
+	store: new RedisStore({
+		/* ... */
+	}), // Use the external store
 })
 
-// Apply the rate limiting middleware to API calls only
-app.use('/api', apiLimiter)
+// Apply the rate limiting middleware to all requests
+app.use(rateLimiter)
 ```
 
 > **Note:** most stores will require additional configuration, such as custom
@@ -296,16 +330,38 @@ Defaults to `true` (for backward compatibility).
 
 ### `standardHeaders`
 
-> `boolean`
+> `boolean` | `'draft-6'` | `'draft-7'`
 
 Whether to enable support for headers conforming to the
-[ratelimit standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers/blob/main/draft-ietf-httpapi-ratelimit-headers.md)
-adopted by the IETF (`RateLimit-Limit`, `RateLimit-Remaining`, and, if the store
-supports it, `RateLimit-Reset`). If set to `true`, the middleware also sends the
-`Retry-After` header on all blocked requests. May be used in conjunction with,
-or instead of the `legacyHeaders` option.
+[RateLimit header fields for HTTP standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers)
+adopted by the IETF.
+
+If set to `draft-6`, separate `RateLimit-Policy` `RateLimit-Limit`,
+`RateLimit-Remaining`, and, if the store supports it, `RateLimit-Reset` headers
+are set on the response, in accordance with
+[draft-ietf-httpapi-ratelimit-headers-06](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-06).
+
+If set to `draft-7`, a combined `RateLimit` header is set containing limit,
+remaining, and reset values, and a `RateLimit-Policy` header is set, in
+accordiance with
+[draft-ietf-httpapi-ratelimit-headers-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-07).
+`windowMs` is used for the reset value if the store does not provide a reset
+time.
 
-Defaults to `false` (for backward compatibility, but its use is recommended).
+If set to `true`, it is treated as `draft-6`, however this behavior may change
+in a future semver major release.
+
+If set to any truthy value, the middleware also sends the `Retry-After` header
+on all blocked requests.
+
+The `standardHeaders` option may be used in conjunction with, or instead of the
+`legacyHeaders` option.
+
+ℹ️ Tip: use
+[ratelimit-header-parser](https://www.npmjs.com/package/ratelimit-header-parser)
+in clients to read/parse any form of express-rate-limit's headers.
+
+Defaults to `false`.
 
 > Renamed in `6.x` from `draft_polli_ratelimit_headers` to `standardHeaders`.
 
@@ -397,8 +453,8 @@ const limiter = rateLimit({
 > `function`
 
 A (sync/async) function that accepts the Express `request` and `response`
-objects that is called when a client has reached their rate limit, and will be
-rate limited on their next request.
+objects that is called the on the request where a client has just exceeded their
+rate limit.
 
 This method was
 [deprecated in v6](https://github.com/express-rate-limit/express-rate-limit/releases/v6.0.0) -
@@ -482,7 +538,7 @@ Here is a list of external stores:
 | [`rate-limit-redis`](https://npmjs.com/package/rate-limit-redis)                       | A [Redis](http://redis.io/)-backed store, more suitable for large or demanding deployments.           | Modern as of v3.0.0 |
 | [`rate-limit-memcached`](https://npmjs.org/package/rate-limit-memcached)               | A [Memcached](https://memcached.org/)-backed store.                                                   | Legacy              |
 | [`rate-limit-mongo`](https://www.npmjs.com/package/rate-limit-mongo)                   | A [MongoDB](https://www.mongodb.com/)-backed store.                                                   | Legacy              |
-| [`precise-memory-rate-limit`](https://www.npmjs.com/package/precise-memory-rate-limit) | A memory store similar to the built-in one, except that it stores a distinct timestamp for each key.  | Legacy              |
+| [`precise-memory-rate-limit`](https://www.npmjs.com/package/precise-memory-rate-limit) | A memory store similar to the built-in one, except that it stores a distinct timestamp for each key.  | Modern as of v2.0.0 |
 
 Take a look at
 [this guide](https://github.com/express-rate-limit/express-rate-limit/wiki/Creating-Your-Own-Store)

package/tsconfig.json

@@ -1,13 +1,5 @@
 {
 	"include": ["source/"],
 	"exclude": ["node_modules/"],
-	"compilerOptions": {
-		"declaration": true,
-		"strict": true,
-		"noUnusedLocals": true,
-		"noImplicitReturns": true,
-		"noFallthroughCasesInSwitch": true,
-		"esModuleInterop": true,
-		"moduleResolution": "node"
-	}
+	"extends": "@express-rate-limit/tsconfig"
 }