hono-rate-limiter 0.5.2 → 0.5.4

package/dist/index.cjs

@@ -360,6 +360,19 @@ const scripts = {
       local timeToExpire = redis.call("PTTL", KEYS[1])
 
       return { totalHits, timeToExpire }
+		`.replaceAll(/^\s+/gm, "").trim(),
+  // Mirrors the `MemoryStore` behaviour: never go below zero, and never
+  // disturb the expiry. A raw DECR on a missing key (e.g. the window expired
+  // while a slow handler ran) would create it at -1 with no TTL, and that
+  // negative value would leak into the next window, letting a client exceed
+  // the configured limit. Reading the value first and only decrementing when
+  // it is a positive number avoids that. A nil GET means the window already
+  // ended, so the correct action is to do nothing.
+  decrement: `
+      local current = tonumber(redis.call("GET", KEYS[1]))
+      if current and current > 0 then
+        redis.call("DECR", KEYS[1])
+      end
 		`.replaceAll(/^\s+/gm, "").trim()
 };
 
@@ -389,6 +402,13 @@ class RedisStore {
     this.resetExpiryOnChange = options.resetExpiryOnChange ?? false;
     this.incrementScriptSha = this.loadIncrementScript();
     this.getScriptSha = this.loadGetScript();
+    this.decrementScriptSha = this.loadDecrementScript();
+    this.incrementScriptSha.catch(() => {
+    });
+    this.getScriptSha.catch(() => {
+    });
+    this.decrementScriptSha.catch(() => {
+    });
   }
   /**
    * Loads the script used to increment a client's hit count.
@@ -410,6 +430,16 @@ class RedisStore {
     }
     return result;
   }
+  /**
+   * Loads the script used to decrement a client's hit count.
+   */
+  async loadDecrementScript() {
+    const result = await this.client.scriptLoad(scripts.decrement);
+    if (typeof result !== "string") {
+      throw new TypeError("unexpected reply from redis client");
+    }
+    return result;
+  }
   /**
    * Runs the increment command, and retries it if the script is not loaded.
    */
@@ -427,6 +457,23 @@ class RedisStore {
       return evalCommand();
     }
   }
+  /**
+   * Runs the decrement command, and retries it if the script is not loaded.
+   */
+  async retryableDecrement(key) {
+    const evalCommand = async () => this.client.evalsha(
+      await this.decrementScriptSha,
+      [this.prefixKey(key)],
+      []
+    );
+    try {
+      const result = await evalCommand();
+      return result;
+    } catch {
+      this.decrementScriptSha = this.loadDecrementScript();
+      return evalCommand();
+    }
+  }
   /**
    * Method to prefix the keys with the given text.
    *
@@ -474,10 +521,16 @@ class RedisStore {
   /**
    * Method to decrement a client's hit counter.
    *
+   * Uses a Lua script so the read-and-decrement is atomic. It never takes the
+   * counter below zero and never touches the key's expiry, mirroring the
+   * `MemoryStore`. This prevents a decrement that lands after the window has
+   * expired from creating a negative, TTL-less key that would leak extra
+   * requests into the next window.
+   *
    * @param key {string} - The identifier for a client
    */
   async decrement(key) {
-    await this.client.decr(this.prefixKey(key));
+    await this.retryableDecrement(key);
   }
   /**
    * Method to reset a client's hit counter.
@@ -525,15 +578,23 @@ class UnstorageStore {
    * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
    */
   async get(key) {
-    const result = await this.storage.get(this.prefixKey(key)).then(
-      (value) => value ? JSON.parse(String(value)) : void 0
-    );
+    const result = await this.storage.get(this.prefixKey(key)).then((value) => {
+      if (typeof value === "object") {
+        return value;
+      }
+      return value ? JSON.parse(String(value)) : void 0;
+    });
     return result;
   }
   /**
    * Method to increment a client's hit counter. If the current time is within an active window,
    * it increments the existing hit count. Otherwise, it starts a new window with a hit count of 1.
    *
+   * @remarks
+   * This read-modify-write is not atomic. Concurrent calls for the same key
+   * may under-count and let a client exceed the limit. See the class-level
+   * remarks for details and alternatives.
+   *
    * @param key {string} - The identifier for a client
    *
    * @returns {ClientRateLimitInfo} - An object containing:
@@ -656,26 +717,18 @@ function webSocketLimiter(config) {
             decremented = true;
           }
         };
-        const shouldSkipRequest = async () => {
-          if (skipSuccessfulRequests) await decrementKey();
-        };
         if (totalHits > _limit) {
-          await shouldSkipRequest();
           return handler(event, ws, options);
         }
         try {
           await events.onMessage?.(event, ws);
-          await shouldSkipRequest();
+          if (skipSuccessfulRequests) await decrementKey();
         } catch (error) {
           if (skipFailedRequests) await decrementKey();
           throw error;
         }
       },
       onError: async (event, ws) => {
-        if (skipFailedRequests) {
-          const key = await keyGenerator(c);
-          await store.decrement(key);
-        }
         events.onError?.(event, ws);
       }
     };

package/dist/index.d.cts

@@ -143,7 +143,7 @@ type HonoConfigType<E extends Env = Env, P extends string = string, I extends In
      */
     skipSuccessfulRequests: boolean;
     /**
-     * Method to determine whether or not the request counts as 'succesful'. Used
+     * Method to determine whether or not the request counts as 'successful'. Used
      * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
      *
      * By default, requests with a response status code less than 400 are considered
@@ -439,6 +439,7 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
      */
     incrementScriptSha: Promise<string>;
     getScriptSha: Promise<string>;
+    decrementScriptSha: Promise<string>;
     /**
      * @constructor for `RedisStore`.
      *
@@ -453,10 +454,18 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
      * Loads the script used to fetch a client's hit count and expiry time.
      */
     loadGetScript(): Promise<string>;
+    /**
+     * Loads the script used to decrement a client's hit count.
+     */
+    loadDecrementScript(): Promise<string>;
     /**
      * Runs the increment command, and retries it if the script is not loaded.
      */
     retryableIncrement(key: string): Promise<RedisReply>;
+    /**
+     * Runs the decrement command, and retries it if the script is not loaded.
+     */
+    retryableDecrement(key: string): Promise<RedisReply>;
     /**
      * Method to prefix the keys with the given text.
      *
@@ -490,6 +499,12 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
     /**
      * Method to decrement a client's hit counter.
      *
+     * Uses a Lua script so the read-and-decrement is atomic. It never takes the
+     * counter below zero and never touches the key's expiry, mirroring the
+     * `MemoryStore`. This prevents a decrement that lands after the window has
+     * expired from creating a negative, TTL-less key that would leak extra
+     * requests into the next window.
+     *
      * @param key {string} - The identifier for a client
      */
     decrement(key: string): Promise<void>;
@@ -510,6 +525,22 @@ type UnstorageInstance = {
  * A `Store` that stores the hit count for each client using Unstorage
  *
  * {@link https://unstorage.unjs.io/}
+ *
+ * @remarks
+ * **Not safe under high concurrency.** Unstorage exposes no atomic
+ * increment or compare-and-swap primitive, so `increment()` and
+ * `decrement()` perform a non-atomic read-modify-write against the backing
+ * driver. When many requests for the same key arrive at once, they can all
+ * read the same hit count before any of them writes it back, so the counter
+ * under-counts and a client can exceed the configured limit. The wider the
+ * driver's read/write latency (e.g. Vercel KV, Cloudflare KV, S3), the wider
+ * this window. The same applies across multiple server instances sharing one
+ * backend.
+ *
+ * If you need correct counting under concurrent load, use a store backed by
+ * an atomic counter such as `RedisStore` (which does all its work inside a
+ * Lua script). `MemoryStore` is also race-free within a single process, but
+ * does not share state across instances.
  */
 declare class UnstorageStore<E extends Env$1 = Env$1, P extends string = string, I extends Input$1 = Input$1> implements Store<E, P, I> {
     /**
@@ -559,6 +590,11 @@ declare class UnstorageStore<E extends Env$1 = Env$1, P extends string = string,
      * Method to increment a client's hit counter. If the current time is within an active window,
      * it increments the existing hit count. Otherwise, it starts a new window with a hit count of 1.
      *
+     * @remarks
+     * This read-modify-write is not atomic. Concurrent calls for the same key
+     * may under-count and let a client exceed the limit. See the class-level
+     * remarks for details and alternatives.
+     *
      * @param key {string} - The identifier for a client
      *
      * @returns {ClientRateLimitInfo} - An object containing:

package/dist/index.d.ts

@@ -143,7 +143,7 @@ type HonoConfigType<E extends Env = Env, P extends string = string, I extends In
      */
     skipSuccessfulRequests: boolean;
     /**
-     * Method to determine whether or not the request counts as 'succesful'. Used
+     * Method to determine whether or not the request counts as 'successful'. Used
      * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
      *
      * By default, requests with a response status code less than 400 are considered
@@ -439,6 +439,7 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
      */
     incrementScriptSha: Promise<string>;
     getScriptSha: Promise<string>;
+    decrementScriptSha: Promise<string>;
     /**
      * @constructor for `RedisStore`.
      *
@@ -453,10 +454,18 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
      * Loads the script used to fetch a client's hit count and expiry time.
      */
     loadGetScript(): Promise<string>;
+    /**
+     * Loads the script used to decrement a client's hit count.
+     */
+    loadDecrementScript(): Promise<string>;
     /**
      * Runs the increment command, and retries it if the script is not loaded.
      */
     retryableIncrement(key: string): Promise<RedisReply>;
+    /**
+     * Runs the decrement command, and retries it if the script is not loaded.
+     */
+    retryableDecrement(key: string): Promise<RedisReply>;
     /**
      * Method to prefix the keys with the given text.
      *
@@ -490,6 +499,12 @@ declare class RedisStore<E extends Env$1 = Env$1, P extends string = string, I e
     /**
      * Method to decrement a client's hit counter.
      *
+     * Uses a Lua script so the read-and-decrement is atomic. It never takes the
+     * counter below zero and never touches the key's expiry, mirroring the
+     * `MemoryStore`. This prevents a decrement that lands after the window has
+     * expired from creating a negative, TTL-less key that would leak extra
+     * requests into the next window.
+     *
      * @param key {string} - The identifier for a client
      */
     decrement(key: string): Promise<void>;
@@ -510,6 +525,22 @@ type UnstorageInstance = {
  * A `Store` that stores the hit count for each client using Unstorage
  *
  * {@link https://unstorage.unjs.io/}
+ *
+ * @remarks
+ * **Not safe under high concurrency.** Unstorage exposes no atomic
+ * increment or compare-and-swap primitive, so `increment()` and
+ * `decrement()` perform a non-atomic read-modify-write against the backing
+ * driver. When many requests for the same key arrive at once, they can all
+ * read the same hit count before any of them writes it back, so the counter
+ * under-counts and a client can exceed the configured limit. The wider the
+ * driver's read/write latency (e.g. Vercel KV, Cloudflare KV, S3), the wider
+ * this window. The same applies across multiple server instances sharing one
+ * backend.
+ *
+ * If you need correct counting under concurrent load, use a store backed by
+ * an atomic counter such as `RedisStore` (which does all its work inside a
+ * Lua script). `MemoryStore` is also race-free within a single process, but
+ * does not share state across instances.
  */
 declare class UnstorageStore<E extends Env$1 = Env$1, P extends string = string, I extends Input$1 = Input$1> implements Store<E, P, I> {
     /**
@@ -559,6 +590,11 @@ declare class UnstorageStore<E extends Env$1 = Env$1, P extends string = string,
      * Method to increment a client's hit counter. If the current time is within an active window,
      * it increments the existing hit count. Otherwise, it starts a new window with a hit count of 1.
      *
+     * @remarks
+     * This read-modify-write is not atomic. Concurrent calls for the same key
+     * may under-count and let a client exceed the limit. See the class-level
+     * remarks for details and alternatives.
+     *
      * @param key {string} - The identifier for a client
      *
      * @returns {ClientRateLimitInfo} - An object containing:

package/dist/index.js

@@ -358,6 +358,19 @@ const scripts = {
       local timeToExpire = redis.call("PTTL", KEYS[1])
 
       return { totalHits, timeToExpire }
+		`.replaceAll(/^\s+/gm, "").trim(),
+  // Mirrors the `MemoryStore` behaviour: never go below zero, and never
+  // disturb the expiry. A raw DECR on a missing key (e.g. the window expired
+  // while a slow handler ran) would create it at -1 with no TTL, and that
+  // negative value would leak into the next window, letting a client exceed
+  // the configured limit. Reading the value first and only decrementing when
+  // it is a positive number avoids that. A nil GET means the window already
+  // ended, so the correct action is to do nothing.
+  decrement: `
+      local current = tonumber(redis.call("GET", KEYS[1]))
+      if current and current > 0 then
+        redis.call("DECR", KEYS[1])
+      end
 		`.replaceAll(/^\s+/gm, "").trim()
 };
 
