edgeway 0.1.0 → 0.3.0

data/js/cloudflare-d1-sessions.js

@@ -0,0 +1,68 @@
+// X-D1-Bookmark is "BINDING=bookmark, ..."; clients resend it whole.
+import { addVary } from "./headers.js";
+
+export const BOOKMARK_HEADER = "X-D1-Bookmark";
+
+const isRead = (request) => request?.method === "GET" || request?.method === "HEAD";
+
+// A bookmark is opaque and D1's: one that does not look like D1's is dropped,
+// as D1 itself would keep a high-sorting garbage value as the latest bookmark.
+const BINDING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const BOOKMARK = /^[0-9a-f-]{1,128}$/;
+
+export function parseBookmarks(value) {
+  const bookmarks = {};
+  for (const pair of (value ?? "").split(",")) {
+    const separator = pair.indexOf("=");
+    const name = pair.slice(0, separator).trim();
+    const bookmark = pair.slice(separator + 1).trim();
+    if (separator > 0 && BINDING_NAME.test(name) && BOOKMARK.test(bookmark)) bookmarks[name] = bookmark;
+  }
+  return bookmarks;
+}
+
+export class D1Sessions {
+  constructor(env, request, names = []) {
+    this.env = env;
+    this.names = new Set(names);
+    this.readRequest = isRead(request);
+    this.bookmarks = parseBookmarks(request?.headers.get(BOOKMARK_HEADER));
+    this.sessions = new Map();
+  }
+
+  uses(name) {
+    return this.names.has(name);
+  }
+
+  database(name) {
+    const binding = this.env[name];
+    if (!binding || !this.names.has(name)) return binding;
+    if (!this.sessions.has(name)) this.sessions.set(name, this.start(binding, name));
+    return this.sessions.get(name);
+  }
+
+  start(binding, name) {
+    return binding.withSession(this.startPoint(name));
+  }
+
+  startPoint(name) {
+    if (!this.readRequest) return "first-primary";
+    return this.bookmarks[name] ?? "first-unconstrained";
+  }
+
+  header() {
+    const pairs = [];
+    for (const name of this.names) {
+      const bookmark = this.sessions.get(name)?.getBookmark() ?? this.bookmarks[name];
+      if (bookmark) pairs.push(`${name}=${bookmark}`);
+    }
+    return pairs.join(", ");
+  }
+
+  annotate(response) {
+    const value = this.header();
+    if (value) response.headers.set(BOOKMARK_HEADER, value);
+    if (this.names.size > 0) addVary(response.headers, BOOKMARK_HEADER);
+    return response;
+  }
+}

data/js/cloudflare-kv.js

@@ -0,0 +1,47 @@
+import { jspiHelpers } from "./jspi.js";
+
+export const MIN_EXPIRATION_TTL = 60;
+
+export function putOptions(expiresIn) {
+  if (!(expiresIn > 0)) return undefined;
+  return { expirationTtl: Math.max(expiresIn, MIN_EXPIRATION_TTL) };
+}
+
+// An R2 bucket also has get, put and delete; only a KV namespace has getWithMetadata.
+export const isKvNamespace = (value) => Boolean(value) && ["get", "put", "delete", "getWithMetadata"].every((name) => typeof value[name] === "function");
+
+export function kvImports(env, getInstance) {
+  const { readCString, setResult, take } = jspiHelpers(getInstance);
+
+  const namespaceOf = (bindingName) => {
+    const namespace = env[bindingName];
+    if (!isKvNamespace(namespace)) throw new Error(`no KV binding ${bindingName}`);
+    return namespace;
+  };
+
+  const suspending = (operation) => new WebAssembly.Suspending(async (bindingPointer, keyPointer, ...rest) => {
+    let result;
+    try {
+      const namespace = namespaceOf(readCString(bindingPointer));
+      result = await operation(namespace, readCString(keyPointer), ...rest);
+    } catch (error) {
+      result = { error: String(error?.message ?? error) };
+    }
+    return setResult(result);
+  });
+
+  return {
+    edgeway_kv: {
+      get: suspending(async (namespace, key) => ({ value: await namespace.get(key, "text") })),
+      put: suspending(async (namespace, key, textPointer, expiresIn) => {
+        await namespace.put(key, readCString(textPointer), putOptions(expiresIn));
+        return { ok: true };
+      }),
+      delete: suspending(async (namespace, key) => {
+        await namespace.delete(key);
+        return { ok: true };
+      }),
+      take,
+    },
+  };
+}

