@clov-std/elysia-ratelimit 4.0.18 → 5.0.0-rc.1

package/README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/gh/ClovLabs/std@main/packages/elysia-ratelimit/logo-elysia-ratelimit.png" alt="Clov Elysia Rate Limit logo" width="200" />
+  <img src="https://cdn.jsdelivr.net/gh/ClovLabs/std@main/packages/elysia-ratelimit/logo-elysia-ratelimit.svg" alt="Clov Elysia Rate Limit logo" width="200" />
 </p>
 
 # Clov Elysia Rate Limit
 
 Rate limiting for Elysia, as a macro. Put `rateLimit: { limit: 10, window: 60 }` on a route, guard or group and you're done.
 
-It runs in `transform`, the first per-route hook, so excess requests are rejected before auth guards or handlers do any work. Counters are per client IP by default, which suits login endpoints. When lots of users share one IP (an office, a corporate proxy), a `keyGenerator` lets you count per token, session, API key, or whatever fits.
+It runs in `transform`, the first per-route hook, so excess requests are rejected before auth guards or handlers do any work. Counters are per route pattern and client IP by default, which suits login endpoints: `/users/1` and `/users/2` share the quota of `/users/:id`. When lots of users share one IP (an office, a corporate proxy), count per authenticated user instead, with the `derive` hook.
 
 Storage goes through `@clov-std/kv-store`: memory by default, Redis when you need it, same routes either way.
 
@@ -55,34 +55,42 @@ new Elysia()
 
 ### Per user instead of per IP
 
-For authenticated routes behind a shared IP, give each user their own counter:
+A `transform` hook only knows the request. To count per user, run the quota in `derive` (or `beforeHandle`), after the hook that authenticates, and key it on what that hook added. Give the quota its own `policy`, so its counters and headers stay apart from the per-IP one:
 
 ```ts
-import { rateLimitPlugin } from '@clov-std/elysia-ratelimit';
-import { Elysia } from 'elysia';
-
 new Elysia()
 	.use(rateLimitPlugin())
-	.get(
-		'/api/data',
-		{
+	.macro({
+		requireAuth: {
+			derive: async ({ headers }) => ({ idUser: await authenticate(headers) }),
+			// declared after the derive: derives run in declaration order
 			rateLimit: {
-				limit: 100,
+				policy: 'user',
+				hook: 'derive',
+				limit: 300,
 				window: 60,
-				keyGenerator: ({ ip, request }) =>
-					`${ip}:${request.headers.get('authorization') ?? ip}`
+				keyGenerator: ({ idUser }) => idUser
 			}
-		},
-		() => getData()
-	)
+		}
+	})
+	.get('/api/data', { requireAuth: true }, () => getData())
 	.listen(3000);
 ```
 
+Elysia can't type what earlier hooks added, so `keyGenerator` returns `unknown`: anything but a non-empty string throws, so a key read before the hook adding it fails loudly instead of putting every client in one quota. A quota declared at several levels (a guard and its route) counts a request once.
+
 `extractClientIp` is exported if you need it in your own `keyGenerator`.
 
 ## Headers and the 429
 
-Every response gets `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
+Every limited response lists its quotas in the `RateLimit-Policy` and `RateLimit` fields of [draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/), one item per policy:
+
+```http
+RateLimit-Policy: "default";q=10;w=60, "user";q=300;w=60
+RateLimit: "default";r=9;t=60, "user";r=299;t=60
+```
+
+The `429` adds the standard `Retry-After` (RFC 9110), in seconds.
 
 Once the limit is hit, the plugin throws Elysia's `problem()`, so the `429` is a full RFC 9457 document (`application/problem+json`) without any exception class to import:
 
@@ -99,7 +107,7 @@ Once the limit is hit, the plugin throws Elysia's `problem()`, so the `429` is a
 - `title` comes from Elysia, based on the status.
 - `detail` reflects the current counter, so it changes from one 429 to the next.
 
-The headers are set before the throw, so they're still on the `429`. The macro also declares this response for OpenAPI, so typed clients know about it.
+The fields are set before the throw, so they're still on the `429`. The macro also declares this response for OpenAPI, so typed clients know about it.
 
 ## Docs
 

package/dist/index.js

@@ -2,13 +2,12 @@
 // src/rate-limit.ts
 import { MemoryStore } from "@clov-std/kv-store";
 import { Elysia, problem, t } from "elysia";
+import { isIP } from "net";
 var RATE_LIMIT_ERROR_CODES = {
   QUOTA_EXCEEDED: "rate-limit.quota.exceeded"
 };
 var rateLimitResponseSchema = t.Object({
-  type: t.String({
-    description: `Error code. Always \`${RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED}\`.`
-  }),
+  type: t.Literal(RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED, { description: "Error code." }),
   title: t.String({
     description: "Short, human-readable summary of the error."
   }),
