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

package/lib/RateLimiterSQLite.js

@@ -0,0 +1,338 @@
+const RateLimiterStoreAbstract = require("./RateLimiterStoreAbstract");
+const RateLimiterRes = require("./RateLimiterRes");
+
+class RateLimiterSQLite extends RateLimiterStoreAbstract {
+  /**
+   * Internal store type used to determine the SQLite client in use.
+   * It can be one of the following:
+   * - `"sqlite3".
+   * - `"better-sqlite3".
+   *
+   * @type {("sqlite3" | "better-sqlite3" | null)}
+   * @private
+   */
+  _internalStoreType = null;
+
+  /**
+   * @callback callback
+   * @param {Object} err
+   *
+   * @param {Object} opts
+   * @param {callback} cb
+   * Defaults {
+   *   ... see other in RateLimiterStoreAbstract
+   *   storeClient: sqliteClient, // SQLite database instance (sqlite3, better-sqlite3, or knex instance)
+   *   storeType: 'sqlite3' | 'better-sqlite3' | 'knex', // Optional, defaults to 'sqlite3'
+   *   tableName: 'string',
+   *   tableCreated: boolean,
+   *   clearExpiredByTimeout: boolean,
+   * }
+   */
+  constructor(opts, cb = null) {
+    super(opts);
+
+    this.client = opts.storeClient;
+    this.storeType = opts.storeType || "sqlite3";
+    this.tableName = opts.tableName;
+    this.tableCreated = opts.tableCreated || false;
+    this.clearExpiredByTimeout = opts.clearExpiredByTimeout;
+
+    this._validateStoreTypes(cb);
+    this._validateStoreClient(cb);
+    this._setInternalStoreType(cb);
+    this._validateTableName(cb);
+
+    if (!this.tableCreated) {
+      this._createDbAndTable()
+        .then(() => {
+          this.tableCreated = true;
+          if (this.clearExpiredByTimeout) this._clearExpiredHourAgo();
+          if (typeof cb === "function") cb();
+        })
+        .catch((err) => {
+          if (typeof cb === "function") cb(err);
+          else throw err;
+        });
+    } else {
+      if (this.clearExpiredByTimeout) this._clearExpiredHourAgo();
+      if (typeof cb === "function") cb();
+    }
+  }
+  _validateStoreTypes(cb) {
+    const validStoreTypes = ["sqlite3", "better-sqlite3", "knex"];
+    if (!validStoreTypes.includes(this.storeType)) {
+      const err = new Error(
+        `storeType must be one of: ${validStoreTypes.join(", ")}`
+      );
+      if (typeof cb === "function") return cb(err);
+      throw err;
+    }
+  }
+  _validateStoreClient(cb) {
+    if (this.storeType === "sqlite3") {
+      if (typeof this.client.run !== "function") {
+        const err = new Error(
+          "storeClient must be an instance of sqlite3.Database when storeType is 'sqlite3' or no storeType was provided"
+        );
+        if (typeof cb === "function") return cb(err);
+        throw err;
+      }
+    } else if (this.storeType === "better-sqlite3") {
+      if (
+        typeof this.client.prepare !== "function" ||
+        typeof this.client.run !== "undefined"
+      ) {
+        const err = new Error(
+          "storeClient must be an instance of better-sqlite3.Database when storeType is 'better-sqlite3'"
+        );
+        if (typeof cb === "function") return cb(err);
+        throw err;
+      }
+    } else if (this.storeType === "knex") {
+      if (typeof this.client.raw !== "function") {
+        const err = new Error(
+          "storeClient must be an instance of Knex when storeType is 'knex'"
+        );
+        if (typeof cb === "function") return cb(err);
+        throw err;
+      }
+    }
+  }
+  _setInternalStoreType(cb) {
+    if (this.storeType === "knex") {
+      const knexClientType = this.client.client.config.client;
+      if (knexClientType === "sqlite3") {
+        this._internalStoreType = "sqlite3";
+      } else if (knexClientType === "better-sqlite3") {
+        this._internalStoreType = "better-sqlite3";
+      } else {
+        const err = new Error(
+          "Knex must be configured with 'sqlite3' or 'better-sqlite3' for RateLimiterSQLite"
+        );
+        if (typeof cb === "function") return cb(err);
+        throw err;
+      }
+    } else {
+      this._internalStoreType = this.storeType;
+    }
+  }
+  _validateTableName(cb) {
+    if (!/^[A-Za-z0-9_]*$/.test(this.tableName)) {
+      const err = new Error("Table name must contain only letters and numbers");
+      if (typeof cb === "function") return cb(err);
+      throw err;
+    }
+  }
+
+  /**
+   * Acquires the database connection based on the storeType.
+   * @returns {Promise<Object>} The database client or connection
+   */
+  async _getConnection() {
+    if (this.storeType === "knex") {
+      return this.client.client.acquireConnection(); // Acquire raw connection from knex pool
+    }
+    return this.client; // For sqlite3 and better-sqlite3, return the client directly
+  }
+
+  /**
+   * Releases the database connection if necessary.
+   * @param {Object} conn The database client or connection
+   */
+  _releaseConnection(conn) {
+    if (this.storeType === "knex") {
+      this.client.client.releaseConnection(conn);
+    }
+    // No release needed for direct sqlite3 or better-sqlite3 clients
+  }
+
+  async _createDbAndTable() {
+    const conn = await this._getConnection();
+    try {
+      switch (this._internalStoreType) {
+        case "sqlite3":
+          await new Promise((resolve, reject) => {
+            conn.run(this._getCreateTableSQL(), (err) =>
+              err ? reject(err) : resolve()
+            );
+          });
+          break;
+        case "better-sqlite3":
+          conn.prepare(this._getCreateTableSQL()).run();
+          break;
+        default:
+          throw new Error("Unsupported internalStoreType");
+      }
+    } finally {
+      this._releaseConnection(conn);
+    }
+  }
+
+  _getCreateTableSQL() {
+    return `CREATE TABLE IF NOT EXISTS ${this.tableName} (
+      key TEXT PRIMARY KEY,
+      points INTEGER NOT NULL DEFAULT 0,
+      expire INTEGER
+    )`;
+  }
+
+  _clearExpiredHourAgo() {
+    if (this._clearExpiredTimeoutId) clearTimeout(this._clearExpiredTimeoutId);
+    this._clearExpiredTimeoutId = setTimeout(() => {
+      this.clearExpired(Date.now() - 3600000) // 1 hour ago
+        .then(() => this._clearExpiredHourAgo());
+    }, 300000); // Every 5 minutes
+    this._clearExpiredTimeoutId.unref();
+  }
+
+  async clearExpired(nowMs) {
+    const sql = `DELETE FROM ${this.tableName} WHERE expire < ?`;
+    const conn = await this._getConnection();
+    try {
+      switch (this._internalStoreType) {
+        case "sqlite3":
+          await new Promise((resolve, reject) => {
+            conn.run(sql, [nowMs], (err) => (err ? reject(err) : resolve()));
+          });
+          break;
+        case "better-sqlite3":
+          conn.prepare(sql).run(nowMs);
+          break;
+        default:
+          throw new Error("Unsupported internalStoreType");
+      }
+    } finally {
+      this._releaseConnection(conn);
+    }
+  }
+
+  _getRateLimiterRes(rlKey, changedPoints, result) {
+    const res = new RateLimiterRes();
+    res.isFirstInDuration = changedPoints === result.points;
+    res.consumedPoints = res.isFirstInDuration ? changedPoints : result.points;
+    res.remainingPoints = Math.max(this.points - res.consumedPoints, 0);
+    res.msBeforeNext = result.expire
+      ? Math.max(result.expire - Date.now(), 0)
+      : -1;
+    return res;
+  }
+
+  async _upsertTransactionSQLite3(conn, upsertQuery, upsertParams) {
+    return await new Promise((resolve, reject) => {
+      conn.serialize(() => {
+        conn.run("SAVEPOINT rate_limiter_trx;", (err) => {
+          if (err) return reject(err);
+          conn.get(upsertQuery, upsertParams, (err, row) => {
+            if (err) {
+              conn.run("ROLLBACK TO SAVEPOINT rate_limiter_trx;", () =>
+                reject(err)
+              );
+              return;
+            }
+            conn.run("RELEASE SAVEPOINT rate_limiter_trx;", () => resolve(row));
+          });
+        });
+      });
+    });
+  }
+
+  async _upsertTransactionBetterSQLite3(conn, upsertQuery, upsertParams) {
+    return conn.transaction(() =>
+      conn.prepare(upsertQuery).get(...upsertParams)
+    )();
+  }
+  async _upsertTransaction(rlKey, points, msDuration, forceExpire) {
+    const dateNow = Date.now();
+    const newExpire = msDuration > 0 ? dateNow + msDuration : null;
+    const upsertQuery = forceExpire
+      ? `INSERT OR REPLACE INTO ${this.tableName} (key, points, expire) VALUES (?, ?, ?) RETURNING points, expire`
+      : `INSERT INTO ${this.tableName} (key, points, expire)
+         VALUES (?, ?, ?)
+         ON CONFLICT(key) DO UPDATE SET
+           points = CASE WHEN expire IS NULL OR expire > ? THEN points + excluded.points ELSE excluded.points END,
+           expire = CASE WHEN expire IS NULL OR expire > ? THEN expire ELSE excluded.expire END
+         RETURNING points, expire`;
+    const upsertParams = forceExpire
+      ? [rlKey, points, newExpire]
+      : [rlKey, points, newExpire, dateNow, dateNow];
+
+    const conn = await this._getConnection();
+    try {
+      switch (this._internalStoreType) {
+        case "sqlite3":
+          return this._upsertTransactionSQLite3(
+            conn,
+            upsertQuery,
+            upsertParams
+          );
+        case "better-sqlite3":
+          return this._upsertTransactionBetterSQLite3(
+            conn,
+            upsertQuery,
+            upsertParams
+          );
+        default:
+          throw new Error("Unsupported internalStoreType");
+      }
+    } finally {
+      this._releaseConnection(conn);
+    }
+  }
+
+  _upsert(rlKey, points, msDuration, forceExpire = false) {
+    if (!this.tableCreated) {
+      return Promise.reject(new Error("Table is not created yet"));
+    }
+    return this._upsertTransaction(rlKey, points, msDuration, forceExpire);
+  }
+
+  async _get(rlKey) {
+    const sql = `SELECT points, expire FROM ${this.tableName} WHERE key = ? AND (expire > ? OR expire IS NULL)`;
+    const now = Date.now();
+    const conn = await this._getConnection();
+    try {
+      switch (this._internalStoreType) {
+        case "sqlite3":
+          return await new Promise((resolve, reject) => {
+            conn.get(sql, [rlKey, now], (err, row) =>
+              err ? reject(err) : resolve(row || null)
+            );
+          });
+        case "better-sqlite3":
+          return conn.prepare(sql).get(rlKey, now) || null;
+        default:
+          throw new Error("Unsupported internalStoreType");
+      }
+    } finally {
+      this._releaseConnection(conn);
+    }
+  }
+
+  async _delete(rlKey) {
+    if (!this.tableCreated) {
+      return Promise.reject(new Error("Table is not created yet"));
+    }
+    const sql = `DELETE FROM ${this.tableName} WHERE key = ?`;
+    const conn = await this._getConnection();
+    try {
+      switch (this._internalStoreType) {
+        case "sqlite3":
+          return await new Promise((resolve, reject) => {
+            conn.run(sql, [rlKey], function (err) {
+              if (err) reject(err);
+              else resolve(this.changes > 0);
+            });
+          });
+        case "better-sqlite3":
+          const result = conn.prepare(sql).run(rlKey);
+          return result.changes > 0;
+        default:
+          throw new Error("Unsupported internalStoreType");
+      }
+    } finally {
+      this._releaseConnection(conn);
+    }
+  }
+}
+
+module.exports = RateLimiterSQLite;