data/js/cloudflare-ratelimit.js

@@ -0,0 +1,31 @@
+import { jspiHelpers } from "./jspi.js";
+
+const isRateLimit = (value) => Boolean(value) && typeof value.limit === "function";
+
+export function rateLimitImports(env, getInstance) {
+  const { readCString, setResult, take } = jspiHelpers(getInstance);
+
+  const check = new WebAssembly.Suspending(async (bindingPointer, keyPointer) => {
+    let result;
+    try {
+      const bindingName = readCString(bindingPointer);
+      const rateLimit = env[bindingName];
+      if (isRateLimit(rateLimit)) {
+        const { success } = await rateLimit.limit({ key: readCString(keyPointer) });
+        result = { success: success !== false };
+      } else {
+        result = { misconfigured: `no rate limit binding ${bindingName}` };
+      }
+    } catch (error) {
+      result = { error: String(error?.message ?? error) };
+    }
+    return setResult(result);
+  });
+
+  return {
+    edgeway_ratelimit: {
+      check,
+      take,
+    },
+  };
+}

data/js/cloudflare-test-database.js

@@ -0,0 +1,112 @@
+// The databases of `edgeway test` on a local D1: dropped and migrated again
+// before each test, so every test starts from the migrations' state.
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// What wrangler and D1 keep in the database themselves.
+const KEPT_OBJECT = /^(sqlite_|_cf_)|^d1_migrations$/;
+
+const quoted = (name) => `"${name.replaceAll('"', '""')}"`;
+
+const COMMENT = /--[^\n]*|\/\*[\s\S]*?\*\//g;
+const withoutComments = (sql) => sql.replace(COMMENT, " ");
+const startsTrigger = (statement) => /^\s*create\s+(temp(orary)?\s+)?trigger\b/i.test(withoutComments(statement));
+// A trigger's body is statements ending in ';', and the trigger ends at the
+// END after the last of them (sqlite3_complete's rule): not at the END of a
+// CASE, nor a column named end.
+const triggerEnded = (statement) => /;\s*end\s*$/i.test(withoutComments(statement));
+
+// SQL text split into statements at the ';' outside strings, comments and a
+// trigger's body. Each statement is run with prepare(), which takes one.
+// Text with nothing but comments is no statement (D1 refuses it).
+export function splitStatements(sql) {
+  const statements = [];
+  let current = "";
+  let at = 0;
+  const copyUntil = (terminator) => {
+    const stop = sql.indexOf(terminator, at + 1);
+    const end = stop === -1 ? sql.length : stop + terminator.length;
+    current += sql.slice(at, end);
+    at = end;
+  };
+  const endsStatement = () => !startsTrigger(current) || triggerEnded(current);
+  while (at < sql.length) {
+    const char = sql[at];
+    if (char === "'" || char === '"' || char === "`") copyUntil(char);
+    else if (char === "[") copyUntil("]");
+    else if (sql.startsWith("--", at)) copyUntil("\n");
+    else if (sql.startsWith("/*", at)) copyUntil("*/");
+    else if (char === ";" && endsStatement()) {
+      statements.push(current.trim());
+      current = "";
+      at++;
+    } else {
+      current += char;
+      at++;
+    }
+  }
+  statements.push(current.trim());
+  return statements.filter((statement) => withoutComments(statement).trim() !== "");
+}
+
+// The files of a migrations directory in file name order, each as
+// { name, statements }. A directory that is not there has none.
+export function migrationFiles(directory, { readdir = readdirSync, read = readFileSync, exists = existsSync } = {}) {
+  if (!exists(directory)) return [];
+  return readdir(directory)
+    .filter((name) => name.endsWith(".sql"))
+    .sort()
+    .map((name) => ({ name, statements: splitStatements(read(join(directory, name), "utf8")) }));
+}
+
+// databases: [{ binding, migrations: directory }]
+export function loadMigrations(databases, options) {
+  return databases.map(({ binding, migrations }) => ({ binding, files: migrationFiles(migrations, options) }));
+}
+
+// The statements that empty a database, from the rows of sqlite_master
+// ({ type, name }). Dropping a table drops its indexes and triggers. Foreign
+// keys are enforced, so the checks wait for the end of the batch.
+export function dropStatements(objects) {
+  const dropped = objects.filter(({ name }) => !KEPT_OBJECT.test(name));
+  const views = dropped.filter(({ type }) => type === "view");
+  const tables = dropped.filter(({ type }) => type === "table");
+  if (views.length + tables.length === 0) return [];
+  return [
+    "PRAGMA defer_foreign_keys = on",
+    ...views.map(({ name }) => `DROP VIEW IF EXISTS ${quoted(name)}`),
+    ...tables.map(({ name }) => `DROP TABLE IF EXISTS ${quoted(name)}`),
+  ];
+}
+
+async function dropEverything(database) {
+  const { results } = await database.prepare("SELECT type, name FROM sqlite_master WHERE type IN ('table', 'view')").all();
+  const statements = dropStatements(results);
+  if (statements.length > 0) await database.batch(statements.map((sql) => database.prepare(sql)));
+}
+
+async function migrate(database, files) {
+  for (const { name, statements } of files) {
+    if (statements.length === 0) continue;
+    try {
+      await database.batch(statements.map((sql) => database.prepare(sql)));
+    } catch (error) {
+      throw new Error(`migration ${name}: ${error?.message ?? error}`);
+    }
+  }
+}
+
+// migrations: loadMigrations' answer. Entries that share a binding are one
+// database: it is emptied once, then every entry's files are applied in order.
+export async function resetDatabases(env, migrations) {
+  const filesByBinding = new Map();
+  for (const { binding, files } of migrations) {
+    filesByBinding.set(binding, [...(filesByBinding.get(binding) ?? []), ...files]);
+  }
+  for (const [binding, files] of filesByBinding) {
+    const database = env[binding];
+    if (!database) throw new Error(`no D1 binding ${binding} in wrangler.toml`);
+    await dropEverything(database);
+    await migrate(database, files);
+  }
+}

