@sproutboat/wire 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @sproutboat/wire
 
+## 0.9.0
+
+### Minor Changes
+
+- 4a7fe62: Cache API: `caches.default` / `caches.open(name)` (baronunread/sproutboat#59), with `match()`/`put()`/`delete()` backed by both transports (broker's `cache.*` ops and the standalone embedded transport, so behavior matches whichever way the app deploys). Keyed on method+URL for v1 (no `Vary` support yet). `put()` throws for a non-GET request, matching the spec; a 206 status or an explicit `no-store`/`private` `Cache-Control` is a silent no-op rather than an error, matching Workers' own `caches.default`. TTL derives from `s-maxage` (preferred) or `max-age`; entries with neither have no expiry.
+  
+  Deliberately synchronous, not Promise-returning: every other buffered-body method this runtime already ships (`text()`/`json()`/`arrayBuffer()`/`blob()`/`formData()`) is sync too, and this runtime's own coroutine machinery has a known, still-open memory-corruption issue tied specifically to nested `async function` calls accumulating across many requests (baronunread/sproutboat#168) — no reason to add more async surface here. `await caches.default.match(...)` still reads correctly: awaiting a non-promise value resolves to it immediately.
+
+### Patch Changes
+
+- Updated dependencies [6145afe]
+  - @sproutboat/assets@0.3.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 7287d9b: KV: native key expiration (baronunread/sproutboat#58). `env.KV.put(key, value, { expirationTtl })` / `{ expiration }` now match the Cloudflare Workers contract: `expirationTtl` is seconds from now (rejected below 60, matching CF), `expiration` is an absolute unix-seconds timestamp. An expired key reads as absent from `get()` and is omitted from `list()`; the row is hard-deleted lazily the next time it's touched by a get. No new transport op — both `expirationTtl` and `expiration` are optional fields on the existing `kv.put` frame, so an older broker/prelude pair that ignores them keeps working exactly as before.
+
 ## 0.7.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@sproutboat/assets": "^0.2.0"
+    "@sproutboat/assets": "^0.3.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/broker.test.ts

@@ -50,11 +50,87 @@ test("KV put / get / list / delete, scoped to a bound namespace", async () => {
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toMatchObject({ found: false });
 });
 
+test("KV expirationTtl under 60 seconds is rejected, matching CF", async () => {
+  const b = make({ bindings: { kv: ["CACHE"] } });
+  await expect(b.dispatch({ op: "kv.put", ns: "CACHE", key: "k", value: "v", expirationTtl: 59 })).rejects.toThrow(
+    "at least 60 seconds",
+  );
+});
+
+test("a key past its expiration reads as absent and is omitted from list", async () => {
+  const b = make({ bindings: { kv: ["CACHE"] } });
+  const past = Math.floor((Date.now() - 1000) / 1000);
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "expired", value: "v", expiration: past });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "fresh", value: "v", expirationTtl: 3600 });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "expired" })).toEqual({
+    ok: true,
+    found: false,
+    value: null,
+  });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "" })).toEqual({ ok: true, keys: ["fresh"] });
+});
+
 test("an unbound KV namespace is rejected", async () => {
   const b = make({ bindings: { kv: ["CACHE"] } });
   await expect(b.dispatch({ op: "kv.put", ns: "OTHER", key: "k", value: "v" })).rejects.toThrow("not bound");
 });
 