package/lib/RateLimiterStoreAbstract.js

@@ -0,0 +1,349 @@
+const RateLimiterAbstract = require('./RateLimiterAbstract');
+const BlockedKeys = require('./component/BlockedKeys');
+const RateLimiterRes = require('./RateLimiterRes');
+const RateLimiterInsuredAbstract = require('./RateLimiterInsuredAbstract');
+
+module.exports = class RateLimiterStoreAbstract extends RateLimiterInsuredAbstract {
+  /**
+   *
+   * @param opts Object Defaults {
+   *   ... see other in RateLimiterAbstract
+   *
+   *   inMemoryBlockOnConsumed: 40, // Number of points when key is blocked
+   *   inMemoryBlockDuration: 10, // Block duration in seconds
+   *   insuranceLimiter: RateLimiterAbstract
+   * }
+   */
+  constructor(opts = {}) {
+    super(opts);
+
+    this.inMemoryBlockOnConsumed = opts.inMemoryBlockOnConsumed;
+    this.inMemoryBlockDuration = opts.inMemoryBlockDuration;
+    this._inMemoryBlockedKeys = new BlockedKeys();
+  }
+
+  get client() {
+    return this._client;
+  }
+
+  set client(value) {
+    if (typeof value === 'undefined') {
+      throw new Error('storeClient is not set');
+    }
+    this._client = value;
+  }
+
+  /**
+   * Have to be launched after consume
+   * It blocks key and execute evenly depending on result from store
+   *
+   * It uses _getRateLimiterRes function to prepare RateLimiterRes from store result
+   *
+   * @param resolve
+   * @param reject
+   * @param rlKey
+   * @param changedPoints
+   * @param storeResult
+   * @param {Object} options
+   * @private
+   */
+  _afterConsume(resolve, reject, rlKey, changedPoints, storeResult, options = {}) {
+    const res = this._getRateLimiterRes(rlKey, changedPoints, storeResult);
+
+    if (this.inMemoryBlockOnConsumed > 0 && !(this.inMemoryBlockDuration > 0)
+      && res.consumedPoints >= this.inMemoryBlockOnConsumed
+    ) {
+      this._inMemoryBlockedKeys.addMs(rlKey, res.msBeforeNext);
+      if (res.consumedPoints > this.points) {
+        return reject(res);
+      } else {
+        return resolve(res)
+      }
+    } else if (res.consumedPoints > this.points) {
+      let blockPromise = Promise.resolve();
+      // Block only first time when consumed more than points
+      if (this.blockDuration > 0 && res.consumedPoints <= (this.points + changedPoints)) {
+        res.msBeforeNext = this.msBlockDuration;
+        blockPromise = this._block(rlKey, res.consumedPoints, this.msBlockDuration, options);
+      }
+
+      if (this.inMemoryBlockOnConsumed > 0 && res.consumedPoints >= this.inMemoryBlockOnConsumed) {
+        // Block key for this.inMemoryBlockDuration seconds
+        this._inMemoryBlockedKeys.add(rlKey, this.inMemoryBlockDuration);
+        res.msBeforeNext = this.msInMemoryBlockDuration;
+      }
+
+      blockPromise
+        .then(() => {
+          reject(res);
+        })
+        .catch((err) => {
+          reject(err);
+        });
+    } else if (this.execEvenly && res.msBeforeNext > 0 && !res.isFirstInDuration) {
+      let delay = Math.ceil(res.msBeforeNext / (res.remainingPoints + 2));
+      if (delay < this.execEvenlyMinDelayMs) {
+        delay = res.consumedPoints * this.execEvenlyMinDelayMs;
+      }
+
+      setTimeout(resolve, delay, res);
+    } else {
+      resolve(res);
+    }
+  }
+
+  getInMemoryBlockMsBeforeExpire(rlKey) {
+    if (this.inMemoryBlockOnConsumed > 0) {
+      return this._inMemoryBlockedKeys.msBeforeExpire(rlKey);
+    }
+
+    return 0;
+  }
+
+  get inMemoryBlockOnConsumed() {
+    return this._inMemoryBlockOnConsumed;
+  }
+
+  set inMemoryBlockOnConsumed(value) {
+    this._inMemoryBlockOnConsumed = value ? parseInt(value) : 0;
+    if (this.inMemoryBlockOnConsumed > 0 && this.points > this.inMemoryBlockOnConsumed) {
+      throw new Error('inMemoryBlockOnConsumed option must be greater or equal "points" option');
+    }
+  }
+
+  get inMemoryBlockDuration() {
+    return this._inMemoryBlockDuration;
+  }
+
+  set inMemoryBlockDuration(value) {
+    this._inMemoryBlockDuration = value ? parseInt(value) : 0;
+    if (this.inMemoryBlockDuration > 0 && this.inMemoryBlockOnConsumed === 0) {
+      throw new Error('inMemoryBlockOnConsumed option must be set up');
+    }
+  }
+
+  get msInMemoryBlockDuration() {
+    return this._inMemoryBlockDuration * 1000;
+  }
+
+  /**
+   * Block any key for secDuration seconds
+   *
+   * @param key
+   * @param secDuration
+   * @param {Object} options
+   *
+   * @return Promise<RateLimiterRes>
+   */
+  block(key, secDuration, options = {}) {
+    const msDuration = secDuration * 1000;
+    return this._block(this.getKey(key), this.points + 1, msDuration, options);
+  }
+
+  /**
+   * Set points by key for any duration
+   *
+   * @param key
+   * @param points
+   * @param secDuration
+   * @param {Object} options
+   *
+   * @return Promise<RateLimiterRes>
+   */
+  set(key, points, secDuration, options = {}) {
+    const msDuration = (secDuration >= 0 ? secDuration : this.duration) * 1000;
+    return this._block(this.getKey(key), points, msDuration, options);
+  }
+
+  /**
+   *
+   * @param key
+   * @param pointsToConsume
+   * @param {Object} options
+   * @returns Promise<RateLimiterRes>
+   */
+  _consume(key, pointsToConsume = 1, options = {}) {
+    return new Promise((resolve, reject) => {
+      const rlKey = this.getKey(key);
+
+      const inMemoryBlockMsBeforeExpire = this.getInMemoryBlockMsBeforeExpire(rlKey);
+      if (inMemoryBlockMsBeforeExpire > 0) {
+        return reject(new RateLimiterRes(0, inMemoryBlockMsBeforeExpire));
+      }
+
+      this._upsert(rlKey, pointsToConsume, this._getKeySecDuration(options) * 1000, false, options)
+        .then((res) => {
+          this._afterConsume(resolve, reject, rlKey, pointsToConsume, res);
+        })
+        .catch((err) => reject(err));
+    });
+  }
+
+  /**
+   *
+   * @param key
+   * @param points
+   * @param {Object} options
+   * @returns Promise<RateLimiterRes>
+   */
+  _penalty(key, points = 1, options = {}) {
+    const rlKey = this.getKey(key);
+    return new Promise((resolve, reject) => {
+      this._upsert(rlKey, points, this._getKeySecDuration(options) * 1000, false, options)
+        .then((res) => {
+          resolve(this._getRateLimiterRes(rlKey, points, res));
+        })
+        .catch((res) => reject(res));
+    });
+  }
+
+  /**
+   *
+   * @param key
+   * @param points
+   * @param {Object} options
+   * @returns Promise<RateLimiterRes>
+   */
+  _reward(key, points = 1, options = {}) {
+    const rlKey = this.getKey(key);
+    return new Promise((resolve, reject) => {
+      this._upsert(rlKey, -points, this._getKeySecDuration(options) * 1000, false, options)
+        .then((res) => {
+          resolve(this._getRateLimiterRes(rlKey, -points, res));
+        })
+        .catch((res) => reject(res));
+    });
+  }
+
+  /**
+   *
+   * @param key
+   * @param {Object} options
+   * @returns Promise<RateLimiterRes>|null
+   */
+  get(key, options = {}) {
+    const rlKey = this.getKey(key);
+    return new Promise((resolve, reject) => {
+      this._get(rlKey, options)
+        .then((res) => {
+          if (res === null || typeof res === 'undefined') {
+            resolve(null);
+          } else {
+            resolve(this._getRateLimiterRes(rlKey, 0, res));
+          }
+        })
+        .catch((err) => {
+          this._handleError(err, 'get', resolve, reject, [key, options]);
+        });
+    });
+  }
+
+  /**
+   *
+   * @param key
+   * @param {Object} options
+   * @returns Promise<boolean>
+   */
+  delete(key, options = {}) {
+    const rlKey = this.getKey(key);
+    return new Promise((resolve, reject) => {
+      this._delete(rlKey, options)
+        .then((res) => {
+          this._inMemoryBlockedKeys.delete(rlKey);
+          resolve(res);
+        })
+        .catch((err) => {
+          this._handleError(err, 'delete', resolve, reject, [key, options]);
+        });
+    });
+  }
+
+  /**
+   * Cleanup keys no-matter expired or not.
+   */
+  deleteInMemoryBlockedAll() {
+    this._inMemoryBlockedKeys.delete();
+  }
+
+  /**
+   * Get RateLimiterRes object filled depending on storeResult, which specific for exact store
+   *
+   * @param rlKey
+   * @param changedPoints
+   * @param storeResult
+   * @private
+   */
+  _getRateLimiterRes(rlKey, changedPoints, storeResult) { // eslint-disable-line no-unused-vars
+    throw new Error("You have to implement the method '_getRateLimiterRes'!");
+  }
+
+  /**
+   * Block key for this.msBlockDuration milliseconds
+   * Usually, it just prolongs lifetime of key
+   *
+   * @param rlKey
+   * @param initPoints
+   * @param msDuration
+   * @param {Object} options
+   *
+   * @return Promise<any>
+   */
+  _block(rlKey, initPoints, msDuration, options = {}) {
+    return new Promise((resolve, reject) => {
+      this._upsert(rlKey, initPoints, msDuration, true, options)
+        .then(() => {
+          resolve(new RateLimiterRes(0, msDuration > 0 ? msDuration : -1, initPoints));
+        })
+        .catch((err) => {
+          this._handleError(err, 'block', resolve, reject, [this.parseKey(rlKey), msDuration / 1000, options]);
+        });
+    });
+  }
+
+  /**
+   * Have to be implemented in every limiter
+   * Resolve with raw result from Store OR null if rlKey is not set
+   * or Reject with error
+   *
+   * @param rlKey
+   * @param {Object} options
+   * @private
+   *
+   * @return Promise<any>
+   */
+  _get(rlKey, options = {}) { // eslint-disable-line no-unused-vars
+    throw new Error("You have to implement the method '_get'!");
+  }
+
+  /**
+   * Have to be implemented
+   * Resolve with true OR false if rlKey doesn't exist
+   * or Reject with error
+   *
+   * @param rlKey
+   * @param {Object} options
+   * @private
+   *
+   * @return Promise<any>
+   */
+  _delete(rlKey, options = {}) { // eslint-disable-line no-unused-vars
+    throw new Error("You have to implement the method '_delete'!");
+  }
+
+  /**
+   * Have to be implemented
+   * Resolve with object used for {@link _getRateLimiterRes} to generate {@link RateLimiterRes}
+   *
+   * @param {string} rlKey
+   * @param {number} points
+   * @param {number} msDuration
+   * @param {boolean} forceExpire
+   * @param {Object} options
+   * @abstract
+   *
+   * @return Promise<Object>
+   */
+  _upsert(rlKey, points, msDuration, forceExpire = false, options = {}) {
+    throw new Error("You have to implement the method '_upsert'!");
+  }
+};