@depup/rate-limiter-flexible 9.1.1-depup.0

package/lib/RateLimiterUnion.js

@@ -0,0 +1,51 @@
+const RateLimiterAbstract = require('./RateLimiterAbstract');
+
+module.exports = class RateLimiterUnion {
+  constructor(...limiters) {
+    if (limiters.length < 1) {
+      throw new Error('RateLimiterUnion: at least one limiter have to be passed');
+    }
+    limiters.forEach((limiter) => {
+      if (!(limiter instanceof RateLimiterAbstract)) {
+        throw new Error('RateLimiterUnion: all limiters have to be instance of RateLimiterAbstract');
+      }
+    });
+
+    this._limiters = limiters;
+  }
+
+  consume(key, points = 1) {
+    return new Promise((resolve, reject) => {
+      const promises = [];
+      this._limiters.forEach((limiter) => {
+        promises.push(limiter.consume(key, points).catch(rej => ({ rejected: true, rej })));
+      });
+
+      Promise.all(promises)
+        .then((res) => {
+          const resObj = {};
+          let rejected = false;
+
+          res.forEach((item) => {
+            if (item.rejected === true) {
+              rejected = true;
+            }
+          });
+
+          for (let i = 0; i < res.length; i++) {
+            if (rejected && res[i].rejected === true) {
+              resObj[this._limiters[i].keyPrefix] = res[i].rej;
+            } else if (!rejected) {
+              resObj[this._limiters[i].keyPrefix] = res[i];
+            }
+          }
+
+          if (rejected) {
+            reject(resObj);
+          } else {
+            resolve(resObj);
+          }
+        });
+    });
+  }
+};

package/lib/RateLimiterValkey.js

@@ -0,0 +1,117 @@
+const RateLimiterStoreAbstract = require('./RateLimiterStoreAbstract');
+const RateLimiterRes = require('./RateLimiterRes');
+
+const incrTtlLuaScript = `
+server.call('set', KEYS[1], 0, 'EX', ARGV[2], 'NX')
+local consumed = server.call('incrby', KEYS[1], ARGV[1])
+local ttl = server.call('pttl', KEYS[1])
+return {consumed, ttl}
+`;
+
+class RateLimiterValkey extends RateLimiterStoreAbstract {
+  /**
+   *
+   * @param {Object} opts
+   * Defaults {
+   *   ... see other in RateLimiterStoreAbstract
+   *
+   *   storeClient: ValkeyClient
+   *   rejectIfValkeyNotReady: boolean = false - reject / invoke insuranceLimiter immediately when valkey connection is not "ready"
+   * }
+   */
+  constructor(opts) {
+    super(opts);
+    this.client = opts.storeClient;
+
+    this._rejectIfValkeyNotReady = !!opts.rejectIfValkeyNotReady;
+    this._incrTtlLuaScript = opts.customIncrTtlLuaScript || incrTtlLuaScript;
+
+    this.client.defineCommand('rlflxIncr', {
+      numberOfKeys: 1,
+      lua: this._incrTtlLuaScript,
+    });
+  }
+
+  /**
+   * Prevent actual valkey call if valkey connection is not ready
+   * @return {boolean}
+   * @private
+   */
+  _isValkeyReady() {
+    if (!this._rejectIfValkeyNotReady) {
+      return true;
+    }
+
+    return this.client.status === 'ready';
+  }
+
+  _getRateLimiterRes(rlKey, changedPoints, result) {
+    let consumed;
+    let resTtlMs;
+
+    if (Array.isArray(result[0])) {
+      [[, consumed], [, resTtlMs]] = result;
+    } else {
+      [consumed, resTtlMs] = result;
+    }
+
+    const res = new RateLimiterRes();
+    res.consumedPoints = +consumed;
+    res.isFirstInDuration = res.consumedPoints === changedPoints;
+    res.remainingPoints = Math.max(this.points - res.consumedPoints, 0);
+    res.msBeforeNext = resTtlMs;
+
+    return res;
+  }
+
+  _upsert(rlKey, points, msDuration, forceExpire = false) {
+    if (!this._isValkeyReady()) {
+      throw new Error('Valkey connection is not ready');
+    }
+
+    const secDuration = Math.floor(msDuration / 1000);
+
+    if (forceExpire) {
+      const multi = this.client.multi();
+
+      if (secDuration > 0) {
+        multi.set(rlKey, points, 'EX', secDuration);
+      } else {
+        multi.set(rlKey, points);
+      }
+
+      return multi.pttl(rlKey).exec();
+    }
+
+    if (secDuration > 0) {
+      return this.client.rlflxIncr([rlKey, String(points), String(secDuration), String(this.points), String(this.duration)]);
+    }
+
+    return this.client.multi().incrby(rlKey, points).pttl(rlKey).exec();
+  }
+
+  _get(rlKey) {
+    if (!this._isValkeyReady()) {
+      throw new Error('Valkey connection is not ready');
+    }
+
+    return this.client
+      .multi()
+      .get(rlKey)
+      .pttl(rlKey)
+      .exec()
+      .then((result) => {
+        const [[, points]] = result;
+        if (points === null) return null;
+        return result;
+      });
+  }
+
+  _delete(rlKey) {
+    return this.client
+      .del(rlKey)
+      .then(result => result > 0);
+  }
+}
+
+module.exports = RateLimiterValkey;

