@suluk/cloudflare 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cloudflare",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Butter-smooth, API-driven provisioning + deployment for a Suluk app on Cloudflare — no wrangler CLI. A typed REST client + idempotent provisioners (D1, KV, R2, secrets) + the Workers module-script + static-assets upload flow, orchestrated into one deploy(). The platform that ships itself, shipping itself. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"

package/src/index.ts

@@ -9,3 +9,5 @@ export { provisionD1, queryD1, applyMigrations, provisionKvNamespace, provisionR
 export { uploadAssets, assetHash, extractAssetRuleFiles, type AssetFile, type UploadSession, type AssetRuleFiles } from "./assets";
 export { deployWorker, putCronTriggers, type DeployWorkerOptions, type WorkerBinding } from "./worker";
 export { deploy, deployWith, type DeployPlan, type DeployResult, type DeployLog } from "./deploy";
+// the production KV-backed RateLimitStore for @suluk/hono's enforceRateLimit (MemoryRateLimitStore is dev-only).
+export { kvRateLimitStore, memoryRateLimitStore, type RateLimitStore, type ConsumeOptions, type ConsumeResult, type KvLike } from "./ratelimit";

package/src/ratelimit.ts

@@ -0,0 +1,55 @@
+/**
+ * A KV-backed RateLimitStore — the production durable counter @suluk/hono's `enforceRateLimit` needs (its
+ * MemoryRateLimitStore is DEV-only; it doesn't coordinate across Workers isolates). Fixed-window counter in a
+ * Workers KV namespace, fail-OPEN to a fallback store on any KV blip so a KV outage never hard-blocks traffic.
+ *
+ * Structurally typed (no @suluk/hono dependency — the consume contract is tiny + stable), so the returned store
+ * plugs straight into enforceRateLimit({ store }). The KV binding is resolved LAZILY (a getter) because on Workers
+ * the binding isn't available at module-init — capture it on first request.
+ */
+
+export interface ConsumeOptions { maxRequests: number; windowMs: number; now: number }
+export interface ConsumeResult { limited: boolean; remaining: number; retryAfterMs: number }
+/** Matches @suluk/hono's RateLimitStore (structural — satisfies enforceRateLimit's `store` without a package dep). */
+export interface RateLimitStore { consume(key: string, opts: ConsumeOptions): Promise<ConsumeResult> }
+/** The slice of the Workers KV API this needs (get/put with TTL). */
+export interface KvLike { get(key: string): Promise<string | null>; put(key: string, value: string, opts?: { expirationTtl?: number }): Promise<void> }
+
+/** A per-instance in-memory fixed-window store — the fail-open fallback (DEV only / KV-blip; not cross-isolate). */
+export function memoryRateLimitStore(): RateLimitStore {
+  const m = new Map<string, { count: number; resetAt: number }>();
+  return {
+    async consume(key, o) {
+      let e = m.get(key);
+      if (!e || o.now > e.resetAt) e = { count: 1, resetAt: o.now + o.windowMs };
+      else e.count++;
+      m.set(key, e);
+      const limited = e.count > o.maxRequests;
+      return { limited, remaining: Math.max(0, o.maxRequests - e.count), retryAfterMs: limited ? o.windowMs : 0 };
+    },
+  };
+}
+
+/**
+ * Build a KV-backed RateLimitStore. `kv` is the namespace, or a getter (lazy — capture the binding on first request).
+ * Falls open to `opts.fallback` (default a per-instance memory store) when KV is absent or errors.
+ */
+export function kvRateLimitStore(kv: KvLike | undefined | (() => KvLike | undefined), opts: { fallback?: RateLimitStore } = {}): RateLimitStore {
+  const getKv = typeof kv === "function" ? kv : () => kv;
+  const fallback = opts.fallback ?? memoryRateLimitStore();
+  return {
+    async consume(key, o) {
+      const k = getKv();
+      if (!k) return fallback.consume(key, o);
+      try {
+        const raw = await k.get(key);
+        let e = raw ? (JSON.parse(raw) as { count: number; resetAt: number }) : null;
+        if (!e || o.now > e.resetAt) e = { count: 1, resetAt: o.now + o.windowMs };
+        else e.count++;
+        const limited = e.count > o.maxRequests;
+        await k.put(key, JSON.stringify(e), { expirationTtl: Math.max(60, Math.ceil(o.windowMs / 1000) + 5) });
+        return { limited, remaining: Math.max(0, o.maxRequests - e.count), retryAfterMs: limited ? o.windowMs : 0 };
+      } catch { return fallback.consume(key, o); } // KV blip → fail open
+    },
+  };
+}

package/test/ratelimit.test.ts

@@ -0,0 +1,57 @@
+/**
+ * kvRateLimitStore — the production KV-backed RateLimitStore. Fixed-window counting, window reset, lazy KV getter,
+ * and fail-open to the fallback on a missing binding / KV error.
+ */
+import { test, expect, describe } from "bun:test";
+import { kvRateLimitStore, memoryRateLimitStore, type KvLike } from "../src/index";
+
+function mockKv(): KvLike & { map: Map<string, string> } {
+  const map = new Map<string, string>();
+  return { map, async get(k) { return map.get(k) ?? null; }, async put(k, v) { map.set(k, v); } };
+}
+
+describe("kvRateLimitStore", () => {
+  test("counts within a fixed window and limits past maxRequests", async () => {
+    const s = kvRateLimitStore(mockKv());
+    const o = { maxRequests: 3, windowMs: 60000, now: 1000 };
+    expect((await s.consume("ip", o)).limited).toBe(false); // 1
+    expect((await s.consume("ip", o)).limited).toBe(false); // 2
+    const third = await s.consume("ip", o); // 3
+    expect(third.limited).toBe(false);
+    expect(third.remaining).toBe(0);
+    const fourth = await s.consume("ip", o); // 4 → over
+    expect(fourth.limited).toBe(true);
+    expect(fourth.retryAfterMs).toBe(60000);
+  });
+
+  test("resets after the window elapses (now > resetAt)", async () => {
+    const s = kvRateLimitStore(mockKv());
+    await s.consume("ip", { maxRequests: 1, windowMs: 1000, now: 1000 });
+    expect((await s.consume("ip", { maxRequests: 1, windowMs: 1000, now: 1500 })).limited).toBe(true); // same window
+    expect((await s.consume("ip", { maxRequests: 1, windowMs: 1000, now: 3000 })).limited).toBe(false); // new window
+  });
+
+  test("separate keys are independent", async () => {
+    const s = kvRateLimitStore(mockKv());
+    const o = { maxRequests: 1, windowMs: 60000, now: 1000 };
+    expect((await s.consume("a", o)).limited).toBe(false);
+    expect((await s.consume("b", o)).limited).toBe(false); // b's own bucket
+    expect((await s.consume("a", o)).limited).toBe(true);
+  });
+
+  test("lazy getter: no binding yet → falls open to the fallback, then uses KV once present", async () => {
+    let kv: KvLike | undefined;
+    const fallback = memoryRateLimitStore();
+    const s = kvRateLimitStore(() => kv, { fallback });
+    const o = { maxRequests: 100, windowMs: 60000, now: 1000 };
+    expect((await s.consume("ip", o)).limited).toBe(false); // via fallback (kv undefined)
+    kv = mockKv(); // binding captured on a later request
+    expect((await s.consume("ip", o)).remaining).toBe(99); // now via KV (fresh count)
+  });
+
+  test("KV error fails OPEN to the fallback (never hard-blocks)", async () => {
+    const throwingKv: KvLike = { async get() { throw new Error("kv down"); }, async put() { throw new Error("kv down"); } };
+    const s = kvRateLimitStore(throwingKv);
+    expect((await s.consume("ip", { maxRequests: 1, windowMs: 60000, now: 1000 })).limited).toBe(false); // fell open
+  });
+});