@teikyo/rate-limit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @teikyo/rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rate limiting plugin for `@sozai/http-server`. It limits every request per resolved client IP, answering `429` with a `Retry-After` header past the limit. Routes registered by plugins listed before it are limited too; health routes never are.
+
+## Install
+
+```sh
+pnpm add @teikyo/rate-limit @sozai/http-server hono
+```
+
+## Usage
+
+Plugin name: `http:rate-limit` (exported as `RATE_LIMIT`).
+
+```ts
+import { createServer } from '@sozai/http-server'
+import { rateLimitPlugin } from '@teikyo/rate-limit'
+
+const server = await createServer({
+  trustProxy: 1,
+  plugins: [rateLimitPlugin({ windowMs: 60_000, limit: 100 })],
+})
+```
+
+Clients are keyed on the IP resolved by the server, so set `trustProxy` when running behind a reverse proxy. An IPv4 address is keyed whole; an IPv6 address is keyed by its /64 prefix, the usual allocation to one subscriber, so a client cannot multiply its budget by rotating addresses within its prefix. IPv4-mapped IPv6 (`::ffff:a.b.c.d`) is keyed as IPv4. Responses carry the IETF `RateLimit` draft-7 headers.
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `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. |
+| `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

@@ -0,0 +1,19 @@
+import { type HTTPPlugin } from '@sozai/http-server';
+import { type Store } from 'hono-rate-limiter';
+export declare const RATE_LIMIT: import("@sozai/http-server").PluginName<"http:rate-limit", void>;
+export type RateLimitPluginParams = {
+    /** Length of the rate limiting window, in milliseconds. */
+    windowMs: number;
+    /** Maximum number of requests per client within a window. */
+    limit: number;
+    /**
+     * 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.
+     */
+    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.
+ */
+export declare function rateLimitPlugin(params: RateLimitPluginParams): HTTPPlugin<'http:rate-limit', void, []>;

package/lib/index.js

@@ -0,0 +1,34 @@
+import { pluginName } from '@sozai/http-server';
+import { MemoryStore, rateLimiter } from 'hono-rate-limiter';
+import { clientKey } from './key.js';
+export const RATE_LIMIT = pluginName()('http:rate-limit');
+function assertPositiveInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive safe integer, received ${String(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.
+ */ export function rateLimitPlugin(params) {
+    assertPositiveInteger('windowMs', params.windowMs);
+    assertPositiveInteger('limit', params.limit);
+    const { windowMs, limit } = params;
+    return {
+        name: RATE_LIMIT,
+        dependsOn: [],
+        setup (ctx) {
+            const store = params.store ?? new MemoryStore();
+            ctx.middleware(rateLimiter({
+                windowMs,
+                limit,
+                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)),
+                store
+            }));
+            ctx.onClose(()=>store.shutdown?.());
+        }
+    };
+}

package/lib/key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rate-limit key for a client address. IPv4 is kept whole and IPv6 is grouped by its /64, the
+ * usual allocation to one subscriber, so a client cannot multiply its budget by rotating through
+ * addresses in its own prefix. IPv4-mapped IPv6 (`::ffff:a.b.c.d`) is keyed as IPv4. Anything else
+ * (no resolvable address) is returned unchanged.
+ */
+export declare function clientKey(ip: string): string;

package/lib/key.js

@@ -0,0 +1,47 @@
+function parseGroups(part) {
+    return part === '' ? [] : part.split(':').map((group)=>Number.parseInt(group, 16));
+}
+/**
+ * Expand an IPv6 address into its eight 16-bit groups, or return `undefined` when it is not one.
+ * The WHATWG URL parser validates it and rewrites any dotted IPv4 tail as two hex groups.
+ */ function ipv6Groups(address) {
+    const zoneIndex = address.indexOf('%');
+    let canonical;
+    try {
+        const host = zoneIndex === -1 ? address : address.slice(0, zoneIndex);
+        canonical = new URL(`http://[${host}]`).hostname.slice(1, -1);
+    } catch  {
+        return undefined;
+    }
+    const [head = '', tail] = canonical.split('::');
+    if (tail == null) return parseGroups(head);
+    const headGroups = parseGroups(head);
+    const tailGroups = parseGroups(tail);
+    const zeros = new Array(8 - headGroups.length - tailGroups.length).fill(0);
+    return [
+        ...headGroups,
+        ...zeros,
+        ...tailGroups
+    ];
+}
+/**
+ * Rate-limit key for a client address. IPv4 is kept whole and IPv6 is grouped by its /64, the
+ * usual allocation to one subscriber, so a client cannot multiply its budget by rotating through
+ * addresses in its own prefix. IPv4-mapped IPv6 (`::ffff:a.b.c.d`) is keyed as IPv4. Anything else
+ * (no resolvable address) is returned unchanged.
+ */ export function clientKey(ip) {
+    if (!ip.includes(':')) return ip;
+    const groups = ipv6Groups(ip);
+    if (groups == null) return ip;
+    if (groups.slice(0, 5).every((group)=>group === 0) && groups[5] === 0xffff) {
+        const high = groups[6] ?? 0;
+        const low = groups[7] ?? 0;
+        return [
+            high >> 8,
+            high & 0xff,
+            low >> 8,
+            low & 0xff
+        ].join('.');
+    }
+    return `${groups.slice(0, 4).map((group)=>group.toString(16)).join(':')}::/64`;
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@teikyo/rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Rate limiting plugin for Sozai HTTP servers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/teikyo.git",
+    "directory": "packages/rate-limit"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@sozai/http-server": "^0.1.0",
+    "hono-rate-limiter": "^0.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "hono": "^4.13.13",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.13"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }