@sproutboat/wire 0.14.6 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @sproutboat/wire
 
+## 0.16.0
+
+### Minor Changes
+
+- 9be9c74: R2 matches workerd from compatibility date `2026-10-26`:
+  
+  - `get`, `put`, `head`, `delete`, `list` and `createMultipartUpload` return Promises, and errors reject them.
+  - An object's `etag` is the MD5 of its bytes, with `checksums.md5`. Objects written before keep their old etag.
+  - Objects have `uploaded` as a `Date`, `version`, `storageClass`, `range` and `writeHttpMetadata(headers)`. A body has `body` (a `ReadableStream`), `bodyUsed`, `text()`, `json()`, `arrayBuffer()` and `blob()`.
+  - `get(key, { range, onlyIf })` takes `{ offset, length }`, `{ suffix }` or a `Range` header, and `etagMatches`, `etagDoesNotMatch`, `uploadedBefore`, `uploadedAfter` or `If-*` headers. When the condition fails it returns the object without a body.
+  - `put(key, value, { onlyIf, httpMetadata })` takes a `ReadableStream` or a `Blob`, and `httpMetadata` as `Headers`. When the condition fails it returns `null`.
+  - `delete([keys])` deletes several keys.
+  - `list({ prefix, limit, cursor, delimiter, include })` pages at up to 1,000 entries, groups keys into `delimitedPrefixes`, and returns `httpMetadata` and `customMetadata` only when `include` asks for them.
+  - A value of the wrong type and a key longer than 1,024 bytes fail with R2's errors.
+  
+  Earlier dates keep the synchronous shim. One change applies at every date: **a `list()` prefix now matches exactly.** It used SQL `LIKE`, so it ignored case and read `_` and `%` as wildcards. Both transports store an object's MD5 in a new column, added to existing stores when they open.
+  
+  Against miniflare 4.20260730, `conformance/bindings/r2.js` in sproutd passes 48/48 at `2026-10-26` (16/48 before).
+
+### Patch Changes
+
+- Updated dependencies [9be9c74]
+  - @sproutboat/runtime@0.27.0
+
+## 0.15.0
+
+### Minor Changes
+
+- 9b15539: KV matches workerd from compatibility date `2026-10-25`:
+  
+  - `get`, `getWithMetadata`, `put`, `delete` and `list` return Promises, and errors reject them.
+  - `get(key, type)` takes `"text"`, `"json"`, `"arrayBuffer"` and `"stream"`, and `get([keys])` returns a `Map`.
+  - `getWithMetadata(key, type)` returns `{ value, metadata, cacheStatus }`.
+  - `put(key, value, { expiration, expirationTtl, metadata })` takes strings, bytes and `ReadableStream`s, and stores the metadata.
+  - `list({ prefix, limit, cursor })` returns `{ keys: [{ name, expiration?, metadata? }], list_complete, cursor?, cacheStatus }` and pages at up to 1,000 keys.
+  - Keys, values, expirations, metadata and list limits fail with KV's own errors. For example: `Key name cannot be empty.`, `KV PUT failed: 414 UTF-8 encoded length of 513 exceeds key length limit of 512.`, `KV PUT failed: 400 Invalid expiration_ttl of 30. Expiration TTL must be at least 60.`, and `KV PUT failed: 413 Metadata length of 1110 exceeds limit of 1024.`
+  
+  Earlier dates keep the synchronous shim. Two changes apply at every date:
+  
+  - **A `list()` prefix now matches exactly.** It used SQL `LIKE`, so it ignored case and read `_` and `%` as wildcards. For example, the prefix `a_` also listed `ab`, and `a` also listed `AB`.
+  - **Both transports store KV metadata in a new column.** It's added to existing stores when they open.
+
+### Patch Changes
+
+- Updated dependencies [9b15539]
+- Updated dependencies [1c36119]
+- Updated dependencies [3cad1f0]
+  - @sproutboat/runtime@0.26.0
+
 ## 0.14.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.14.6",
+  "version": "0.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "@sproutboat/assets": "^0.3.0",
-    "@sproutboat/runtime": "^0.25.0"
+    "@sproutboat/runtime": "^0.27.0"
   }
 }