+test("cache.match on an empty cache is a plain miss", async () => {
+  const b = make();
+  expect(await b.dispatch({ op: "cache.match", key: "GET https://example.com/a" })).toEqual({
+    ok: true,
+    found: false,
+  });
+});
+
+test("cache: put then match round-trips status/headers/body, deletes work, ambient (no binding needed)", async () => {
+  const b = make();
+  const key = "GET https://example.com/a";
+  expect(
+    await b.dispatch({ op: "cache.put", key, status: 200, headers: { "content-type": "text/plain" }, body: "hi" }),
+  ).toEqual({ ok: true, stored: true });
+  expect(await b.dispatch({ op: "cache.match", key })).toEqual({
+    ok: true,
+    found: true,
+    status: 200,
+    headers: { "content-type": "text/plain" },
+    body: "hi",
+  });
+  expect(await b.dispatch({ op: "cache.delete", key })).toEqual({ ok: true, deleted: true });
+  expect(await b.dispatch({ op: "cache.match", key })).toEqual({ ok: true, found: false });
+  expect(await b.dispatch({ op: "cache.delete", key })).toEqual({ ok: true, deleted: false });
+});
+
+test("cache.put skips storage (silently) for a 206, no-store, or private response", async () => {
+  const b = make();
+  await b.dispatch({ op: "cache.put", key: "k1", status: 206, body: "partial" });
+  await b.dispatch({ op: "cache.put", key: "k2", status: 200, headers: { "cache-control": "no-store" }, body: "x" });
+  await b.dispatch({ op: "cache.put", key: "k3", status: 200, headers: { "cache-control": "private" }, body: "x" });
+  expect(await b.dispatch({ op: "cache.match", key: "k1" })).toEqual({ ok: true, found: false });
+  expect(await b.dispatch({ op: "cache.match", key: "k2" })).toEqual({ ok: true, found: false });
+  expect(await b.dispatch({ op: "cache.match", key: "k3" })).toEqual({ ok: true, found: false });
+});
+
+test("cache.put derives TTL from s-maxage over max-age; an expired entry reads as a miss", async () => {
+  const b = make();
+  await b.dispatch({
+    op: "cache.put",
+    key: "k",
+    status: 200,
+    headers: { "cache-control": "max-age=3600, s-maxage=0" },
+    body: "x",
+  });
+  // s-maxage=0 wins over max-age=3600 -> expires immediately.
+  expect(await b.dispatch({ op: "cache.match", key: "k" })).toEqual({ ok: true, found: false });
+});
+
+test("cache namespaces (caches.open) don't collide on the same key", async () => {
+  const b = make();
+  await b.dispatch({ op: "cache.put", name: "images", key: "k", status: 200, body: "img" });
+  expect(await b.dispatch({ op: "cache.match", name: "images", key: "k" })).toMatchObject({ found: true, body: "img" });
+  expect(await b.dispatch({ op: "cache.match", key: "k" })).toEqual({ ok: true, found: false });
+});
+
 test("secrets resolve only when both bound and present", async () => {
   const b = make({ bindings: { secrets: ["API_KEY", "MISSING"] }, secrets: { API_KEY: "s3cr3t" } });
   expect(await b.dispatch({ op: "secret.get", name: "API_KEY" })).toEqual({ ok: true, value: "s3cr3t" });

package/src/broker.ts

@@ -264,8 +264,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     conn.exec("PRAGMA journal_mode = WAL");
     conn.exec("PRAGMA synchronous = NORMAL");
     conn.exec(
-      "CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))",
+      "CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, " +
+        "expires_at INTEGER, PRIMARY KEY (ns, key))",
     );
+    const kvColumns = conn.query<{ name: string }, []>("PRAGMA table_info(kv)").all();
+    if (!kvColumns.some((column) => column.name === "expires_at")) conn.exec("ALTER TABLE kv ADD COLUMN expires_at INTEGER");
     // #56 — no `body` column: an object's bytes live in their own file under
     // `r2Dir` (or an in-memory map for `:memory:`), never in the SQLite row.
     // Doubling every object through SQLite's own page cache on top of the
@@ -329,6 +332,14 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "CREATE TABLE IF NOT EXISTS ratelimit (name TEXT NOT NULL, key TEXT NOT NULL, window_start INTEGER NOT NULL, " +
       "count INTEGER NOT NULL, PRIMARY KEY (name, key))",
   );
+  // #59 — caches.default: ambient, not a resource a project binds (no config
+  // key), so it lives in the per-deployment db like do_storage/ae rather than
+  // going through the account-level resource registry. Key on method+URL for
+  // v1, per the issue's own scoped-down ask; no Vary support yet.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS cache (name TEXT NOT NULL, cache_key TEXT NOT NULL, status INTEGER NOT NULL, " +
+      "headers_json TEXT NOT NULL, body TEXT NOT NULL, expires_at INTEGER, PRIMARY KEY (name, cache_key))",
+  );
 
   // #74 — one SQLite file per account-level resource id, opened on first use.
   const resourceDbs = new Map<string, Database>();
