hono-rate-limiter 0.3.0 → 0.4.0-rc.0

package/README.md

@@ -47,8 +47,8 @@ Here is a list of stores:
 | MemoryStore                                                                          | (default) Simple in-memory option. Does not share state when the app has multiple processes or servers.                                                                                            |
 | [`@hono-rate-limiter/redis`](https://www.npm.im/@hono-rate-limiter/redis)            | A [Redis](https://redis.io/)-backed store, used with [`@vercel/kv`](https://www.npmjs.com/package/@vercel/kv) and [`@upstash/redis`](https://www.npmjs.com/package/@upstash/redis)                 |
 | [`rate-limit-redis`](https://npm.im/rate-limit-redis)                                | A [Redis](https://redis.io/)-backed store, more suitable for large or demanding deployments.                                                                                                       |
-| [`rate-limit-postresql`](https://www.npm.im/@acpr/rate-limit-postgresql)             | A [PostgreSQL](https://www.postgresql.org/)-backed store.                                                                                                                                          |
-| [`rate-limit-memecached`](https://npmjs.org/package/rate-limit-memcached)            | A [Memcached](https://memcached.org/)-backed store.                                                                                                                                                |
+| [`rate-limit-postgresql`](https://www.npm.im/@acpr/rate-limit-postgresql)             | A [PostgreSQL](https://www.postgresql.org/)-backed store.                                                                                                                                          |
+| [`rate-limit-memcached`](https://npmjs.org/package/rate-limit-memcached)            | A [Memcached](https://memcached.org/)-backed store.                                                                                                                                                |
 | [`cluster-memory-store`](https://npm.im/@express-rate-limit/cluster-memory-store)    | A memory-store wrapper that shares state across all processes on a single server via the [node:cluster](https://nodejs.org/api/cluster.html) module. Does not share state across multiple servers. |
 | [`precise-memory-rate-limit`](https://www.npm.im/precise-memory-rate-limit)          | A memory store similar to the built-in one, except that it stores a distinct timestamp for each key.                                                                                               |
 | [`typeorm-rate-limit-store`](https://www.npmjs.com/package/typeorm-rate-limit-store) | Supports a variety of databases via [TypeORM](https://typeorm.io/): MySQL, MariaDB, CockroachDB, SQLite, Microsoft SQL Server, Oracle, SAP Hana, and more.                                         |

package/index.cjs.js

@@ -10,6 +10,9 @@ class MemoryStore{init(options){this.windowMs=options.windowMs;if(this.interval)
 
 const isValidStore=value=>!!value?.increment;
 
-function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return factory.createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
+function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implemented!");if(typeof store.init==="function")store.init(options);return factory.createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
+
+async function webSocketLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=1008,requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,handler=async(_,ws,options)=>ws.close(options.statusCode,options.message),store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implemented!");if(typeof store.init==="function")store.init(options);return createEvents=>{return async c=>{const events=await createEvents(c);return {...events,onMessage:async(event,ws)=>{const isSkippable=await skip(event,ws);if(isSkippable){await events.onMessage?.(event,ws);return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);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();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}},onError:async(event,ws)=>{if(skipFailedRequests){const key=await keyGenerator(c);await store.decrement(key);}events.onError?.(event,ws);}}}}}
 
 exports.rateLimiter = rateLimiter;
+exports.webSocketLimiter = webSocketLimiter;

package/index.esm.js

@@ -6,6 +6,8 @@ class MemoryStore{init(options){this.windowMs=options.windowMs;if(this.interval)
 
 const isValidStore=value=>!!value?.increment;
 
-function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
+function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implemented!");if(typeof store.init==="function")store.init(options);return createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
 
-export { rateLimiter };
+async function webSocketLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=1008,requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,handler=async(_,ws,options)=>ws.close(options.statusCode,options.message),store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implemented!");if(typeof store.init==="function")store.init(options);return createEvents=>{return async c=>{const events=await createEvents(c);return {...events,onMessage:async(event,ws)=>{const isSkippable=await skip(event,ws);if(isSkippable){await events.onMessage?.(event,ws);return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);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();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}},onError:async(event,ws)=>{if(skipFailedRequests){const key=await keyGenerator(c);await store.decrement(key);}events.onError?.(event,ws);}}}}}
+
+export { rateLimiter, webSocketLimiter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-rate-limiter",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.0",
   "license": "MIT",
   "keywords": [
     "hono",

package/src/core.d.ts

@@ -2,9 +2,9 @@ import type { Env, Input } from "hono";
 import type { ConfigType } from "./types";
 /**
  *
- * Create an instance of IP rate-limiting middleware for Hono.
+ * Create an instance of rate-limiting middleware for Hono.
  *
- * @param config {ConfigType} - Options to configure the rate limiter.
+ * @param config x{ConfigType} - Options to configure the rate limiter.
  *
  * @returns - The middleware that rate-limits clients based on your configuration.
  *

package/src/index.d.ts

@@ -1,2 +1,3 @@
 export { rateLimiter } from "./core";
+export { webSocketLimiter } from "./websocket";
 export type * from "./types";

package/src/store.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import type { Env, Input } from "hono/types";
-import type { ClientRateLimitInfo, ConfigType, Store } from "./types";
+import type { ClientRateLimitInfo, ConfigType, Store, WSConfigType } from "./types";
 /**
  * The record that stores information about a client - namely, how many times
  * they have hit the endpoint, and when their hit count resets.
@@ -47,7 +47,7 @@ export declare class MemoryStore<E extends Env = Env, P extends string = string,
      *
      * @param options {ConfigType} - The options used to setup the middleware.
      */
-    init(options: ConfigType<E, P, I>): void;
+    init(options: ConfigType<E, P, I> | WSConfigType<E, P, I>): void;
     /**
      * Method to fetch a client's hit count and reset time.
      *

package/src/types.d.ts

@@ -1,5 +1,6 @@
 import type { Context, Env, Input, Next } from "hono";
 import type { StatusCode } from "hono/utils/http-status";
+import type { WSContext } from "hono/ws";
 /**
  * Data returned from the `Store` when a client's hit counter is incremented.
  *
@@ -40,7 +41,7 @@ export type RateLimitExceededEventHandler<E extends Env = Env, P extends string
 /**
  * The configuration options for the rate limiter.
  */
-export type ConfigType<E extends Env = Env, P extends string = string, I extends Input = Input> = {
+export interface ConfigType<E extends Env = Env, P extends string = string, I extends Input = Input> {
     /**
      * How long we should remember the requests.
      *
@@ -103,8 +104,6 @@ export type ConfigType<E extends Env = Env, P extends string = string, I extends
     skipSuccessfulRequests: boolean;
     /**
      * Method to generate custom identifiers for clients.
-     *
-     * By default, the client's IP address is used.
      */
     keyGenerator: (c: Context<E, P, I>) => Promisify<string>;
     /**
@@ -135,7 +134,48 @@ export type ConfigType<E extends Env = Env, P extends string = string, I extends
      * By default, the built-in `MemoryStore` will be used.
      */
     store: Store<E, P, I>;
-};
+}
+export type WSStatusCode = 1000 | 1001 | 1002 | 1003 | 1004 | 1005 | 1006 | 1007 | 1008 | 1009 | 1010;
+/**
+ * Hono request handler that sends back a response when a client is
+ * rate-limited.
+ *
+ * @param context {Context} - The Hono context object.
+ * @param next {Next} - The Hono `next` function, can be called to skip responding.
+ * @param optionsUsed {ConfigType} - The options used to set up the middleware.
+ */
+export type WSRateLimitExceededEventHandler<E extends Env = Env, P extends string = string, I extends Input = Input> = (event: unknown, ws: WSContext, optionsUsed: WSConfigType<E, P, I>) => void;
+/**
+ * The configuration options for the rate limiter.
+ */
+export interface WSConfigType<E extends Env = Env, P extends string = string, I extends Input = Input> extends Omit<ConfigType<E, P, I>, "statusCode" | "standardHeaders" | "requestWasSuccessful" | "handler" | "skip"> {
+    /**
+     * The response body to send back when a client is rate limited.
+     *
+     * Defaults to `'Too many requests, please try again later.'`
+     */
+    message: string;
+    /**
+     * The ws status code to send back when a client is rate limited.
+     *
+     * Defaults to `HTTP 1008 Terminating The Connection` (RFC 6455).
+     */
+    statusCode: WSStatusCode;
+    /**
+     * Hono ws request handler that sends back a response when a client is
+     * rate-limited.
+     *
+     * By default, sends back the `statusCode` and `message` set via the options.
+     */
+    handler: WSRateLimitExceededEventHandler<E, P, I>;
+    /**
+     * Method (in the form of middleware) to determine whether or not this ws request
+     * counts towards a client's quota.
+     *
+     * By default, skips no requests.
+     */
+    skip: (event: unknown, ws: WSContext) => Promisify<boolean>;
+}
 export type IncrementResponse = ClientRateLimitInfo;
 /**
  * An interface that all hit counter stores must implement.

package/src/websocket.d.ts

@@ -0,0 +1,14 @@
+import type { Context, Env, Input } from "hono";
+import type { WSEvents } from "hono/ws";
+import type { WSConfigType } from "./types";
+/**
+ *
+ * Create an instance of ws based rate-limiting middleware for Hono.
+ *
+ * @param config {WSConfigType} - Options to configure the rate limiter.
+ *
+ * @returns - The middleware that rate-limits clients based on your configuration.
+ *
+ * @public
+ */
+export declare function webSocketLimiter<E extends Env = Env, P extends string = string, I extends Input = Input>(config: Pick<WSConfigType<E, P, I>, "keyGenerator"> & Partial<Omit<WSConfigType<E, P, I>, "keyGenerator">>): Promise<(createEvents: (c: Context<E, P, I>) => WSEvents | Promise<WSEvents>) => (c: Context<E, P, I>) => Promise<WSEvents>>;