@suluk/cloudflare 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cloudflare",
-  "version": "0.1.0",
+  "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/assets.ts

@@ -33,6 +33,34 @@ export interface UploadSession {
   buckets?: string[][];
 }
 
+/** The result of splitting Workers-Assets rule files out of an asset list. */
+export interface AssetRuleFiles {
+  /** the remaining files to actually upload + serve. */
+  assets: AssetFile[];
+  /** raw `_headers` file contents, if present — passed in the worker metadata's assets.config, NOT uploaded. */
+  _headers?: string;
+  /** raw `_redirects` file contents, if present. */
+  _redirects?: string;
+}
+
+/**
+ * Pull `_headers` / `_redirects` OUT of an asset list. Cloudflare Workers Static Assets does NOT serve these as files
+ * — it parses their raw text (sent in the worker metadata's `assets.config._headers` / `._redirects`) into the
+ * header/redirect rules the asset runtime applies. So they must be EXCLUDED from the upload manifest (else they'd
+ * serve as public 200 blobs and the rules would never activate) and their contents routed to the config instead.
+ * This mirrors exactly what wrangler does (excludes the two files, forwards their contents in the config).
+ */
+export function extractAssetRuleFiles(files: AssetFile[]): AssetRuleFiles {
+  const out: AssetRuleFiles = { assets: [] };
+  const dec = new TextDecoder();
+  for (const f of files) {
+    if (f.path === "/_headers") out._headers = dec.decode(f.bytes as unknown as Uint8Array);
+    else if (f.path === "/_redirects") out._redirects = dec.decode(f.bytes as unknown as Uint8Array);
+    else out.assets.push(f);
+  }
+  return out;
+}
+
 /**
  * Upload a set of static assets; returns the completion JWT for the worker metadata, or `null` when there are none.
  * When every file is already cached server-side the session returns no buckets and its own jwt IS the completion token.

package/src/deploy.ts

@@ -6,7 +6,7 @@
  */
 import { CloudflareClient, type CloudflareClientOptions } from "./client";
 import { provisionD1, provisionKvNamespace, provisionR2Bucket, applyMigrations, putSecrets, type Migration } from "./resources";
