@mezzanine-stack/ratelimit-kv 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @mezzanine-stack/ratelimit-kv
+
+Cloudflare KV を使う `RateLimitAdapter` の実装。2 窓（1 分 / 10 分）のレート制限を IP ベースで行います。
+
+## 使い方
+
+```typescript
+import { KvRateLimitAdapter } from "@mezzanine-stack/ratelimit-kv";
+
+const limiter = new KvRateLimitAdapter({
+  kv: env.RATE_LIMIT_KV,      // KVNamespace binding
+  perMinute: 5,
+  per10Minutes: 20,
+});
+
+const result = await limiter.check(ip, ua);
+if (!result.allowed) {
+  // result.retryAfterSeconds には推奨待機秒数が入る
+}
+```
+
+## 戻り値 (`RateLimitResult`)
+
+| フィールド | 型 | 説明 |
+|---|---|---|
+| `allowed` | `boolean` | リクエストを許可するか |
+| `retryAfterSeconds` | `number?` | 超過した窓に応じた待機秒数 (60 または 600) |
+
+## KV binding のセットアップ
+
+`wrangler.toml` に KV namespace を設定します:
+
+```toml
+[[kv_namespaces]]
+binding = "RATE_LIMIT_KV"
+id = "YOUR_KV_NAMESPACE_ID"
+```
+
+KV namespace の作成:
+```bash
+wrangler kv namespace create "RATE_LIMIT_KV"
+```
+
+## 設計上の注意
+
+- Cloudflare KV は **eventually consistent** です。高トラフィック下では複数 edge に同時にリクエストが届くと、カウントが若干低く見積もられる場合があります。これはベストエフォートの防御として許容しています。
+- キーは `rl:{ip}:{ua_hash}:m:{bucket}` / `rl:{ip}:{ua_hash}:t:{bucket}` 形式。UA ハッシュで NAT 背後の複数ユーザーを軽く識別します。
+- TTL は 1 分窓 90 秒、10 分窓 700 秒で設定され、古いエントリは自動削除されます。
+
+## 環境変数 (wrangler.toml)
+
+| 変数名 | デフォルト | 説明 |
+|---|---|---|
+| `RATE_PER_MINUTE` | `5` | 1 分あたり上限リクエスト数 |
+| `RATE_PER_10_MINUTES` | `20` | 10 分あたり上限リクエスト数 |

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mezzanine-stack/ratelimit-kv",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@mezzanine-stack/contact-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260312.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from "vitest";
+import { KvRateLimitAdapter } from "./index.js";
+
+function createMockKv(initial: Record<string, string> = {}) {
+  const store = new Map(Object.entries(initial));
+  return {
+    store,
+    kv: {
+      get: vi.fn(async (key: string) => store.get(key) ?? null),
+      put: vi.fn(async (key: string, value: string) => {
+        store.set(key, value);
+      }),
+    } as unknown as KVNamespace,
+  };
+}
+
+describe("KvRateLimitAdapter", () => {
+  it("allows first request and blocks second when perMinute is 1", async () => {
+    const nowSpy = vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    const { kv } = createMockKv();
+    const adapter = new KvRateLimitAdapter({ kv, perMinute: 1, per10Minutes: 10 });
+
+    const first = await adapter.check("203.0.113.1", "ua");
+    const second = await adapter.check("203.0.113.1", "ua");
+
+    expect(first).toEqual({ allowed: true });
+    expect(second).toEqual({ allowed: false, retryAfterSeconds: 60 });
+    nowSpy.mockRestore();
+  });
+
+  it("clamps perMinute lower bound to 1", async () => {
+    const nowSpy = vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    const { kv } = createMockKv();
+    const adapter = new KvRateLimitAdapter({ kv, perMinute: 0, per10Minutes: 10 });
+
+    const first = await adapter.check("203.0.113.2", "ua");
+    const second = await adapter.check("203.0.113.2", "ua");
+
+    expect(first.allowed).toBe(true);
+    expect(second.allowed).toBe(false);
+    nowSpy.mockRestore();
+  });
+});
+

package/src/index.ts

@@ -0,0 +1,78 @@
+import type { RateLimitAdapter, RateLimitResult } from "@mezzanine-stack/contact-core";
+
+export interface KvRateLimitAdapterOptions {
+  kv: KVNamespace;
+  /** Max requests per minute per IP. Default: 5 */
+  perMinute?: number;
+  /** Max requests per 10 minutes per IP. Default: 20 */
+  per10Minutes?: number;
+}
+
+/**
+ * Two-window rate limiter backed by Cloudflare KV.
+ *
+ * Uses a cheap FNV-1a hash of the User-Agent to slightly differentiate NAT peers
+ * sharing the same IP address.
+ *
+ * Note: Cloudflare KV has eventual consistency. Under very high concurrency,
+ * the count may be slightly under-counted. This is an accepted trade-off for the
+ * low cost and operational simplicity — the rate limiter is a best-effort defence,
+ * not a strict quota system.
+ */
+export class KvRateLimitAdapter implements RateLimitAdapter {
+  readonly #kv: KVNamespace;
+  readonly #perMinute: number;
+  readonly #per10: number;
+
+  constructor(options: KvRateLimitAdapterOptions) {
+    this.#kv = options.kv;
+    this.#perMinute = clamp(options.perMinute ?? 5, 1, 60);
+    this.#per10 = clamp(options.per10Minutes ?? 20, 1, 300);
+  }
+
+  async check(ip: string, ua: string): Promise<RateLimitResult> {
+    const now = Date.now();
+    const mBucket = Math.floor(now / 60_000);
+    const tBucket = Math.floor(now / 600_000);
+    const uaKey = simpleHash(ua).slice(0, 8);
+
+    const k1 = `rl:${ip}:${uaKey}:m:${mBucket}`;
+    const k2 = `rl:${ip}:${uaKey}:t:${tBucket}`;
+
+    const [c1, c2] = await Promise.all([getCount(this.#kv, k1), getCount(this.#kv, k2)]);
+
+    if (c1 >= this.#perMinute) {
+      return { allowed: false, retryAfterSeconds: 60 };
+    }
+    if (c2 >= this.#per10) {
+      return { allowed: false, retryAfterSeconds: 600 };
+    }
+
+    await Promise.all([
+      this.#kv.put(k1, String(c1 + 1), { expirationTtl: 90 }),
+      this.#kv.put(k2, String(c2 + 1), { expirationTtl: 700 }),
+    ]);
+
+    return { allowed: true };
+  }
+}
+
+async function getCount(kv: KVNamespace, key: string): Promise<number> {
+  const v = await kv.get(key);
+  const n = Number(v ?? "0");
+  return Number.isFinite(n) ? n : 0;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/** FNV-1a 32-bit hash (non-cryptographic, cheap key stabilizer). */
+function simpleHash(s: string): string {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});
+