data/js/cloudflare-test-runner.js

@@ -0,0 +1,76 @@
+// Runs the wasm build of an app's tests, on a local in-memory D1:
+//
+//   node cloudflare-test-runner.js TEST.wasm [ARGS...]
+//
+// `edgeway test` starts it (with --experimental-wasm-jspi and --experimental-wasm-exnref on Node.js 24); ARGS
+// go to the program (-n NAME). The environment is wrangler's getPlatformProxy
+// with persist: false, so the state in .wrangler/state is never touched. The
+// wasm calls edgeway_test.reset before each test, and the exit status is its own.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import config from "./config.js";
+import { WASI } from "./wasi-shim.js";
+import { lineSplitter, parseLogLine } from "./runtime.js";
+import { d1Imports, varsOf } from "./cloudflare.js";
+import { jwtImports } from "./jwt.js";
+import { fetchImports } from "./fetch.js";
+import { kvImports } from "./cloudflare-kv.js";
+import { rateLimitImports } from "./cloudflare-ratelimit.js";
+import { D1Sessions } from "./cloudflare-d1-sessions.js";
+import { loadMigrations, resetDatabases } from "./cloudflare-test-database.js";
+
+function requireJspi() {
+  if (typeof WebAssembly.Suspending === "function") return;
+  throw new Error("this Node.js has no WebAssembly JSPI; Node.js 24 needs --experimental-wasm-jspi (`edgeway test` passes it)");
+}
+
+function logText(line) {
+  const { level, message, ...fields } = parseLogLine(line) ?? {};
+  if (level === undefined) return line;
+  const pairs = Object.entries(fields).map(([name, value]) => ` ${name}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+  return `[edgeway] ${level.toUpperCase()} ${message}${pairs.join("")}`;
+}
+
+async function runTests(wasmPath, args, env) {
+  const migrations = loadMigrations(config.databases);
+  const stderr = lineSplitter((line) => process.stderr.write(`${logText(line)}\n`));
+  const wasi = new WASI({
+    args: ["test", ...args],
+    env: { ...varsOf(env), EDGEWAY_ENV: config.env },
+    onStdout: (text) => process.stdout.write(text),
+    onStderr: (text) => stderr.push(text),
+  });
+  const reset = new WebAssembly.Suspending(() => resetDatabases(env, migrations));
+  let instance;
+  instance = new WebAssembly.Instance(await WebAssembly.compile(readFileSync(wasmPath)), {
+    wasi_snapshot_preview1: wasi.wasiImport,
+    ...d1Imports(env, () => instance, new D1Sessions(env, undefined, config.sessions)),
+    ...jwtImports(env, () => instance),
+    ...fetchImports(() => instance),
+    ...kvImports(env, () => instance),
+    ...rateLimitImports(env, () => instance),
+    edgeway_test: { reset },
+  });
+  try {
+    return await wasi.startAsync(instance);
+  } finally {
+    stderr.flush();
+  }
+}
+
+async function main() {
+  const [wasmPath, ...args] = process.argv.slice(2);
+  requireJspi();
+  const { getPlatformProxy } = await import("wrangler");
+  const proxy = await getPlatformProxy({ configPath: join(config.appRoot, "wrangler.toml"), persist: false });
+  try {
+    process.exitCode = await runTests(wasmPath, args, proxy.env);
+  } finally {
+    await proxy.dispose();
+  }
+}
+
+main().catch((error) => {
+  console.error(`edgeway test: ${error instanceof WebAssembly.RuntimeError ? error.stack : error?.message ?? error}`);
+  process.exitCode = 1;
+});

data/js/cloudflare.js

@@ -5,20 +5,104 @@
 //   export default createWorker(app);
 //
 // build/edgeway/config.js is written by `edgeway build` from
-// config/database.yml: the environment name and the D1 binding.
+// config/database.yml: the environment name, the D1 binding, and the bindings
+// that use D1 Sessions.
 import { runCgi } from "./runtime.js";
 import config from "./config.js";
 import { jwtImports } from "./jwt.js";
+import { fetchImports } from "./fetch.js";
+import { kvImports } from "./cloudflare-kv.js";
+import { rateLimitImports } from "./cloudflare-ratelimit.js";
 import { withCors } from "./cors.js";
+import { BOOKMARK_HEADER, D1Sessions } from "./cloudflare-d1-sessions.js";
+
+// D1's transient errors, which are worth a retry by the client
+// (developers.cloudflare.com/d1/observability/debug-d1/). D1 retries read-only
+// queries itself; Edgeway never retries, as a write is not idempotent.
+// "exceeded", "CPU time limit", "memory limit" and "timeout" are not here.
+export const TRANSIENT_D1_ERRORS = [
+  "Network connection lost",
+  "reset because its code was updated",
+  "storage caused object to be reset",
+  "Replica disconnected from primary",
+  "transient issue on remote node",
+  "Can't read from request stream because client disconnected",
+  "D1 DB is overloaded",
+];
+
+export const isTransientD1Error = (message) => TRANSIENT_D1_ERRORS.some((s) => message.includes(s));
+
+// Counts are 32-bit in wasm: a larger one is clamped.
+const MAX_COUNT = 2147483647;
+
+// D1's result.meta in the shape of META above. A local D1 (wrangler dev) may
+// leave fields out.
+export function metaOf(meta) {
+  return {
+    rows_read: Math.min(meta?.rows_read ?? 0, MAX_COUNT),
+    rows_written: Math.min(meta?.rows_written ?? 0, MAX_COUNT),
+    duration: meta?.duration ?? 0,
+    served_by_region: meta?.served_by_region ?? "",
+    served_by_primary: meta?.served_by_primary ?? true,
+  };
+}
+
+export function sumMeta(metas) {
+  const all = metas.map(metaOf);
+  const sum = (field) => all.reduce((total, meta) => total + meta[field], 0);
+  return {
+    ...all[all.length - 1],
+    rows_read: Math.min(sum("rows_read"), MAX_COUNT),
+    rows_written: Math.min(sum("rows_written"), MAX_COUNT),
+    duration: sum("duration"),
+  };
+}
+
+// A BLOB crosses as {"$blob": "<base64>"}. D1 binds an ArrayBuffer as a BLOB and
+// answers a BLOB column as an Array of byte numbers.
+export function bindOf(value) {
+  if (value === null || typeof value !== "object" || typeof value.$blob !== "string") return value;
+  return Uint8Array.from(atob(value.$blob), (char) => char.charCodeAt(0)).buffer;
+}
+
+const isBytes = (value) => Array.isArray(value) || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+
+function bytesOf(value) {
+  if (Array.isArray(value)) return Uint8Array.from(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  return new Uint8Array(value);
+}
+
+function base64Of(value) {
+  const bytes = bytesOf(value);
+  let binary = "";
+  for (let at = 0; at < bytes.length; at += 8192) binary += String.fromCharCode(...bytes.subarray(at, at + 8192));
+  return btoa(binary);
+}
+
+export function rowOf(row) {
+  for (const column of Object.keys(row)) {
+    const value = row[column];
+    if (value !== null && typeof value === "object" && isBytes(value)) row[column] = { $blob: base64Of(value) };
+  }
+  return row;
+}
 
 // The wasm import module "edgeway_d1" (lib/edgeway/service/cloudflare/d1.rb). Each call
 // answers the byte length of its JSON result; take() copies it out.
-//   query(binding, sql, binds)   -> {"rows": [...]}
-//   execute(binding, sql, binds) -> {"changes": n, "last_insert_id": id}
-//   batch(binding, statements)   -> {"results": [{"changes": n, "last_insert_id": id}, ...]}
+//   query(binding, sql, binds)   -> {"rows": [...], "meta": META}
+//   execute(binding, sql, binds) -> {"changes": n, "last_insert_id": id, "meta": META}
+//   exec(binding, sql)           -> {"count": n, "meta": META}
+//                                   (sql: statements separated by newlines, no binds; an error on a database with sessions)
+//   batch(binding, statements)   -> {"results": [{"changes": n, "last_insert_id": id}, ...], "meta": META}
 //                                   (statements: [[sql, binds], ...], one atomic D1 batch)
-// An error is {"error": "message"}.
-export function d1Imports(env, getInstance) {
+// META is {"rows_read": n, "rows_written": n, "duration": ms, "served_by_region": "...",
+// "served_by_primary": bool}; a batch's sums the statements'. exec's has only
+// rows_read, rows_written and duration.
+// An error is {"error": "message"} (no meta), with "unavailable": true when it is transient.
+const SESSION_EXEC_ERROR = "exec() is not available on a database with sessions: true (a D1 session has no exec)";
+
+export function d1Imports(env, getInstance, sessions = new D1Sessions(env)) {
   const mem = () => new Uint8Array(getInstance().exports.memory.buffer);
   const cstr = (p) => {
     const b = mem();
@@ -29,36 +113,47 @@ export function d1Imports(env, getInstance) {
   let pending = new Uint8Array(0);
 
   // fn(db, ...pointers) answers the result object; a failure is {error}.
-  const suspending = (fn) => new WebAssembly.Suspending(async (bindingPtr, ...ptrs) => {
+  const suspending = (fn, { withoutSessions = false } = {}) => new WebAssembly.Suspending(async (bindingPtr, ...ptrs) => {
     let res;
     try {
       const name = cstr(bindingPtr) || config.d1Binding;
-      const db = env[name];
+      if (withoutSessions && sessions.uses(name)) throw new Error(SESSION_EXEC_ERROR);
+      const db = sessions.database(name);
       if (!db) throw new Error(`no D1 binding ${name}`);
       res = await fn(db, ...ptrs);
     } catch (e) {
-      res = { error: String(e?.message ?? e) };
+      const error = String(e?.message ?? e);
+      res = isTransientD1Error(error) ? { error, unavailable: true } : { error };
     }
     pending = new TextEncoder().encode(JSON.stringify(res));
     return pending.length;
   });
+  const prepare = (db, sql, binds) => db.prepare(sql).bind(...binds.map(bindOf));
   const run = (fn) => suspending((db, sqlPtr, bindsPtr) =>
-    fn(db.prepare(cstr(sqlPtr)).bind(...JSON.parse(cstr(bindsPtr)))));
+    fn(prepare(db, cstr(sqlPtr), JSON.parse(cstr(bindsPtr)))));
 
   return {
     edgeway_d1: {
-      query: run(async (st) => ({ rows: (await st.all()).results })),
-      execute: run(async (st) => {
-        const meta = (await st.run()).meta;
-        return { changes: meta.changes ?? 0, last_insert_id: meta.last_row_id ?? 0 };
+      query: run(async (statement) => {
+        const result = await statement.all();
+        return { rows: result.results.map(rowOf), meta: metaOf(result.meta) };
+      }),
+      execute: run(async (statement) => {
+        const meta = (await statement.run()).meta;
+        return { changes: meta.changes ?? 0, last_insert_id: meta.last_row_id ?? 0, meta: metaOf(meta) };
       }),
+      exec: suspending(async (db, sqlPtr) => {
+        const result = await db.exec(cstr(sqlPtr));
+        return { count: result.count ?? 0, meta: { rows_read: 0, rows_written: 0, duration: result.duration ?? 0 } };
+      }, { withoutSessions: true }),
       // db.batch() is one transaction: a failing statement rejects it and
       // none of the statements stay applied.
       batch: suspending(async (db, statementsPtr) => {
         const statements = JSON.parse(cstr(statementsPtr));
-        const results = await db.batch(statements.map(([sql, binds]) => db.prepare(sql).bind(...binds)));
+        const results = await db.batch(statements.map(([sql, binds]) => prepare(db, sql, binds)));
         return {
-          results: results.map((r) => ({ changes: r.meta.changes ?? 0, last_insert_id: r.meta.last_row_id ?? 0 })),
+          results: results.map((result) => ({ changes: result.meta.changes ?? 0, last_insert_id: result.meta.last_row_id ?? 0 })),
+          meta: sumMeta(results.map((result) => result.meta)),
         };
       }),
       take(buf) {
@@ -73,6 +168,7 @@ export function d1Imports(env, getInstance) {
 // out.
 const FRAMEWORK_VARS = new Set([
   "JWT_ISSUER", "JWT_AUDIENCE", "JWT_LEEWAY", "JWT_ALGORITHMS", "JWT_JWKS_URL",
+  "LOG_LEVEL",
 ]);
 
 // The Worker's variables (strings) become CGI environment variables, which
@@ -90,14 +186,40 @@ export function varsOf(env) {
   return vars;
 }
 
+// Not CORS-safelisted, so a page reads it on a 429 or 503 only when exposed.
+const RETRY_AFTER_HEADER = "Retry-After";
+
+export function corsOptions(sessionBindings) {
+  const bookmark = sessionBindings.length > 0 ? [BOOKMARK_HEADER] : [];
+  return { exposeHeaders: [RETRY_AFTER_HEADER, ...bookmark], allowHeaders: bookmark };
+}
+
+// What identifies the request in every log line: the ray id (absent in local
+// development).
+export function logFieldsOf(request) {
+  const ray = request.headers.get("cf-ray");
+  return ray ? { ray } : {};
+}
+
 // appModule: the WebAssembly.Module that `import app from "...app.wasm"` gives.
 export function createWorker(appModule) {
   return {
-    fetch: withCors((request, env) => runCgi(appModule, request, {
-      extraEnv: { EDGEWAY_ENV: config.env, ...varsOf(env) },
-      // Both modules are always supplied, whether or not the app uses them:
-      // the wasm instance needs every import it declares.
-      imports: (getInstance) => ({ ...d1Imports(env, getInstance), ...jwtImports(env, getInstance) }),
-    })),
+    fetch: withCors(async (request, env) => {
+      const sessions = new D1Sessions(env, request, config.sessions ?? []);
+      const response = await runCgi(appModule, request, {
+        extraEnv: { EDGEWAY_ENV: config.env, ...varsOf(env) },
+        logFields: logFieldsOf(request),
+        // Every module is always supplied, whether or not the app uses it:
+        // the wasm instance needs every import it declares.
+        imports: (getInstance) => ({
+          ...d1Imports(env, getInstance, sessions),
+          ...jwtImports(env, getInstance),
+          ...fetchImports(getInstance),
+          ...kvImports(env, getInstance),
+          ...rateLimitImports(env, getInstance),
+        }),
+      });
+      return sessions.annotate(response);
+    }, corsOptions(config.sessions ?? [])),
   };
 }

data/js/cors.js

@@ -4,6 +4,8 @@
 // status instead of an opaque CORS error. Nothing here is specific to a
 // platform. Cookies are not supported: Access-Control-Allow-Credentials is
 // never sent.
+import { addVary, withHeaders } from "./headers.js";
+
 const DEFAULT_HEADERS = "Authorization, Content-Type";
 const DEFAULT_MAX_AGE = "600";
 const METHODS = "GET, HEAD, POST, PUT, PATCH, DELETE";
@@ -15,17 +17,17 @@ function json(status, body, headers = {}) {
 // The settings from the Worker's variables, or null when CORS is off.
 // A bad CORS_MAX_AGE is { error }: like JWT, a misconfiguration is a 500, not
 // a silent default.
-function settings(env) {
-  const list = (env.CORS_ORIGINS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+function settings(env, { exposeHeaders, allowHeaders }) {
+  const list = (env.CORS_ORIGINS ?? "").split(",").map((origin) => origin.trim()).filter(Boolean);
   if (list.length === 0) return null;
   const maxAge = (env.CORS_MAX_AGE ?? "").trim() || DEFAULT_MAX_AGE;
   if (!/^\d+$/.test(maxAge)) return { error: `CORS_MAX_AGE must be a non-negative integer, got "${env.CORS_MAX_AGE}"` };
   return {
     any: list.includes("*"),
     origins: new Set(list),
-    headers: (env.CORS_HEADERS ?? "").trim() || DEFAULT_HEADERS,
+    headers: withHeaders((env.CORS_HEADERS ?? "").trim() || DEFAULT_HEADERS, ...allowHeaders),
     maxAge,
-    expose: (env.CORS_EXPOSE_HEADERS ?? "").trim(),
+    expose: withHeaders(env.CORS_EXPOSE_HEADERS, ...exposeHeaders),
   };
 }
 
@@ -36,20 +38,17 @@ function allowed(cfg, origin) {
   return cfg.any || cfg.origins.has(origin);
 }
 
-// Appends Origin to Vary unless it (or *) is already there.
-function addVary(headers, ...names) {
-  const have = (headers.get("Vary") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-  if (have.includes("*")) return;
-  for (const n of names) {
-    if (!have.some((h) => h.toLowerCase() === n.toLowerCase())) have.push(n);
-  }
-  headers.set("Vary", have.join(", "));
+function exposeOn(headers, expose) {
+  const merged = withHeaders(headers.get("Access-Control-Expose-Headers"), ...expose.split(", ").filter(Boolean));
+  if (merged) headers.set("Access-Control-Expose-Headers", merged);
 }
 
-// Wraps a fetch handler (request, env, ctx) -> Response.
-export function withCors(handler) {
+// Wraps a fetch handler (request, env, ctx) -> Response. exposeHeaders and
+// allowHeaders are names the platform layer always adds to the exposed and the
+// preflight-allowed headers.
+export function withCors(handler, { exposeHeaders = [], allowHeaders = [] } = {}) {
   return async (request, env, ctx) => {
-    const cfg = settings(env);
+    const cfg = settings(env, { exposeHeaders, allowHeaders });
     if (!cfg) return handler(request, env, ctx);
     if (cfg.error) {
       console.error(cfg.error);
@@ -79,7 +78,7 @@ export function withCors(handler) {
     const out = new Response(res.body, res);
     if (ok) {
       out.headers.set("Access-Control-Allow-Origin", origin);
-      if (cfg.expose) out.headers.set("Access-Control-Expose-Headers", cfg.expose);
+      exposeOn(out.headers, cfg.expose);
     }
     addVary(out.headers, "Origin");
     return out;