@@ -470,29 +481,48 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   };
 
   type KvStmts = {
-    get: Statement<{ value: string }, [string, string]>;
-    put: Statement<unknown, [string, string, string]>;
+    get: Statement<{ value: string; expires_at: number | null }, [string, string]>;
+    put: Statement<unknown, [string, string, string, number | null]>;
     del: Statement<unknown, [string, string]>;
-    list: Statement<{ key: string }, [string, string]>;
+    list: Statement<{ key: string }, [string, string, number]>;
   };
   const kvStmtCache = new Map<Database, KvStmts>();
   const kvStmts = (store: Database): KvStmts => {
     let stmts = kvStmtCache.get(store);
     if (!stmts) {
       stmts = {
-        get: store.query<{ value: string }, [string, string]>("SELECT value FROM kv WHERE ns = ? AND key = ?"),
+        get: store.query<{ value: string; expires_at: number | null }, [string, string]>(
+          "SELECT value, expires_at FROM kv WHERE ns = ? AND key = ?",
+        ),
         put: store.query(
-          "INSERT INTO kv (ns, key, value) VALUES (?1, ?2, ?3) ON CONFLICT (ns, key) DO UPDATE SET value = ?3",
+          "INSERT INTO kv (ns, key, value, expires_at) VALUES (?1, ?2, ?3, ?4) " +
+            "ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4",
         ),
         del: store.query("DELETE FROM kv WHERE ns = ? AND key = ?"),
-        list: store.query<{ key: string }, [string, string]>(
-          "SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' ORDER BY key LIMIT 1000",
+        // #58 — an expired row is filtered out here; a periodic sweep to hard-delete
+        // it is a separate concern (ponytail: rows accumulate until touched by a
+        // get/list/put on the same key/prefix, add a cron sweep if that matters).
+        list: store.query<{ key: string }, [string, string, number]>(
+          "SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' AND (expires_at IS NULL OR expires_at > ?) ORDER BY key LIMIT 1000",
         ),
       };
       kvStmtCache.set(store, stmts);
     }
     return stmts;
   };
+  /** CF's own floor. Cloudflare rejects `expirationTtl < 60`; matched here so a
+   *  handler ported from Workers gets the same validation error either place. */
+  const MIN_KV_TTL_SECONDS = 60;
+  /** `{ expirationTtl }` (seconds from now) or `{ expiration }` (absolute unix
+   *  seconds) -> ms epoch, or `null` for no expiry. */
+  const kvExpiresAt = (msg: Frame): number | null => {
+    if (isNumber(msg.expirationTtl)) {
+      if (msg.expirationTtl < MIN_KV_TTL_SECONDS) throw new Error(`expirationTtl must be at least ${MIN_KV_TTL_SECONDS} seconds`);
+      return Date.now() + msg.expirationTtl * 1000;
+    }
+    if (isNumber(msg.expiration)) return msg.expiration * 1000;
+    return null;
+  };
 
   const bound =
     (list: string[], kind: string) =>
@@ -1190,12 +1220,18 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         return { ok: true, op: "pong", echo: msg.msg ?? null, pid: process.pid };
       case "kv.get": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
-        const row = kvStmts(store).get.get(part, str(msg.key));
-        return row ? { ok: true, found: true, value: row.value } : { ok: true, found: false, value: null };
+        const stmts = kvStmts(store);
+        const row = stmts.get.get(part, str(msg.key));
+        if (!row) return { ok: true, found: false, value: null };
+        if (row.expires_at != null && row.expires_at <= Date.now()) {
+          stmts.del.run(part, str(msg.key));
+          return { ok: true, found: false, value: null };
+        }
+        return { ok: true, found: true, value: row.value };
       }
       case "kv.put": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