package/lib/RateLimiterValkeyGlide.js

@@ -0,0 +1,273 @@
+/* eslint-disable no-unused-vars */
+const RateLimiterStoreAbstract = require('./RateLimiterStoreAbstract');
+const RateLimiterRes = require('./RateLimiterRes');
+
+/**
+ * @typedef {import('@valkey/valkey-glide').GlideClient} GlideClient
+ * @typedef {import('@valkey/valkey-glide').GlideClusterClient} GlideClusterClient
+ */
+
+const DEFAULT_LIBRARY_NAME = 'ratelimiterflexible';
+
+const DEFAULT_VALKEY_SCRIPT = `local key = KEYS[1]
+local pointsToConsume = tonumber(ARGV[1])
+if tonumber(ARGV[2]) > 0 then
+  server.call('set', key, "0", 'EX', ARGV[2], 'NX')
+  local consumed = server.call('incrby', key, pointsToConsume)
+  local pttl = server.call('pttl', key)
+  return {consumed, pttl}
+end
+local consumed = server.call('incrby', key, pointsToConsume)
+local pttl = server.call('pttl', key)
+return {consumed, pttl}`;
+
+const GET_VALKEY_SCRIPT = `local key = KEYS[1]
+local value = server.call('get', key)
+if value == nil then
+  return value
+end
+local pttl = server.call('pttl', key)
+return {tonumber(value), pttl}`;
+
+class RateLimiterValkeyGlide extends RateLimiterStoreAbstract {
+  /**
+   * Constructor for RateLimiterValkeyGlide
+   *
+   * @param {Object} opts - Configuration options
+   * @param {GlideClient|GlideClusterClient} opts.storeClient - Valkey Glide client instance (required)
+   * @param {number} [opts.points=4] - Maximum number of points that can be consumed over duration
+   * @param {number} [opts.duration=1] - Duration in seconds before points are reset
+   * @param {number} [opts.blockDuration=0] - Duration in seconds that a key will be blocked for if consumed more than points
+   * @param {boolean} [opts.rejectIfValkeyNotReady=false] - Whether to reject requests if Valkey is not ready
+   * @param {boolean} [opts.execEvenly=false] - Delay actions to distribute them evenly over duration
+   * @param {number} [opts.execEvenlyMinDelayMs] - Minimum delay between actions when execEvenly is true
+   * @param {string} [opts.customFunction] - Custom Lua script for rate limiting logic
+   * @param {number} [opts.inMemoryBlockOnConsumed] - Points threshold for in-memory blocking
+   * @param {number} [opts.inMemoryBlockDuration] - Duration in seconds for in-memory blocking
+   * @param {string} [opts.customFunctionLibName] - Custom name for the function library, defaults to 'ratelimiter'.
+   * The name is used to identify the library of the lua function. An custom name should be used only if you
+   * you want to use different libraries for different rate limiters, otherwise it is not needed.
+   * @param {RateLimiterAbstract} [opts.insuranceLimiter] - Backup limiter to use when the primary client fails
+   *
+   * @example
+   * const rateLimiter = new RateLimiterValkeyGlide({
+   *   storeClient: glideClient,
+   *   points: 5,
+   *   duration: 1
+   * });
+   *
+   * @example <caption>With custom Lua function</caption>
+   * const customScript = `local key = KEYS[1]
+   * local pointsToConsume = tonumber(ARGV[1]) or 0
+   * local secDuration = tonumber(ARGV[2]) or 0
+   *
+   * -- Custom implementation
+   * -- ...
+   *
+   * -- Must return exactly two values: [consumed_points, ttl_in_ms]
+   * return {consumed, ttl}`
+   *
+   * const rateLimiter = new RateLimiterValkeyGlide({
+   *   storeClient: glideClient,
+   *   points: 5,
+   *   customFunction: customScript
+   * });
+   *
+   * @example <caption>With insurance limiter</caption>
+   * const rateLimiter = new RateLimiterValkeyGlide({
+   *   storeClient: primaryGlideClient,
+   *   points: 5,
+   *   duration: 2,
+   *   insuranceLimiter: new RateLimiterMemory({
+   *     points: 5,
+   *     duration: 2
+   *   })
+   * });
+   *
+   * @description
+   * When providing a custom Lua script via `opts.customFunction`, it must:
+   *
+   * 1. Accept parameters:
+   *    - KEYS[1]: The key being rate limited
+   *    - ARGV[1]: Points to consume (as string, use tonumber() to convert)
+   *    - ARGV[2]: Duration in seconds (as string, use tonumber() to convert)
+   *
+   * 2. Return an array with exactly two elements:
+   *    - [0]: Consumed points (number)
+   *    - [1]: TTL in milliseconds (number)
+   *
+   * 3. Handle scenarios:
+   *    - New key creation: Initialize with expiry for fixed windows
+   *    - Key updates: Increment existing counters
+   */
+  constructor(opts) {
+    super(opts);
+    this.client = opts.storeClient;
+    this._scriptLoaded = false;
+    this._getScriptLoaded = false;
+    this._rejectIfValkeyNotReady = !!opts.rejectIfValkeyNotReady;
+    this._luaScript = opts.customFunction || DEFAULT_VALKEY_SCRIPT;
+    this._libraryName = opts.customFunctionLibName || DEFAULT_LIBRARY_NAME;
+  }
+
+  /**
+   * Ensure scripts are loaded in the Valkey server
+   * @returns {Promise<boolean>} True if scripts are loaded
+   * @private
+   */
+  async _loadScripts() {
+    if (this._scriptLoaded && this._getScriptLoaded) {
+      return true;
+    }
+    if (!this.client) {
+      throw new Error('Valkey client is not set');
+    }
+    const promises = [];
+    if (!this._scriptLoaded) {
+      const script = Buffer.from(`#!lua name=${this._libraryName}
+        local function consume(KEYS, ARGV)
+          ${this._luaScript.trim()}
+        end
+        server.register_function('consume', consume)`);
+      promises.push(this.client.functionLoad(script, { replace: true }));
+    } else promises.push(Promise.resolve(this._libraryName));
+
+    if (!this._getScriptLoaded) {
+      const script = Buffer.from(`#!lua name=ratelimiter_get
+        local function getValue(KEYS, ARGV)
+          ${GET_VALKEY_SCRIPT.trim()}
+        end
+        server.register_function('getValue', getValue)`);
+      promises.push(this.client.functionLoad(script, { replace: true }));
+    } else promises.push(Promise.resolve('ratelimiter_get'));
+
+    const results = await Promise.all(promises);
+    this._scriptLoaded = results[0] === this._libraryName;
+    this._getScriptLoaded = results[1] === 'ratelimiter_get';
+
+    if ((!this._scriptLoaded || !this._getScriptLoaded)) {
+      throw new Error('Valkey connection is not ready, scripts not loaded');
+    }
+    return true;
+  }
+
+  /**
+   * Update or insert the rate limiter record
+   *
+   * @param {string} rlKey - The rate limiter key
+   * @param {number} pointsToConsume - Points to be consumed
+   * @param {number} msDuration - Duration in milliseconds
+   * @param {boolean} [forceExpire=false] - Whether to force expiration
+   * @param {Object} [options={}] - Additional options
+   * @returns {Promise<Array>} Array containing consumed points and TTL
+   * @private
+   */
+  async _upsert(rlKey, pointsToConsume, msDuration, forceExpire = false, options = {}) {
+    await this._loadScripts();
+    const secDuration = Math.floor(msDuration / 1000);
+    if (forceExpire) {
+      if (secDuration > 0) {
+        await this.client.set(
+          rlKey,
+          String(pointsToConsume),
+          { expiry: { type: 'EX', count: secDuration } },
+        );
+        return [pointsToConsume, secDuration * 1000];
+      }
+      await this.client.set(rlKey, String(pointsToConsume));
+      return [pointsToConsume, -1];
+    }
+    const result = await this.client.fcall(
+      'consume',
+      [rlKey],
+      [String(pointsToConsume), String(secDuration)],
+    );
+    return result;
+  }
+
+  /**
+   * Get the rate limiter record
+   *
+   * @param {string} rlKey - The rate limiter key
+   * @param {Object} [options={}] - Additional options
+   * @returns {Promise<Array|null>} Array containing consumed points and TTL, or null if not found
+   * @private
+   */
+  async _get(rlKey, options = {}) {
+    await this._loadScripts();
+    const res = await this.client.fcall('getValue', [rlKey], []);
+    return res.length > 0 ? res : null;
+  }
+
+  /**
+   * Delete the rate limiter record
+   *
+   * @param {string} rlKey - The rate limiter key
+   * @param {Object} [options={}] - Additional options
+   * @returns {Promise<boolean>} True if successful, false otherwise
+   * @private
+   */
+  async _delete(rlKey, options = {}) {
+    const result = await this.client.del([rlKey]);
+    return result > 0;
+  }
+
+  /**
+   * Convert raw result to RateLimiterRes object
+   *
+   * @param {string} rlKey - The rate limiter key
+   * @param {number} changedPoints - Points changed in this operation
+   * @param {Array|null} result - Result from Valkey operation
+   * @returns {RateLimiterRes|null} RateLimiterRes object or null if result is null
+   * @private
+   */
+  _getRateLimiterRes(rlKey, changedPoints, result) {
+    if (result === null) {
+      return null;
+    }
+    const res = new RateLimiterRes();
+    const [consumedPointsStr, pttl] = result;
+    const consumedPoints = Number(consumedPointsStr);
+
+    // Handle consumed points
+    res.isFirstInDuration = consumedPoints === changedPoints;
+    res.consumedPoints = consumedPoints;
+    res.remainingPoints = Math.max(this.points - res.consumedPoints, 0);
+    res.msBeforeNext = pttl;
+    return res;
+  }
+
+  /**
+   * Close the rate limiter and release resources
+   * Note: The method won't going to close the Valkey client, as it may be shared with other instances.
+   * @returns {Promise<void>} Promise that resolves when the rate limiter is closed
+   */
+  async close() {
+    if (this._scriptLoaded) {
+      await this.client.functionDelete(this._libraryName);
+      this._scriptLoaded = false;
+    }
+    if (this._getScriptLoaded) {
+      await this.client.functionDelete('ratelimiter_get');
+      this._getScriptLoaded = false;
+    }
+    if (this.insuranceLimiter) {
+      try {
+        await this.insuranceLimiter.close();
+      } catch (e) {
+        // We can't assume that insuranceLimiter is a Valkey client or any
+        // other insuranceLimiter type which implement close method.
+      }
+    }
+    // Clear instance properties to let garbage collector free memory
+    this.client = null;
+    this._scriptLoaded = false;
+    this._getScriptLoaded = false;
+    this._rejectIfValkeyNotReady = false;
+    this._luaScript = null;
+    this._libraryName = null;
+    this.insuranceLimiter = null;
+  }
+}
+
+module.exports = RateLimiterValkeyGlide;

