@specific.dev/spectest 0.92.1 → 0.93.1

package/src/harness/built-image.ts

@@ -0,0 +1,53 @@
+/** Read build results without reserializing manifests or exporting layers. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import { canonicalImageReference } from "./component-images.js";
+
+export interface Descriptor { digest: string; size: number; mediaType: string; platform?: { os: string; architecture: string } }
+interface Manifest { schemaVersion: number; mediaType: string; config: Descriptor; layers: Descriptor[]; annotations?: Record<string, string> }
+const digest = (bytes: Uint8Array) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const descriptor = (bytes: Uint8Array, mediaType: string): Descriptor => ({ digest: digest(bytes), size: bytes.length, mediaType });
+const run = promisify(execFile);
+const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
+
+async function hostContent(id: string): Promise<Buffer> {
+  if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error(`invalid content digest ${id}`);
+  const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
+  if (digest(result.stdout) !== id) throw new Error(`corrupt image metadata ${id}`);
+  return result.stdout;
+}
+
+/** Preserve the original index/manifest bytes and all application descriptors. */
+export async function hostImage(source: string) {
+  const name = canonicalImageReference(source);
+  const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
+  const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
+  if (!found) throw new Error(`built image ${name} is missing from the VM container store`);
+  const metadata = new Map<string, Buffer>();
+  const allowed = new Map<string, Descriptor>();
+  let configDigest: string | undefined;
+  async function visit(id: string, selected: boolean, depth = 0): Promise<Descriptor> {
+    if (depth > 4) throw new Error(`built image ${name} has a recursive manifest index`);
+    const bytes = await hostContent(id);
+    const obj = JSON.parse(bytes.toString());
+    const desc = descriptor(bytes, obj.mediaType);
+    metadata.set(id, bytes);
+    allowed.set(id, desc);
+    if (obj.config && Array.isArray(obj.layers)) {
+      const manifest = obj as Manifest;
+      for (const blob of [manifest.config, ...manifest.layers]) allowed.set(blob.digest, blob);
+      if (selected) configDigest = manifest.config.digest;
+    } else if (Array.isArray(obj.manifests)) {
+      for (const entry of obj.manifests as Descriptor[]) {
+        const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
+        await visit(entry.digest, selected && matches, depth + 1);
+      }
+    } else throw new Error(`built image ${name} has invalid image metadata`);
+    return desc;
+  }
+  const target = await visit(found, true);
+  if (!configDigest) throw new Error(`built image ${name} has no image for this VM's platform`);
+  return { target, metadata, allowed, configDigest };
+}
+

package/src/harness/k3s-image-loader.ts

@@ -1,62 +1,17 @@
 /** A short-lived, read-only OCI endpoint over the host containerd content store.
  * k3s fetches only missing blobs and unpacks only missing snapshots. No Docker
  * archive, staging registry, or second persistent copy of application blobs. */
-import { execFile, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createServer } from "node:http";
-import { promisify } from "node:util";
 import type { SpectestContext } from "../index.js";
 import { canonicalImageReference, type PreparedComponentImage } from "./component-images.js";
 import { waitForK3sRuntime } from "./k3s-prepull.js";
+import { hostImage } from "./built-image.js";
 import { waitForAll } from "./concurrency.js";
 
-interface Descriptor { digest: string; size: number; mediaType: string; platform?: { os: string; architecture: string } }
-interface Manifest { schemaVersion: number; mediaType: string; config: Descriptor; layers: Descriptor[]; annotations?: Record<string, string> }
-const digest = (bytes: Uint8Array) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
-const descriptor = (bytes: Uint8Array, mediaType: string): Descriptor => ({ digest: digest(bytes), size: bytes.length, mediaType });
-const run = promisify(execFile);
 const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
 
