@specific.dev/spectest 0.92.1 → 0.93.1

package/dist/harness/registry-seed.js

@@ -0,0 +1,61 @@
+/** Distribution v2 publication. Blob data stays in containerd, mounted
+ * read-only in the registry. Repository metadata and uploads MUST live on
+ * the environment rootfs, outside persistent image/build caches. */
+import { mkdir, stat, symlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { hostImage } from "./built-image.js";
+import { canonicalImageReference } from "./component-images.js";
+export const REGISTRY_DATA = "/var/lib/spectest-registry";
+export const REGISTRY_CONTENT = "/spectest-registry-content";
+export const CONTENT_BLOBS = "io.containerd.content.v1.content/blobs/sha256";
+export const REGISTRY_IMAGE = "registry:2.8.3";
+export const registryDirectory = (service) => `/var/lib/spectest-registries/${service}`;
+/** Distribution 2.8 registry/storage/paths.go defines this layout. Seed
+ * before starting the registry so it cannot cache partial publication.
+ * The prepared build's containerd image record retains the referenced blobs. */
+export async function seedRegistryImage(directory, contentDirectory, reference, image, mountedContent = REGISTRY_CONTENT) {
+    const canonical = canonicalImageReference(reference);
+    if (canonical.includes("@"))
+        throw new Error("registry publication must name a tag");
+    const repository = canonical.slice(canonical.indexOf("/") + 1, canonical.lastIndexOf(":"));
+    const tag = canonical.slice(canonical.lastIndexOf(":") + 1);
+    const root = `${directory}/docker/registry/v2`;
+    const repo = `${root}/repositories/${repository}`;
+    const link = async (path, value) => {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, value);
+    };
+    for (const [id, descriptor] of image.allowed) {
+        if (!/^sha256:[a-f0-9]{64}$/.test(id))
+            throw new Error(`invalid registry seed digest ${id}`);
+        const hex = id.slice(7);
+        const info = await stat(`${contentDirectory}/${hex}`);
+        if (!info.isFile() || info.size !== descriptor.size)
+            throw new Error(`missing or incomplete registry seed blob ${id}`);
+        const destination = `${root}/blobs/sha256/${hex.slice(0, 2)}/${hex}/data`;
+        await mkdir(dirname(destination), { recursive: true });
+        try {
+            await symlink(`${mountedContent}/${hex}`, destination);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        await link(`${repo}/_layers/sha256/${hex}/link`, id);
+        if (image.metadata.has(id))
+            await link(`${repo}/_manifests/revisions/sha256/${hex}/link`, id);
+    }
+    const id = image.target.digest;
+    await link(`${repo}/_manifests/tags/${tag}/index/sha256/${id.slice(7)}/link`, id);
+    await link(`${repo}/_manifests/tags/${tag}/current/link`, id);
+}
+export async function seedRegistry(service, contentDirectory, images) {
+    // Sequential metadata updates avoid races when several tags share blobs.
+    // Builds themselves still run concurrently with all environment preparation.
+    for (const image of images) {
+        await image.ready;
+        const built = await hostImage(image.source);
+        await seedRegistryImage(registryDirectory(service), contentDirectory, image.reference, built);
+        console.log(`[k3s-registry] ${service}: ${image.reference} @ ${built.target.digest} (cached blobs, no export)`);
+    }
+}

package/dist/index.d.ts

@@ -831,7 +831,8 @@ export type BuildImage = (Omit<Extract<NormalizedServiceImage, {
 }>, "type">) & {
     /** Full image reference, e.g. "k8s.internal:5000/runtime:spectest".
      * Optional for a service; required for a Kubernetes build. This names a
-     * local image and does not publish it to a registry. */
+     * local image. In k3s, builds targeting `registry.host` are also published
+     * to that component's registry; other references are only preloaded. */
     reference?: string;
 };
 /** A registry reference or Dockerfile build. Tagged objects from older SDKs

package/package.json

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

package/src/components/email.ts

@@ -1,3 +1,4 @@
+import { rawFetch } from "../harness/raw-fetch.js";
 // `email()` — a real SMTP server as a spectest service. The app under test
 // points its SMTP transport at `<key>:1025` and sends mail exactly as it
 // would in production; every message is captured instead of delivered.
@@ -19,10 +20,8 @@
 
 import type { ServiceDefinition } from "../index.js";
 import {
-  pauseRecording,
   recordEmail,
   reserveEvent,
-  resumeRecording,
   truncateUtf8,
   type EmailEventMessage,
   type EmailEventSummary,
@@ -262,26 +261,19 @@ async function instrumented<T>(
   }
 }
 
-/** Query the mail server's HTTP API. Recording is paused around the fetch
- *  so these internal polls don't land as `http` events on the timeline —
- *  the helper records one consolidated `email` event instead. */
+/** Internal HTTP stays native; the public helper records one email event. */
 async function api(base: string, path: string, init?: RequestInit): Promise<unknown> {
-  pauseRecording();
+  const res = await rawFetch(`${base}${path}`, init);
+  if (!res.ok) {
+    throw new Error(`email server API ${path} failed: HTTP ${res.status}`);
+  }
+  const text = await res.text();
+  if (text === "") return undefined;
   try {
-    const res = await fetch(`${base}${path}`, init);
-    if (!res.ok) {
-      throw new Error(`email server API ${path} failed: HTTP ${res.status}`);
-    }
-    const text = await res.text();
-    if (text === "") return undefined;
-    try {
-      return JSON.parse(text);
-    } catch {
-      // Mutating endpoints reply with a plain-text acknowledgement.
-      return text;
-    }
-  } finally {
-    resumeRecording();
+    return JSON.parse(text);
+  } catch {
+    // Mutating endpoints reply with a plain-text acknowledgement.
+    return text;
   }
 }
 

package/src/components/index.ts

@@ -26,6 +26,7 @@ export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export {
   k3s,
   type K3sOptions,
+  type K3sRegistryOptions,
   type KubernetesImage,
   type K3sHelpers,
   type K3sClient,

package/src/components/internal-fetch.test.ts

@@ -0,0 +1,109 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Exercise public component hooks with the same dispatcher and async scope as
+// bootstrap. A child process isolates global fetch and recorder state.
+async function check(code: string, workspace?: string): Promise<void> {
+  const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  const script = `
+    import { strict as assert } from "node:assert";
+    import { s3 } from ${moduleUrl("./s3.ts")};
+    import { supabase } from ${moduleUrl("./supabase.ts")};
+    import { emailHelpers } from ${moduleUrl("./email.ts")};
+    import { installFetchWrapper } from ${moduleUrl("../harness/fetch.ts")};
+    import { createInstrumentationScope, runInstrumented } from ${moduleUrl("../harness/instrumentation-scope.ts")};
+    import { startRecording, stopRecording } from ${moduleUrl("../recorder.ts")};
+    let respond = () => Response.json({});
+    const requests = [];
+    globalThis.fetch = async (input, init) => {
+      requests.push({ url: String(input), method: init?.method ?? "GET" });
+      return respond();
+    };
+    const restore = installFetchWrapper();
+    const scope = createInstrumentationScope(false);
+    try {
+      await runInstrumented(scope, async () => {
+        assert.equal((await fetch("http://probe/")).status.unwrap(), 200);
+        requests.length = 0;
+        ${code}
+      });
+    } finally { scope.active = false; restore(); }
+  `;
+  const child = Bun.spawn([process.execPath, "--eval", script], {
+    env: { ...process.env, ...(workspace ? { SPECTEST_WORKSPACE: workspace } : {}) },
+    stdout: "pipe", stderr: "pipe",
+  });
+  const [exit, stdout, stderr] = await Promise.all([
+    child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+  ]);
+  expect(exit, stdout + stderr).toBe(0);
+}
+
+test.each([200, 201, 409, 403, 500])("S3 setup handles HTTP %i inside a wrapped setup scope", async (status) => {
+  await check(`
+    respond = () => new Response("bucket response", { status: ${status} });
+    const setup = s3({ buckets: ["uploads", "assets"] }).setup;
+    ${status === 403 || status === 500
+      ? `await assert.rejects(() => setup({ name: "storage" }), /failed to create bucket uploads: ${status}/);
+         assert.equal(requests.length, 1);`
+      : `await setup({ name: "storage" });
+         assert.deepEqual(requests, [
+           { url: "http://storage:9090/uploads", method: "PUT" },
+           { url: "http://storage:9090/assets", method: "PUT" },
+         ]);`}
+  `);
+});
+
+test("S3 setup propagates transport failures", async () => {
+  await check(`
+    respond = () => { throw new Error("connection refused"); };
+    await assert.rejects(() => s3({ buckets: ["uploads"] }).setup({ name: "storage" }), /connection refused/);
+  `);
+});
+
+test("Supabase warm-up handles errors and reads native JSON in a wrapped setup scope", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-component-fetch-"));
+  try {
+    await mkdir(join(root, "supabase/functions/hello"), { recursive: true });
+    await writeFile(join(root, "supabase/functions/hello/index.ts"), "export default {};");
+    await check(`
+      const parts = supabase({ dir: "supabase" }).group.services({
+        name: "supabase", key: part => part === "gateway" ? "supabase" : "supabase-" + part,
+      });
+      const warnings = [], logs = [];
+      console.warn = (...args) => warnings.push(args.join(" "));
+      console.log = (...args) => logs.push(args.join(" "));
+      respond = () => new Response("unavailable", { status: 503 });
+      await parts.functions.setup();
+      assert.equal(warnings.length, 1);
+      assert.match(warnings[0], /warm-up answered 503/);
+      respond = () => Response.json({ mode: "shared", warmed: ["hello"], failed: {} });
+      await parts.functions.setup();
+      assert.equal(logs.length, 1);
+      assert.match(logs[0], /warmed 1 edge function in one isolate/);
+    `, root);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("email helpers reject HTTP errors and retain their public event without internal HTTP events", async () => {
+  await check(`
+    const mail = emailHelpers("mail");
+    scope.recording = true;
+    startRecording();
+    respond = () => new Response("unavailable", { status: 503 });
+    await assert.rejects(() => mail.clear(), /email server API .* failed: HTTP 503/);
+    let events = stopRecording();
+    assert.deepEqual(events.map(e => e.kind), ["email"]);
+    assert.match(events[0].error, /HTTP 503/);
+    startRecording();
+    respond = () => Response.json({ messages: [] });
+    assert.deepEqual((await mail.emails()).unwrap(), []);
+    respond = () => new Response(null, { status: 204 });
+    await mail.clear();
+    events = stopRecording();
+    assert.deepEqual(events.map(e => e.kind), ["email", "email"]);
+    assert.equal(events.some(e => e.error), false);
+  `);
+});

package/src/components/k3s-registry.test.ts

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import { k3s } from "./k3s";
+import { REGISTRY_CONTENT, REGISTRY_DATA } from "../harness/registry-seed";
+
+test("HTTPS registry is component-owned, with explicit containerd trust and no Traefik dependency", () => {
+  const cluster = k3s({ registry: { host: "Registry.Test" }, traefik: false });
+  expect(cluster.tls).toEqual([{ hostname: "registry.test", port: 5000 }]);
+  const registries = cluster.files.find(file => file.path.endsWith("registries.yaml"))!.content;
+  expect(registries).toContain('"registry.test":\n    tls:\n      ca_file:');
+  expect(registries).not.toContain('"https://127.0.0.1');
+  expect(registries).toContain('"http://127.0.0.1:5000"');
+});
+
+test("only builds targeting the configured registry require publication storage", () => {
+  const image = { content: "FROM scratch", reference: "registry.test/codenode:latest" };
+  const cluster = k3s({ registry: { host: "registry.test" }, images: [image] });
+  expect(cluster.imageBuilds).toHaveLength(1);
+  expect(cluster.volumes.find(v => v.target === REGISTRY_DATA)?.source).toBe(
+    "/var/lib/spectest-registries/{{SPECTEST_SERVICE}}",
+  );
+  expect(cluster.volumes.find(v => v.target === REGISTRY_CONTENT)?.readOnly).toBe(true);
+  for (const registry of [undefined, false, true, { host: "other.test" }]) {
+    expect(k3s({ registry, images: [image] }).volumes.some(v => v.target === REGISTRY_DATA)).toBe(false);
+  }
+  expect(k3s({ registry: { host: "registry.test" }, images: [image.reference] }).volumes.some(v => v.target === REGISTRY_DATA)).toBe(false);
+});
+
+test("registry host rejects ports, URLs, wildcard and reserved hostnames", () => {
+  for (const host of ["", "https://registry.test", "registry.test:443", "*.registry.test", "k8s.internal", "registry.test/path"]) {
+    expect(() => k3s({ registry: { host } })).toThrow();
+  }
+  for (const registry of [null, "registry.test", {}, { host: 123 }]) {
+    expect(() => k3s({ registry } as never)).toThrow();
+  }
+});
+
+test("registry upload URLs are relative and local pre-pulls wait for the registry", async () => {
+  const cluster = k3s({ registry: { host: "registry.test" }, traefik: false, images: ["registry.test/app:latest"] });
+  let ready = false;
+  await cluster.setup({ name: "cluster", helpers: {
+    apply: async (manifest: string) => {
+      expect(manifest).toContain('REGISTRY_HTTP_RELATIVEURLS\n          value: "true"');
+      expect(manifest).toContain("emptyDir: {}");
+    },
+    waitForRollout: async () => { ready = true; },
+  }, exec: async (_name: string, args: string[]) => {
+    if (args[3] === "pull") expect(ready).toBe(true);
+    return { exitCode: 0, stdout: "", stderr: "" };
+  } } as never);
+});

package/src/components/k3s.ts

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 import { installPodTrust } from "./k3s-trust.js";
 import { waitForAll } from "../harness/concurrency.js";
+import { CONTENT_BLOBS, REGISTRY_CONTENT, REGISTRY_DATA, REGISTRY_IMAGE, registryDirectory, seedRegistry } from "../harness/registry-seed.js";
 import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
@@ -60,6 +61,15 @@ export type {
   KubernetesListObject,
 } from "@kubernetes/client-node";
 
+/** HTTPS exposure and publication for the component's writable registry. */
+export interface K3sRegistryOptions {
+  /** Exact DNS hostname exposed through Spectest's VM HTTPS proxy on port 443.
+   * Clients and Kubernetes's containerd trust the environment CA automatically.
+   * Builds in `images` whose reference starts with this host are also published
+   * here, using their original cached blobs and manifest digests. */
+  host: string;
+}
+
 /** Kubernetes pods receive read-only environment CA mounts during admission.
  * Image bytes and digests stay unchanged; explicit pod trust settings win. */
 export interface K3sOptions {
@@ -67,6 +77,9 @@ export interface K3sOptions {
    * or Dockerfile builds with a full `reference` matching your manifests. Builds
    * support path/content, context, exclude, target and buildArgs, and run in
    * parallel with service builds through the standard BuildKit pipeline.
+   * With `registry: { host }`, builds targeting that host are also published
+   * to the writable registry before setup completes. Other images remain
+   * direct preloads; no external registry receives pushes.
    * Setup waits for every pull and fails if a requested image cannot be pulled.
    * Sticky-enabled projects retain image content and unpacked layers between
    * fresh builds automatically. Digest references can reuse the cache offline;
@@ -141,10 +154,15 @@ export interface K3sOptions {
    * into your platform, e.g. `env: { REGISTRY_URL: "cluster.internal:5000" }`.
    * Plain HTTP, so configure your push client for an insecure registry.
    *
+   * Set `{ host: "registry.test" }` for verified HTTPS on port 443 through
+   * the built-in VM proxy, including containerd trust and relative upload URLs.
+   * This does not require Traefik. Builds targeting that host in `images` are
+   * published automatically; tags and test uploads remain isolated per fork.
+   *
    * On by default. Set `false` for clusters that only ever run public
    * images — that skips the extra pod.
    */
-  registry?: boolean;
+  registry?: boolean | K3sRegistryOptions;
   /**
    * Domains to route into this cluster's ingress via **wildcard DNS**. For
    * each `"example.com"`, spectest-resolver answers any `*.example.com`
@@ -1290,7 +1308,7 @@ const HUB_MIRROR = { registry: "docker.io", mirror: "https://mirror.gcr.io", ups
  *      shares the node's netns, so this needs no in-container DNS and
  *      can't be broken by a clobbered `hostnames`.
  */
-function buildRegistriesYaml(registryEnabled: boolean): string | null {
+function buildRegistriesYaml(registryEnabled: boolean, host?: string): string | null {
   const lines: string[] = [
     "mirrors:",
     `  "${HUB_MIRROR.registry}":`,
@@ -1312,6 +1330,11 @@ function buildRegistriesYaml(registryEnabled: boolean): string | null {
       `      insecure_skip_verify: true`,
     );
   }
+  if (host) {
+    // This names the verified HTTPS endpoint itself; do not mirror it to HTTP.
+    // container-run mounts the environment CA before k3s/containerd starts.
+    lines.push(`  "${host}":`, "    tls:", `      ca_file: ${JSON.stringify(CA_PATH)}`);
+  }
   return lines.join("\n") + "\n";
 }
 
@@ -1320,11 +1343,13 @@ function buildRegistriesYaml(registryEnabled: boolean): string | null {
  * binds the cluster container's `:5000` directly — the same trick
  * Traefik uses — so peer services reach it at `<cluster-key>.internal:5000`
  * (the cluster service's own alias) and the node's own containerd reaches
- * it at `127.0.0.1:5000`. Storage is an `emptyDir`, so pushed images live
- * in the cluster and are captured by snapshot / isolated per test fork
- * like all other in-VM state.
+ * it at `127.0.0.1:5000`. Storage is an `emptyDir` by default. Declared
+ * publications use a rootfs directory plus a read-only content mount; both
+ * variants keep writable registry state outside persistent image caches and
+ * capture it with the VM snapshot, isolated per test fork.
  */
-const REGISTRY_MANIFEST = `apiVersion: apps/v1
+function registryManifest(seeded: boolean): string {
+  return `apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: spectest-registry
@@ -1347,11 +1372,13 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: registry:2
+        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
           value: ":${K3S_REGISTRY_PORT}"
+        - name: REGISTRY_HTTP_RELATIVEURLS
+          value: "true"
         - name: REGISTRY_STORAGE_DELETE_ENABLED
           value: "true"
         ports:
@@ -1360,10 +1387,20 @@ spec:
         volumeMounts:
         - name: data
           mountPath: /var/lib/registry
-      volumes:
+${seeded ? `        - name: content
+          mountPath: ${REGISTRY_CONTENT}
+          readOnly: true
+` : ""}      volumes:
       - name: data
-        emptyDir: {}
+${seeded ? `        hostPath:
+          path: ${REGISTRY_DATA}
+          type: Directory
+      - name: content
+        hostPath:
+          path: ${REGISTRY_CONTENT}
+          type: Directory` : "        emptyDir: {}"}
 `;
+}
 
 // ────────────────────────────────────────────────────────────────────────
 // Apply — server-side, converging
@@ -1883,7 +1920,7 @@ async function waitForJob(
 async function setupK3sCluster(
   name: string,
   helpers: K3sHelpers,
-  opts: { registry: boolean; ingressDomains: string[]; traefik: boolean },
+  opts: { registry: boolean; ingressDomains: string[]; traefik: boolean; seed?: () => Promise<void> },
 ): Promise<void> {
   // The registry can start while Traefik's certificates are being prepared.
   const wait = (deployment: string): Promise<void> =>
@@ -1927,7 +1964,8 @@ async function setupK3sCluster(
     })(),
     (async () => {
       if (!opts.registry) return;
-      await helpers.apply(REGISTRY_MANIFEST);
+      await opts.seed?.();
+      await helpers.apply(registryManifest(!!opts.seed));
       await wait("spectest-registry");
     })(),
   ]);
@@ -2061,6 +2099,16 @@ export function k3s(opts: K3sOptions = {}) {
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
+  let registryHost: string | undefined;
+  if (opts.registry !== undefined && typeof opts.registry !== "boolean") {
+    if (!opts.registry || typeof opts.registry.host !== "string" || opts.registry.host.startsWith("*.")) {
+      throw new Error("k3s(): registry must be a boolean or { host: an exact DNS hostname }");
+    }
+    // Reuse ingress validation (no scheme, port, path, or reserved .internal).
+    registryHost = dnsName(opts.registry.host, { ingress: true }).hostname;
+  }
+  const isPublished = (reference: string) => !!registryHost && reference.startsWith(`${registryHost}/`);
+  const publishBuilds = images.builds.filter(image => isPublished(image.reference));
   const traefikEnabled = opts.traefik !== false;
   const loadBalancerEnabled = opts.loadBalancer !== false;
   // Wildcard ingress domains. Drives both the `provides(... dnsName)`
@@ -2070,12 +2118,13 @@ export function k3s(opts: K3sOptions = {}) {
   // `/etc/rancher/k3s/registries.yaml` (host-cache mirrors + trust for
   // the in-cluster registry). Seeded via `files` because k3s reads it
   // only at startup, before any setup hook could run.
-  const registriesYaml = buildRegistriesYaml(registryEnabled);
+  const registriesYaml = buildRegistriesYaml(registryEnabled, registryHost);
   // The environment's image cache, when this VM carries one: the
   // cluster's store goes on its root disk and its layers come off the
   // shared layers disk (see the store section above).
   const sticky = stickyDiskPathSync();
   const cache = sticky ? null : imageCachePathsSync();
+  const contentDirectory = `${sticky ? `${sticky}/containerd` : cache?.root ?? "/var/lib/containerd"}/${CONTENT_BLOBS}`;
   const serverArgs = [
     "k3s",
     "server",
@@ -2175,6 +2224,7 @@ export function k3s(opts: K3sOptions = {}) {
   const def = {
     image: { type: "registry", reference: `rancher/k3s:${version}` },
     imageBuilds: images.builds,
+    tls: registryHost ? [{ hostname: registryHost, port: K3S_REGISTRY_PORT }] : [],
     command: cmd,
     privileged: true,
     tmpfs: ["/run", "/var/run"],
@@ -2196,7 +2246,7 @@ export function k3s(opts: K3sOptions = {}) {
     // in one environment get separate roots either way (the service
     // token names the directory), because two containerd daemons cannot
     // share a store: bolt takes an exclusive lock.
-    volumes: sticky
+    volumes: [...(sticky
       ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
       : cache ? [
           { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
@@ -2204,7 +2254,12 @@ export function k3s(opts: K3sOptions = {}) {
           { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
           { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
         ]
-      : [{ target: CLUSTER_STORE_TARGET }],
+      : [{ target: CLUSTER_STORE_TARGET }]),
+      ...(publishBuilds.length ? [
+        { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
+        { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
+      ] : []),
+    ],
     files: [
       ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
       ...(cache
@@ -2223,49 +2278,56 @@ export function k3s(opts: K3sOptions = {}) {
       const { name, helpers, exec } = ctx;
       const runtime = componentRuntime(ctx);
       if (images.builds.length && !runtime) throw new Error(`k3s(${name}): prepared image inputs are missing`);
-      await waitForAll([
-        runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
-        prePullK3sImages(name, images.pulls, exec),
-        (async () => {
-          if (runtime?.caBundle && caPresent()) {
-            const { cert, key } = await issueIngressCert([runtime.gateway]);
-            await installPodTrust({ name, gateway: runtime.gateway, cert, key,
-              ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
-            }, {
-              apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
-              ensureBundle: async (namespace, configMap, bundle) => {
-                try {
-                  await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
-                    metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
-                  } });
-                } catch (err) {
-                  // A simultaneous Pod may have created the same namespace's bundle.
-                  const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
-                  if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true) throw err;
-                }
-              },
-            });
-            // The API server observes webhook registration asynchronously. A dry-run
-            // Pod proves TLS reachability and admission before any project workload.
-            const deadline = Date.now() + 30_000;
-            for (;;) {
+      const infrastructure = (async () => {
+        if (runtime?.caBundle && caPresent()) {
+          const { cert, key } = await issueIngressCert([runtime.gateway]);
+          await installPodTrust({ name, gateway: runtime.gateway, cert, key,
+            ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
+          }, {
+            apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
+            ensureBundle: async (namespace, configMap, bundle) => {
               try {
-                const pod = (await helpers.client.core.createNamespacedPod({ namespace: "default", dryRun: "All", body: {
-                  metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: "registry.k8s.io/pause:3.10" }] },
-                } })).unwrap();
-                if (pod.spec?.containers[0].env?.some(e => e.name === "SSL_CERT_FILE" && e.value === "/spectest/ca-bundle.crt")) break;
-                if (Date.now() >= deadline) throw new Error(`k3s(${name}): Pod CA mounts did not become ready`);
+                await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
+                  metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
+                } });
               } catch (err) {
-                if (Date.now() >= deadline) throw err;
+                // A simultaneous Pod may have created the same namespace's bundle.
+                const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
+                if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true) throw err;
               }
-              await new Promise(resolve => setTimeout(resolve, 100));
+            },
+          });
+          // The API server observes webhook registration asynchronously. A dry-run
+          // Pod proves TLS reachability and admission before any project workload.
+          const deadline = Date.now() + 30_000;
+          for (;;) {
+            try {
+              const pod = (await helpers.client.core.createNamespacedPod({ namespace: "default", dryRun: "All", body: {
+                metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: "registry.k8s.io/pause:3.10" }] },
+              } })).unwrap();
+              if (pod.spec?.containers[0].env?.some(e => e.name === "SSL_CERT_FILE" && e.value === "/spectest/ca-bundle.crt")) break;
+              if (Date.now() >= deadline) throw new Error(`k3s(${name}): Pod CA mounts did not become ready`);
+            } catch (err) {
+              if (Date.now() >= deadline) throw err;
             }
+            await new Promise(resolve => setTimeout(resolve, 100));
           }
-          await setupK3sCluster(name, helpers, {
-            registry: registryEnabled,
-            ingressDomains,
-            traefik: traefikEnabled,
-          });
+        }
+        await setupK3sCluster(name, helpers, {
+          registry: registryEnabled,
+          seed: publishBuilds.length ? () => seedRegistry(name, contentDirectory,
+            runtime!.images.filter(image => isPublished(image.reference))) : undefined,
+          ingressDomains,
+          traefik: traefikEnabled,
+        });
+      })();
+      await waitForAll([
+        runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
+        prePullK3sImages(name, images.pulls.filter(ref => !isPublished(ref)), exec),
+        (async () => {
+          // Registry-local references must not race registry startup/publication.
+          await infrastructure;
+          await prePullK3sImages(name, images.pulls.filter(isPublished), exec);
         })(),
       ]);
       if (sticky) await registerStickyKubernetesStore(name, version);

package/src/components/s3.ts

@@ -1,3 +1,4 @@
+import { rawFetch } from "../harness/raw-fetch.js";
 import type { ServiceDefinition } from "../index.js";
 import { S3Client, type S3ClientLike } from "../s3.js";
 
@@ -123,7 +124,7 @@ export function s3(opts: S3Options = {}) {
               // CreateBucket is a plain `PUT` on the bucket root; the store
               // returns 200 (or 409 if it already exists — idempotent enough to
               // ignore).
-              const res = await fetch(`http://${name}:${S3_PORT}/${bucket}`, {
+              const res = await rawFetch(`http://${name}:${S3_PORT}/${bucket}`, {
                 method: "PUT",
               });
               if (!res.ok && res.status !== 409) {

package/src/components/supabase.ts

@@ -1,3 +1,4 @@
+import { rawFetch } from "../harness/raw-fetch.js";
 // A ready-to-use, self-hosted **Supabase** stack, expressed as a set of
 // spectest services (one container each) wired together on spectest-net.
 //
@@ -2300,7 +2301,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // 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`);
+            const res = await rawFetch(`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;

package/src/daemon.ts

@@ -2417,6 +2417,9 @@ function bindIngressServer(
     // {@link stopIngressServers} depends on: a half-alive listener shares
     // the port silently instead of colliding loudly.
     reusePort: true,
+    // OCI layer uploads can exceed Bun's default 128 MiB request limit.
+    // Large proxy bodies stream through; this limit does not allocate a buffer.
+    maxRequestBodySize: 1024 ** 4,
     // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
     // request whose upstream takes >10s to produce bytes — under parallel
     // test load that surfaced as "fetch failed"/"other side closed" on