rate-limiter-flexible 11.0.2 → 11.1.0

package/README.md

@@ -136,7 +136,7 @@ Copy/paste examples on Wiki:
 * [DynamoDb](https://github.com/animir/node-rate-limiter-flexible/wiki/DynamoDB)
 * [Etcd](https://github.com/animir/node-rate-limiter-flexible/wiki/Etcd) Atomic and non-atomic counters.
 * [Memcached](https://github.com/animir/node-rate-limiter-flexible/wiki/Memcache)
-* [Memory](https://github.com/animir/node-rate-limiter-flexible/wiki/Memory)
+* [Memory](https://github.com/animir/node-rate-limiter-flexible/wiki/Memory) Supports dump() and restore() for graceful restarts and green/blue deployment
 * [Mongo](https://github.com/animir/node-rate-limiter-flexible/wiki/Mongo) (with [sharding support](https://github.com/animir/node-rate-limiter-flexible/wiki/Mongo#mongodb-sharding-options))
 * [MySQL](https://github.com/animir/node-rate-limiter-flexible/wiki/MySQL) (support Sequelize and Knex)
 * [Postgres](https://github.com/animir/node-rate-limiter-flexible/wiki/PostgreSQL) (support Sequelize, TypeORM and Knex)

package/lib/RateLimiterMemory.js

@@ -102,6 +102,96 @@ class RateLimiterMemory extends RateLimiterAbstract {
   delete(key) {
     return Promise.resolve(this._memoryStorage.delete(this.getKey(key)));
   }
+
+  dump() {
+    const storage = [];
+    for (const [key, record] of this._memoryStorage._storage) {
+      storage.push({
+        key: this.parseKey(key),
+        value: record.value,
+        expiresAt: record.expiresAt,
+      });
+    }
+
+    return {
+      version: 1,
+      dumpedAt: Date.now(),
+      storage,
+    };
+  }
+
+  /**
+   * Restores rate-limiter state from a previously dumped snapshot.
+   *
+   * Each entry is classified into one of three buckets:
+   *  - **invalid**  – the item is not an object or has a malformed schema (bad key, value or expiry type).
+   *  - **expired**  – the item has logically expired based on current timestamp.
+   *  - **restored** – the item was valid and successfully loaded into storage.
+   *
+   * @param {Object}  data            - Snapshot produced by {@link dump}.
+   * @param {boolean} [detailResponse=false] - When `true`, each bucket also
+   *   carries a `keys` array listing every affected key.
+   * @returns {{ invalid, expired, restored } | undefined} Summary counts (and
+   *   optionally keys).  Returns `undefined` when `data` fails schema checks.
+   */
+  restore(data, detailResponse = false) {
+    if (!data || typeof data !== 'object' || data.version !== 1) {
+      return undefined;
+    }
+
+    const response = detailResponse
+      ? {
+        invalid: { count: 0, keys: [] },
+        expired: { count: 0, keys: [] },
+        restored: { count: 0, keys: [] },
+      }
+      : { invalid: 0, expired: 0, restored: 0 };
+
+    /**
+     * Increments the named bucket and, in detail mode, appends the key.
+     * @param {'invalid'|'expired'|'restored'} bucket
+     * @param {string|number} key
+     */
+    const record = (bucket, key) => {
+      if (detailResponse) {
+        response[bucket].count += 1;
+        response[bucket].keys.push(key);
+      } else {
+        response[bucket] += 1;
+      }
+    };
+
+    if (!Array.isArray(data.storage)) {
+      return response;
+    }
+
+    for (const item of data.storage) {
+      if (!item || typeof item !== 'object') {
+        //in array if we don't get object we push N/A
+        record('invalid', 'N/A');
+        continue;
+      }
+
+      const isValidKey = typeof item.key === 'string' || typeof item.key === 'number';
+      const isValidValue = Number.isFinite(item.value);
+      const isValidExpiry = item.expiresAt === null || Number.isFinite(item.expiresAt);
+
+      if (!isValidKey || !isValidValue || !isValidExpiry) {
+        record('invalid', item.key);
+        continue;
+      }
+
+      if (item.expiresAt !== null && item.expiresAt <= Date.now()) {
+        record('expired', item.key);
+        continue;
+      }
+
+      this._memoryStorage._restoreRecord(this.getKey(item.key), item.value, item.expiresAt);
+      record('restored', item.key);
+    }
+
+    return response;
+  }
 }
 
 module.exports = RateLimiterMemory;

package/lib/component/MemoryStorage/MemoryStorage.js

@@ -86,4 +86,45 @@ module.exports = class MemoryStorage {
     }
     return false;
   }
+
+  /**
+   * @internal
+   * @param key
+   * @param value
+   * @param expiresAt
+   */
+  _restoreRecord(key, value, expiresAt) {
+    const now = Date.now();
+    const hasExpiresAt = expiresAt !== null;
+
+    if (hasExpiresAt && !Number.isFinite(expiresAt)) {
+      return;
+    }
+
+    if (hasExpiresAt && expiresAt <= now) {
+      return;
+    }
+
+    const durationMs = hasExpiresAt ? expiresAt - now : 0;
+
+    const existingRecord = this._storage.get(key);
+    if (existingRecord && existingRecord.timeoutId) {
+      clearTimeout(existingRecord.timeoutId);
+    }
+
+    const record = new Record(
+      value,
+      expiresAt
+    );
+    this._storage.set(key, record);
+
+    if (durationMs > 0) {
+      record.timeoutId = setTimeout(() => {
+        this._storage.delete(key);
+      }, durationMs);
+      if (record.timeoutId.unref) {
+        record.timeoutId.unref();
+      }
+    }
+  }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rate-limiter-flexible",
-  "version": "11.0.2",
+  "version": "11.1.0",
   "description": "Node.js atomic and non-atomic counters, rate limiting tools, protection from DoS and brute-force attacks at scale",
   "main": "index.js",
   "scripts": {

package/types.d.ts

@@ -318,7 +318,7 @@ interface IRateLimiterRedisOptions extends IRateLimiterStoreOptions {
 }
 
 interface IRateLimiterValkeyOptions extends IRateLimiterStoreOptions {
-  customIncrTtlLuaScript?: string;
+    customIncrTtlLuaScript?: string;
 }
 
 interface ICallbackReady {
@@ -334,8 +334,43 @@ interface IRLWrapperBlackAndWhiteOptions {
     runActionAnyway?: boolean;
 }
 
+export interface IRateLimiterMemoryRecord {
+    key: string | number;
+    value: number;
+    expiresAt: number | null;
+}
+
+export interface IRateLimiterMemoryExport {
+    version: number;
+    dumpedAt: number;
+    storage: IRateLimiterMemoryRecord[];
+}
+
+/** Common structure for restore results. */
+export interface IRateLimiterRestoreResult<T> {
+    invalid: T;
+    expired: T;
+    restored: T;
+}
+
+/** Returned by {@link RateLimiterMemory.restore} when `detailResponse` is `false` (default). */
+export type IRateLimiterRestoreResponse = IRateLimiterRestoreResult<number>;
+
+export interface IRateLimiterRestoreBucketDetail {
+    count: number;
+    keys: Array<string | number>;
+}
+
+/** Returned by {@link RateLimiterMemory.restore} when `detailResponse` is `true`. */
+export type IRateLimiterRestoreDetailResponse = IRateLimiterRestoreResult<IRateLimiterRestoreBucketDetail>;
+
 export class RateLimiterMemory extends RateLimiterAbstract {
     constructor(opts: IRateLimiterOptions);
+
+    dump(): IRateLimiterMemoryExport;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse: true): IRateLimiterRestoreDetailResponse | undefined;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse?: false): IRateLimiterRestoreResponse | undefined;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse?: boolean): IRateLimiterRestoreResponse | IRateLimiterRestoreDetailResponse | undefined;
 }
 
 export class RateLimiterCluster extends RateLimiterAbstract {
@@ -359,7 +394,7 @@ export class RateLimiterRedisNonAtomic extends RateLimiterStoreAbstract {
 }
 
 export class RateLimiterValkey extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterValkeyOptions);
+    constructor(opts: IRateLimiterValkeyOptions);
 }
 
 export interface IRateLimiterMongoFunctionOptions {
@@ -424,19 +459,19 @@ export class RateLimiterPostgres extends RateLimiterStoreAbstract {
 }
 
 export class RateLimiterSQLite extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
 }
 
 export class RateLimiterPrisma extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
 }
 
 export class RateLimiterDrizzle extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
 }
 
 export class RateLimiterDrizzleNonAtomic extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
 }
 
 export class RateLimiterMemcache extends RateLimiterStoreAbstract { }