package/lib/component/BlockedKeys/BlockedKeys.js

@@ -0,0 +1,75 @@
+module.exports = class BlockedKeys {
+  constructor() {
+    this._keys = {}; // {'key': 1526279430331}
+    this._addedKeysAmount = 0;
+  }
+
+  collectExpired() {
+    const now = Date.now();
+
+    Object.keys(this._keys).forEach((key) => {
+      if (this._keys[key] <= now) {
+        delete this._keys[key];
+      }
+    });
+
+    this._addedKeysAmount = Object.keys(this._keys).length;
+  }
+
+  /**
+   * Add new blocked key
+   *
+   * @param key String
+   * @param sec Number
+   */
+  add(key, sec) {
+    this.addMs(key, sec * 1000);
+  }
+
+  /**
+   * Add new blocked key for ms
+   *
+   * @param key String
+   * @param ms Number
+   */
+  addMs(key, ms) {
+    this._keys[key] = Date.now() + ms;
+    this._addedKeysAmount++;
+    if (this._addedKeysAmount > 999) {
+      this.collectExpired();
+    }
+  }
+
+  /**
+   * 0 means not blocked
+   *
+   * @param key
+   * @returns {number}
+   */
+  msBeforeExpire(key) {
+    const expire = this._keys[key];
+
+    if (expire && expire >= Date.now()) {
+      this.collectExpired();
+      const now = Date.now();
+      return expire >= now ? expire - now : 0;
+    }
+
+    return 0;
+  }
+
+  /**
+   * If key is not given, delete all data in memory
+   * 
+   * @param {string|undefined} key
+   */
+  delete(key) {
+    if (key) {
+      delete this._keys[key];
+    } else {
+      Object.keys(this._keys).forEach((key) => {
+        delete this._keys[key];
+      });
+    }
+  }
+};

