@teikyo/rate-limit 0.2.0 → 0.3.1

package/README.md

@@ -30,4 +30,5 @@ Clients are keyed on the IP resolved by the server, so set `trustProxy` when run
 | --- | --- | --- |
 | `windowMs` | `number` | Length of the window in milliseconds. Must be a positive safe integer. |
 | `limit` | `number` | Maximum requests per client within a window. Must be a positive safe integer. |
+| `path` | `string` (optional) | Limit only this path prefix, matched by segment: `/oauth` covers `/oauth` and `/oauth/...` but not `/oauthx`. Other routes stay unlimited. A server runs one rate limit plugin, so a global limit and a scoped one cannot be combined. |
 | `store` | `Store` (optional) | A `hono-rate-limiter` store, in-memory by default. The plugin calls its `shutdown()` when the server closes, so do not pass a store shared with or owned by something else. |

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 import { type HTTPPlugin } from '@sozai/http-server';
+import type { Context } from 'hono';
 import { type Store } from 'hono-rate-limiter';
 export declare const RATE_LIMIT: import("@sozai/http-server").PluginName<"http:rate-limit", void>;
 export type RateLimitPluginParams = {
@@ -6,6 +7,10 @@ export type RateLimitPluginParams = {
     windowMs: number;
     /** Maximum number of requests per client within a window. */
     limit: number;
+    /** Limit only this path prefix, segment-aware: `/oauth` covers `/oauth/...` but not `/oauthx`. */
+    path?: string;
+    /** Bucket by IP (default), principal attribution, or a custom key with nullish IP fallback. */
+    key?: 'ip' | 'principal' | ((c: Context) => string | null | undefined | Promise<string | null | undefined>);
     /**
      * Custom store, defaults to an in-memory store. The plugin calls `shutdown()` on it when
      * the server closes, so do not pass a store shared with or owned by something else.
@@ -13,7 +18,8 @@ export type RateLimitPluginParams = {
     store?: Store;
 };
 /**
- * Rate limit every request by resolved client IP (IPv6 grouped by /64), answering `429` with a
- * `Retry-After` header past the limit. Health routes are never limited.
+ * Rate limit requests by IP, principal attribution, or a custom key, answering `429` with a
+ * `Retry-After` header past the limit. With `path`, only that prefix is limited. Health routes are
+ * never limited.
  */
 export declare function rateLimitPlugin(params: RateLimitPluginParams): HTTPPlugin<'http:rate-limit', void, []>;

package/lib/index.js

@@ -1,4 +1,5 @@
 import { pluginName } from '@sozai/http-server';
+import { attributionOf, getPrincipal } from '@teikyo/principal';
 import { MemoryStore, rateLimiter } from 'hono-rate-limiter';
 import { clientKey } from './key.js';
 export const RATE_LIMIT = pluginName()('http:rate-limit');
@@ -8,12 +9,13 @@ function assertPositiveInteger(name, value) {
     }
 }
 /**
- * Rate limit every request by resolved client IP (IPv6 grouped by /64), answering `429` with a
- * `Retry-After` header past the limit. Health routes are never limited.
+ * Rate limit requests by IP, principal attribution, or a custom key, answering `429` with a
+ * `Retry-After` header past the limit. With `path`, only that prefix is limited. Health routes are
+ * never limited.
  */ export function rateLimitPlugin(params) {
     assertPositiveInteger('windowMs', params.windowMs);
     assertPositiveInteger('limit', params.limit);
-    const { windowMs, limit } = params;
+    const { windowMs, limit, key = 'ip', path } = params;
     return {
         name: RATE_LIMIT,
         dependsOn: [],
@@ -25,9 +27,18 @@ function assertPositiveInteger(name, value) {
                 standardHeaders: 'draft-7',
                 // IPv6 clients share one bucket per /64. A request with no resolvable client IP falls
                 // into one shared bucket.
-                keyGenerator: (c)=>clientKey(ctx.clientIP(c)),
+                keyGenerator: async (c)=>{
+                    if (typeof key === 'function') {
+                        const customKey = await key(c);
+                        if (customKey != null) return customKey;
+                    } else if (key === 'principal') {
+                        const principal = getPrincipal(c);
+                        if (principal != null) return `p:${attributionOf(principal).onBehalfOf}`;
+                    }
+                    return `ip:${clientKey(ctx.clientIP(c))}`;
+                },
                 store
-            }));
+            }), path);
             ctx.onClose(()=>store.shutdown?.());
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teikyo/rate-limit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Rate limiting plugin for Sozai HTTP servers",
   "repository": {
     "type": "git",
@@ -19,17 +19,18 @@
     "lib/*"
   ],
   "dependencies": {
-    "@sozai/http-server": "^0.2.0",
+    "@sozai/http-server": "^0.2.2",
+    "@teikyo/principal": "^0.1.0",
     "hono-rate-limiter": "^0.5.4"
   },
   "devDependencies": {
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "del-cli": "^8.0.1",
-    "hono": "^4.13.13",
-    "vitest": "5.0.5"
+    "hono": "^4.13.18",
+    "vitest": "5.1.0"
   },
   "peerDependencies": {
-    "hono": "^4.13.13"
+    "hono": "^4.13.18"
   },
   "engines": {
     "node": ">=24"