package/src/broker.test.ts

@@ -114,7 +114,7 @@ test("#233: a KV value put as bytes is flagged binary and survives an existing s
   const bytes = Array.from({ length: 256 }, (_, i) => String.fromCharCode(i)).join("");
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "bin", value: bytes, binary: true });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "txt", value: "café" });
-  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "bin" })).toEqual({ ok: true, found: true, value: bytes, binary: true });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "bin" })).toMatchObject({ ok: true, found: true, value: bytes, binary: true });
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "txt" })).toMatchObject({ value: "café", binary: false });
   // Overwriting a binary value with text clears the flag.
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "bin", value: "now text" });
@@ -126,12 +126,36 @@ test("KV put / get / list / delete, scoped to a bound namespace", async () => {
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toEqual({ ok: true, found: false, value: null });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "k", value: "v" });
   await b.dispatch({ op: "kv.put", ns: "CACHE", key: "k2", value: "v2" });
-  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toEqual({ ok: true, found: true, value: "v", binary: false });
-  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "k" })).toEqual({ ok: true, keys: ["k", "k2"] });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toMatchObject({ ok: true, found: true, value: "v", binary: false });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "k" })).toMatchObject({ ok: true, keys: ["k", "k2"] });
   await b.dispatch({ op: "kv.delete", ns: "CACHE", key: "k" });
   expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "k" })).toMatchObject({ found: false });
 });
 
+test("KV metadata, expiration and paged list (the shim from 2026-10-25); the prefix matches exactly", async () => {
+  const b = make({ bindings: { kv: ["CACHE"] } });
+  const at = Math.floor(Date.now() / 1000) + 3600;
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "a", value: "1", metadata: '{"t":1}' });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "b", value: "2", expiration: at });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "c", value: "3" });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "a_x", value: "4" });
+  await b.dispatch({ op: "kv.put", ns: "CACHE", key: "AB", value: "5" });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "a" })).toMatchObject({ metadata: '{"t":1}', expiration: null });
+  expect(await b.dispatch({ op: "kv.get", ns: "CACHE", key: "b" })).toMatchObject({ metadata: null, expiration: at });
+  // LIKE matched "ab" for "a_" and "AB" for "a"; the prefix is now exact and case-sensitive.
+  expect((await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "a_" })).keys).toEqual(["a_x"]);
+  expect((await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "a" })).keys).toEqual(["a", "a_x"]);
+  const first = await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "" });
+  expect(first).toMatchObject({ keys: ["AB", "a"], list_complete: false, cursor: "a" });
+  expect(first.entries).toEqual([
+    { name: "AB", expiration: null, metadata: null },
+    { name: "a", expiration: null, metadata: '{"t":1}' },
+  ]);
+  const rest = await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "a" });
+  expect(rest).toMatchObject({ keys: ["a_x", "b"], list_complete: false, cursor: "b" });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "", limit: 2, cursor: "b" })).toMatchObject({ keys: ["c"], list_complete: true, cursor: "" });
+});
+
 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(
@@ -149,7 +173,7 @@ test("a key past its expiration reads as absent and is omitted from list", async
     found: false,
     value: null,
   });