package/lib/component/BlockedKeys/index.js

@@ -0,0 +1,3 @@
+const BlockedKeys = require('./BlockedKeys');
+
+module.exports = BlockedKeys;

package/lib/component/MemoryStorage/MemoryStorage.js

@@ -0,0 +1,83 @@
+const Record = require('./Record');
+const RateLimiterRes = require('../../RateLimiterRes');
+
+module.exports = class MemoryStorage {
+  constructor() {
+    /**
+     * @type {Object.<string, Record>}
+     * @private
+     */
+    this._storage = {};
+  }
+
+  incrby(key, value, durationSec) {
+    if (this._storage[key]) {
+      const msBeforeExpires = this._storage[key].expiresAt
+        ? this._storage[key].expiresAt.getTime() - new Date().getTime()
+        : -1;
+      if (!this._storage[key].expiresAt || msBeforeExpires > 0) {
+        // Change value
+        this._storage[key].value = this._storage[key].value + value;
+
+        return new RateLimiterRes(0, msBeforeExpires, this._storage[key].value, false);
+      }
+
+      return this.set(key, value, durationSec);
+    }
+    return this.set(key, value, durationSec);
+  }
+
+  set(key, value, durationSec) {
+    const durationMs = durationSec * 1000;
+
+    if (this._storage[key] && this._storage[key].timeoutId) {
+      clearTimeout(this._storage[key].timeoutId);
+    }
+
+    this._storage[key] = new Record(
+      value,
+      durationMs > 0 ? new Date(Date.now() + durationMs) : null
+    );
+    if (durationMs > 0) {
+      this._storage[key].timeoutId = setTimeout(() => {
+        delete this._storage[key];
+      }, durationMs);
+      if (this._storage[key].timeoutId.unref) {
+        this._storage[key].timeoutId.unref();
+      }
+    }
+
+    return new RateLimiterRes(0, durationMs === 0 ? -1 : durationMs, this._storage[key].value, true);
+  }
+
+  /**
+   *
+   * @param key
+   * @returns {*}
+   */
+  get(key) {
+    if (this._storage[key]) {
+      const msBeforeExpires = this._storage[key].expiresAt
+        ? this._storage[key].expiresAt.getTime() - new Date().getTime()
+        : -1;
+      return new RateLimiterRes(0, msBeforeExpires, this._storage[key].value, false);
+    }
+    return null;
+  }
+
+  /**
+   *
+   * @param key
+   * @returns {boolean}
+   */
+  delete(key) {
+    if (this._storage[key]) {
+      if (this._storage[key].timeoutId) {
+        clearTimeout(this._storage[key].timeoutId);
+      }
+      delete this._storage[key];
+      return true;
+    }
+    return false;
+  }
+};