-        kvStmts(store).put.run(part, str(msg.key), str(msg.value));
+        kvStmts(store).put.run(part, str(msg.key), str(msg.value), kvExpiresAt(msg));
         return { ok: true };
       }
       case "kv.delete": {
@@ -1208,10 +1244,54 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         return {
           ok: true,
           keys: kvStmts(store)
-            .list.all(part, str(msg.prefix))
+            .list.all(part, str(msg.prefix), Date.now())
             .map((r) => r.key),
         };
       }
+      case "cache.match": {
+        const name = str(msg.name) || "default";
+        const key = str(msg.key);
+        const row = db
+          .query<
+            { status: number; headers_json: string; body: string; expires_at: number | null },
+            [string, string]
+          >("SELECT status, headers_json, body, expires_at FROM cache WHERE name = ? AND cache_key = ?")
+          .get(name, key);
+        if (!row) return { ok: true, found: false };
+        if (row.expires_at != null && row.expires_at <= Date.now()) {
+          db.query("DELETE FROM cache WHERE name = ? AND cache_key = ?").run(name, key);
+          return { ok: true, found: false };
+        }
+        return { ok: true, found: true, status: row.status, headers: jsonObject(parseJsonValue(row.headers_json)) ?? {}, body: row.body };
+      }
+      case "cache.put": {
+        const name = str(msg.name) || "default";
+        const key = str(msg.key);
+        const status = Number(msg.status) || 200;
+        const headers = jsonObject(msg.headers ?? null) ?? {};
+        const cacheControl = str(headers["cache-control"] ?? headers["Cache-Control"] ?? "").toLowerCase();
+        // Mirrors Workers' own `caches.default.put()`: a 206 or an explicit
+        // no-store/private is a silent no-op, not an error — the handler's
+        // response still goes to the client either way.
+        if (status === 206 || cacheControl.includes("no-store") || cacheControl.includes("private")) {
+          return { ok: true, stored: false };
+        }
+        const sMaxAge = /s-maxage=(\d+)/.exec(cacheControl);
+        const maxAge = /max-age=(\d+)/.exec(cacheControl);
+        const ttlSeconds = sMaxAge ? Number(sMaxAge[1]) : maxAge ? Number(maxAge[1]) : null;
+        const expiresAt = ttlSeconds != null ? Date.now() + ttlSeconds * 1000 : null;
+        db.query(
+          "INSERT INTO cache (name, cache_key, status, headers_json, body, expires_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6) " +
+            "ON CONFLICT (name, cache_key) DO UPDATE SET status = ?3, headers_json = ?4, body = ?5, expires_at = ?6",
+        ).run(name, key, status, JSON.stringify(headers), str(msg.body), expiresAt);
+        return { ok: true, stored: true };
+      }
+      case "cache.delete": {
+        const name = str(msg.name) || "default";
+        const key = str(msg.key);
+        const r = db.query("DELETE FROM cache WHERE name = ? AND cache_key = ?").run(name, key);
+        return { ok: true, deleted: r.changes > 0 };
+      }
       case "secret.get": {
         const name = str(msg.name);
         if (!bindings.secrets.includes(name)) throw new Error(`secret not bound: ${name}`);
@@ -1676,6 +1756,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const REPLAYABLE = new Set([
     "kv.put",
     "kv.delete",
+    "cache.put",
+    "cache.delete",
     "queue.send",
     "queue.send_batch",
     "d1.query",