@specific.dev/spectest 0.64.0 → 0.66.0

package/dist/components/supabase.d.ts

@@ -33,6 +33,20 @@ export interface SupabaseOptions {
     storage?: boolean;
     /** Include Realtime (`<name>-realtime`). Default `true`. */
     realtime?: boolean;
+    /**
+     * Edge functions. `isolation` picks how they run on the edge runtime:
+     * `"shared"` (default) loads every function into **one** isolate, so a
+     * shared module graph (`_shared/`, npm packages) is loaded once rather than
+     * once per function — measured on a 51-function project as 230 MB against
+     * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
+     * that differs is module-level state: a singleton in `_shared` is one
+     * object for all functions here, one per function there. `"per-function"`
+     * runs it the hosted way. Either way the runtime, the request each
+     * function sees and the per-function `verify_jwt` are the same.
+     */
+    functions?: {
+        isolation?: "shared" | "per-function";
+    };
     /**
      * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
      * daemon's CA-trusted TLS reverse proxy (in addition to the plain

package/dist/components/supabase.js

@@ -698,6 +698,17 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** How the functions run: every function in one isolate (the default), or
+ *  one isolate per function as hosted Supabase does — see sharedWorker. */
+const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
 /** One isolate per function, reused across requests (the runtime pools by
  *  servicePath). The idle timeout is a day, not upstream's five minutes: a
  *  test environment is a snapshot lineage whose forks inherit these
@@ -708,32 +719,268 @@ function workerFor(name: string) {
   return EdgeRuntime.userWorkers.create({
     servicePath: FUNCTIONS_DIR + "/" + name,
     memoryLimitMb: 256,
-    workerTimeoutMs: 24 * 60 * 60 * 1000,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
     noModuleCache: false,
     importMapPath: null,
     envVars: Object.entries(Deno.env.toObject()),
   });
 }
 
-/** Boot every function's isolate now, without calling it. Creating the
- *  worker loads the module graph and runs the module's top level — for a
- *  function that is its \`Deno.serve(handler)\` registration, no business
- *  logic. Called once at environment setup, before the warm snapshot, so
- *  the isolates are shared, clean pages of the snapshot rather than a boot
- *  in every test that first touches a function. */
-async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, string> }> {
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
   const names: string[] = [];
   for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
     if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// It stands in only where it can be exact. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
     try {
-      await Deno.stat(FUNCTIONS_DIR + "/" + entry.name + "/index.ts");
-      names.push(entry.name);
-    } catch {
-      // not a function directory
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
     }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
   }
-  // All at once: a project can have dozens of functions, and each boot is
-  // mostly module loading — the isolates come up concurrently.
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (ISOLATION !== "shared") return null;
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
+  }
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
   const results = await Promise.allSettled(names.map((name) => workerFor(name)));
   const warmed: string[] = [];
   const failed: Record<string, string> = {};
@@ -741,7 +988,7 @@ async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, str
     if (r.status === "fulfilled") warmed.push(names[i]);
     else failed[names[i]] = String(r.reason);
   });
