@specific.dev/spectest 0.71.0 → 0.72.0

package/src/harness/image-cache.ts

@@ -0,0 +1,79 @@
+/**
+ * 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";
+
+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;
+  return hostPath === paths.root || hostPath.startsWith(`${paths.root}/`) || hostPath === paths.layers || hostPath.startsWith(`${paths.layers}/`);
+}

package/src/harness/volume-paths.ts

@@ -63,8 +63,9 @@ export function sanitizeSegment(p: string): string {
  * `files` does: a component cannot know the map key the user will give it,
  * and an **absolute** source gets no automatic per-service directory. A
  * component that needs one — a nested runtime keeping its store under
- * {@link NESTED_STORE_ROOT}, where two of them sharing one directory would
- * be two daemons on one metadata store — writes the token into the path.
+ * the image cache's `spectest-nested/<service>` (`image-cache.ts::nestedStoreDir`),
+ * where two of them sharing one directory would be two daemons on one
+ * metadata store — writes the token into the path.
  *
  * `workspace` is a parameter rather than a module constant so the rule is
  * testable without touching the filesystem.