-  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "" })).toEqual({ ok: true, keys: ["fresh"] });
+  expect(await b.dispatch({ op: "kv.list", ns: "CACHE", prefix: "" })).toMatchObject({ ok: true, keys: ["fresh"] });
 });
 
 test("an unbound KV namespace is rejected", async () => {
@@ -400,6 +424,28 @@ test("R2: put / get / head / list / delete on a bound bucket", async () => {
   await expect(b.dispatch({ op: "r2.put", bucket: "NOPE", key: "x", body: "y" })).rejects.toThrow("not bound");
 });
 
+test("R2: exact list prefix at every date; md5, paged list and delimiter for the shim from 2026-10-26", async () => {
+  const b = make({ bindings: { r2: ["ASSETS"] } });
+  for (const key of ["a_x", "ab", "AB", "d/1", "d/2", "e/1", "f"]) await b.dispatch({ op: "r2.put", bucket: "ASSETS", key, body: "v" });
+  // LIKE listed "ab" for "a_" and "AB" for "a".
+  expect(arr((await b.dispatch({ op: "r2.list", bucket: "ASSETS", prefix: "a_" })).objects).map((o) => obj(o).key)).toEqual(["a_x"]);
+  expect(arr((await b.dispatch({ op: "r2.list", bucket: "ASSETS", prefix: "a" })).objects).map((o) => obj(o).key)).toEqual(["a_x", "ab"]);
+  const put = await b.dispatch({ op: "r2.put", bucket: "ASSETS", key: "m", body: "hello" });
+  await b.dispatch({ op: "r2.md5", bucket: "ASSETS", key: "m", etag: obj(put.object).etag, md5: "5d41402abc4b2a76b9719d911017c592" });
+  expect(obj((await b.dispatch({ op: "r2.head", bucket: "ASSETS", key: "m" })).object).md5).toBe("5d41402abc4b2a76b9719d911017c592");
+  // A stale etag (the object was written again since) records nothing.
+  await b.dispatch({ op: "r2.md5", bucket: "ASSETS", key: "m", etag: "stale", md5: "x" });
+  expect(obj((await b.dispatch({ op: "r2.head", bucket: "ASSETS", key: "m" })).object).md5).toBe("5d41402abc4b2a76b9719d911017c592");
+  const page = (cursor: string) => b.dispatch({ op: "r2.list", bucket: "ASSETS", page: true, prefix: "", cursor, limit: 3, delimiter: "/" });
+  const first = await page("");
+  expect(arr(first.objects).map((o) => obj(o).key)).toEqual(["AB", "a_x", "ab"]);
+  expect(first).toMatchObject({ truncated: true, cursor: "ab", delimitedPrefixes: [] });
+  const second = await page("ab");
+  expect(arr(second.objects).map((o) => obj(o).key)).toEqual(["f"]);
+  expect(second).toMatchObject({ truncated: true, delimitedPrefixes: ["d/", "e/"] });
+  expect(await page(String(second.cursor))).toMatchObject({ objects: [{ key: "m" }], truncated: false, cursor: "" });
+});
+
 test("R2 direct transfer: streamed upload, metadata, one-use ticket and ranged download", async () => {
   const root = mkdtempSync(join(tmpdir(), "sb-r2-transfer-"));
   try {
@@ -883,7 +929,7 @@ test("resource-backed KV persists across brokers and is shared by id", async ()
       resourceDir,
       bindings: { kv: ["SHORTENER"], resources: { SHORTENER: { kind: "kv", id: kvId } } },
     });
-    expect(await second.dispatch({ op: "kv.get", ns: "SHORTENER", key: "a" })).toEqual({
+    expect(await second.dispatch({ op: "kv.get", ns: "SHORTENER", key: "a" })).toMatchObject({
       ok: true,
       found: true,
       binary: false,

package/src/broker.ts

@@ -150,6 +150,7 @@ type R2Row = {
   http_json: string;
   custom_json: string;
   blob_id: string | null;
+  md5?: string | null;
 };
 type R2UploadRow = {
   key: string;
@@ -301,6 +302,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     // #233 — 1 when the value was put as bytes (stored one char per byte), so get()
     // can hand back exact bytes or decoded text depending on the requested type.
     if (!kvColumns.some((column) => column.name === "binary")) conn.exec("ALTER TABLE kv ADD COLUMN binary INTEGER NOT NULL DEFAULT 0");
+    // A key's metadata (put(key, value, { metadata })), as JSON text.
+    if (!kvColumns.some((column) => column.name === "metadata")) conn.exec("ALTER TABLE kv ADD COLUMN metadata TEXT");
     // #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
@@ -315,6 +318,8 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     );
     const r2Columns = conn.query<{ name: string }, []>("PRAGMA table_info(r2)").all();
     if (!r2Columns.some((column) => column.name === "blob_id")) conn.exec("ALTER TABLE r2 ADD COLUMN blob_id TEXT");
+    // The MD5 of an object's bytes, its etag from compatibility date 2026-10-26 (r2.md5).
+    if (!r2Columns.some((column) => column.name === "md5")) conn.exec("ALTER TABLE r2 ADD COLUMN md5 TEXT");
     conn.exec(
       "CREATE TABLE IF NOT EXISTS r2_upload (bucket TEXT NOT NULL, key TEXT NOT NULL, upload_id TEXT NOT NULL, " +
         "uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
@@ -521,29 +526,31 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   };
 
   type KvStmts = {
-    get: Statement<{ value: string; expires_at: number | null; binary: number }, [string, string]>;
-    put: Statement<unknown, [string, string, string, number | null, number]>;
+    get: Statement<{ value: string; expires_at: number | null; binary: number; metadata: string | null }, [string, string]>;
+    put: Statement<unknown, [string, string, string, number | null, number, string | null]>;
     del: Statement<unknown, [string, string]>;
-    list: Statement<{ key: string }, [string, string, number]>;
+    list: Statement<{ key: string; expires_at: number | null; metadata: string | null }, [string, string, string, number, 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; expires_at: number | null; binary: number }, [string, string]>(
-          "SELECT value, expires_at, binary FROM kv WHERE ns = ? AND key = ?",
+        get: store.query<{ value: string; expires_at: number | null; binary: number; metadata: string | null }, [string, string]>(
+          "SELECT value, expires_at, binary, metadata FROM kv WHERE ns = ? AND key = ?",
         ),
         put: store.query(
-          "INSERT INTO kv (ns, key, value, expires_at, binary) VALUES (?1, ?2, ?3, ?4, ?5) " +
-            "ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5",
+          "INSERT INTO kv (ns, key, value, expires_at, binary, metadata) VALUES (?1, ?2, ?3, ?4, ?5, ?6) " +
+            "ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5, metadata = ?6",
         ),
         del: store.query("DELETE FROM kv WHERE ns = ? AND key = ?"),
         // #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",
+        // The prefix matches exactly: LIKE ignored case and read "_" and "%" as wildcards.
+        list: store.query<{ key: string; expires_at: number | null; metadata: string | null }, [string, string, string, number, number]>(
+          "SELECT key, expires_at, metadata FROM kv WHERE ns = ?1 AND substr(key, 1, length(?2)) = ?2 AND key > ?3 " +
+            "AND (expires_at IS NULL OR expires_at > ?4) ORDER BY key LIMIT ?5",
         ),
       };
       kvStmtCache.set(store, stmts);
@@ -1091,6 +1098,38 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     return r2Row(row);
   };
 
+  // One page of r2.list for the shim from 2026-10-26: at most LIMIT entries after CURSOR,
+  // keys under PREFIX, those holding DELIMITER after it grouped into delimitedPrefixes (a
+  // group counts as one entry). Same rules as the embedded transport's __sbR2ListPage.
+  // ponytail: with a delimiter every key after the cursor is read; an index on the
+  // delimited prefix if buckets grow past ~100k keys.
+  const r2ListPage = (store: Database, bucket: string, prefix: string, cursor: string, limit: number, delimiter: string) => {
+    const rows = store
+      .query<R2Row, [string, string, string]>(
+        "SELECT * FROM r2 WHERE bucket = ?1 AND substr(key, 1, length(?2)) = ?2 AND key > ?3 ORDER BY key" +
+          (delimiter ? "" : ` LIMIT ${limit + 1}`),
+      )
+      .all(bucket, prefix, cursor);
+    const objects: ReturnType<typeof r2Row>[] = [];
+    const delimitedPrefixes: string[] = [];
+    let last = "";
+    let truncated = false;
+    for (const row of rows) {
+      const at = delimiter ? row.key.indexOf(delimiter, prefix.length) : -1;
+      const group = at < 0 ? "" : row.key.slice(0, at + delimiter.length);
+      if (!group || delimitedPrefixes[delimitedPrefixes.length - 1] !== group) {
+        if (objects.length + delimitedPrefixes.length >= limit) {
+          truncated = true;
+          break;
+        }
+        if (group) delimitedPrefixes.push(group);
+        else objects.push(r2Row(row));
+      }
+      last = row.key;
+    }
+    return { ok: true, objects, delimitedPrefixes, truncated, cursor: truncated ? last : "" };
+  };
+
   const r2Row = (r: R2Row) => ({
     key: r.key,
     size: r.size,
@@ -1098,6 +1137,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     uploaded: r.uploaded,
     httpMetadata: parseJsonValue(r.http_json),
     customMetadata: parseJsonValue(r.custom_json),
+    md5: r.md5 ?? null,
   });
 
   /**
@@ -1285,11 +1325,25 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
           stmts.del.run(part, str(msg.key));
           return { ok: true, found: false, value: null };
         }
-        return { ok: true, found: true, value: row.value, binary: row.binary === 1 };
+        return {
+          ok: true,
+          found: true,
+          value: row.value,
+          binary: row.binary === 1,
+          metadata: row.metadata,
+          expiration: row.expires_at == null ? null : Math.floor(row.expires_at / 1000),
+        };
       }
       case "kv.put": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
-        kvStmts(store).put.run(part, str(msg.key), str(msg.value), kvExpiresAt(msg), msg.binary === true ? 1 : 0);
+        kvStmts(store).put.run(
+          part,
+          str(msg.key),
+          str(msg.value),
+          kvExpiresAt(msg),
+          msg.binary === true ? 1 : 0,
+          msg.metadata == null ? null : str(msg.metadata),
+        );
         return { ok: true };
       }
       case "kv.delete": {
@@ -1299,11 +1353,23 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "kv.list": {
         const { store, part } = storeFor("kv", requireKv(msg.ns));
+        // With a limit (the shim from 2026-10-25): a page after the cursor (the previous page's
+        // last key), with expirations and metadata. Without one: up to 1,000 keys, as before.
+        const paged = isNumber(msg.limit);
+        const limit = paged ? Math.max(0, Math.floor(Number(msg.limit))) : 1000;
+        const rows = kvStmts(store).list.all(part, str(msg.prefix), paged ? str(msg.cursor) : "", Date.now(), paged ? limit + 1 : limit);
+        const page = rows.slice(0, limit);
+        const complete = !paged || rows.length <= limit;
         return {
           ok: true,
-          keys: kvStmts(store)
-            .list.all(part, str(msg.prefix), Date.now())
-            .map((r) => r.key),
+          keys: page.map((r) => r.key),
+          entries: page.map((r) => ({
+            name: r.key,
+            expiration: r.expires_at == null ? null : Math.floor(r.expires_at / 1000),
+            metadata: r.metadata,
+          })),
+          list_complete: complete,
+          cursor: complete ? "" : (page[page.length - 1]?.key ?? ""),
         };
       }
       case "cache.match": {
@@ -1513,14 +1579,22 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         if (row) r2DeleteBlob(store, bucket, key, row.blob_id);
         return { ok: true };
       }
+      case "r2.md5": {
+        // Recorded after the put that wrote these bytes (etag): the shim from 2026-10-26 hashes them.
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        store.query("UPDATE r2 SET md5 = ?1 WHERE bucket = ?2 AND key = ?3 AND etag = ?4").run(str(msg.md5), bucket, str(msg.key), str(msg.etag));
+        return { ok: true };
+      }
       case "r2.list": {
+        // The prefix matches exactly at every date: LIKE ignored case and read "_" and "%" as wildcards.
         const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
         const prefix = str(msg.prefix);
         const cursor = str(msg.cursor);
-        const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 1000);
+        const limit = Math.min(Math.max(Math.floor(Number(msg.limit)) || 1000, 1), 1000);
+        if (msg.page === true) return r2ListPage(store, bucket, prefix, cursor, limit, str(msg.delimiter));
         const rows = store
           .query<R2Row, [string, string, string, number]>(
-            "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT ?",
+            "SELECT * FROM r2 WHERE bucket = ?1 AND substr(key, 1, length(?2)) = ?2 AND key > ?3 ORDER BY key LIMIT ?4",
           )
           .all(bucket, prefix, cursor, limit + 1);
         const truncated = rows.length > limit;
@@ -1846,6 +1920,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "r2.multipart.abort",
     "r2.transfer.create",
     "r2.delete",
+    "r2.md5",
     "do.storage.put",
     "do.storage.delete",
     "do.storage.delete_all",