@@ -387,6 +400,13 @@ class RedisStore {
     this.resetExpiryOnChange = options.resetExpiryOnChange ?? false;
     this.incrementScriptSha = this.loadIncrementScript();
     this.getScriptSha = this.loadGetScript();
+    this.decrementScriptSha = this.loadDecrementScript();
+    this.incrementScriptSha.catch(() => {
+    });
+    this.getScriptSha.catch(() => {
+    });
+    this.decrementScriptSha.catch(() => {
+    });
   }
   /**
    * Loads the script used to increment a client's hit count.
@@ -408,6 +428,16 @@ class RedisStore {
     }
     return result;
   }
+  /**
+   * Loads the script used to decrement a client's hit count.
+   */
+  async loadDecrementScript() {
+    const result = await this.client.scriptLoad(scripts.decrement);
+    if (typeof result !== "string") {
+      throw new TypeError("unexpected reply from redis client");
+    }
+    return result;
+  }
   /**
    * Runs the increment command, and retries it if the script is not loaded.
    */
@@ -425,6 +455,23 @@ class RedisStore {
       return evalCommand();
     }
   }
+  /**
+   * Runs the decrement command, and retries it if the script is not loaded.
+   */
+  async retryableDecrement(key) {
+    const evalCommand = async () => this.client.evalsha(
+      await this.decrementScriptSha,
+      [this.prefixKey(key)],
+      []
+    );
+    try {
+      const result = await evalCommand();
+      return result;
+    } catch {
+      this.decrementScriptSha = this.loadDecrementScript();
+      return evalCommand();
+    }
+  }
   /**
    * Method to prefix the keys with the given text.
    *
@@ -472,10 +519,16 @@ class RedisStore {
   /**
    * Method to decrement a client's hit counter.
    *
+   * Uses a Lua script so the read-and-decrement is atomic. It never takes the
+   * counter below zero and never touches the key's expiry, mirroring the
+   * `MemoryStore`. This prevents a decrement that lands after the window has
+   * expired from creating a negative, TTL-less key that would leak extra
+   * requests into the next window.
+   *
    * @param key {string} - The identifier for a client
    */
   async decrement(key) {
-    await this.client.decr(this.prefixKey(key));
+    await this.retryableDecrement(key);
   }
   /**
    * Method to reset a client's hit counter.
@@ -523,15 +576,23 @@ class UnstorageStore {
    * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
    */
   async get(key) {
-    const result = await this.storage.get(this.prefixKey(key)).then(
-      (value) => value ? JSON.parse(String(value)) : void 0
-    );
+    const result = await this.storage.get(this.prefixKey(key)).then((value) => {
+      if (typeof value === "object") {
+        return value;
+      }
+      return value ? JSON.parse(String(value)) : void 0;
+    });
     return result;
   }
   /**
    * Method to increment a client's hit counter. If the current time is within an active window,
    * it increments the existing hit count. Otherwise, it starts a new window with a hit count of 1.
    *
+   * @remarks
+   * This read-modify-write is not atomic. Concurrent calls for the same key
+   * may under-count and let a client exceed the limit. See the class-level
+   * remarks for details and alternatives.
+   *
    * @param key {string} - The identifier for a client
    *
    * @returns {ClientRateLimitInfo} - An object containing:
@@ -654,26 +715,18 @@ function webSocketLimiter(config) {
             decremented = true;
           }
         };
-        const shouldSkipRequest = async () => {
-          if (skipSuccessfulRequests) await decrementKey();
-        };
         if (totalHits > _limit) {
-          await shouldSkipRequest();
           return handler(event, ws, options);
         }
         try {
           await events.onMessage?.(event, ws);
-          await shouldSkipRequest();
+          if (skipSuccessfulRequests) await decrementKey();
         } catch (error) {
           if (skipFailedRequests) await decrementKey();
           throw error;
         }
       },
       onError: async (event, ws) => {
-        if (skipFailedRequests) {
-          const key = await keyGenerator(c);
-          await store.decrement(key);
-        }
         events.onError?.(event, ws);
       }
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hono-rate-limiter",
   "description": "Rate limit middleware for Hono.",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "license": "MIT",
   "keywords": [