@@ -19,39 +18,62 @@ var rateLimitResponseSchema = t.Object({
     description: "Explanation specific to this occurrence, including when to retry."
   })
 });
+var isClientIp = (value) => typeof value === "string" && isIP(value) !== 0 && !value.includes("%");
 var extractClientIp = (request, server) => {
-  const forwarded = request.headers.get("x-forwarded-for");
-  if (forwarded) {
-    const [first] = forwarded.split(",");
-    if (first)
-      return first.trim();
-  }
-  return request.headers.get("x-real-ip") ?? server?.requestIP(request)?.address ?? "127.0.0.1";
+  const forwardedIp = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  if (isClientIp(forwardedIp))
+    return forwardedIp;
+  const realIp = request.headers.get("x-real-ip");
+  return isClientIp(realIp) ? realIp : server?.requestIP(request)?.address ?? "127.0.0.1";
 };
-var rateLimitPlugin = (store = new MemoryStore) => new Elysia({ name: "rateLimitPlugin" }).macro({
-  rateLimit: ({ limit, window, keyGenerator }) => ({
-    response: { 429: rateLimitResponseSchema },
-    transform: async ({ set, request, server }) => {
-      const route = `${request.method}:${new URL(request.url).pathname}`;
-      const ip = extractClientIp(request, server);
-      const discriminator = keyGenerator ? keyGenerator({ request, server, ip }) : ip;
-      const key = `ratelimit:${route}:${discriminator}`;
-      const count = await store.increment(key);
-      if (count === 1)
-        await store.expire(key, window);
-      const remaining = Math.max(0, limit - count);
-      const reset = await store.ttl(key);
-      set.headers["X-RateLimit-Limit"] = limit.toString();
-      set.headers["X-RateLimit-Remaining"] = remaining.toString();
-      set.headers["X-RateLimit-Reset"] = reset.toString();
-      if (count > limit)
-        throw problem({
-          type: RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED,
-          status: 429,
-          detail: `Limit of ${limit} requests per ${window}s exceeded. Retry in ${reset}s.`
-        });
-    }
-  })
+var countedRequests = new WeakMap;
+var appendHeader = (headers, name, item) => {
+  const current = headers[name];
+  headers[name] = typeof current === "string" ? `${current}, ${item}` : item;
+};
+var consumeRateLimit = async (store, { set, request, path, route }, { policy, key, limit, window }) => {
+  const storeKey = `ratelimit:${policy}:${request.method}:${route ?? path}:${key}`;
+  const counted = countedRequests.get(request) ?? new Set;
+  if (counted.has(storeKey))
+    return;
+  countedRequests.set(request, counted.add(storeKey));
+  const count = await store.increment(storeKey);
+  if (count === 1)
+    await store.expire(storeKey, window);
+  const reset = await store.ttl(storeKey);
+  appendHeader(set.headers, "RateLimit-Policy", `"${policy}";q=${limit};w=${window}`);
+  appendHeader(set.headers, "RateLimit", `"${policy}";r=${Math.max(0, limit - count)};t=${reset}`);
+  if (count <= limit)
+    return;
+  set.headers["Retry-After"] = reset.toString();
+  throw problem({
+    type: RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED,
+    status: 429,
+    detail: `Limit of ${limit} requests per ${window}s exceeded. Retry in ${reset}s.`
+  });
+};
+var rateLimitPlugin = (store = new MemoryStore) => new Elysia({ name: "rateLimitPlugin" }).model({ [RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED]: rateLimitResponseSchema }).macro({
+  rateLimit: ({
+    limit,
+    window,
+    policy = "default",
+    hook = "transform",
+    keyGenerator
+  }) => {
+    const count = async (ctx) => {
+      const ip = extractClientIp(ctx.request, ctx.server);
+      const key = keyGenerator ? keyGenerator({ ...ctx, ip }) : ip;
+      if (typeof key !== "string" || key === "")
+        throw new Error(`rateLimit "${policy}": keyGenerator returned no key, is the hook it reads declared before it?`);
+      await consumeRateLimit(store, ctx, { policy, key, limit, window });
+    };
+    const response = { 429: RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED };
+    if (hook === "derive")
+      return { response, derive: count };
+    if (hook === "beforeHandle")
+      return { response, beforeHandle: count };
+    return { response, transform: count };
+  }
 });
 export {
   RATE_LIMIT_ERROR_CODES,

package/dist/rate-limit.d.ts

@@ -4,14 +4,8 @@ import { Elysia, type HTTPHeaders } from 'elysia';
 export declare const RATE_LIMIT_ERROR_CODES: {
     readonly QUOTA_EXCEEDED: 'rate-limit.quota.exceeded';
 };
-/**
- * Shape of the `429` body, an RFC 9457 problem document.
- *
- * `title` is filled by Elysia from the status reason phrase, so the plugin only supplies
- * `type`, `status`, and `detail`.
- */
 declare const rateLimitResponseSchema: import("typebox").TObject<{
-    type: import("typebox").TString;
+    type: import("typebox").TLiteral<"rate-limit.quota.exceeded">;
     title: import("typebox").TString;
     status: import("typebox").TLiteral<429>;
     detail: import("typebox").TString;
@@ -20,32 +14,61 @@ export interface RateLimitKeyContext {
     request: Request;
     server: Server<unknown> | null;
     ip: string;
+    [key: string]: unknown;
 }
 export interface RateLimitMacroOptions {
     limit: number;
     window: number;
-    keyGenerator?: (context: RateLimitKeyContext) => string;
+    /**
+     * Names the quota in the RateLimit fields, and separates its counters from other quotas.
+     * @default 'default'
+     */
+    policy?: string;
+    /**
+     * `transform` counts first, the key only knows the request.
+     * `derive` | `beforeHandle` count later, the key can read what earlier hooks added, like a user.
+     * @default 'transform'
+     */
+    hook?: 'transform' | 'derive' | 'beforeHandle';
+    keyGenerator?: (context: RateLimitKeyContext) => unknown;
 }
-interface RateLimitTransformContext {
+interface RateLimitContext {
     set: {
         headers: HTTPHeaders;
     };
     request: Request;
     server: Server<unknown> | null;
+    path: string;
+    route?: string;
 }
+type RateLimitHook = (context: RateLimitContext) => Promise<void>;
 type RateLimitMacro = (options: RateLimitMacroOptions) => {
     response: {
-        429: typeof rateLimitResponseSchema;
+        429: typeof RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED;
     };
-    transform: (context: RateLimitTransformContext) => Promise<void>;
-};
+} & ({
+    transform: RateLimitHook;
+} | {
+    derive: RateLimitHook;
+} | {
+    beforeHandle: RateLimitHook;
+});
 export declare const extractClientIp: (request: Request, server: Server<unknown> | null) => string;
+/**
+ * Creates the rate limit plugin
+ *
+ * Elysia keeps one definition per plugin name, so every `rateLimitPlugin()` of an app tree
+ * resolves to a single plugin instance — the first one. Pass the store here to change it
+ * for the whole app, a later `rateLimitPlugin(store)` is ignored.
+ */
 export declare const rateLimitPlugin: (store?: KvStore) => Elysia<'rateLimitPlugin', 'local', {
     decorator: {};
     derive: {};
     store: {};
 }, {
-    typebox: {};
+    typebox: {
+        [RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED]: typeof rateLimitResponseSchema;
+    };
     error: [];
 }, {
     schema: {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@clov-std/elysia-ratelimit",
-	"version": "4.0.18",
+	"version": "5.0.0-rc.1",
 	"description": "Rate limiting for Elysia as a route macro, with RFC 9457 429 responses and pluggable storage.",
 	"keywords": [
 		"elysia",
@@ -36,18 +36,18 @@
 		"test": "bun test --pass-with-no-tests --coverage"
 	},
 	"dependencies": {
-		"@clov-std/kv-store": "^2.0.4"
+		"@clov-std/kv-store": "^2.0.5"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.4.2",
-		"oxfmt": "0.72.0",
-		"oxlint": "1.87.0",
+		"oxfmt": "0.74.0",
+		"oxlint": "1.89.0",
 		"oxlint-tsgolint": "7.0.2004",
 		"typescript": "^7.0.2"
 	},
 	"peerDependencies": {
-		"@clov-std/kv-store": "^2.0.4",
-		"elysia": "next",
+		"@clov-std/kv-store": "^2.0.5",
+		"elysia": "rc",
 		"typebox": "^1.3.36"
 	}
 }