-  return { warmed: warmed.sort(), failed };
+  return { mode: "per-function", warmed: warmed.sort(), failed };
 }
 
 Deno.serve(async (req: Request) => {
@@ -766,7 +1013,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await workerFor(name);
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1482,6 +1729,9 @@ export function supabase(opts = {}) {
                         JWT_SECRET: jwtSecret,
                         // Where the router looks for `<name>/`, inside the repo mount.
                         FUNCTIONS_DIR: fnServePath,
+                        // One isolate for all functions (default) or one each — see the
+                        // `functions` option and the router's shared-isolate notes.
+                        FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
                         // The default a function inherits when the config says nothing:
                         // reject an unauthenticated call, as hosted Supabase does.
                         VERIFY_JWT: "true",
@@ -1521,13 +1771,16 @@ export function supabase(opts = {}) {
                     // fork of it. Warm, the isolates are clean shared pages of the
                     // snapshot and a test's diff is what its requests mutate.
                     setup: async () => {
+                        const t0 = Date.now();
                         const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
                         if (!res.ok) {
                             console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
                             return;
                         }
-                        const { warmed, failed } = (await res.json());
-                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"}${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+                        const { mode, warmed, failed } = (await res.json());
+                        const secs = ((Date.now() - t0) / 1000).toFixed(1);
+                        const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
                         for (const [name, err] of Object.entries(failed)) {
                             console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/supabase.ts

@@ -235,6 +235,18 @@ export interface SupabaseOptions {
   storage?: boolean;
   /** Include Realtime (`<name>-realtime`). Default `true`. */
   realtime?: boolean;
+  /**
+   * Edge functions. `isolation` picks how they run on the edge runtime:
+   * `"shared"` (default) loads every function into **one** isolate, so a
+   * shared module graph (`_shared/`, npm packages) is loaded once rather than
+   * once per function — measured on a 51-function project as 230 MB against
+   * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
+   * that differs is module-level state: a singleton in `_shared` is one
+   * object for all functions here, one per function there. `"per-function"`
+   * runs it the hosted way. Either way the runtime, the request each
+   * function sees and the per-function `verify_jwt` are the same.
+   */
+  functions?: { isolation?: "shared" | "per-function" };
 
   /**
    * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
@@ -1043,6 +1055,17 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** How the functions run: every function in one isolate (the default), or
+ *  one isolate per function as hosted Supabase does — see sharedWorker. */
+const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
 /** One isolate per function, reused across requests (the runtime pools by
  *  servicePath). The idle timeout is a day, not upstream's five minutes: a
  *  test environment is a snapshot lineage whose forks inherit these
@@ -1053,32 +1076,268 @@ function workerFor(name: string) {
   return EdgeRuntime.userWorkers.create({
     servicePath: FUNCTIONS_DIR + "/" + name,
     memoryLimitMb: 256,
-    workerTimeoutMs: 24 * 60 * 60 * 1000,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
     noModuleCache: false,
     importMapPath: null,
     envVars: Object.entries(Deno.env.toObject()),
   });
 }
 
-/** Boot every function's isolate now, without calling it. Creating the
- *  worker loads the module graph and runs the module's top level — for a
- *  function that is its \`Deno.serve(handler)\` registration, no business
- *  logic. Called once at environment setup, before the warm snapshot, so
- *  the isolates are shared, clean pages of the snapshot rather than a boot
- *  in every test that first touches a function. */
-async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, string> }> {
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
   const names: string[] = [];
   for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
     if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// It stands in only where it can be exact. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
     try {
-      await Deno.stat(FUNCTIONS_DIR + "/" + entry.name + "/index.ts");
-      names.push(entry.name);
-    } catch {
-      // not a function directory
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
     }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
+  }
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (ISOLATION !== "shared") return null;
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
   }
-  // All at once: a project can have dozens of functions, and each boot is
-  // mostly module loading — the isolates come up concurrently.
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
   const results = await Promise.allSettled(names.map((name) => workerFor(name)));
   const warmed: string[] = [];
   const failed: Record<string, string> = {};
@@ -1086,7 +1345,7 @@ async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, str
     if (r.status === "fulfilled") warmed.push(names[i]);
     else failed[names[i]] = String(r.reason);
   });
-  return { warmed: warmed.sort(), failed };
+  return { mode: "per-function", warmed: warmed.sort(), failed };
 }
 
 Deno.serve(async (req: Request) => {
@@ -1111,7 +1370,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await workerFor(name);
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1983,6 +2242,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             JWT_SECRET: jwtSecret,
             // Where the router looks for `<name>/`, inside the repo mount.
             FUNCTIONS_DIR: fnServePath,
+            // One isolate for all functions (default) or one each — see the
+            // `functions` option and the router's shared-isolate notes.
+            FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
             // The default a function inherits when the config says nothing:
             // reject an unauthenticated call, as hosted Supabase does.
             VERIFY_JWT: "true",
@@ -2025,13 +2287,20 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // fork of it. Warm, the isolates are clean shared pages of the
           // snapshot and a test's diff is what its requests mutate.
           setup: async () => {
+            const t0 = Date.now();
             const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
             if (!res.ok) {
               console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
               return;
             }
-            const { warmed, failed } = (await res.json()) as { warmed: string[]; failed: Record<string, string> };
-            console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"}${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+            const { mode, warmed, failed } = (await res.json()) as {
+              mode: "shared" | "per-function";
+              warmed: string[];
+              failed: Record<string, string>;
+            };
+            const secs = ((Date.now() - t0) / 1000).toFixed(1);
+            const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+            console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
             for (const [name, err] of Object.entries(failed)) {
               console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
             }