express-rate-limit 5.5.1 → 6.0.3

package/changelog.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.0.2](https://github.com/nfriedly/express-rate-limit/releases/v6.0.2)
+
+### Fixed
+
+- Ensure CommonJS projects can import the module.
+
+### Added
+
+- Add additional tests that test:
+  - importing the library in `js-cjs`, `js-esm`, `ts-cjs`, `ts-esm`
+    environments.
+  - usage of the library with external stores (`redis`, `mongo`, `memcached`,
+    `precise`).
+
+### Changed
+
+- Use [`esbuild`](https://esbuild.github.io/) to generate ESM and CJS output.
+  This reduces the size of the built package from 138 kb to 13kb and build time
+  to 4 ms! :rocket:
+- Use [`dts-bundle-generator`](https://github.com/timocov/dts-bundle-generator)
+  to generate a single Typescript declaration file.
+
+## [6.0.1](https://github.com/nfriedly/express-rate-limit/releases/v6.0.1)
+
+### Fixed
+
+- Ensure CommonJS projects can import the module.
+
+## [6.0.0](https://github.com/nfriedly/express-rate-limit/releases/v6.0.0)
+
+### Added
+
+- `express` 4.x as a peer dependency.
+- Better Typescript support (the library was rewritten in Typescript).
+- Export the package as both ESM and CJS.
+- Publish the built package (`.tgz` file) on GitHub releases as well as the npm
+  registry.
+- Issue and PR templates.
+- A contributing guide.
+
+### Changed
+
+- Rename the `draft_polli_ratelimit_headers` option to `standardHeaders`.
+- Rename the `headers` option to `legacyHeaders`.
+- `Retry-After` header is now sent if either `legacyHeaders` or
+  `standardHeaders` is set.
+- Allow `keyGenerator` to be an async function/return a promise.
+- Change the way custom stores are defined.
+  - Add the `init` method for stores to set themselves up using options passed
+    to the middleware.
+  - Rename the `incr` method to `increment`.
+  - Allow the `increment`, `decrement`, `resetKey` and `resetAll` methods to
+    return a promise.
+  - Old stores will automatically be promisified and used.
+- The package can now only be used with NodeJS version 12.9.0 or greater.
+- The `onLimitReached` configuration option is now deprecated. Replace it with a
+  custom `handler` that checks the number of hits.
+
+### Removed
+
+- Remove the deprecated `limiter.resetIp` method (use the `limiter.resetKey`
+  method instead).
+- Remove the deprecated options `delayMs`, `delayAfter` (the delay functionality
+  was moved to the
+  [`express-slow-down`](https://github.com/nfriedly/express-slow-down) package)
+  and `global` (use a key generator that returns a constant value).
+
+## [5.x](https://github.com/nfriedly/express-rate-limit/releases/tag/v5.5.1)
+
+### Added
+
+- The middleware ~throws~ logs an error if `request.ip` is undefined.
+
+### Removed
+
+- Removes typescript typings. (See
+  [#138](https://github.com/nfriedly/express-rate-limit/issues/138))
+
+## [4.x](https://github.com/nfriedly/express-rate-limit/releases/tag/v4.0.4)
+
+### Changed
+
+- The library no longer modifies the passed-in options object, it instead makes
+  a clone of it.
+
+## [3.x](https://github.com/nfriedly/express-rate-limit/releases/tag/v3.5.2)
+
+### Added
+
+- Simplifies the default `handler` function so that it no longer changes the
+  response format. The default handler also uses
+  [response.send](https://expressjs.com/en/4x/api.html#response.send).
+
+### Changes
+
+- `onLimitReached` now only triggers once for a client and window. However, the
+  `handle` method is called for every blocked request.
+
+### Removed
+
+- The `delayAfter` and `delayMs` options; they were moved to the
+  [express-slow-down](https://npmjs.org/package/express-slow-down) package.
+
+## [2.x](https://github.com/nfriedly/express-rate-limit/releases/tag/v2.14.2)
+
+### Added
+
+- A `limiter.resetKey()` method to reset the hit counter for a particular client
+
+### Changes
+
+- The rate limiter now uses a less precise but less resource intensive method of
+  tracking hits from a client.
+
+### Removed
+
+- The `global` option.

package/dist/index.cjs

@@ -0,0 +1,226 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __markAsModule = (target) => __defProp(target, "__esModule", { value: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __reExport = (target, module2, copyDefault, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && (copyDefault || key !== "default"))
+        __defProp(target, key, { get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable });
+  }
+  return target;
+};
+var __toCommonJS = /* @__PURE__ */ ((cache) => {
+  return (module2, temp) => {
+    return cache && cache.get(module2) || (temp = __reExport(__markAsModule({}), module2, 1), cache && cache.set(module2, temp), temp);
+  };
+})(typeof WeakMap !== "undefined" ? /* @__PURE__ */ new WeakMap() : 0);
+
+// source/index.ts
+var source_exports = {};
+__export(source_exports, {
+  default: () => source_default
+});
+
+// source/memory-store.ts
+var calculateNextResetTime = (windowMs) => {
+  const resetTime = new Date();
+  resetTime.setMilliseconds(resetTime.getMilliseconds() + windowMs);
+  return resetTime;
+};
+var MemoryStore = class {
+  init(options) {
+    this.windowMs = options.windowMs;
+    this.resetTime = calculateNextResetTime(this.windowMs);
+    this.hits = {};
+    const interval = setInterval(async () => {
+      await this.resetAll();
+    }, this.windowMs);
+    if (interval.unref) {
+      interval.unref();
+    }
+  }
+  async increment(key) {
+    const totalHits = (this.hits[key] ?? 0) + 1;
+    this.hits[key] = totalHits;
+    return {
+      totalHits,
+      resetTime: this.resetTime
+    };
+  }
+  async decrement(key) {
+    const current = this.hits[key];
+    if (current) {
+      this.hits[key] = current - 1;
+    }
+  }
+  async resetKey(key) {
+    delete this.hits[key];
+  }
+  async resetAll() {
+    this.hits = {};
+    this.resetTime = calculateNextResetTime(this.windowMs);
+  }
+};
+
+// source/lib.ts
+var isLegacyStore = (store) => typeof store.incr === "function" && typeof store.increment !== "function";
+var promisifyStore = (passedStore) => {
+  if (!isLegacyStore(passedStore)) {
+    return passedStore;
+  }
+  const legacyStore = passedStore;
+  class PromisifiedStore {
+    async increment(key) {
+      return new Promise((resolve, reject) => {
+        legacyStore.incr(key, (error, totalHits, resetTime) => {
+          if (error)
+            reject(error);
+          resolve({ totalHits, resetTime });
+        });
+      });
+    }
+    async decrement(key) {
+      return Promise.resolve(legacyStore.decrement(key));
+    }
+    async resetKey(key) {
+      return Promise.resolve(legacyStore.resetKey(key));
+    }
+    async resetAll() {
+      if (typeof legacyStore.resetAll === "function")
+        return Promise.resolve(legacyStore.resetAll());
+    }
+  }
+  return new PromisifiedStore();
+};
+var parseOptions = (passedOptions) => {
+  const options = {
+    windowMs: 60 * 1e3,
+    store: new MemoryStore(),
+    max: 5,
+    message: "Too many requests, please try again later.",
+    statusCode: 429,
+    legacyHeaders: passedOptions.headers ?? true,
+    standardHeaders: passedOptions.draft_polli_ratelimit_headers ?? false,
+    requestPropertyName: "rateLimit",
+    skipFailedRequests: false,
+    skipSuccessfulRequests: false,
+    requestWasSuccessful: (_request, response) => response.statusCode < 400,
+    skip: (_request, _response) => false,
+    keyGenerator: (request, _response) => {
+      if (!request.ip) {
+        console.error("WARN | `express-rate-limit` | `request.ip` is undefined. You can avoid this by providing a custom `keyGenerator` function, but it may be indicative of a larger issue.");
+      }
+      return request.ip;
+    },
+    handler: (_request, response, _next, _optionsUsed) => {
+      response.status(options.statusCode).send(options.message);
+    },
+    onLimitReached: (_request, _response, _optionsUsed) => {
+    },
+    ...passedOptions
+  };
+  if (typeof options.store.incr !== "function" && typeof options.store.increment !== "function" || typeof options.store.decrement !== "function" || typeof options.store.resetKey !== "function" || typeof options.store.resetAll !== "undefined" && typeof options.store.resetAll !== "function" || typeof options.store.init !== "undefined" && typeof options.store.init !== "function") {
+    throw new TypeError("An invalid store was passed. Please ensure that the store is a class that implements the `Store` interface.");
+  }
+  options.store = promisifyStore(options.store);
+  return options;
+};
+var handleAsyncErrors = (fn) => async (request, response, next) => {
+  try {
+    await Promise.resolve(fn(request, response, next)).catch(next);
+  } catch (error) {
+    next(error);
+  }
+};
+var rateLimit = (passedOptions) => {
+  const options = parseOptions(passedOptions ?? {});
+  if (typeof options.store.init === "function")
+    options.store.init(options);
+  const middleware = handleAsyncErrors(async (request, response, next) => {
+    const skip = await options.skip(request, response);
+    if (skip) {
+      next();
+      return;
+    }
+    const augmentedRequest = request;
+    const key = await options.keyGenerator(request, response);
+    const { totalHits, resetTime } = await options.store.increment(key);
+    const retrieveQuota = typeof options.max === "function" ? options.max(request, response) : options.max;
+    const maxHits = await retrieveQuota;
+    augmentedRequest[options.requestPropertyName] = {
+      limit: maxHits,
+      current: totalHits,
+      remaining: Math.max(maxHits - totalHits, 0),
+      resetTime
+    };
+    if (options.legacyHeaders && !response.headersSent) {
+      response.setHeader("X-RateLimit-Limit", maxHits);
+      response.setHeader("X-RateLimit-Remaining", augmentedRequest[options.requestPropertyName].remaining);
+      if (resetTime instanceof Date) {
+        response.setHeader("Date", new Date().toUTCString());
+        response.setHeader("X-RateLimit-Reset", Math.ceil(resetTime.getTime() / 1e3));
+      }
+    }
+    if (options.standardHeaders && !response.headersSent) {
+      response.setHeader("RateLimit-Limit", maxHits);
+      response.setHeader("RateLimit-Remaining", augmentedRequest[options.requestPropertyName].remaining);
+      if (resetTime) {
+        const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+        response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+      }
+    }
+    if (options.skipFailedRequests || options.skipSuccessfulRequests) {
+      let decremented = false;
+      const decrementKey = async () => {
+        if (!decremented) {
+          await options.store.decrement(key);
+          decremented = true;
+        }
+      };
+      if (options.skipFailedRequests) {
+        response.on("finish", async () => {
+          if (!options.requestWasSuccessful(request, response))
+            await decrementKey();
+        });
+        response.on("close", async () => {
+          if (!response.writableEnded)
+            await decrementKey();
+        });
+        response.on("error", async () => {
+          await decrementKey();
+        });
+      }
+      if (options.skipSuccessfulRequests) {
+        response.on("finish", async () => {
+          if (options.requestWasSuccessful(request, response))
+            await decrementKey();
+        });
+      }
+    }
+    if (maxHits && totalHits === maxHits + 1) {
+      options.onLimitReached(request, response, options);
+    }
+    if (maxHits && totalHits > maxHits) {
+      if ((options.legacyHeaders || options.standardHeaders) && !response.headersSent) {
+        response.setHeader("Retry-After", Math.ceil(options.windowMs / 1e3));
+      }
+      options.handler(request, response, next, options);
+      return;
+    }
+    next();
+  });
+  middleware.resetKey = options.store.resetKey.bind(options.store);
+  return middleware;
+};
+var lib_default = rateLimit;
+
+// source/index.ts
+var source_default = lib_default;
+module.exports = __toCommonJS(source_exports);
+module.exports = rateLimit;

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+// Generated by dts-bundle-generator v6.2.0
+
+import Express from 'express';
+
+/**
+ * Callback that fires when a client's hit counter is incremented.
+ *
+ * @param error {Error | undefined} - The error that occurred, if any
+ * @param totalHits {number} - The number of hits for that client so far
+ * @param resetTime {Date | undefined} - The time when the counter resets
+ */
+export declare type IncrementCallback = (error: Error | undefined, totalHits: number, resetTime: Date | undefined) => void;
+/**
+ * Method (in the form of middleware) to generate/retrieve a value based on the
+ * incoming request
+ *
+ * @param request {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ *
+ * @returns {T} - The value needed
+ */
+export declare type ValueDeterminingMiddleware<T> = (request: Express.Request, response: Express.Response) => T | Promise<T>;
+/**
+ * Express request handler that sends back a response when a client is
+ * rate-limited.
+ *
+ * @param request {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ * @param next {Express.NextFunction} - The Express `next` function, can be called to skip responding
+ * @param optionsUsed {Options} - The options used to set up the middleware
+ */
+export declare type RateLimitExceededEventHandler = (request: Express.Request, response: Express.Response, next: Express.NextFunction, optionsUsed: Options) => void;
+/**
+ * Event callback that is triggered on a client's first request that exceeds the limit
+ * but not for subsequent requests. May be used for logging, etc. Should *not*
+ * send a response.
+ *
+ * @param request {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ * @param optionsUsed {Options} - The options used to set up the middleware
+ */
+export declare type RateLimitReachedEventHandler = (request: Express.Request, response: Express.Response, optionsUsed: Options) => void;
+/**
+ * Data returned from the `Store` when a client's hit counter is incremented.
+ *
+ * @property totalHits {number} - The number of hits for that client so far
+ * @property resetTime {Date | undefined} - The time when the counter resets
+ */
+export declare type IncrementResponse = {
+	totalHits: number;
+	resetTime: Date | undefined;
+};
+/**
+ * A modified Express request handler with the rate limit functions.
+ */
+export declare type RateLimitRequestHandler = Express.RequestHandler & {
+	/**
+	 * Method to reset a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	resetKey: (key: string) => void;
+};
+/**
+ * An interface that all hit counter stores must implement.
+ *
+ * @deprecated 6.x - Implement the `Store` interface instead.
+ */
+export interface LegacyStore {
+	/**
+	 * Method to increment a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 * @param callback {IncrementCallback} - The callback to call once the counter is incremented
+	 */
+	incr: (key: string, callback: IncrementCallback) => void;
+	/**
+	 * Method to decrement a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	decrement: (key: string) => void;
+	/**
+	 * Method to reset a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	resetKey: (key: string) => void;
+	/**
+	 * Method to reset everyone's hit counter.
+	 */
+	resetAll?: () => void;
+}
+/**
+ * An interface that all hit counter stores must implement.
+ */
+export interface Store {
+	/**
+	 * Method that initializes the store, and has access to the options passed to
+	 * the middleware too.
+	 *
+	 * @param options {Options} - The options used to setup the middleware
+	 */
+	init?: (options: Options) => void;
+	/**
+	 * Method to increment a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 *
+	 * @returns {IncrementResponse} - The number of hits and reset time for that client
+	 */
+	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+	/**
+	 * Method to decrement a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	decrement: (key: string) => Promise<void> | void;
+	/**
+	 * Method to reset a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	resetKey: (key: string) => Promise<void> | void;
+	/**
+	 * Method to reset everyone's hit counter.
+	 */
+	resetAll?: () => Promise<void> | void;
+}
+/**
+ * The configuration options for the rate limiter.
+ */
+export interface Options {
+	/**
+	 * How long we should remember the requests.
+	 */
+	readonly windowMs: number;
+	/**
+	 * The maximum number of connection to allow during the `window` before
+	 * rate limiting the client.
+	 *
+	 * Can be the limit itself as a number or express middleware that parses
+	 * the request and then figures out the limit.
+	 */
+	readonly max: number | ValueDeterminingMiddleware<number>;
+	/**
+	 * The response body to send back when a client is rate limited.
+	 */
+	readonly message: any;
+	/**
+	 * The HTTP status code to send back when a client is rate limited.
+	 *
+	 * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
+	 */
+	readonly statusCode: number;
+	/**
+	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 */
+	readonly legacyHeaders: boolean;
+	/**
+	 * Whether to enable support for the rate limit standardization headers (`RateLimit-*`).
+	 */
+	readonly standardHeaders: boolean;
+	/**
+	 * The name of the property on the request object to store the rate limit info.
+	 *
+	 * Defaults to `rateLimit`.
+	 */
+	readonly requestPropertyName: string;
+	/**
+	 * If `true`, the library will (by default) skip all requests that have a 4XX
+	 * or 5XX status.
+	 */
+	readonly skipFailedRequests: boolean;
+	/**
+	 * If `true`, the library will (by default) skip all requests that have a
+	 * status code less than 400.
+	 */
+	readonly skipSuccessfulRequests: boolean;
+	/**
+	 * Method to determine whether or not the request counts as 'succesful'. Used
+	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
+	 */
+	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
+	/**
+	 * Method to generate custom identifiers for clients.
+	 *
+	 * By default, the client's IP address is used.
+	 */
+	readonly keyGenerator: ValueDeterminingMiddleware<string>;
+	/**
+	 * Method (in the form of middleware) to determine whether or not this request
+	 * counts towards a client's quota.
+	 */
+	readonly skip: ValueDeterminingMiddleware<boolean>;
+	/**
+	 * Express request handler that sends back a response when a client is
+	 * rate-limited.
+	 */
+	readonly handler: RateLimitExceededEventHandler;
+	/**
+	 * Express request handler that sends back a response when a client has
+	 * reached their rate limit, and will be rate limited on their next request.
+	 */
+	readonly onLimitReached: RateLimitReachedEventHandler;
+	/**
+	 * The {@link Store} to use to store the hit count for each client.
+	 */
+	store: Store;
+	/**
+	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 *
+	 * @deprecated 6.x - This option was renamed to `legacyHeaders`.
+	 */
+	headers?: boolean;
+	/**
+	 * Whether to send `RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 *
+	 * @deprecated 6.x - This option was renamed to `standardHeaders`.
+	 */
+	draft_polli_ratelimit_headers?: boolean;
+}
+/**
+ * The extended request object that includes information about the client's
+ * rate limit.
+ */
+export declare type AugmentedRequest = Express.Request & {
+	[key: string]: RateLimitInfo;
+};
+/**
+ * The rate limit related information for each client included in the
+ * Express request object.
+ */
+export interface RateLimitInfo {
+	readonly limit: number;
+	readonly current: number;
+	readonly remaining: number;
+	readonly resetTime: Date | undefined;
+}
+declare const rateLimit: (passedOptions?: (Omit<Partial<Options>, "store"> & {
+	store?: LegacyStore | Store | undefined;
+}) | undefined) => RateLimitRequestHandler;
+export default rateLimit;
+
+export {};