package/lib/component/MemoryStorage/Record.js

@@ -0,0 +1,40 @@
+module.exports = class Record {
+  /**
+   *
+   * @param value int
+   * @param expiresAt Date|int
+   * @param timeoutId
+   */
+  constructor(value, expiresAt, timeoutId = null) {
+    this.value = value;
+    this.expiresAt = expiresAt;
+    this.timeoutId = timeoutId;
+  }
+
+  get value() {
+    return this._value;
+  }
+
+  set value(value) {
+    this._value = parseInt(value);
+  }
+
+  get expiresAt() {
+    return this._expiresAt;
+  }
+
+  set expiresAt(value) {
+    if (!(value instanceof Date) && Number.isInteger(value)) {
+      value = new Date(value);
+    }
+    this._expiresAt = value;
+  }
+
+  get timeoutId() {
+    return this._timeoutId;
+  }
+
+  set timeoutId(value) {
+    this._timeoutId = value;
+  }
+};

package/lib/component/MemoryStorage/index.js

@@ -0,0 +1,3 @@
+const MemoryStorage = require('./MemoryStorage');
+
+module.exports = MemoryStorage;

package/lib/component/RateLimiterEtcdTransactionFailedError.js

@@ -0,0 +1,10 @@
+module.exports = class RateLimiterEtcdTransactionFailedError extends Error {
+  constructor(message) {
+    super();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = 'RateLimiterEtcdTransactionFailedError';
+    this.message = message;
+  }
+};

package/lib/component/RateLimiterQueueError.js

@@ -0,0 +1,13 @@
+module.exports = class RateLimiterQueueError extends Error {
+  constructor(message, extra) {
+    super();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = 'CustomError';
+    this.message = message;
+    if (extra) {
+      this.extra = extra;
+    }
+  }
+};

package/lib/component/RateLimiterSetupError.js

@@ -0,0 +1,10 @@
+module.exports = class RateLimiterSetupError extends Error {
+  constructor(message) {
+    super();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = 'RateLimiterSetupError';
+    this.message = message;
+  }
+};