@specific.dev/spectest 0.119.6 → 0.119.7

package/dist/harness/image-cache.js

@@ -1,150 +0,0 @@
-/**
- * The image cache as the guest sees it (`CONTAINER_STORE.md`).
- *
- * The control plane writes one manifest per VM at start naming the two
- * cache disks it attached: the **root** (containerd's own root,
- * read-write, this VM's clone) and the **layers** disk (read-only, one
- * EROFS file per layer, shared by every VM of a generation). Both paths
- * are fixed by the control plane; the manifest is how a harness learns
- * whether this VM carries a cache at all (the fake backend does not,
- * and neither does a server older than the cache).
- *
- * Read synchronously as well as asynchronously: a component's service
- * definition is built inside `defineEnvironment`, which is synchronous,
- * and `k3s()` decides its mounts there.
- */
-import { existsSync, readFileSync } from "node:fs";
-/** Written by `env.rs` before the harness starts. */
-export const IMAGE_CACHE_MANIFEST = "/run/spectest-image-cache.json";
-/**
- * Directory under the root disk holding a nested runtime's containerd
- * root, one per service: `<root>/spectest-nested/<service>`. The merge
- * (`image_cache/merge.rs::NESTED_DIR`) reads every store it finds there
- * exactly as it reads the disk's own.
- */
-export const NESTED_STORES_DIR = "spectest-nested";
-/** The guest's static `mkfs.erofs`, which a nested runtime's EROFS
- *  differ needs and no runtime image ships. */
-export const MKFS_EROFS_PATH = "/usr/local/bin/mkfs.erofs";
-/** The guest's adopt helper (`base.rs::STORE_ADOPT_SH`), POSIX sh so a
- *  nested runtime's busybox can run the same file. */
-export const STORE_ADOPT_PATH = "/usr/local/bin/spectest-store-adopt";
-/**
- * The BuildKit cache directory under each cache disk (`merge.rs::CACHE_DIR`):
- * on the layers disk the merged export of every earlier build, read-only;
- * on the root disk this lineage's own exports, which the merge harvests.
- */
-export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
-/**
- * One directory that is both: an overlayfs with the layers disk's cache
- * directory as the read-only lower and the root disk's as the upper,
- * mounted here by the harness when the in-VM builder comes up
- * (`daemon.ts::ensureBuildkitCacheUnion`). It is for the PROJECT'S OWN
- * BuildKit — the `/services` docs page tells it to mount this one path
- * for both of its cache flags. BuildKit's local exporter skips a blob its
- * destination already holds, and through the union every merged blob is
- * already there, so a fully cached build exports its index and manifest
- * and nothing else (a fresh directory on the root cost every
- * uncompressed layer again, 1.1 GB and 20 s for one service, measured
- * 2026-09-06). New layers land in the upper, which the merge reads.
- *
- * The harness's own service builds used it too until SDK 0.76.0; since
- * then their cache is the in-VM daemon's own state, which lives on the
- * root disk and rides the base root into the next cold build
- * (CONTAINER_STORE.md §20).
- */
-export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
-/**
- * The prefix the docs reserve for spectest in that directory's one flat
- * tag namespace. The harness tagged its service builds under it from
- * SDK 0.75.0 to 0.76.0, after Specific's `nginx-mod` service tagged its
- * own `buildctl` cache `nginx-mod` and the two overwrote each other on
- * alternate boots (2026-09-06); the harness writes no tags now, and the
- * prefix stays reserved so nothing a project names can ever collide
- * with something spectest writes there later.
- */
-export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
-/** The tag a service's Dockerfile build would carry under the reserved
- *  prefix: the service name, lowercased with anything outside `[a-z0-9-]`
- *  folded to `-`. Unused by the harness since SDK 0.76.0. */
-export function buildkitCacheTag(service) {
-    return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
-}
-function parse(raw) {
-    const parsed = JSON.parse(raw);
-    const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;
-    const layers = (parsed.disks ?? []).find((d) => d.role === "layers" && d.path)?.path;
-    return root && layers ? { root, layers } : null;
-}
-/** The cache's paths, or `null` when this VM carries none.
- *  `SPECTEST_IMAGE_CACHE_MANIFEST` points a test at another file. */
-export function imageCachePathsSync(manifest = process.env.SPECTEST_IMAGE_CACHE_MANIFEST || IMAGE_CACHE_MANIFEST) {
-    try {
-        if (!existsSync(manifest))
-            return null;
-        return parse(readFileSync(manifest, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-/** The host directory a nested runtime keeps its containerd root in. */
-export function nestedStoreDir(paths, service) {
-    return `${paths.root}/${NESTED_STORES_DIR}/${service}`;
-}
-/**
- * Is a volume's host path on a cache disk? Such a directory is a cache
- * the lineage keeps — like the container store one level up — and the
- * delta-restore teardown must not wipe it.
- */
-export function isOnImageCache(hostPath, paths) {
-    if (!paths)
-        return false;
-    // The union is the root's cache directory seen through the layers
-    // disk: wiping it would wipe the upper, i.e. this lineage's exports.
-    if (hostPath === BUILDKIT_CACHE_UNION || hostPath.startsWith(`${BUILDKIT_CACHE_UNION}/`))
-        return true;
-    return hostPath === paths.root || hostPath.startsWith(`${paths.root}/`) || hostPath === paths.layers || hostPath.startsWith(`${paths.layers}/`);
-}
-const REF_NAME = "org.opencontainers.image.ref.name";
-/**
- * The index the BuildKit cache union must show: every tag of the merged
- * cache (lower), overridden by this lineage's own exports (upper) where
- * the upper still holds the manifest.
- *
- * overlayfs shadows whole files, so an `index.json` in the upper hides
- * the lower's completely — and a root disk can carry one: the exports
- * of a lineage that built before the union existed, or an index left
- * behind with its blobs gone. Either way BuildKit then imports from an
- * index naming a few tags whose manifests may not exist, skips the
- * import, and every step runs (seen 2026-09-06: a cold build with
- * every service's cache on the layers disk and 4 stale tags in the
- * upper built everything from scratch). `upperHasBlob` says whether the
- * upper holds a manifest's blob; an upper entry without one is dropped,
- * since it would fail the whole import.
- */
-export function mergeCacheIndex(lower, upper, upperHasBlob) {
-    const byTag = new Map();
-    const untagged = [];
-    for (const m of lower?.manifests ?? []) {
-        const tag = m.annotations?.[REF_NAME];
-        if (tag)
-            byTag.set(tag, m);
-        else
-            untagged.push(m);
-    }
-    for (const m of upper?.manifests ?? []) {
-        if (!upperHasBlob(m.digest.replace(/^sha256:/, "")))
-            continue;
-        const tag = m.annotations?.[REF_NAME];
-        if (tag)
-            byTag.set(tag, m);
-        else
-            untagged.push(m);
-    }
-    return {
-        schemaVersion: 2,
-        mediaType: lower?.mediaType ?? upper?.mediaType ?? "application/vnd.oci.image.index.v1+json",
-        manifests: [...untagged, ...byTag.values()],
-    };
-}

package/src/harness/image-cache.test.ts

@@ -1,81 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import { BUILDKIT_CACHE_UNION, isOnImageCache } from "./image-cache";
-
-const paths = { root: "/var/lib/containerd", layers: "/var/lib/spectest-image-cache" };
-
-describe("isOnImageCache", () => {
-  test("the two cache disks and anything under them", () => {
-    expect(isOnImageCache("/var/lib/containerd", paths)).toBe(true);
-    expect(isOnImageCache("/var/lib/containerd/spectest-nested/k8s", paths)).toBe(true);
-    expect(isOnImageCache("/var/lib/spectest-image-cache/spectest-buildkit-cache", paths)).toBe(true);
-  });
-
-  /** The union is the root's export directory seen through the layers
-   *  disk; wiping it at a delta restore would wipe this lineage's exports. */
-  test("the BuildKit cache union counts as cache", () => {
-    expect(isOnImageCache(BUILDKIT_CACHE_UNION, paths)).toBe(true);
-    expect(isOnImageCache(`${BUILDKIT_CACHE_UNION}/blobs`, paths)).toBe(true);
-  });
-
-  test("an ordinary project volume does not", () => {
-    expect(isOnImageCache("/var/cache/spectest/volumes/db", paths)).toBe(false);
-    expect(isOnImageCache("/var/lib/containerd-not", paths)).toBe(false);
-  });
-
-  test("no cache, nothing counts", () => {
-    expect(isOnImageCache(BUILDKIT_CACHE_UNION, null)).toBe(false);
-  });
-});
-
-import { BUILDKIT_CACHE_TAG_PREFIX, buildkitCacheTag, mergeCacheIndex, type OciIndex } from "./image-cache";
-
-const entry = (tag: string, hex: string) => ({ mediaType: "application/vnd.oci.image.manifest.v1+json", digest: `sha256:${hex}`, size: 1, annotations: { "org.opencontainers.image.ref.name": tag } });
-
-describe("mergeCacheIndex", () => {
-  const lower: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a1"), entry("cli", "c1")] };
-
-  test("no upper index: the merged cache's tags, unchanged", () => {
-    const out = mergeCacheIndex(lower, null, () => false);
-    expect(out.manifests.map((m) => m.annotations?.["org.opencontainers.image.ref.name"])).toEqual(["api", "cli"]);
-  });
-
-  /** The lineage's own export of a service wins over the merged one. */
-  test("an upper entry whose manifest exists overrides the lower's tag", () => {
-    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a2")] };
-    const out = mergeCacheIndex(lower, upper, (hex) => hex === "a2");
-    const api = out.manifests.find((m) => m.annotations?.["org.opencontainers.image.ref.name"] === "api");
-    expect(api?.digest).toBe("sha256:a2");
-    expect(out.manifests).toHaveLength(2);
-  });
-
-  /** A stale upper index — blobs emptied, index left — would hide every
-   *  lower tag and fail the import; its entries are dropped instead. */
-  test("an upper entry without its manifest blob is dropped", () => {
-    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a2"), entry("worker", "w1")] };
-    const out = mergeCacheIndex(lower, upper, () => false);
-    expect(out.manifests.map((m) => m.digest)).toEqual(["sha256:a1", "sha256:c1"]);
-  });
-
-  test("a valid upper tag the lower lacks is added", () => {
-    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("worker", "w1")] };
-    const out = mergeCacheIndex(lower, upper, () => true);
-    expect(out.manifests.map((m) => m.annotations?.["org.opencontainers.image.ref.name"])).toEqual(["api", "cli", "worker"]);
-  });
-
-  /** The directory is one tag namespace shared with the project's own
-   *  BuildKit. The harness's tags are prefixed so a project tag named after
-   *  the same service sits beside it instead of replacing it. */
-  test("a project's tag and the harness's tag for the same service both survive", () => {
-    const both: OciIndex = { schemaVersion: 2, manifests: [entry("nginx-mod", "p1"), entry(buildkitCacheTag("nginx-mod"), "h1")] };
-    const out = mergeCacheIndex(both, null, () => false);
-    expect(out.manifests.map((m) => m.digest)).toEqual(["sha256:p1", "sha256:h1"]);
-  });
-});
-
-describe("buildkitCacheTag", () => {
-  test("the reserved prefix plus the normalised service name", () => {
-    expect(buildkitCacheTag("nginx-mod")).toBe(`${BUILDKIT_CACHE_TAG_PREFIX}nginx-mod`);
-    expect(buildkitCacheTag("Api_v2")).toBe("spectest/service/api-v2");
-  });
-});

package/src/harness/image-cache.ts

@@ -1,175 +0,0 @@
-/**
- * The image cache as the guest sees it (`CONTAINER_STORE.md`).
- *
- * The control plane writes one manifest per VM at start naming the two
- * cache disks it attached: the **root** (containerd's own root,
- * read-write, this VM's clone) and the **layers** disk (read-only, one
- * EROFS file per layer, shared by every VM of a generation). Both paths
- * are fixed by the control plane; the manifest is how a harness learns
- * whether this VM carries a cache at all (the fake backend does not,
- * and neither does a server older than the cache).
- *
- * Read synchronously as well as asynchronously: a component's service
- * definition is built inside `defineEnvironment`, which is synchronous,
- * and `k3s()` decides its mounts there.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-
-/** Written by `env.rs` before the harness starts. */
-export const IMAGE_CACHE_MANIFEST = "/run/spectest-image-cache.json";
-
-/** Where the cache's paths are, when this VM carries one. */
-export interface ImageCachePaths {
-  /** containerd's root: read-write, this VM's own clone. */
-  root: string;
-  /** The layers disk: read-only, shared by every VM of a generation. */
-  layers: string;
-}
-
-/**
- * Directory under the root disk holding a nested runtime's containerd
- * root, one per service: `<root>/spectest-nested/<service>`. The merge
- * (`image_cache/merge.rs::NESTED_DIR`) reads every store it finds there
- * exactly as it reads the disk's own.
- */
-export const NESTED_STORES_DIR = "spectest-nested";
-
-/** The guest's static `mkfs.erofs`, which a nested runtime's EROFS
- *  differ needs and no runtime image ships. */
-export const MKFS_EROFS_PATH = "/usr/local/bin/mkfs.erofs";
-
-/** The guest's adopt helper (`base.rs::STORE_ADOPT_SH`), POSIX sh so a
- *  nested runtime's busybox can run the same file. */
-export const STORE_ADOPT_PATH = "/usr/local/bin/spectest-store-adopt";
-
-/**
- * The BuildKit cache directory under each cache disk (`merge.rs::CACHE_DIR`):
- * on the layers disk the merged export of every earlier build, read-only;
- * on the root disk this lineage's own exports, which the merge harvests.
- */
-export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
-
-/**
- * One directory that is both: an overlayfs with the layers disk's cache
- * directory as the read-only lower and the root disk's as the upper,
- * mounted here by the harness when the in-VM builder comes up
- * (`daemon.ts::ensureBuildkitCacheUnion`). It is for the PROJECT'S OWN
- * BuildKit — the `/services` docs page tells it to mount this one path
- * for both of its cache flags. BuildKit's local exporter skips a blob its
- * destination already holds, and through the union every merged blob is
- * already there, so a fully cached build exports its index and manifest
- * and nothing else (a fresh directory on the root cost every
- * uncompressed layer again, 1.1 GB and 20 s for one service, measured
- * 2026-09-06). New layers land in the upper, which the merge reads.
- *
- * The harness's own service builds used it too until SDK 0.76.0; since
- * then their cache is the in-VM daemon's own state, which lives on the
- * root disk and rides the base root into the next cold build
- * (CONTAINER_STORE.md §20).
- */
-export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
-
-/**
- * The prefix the docs reserve for spectest in that directory's one flat
- * tag namespace. The harness tagged its service builds under it from
- * SDK 0.75.0 to 0.76.0, after Specific's `nginx-mod` service tagged its
- * own `buildctl` cache `nginx-mod` and the two overwrote each other on
- * alternate boots (2026-09-06); the harness writes no tags now, and the
- * prefix stays reserved so nothing a project names can ever collide
- * with something spectest writes there later.
- */
-export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
-
-/** The tag a service's Dockerfile build would carry under the reserved
- *  prefix: the service name, lowercased with anything outside `[a-z0-9-]`
- *  folded to `-`. Unused by the harness since SDK 0.76.0. */
-export function buildkitCacheTag(service: string): string {
-  return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
-}
-
-function parse(raw: string): ImageCachePaths | null {
-  const parsed = JSON.parse(raw) as { disks?: { role?: string; path?: string }[] };
-  const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;
-  const layers = (parsed.disks ?? []).find((d) => d.role === "layers" && d.path)?.path;
-  return root && layers ? { root, layers } : null;
-}
-
-/** The cache's paths, or `null` when this VM carries none.
- *  `SPECTEST_IMAGE_CACHE_MANIFEST` points a test at another file. */
-export function imageCachePathsSync(
-  manifest: string = process.env.SPECTEST_IMAGE_CACHE_MANIFEST || IMAGE_CACHE_MANIFEST,
-): ImageCachePaths | null {
-  try {
-    if (!existsSync(manifest)) return null;
-    return parse(readFileSync(manifest, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-/** The host directory a nested runtime keeps its containerd root in. */
-export function nestedStoreDir(paths: ImageCachePaths, service: string): string {
-  return `${paths.root}/${NESTED_STORES_DIR}/${service}`;
-}
-
-/**
- * Is a volume's host path on a cache disk? Such a directory is a cache
- * the lineage keeps — like the container store one level up — and the
- * delta-restore teardown must not wipe it.
- */
-export function isOnImageCache(hostPath: string, paths: ImageCachePaths | null): boolean {
-  if (!paths) return false;
-  // The union is the root's cache directory seen through the layers
-  // disk: wiping it would wipe the upper, i.e. this lineage's exports.
-  if (hostPath === BUILDKIT_CACHE_UNION || hostPath.startsWith(`${BUILDKIT_CACHE_UNION}/`)) return true;
-  return hostPath === paths.root || hostPath.startsWith(`${paths.root}/`) || hostPath === paths.layers || hostPath.startsWith(`${paths.layers}/`);
-}
-
-/** The shape of an OCI layout's `index.json` the BuildKit local cache
- *  exporter writes: one manifest per tag, the tag in the ref-name
- *  annotation. */
-export interface OciIndex {
-  schemaVersion?: number;
-  mediaType?: string;
-  manifests: Array<{ mediaType?: string; digest: string; size?: number; annotations?: Record<string, string> }>;
-}
-
-const REF_NAME = "org.opencontainers.image.ref.name";
-
-/**
- * The index the BuildKit cache union must show: every tag of the merged
- * cache (lower), overridden by this lineage's own exports (upper) where
- * the upper still holds the manifest.
- *
- * overlayfs shadows whole files, so an `index.json` in the upper hides
- * the lower's completely — and a root disk can carry one: the exports
- * of a lineage that built before the union existed, or an index left
- * behind with its blobs gone. Either way BuildKit then imports from an
- * index naming a few tags whose manifests may not exist, skips the
- * import, and every step runs (seen 2026-09-06: a cold build with
- * every service's cache on the layers disk and 4 stale tags in the
- * upper built everything from scratch). `upperHasBlob` says whether the
- * upper holds a manifest's blob; an upper entry without one is dropped,
- * since it would fail the whole import.
- */
-export function mergeCacheIndex(lower: OciIndex | null, upper: OciIndex | null, upperHasBlob: (hex: string) => boolean): OciIndex {
-  const byTag = new Map<string, OciIndex["manifests"][number]>();
-  const untagged: OciIndex["manifests"] = [];
-  for (const m of lower?.manifests ?? []) {
-    const tag = m.annotations?.[REF_NAME];
-    if (tag) byTag.set(tag, m);
-    else untagged.push(m);
-  }
-  for (const m of upper?.manifests ?? []) {
-    if (!upperHasBlob(m.digest.replace(/^sha256:/, ""))) continue;
-    const tag = m.annotations?.[REF_NAME];
-    if (tag) byTag.set(tag, m);
-    else untagged.push(m);
-  }
-  return {
-    schemaVersion: 2,
-    mediaType: lower?.mediaType ?? upper?.mediaType ?? "application/vnd.oci.image.index.v1+json",
-    manifests: [...untagged, ...byTag.values()],
-  };
-}