-async function hostContent(id: string): Promise<Buffer> {
-  if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error(`invalid content digest ${id}`);
-  const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
-  if (digest(result.stdout) !== id) throw new Error(`corrupt image metadata ${id}`);
-  return result.stdout;
-}
-
-/** Preserve the original index/manifest bytes and all application descriptors. */
-async function hostImage(source: string) {
-  const name = canonicalImageReference(source);
-  const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
-  const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
-  if (!found) throw new Error(`built image ${name} is missing from the VM container store`);
-  const metadata = new Map<string, Buffer>();
-  const allowed = new Map<string, Descriptor>();
-  let configDigest: string | undefined;
-  async function visit(id: string, selected: boolean, depth = 0): Promise<Descriptor> {
-    if (depth > 4) throw new Error(`built image ${name} has a recursive manifest index`);
-    const bytes = await hostContent(id);
-    const obj = JSON.parse(bytes.toString());
-    const desc = descriptor(bytes, obj.mediaType);
-    metadata.set(id, bytes);
-    allowed.set(id, desc);
-    if (obj.config && Array.isArray(obj.layers)) {
-      const manifest = obj as Manifest;
-      for (const blob of [manifest.config, ...manifest.layers]) allowed.set(blob.digest, blob);
-      if (selected) configDigest = manifest.config.digest;
-    } else if (Array.isArray(obj.manifests)) {
-      for (const entry of obj.manifests as Descriptor[]) {
-        const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
-        await visit(entry.digest, selected && matches, depth + 1);
-      }
-    } else throw new Error(`built image ${name} has invalid image metadata`);
-    return desc;
-  }
-  const target = await visit(found, true);
-  if (!configDigest) throw new Error(`built image ${name} has no image for this VM's platform`);
-  return { target, metadata, allowed, configDigest };
-}
-
 export async function loadK3sBuildImages(
   service: string, images: readonly PreparedComponentImage[],
   gateway: string, exec: SpectestContext["exec"],

package/src/harness/registry-seed.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedRegistryImage } from "./registry-seed";
+import type { Descriptor } from "./built-image";
+
+const roots: string[] = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "registry-seed-")); roots.push(root);
+  const content = `${root}/content`; await mkdir(content);
+  const metadata = new Map<string, Buffer>(), allowed = new Map<string, Descriptor>();
+  async function blob(value: string, mediaType: string, manifest = false) {
+    const bytes = Buffer.from(value);
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    const descriptor = { digest, size: bytes.length, mediaType };
+    await writeFile(`${content}/${digest.slice(7)}`, bytes);
+    allowed.set(digest, descriptor);
+    if (manifest) metadata.set(digest, bytes);
+    return descriptor;
+  }
+  const config = await blob('{"rootfs":{"type":"layers","diff_ids":[]}}', "application/vnd.oci.image.config.v1+json");
+  const layer = await blob("layer bytes", "application/vnd.oci.image.layer.v1.tar");
+  const manifestType = "application/vnd.oci.image.manifest.v1+json";
+  const manifest = await blob(JSON.stringify({ schemaVersion: 2, mediaType: manifestType, config, layers: [layer] }), manifestType, true);
+  const indexType = "application/vnd.oci.image.index.v1+json";
+  const target = await blob(JSON.stringify({ schemaVersion: 2, mediaType: indexType, manifests: [manifest] }), indexType, true);
+  return { root, content, layer, image: { target, metadata, allowed, configDigest: config.digest } };
+}
+
+test("seeding preserves index/manifest bytes and shares blobs while repository state stays separate", async () => {
+  const { root, content, image } = await fixture();
+  for (const name of ["a", "b"]) {
+    await seedRegistryImage(`${root}/${name}`, content, "registry.test/team/code:latest", image, content);
+  }
+  const base = "/docker/registry/v2";
+  for (const id of image.allowed.keys()) {
+    const hex = id.slice(7), path = `${base}/blobs/sha256/${hex.slice(0, 2)}/${hex}/data`;
+    expect(await readFile(`${root}/a${path}`)).toEqual(await readFile(`${content}/${hex}`));
+    expect((await stat(`${root}/a${path}`)).ino).toBe((await stat(`${root}/b${path}`)).ino);
+  }
+  const tag = `${base}/repositories/team/code/_manifests/tags/latest/current/link`;
+  expect(await readFile(`${root}/a${tag}`, "utf8")).toBe(image.target.digest);
+  await writeFile(`${root}/a${tag}`, `sha256:${"f".repeat(64)}`);
+  expect(await readFile(`${root}/b${tag}`, "utf8")).toBe(image.target.digest);
+  // A new environment seeded against the same cached blobs has only its declaration.
+  await seedRegistryImage(`${root}/fresh`, content, "registry.test/team/code:latest", image, content);
+  expect(await readdir(`${root}/fresh${base}/repositories/team/code/_manifests/tags`)).toEqual(["latest"]);
+  expect(await readFile(`${root}/fresh${tag}`, "utf8")).toBe(image.target.digest);
+});
+
+test("an incomplete cached build cannot publish a usable tag", async () => {
+  const { root, content, image, layer } = await fixture();
+  await writeFile(`${content}/${layer.digest.slice(7)}`, "truncated");
+  await expect(seedRegistryImage(`${root}/data`, content, "registry.test/code:latest", image, content)).rejects.toThrow("incomplete");
+  expect(await Bun.file(`${root}/data/docker/registry/v2/repositories/code/_manifests/tags/latest/current/link`).exists()).toBe(false);
+});

package/src/harness/registry-seed.ts

@@ -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, type PreparedComponentImage } 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: string) => `/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: string, contentDirectory: string, reference: string,
+  image: Awaited<ReturnType<typeof hostImage>>,
+  mountedContent = REGISTRY_CONTENT,
+): Promise<void> {
+  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: string, value: string) => {
+    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 as NodeJS.ErrnoException).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: string, contentDirectory: string, images: readonly PreparedComponentImage[],
+): Promise<void> {
+  // 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/src/index.ts

@@ -1250,7 +1250,8 @@ export type BuildImage = (
 ) & {
   /** 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;
 };