-import { uploadAssets, type AssetFile } from "./assets";
+import { uploadAssets, extractAssetRuleFiles, type AssetFile } from "./assets";
 import { deployWorker, putCronTriggers, type WorkerBinding } from "./worker";
 
 export interface DeployPlan {
@@ -73,13 +73,29 @@ export async function deploy(cf: CloudflareClient, plan: DeployPlan, log: Deploy
   for (const b of plan.r2 ?? []) { const bk = await provisionR2Bucket(cf, b.bucketName); bindings.push({ type: "r2_bucket", name: b.binding, bucket_name: bk.name }); r2.push({ binding: b.binding, name: bk.name }); log(`R2 "${bk.name}" bound`); }
 
   let assetsJwt: string | null = null;
-  if (plan.assets?.length) { assetsJwt = await uploadAssets(cf, plan.scriptName, plan.assets); log(`assets: ${plan.assets.length} files uploaded`); }
+  let assetsConfig = plan.assetsConfig;
+  let assetsUploaded = 0;
+  if (plan.assets?.length) {
+    // `_headers`/`_redirects` are NOT uploaded as files — their raw text rides in assets.config and Cloudflare parses
+    // them server-side into header/redirect rules (the asset runtime then applies them). Excluding them from the
+    // manifest is load-bearing: an uploaded /_headers would serve as a public 200 blob AND never activate as rules.
+    const { assets, _headers, _redirects } = extractAssetRuleFiles(plan.assets);
+    if (_headers != null || _redirects != null) {
+      assetsConfig = { ...assetsConfig, ...(_headers != null ? { _headers } : {}), ...(_redirects != null ? { _redirects } : {}) };
+    }
+    assetsUploaded = assets.length;
+    if (assets.length) {
+      assetsJwt = await uploadAssets(cf, plan.scriptName, assets);
+      const rules = [_headers != null ? "_headers" : "", _redirects != null ? "_redirects" : ""].filter(Boolean).join("+");
+      log(`assets: ${assets.length} files uploaded${rules ? ` (${rules} → config rules)` : ""}`);
+    }
+  }
 
   await deployWorker(cf, {
     name: plan.scriptName, module: plan.module, mainModule: plan.mainModule,
     compatibilityDate: plan.compatibilityDate, compatibilityFlags: plan.compatibilityFlags,
     bindings, vars: plan.vars,
-    assets: { jwt: assetsJwt, binding: plan.assetsBinding, config: plan.assetsConfig },
+    assets: { jwt: assetsJwt, binding: plan.assetsBinding, config: assetsConfig },
     observability: plan.observability,
   });
   log(`worker "${plan.scriptName}" deployed`);
@@ -89,7 +105,7 @@ export async function deploy(cf: CloudflareClient, plan: DeployPlan, log: Deploy
 
   if (plan.crons?.length) { await putCronTriggers(cf, plan.scriptName, plan.crons); log(`crons: ${plan.crons.join(" · ")}`); }
 
-  return { accountId, scriptName: plan.scriptName, d1, kv, r2, assetsUploaded: plan.assets?.length ?? 0, secretsSet, crons: plan.crons ?? [] };
+  return { accountId, scriptName: plan.scriptName, d1, kv, r2, assetsUploaded, secretsSet, crons: plan.crons ?? [] };
 }
 
 /** Convenience: build a client from token/account options and run a deploy. */

package/src/index.ts

@@ -6,6 +6,8 @@
  */
 export { CloudflareClient, CloudflareError, type CloudflareClientOptions, type RequestOptions } from "./client";
 export { provisionD1, queryD1, applyMigrations, provisionKvNamespace, provisionR2Bucket, putSecret, putSecrets, type D1Database, type KvNamespace, type Migration } from "./resources";
-export { uploadAssets, assetHash, type AssetFile, type UploadSession } from "./assets";
+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/cloudflare.test.ts

@@ -132,4 +132,33 @@ describe("deploy() — full orchestration in dependency order", () => {
     expect(idx(/POST .*\/d1\/database\/db_1\/query/)).toBeLessThan(idx(/PUT .*\/workers\/scripts\/saasuluk$/));
     expect(idx(/PUT .*\/workers\/scripts\/saasuluk$/)).toBeLessThan(idx(/\/secrets$/));
   });
+
+  test("routes _headers/_redirects into assets.config and EXCLUDES them from the upload manifest", async () => {
+    const { fetch, calls } = mockCf([
+      [/GET \/accounts$/, [{ id: "acct_1" }]],
+      [/POST .*\/assets-upload-session$/, { jwt: "session_jwt", buckets: [] }],
+      [/PUT .*\/workers\/scripts\/saasuluk$/, { id: "saasuluk" }],
+    ]);
+    const cf = new CloudflareClient({ apiToken: "t", fetch });
+    const assets: AssetFile[] = [
+      { path: "/_headers", bytes: new TextEncoder().encode("/_astro/*\n  Cache-Control: public, max-age=31536000, immutable\n"), contentType: "application/octet-stream" },
+      { path: "/_redirects", bytes: new TextEncoder().encode("/old /new 301\n"), contentType: "application/octet-stream" },
+      { path: "/index.html", bytes: new TextEncoder().encode("<!doctype html>"), contentType: "text/html" },
+    ];
+    const res = await deploy(cf, { scriptName: "saasuluk", module: "m", compatibilityDate: "2026-06-01", assets, assetsConfig: { html_handling: "auto-trailing-slash" } });
+
+    expect(res.assetsUploaded).toBe(1); // only /index.html — the two rule files are NOT uploaded
+
+    // the upload-session manifest must contain ONLY /index.html (rule files excluded so they never serve as blobs)
+    const session = calls.find((c) => /assets-upload-session$/.test(c.path))!;
+    const manifest = JSON.parse(session.body as string).manifest;
+    expect(Object.keys(manifest)).toEqual(["/index.html"]);
+
+    // the worker metadata carried the raw rule-file contents in assets.config, alongside html_handling
+    const put = calls.find((c) => c.method === "PUT" && /\/workers\/scripts\/saasuluk$/.test(c.path))!;
+    const meta = JSON.parse(await (put.body as FormData).get("metadata")!.text());
+    expect(meta.assets.config.html_handling).toBe("auto-trailing-slash");
+    expect(meta.assets.config._headers).toContain("immutable");
+    expect(meta.assets.config._redirects).toContain("/old /new 301");
+  });
 });

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
+  });
+});