From 966a877fe5604def49d57c7ac64a046104fe24e3 Mon Sep 17 00:00:00 2001 From: codethief Date: Fri, 14 Aug 2026 18:52:49 +0200 Subject: [PATCH 1/5] Breaking change: Allow using OCI images as rootfs; rename `resources.rootfsSize` Rename/move `resources.rootfsSize` to `rootfs.size`. --- CHANGELOG.md | 18 ++ docs/Configuration.md | 38 ++- src/config/defaults.test.ts | 16 +- src/config/defaults.ts | 18 +- src/config/merge.test.ts | 125 +++++++- src/config/merge.ts | 16 +- src/config/resolve.test.ts | 61 +++- src/config/resolve.ts | 18 ++ src/config/schema.test.ts | 114 ++++++- src/config/schema.ts | 117 ++++++- src/core/image.test.ts | 588 ++++++++++++++++++++++++++++++++++++ src/core/image.ts | 361 ++++++++++++++++++++++ src/core/session.ts | 45 ++- 13 files changed, 1491 insertions(+), 44 deletions(-) create mode 100644 src/core/image.test.ts create mode 100644 src/core/image.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index a3c2437..47bea0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Unreleased +## Breaking changes +- Config: Replaced `resources.rootfsSize` with a new `rootfs.size` setting (see + below) and added stricter validation. The old field accepted any non-empty + string; the new one enforces a QEMU-compatible size syntax (a positive integer + with a *mandatory* K/M/G/T suffix). + + +## Features +- Config: Add new `rootfs.image` setting to expose a [Gondolin + feature](https://earendil-works.github.io/gondolin/custom-images/) that allows + configuring a custom OCI container image to be used for the VM's rootfs + instead of Gondolin's default `alpine-base` image. (The kernel is still taken + from Alpine, though.)) +- Config: The new `rootfs.size` setting can be used both with the default VM + rootfs (same behavior as the old `resources.rootfsSize`), in which case it + grows the file system after boot (using `resize2fs`), or with a custom image + (`rootfs.image`), in which case the size gets baked in at build time. + # 0.6.0 (2026-10-09) diff --git a/docs/Configuration.md b/docs/Configuration.md index 1161af7..6bb805d 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -18,6 +18,9 @@ general, child settings override parent settings, except in the following cases: - Env vars, mounts, volumes get merged (shallow merge). - Boot commands are concatenated (parent commands run first). - Network: Child network mode overrides parent mode; allowed hosts are merged. +- `rootfs` gets merged field by field, so a child may set `size` without + restating `image` (or vice versa). `image` itself is *not* merged field-wise: + a child that specifies it replaces the parent's block entirely. ## Config options @@ -36,7 +39,7 @@ is validated): // $PWD lets you mount wherever you launched Tuor from: { "hostPath": "$PWD", "guestPath": "/workspace", "mode": "readwrite" } ], - "resources": { "rootfsSize": "${ROOTFS_SIZE}" }, + "rootfs": { "size": "${ROOTFS_SIZE}" }, // Use $$ for a literal dollar sign: "env": { "PROMPT": "$$ " } } @@ -109,12 +112,33 @@ that is not set on the host is an error. // `qemu.cpu` (the emulated CPU model). "resources": { "cpus": 4, // vCPU count (positive integer) - "memory": "2G", // RAM, QEMU syntax (e.g. "512M", "2G") - // Minimum virtual disk size (COW overlay, so actual host usage stays - // sparse). Note that the virtual disk will be discarded on VM shutdown, - // so it is not meant for persisting data across VM boots. (Use mounts & - // volumes, instead!) - "rootfsSize": "2G" + "memory": "2G" // RAM, QEMU syntax (e.g. "512M", "2G") + }, + "rootfs": { + "image": { + // Whole OCI image ref (`:tag` or `@sha256:…`). Omit the whole `image` + // block to boot Gondolin's default alpine-base image. + "ref": "docker.io/library/debian:bookworm-slim", + // Optional: container engine used to pull & export the image. Omit to let + // Gondolin auto-detect (docker, else podman). + "engine": "docker", + // Optional (default "if-not-present"): where the image comes from on the + // runs that build. "always" to re-pull every time, "never" to use the + // engine's local image store only (and fail if the image isn't in it). + "pullPolicy": "if-not-present", + // Optional (default "if-not-present"): whether to reuse the guest assets + // Tuor cached for this `ref`. "always" rebuilds them every run. Note that + // `ref`, not the image contents, is the cache identity, so a moving tag + // needs *this* set to "always" — `pullPolicy` alone won't refresh + // anything, because a cache hit skips the build that would pull. + "buildPolicy": "if-not-present" + }, + // Optional: total rootfs size — a positive integer plus a *mandatory* + // K/M/G/T suffix. Grow-only (never shrinks). + // Note that the virtual disk is discarded on VM shutdown, so it is not + // meant for persisting data across VM boots. (Use mounts & volumes, + // instead!) + "size": "8G" }, // Guest user (numeric uid/gid) the shell runs under and that mounted // directories are presented as owned by. `homedir` (optional, default /root) diff --git a/src/config/defaults.test.ts b/src/config/defaults.test.ts index 515863d..30b7abf 100644 --- a/src/config/defaults.test.ts +++ b/src/config/defaults.test.ts @@ -75,16 +75,28 @@ describe("applyConfigDefaults", () => { }); }); + describe("rootfs", () => { + test("leaves an absent rootfs absent (no empty object synthesized)", () => { + expect(applyConfigDefaults(config()).rootfs).toBeUndefined(); + }); + + test("invents no image for a rootfs that only sets size", () => { + const result = applyConfigDefaults(config({ rootfs: { size: "8G" } })); + expect(result.rootfs).toEqual({ size: "8G" }); + expect(result.rootfs && "image" in result.rootfs).toBe(false); + }); + }); + test("leaves other fields untouched", () => { const input = config({ guestUser: { uid: 0, gid: 0 }, workdir: "/work", - resources: { rootfsSize: "2G" }, + resources: { memory: "2G" }, }); const result = applyConfigDefaults(input); expect(result.guestUser).toEqual({ uid: 0, gid: 0, homedir: "/root" }); expect(result.workdir).toBe("/work"); - expect(result.resources).toEqual({ rootfsSize: "2G" }); + expect(result.resources).toEqual({ memory: "2G" }); }); test("does not mutate the input config", () => { diff --git a/src/config/defaults.ts b/src/config/defaults.ts index cbd598a..5d9e0f8 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -41,17 +41,19 @@ export type DefaultedConfig = Omit< /** * Fill the config-level defaults that don't come from the arktype schema: - * `guestUser`, `workdir`, and `network` (block-all when omitted). + * `guestUser`, `workdir` and `network` (block-all when omitted). * - * `guestUser`/`workdir` are defaulted *here* rather than in the schema so that a - * child config layer that omits them doesn't clobber a value inherited from a - * parent layer during merge (their "omitted" would otherwise be indistinguish- - * able from an explicit default). This must run after `mergeConfigs`. + * These are defaulted *here* rather than in the schema so that a child config + * layer that omits them doesn't clobber a value inherited from a parent layer + * during merge (their "omitted" would otherwise be indistinguishable from an + * explicit default, because `parseConfig` runs per layer, before the merge). + * This must run after `mergeConfigs`. * * Pure and dependency-free. The remaining schema defaults (mount `mode`, - * `nixLd`) are already applied by `parseConfig`; computed conversions (path - * expansion, env/secret split, nix→mounts, overlay state dirs, …) are *not* - * defaults and stay in {@link createSessionSpecFromConfig}. + * `nixLd`, `rootfs.image.pullPolicy`) are already applied by `parseConfig`; + * computed conversions (path expansion, env/secret split, nix→mounts, overlay + * state dirs, …) are *not* defaults and stay in + * {@link createSessionSpecFromConfig}. */ export function applyConfigDefaults(config: TuorConfig): DefaultedConfig { const guestUser = config.guestUser ?? DEFAULT_GUEST_USER; diff --git a/src/config/merge.test.ts b/src/config/merge.test.ts index fdd6f33..ac704c1 100644 --- a/src/config/merge.test.ts +++ b/src/config/merge.test.ts @@ -1,6 +1,11 @@ import { describe, expect, test } from "vitest"; import { type ConfigLayer, findAllConfigDirs, mergeConfigs } from "./merge.ts"; -import type { MountConfig, TuorConfig } from "./schema.ts"; +import { + type MountConfig, + parseConfig, + type RootfsImageConfig, + type TuorConfig, +} from "./schema.ts"; /** * Minimal valid config, matching what parseConfig returns: user/workdir carry @@ -25,6 +30,17 @@ function mount( return { mode: "readonly", ...overrides }; } +/** Rootfs image with its required policy defaults. */ +function withPolicyDefaults( + overrides: Partial & { ref: string }, +): RootfsImageConfig { + return { + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + ...overrides, + }; +} + describe("findAllConfigDirs", () => { test("returns home config first, then ancestors root-to-closest", () => { const existing = new Set([ @@ -429,17 +445,17 @@ describe("mergeConfigs", () => { test("distinct fields across layers are combined", () => { const result = mergeConfigs([ layer("/a", { resources: { memory: "1G" } }), - layer("/b", { resources: { rootfsSize: "4G" } }), + layer("/b", { resources: { cpus: 4 } }), ]); - expect(result.resources).toEqual({ memory: "1G", rootfsSize: "4G" }); + expect(result.resources).toEqual({ memory: "1G", cpus: 4 }); }); - test("child rootfsSize overrides parent", () => { + test("child memory overrides parent", () => { const result = mergeConfigs([ - layer("/a", { resources: { rootfsSize: "1G" } }), - layer("/b", { resources: { rootfsSize: "4G" } }), + layer("/a", { resources: { memory: "1G" } }), + layer("/b", { resources: { memory: "4G" } }), ]); - expect(result.resources).toEqual({ rootfsSize: "4G" }); + expect(result.resources).toEqual({ memory: "4G" }); }); test("parent resources used when child has none", () => { @@ -456,6 +472,101 @@ describe("mergeConfigs", () => { }); }); + describe("rootfs: field merge, atomic image", () => { + test("parent rootfs used when child has none", () => { + const result = mergeConfigs([ + layer("/a", { + rootfs: { image: withPolicyDefaults({ ref: "debian:trixie" }) }, + }), + layer("/b"), + ]); + expect(result.rootfs).toEqual({ + image: withPolicyDefaults({ ref: "debian:trixie" }), + }); + }); + + test("child rootfs used when parent has none", () => { + const result = mergeConfigs([ + layer("/a"), + layer("/b", { rootfs: { size: "8G" } }), + ]); + expect(result.rootfs).toEqual({ size: "8G" }); + }); + + test("no rootfs when neither layer has it", () => { + const result = mergeConfigs([layer("/a"), layer("/b")]); + expect(result.rootfs).toBeUndefined(); + }); + + test("child size overrides parent size", () => { + const result = mergeConfigs([ + layer("/a", { rootfs: { size: "2G" } }), + layer("/b", { rootfs: { size: "8G" } }), + ]); + expect(result.rootfs).toEqual({ size: "8G" }); + }); + + test("child size keeps the parent's image", () => { + const result = mergeConfigs([ + layer("/a", { + rootfs: { image: withPolicyDefaults({ ref: "debian:trixie" }) }, + }), + layer("/b", { rootfs: { size: "8G" } }), + ]); + expect(result.rootfs).toEqual({ + image: withPolicyDefaults({ ref: "debian:trixie" }), + size: "8G", + }); + }); + + test("child image replaces the parent's entirely", () => { + const result = mergeConfigs([ + layer("/a", { + rootfs: { + image: withPolicyDefaults({ + ref: "debian:trixie", + engine: "podman", + }), + }, + }), + layer("/b", { + rootfs: { image: withPolicyDefaults({ ref: "alpine:3.23" }) }, + }), + ]); + // `engine` is *not* inherited: `image` is atomic, so re-pointing `ref` + // means re-stating everything else you want with it. + expect(result.rootfs?.image).toEqual( + withPolicyDefaults({ ref: "alpine:3.23" }), + ); + }); + + /** + * Goes through `parseConfig` per layer, as load.ts does, so the child's + * `pullPolicy` default is materialized before the merge. Since `image` is + * atomic, that default replaces the parent's explicit value rather than + * being interleaved with it. + */ + test("child image drops the parent's explicit pullPolicy", () => { + const result = mergeConfigs([ + { + config: parseConfig({ + rootfs: { image: { ref: "debian:trixie", pullPolicy: "always" } }, + }), + configDir: "/a", + }, + { + config: parseConfig({ rootfs: { image: { ref: "alpine:3.23" } } }), + configDir: "/b", + }, + ]); + expect(result.rootfs?.image).toEqual({ + ref: "alpine:3.23", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }); + }); + }); + describe("three-level merge", () => { test("most specific wins for scalars, arrays concatenate across all layers", () => { const result = mergeConfigs([ diff --git a/src/config/merge.ts b/src/config/merge.ts index fc61fa3..42f59e4 100644 --- a/src/config/merge.ts +++ b/src/config/merge.ts @@ -7,6 +7,7 @@ import type { NetworkConfig, QemuConfig, ResourcesConfig, + RootfsConfig, TuorConfig, } from "./schema.ts"; @@ -89,7 +90,7 @@ export function mergeConfigs(layers: ConfigLayer[]): TuorConfig { function mergeTwoConfigs(parent: TuorConfig, child: TuorConfig): TuorConfig { return { // Scalars: child wins, falling back to parent when the child omits the - // field. guestUser/workdir carry no schema default anymore, so "omitted" is + // field. guestUser/workdir carry no schema default, so "omitted" is // genuinely undefined here — otherwise a child layer's silently-defaulted // value would clobber a value inherited from a parent layer. Their defaults // are applied post-merge in applyConfigDefaults. @@ -106,6 +107,9 @@ function mergeTwoConfigs(parent: TuorConfig, child: TuorConfig): TuorConfig { // Resources: deep-merge each field, child field wins ...mergeResources(parent.resources, child.resources), + // Rootfs: merge field by field, child wins (`image` is atomic) + ...mergeRootfs(parent.rootfs, child.rootfs), + // Arrays: concatenate ...mergeArrayField(parent.mounts, child.mounts, "mounts"), ...mergeArrayField(parent.volumes, child.volumes, "volumes"), @@ -206,6 +210,16 @@ function mergeResources( return { resources: { ...parentResources, ...childResources } }; } +function mergeRootfs( + parentRootfs: RootfsConfig | undefined, + childRootfs: RootfsConfig | undefined, +): { rootfs: RootfsConfig } | Record { + if (!parentRootfs && !childRootfs) return {} as Record; + // Shallow merge: `size` is a scalar and `image` is atomic, so child wins for + // whichever keys it actually carries. + return { rootfs: { ...parentRootfs, ...childRootfs } }; +} + function mergeStringArrayField( parentArr: string[] | undefined, childArr: string[] | undefined, diff --git a/src/config/resolve.test.ts b/src/config/resolve.test.ts index 63a8164..69e2e2d 100644 --- a/src/config/resolve.test.ts +++ b/src/config/resolve.test.ts @@ -485,12 +485,11 @@ describe("createSessionSpecFromConfig", () => { test("passes the resources config through verbatim", () => { const spec = resolve({ - resources: { memory: "2G", cpus: 4, rootfsSize: "8G" }, + resources: { memory: "2G", cpus: 4 }, }); expect(spec.resources).toEqual({ memory: "2G", cpus: 4, - rootfsSize: "8G", }); }); @@ -504,6 +503,64 @@ describe("createSessionSpecFromConfig", () => { expect(spec.resources).toBeUndefined(); }); }); + + describe("rootfs resolution", () => { + test("omits rootfs when nothing is configured", () => { + const spec = resolve({}); + expect(spec.rootfs).toBeUndefined(); + }); + + test("passes the image and size through", () => { + const spec = resolve({ + rootfs: { + image: { + ref: "docker.io/library/debian:bookworm-slim", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }, + size: "8G", + }, + }); + expect(spec.rootfs).toEqual({ + image: { + ref: "docker.io/library/debian:bookworm-slim", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }, + size: "8G", + }); + }); + + test("preserves explicit policies and engine", () => { + const spec = resolve({ + rootfs: { + image: { + ref: "alpine:3.23", + engine: "podman", + pullPolicy: "always", + buildPolicy: "always", + }, + }, + }); + expect(spec.rootfs?.image).toEqual({ + ref: "alpine:3.23", + engine: "podman", + pullPolicy: "always", + buildPolicy: "always", + }); + }); + + /** `size` stays a string here — core decides bake-vs-grow. */ + test("passes a bare size through without inventing an image", () => { + const spec = resolve({ rootfs: { size: "512M" } }); + expect(spec.rootfs).toEqual({ size: "512M" }); + }); + + test("treats an empty rootfs config as unset", () => { + const spec = resolve({ rootfs: {} }); + expect(spec.rootfs).toBeUndefined(); + }); + }); }); describe("_resolveEnv", () => { diff --git a/src/config/resolve.ts b/src/config/resolve.ts index c1284ec..640fb57 100644 --- a/src/config/resolve.ts +++ b/src/config/resolve.ts @@ -10,6 +10,7 @@ import { validateMounts } from "../core/mounts.ts"; import type { QemuSpec, ResourcesSpec, + RootfsSpec, SecretSpec, SessionSpec, } from "../core/session.ts"; @@ -117,6 +118,7 @@ export function createSessionSpecFromConfig( const qemu = resolveQemu(config.qemu); const resources = resolveResources(config.resources); + const rootfs = resolveRootfs(config.rootfs); // Nix's own boot commands (currently just the nix-ld symlink) run first so // that user-provided bootCommands can already rely on the setup they do. @@ -131,6 +133,7 @@ export function createSessionSpecFromConfig( mounts: allMounts, ...(volumes.length > 0 ? { volumes } : {}), ...(resources ? { resources } : {}), + ...(rootfs ? { rootfs } : {}), ...(hasEnv ? { env: mergedEnv } : {}), ...(hasSecrets ? { secrets } : {}), ...(qemu ? { qemu } : {}), @@ -277,6 +280,21 @@ function resolveResources( return { ...resources }; } +/** + * Pass the configured rootfs through verbatim. (Defaults have already been + * applied!) + * + * `size` stays the QEMU-syntax string here: whether it is baked into a built + * image (converted to MB) or grown at runtime is core's dispatch to make, in + * `runSession`. + */ +function resolveRootfs( + rootfs: DefaultedConfig["rootfs"], +): RootfsSpec | undefined { + if (!rootfs || Object.keys(rootfs).length === 0) return undefined; + return { ...rootfs }; +} + function resolveVolumeConfig( v: VolumeConfig, configDir: string, diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts index 55501ad..fe5dd66 100644 --- a/src/config/schema.test.ts +++ b/src/config/schema.test.ts @@ -369,14 +369,13 @@ describe("parseConfig", () => { }); describe("resources config", () => { - test("accepts memory, cpus and rootfsSize", () => { + test("accepts memory and cpus", () => { const config = parseConfig({ - resources: { memory: "2G", cpus: 4, rootfsSize: "8G" }, + resources: { memory: "2G", cpus: 4 }, }); expect(config.resources).toEqual({ memory: "2G", cpus: 4, - rootfsSize: "8G", }); }); @@ -396,6 +395,95 @@ describe("parseConfig", () => { }); }); + describe("rootfs config", () => { + test("accepts an image with just a ref", () => { + const config = parseConfig({ + rootfs: { image: { ref: "docker.io/library/debian:bookworm-slim" } }, + }); + expect(config.rootfs).toEqual({ + image: { + ref: "docker.io/library/debian:bookworm-slim", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }, + }); + }); + + test("defaults an omitted pullPolicy to if-not-present", () => { + const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23" } } }); + expect(config.rootfs?.image?.pullPolicy).toBe("if-not-present"); + }); + + test("defaults an omitted buildPolicy to if-not-present", () => { + const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23" } } }); + expect(config.rootfs?.image?.buildPolicy).toBe("if-not-present"); + }); + + test.each([ + "if-not-present", + "always", + ])("accepts an explicit buildPolicy: %s", (buildPolicy) => { + const config = parseConfig({ + rootfs: { image: { ref: "alpine:3.23", buildPolicy } }, + }); + expect(config.rootfs?.image?.buildPolicy).toBe(buildPolicy); + }); + + test("rejects buildPolicy 'never'", () => { + expect(() => + parseConfig({ + rootfs: { image: { ref: "alpine:3.23", buildPolicy: "never" } }, + }), + ).toThrow(); + }); + + test.each([ + "if-not-present", + "always", + "never", + ])("accepts an explicit pullPolicy: %s", (pullPolicy) => { + const config = parseConfig({ + rootfs: { image: { ref: "alpine:3.23", pullPolicy } }, + }); + expect(config.rootfs?.image?.pullPolicy).toBe(pullPolicy); + }); + + test.each(["docker", "podman"])("accepts engine: %s", (engine) => { + const config = parseConfig({ + rootfs: { image: { ref: "alpine:3.23", engine } }, + }); + expect(config.rootfs?.image?.engine).toBe(engine); + }); + + test("accepts a size alongside an image", () => { + const config = parseConfig({ + rootfs: { image: { ref: "alpine:3.23" }, size: "8G" }, + }); + expect(config.rootfs).toEqual({ + image: { + ref: "alpine:3.23", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }, + size: "8G", + }); + }); + + test("accepts a bare size without an image", () => { + const config = parseConfig({ rootfs: { size: "512M" } }); + expect(config.rootfs).toEqual({ size: "512M" }); + }); + + test.each(["512M", "8g", "1T", "1048576K"])("accepts size: %s", (size) => { + expect(parseConfig({ rootfs: { size } }).rootfs).toEqual({ size }); + }); + + test("omits rootfs when not specified", () => { + const config = parseConfig({}); + expect(config.rootfs).toBeUndefined(); + }); + }); + test.each([ ["qemu unknown field", { qemu: { foo: "bar" } }], ["qemu empty accel", { qemu: { accel: "" } }], @@ -406,6 +494,26 @@ describe("parseConfig", () => { ["resources non-integer cpus", { resources: { cpus: 1.5 } }], ["resources zero cpus", { resources: { cpus: 0 } }], ["resources non-number cpus", { resources: { cpus: "4" } }], + ["rootfs unknown field", { rootfs: { foo: "bar" } }], + ["rootfs image without ref", { rootfs: { image: { engine: "docker" } } }], + ["rootfs image empty ref", { rootfs: { image: { ref: "" } } }], + [ + "rootfs image unknown field", + { rootfs: { image: { ref: "alpine", platform: "linux/amd64" } } }, + ], + [ + "rootfs image bad engine", + { rootfs: { image: { ref: "alpine", engine: "containerd" } } }, + ], + [ + "rootfs image bad pullPolicy", + { rootfs: { image: { ref: "alpine", pullPolicy: "sometimes" } } }, + ], + ["rootfs malformed size", { rootfs: { size: "8GB" } }], + ["rootfs size with a space", { rootfs: { size: "8 G" } }], + ["rootfs empty size", { rootfs: { size: "" } }], + ["rootfs non-string size", { rootfs: { size: 8192 } }], + ["rootfs size without a unit suffix", { rootfs: { size: "2048" } }], [ "relative guestPath", { mounts: [{ hostPath: "/foo", guestPath: "rel" }] }, diff --git a/src/config/schema.ts b/src/config/schema.ts index 99d4a9c..a77d600 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -1,6 +1,7 @@ import { existsSync } from "node:fs"; import { dirname, join, resolve } from "node:path"; import { scope, type } from "arktype"; +import { SIZE_FORMAT } from "../core/image.ts"; const types = scope({ // -------------------------------------------------------------------------- @@ -46,10 +47,15 @@ const types = scope({ "qemu?": "QemuConfig", /** - * VM resource sizing (RAM, vCPU count, rootfs disk size). + * VM resource sizing (RAM, vCPU count). */ "resources?": "ResourcesConfig", + /** + * Root filesystem configuration: base image and/or size. + */ + "rootfs?": "RootfsConfig", + /** * The user (as numeric uid/gid) that the guest shell runs under. */ @@ -317,14 +323,109 @@ const types = scope({ * from `QemuConfig.cpu` (the emulated CPU *model*)! */ "cpus?": "number.integer >= 1", + }, + + // -------------------------------------------------------------------------- + // Root filesystem + // -------------------------------------------------------------------------- + + /** + * Root filesystem: which image the guest boots from and how big its disk is. + * + * NOTE: This is Tuor's config type — it is distinct from Gondolin's own + * build-time `RootfsConfig` (`{ label, sizeMb }`) and from Gondolin's runtime + * `rootfs.{mode,size}` VM option, both of which it feeds into. + */ + RootfsConfig: { + "+": "reject", + /** + * Source image for the guest rootfs. Omit to boot Gondolin's default + * `alpine-base` image. + */ + "image?": "RootfsImageConfig", + /** + * Target rootfs size in QEMU-compatible syntax: a positive integer with a + * *mandatory* K/M/G/T suffix, e.g. "512M", "8G". + * + * The setting will only ever grow the rootfs, never shrink it, and is + * applied at different stages, depending on `rootfs.image`: + * - No custom `image` set => The disk is *grown* at runtime (using + * Gondolin's `rootfs.size`), which requires `resize2fs` to be installed + * in the guest. + * - Custom `image` set => The size gets baked into the image at build time + * (Gondolin's `rootfs.sizeMb`), so no in-guest `resize2fs` is needed + * (which minimal/distroless images typically lack). + * + * The filesystem is sparse either way, so a large (but mostly empty) rootfs + * won't take up more host disk space. + */ + "size?": type("string > 0").matching(SIZE_FORMAT), + }, + /** + * An optional OCI image to build the guest rootfs from. Essentially a config + * setting for https://earendil-works.github.io/gondolin/custom-images/ . + * + * Note that the choice of image doesn't affect the guest kernel which is + * always taken from Alpine. + * + * Tuor builds the VM image from the OCI image on first use and caches them in + * Gondolin's content-addressed image store (`~/.cache/gondolin/images`, or + * `$GONDOLIN_IMAGE_STORE`) under a `tuor/:latest` ref, where `` + * covers the image ref, the architecture, `rootfs.size` and the Gondolin + * version. The caching can be fine-tuned using `buildPolicy` and + * `pullPolicy`, see below. + * + * Host requirements: + * - `cpio` + * - `lz4` + * - `mke2fs` or `mkfs.ext4` + * - `debugfs` + * + * On Debian/Ubuntu: `apt install cpio lz4 e2fsprogs`. + */ + RootfsImageConfig: { + "+": "reject", + /** + * The OCI image to be used for the rootfs. The architecture is always the + * host's — cross-arch builds are not supported. + * + * Format: `repo/name[:tag]` or `repo/name@sha256:…` + */ + ref: "string > 0", /** - * Minimum virtual disk size for the rootfs (e.g. "2G", "512M"). The COW - * overlay will be grown to at least this size before boot. Actual host disk - * usage remains sparse (only written pages cost space). The config option - * maps to Gondolin's `rootfs.size` and defaults to the size of the base - * image used by Gondolin (no minimum growth). + * Container engine used to pull & export the OCI image. Maps to Gondolin's + * `oci.runtime`. Omit to let Gondolin auto-detect (default docker, else + * podman). + */ + "engine?": "'docker' | 'podman'", + /** + * When to trigger a rebuild of the rootfs image from the OCI image. Allowed + * values: + * + * - always: rebuild the rootfs image every run. Combine with `pullPolicy` + * to say where the image itself comes from — "always" to track a moving + * tag, "never" to rebuild from whatever is in the local store. + * - if-not-present: build once per (ref, arch, size, Gondolin version), + * then reuse. Since `ref` — not the OCI image contents — is the cache + * identity, a changed `:latest` tag in your engine's local image store + * will *not* invalidate the VM build. + * + * Note that Tuor currently does not prune old images from Gondolin's image + * store, nor from Docker/Podman's. + */ + buildPolicy: "'always' | 'if-not-present' = 'if-not-present'", + /** + * Whether to fetch `ref` fresh from its registry, for the runs on which + * Tuor actually builds the rootfs image (see `buildPolicy`). Maps to + * Gondolin's `oci.pullPolicy`. Allowed values: + * + * - always: pull afresh, so a mutable tag picks up its current contents. + * - if-not-present: pull only when the engine's local image store has no + * `ref`. Mutable tags like `:latest` are not refreshed. + * - never: use the engine's local image store only, and fail if `ref` isn't + * in it. */ - "rootfsSize?": "string > 0", + pullPolicy: "'always' | 'if-not-present' | 'never' = 'if-not-present'", }, }).export(); @@ -335,6 +436,8 @@ export type MountConfig = typeof types.MountConfig.infer; export type NixConfig = typeof types.NixConfig.infer; export type QemuConfig = typeof types.QemuConfig.infer; export type ResourcesConfig = typeof types.ResourcesConfig.infer; +export type RootfsConfig = typeof types.RootfsConfig.infer; +export type RootfsImageConfig = typeof types.RootfsImageConfig.infer; export type NetworkConfig = typeof types.NetworkConfig.infer; export type EnvFromHost = typeof types.EnvFromHost.infer; export type EnvSecret = typeof types.EnvSecret.infer; diff --git a/src/core/image.test.ts b/src/core/image.test.ts new file mode 100644 index 0000000..a41e6f9 --- /dev/null +++ b/src/core/image.test.ts @@ -0,0 +1,588 @@ +import { existsSync } from "node:fs"; +import type { + Architecture, + BuildConfig, + BuildOptions, + BuildResult, + LocalImageRef, +} from "@earendil-works/gondolin"; +import { getDefaultBuildConfig } from "@earendil-works/gondolin"; +import { describe, expect, test } from "vitest"; +import { + _hasCachedAssets, + _hostArch, + _preflightBuildTools, + _tuorImageRef, + ensureImageAssets, + type ImageDeps, + parseSizeToMb, + type RootfsImageSpec, +} from "./image.ts"; + +function spec(overrides: Partial = {}): RootfsImageSpec { + return { + ref: "docker.io/library/debian:bookworm-slim", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + ...overrides, + }; +} + +function ref( + reference: string, + targets: LocalImageRef["targets"], +): LocalImageRef { + return { reference, targets, updatedAt: "2026-01-01T00:00:00.000Z" }; +} + +/** Tool probe over an explicit allowlist of "installed" commands. */ +function probe(installed: string[]): (command: string) => boolean { + return (command) => installed.includes(command); +} + +const ALL_TOOLS = [ + "docker", + "podman", + "mke2fs", + "mkfs.ext4", + "debugfs", + "cpio", + "lz4", +]; + +describe("_hostArch", () => { + test.each([ + ["arm64", "aarch64"], + ["x64", "x86_64"], + ])("maps %s to %s", (nodeArch, expected) => { + expect(_hostArch(nodeArch)).toBe(expected); + }); + + test.each(["ia32", "riscv64", "s390x"])("rejects %s", (nodeArch) => { + expect(() => _hostArch(nodeArch)).toThrow(/Unsupported host architecture/); + }); +}); + +describe("parseSizeToMb", () => { + test.each([ + ["8G", 8192], + ["512M", 512], + ["1T", 1024 * 1024], + ["1048576K", 1024], + ])("converts %s to %i MB", (size, expected) => { + expect(parseSizeToMb(size)).toBe(expected); + }); + + test("rounds partial megabytes up", () => { + expect(parseSizeToMb("1500K")).toBe(2); + }); + + test("never returns less than 1 MB", () => { + expect(parseSizeToMb("1K")).toBe(1); + }); + + test("accepts lowercase unit suffixes", () => { + expect(parseSizeToMb("4g")).toBe(4096); + }); + + test.each([ + "8GB", + "8 G", + "", + "eight", + "-8G", + "8.5G", + "2097152", // Unit suffix is mandatory + ])("rejects %o", (size) => { + expect(() => parseSizeToMb(size)).toThrow(/Invalid rootfs size/); + }); +}); + +describe("_tuorImageRef", () => { + test("is stable for identical inputs", () => { + expect(_tuorImageRef(spec(), "x86_64", "0.12.0")).toBe( + _tuorImageRef(spec(), "x86_64", "0.12.0"), + ); + }); + + test("produces a ref name Gondolin accepts", () => { + // Gondolin allows [A-Za-z0-9._/-] in names and requires each segment to + // start alphanumeric — hence hashing the OCI ref instead of embedding it. + expect(_tuorImageRef(spec(), "aarch64", "0.12.0")).toMatch( + /^tuor\/[0-9a-f]{32}:latest$/, + ); + }); + + test.each([ + [ + "the OCI ref", + spec({ ref: "docker.io/library/alpine:3.23" }), + "x86_64", + "0.12.0", + ], + ["the arch", spec(), "aarch64", "0.12.0"], + ["the baked size", spec({ rootfsSizeMb: 8192 }), "x86_64", "0.12.0"], + ["the gondolin version", spec(), "x86_64", "0.13.0"], + ] as const)("changes when %s changes", (_what, s, arch, version) => { + expect(_tuorImageRef(s, arch, version)).not.toBe( + _tuorImageRef(spec(), "x86_64", "0.12.0"), + ); + }); + + /** engine only affects *how* identical assets are produced. */ + test("ignores the container engine", () => { + expect(_tuorImageRef(spec({ engine: "podman" }), "x86_64", "0.12.0")).toBe( + _tuorImageRef(spec({ engine: "docker" }), "x86_64", "0.12.0"), + ); + }); + + /** Both policies pick *when* to (re)fetch and (re)build, not what comes out. */ + test("ignores the pull policy", () => { + expect( + _tuorImageRef(spec({ pullPolicy: "always" }), "x86_64", "0.12.0"), + ).toBe(_tuorImageRef(spec({ pullPolicy: "never" }), "x86_64", "0.12.0")); + }); + + test("ignores the build policy", () => { + expect( + _tuorImageRef(spec({ buildPolicy: "always" }), "x86_64", "0.12.0"), + ).toBe( + _tuorImageRef( + spec({ buildPolicy: "if-not-present" }), + "x86_64", + "0.12.0", + ), + ); + }); +}); + +describe("_hasCachedAssets", () => { + const TUOR_REF = "tuor/abc:latest"; + + test("finds a ref present for our arch", () => { + const refs = [ref(TUOR_REF, { x86_64: "build-1" })]; + expect(_hasCachedAssets(TUOR_REF, "x86_64", refs)).toBe(true); + }); + + test("reports a miss when the ref is absent", () => { + expect(_hasCachedAssets(TUOR_REF, "x86_64", [])).toBe(false); + }); + + test("reports a miss when the ref exists only for another arch", () => { + const refs = [ref(TUOR_REF, { aarch64: "build-1" })]; + expect(_hasCachedAssets(TUOR_REF, "x86_64", refs)).toBe(false); + }); + + test("ignores refs belonging to other images", () => { + const refs = [ref("tuor/other:latest", { x86_64: "build-1" })]; + expect(_hasCachedAssets(TUOR_REF, "x86_64", refs)).toBe(false); + }); +}); + +describe("_preflightBuildTools", () => { + test("passes when every tool is present", () => { + expect(() => + _preflightBuildTools(undefined, probe(ALL_TOOLS)), + ).not.toThrow(); + }); + + /** + * Gondolin's findMke2fs accepts either binary, so requiring `mke2fs` + * specifically would false-fail hosts that ship only `mkfs.ext4`. + */ + test("accepts mkfs.ext4 in place of mke2fs", () => { + const installed = ALL_TOOLS.filter((t) => t !== "mke2fs"); + expect(() => + _preflightBuildTools(undefined, probe(installed)), + ).not.toThrow(); + }); + + test("accepts mke2fs in place of mkfs.ext4", () => { + const installed = ALL_TOOLS.filter((t) => t !== "mkfs.ext4"); + expect(() => + _preflightBuildTools(undefined, probe(installed)), + ).not.toThrow(); + }); + + test("fails when neither mke2fs nor mkfs.ext4 is present", () => { + const installed = ALL_TOOLS.filter( + (t) => t !== "mke2fs" && t !== "mkfs.ext4", + ); + expect(() => _preflightBuildTools(undefined, probe(installed))).toThrow( + /mke2fs/, + ); + }); + + test.each(["debugfs", "cpio", "lz4"])("fails naming a missing %s", (tool) => { + const installed = ALL_TOOLS.filter((t) => t !== tool); + expect(() => _preflightBuildTools(undefined, probe(installed))).toThrow( + new RegExp(tool), + ); + }); + + /** + * Either engine alone suffices, and we assert nothing about which one is + * picked: Tuor selects no engine, it only checks that one exists (Gondolin's + * own detectOciRuntime owns the docker→podman preference). + */ + test.each(["docker", "podman"])("passes with only %s installed", (engine) => { + const installed = ALL_TOOLS.filter( + (t) => t === engine || (t !== "docker" && t !== "podman"), + ); + expect(() => + _preflightBuildTools(undefined, probe(installed)), + ).not.toThrow(); + }); + + test("fails when neither docker nor podman is installed", () => { + const installed = ALL_TOOLS.filter((t) => t !== "docker" && t !== "podman"); + expect(() => _preflightBuildTools(undefined, probe(installed))).toThrow( + /Docker or Podman/, + ); + }); + + test("fails naming an explicitly configured engine that is missing", () => { + const installed = ALL_TOOLS.filter((t) => t !== "docker"); + expect(() => _preflightBuildTools("docker", probe(installed))).toThrow( + /"docker"/, + ); + }); + + test("does not accept the other engine when one was configured explicitly", () => { + const installed = ALL_TOOLS.filter((t) => t !== "podman"); + expect(() => _preflightBuildTools("podman", probe(installed))).toThrow( + /"podman"/, + ); + }); +}); + +// --- ensureImageAssets --- + +const FAKE_GONDOLIN_VERSION = "0.12.0"; + +type ImageCalls = { + resolveImageSelector: Array<{ selector: string; arch?: Architecture }>; + buildAssets: Array<{ config: BuildConfig; options: BuildOptions }>; + importImageFromDirectory: string[]; + setImageRef: Array<{ + reference: string; + buildId: string; + arch: Architecture; + }>; + logs: string[]; +}; + +type HarnessOptions = { + /** Refs in the image store. Mutated in place to model a concurrent builder. */ + refs?: LocalImageRef[]; + installed?: string[]; + arch?: Architecture; + gondolinVersion?: string; + /** Runs inside the fake `buildAssets` — throw here to model a failed build. */ + onBuild?: (options: BuildOptions) => void; +}; + +/** + * Fake {@link ImageDeps} that records every call, so `ensureImageAssets` can be + * driven without Docker, a real build, or the host's own architecture. + */ +function harness(options: HarnessOptions = {}): { + deps: ImageDeps; + calls: ImageCalls; +} { + const { + refs = [], + installed = ALL_TOOLS, + arch = "x86_64", + gondolinVersion = FAKE_GONDOLIN_VERSION, + onBuild, + } = options; + + const calls: ImageCalls = { + resolveImageSelector: [], + buildAssets: [], + importImageFromDirectory: [], + setImageRef: [], + logs: [], + }; + + const deps: ImageDeps = { + hasCommand: probe(installed), + listImageRefs: () => refs, + resolveImageSelector: (selector, selectorArch) => { + calls.resolveImageSelector.push({ selector, arch: selectorArch }); + return { source: "ref", selector, assetDir: "/store/cached" }; + }, + importImageFromDirectory: (assetDir) => { + calls.importImageFromDirectory.push(assetDir); + return { + buildId: "build-1", + arch, + assetDir: "/store/built", + created: true, + }; + }, + setImageRef: (reference, buildId, refArch) => { + calls.setImageRef.push({ reference, buildId, arch: refArch }); + return undefined; + }, + buildAssets: async (config, buildOptions) => { + calls.buildAssets.push({ config, options: buildOptions }); + onBuild?.(buildOptions); + return { + outputDir: buildOptions.outputDir, + manifestPath: `${buildOptions.outputDir}/manifest.json`, + manifest: {}, + } as BuildResult; + }, + gondolinVersion: () => gondolinVersion, + hostArch: () => arch, + log: (message) => calls.logs.push(message), + }; + + return { deps, calls }; +} + +function cachedRef(s: RootfsImageSpec, arch: Architecture): LocalImageRef { + return ref(_tuorImageRef(s, arch, FAKE_GONDOLIN_VERSION), { + [arch]: "build-0", + }); +} + +/** The single `BuildConfig` handed to Gondolin by a run that built. */ +function builtConfig(calls: ImageCalls): BuildConfig { + expect(calls.buildAssets).toHaveLength(1); + return calls.buildAssets[0]!.config; +} + +describe("ensureImageAssets", () => { + describe("caching", () => { + test("returns cached assets without building", async () => { + const { deps, calls } = harness({ refs: [cachedRef(spec(), "x86_64")] }); + + await expect(ensureImageAssets(spec(), deps)).resolves.toBe( + "/store/cached", + ); + expect(calls.buildAssets).toHaveLength(0); + expect(calls.resolveImageSelector).toEqual([ + { + selector: _tuorImageRef(spec(), "x86_64", FAKE_GONDOLIN_VERSION), + arch: "x86_64", + }, + ]); + }); + + /** + * A cache hit must not need a container engine or e2fsprogs: only *building* + * requires them, and demanding them to reuse assets would break hosts that + * built the image once and then uninstalled the toolchain. + */ + test("reuses cached assets on a host with no build tools", async () => { + const { deps } = harness({ + refs: [cachedRef(spec(), "x86_64")], + installed: [], + }); + + await expect(ensureImageAssets(spec(), deps)).resolves.toBe( + "/store/cached", + ); + }); + + test("builds, imports and tags when nothing is cached", async () => { + const { deps, calls } = harness(); + + await expect(ensureImageAssets(spec(), deps)).resolves.toBe( + "/store/built", + ); + // The built assets are imported from the scratch dir Gondolin built into. + expect(calls.importImageFromDirectory).toEqual([ + calls.buildAssets[0]!.options.outputDir, + ]); + expect(calls.setImageRef).toEqual([ + { + reference: _tuorImageRef(spec(), "x86_64", FAKE_GONDOLIN_VERSION), + buildId: "build-1", + arch: "x86_64", + }, + ]); + }); + + test("rebuilds under buildPolicy always, despite a cache hit", async () => { + const s = spec({ buildPolicy: "always" }); + const { deps, calls } = harness({ refs: [cachedRef(s, "x86_64")] }); + + await expect(ensureImageAssets(s, deps)).resolves.toBe("/store/built"); + expect(calls.buildAssets).toHaveLength(1); + }); + + /** + * The two policies are independent axes: `pullPolicy` says where the OCI + * image comes from, `buildPolicy` whether assets are rebuilt from it. On a + * cache hit there is no build, so no image is needed and nothing is pulled + * — asking for a fresh pull cannot by itself invalidate the assets. + */ + test("reuses cached assets under pullPolicy always", async () => { + const s = spec({ pullPolicy: "always" }); + const { deps, calls } = harness({ refs: [cachedRef(s, "x86_64")] }); + + await expect(ensureImageAssets(s, deps)).resolves.toBe("/store/cached"); + expect(calls.buildAssets).toHaveLength(0); + }); + + /** Rebuild the assets, but off the local image rather than the registry. */ + test("rebuilds without pulling under buildPolicy always, pullPolicy never", async () => { + const s = spec({ buildPolicy: "always", pullPolicy: "never" }); + const { deps, calls } = harness({ refs: [cachedRef(s, "x86_64")] }); + + await expect(ensureImageAssets(s, deps)).resolves.toBe("/store/built"); + expect(calls.buildAssets).toHaveLength(1); + expect(builtConfig(calls).oci).toEqual({ + image: s.ref, + pullPolicy: "never", + }); + }); + + /** A Gondolin upgrade changes the ref, so old assets are not reused. */ + test("rebuilds after the Gondolin version changes", async () => { + const { deps, calls } = harness({ + refs: [cachedRef(spec(), "x86_64")], + gondolinVersion: "0.13.0", + }); + + await expect(ensureImageAssets(spec(), deps)).resolves.toBe( + "/store/built", + ); + expect(calls.buildAssets).toHaveLength(1); + }); + }); + + /** + * Both directions are exercised so these stay meaningful on an aarch64 host + * too: a run that read `process.arch` instead of the injected value would + * pass whichever case happens to match the machine running the suite. + */ + describe("architecture", () => { + test.each([ + "x86_64", + "aarch64", + ] as const)("builds and tags for the injected %s", async (arch) => { + const { deps, calls } = harness({ arch }); + + await ensureImageAssets(spec(), deps); + expect(builtConfig(calls).arch).toBe(arch); + expect(calls.setImageRef[0]!.arch).toBe(arch); + }); + + test.each([ + ["x86_64", "aarch64"], + ["aarch64", "x86_64"], + ] as const)("on %s, ignores assets cached for %s", async (arch, otherArch) => { + const { deps, calls } = harness({ + refs: [cachedRef(spec(), otherArch)], + arch, + }); + + await expect(ensureImageAssets(spec(), deps)).resolves.toBe( + "/store/built", + ); + expect(calls.buildAssets).toHaveLength(1); + }); + }); + + describe("build config", () => { + test("forwards the OCI ref and pull policy", async () => { + const s = spec({ pullPolicy: "never" }); + const { deps, calls } = harness(); + + await ensureImageAssets(s, deps); + expect(builtConfig(calls).oci).toEqual({ + image: s.ref, + pullPolicy: "never", + }); + }); + + /** Omitted rather than defaulted, so Gondolin's own detection stays in charge. */ + test("omits the runtime when no engine is configured", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(spec(), deps); + expect(builtConfig(calls).oci).not.toHaveProperty("runtime"); + }); + + test("forwards an explicitly configured engine as the runtime", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(spec({ engine: "podman" }), deps); + expect(builtConfig(calls).oci?.runtime).toBe("podman"); + }); + + /** Merged, not replaced: dropping Gondolin's default label breaks boot. */ + test("bakes in the rootfs size while keeping the default label", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(spec({ rootfsSizeMb: 8192 }), deps); + expect(builtConfig(calls).rootfs).toEqual({ + ...getDefaultBuildConfig().rootfs, + sizeMb: 8192, + }); + }); + + test("leaves rootfs untouched when no size is configured", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(spec(), deps); + expect(builtConfig(calls).rootfs).toEqual(getDefaultBuildConfig().rootfs); + }); + }); + + describe("preflight", () => { + /** + * The point of preflighting is to fail *before* Gondolin downloads sandbox + * helper binaries, so a missing tool must abort the build, not surface from + * inside it. + */ + test("fails without building when a required tool is missing", async () => { + const { deps, calls } = harness({ + installed: ALL_TOOLS.filter((t) => t !== "lz4"), + }); + + await expect(ensureImageAssets(spec(), deps)).rejects.toThrow(/lz4/); + expect(calls.buildAssets).toHaveLength(0); + }); + + test("fails without building when no container engine is present", async () => { + const { deps, calls } = harness({ + installed: ALL_TOOLS.filter((t) => t !== "docker" && t !== "podman"), + }); + + await expect(ensureImageAssets(spec(), deps)).rejects.toThrow( + /Docker or Podman/, + ); + expect(calls.buildAssets).toHaveLength(0); + }); + }); + + describe("scratch dir", () => { + test("removes the build dir after a successful build", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(spec(), deps); + expect(existsSync(calls.buildAssets[0]!.options.outputDir)).toBe(false); + }); + + test("removes the build dir when the build fails", async () => { + let outputDir = ""; + const { deps } = harness({ + onBuild: (options) => { + outputDir = options.outputDir; + throw new Error("mke2fs exploded"); + }, + }); + + await expect(ensureImageAssets(spec(), deps)).rejects.toThrow( + "mke2fs exploded", + ); + expect(existsSync(outputDir)).toBe(false); + }); + }); +}); diff --git a/src/core/image.ts b/src/core/image.ts new file mode 100644 index 0000000..70ed9bb --- /dev/null +++ b/src/core/image.ts @@ -0,0 +1,361 @@ +import { execFileSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { mkdtempSync, rmSync } from "node:fs"; +import { createRequire } from "node:module"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { + type Architecture, + type BuildConfig, + type BuildOptions, + type BuildResult, + buildAssets, + getDefaultBuildConfig, + type ImportedImage, + importImageFromDirectory, + type LocalImageRef, + listImageRefs, + type ResolvedImage, + resolveImageSelector, + setImageRef, +} from "@earendil-works/gondolin"; + +// --- Types --- + +export type RootfsPullPolicy = "always" | "if-not-present" | "never"; +export type RootfsBuildPolicy = "always" | "if-not-present"; +export type ContainerEngine = "docker" | "podman"; + +/** + * Core's input contract for a custom guest rootfs: the OCI image to build from + * plus the knobs that affect the built assets. + * + * The two policies are independent axes: `pullPolicy` says where the OCI image + * comes from, `buildPolicy` whether the guest assets are rebuilt from it. Since + * a reused asset needs no image at all, `pullPolicy` only matters on the runs + * that actually build. + */ +export type RootfsImageSpec = { + /** OCI image ref: `repo/name[:tag]` or `repo/name@sha256:…`. */ + ref: string; + pullPolicy: RootfsPullPolicy; + buildPolicy: RootfsBuildPolicy; + /** Omitted → Gondolin auto-detects (docker, else podman). */ + engine?: ContainerEngine; + /** Total rootfs size baked into the built image (see `parseSizeToMb`). */ + rootfsSizeMb?: number; +}; + +/** + * Injectable seams for {@link ensureImageAssets}: the Gondolin entry points it + * drives plus host probing and logging. Exists so the cache decision and the + * host-tool preflight are unit-testable without Docker or a real build. + */ +export type ImageDeps = { + /** Whether `command` is on PATH. */ + hasCommand: (command: string) => boolean; + listImageRefs: () => LocalImageRef[]; + resolveImageSelector: ( + selector: string, + arch?: Architecture, + ) => ResolvedImage; + importImageFromDirectory: (assetDir: string) => ImportedImage; + setImageRef: ( + reference: string, + buildId: string, + arch: Architecture, + ) => unknown; + buildAssets: ( + config: BuildConfig, + options: BuildOptions, + ) => Promise; + /** Version of the installed Gondolin — part of the cache identity. */ + gondolinVersion: () => string; + /** Architecture to build for — part of the cache identity. */ + hostArch: () => Architecture; + log: (message: string) => void; +}; + +// --- Public API --- + +/** + * Ensure Gondolin guest assets exist for `spec` and return the directory + * holding them (ready to hand to `VM.create({ sandbox: { imagePath } })`). + * + * Assets are cached in **Gondolin's own content-addressed image store** + * (`~/.cache/gondolin/images`, or `$GONDOLIN_IMAGE_STORE`) rather than a Tuor + * cache directory, so we inherit its atomic writes, content dedup and + * concurrent-import handling; Tuor owns no cache dir of its own. Each build is + * tagged with a `tuor/:latest` ref (see {@link _tuorImageRef}), which also + * makes Tuor-built images identifiable in Gondolin tooling. + * + * Building is slow (image pull + mke2fs), so it happens at most once per cache + * identity — unless `buildPolicy` is "always", which rebuilds every run. + * `pullPolicy` governs the separate question of where the OCI image comes + * from, and so only matters on the runs that do build. + */ +export async function ensureImageAssets( + spec: RootfsImageSpec, + deps: ImageDeps = defaultImageDeps, +): Promise { + const arch = deps.hostArch(); + const tuorRef = _tuorImageRef(spec, arch, deps.gondolinVersion()); + const cached = + spec.buildPolicy === "always" + ? undefined + : resolveCached(tuorRef, arch, deps); + if (cached) return cached; + + // Fail fast on a host that can't build, *before* Gondolin downloads sandbox + // helper binaries (which it does before reaching its own engine check). + _preflightBuildTools(spec.engine, deps.hasCommand); + + return await buildAndStore(spec, arch, tuorRef, deps); +} + +/** + * Regex for byte size values: a positive integer plus a *mandatory* K/M/G/T + * unit. + * + * Note that the unit suffix is mandatory for expliciteness, even if that might + * not be required by Gondolin/QEMU. + */ +export const SIZE_FORMAT = /^(\d+)([KMGT])$/i; + +/** + * Convert a `rootfs.size` value (`"8G"`, `"512M"`) into whole megabytes, + * rounded up, minimum 1. + */ +export function parseSizeToMb(size: string): number { + const match = SIZE_FORMAT.exec(size.trim()); + if (!match) { + throw new Error( + `Invalid rootfs size: "${size}". Expected a positive integer with a ` + + 'K/M/G/T suffix, e.g. "512M" or "8G".', + ); + } + const unit = match[2]!.toUpperCase() as keyof typeof BYTES_PER_UNIT; + const bytes = Number(match[1]) * BYTES_PER_UNIT[unit]; + return Math.max(1, Math.ceil(bytes / (1024 * 1024))); +} + +// --- Internals --- + +const BYTES_PER_UNIT = { + K: 1024, + M: 1024 ** 2, + G: 1024 ** 3, + T: 1024 ** 4, +} as const; + +/** + * Map Node's `process.arch` onto Gondolin's architecture names. Takes + * `nodeArch` explicitly rather than doing an effectful call to + * `process.arch()`, so that we can configure the arch in tests. + */ +export function _hostArch(nodeArch: string): Architecture { + switch (nodeArch) { + case "arm64": + return "aarch64"; + case "x64": + return "x86_64"; + default: + throw new Error( + `Unsupported host architecture "${nodeArch}" for building a custom ` + + "rootfs. Only arm64 and x64 are supported.", + ); + } +} + +/** + * The Gondolin image ref under which Tuor stores the assets built for `spec`. + */ +export function _tuorImageRef( + spec: RootfsImageSpec, + arch: Architecture, + gondolinVersion: string, +): string { + // In the ref include all parameters that might change the build outcome. + // Gondolin ref names allow only `[A-Za-z0-9._/-]`, so hash them all. + const identity = JSON.stringify([ + spec.ref, + arch, + spec.rootfsSizeMb ?? null, + gondolinVersion, // Different versions of Gondolin bake different assets into the rootfs. + ]); + const hash = createHash("sha256").update(identity).digest("hex").slice(0, 32); + return `tuor/${hash}:latest`; +} + +/** + * Whether the image store holds assets for `tuorRef` on `arch`. + * + * Presence is a plain lookup over `listImageRefs()` rather than catching a throw + * from `resolveImageSelector`: Gondolin does not export its `ImageResolutionError`, + * so a miss would be indistinguishable from a real failure. (`listImageRefs` + * already omits broken ref links, so a hit here really is resolvable.) + * + * Whether a hit may be *used* is the caller's call — a policy of "always" + * ignores the cache entirely. + */ +export function _hasCachedAssets( + tuorRef: string, + arch: Architecture, + refs: LocalImageRef[], +): boolean { + return refs.some( + (ref) => ref.reference === tuorRef && ref.targets[arch] !== undefined, + ); +} + +/** + * Verify the host can build a custom rootfs, naming the missing tool when it + * can't. + * + * Gondolin checks for these too, but too late to be useful: `cpio`/`lz4` are + * invoked inside a shell pipeline, so their absence surfaces as a bare non-zero + * exit code that names nothing, and the container-engine check only runs after + * sandbox helper binaries have been downloaded. + * + * We deliberately do not pick an engine — that stays Gondolin's job. We just + * assert that *some* engine exists. + */ +export function _preflightBuildTools( + engine: ContainerEngine | undefined, + hasCommand: (command: string) => boolean, +): void { + if (engine) { + if (!hasCommand(engine)) { + throw new Error( + `Building a custom rootfs requires the "${engine}" container engine ` + + "(rootfs.image.engine), but it was not found on PATH.", + ); + } + } else if (!hasCommand("docker") && !hasCommand("podman")) { + throw new Error( + "Building a custom rootfs requires Docker or Podman on PATH to pull and " + + "export the OCI image. Install one, or set rootfs.image.engine.", + ); + } + + for (const tool of REQUIRED_BUILD_TOOLS) { + if (!tool.commands.some(hasCommand)) { + throw new Error( + `Building a custom rootfs requires "${tool.commands[0]}", but it was ` + + `not found on PATH. Install it (e.g. "apt install ${tool.aptPackages}").`, + ); + } + } +} + +/** + * Host tools Gondolin's native OCI build path shells out to. `mke2fs` and + * `mkfs.ext4` are interchangeable (Gondolin's `findMke2fs` accepts either), so + * they share one entry — requiring both would false-fail hosts that ship only + * `mkfs.ext4`. + */ +const REQUIRED_BUILD_TOOLS = [ + { commands: ["mke2fs", "mkfs.ext4"], aptPackages: "e2fsprogs" }, + { commands: ["debugfs"], aptPackages: "e2fsprogs" }, + { commands: ["cpio"], aptPackages: "cpio" }, + { commands: ["lz4"], aptPackages: "lz4" }, +] as const; + +/** Resolve already-built assets for `tuorRef`, or undefined when missing. */ +function resolveCached( + tuorRef: string, + arch: Architecture, + deps: ImageDeps, +): string | undefined { + if (!_hasCachedAssets(tuorRef, arch, deps.listImageRefs())) { + return undefined; + } + return deps.resolveImageSelector(tuorRef, arch).assetDir; +} + +async function buildAndStore( + spec: RootfsImageSpec, + arch: Architecture, + tuorRef: string, + deps: ImageDeps, +): Promise { + const defaults = getDefaultBuildConfig(); + const buildConfig: BuildConfig = { + ...defaults, + arch, + oci: { + image: spec.ref, + pullPolicy: spec.pullPolicy, + // Only forwarded when the user asked for a specific engine; otherwise + // Gondolin auto-detects. + ...(spec.engine ? { runtime: spec.engine } : {}), + }, + // Merge rather than replace, so Gondolin's default volume label survives. + // A baked size needs no in-guest resize2fs at boot. + ...(spec.rootfsSizeMb + ? { rootfs: { ...defaults.rootfs, sizeMb: spec.rootfsSizeMb } } + : {}), + }; + + // The build dir is scratch space: everything worth keeping is copied into the + // image store by the import below. + const outputDir = mkdtempSync(join(tmpdir(), "tuor-build-")); + try { + deps.log( + `Building custom rootfs from ${spec.ref} (this can take a while)…`, + ); + await deps.buildAssets(buildConfig, { outputDir }); + + deps.log(`Importing assets into Gondolin as '${tuorRef}'...`); + // importImageFromDirectory validates the assets, copies them into the store + // under their content-derived build id (temp dir + atomic rename, tolerating + // a concurrent import of the same content), and hands back both the id and + // the stored directory — so we never parse manifest.json ourselves. + const imported = deps.importImageFromDirectory(outputDir); + deps.setImageRef(tuorRef, imported.buildId, arch); + deps.log(`Import complete! Assets written to ${imported.assetDir}`); + + return imported.assetDir; + } finally { + rmSync(outputDir, { recursive: true, force: true }); + } +} + +// --- Default deps --- + +function hasCommandOnPath(command: string): boolean { + try { + execFileSync("which", [command], { stdio: "ignore" }); + return true; + } catch { + return false; + } +} + +/** + * Read the *installed* Gondolin's version at runtime (not the one Tuor was built + * against), since Tuor depends on a version range. + */ +function readGondolinVersion(): string { + try { + const require = createRequire(import.meta.url); + const pkg = require("@earendil-works/gondolin/package.json") as { + version?: string; + }; + return pkg.version ?? "unknown"; + } catch { + throw new Error("Could not determine Gondolin version"); + } +} + +const defaultImageDeps: ImageDeps = { + hasCommand: hasCommandOnPath, + listImageRefs, + resolveImageSelector, + importImageFromDirectory, + setImageRef, + buildAssets, + gondolinVersion: readGondolinVersion, + hostArch: () => _hostArch(process.arch), + log: (message) => console.log(message), +}; diff --git a/src/core/session.ts b/src/core/session.ts index ce2d981..e1d62fe 100644 --- a/src/core/session.ts +++ b/src/core/session.ts @@ -1,4 +1,9 @@ import { createHttpHooks, VM } from "@earendil-works/gondolin"; +import { + ensureImageAssets, + parseSizeToMb, + type RootfsImageSpec, +} from "./image.ts"; import { buildVfsMounts, buildVfsVolumes, @@ -34,13 +39,20 @@ export type QemuSpec = { /** * Resolved VM resource sizing. `memory`/`cpus` map verbatim to Gondolin's - * top-level options; `rootfsSize` maps to `rootfs.size`. An unset field falls - * back to Gondolin's default. + * top-level options. An unset field falls back to Gondolin's default. */ export type ResourcesSpec = { memory?: string; cpus?: number; - rootfsSize?: string; +}; + +/** + * Resolved root filesystem sizing & source. `size` is QEMU syntax; how it is + * applied depends on whether an `image` is built — see {@link runSession}. + */ +export type RootfsSpec = { + image?: RootfsImageSpec; + size?: string; }; /** Core's top-level input contract — everything the session needs to run. */ @@ -50,6 +62,7 @@ export type SessionSpec = { mounts: MountSpec[]; volumes?: VolumeSpec[]; resources?: ResourcesSpec; + rootfs?: RootfsSpec; env?: Record; secrets?: Record; qemu?: QemuSpec; @@ -84,17 +97,35 @@ export async function runSession( const mergedEnv = { ...spec.env, ...placeholderSecretsEnv }; const hasEnv = Object.keys(mergedEnv).length > 0; + // If `rootfs.image` is given, retrieve custom image from cache or build + // fresh if there's a cache miss. + const imagePath = spec.rootfs?.image + ? await ensureImageAssets({ + ...spec.rootfs.image, + ...(spec.rootfs.size + ? { rootfsSizeMb: parseSizeToMb(spec.rootfs.size) } + : {}), + }) + : undefined; + + // Size dispatch: for a built image the size is baked in above (no in-guest + // resize2fs needed, which minimal images often lack), so only the default + // image gets grown at runtime. + const growSize = + spec.rootfs?.size && !spec.rootfs?.image ? spec.rootfs.size : undefined; + + const sandbox = { ...spec.qemu, ...(imagePath ? { imagePath } : {}) }; + const hasSandbox = Object.keys(sandbox).length > 0; + console.log("Starting VM…"); const vm = await VM.create({ ...networkOptions, - ...(spec.resources?.rootfsSize - ? { rootfs: { size: spec.resources.rootfsSize } } - : {}), + ...(growSize ? { rootfs: { size: growSize } } : {}), ...(spec.resources?.memory ? { memory: spec.resources.memory } : {}), ...(spec.resources?.cpus ? { cpus: spec.resources.cpus } : {}), ...(hasEnv ? { env: mergedEnv } : {}), ...(hasVfsMounts ? { vfs: { mounts: vfsMounts } } : {}), - sandbox: spec.qemu, + ...(hasSandbox ? { sandbox } : {}), tmpfs: {}, // ^Disable default tmpfs mounts (/tmp, /var/log, etc.), i.e. don't keep // those folders in memory. RAM is more precious than disk space. Besides, From 27aecd50ff3d1dc0bff9d0f64191b45f213130bc Mon Sep 17 00:00:00 2001 From: codethief Date: Sat, 22 Aug 2026 21:04:40 +0200 Subject: [PATCH 2/5] Breaking change: Require unit suffix in `resources.memory` option --- CHANGELOG.md | 8 +++++--- src/config/schema.test.ts | 16 +++++++++++++--- src/config/schema.ts | 8 ++++---- 3 files changed, 22 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 47bea0d..524f51b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,11 @@ ## Breaking changes - Config: Replaced `resources.rootfsSize` with a new `rootfs.size` setting (see - below) and added stricter validation. The old field accepted any non-empty - string; the new one enforces a QEMU-compatible size syntax (a positive integer - with a *mandatory* K/M/G/T suffix). + below) and added stricter up-front validation. The old field (theoretically) + accepted any non-empty string; the new one enforces a QEMU-compatible size + syntax – a positive integer with a *mandatory* K/M/G/T suffix. +- Config: `resources.memory` now requires a mandatory unit suffix (K/M/G/T), for + consistency with `rootfs.size` (see above). ## Features diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts index fe5dd66..63d9140 100644 --- a/src/config/schema.test.ts +++ b/src/config/schema.test.ts @@ -384,9 +384,15 @@ describe("parseConfig", () => { expect(config.resources).toEqual({ cpus: 8 }); }); - test("accepts memory without a unit suffix", () => { - const config = parseConfig({ resources: { memory: "1024" } }); - expect(config.resources).toEqual({ memory: "1024" }); + test.each([ + "512M", + "2g", + "1T", + "1048576K", + ])("accepts memory: %s", (memory) => { + expect(parseConfig({ resources: { memory } }).resources).toEqual({ + memory, + }); }); test("omits resources when not specified", () => { @@ -491,6 +497,10 @@ describe("parseConfig", () => { ["resources unknown field", { resources: { foo: "bar" } }], ["resources malformed memory", { resources: { memory: "2GB" } }], ["resources empty memory", { resources: { memory: "" } }], + [ + "resources memory without a unit suffix", + { resources: { memory: "1024" } }, + ], ["resources non-integer cpus", { resources: { cpus: 1.5 } }], ["resources zero cpus", { resources: { cpus: 0 } }], ["resources non-number cpus", { resources: { cpus: "4" } }], diff --git a/src/config/schema.ts b/src/config/schema.ts index a77d600..cd765f8 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -312,11 +312,11 @@ const types = scope({ ResourcesConfig: { "+": "reject", /** - * VM RAM in QEMU syntax: a positive integer with an optional K/M/G/T - * suffix, e.g. "512M", "2G". Maps to Gondolin's `memory` top-level option. - * Gondolin default: "1G". + * VM RAM in QEMU-compatible syntax: a positive integer with a *mandatory* + * K/M/G/T suffix, e.g. "512M", "2G". Maps to Gondolin's `memory` top-level + * option. Gondolin default: "1G". */ - "memory?": type("string > 0").matching(/^\d+[KMGT]?$/i), + "memory?": type("string > 0").matching(SIZE_FORMAT), /** * VM vCPU count (positive integer). Maps to Gondolin's `cpus` top-level * option. Gondolin default: 2. Note that this config option is distinct From a8123bcf3b00e24fd103e6b476d48f6b29df2c8c Mon Sep 17 00:00:00 2001 From: codethief Date: Sun, 23 Aug 2026 02:33:37 +0200 Subject: [PATCH 3/5] Allow building the rootfs from a Dockerfile/Containerfile --- CHANGELOG.md | 3 +- src/config/merge.test.ts | 74 ++++++++++- src/config/merge.ts | 24 ++++ src/config/resolve.test.ts | 79 ++++++++++++ src/config/resolve.ts | 32 ++++- src/config/schema.test.ts | 122 +++++++++++++++++- src/config/schema.ts | 70 +++++++++- src/core/image.test.ts | 254 ++++++++++++++++++++++++++++++++++++- src/core/image.ts | 191 ++++++++++++++++++++++++---- 9 files changed, 812 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 524f51b..af8b3ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,8 @@ feature](https://earendil-works.github.io/gondolin/custom-images/) that allows configuring a custom OCI container image to be used for the VM's rootfs instead of Gondolin's default `alpine-base` image. (The kernel is still taken - from Alpine, though.)) + from Alpine, though.) The OCI image can either be an existing one or it can be + built from a Dockerfile/Containerfile. - Config: The new `rootfs.size` setting can be used both with the default VM rootfs (same behavior as the old `resources.rootfsSize`), in which case it grows the file system after boot (using `resize2fs`), or with a custom image diff --git a/src/config/merge.test.ts b/src/config/merge.test.ts index ac704c1..d06f9c1 100644 --- a/src/config/merge.test.ts +++ b/src/config/merge.test.ts @@ -3,7 +3,7 @@ import { type ConfigLayer, findAllConfigDirs, mergeConfigs } from "./merge.ts"; import { type MountConfig, parseConfig, - type RootfsImageConfig, + type RootfsImagePullConfig, type TuorConfig, } from "./schema.ts"; @@ -30,10 +30,10 @@ function mount( return { mode: "readonly", ...overrides }; } -/** Rootfs image with its required policy defaults. */ +/** Pull-variant rootfs image with its required policy defaults. */ function withPolicyDefaults( - overrides: Partial & { ref: string }, -): RootfsImageConfig { + overrides: Partial & { ref: string }, +): RootfsImagePullConfig { return { pullPolicy: "if-not-present", buildPolicy: "if-not-present", @@ -540,6 +540,72 @@ describe("mergeConfigs", () => { ); }); + test("resolves containerfile and context against the declaring layer", () => { + const result = mergeConfigs([ + layer("/a/.tuor", { + rootfs: { + image: { + ref: "my-devbox", + containerfile: "./docker/Containerfile", + context: "..", + buildPolicy: "always", + }, + }, + }), + ]); + expect(result.rootfs?.image).toEqual({ + ref: "my-devbox", + containerfile: "/a/.tuor/docker/Containerfile", + context: "/a", + buildPolicy: "always", + }); + }); + + test("leaves absolute containerfile and context paths alone", () => { + const result = mergeConfigs([ + layer("/a/.tuor", { + rootfs: { + image: { + ref: "my-devbox", + containerfile: "/elsewhere/Containerfile", + context: "/elsewhere", + buildPolicy: "always", + }, + }, + }), + ]); + expect(result.rootfs?.image).toMatchObject({ + containerfile: "/elsewhere/Containerfile", + context: "/elsewhere", + }); + }); + + /** + * Each layer's paths are resolved before the merge, so a child that replaces + * `image` still gets paths relative to *its own* config dir. + */ + test("resolves a child's paths against the child's config dir", () => { + const result = mergeConfigs([ + layer("/a/.tuor", { + rootfs: { image: withPolicyDefaults({ ref: "debian:trixie" }) }, + }), + layer("/a/b/.tuor", { + rootfs: { + image: { + ref: "my-devbox", + containerfile: "./Containerfile", + context: ".", + buildPolicy: "if-not-present", + }, + }, + }), + ]); + expect(result.rootfs?.image).toMatchObject({ + containerfile: "/a/b/.tuor/Containerfile", + context: "/a/b/.tuor", + }); + }); + /** * Goes through `parseConfig` per layer, as load.ts does, so the child's * `pullPolicy` default is materialized before the merge. Since `image` is diff --git a/src/config/merge.ts b/src/config/merge.ts index 42f59e4..7cec681 100644 --- a/src/config/merge.ts +++ b/src/config/merge.ts @@ -245,6 +245,30 @@ function preResolvePaths(layer: ConfigLayer): TuorConfig { ...(typeof config.workdir === "object" ? { workdir: preResolveMountPaths(config.workdir, configDir) } : {}), + ...(config.rootfs + ? { rootfs: preResolveRootfsPaths(config.rootfs, configDir) } + : {}), + }; +} + +/** + * Resolve a build-variant image's `containerfile`/`context` against the layer + * that declared them. Both are plain host paths — no tilde expansion, matching + * `host:` ignoreFileRefs. + */ +function preResolveRootfsPaths( + rootfs: RootfsConfig, + configDir: string, +): RootfsConfig { + const { image } = rootfs; + if (!image || !("containerfile" in image)) return rootfs; + return { + ...rootfs, + image: { + ...image, + containerfile: resolve(configDir, image.containerfile), + context: resolve(configDir, image.context), + }, }; } diff --git a/src/config/resolve.test.ts b/src/config/resolve.test.ts index 69e2e2d..6f7254c 100644 --- a/src/config/resolve.test.ts +++ b/src/config/resolve.test.ts @@ -560,6 +560,85 @@ describe("createSessionSpecFromConfig", () => { const spec = resolve({ rootfs: {} }); expect(spec.rootfs).toBeUndefined(); }); + + describe("Containerfile variant", () => { + const image = { + ref: "my-devbox", + containerfile: "/proj/Containerfile", + context: "/proj", + buildPolicy: "always", + } as const; + + test("passes the build image through untouched", () => { + expect(resolve({ rootfs: { image } }).rootfs?.image).toEqual(image); + }); + + /** + * Without these checks a typo'd path would only surface as a raw engine + * error, after the host-tool preflight and a sandbox-helper download. + */ + test("rejects a containerfile that does not exist", () => { + const deps: ResolveDeps = { + ...validDeps, + mountValidation: { + pathExists: (p) => p !== "/proj/Containerfile", + isDirectory: () => true, + }, + }; + expect(() => resolve({ rootfs: { image } }, undefined, deps)).toThrow( + /rootfs\.image\.containerfile does not exist: \/proj\/Containerfile/, + ); + }); + + test("rejects a context that does not exist", () => { + const deps: ResolveDeps = { + ...validDeps, + mountValidation: { + pathExists: (p) => p !== "/proj", + isDirectory: () => true, + }, + }; + expect(() => resolve({ rootfs: { image } }, undefined, deps)).toThrow( + /rootfs\.image\.context does not exist: \/proj/, + ); + }); + + test("rejects a context that is not a directory", () => { + const deps: ResolveDeps = { + ...validDeps, + mountValidation: { pathExists: () => true, isDirectory: () => false }, + }; + expect(() => resolve({ rootfs: { image } }, undefined, deps)).toThrow( + /rootfs\.image\.context is not a directory/, + ); + }); + + /** The pull variant has no host paths to check. */ + test("checks no paths for a pull image", () => { + const deps: ResolveDeps = { + ...validDeps, + mountValidation: { + pathExists: () => false, + isDirectory: () => false, + }, + }; + expect(() => + resolve( + { + rootfs: { + image: { + ref: "alpine:3.23", + pullPolicy: "if-not-present", + buildPolicy: "if-not-present", + }, + }, + }, + undefined, + deps, + ), + ).not.toThrow(); + }); + }); }); }); diff --git a/src/config/resolve.ts b/src/config/resolve.ts index 640fb57..f32315b 100644 --- a/src/config/resolve.ts +++ b/src/config/resolve.ts @@ -118,7 +118,7 @@ export function createSessionSpecFromConfig( const qemu = resolveQemu(config.qemu); const resources = resolveResources(config.resources); - const rootfs = resolveRootfs(config.rootfs); + const rootfs = resolveRootfs(config.rootfs, deps.mountValidation); // Nix's own boot commands (currently just the nix-ld symlink) run first so // that user-provided bootCommands can already rely on the setup they do. @@ -290,11 +290,41 @@ function resolveResources( */ function resolveRootfs( rootfs: DefaultedConfig["rootfs"], + deps: MountValidationDeps, ): RootfsSpec | undefined { if (!rootfs || Object.keys(rootfs).length === 0) return undefined; + if (rootfs.image && "containerfile" in rootfs.image) { + validateImageBuildPaths(rootfs.image, deps); + } return { ...rootfs }; } +/** + * Check the Containerfile and build context up front. Both paths were already + * made absolute in `preResolvePaths`, and without this a typo would only + * surface much later as a raw ` build` error — after the host-tool + * preflight and possibly a sandbox-helper download. + */ +function validateImageBuildPaths( + image: { containerfile: string; context: string }, + deps: MountValidationDeps, +): void { + if (!deps.pathExists(image.containerfile)) { + throw new Error( + `rootfs.image.containerfile does not exist: ${image.containerfile}`, + ); + } + if (!deps.pathExists(image.context)) { + throw new Error(`rootfs.image.context does not exist: ${image.context}`); + } + if (!deps.isDirectory(image.context)) { + throw new Error( + `rootfs.image.context is not a directory: ${image.context}. ` + + "It is the root of the build context handed to the container engine.", + ); + } +} + function resolveVolumeConfig( v: VolumeConfig, configDir: string, diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts index 63d9140..21b34de 100644 --- a/src/config/schema.test.ts +++ b/src/config/schema.test.ts @@ -1,5 +1,11 @@ import { describe, expect, test } from "vitest"; -import { findConfigDir, parseConfig } from "./schema.ts"; +import { + findConfigDir, + parseConfig, + type RootfsImageBuildConfig, + type RootfsImagePullConfig, + type TuorConfig, +} from "./schema.ts"; describe("findConfigDir", () => { test("returns config dir when config.json exists in start directory", () => { @@ -402,6 +408,24 @@ describe("parseConfig", () => { }); describe("rootfs config", () => { + /** Narrow a parsed `rootfs.image` to the pull variant. */ + function pullImage(config: TuorConfig): RootfsImagePullConfig { + const image = config.rootfs?.image; + if (!image || "containerfile" in image) { + throw new Error(`expected a pull-variant image, got ${image}`); + } + return image; + } + + /** Narrow a parsed `rootfs.image` to the Containerfile variant. */ + function buildImage(config: TuorConfig): RootfsImageBuildConfig { + const image = config.rootfs?.image; + if (!image || !("containerfile" in image)) { + throw new Error(`expected a build-variant image, got ${image}`); + } + return image; + } + test("accepts an image with just a ref", () => { const config = parseConfig({ rootfs: { image: { ref: "docker.io/library/debian:bookworm-slim" } }, @@ -417,12 +441,12 @@ describe("parseConfig", () => { test("defaults an omitted pullPolicy to if-not-present", () => { const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23" } } }); - expect(config.rootfs?.image?.pullPolicy).toBe("if-not-present"); + expect(pullImage(config).pullPolicy).toBe("if-not-present"); }); test("defaults an omitted buildPolicy to if-not-present", () => { const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23" } } }); - expect(config.rootfs?.image?.buildPolicy).toBe("if-not-present"); + expect(pullImage(config).buildPolicy).toBe("if-not-present"); }); test.each([ @@ -432,10 +456,10 @@ describe("parseConfig", () => { const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23", buildPolicy } }, }); - expect(config.rootfs?.image?.buildPolicy).toBe(buildPolicy); + expect(pullImage(config).buildPolicy).toBe(buildPolicy); }); - test("rejects buildPolicy 'never'", () => { + test("rejects buildPolicy 'never' on the pull variant", () => { expect(() => parseConfig({ rootfs: { image: { ref: "alpine:3.23", buildPolicy: "never" } }, @@ -451,7 +475,7 @@ describe("parseConfig", () => { const config = parseConfig({ rootfs: { image: { ref: "alpine:3.23", pullPolicy } }, }); - expect(config.rootfs?.image?.pullPolicy).toBe(pullPolicy); + expect(pullImage(config).pullPolicy).toBe(pullPolicy); }); test.each(["docker", "podman"])("accepts engine: %s", (engine) => { @@ -488,6 +512,92 @@ describe("parseConfig", () => { const config = parseConfig({}); expect(config.rootfs).toBeUndefined(); }); + + describe("Containerfile variant", () => { + const BUILD_IMAGE = { + ref: "my-devbox", + containerfile: "./Containerfile", + context: ".", + buildPolicy: "if-not-present", + }; + + test("accepts the minimal build image", () => { + const config = parseConfig({ rootfs: { image: BUILD_IMAGE } }); + expect(config.rootfs?.image).toEqual(BUILD_IMAGE); + }); + + test("accepts an engine alongside it", () => { + const config = parseConfig({ + rootfs: { image: { ...BUILD_IMAGE, engine: "podman" } }, + }); + expect(buildImage(config).engine).toBe("podman"); + }); + + test.each([ + "if-not-present", + "always", + ])("accepts buildPolicy: %s", (buildPolicy) => { + const config = parseConfig({ + rootfs: { image: { ...BUILD_IMAGE, buildPolicy } }, + }); + expect(buildImage(config).buildPolicy).toBe(buildPolicy); + }); + + test.each([ + "my-devbox", + "tuor/my-devbox", + "my-devbox:v1", + "registry.local/team/devbox:latest", + "550e8400-e29b-41d4-a716-446655440000", + "tuor.dev_01", + ])("accepts ref: %s", (ref) => { + const config = parseConfig({ + rootfs: { image: { ...BUILD_IMAGE, ref } }, + }); + expect(buildImage(config).ref).toBe(ref); + }); + + test.each([ + ["uppercase in the name", "MyDevbox"], + ["a digest you cannot build to", "my-devbox@sha256:abc"], + ["a leading dash", "-my-devbox"], + ["an empty ref", ""], + ])("rejects %s", (_what, ref) => { + expect(() => + parseConfig({ rootfs: { image: { ...BUILD_IMAGE, ref } } }), + ).toThrow(); + }); + + test.each([ + ["containerfile", "context"], + ["context", "containerfile"], + ["buildPolicy", "buildPolicy"], + ])("rejects a build image missing %s", (missing) => { + const image: Record = { ...BUILD_IMAGE }; + delete image[missing]; + expect(() => parseConfig({ rootfs: { image } })).toThrow(); + }); + + /** + * The two variants are mutually exclusive: `pullPolicy` governs fetching + * an image that exists, `buildPolicy` producing one that doesn't. + */ + test("rejects mixing pullPolicy into the build variant", () => { + expect(() => + parseConfig({ + rootfs: { image: { ...BUILD_IMAGE, pullPolicy: "never" } }, + }), + ).toThrow(); + }); + + test("rejects a containerfile without the rest of the variant", () => { + expect(() => + parseConfig({ + rootfs: { image: { ref: "x", containerfile: "./Containerfile" } }, + }), + ).toThrow(); + }); + }); }); test.each([ diff --git a/src/config/schema.ts b/src/config/schema.ts index cd765f8..add8ee6 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -365,6 +365,15 @@ const types = scope({ * An optional OCI image to build the guest rootfs from. Essentially a config * setting for https://earendil-works.github.io/gondolin/custom-images/ . * + * Two ways to name the image, distinguished by whether `containerfile` is + * present: + * - {@link RootfsImagePullConfig} — the image already exists (in a registry + * or the engine's local store) and is pulled. + * - {@link RootfsImageBuildConfig} — the image is built from a Containerfile + * on the host first, then used exactly like a pulled one. + * + * Either way, `ref` names the image and doubles as its cache identity. + * * Note that the choice of image doesn't affect the guest kernel which is * always taken from Alpine. * @@ -380,10 +389,14 @@ const types = scope({ * - `lz4` * - `mke2fs` or `mkfs.ext4` * - `debugfs` + * - Docker or Podman * * On Debian/Ubuntu: `apt install cpio lz4 e2fsprogs`. */ - RootfsImageConfig: { + RootfsImageConfig: "RootfsImagePullConfig | RootfsImageBuildConfig", + + /** Use an OCI image that already exists, pulling it when necessary. */ + RootfsImagePullConfig: { "+": "reject", /** * The OCI image to be used for the rootfs. The architecture is always the @@ -427,6 +440,59 @@ const types = scope({ */ pullPolicy: "'always' | 'if-not-present' | 'never' = 'if-not-present'", }, + + /** + * Build the OCI image from a Containerfile on the host, then use it as the + * rootfs source. Gondolin itself has no Containerfile support (it only pulls, + * creates and exports existing images), so Tuor runs ` build` and + * hands Gondolin the resulting local image. + * + * IMPORTANT: `ref` alone is the cache identity — the Containerfile and the + * context are *not* hashed. Editing them without bumping `ref` will keep + * booting the previously built rootfs. To work around this, use `buildPolicy: + * "always"` while iterating on a Containerfile, or a fresh `ref` (a UUID + * works well) per revision. + */ + RootfsImageBuildConfig: { + "+": "reject", + /** + * Name to tag the built image with, and the identity Tuor caches it under + * (see the note above). Passed verbatim to ` build -t`. + * + * Format: `[repo/]name[:tag]`, lowercase. + */ + ref: type("string > 0").matching( + /^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9_][A-Za-z0-9._-]*)?$/, + ), + /** + * Path to the Containerfile/Dockerfile, absolute or relative to the + * directory containing the config file. Passed to ` build -f`. + */ + containerfile: "string > 0", + /** + * Build context directory, absolute or relative to the directory containing + * the config file. + */ + context: "string > 0", + /** + * Container engine used to build the image. Omit to let Tuor auto-detect + * (docker, else podman). + */ + "engine?": "'docker' | 'podman'", + /** + * Whether to reuse a cached VM image build vs. whether to re-run ` + * build`. Allowed values: + * + * - always: build on every run, and rebuild the VM image from the result. + * The engine's own layer cache still applies, so an unchanged + * Containerfile rebuilds quickly. + * - if-not-present: skip the build if Tuor already has cached the VM image + * for `ref`. Fastest, but with the caveat that changes in the + * Containerfile or build context won't trigger a rebuild (since the `ref` + * is the same). + */ + buildPolicy: "'always' | 'if-not-present'", + }, }).export(); export type GuestUserConfig = typeof types.GuestUserConfig.infer; @@ -438,6 +504,8 @@ export type QemuConfig = typeof types.QemuConfig.infer; export type ResourcesConfig = typeof types.ResourcesConfig.infer; export type RootfsConfig = typeof types.RootfsConfig.infer; export type RootfsImageConfig = typeof types.RootfsImageConfig.infer; +export type RootfsImagePullConfig = typeof types.RootfsImagePullConfig.infer; +export type RootfsImageBuildConfig = typeof types.RootfsImageBuildConfig.infer; export type NetworkConfig = typeof types.NetworkConfig.infer; export type EnvFromHost = typeof types.EnvFromHost.infer; export type EnvSecret = typeof types.EnvSecret.infer; diff --git a/src/core/image.test.ts b/src/core/image.test.ts index a41e6f9..aa924ca 100644 --- a/src/core/image.test.ts +++ b/src/core/image.test.ts @@ -8,18 +8,28 @@ import type { } from "@earendil-works/gondolin"; import { getDefaultBuildConfig } from "@earendil-works/gondolin"; import { describe, expect, test } from "vitest"; +import type { ContainerEngine } from "./image.ts"; import { + _detectEngine, + _engineBuildArgs, _hasCachedAssets, _hostArch, + _ociPlatform, _preflightBuildTools, _tuorImageRef, ensureImageAssets, type ImageDeps, parseSizeToMb, + type RootfsImageBuildSource, + type RootfsImagePullSource, type RootfsImageSpec, } from "./image.ts"; -function spec(overrides: Partial = {}): RootfsImageSpec { +type PullSpec = RootfsImagePullSource & { rootfsSizeMb?: number }; +type BuildSpec = RootfsImageBuildSource & { rootfsSizeMb?: number }; + +/** A pull-variant spec: the OCI image already exists somewhere. */ +function spec(overrides: Partial = {}): PullSpec { return { ref: "docker.io/library/debian:bookworm-slim", pullPolicy: "if-not-present", @@ -28,6 +38,17 @@ function spec(overrides: Partial = {}): RootfsImageSpec { }; } +/** A build-variant spec: the OCI image is produced from a Containerfile. */ +function buildSpec(overrides: Partial = {}): BuildSpec { + return { + ref: "my-devbox", + containerfile: "/proj/Containerfile", + context: "/proj", + buildPolicy: "if-not-present", + ...overrides, + }; +} + function ref( reference: string, targets: LocalImageRef["targets"], @@ -154,6 +175,31 @@ describe("_tuorImageRef", () => { ), ); }); + + /** Same for the build variant — and the Containerfile is not hashed either. */ + test("keys a build spec on its ref alone", () => { + expect( + _tuorImageRef( + buildSpec({ + buildPolicy: "always", + containerfile: "/elsewhere/Containerfile", + context: "/elsewhere", + }), + "x86_64", + "0.12.0", + ), + ).toBe(_tuorImageRef(buildSpec(), "x86_64", "0.12.0")); + }); + + /** + * `docker build -t foo` and `docker pull foo` name the same image, so the two + * variants sharing a cache entry for the same ref is correct, not a clash. + */ + test("keys both variants alike, so the same ref shares one entry", () => { + expect(_tuorImageRef(buildSpec({ ref: "x" }), "x86_64", "0.12.0")).toBe( + _tuorImageRef(spec({ ref: "x" }), "x86_64", "0.12.0"), + ); + }); }); describe("_hasCachedAssets", () => { @@ -179,6 +225,47 @@ describe("_hasCachedAssets", () => { }); }); +describe("_detectEngine", () => { + test("prefers docker when both are installed", () => { + expect(_detectEngine(probe(["docker", "podman"]))).toBe("docker"); + }); + + test("falls back to podman when docker is absent", () => { + expect(_detectEngine(probe(["podman"]))).toBe("podman"); + }); +}); + +describe("_ociPlatform", () => { + test.each([ + ["x86_64", "linux/amd64"], + ["aarch64", "linux/arm64"], + ] as const)("maps %s to %s", (arch, expected) => { + expect(_ociPlatform(arch)).toBe(expected); + }); +}); + +describe("_engineBuildArgs", () => { + test("passes the tag, Containerfile and context, with the context last", () => { + expect( + _engineBuildArgs({ + ref: "my-devbox", + containerfile: "/proj/Containerfile", + context: "/proj", + platform: "linux/amd64", + }), + ).toEqual([ + "build", + "--platform", + "linux/amd64", + "-t", + "my-devbox", + "-f", + "/proj/Containerfile", + "/proj", + ]); + }); +}); + describe("_preflightBuildTools", () => { test("passes when every tool is present", () => { expect(() => @@ -269,6 +356,7 @@ type ImageCalls = { buildId: string; arch: Architecture; }>; + engineBuilds: Array<{ engine: ContainerEngine; args: string[] }>; logs: string[]; }; @@ -280,6 +368,10 @@ type HarnessOptions = { gondolinVersion?: string; /** Runs inside the fake `buildAssets` — throw here to model a failed build. */ onBuild?: (options: BuildOptions) => void; + /** Image tags the container engine's local store already holds. */ + localImages?: string[]; + /** Runs inside the fake engine build — throw here to model a failed build. */ + onEngineBuild?: () => void; }; /** @@ -296,6 +388,8 @@ function harness(options: HarnessOptions = {}): { arch = "x86_64", gondolinVersion = FAKE_GONDOLIN_VERSION, onBuild, + localImages = [], + onEngineBuild, } = options; const calls: ImageCalls = { @@ -303,11 +397,17 @@ function harness(options: HarnessOptions = {}): { buildAssets: [], importImageFromDirectory: [], setImageRef: [], + engineBuilds: [], logs: [], }; const deps: ImageDeps = { hasCommand: probe(installed), + runEngineBuild: (engine, args) => { + calls.engineBuilds.push({ engine, args }); + onEngineBuild?.(); + }, + hasLocalImage: (_engine, imageRef) => localImages.includes(imageRef), listImageRefs: () => refs, resolveImageSelector: (selector, selectorArch) => { calls.resolveImageSelector.push({ selector, arch: selectorArch }); @@ -560,6 +660,158 @@ describe("ensureImageAssets", () => { ); expect(calls.buildAssets).toHaveLength(0); }); + + test("fails before invoking the engine when a tool is missing", async () => { + const { deps, calls } = harness({ + installed: ALL_TOOLS.filter((t) => t !== "cpio"), + }); + + await expect(ensureImageAssets(buildSpec(), deps)).rejects.toThrow( + /cpio/, + ); + expect(calls.engineBuilds).toHaveLength(0); + expect(calls.buildAssets).toHaveLength(0); + }); + }); + + describe("building from a Containerfile", () => { + test("builds the image, then the guest assets from it", async () => { + const { deps, calls } = harness(); + + await expect(ensureImageAssets(buildSpec(), deps)).resolves.toBe( + "/store/built", + ); + expect(calls.engineBuilds).toEqual([ + { + engine: "docker", + args: _engineBuildArgs({ + ref: "my-devbox", + containerfile: "/proj/Containerfile", + context: "/proj", + platform: "linux/amd64", + }), + }, + ]); + // The freshly built image is local-only, so Gondolin must not go looking + // for `my-devbox` in a registry. + expect(builtConfig(calls).oci).toEqual({ + image: "my-devbox", + pullPolicy: "never", + runtime: "docker", + }); + }); + + /** + * Unlike the pull variant, the engine is never left for Gondolin to detect: + * we build with one and it must export with the same one. + */ + test("forwards the auto-detected engine to Gondolin", async () => { + const { deps, calls } = harness({ + installed: ALL_TOOLS.filter((t) => t !== "docker"), + }); + + await ensureImageAssets(buildSpec(), deps); + expect(calls.engineBuilds[0]!.engine).toBe("podman"); + expect(builtConfig(calls).oci?.runtime).toBe("podman"); + }); + + test("honors an explicitly configured engine", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(buildSpec({ engine: "podman" }), deps); + expect(calls.engineBuilds[0]!.engine).toBe("podman"); + expect(builtConfig(calls).oci?.runtime).toBe("podman"); + }); + + test("builds for the injected architecture", async () => { + const { deps, calls } = harness({ arch: "aarch64" }); + + await ensureImageAssets(buildSpec(), deps); + expect(calls.engineBuilds[0]!.args).toContain("linux/arm64"); + }); + + describe("buildPolicy if-not-present", () => { + test("skips both builds when guest assets are cached", async () => { + const { deps, calls } = harness({ + refs: [cachedRef(buildSpec(), "x86_64")], + }); + + await expect(ensureImageAssets(buildSpec(), deps)).resolves.toBe( + "/store/cached", + ); + expect(calls.engineBuilds).toHaveLength(0); + expect(calls.buildAssets).toHaveLength(0); + }); + + /** + * Second rung of the ladder: the guest assets are gone but the OCI image + * is still there — possibly built by hand — so only the assets are rebuilt. + */ + test("reuses an existing image, rebuilding only the guest assets", async () => { + const { deps, calls } = harness({ localImages: ["my-devbox"] }); + + await expect(ensureImageAssets(buildSpec(), deps)).resolves.toBe( + "/store/built", + ); + expect(calls.engineBuilds).toHaveLength(0); + expect(calls.buildAssets).toHaveLength(1); + expect(calls.logs.join("\n")).toMatch(/Using existing docker image/); + }); + + test("builds when the engine holds a different image", async () => { + const { deps, calls } = harness({ localImages: ["some-other-image"] }); + + await ensureImageAssets(buildSpec(), deps); + expect(calls.engineBuilds).toHaveLength(1); + }); + }); + + describe("buildPolicy always", () => { + const s = buildSpec({ buildPolicy: "always" }); + + /** + * The cache key is the ref, which doesn't change when the Containerfile + * does — so reusing cached assets here would silently discard the image we + * just rebuilt, making "always" a no-op. + */ + test("rebuilds the guest assets despite a cache hit", async () => { + const { deps, calls } = harness({ refs: [cachedRef(s, "x86_64")] }); + + await expect(ensureImageAssets(s, deps)).resolves.toBe("/store/built"); + expect(calls.engineBuilds).toHaveLength(1); + expect(calls.buildAssets).toHaveLength(1); + }); + + test("rebuilds the image even though the engine already has it", async () => { + const { deps, calls } = harness({ localImages: ["my-devbox"] }); + + await ensureImageAssets(s, deps); + expect(calls.engineBuilds).toHaveLength(1); + }); + }); + + test("does not build guest assets when the engine build fails", async () => { + const { deps, calls } = harness({ + onEngineBuild: () => { + throw new Error("Containerfile step 3 failed"); + }, + }); + + await expect(ensureImageAssets(buildSpec(), deps)).rejects.toThrow( + "Containerfile step 3 failed", + ); + expect(calls.buildAssets).toHaveLength(0); + }); + + test("bakes the rootfs size into the guest assets", async () => { + const { deps, calls } = harness(); + + await ensureImageAssets(buildSpec({ rootfsSizeMb: 8192 }), deps); + expect(builtConfig(calls).rootfs).toEqual({ + ...getDefaultBuildConfig().rootfs, + sizeMb: 8192, + }); + }); }); describe("scratch dir", () => { diff --git a/src/core/image.ts b/src/core/image.ts index 70ed9bb..b16a365 100644 --- a/src/core/image.ts +++ b/src/core/image.ts @@ -27,25 +27,60 @@ export type RootfsBuildPolicy = "always" | "if-not-present"; export type ContainerEngine = "docker" | "podman"; /** - * Core's input contract for a custom guest rootfs: the OCI image to build from - * plus the knobs that affect the built assets. - * - * The two policies are independent axes: `pullPolicy` says where the OCI image - * comes from, `buildPolicy` whether the guest assets are rebuilt from it. Since - * a reused asset needs no image at all, `pullPolicy` only matters on the runs - * that actually build. + * Reference to an existing OCI image {@link buildAndStore} that we can hand to + * Gondolin, plus how exactly Gondolin should obtain it. Covers only the + * *image*; whether guest assets get rebuilt from it is `buildPolicy`, a + * separate axis. */ -export type RootfsImageSpec = { +type OciImageSource = { /** OCI image ref: `repo/name[:tag]` or `repo/name@sha256:…`. */ ref: string; pullPolicy: RootfsPullPolicy; - buildPolicy: RootfsBuildPolicy; /** Omitted → Gondolin auto-detects (docker, else podman). */ engine?: ContainerEngine; +}; + +/** Use an OCI image that already exists, pulling it when necessary. */ +export type RootfsImagePullSource = OciImageSource & { + buildPolicy: RootfsBuildPolicy; +}; + +/** + * Build the OCI image from a Containerfile first, then use it like a pulled + * one. Gondolin only pulls/creates/exports existing images, so the + * ` build` step is ours. + */ +export type RootfsImageBuildSource = { + /** Tag to build into; also the cache identity (contents are *not* hashed). */ + ref: string; + /** Absolute path to the Containerfile/Dockerfile. */ + containerfile: string; + /** Absolute path to the build context directory. */ + context: string; + buildPolicy: RootfsBuildPolicy; + /** Omitted → auto-detected (docker, else podman). */ + engine?: ContainerEngine; +}; + +/** + * Core's input contract for a custom guest rootfs: where the OCI image comes + * from plus the knobs that affect the built assets. + */ +export type RootfsImageSpec = ( + | RootfsImagePullSource + | RootfsImageBuildSource +) & { /** Total rootfs size baked into the built image (see `parseSizeToMb`). */ rootfsSizeMb?: number; }; +/** Narrow a spec to the Containerfile variant. Both variants carry a `ref`. */ +function isBuildSpec( + spec: RootfsImageSpec, +): spec is RootfsImageBuildSource & { rootfsSizeMb?: number } { + return "containerfile" in spec; +} + /** * Injectable seams for {@link ensureImageAssets}: the Gondolin entry points it * drives plus host probing and logging. Exists so the cache decision and the @@ -54,6 +89,10 @@ export type RootfsImageSpec = { export type ImageDeps = { /** Whether `command` is on PATH. */ hasCommand: (command: string) => boolean; + /** Run ` build …`, streaming its output to the user's terminal. */ + runEngineBuild: (engine: ContainerEngine, args: string[]) => void; + /** Whether ``'s local store already holds an image tagged `ref`. */ + hasLocalImage: (engine: ContainerEngine, ref: string) => boolean; listImageRefs: () => LocalImageRef[]; resolveImageSelector: ( selector: string, @@ -91,8 +130,11 @@ export type ImageDeps = { * * Building is slow (image pull + mke2fs), so it happens at most once per cache * identity — unless `buildPolicy` is "always", which rebuilds every run. - * `pullPolicy` governs the separate question of where the OCI image comes - * from, and so only matters on the runs that do build. + * `pullPolicy` (pull variant) governs the separate question of where the OCI + * image comes from, and so only matters on the runs that do build. + * + * For a Containerfile spec the OCI image itself doesn't exist yet, so an + * ` build` runs first; see {@link ensureOciImage}. */ export async function ensureImageAssets( spec: RootfsImageSpec, @@ -110,7 +152,8 @@ export async function ensureImageAssets( // helper binaries (which it does before reaching its own engine check). _preflightBuildTools(spec.engine, deps.hasCommand); - return await buildAndStore(spec, arch, tuorRef, deps); + const source = isBuildSpec(spec) ? ensureOciImage(spec, arch, deps) : spec; + return await buildAndStore(source, spec.rootfsSizeMb, arch, tuorRef, deps); } /** @@ -217,8 +260,9 @@ export function _hasCachedAssets( * exit code that names nothing, and the container-engine check only runs after * sandbox helper binaries have been downloaded. * - * We deliberately do not pick an engine — that stays Gondolin's job. We just - * assert that *some* engine exists. + * This only asserts that a usable engine exists; picking one is Gondolin's job + * for the pull variant, and {@link _detectEngine}'s for the Containerfile + * variant (which needs a concrete engine of its own to build with). */ export function _preflightBuildTools( engine: ContainerEngine | undefined, @@ -273,8 +317,88 @@ function resolveCached( return deps.resolveImageSelector(tuorRef, arch).assetDir; } +/** + * Make sure the OCI image named by `spec.ref` exists in the engine's local + * store, building it from the Containerfile when it doesn't, and describe it + * the way {@link buildAndStore} wants. + * + * The result is always `pullPolicy: "never"`: the image is local-only and + * Gondolin should not pull. + */ +function ensureOciImage( + spec: RootfsImageBuildSource, + arch: Architecture, + deps: ImageDeps, +): OciImageSource { + // Unlike the pull variant we resolve the engine ourselves and pass it on, so + // that the build below and Gondolin's later export can't pick different ones. + const engine = spec.engine ?? _detectEngine(deps.hasCommand); + + // Build policy "always" rebuilds unconditionally; the engine's layer cache + // keeps that (relatively) cheap when nothing changed. Otherwise + // ("if-not-present") take the image already tagged as `ref`. + const skipBuild = + spec.buildPolicy === "if-not-present" && + deps.hasLocalImage(engine, spec.ref); + + if (skipBuild) { + deps.log(`Using existing ${engine} image ${spec.ref}.`); + } else { + deps.log(`Building ${spec.ref} from ${spec.containerfile} with ${engine}…`); + deps.runEngineBuild( + engine, + _engineBuildArgs({ + ref: spec.ref, + containerfile: spec.containerfile, + context: spec.context, + platform: _ociPlatform(arch), + }), + ); + } + + return { ref: spec.ref, pullPolicy: "never", engine }; +} + +/** + * Pick a container engine the way Gondolin's own `detectOciRuntime` does. + * Callers are expected to have run {@link _preflightBuildTools} first, which is + * where the "no engine at all" case gets its actionable error message. + */ +export function _detectEngine( + hasCommand: (command: string) => boolean, +): ContainerEngine { + return hasCommand("docker") ? "docker" : "podman"; +} + +/** The OCI platform Gondolin will export for — mirrors its `getOciPlatform`. */ +export function _ociPlatform(arch: Architecture): string { + return arch === "x86_64" ? "linux/amd64" : "linux/arm64"; +} + +/** + * Argument vector for ` build`. + */ +export function _engineBuildArgs(args: { + ref: string; + containerfile: string; + context: string; + platform: string; +}): string[] { + return [ + "build", + "--platform", + args.platform, + "-t", + args.ref, + "-f", + args.containerfile, + args.context, + ]; +} + async function buildAndStore( - spec: RootfsImageSpec, + source: OciImageSource, + rootfsSizeMb: number | undefined, arch: Architecture, tuorRef: string, deps: ImageDeps, @@ -284,16 +408,16 @@ async function buildAndStore( ...defaults, arch, oci: { - image: spec.ref, - pullPolicy: spec.pullPolicy, - // Only forwarded when the user asked for a specific engine; otherwise - // Gondolin auto-detects. - ...(spec.engine ? { runtime: spec.engine } : {}), + image: source.ref, + pullPolicy: source.pullPolicy, + // Only forwarded when we know which engine to use; otherwise Gondolin + // auto-detects. + ...(source.engine ? { runtime: source.engine } : {}), }, // Merge rather than replace, so Gondolin's default volume label survives. // A baked size needs no in-guest resize2fs at boot. - ...(spec.rootfsSizeMb - ? { rootfs: { ...defaults.rootfs, sizeMb: spec.rootfsSizeMb } } + ...(rootfsSizeMb + ? { rootfs: { ...defaults.rootfs, sizeMb: rootfsSizeMb } } : {}), }; @@ -302,7 +426,7 @@ async function buildAndStore( const outputDir = mkdtempSync(join(tmpdir(), "tuor-build-")); try { deps.log( - `Building custom rootfs from ${spec.ref} (this can take a while)…`, + `Building custom rootfs from ${source.ref} (this can take a while)…`, ); await deps.buildAssets(buildConfig, { outputDir }); @@ -332,6 +456,25 @@ function hasCommandOnPath(command: string): boolean { } } +/** + * `stdio: "inherit"` on purpose: a cold `docker build` can run for minutes, and + * its progress output is the only sign that anything is happening. A failure + * surfaces as execFileSync's throw, with the engine's own diagnostics already on + * the user's terminal. + */ +function runEngineBuildOnHost(engine: ContainerEngine, args: string[]): void { + execFileSync(engine, args, { stdio: "inherit" }); +} + +function hasLocalImageInStore(engine: ContainerEngine, ref: string): boolean { + try { + execFileSync(engine, ["image", "inspect", ref], { stdio: "ignore" }); + return true; + } catch { + return false; + } +} + /** * Read the *installed* Gondolin's version at runtime (not the one Tuor was built * against), since Tuor depends on a version range. @@ -350,6 +493,8 @@ function readGondolinVersion(): string { const defaultImageDeps: ImageDeps = { hasCommand: hasCommandOnPath, + runEngineBuild: runEngineBuildOnHost, + hasLocalImage: hasLocalImageInStore, listImageRefs, resolveImageSelector, importImageFromDirectory, From 765e61b4bae2c526ed3f3c3446c43dbf1153dd57 Mon Sep 17 00:00:00 2001 From: codethief Date: Mon, 24 Aug 2026 00:27:28 +0200 Subject: [PATCH 4/5] Document how config inheritance/merging works --- docs/Configuration.md | 58 ++++++++++++++++++++++++++++++++++--------- src/config/merge.ts | 7 +++++- 2 files changed, 52 insertions(+), 13 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index 6bb805d..291c74a 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -10,22 +10,56 @@ that VSCode uses, too. An informal specification (not by Microsoft) can be found at https://jsonc.org/. -## Config inheritance +## Config options +A detailed documentation of all config options is still work in progress. In the +meantime, please refer to [`/src/config/schema.ts`](../src/config/schema.ts). + + +## Config inheritance & merging Configs in child directories inherit from configs in parent directories (and so -on), which in turn inherit from the global `~/.config/tuor/config.json`. In -general, child settings override parent settings, except in the following cases: +on), which in turn inherit from the global `~/.config/tuor/config.json`. The +individual config files don't need to provide all settings that are required by +the schema (see above); only the end result after merging them gets validated. -- Env vars, mounts, volumes get merged (shallow merge). -- Boot commands are concatenated (parent commands run first). -- Network: Child network mode overrides parent mode; allowed hosts are merged. -- `rootfs` gets merged field by field, so a child may set `size` without - restating `image` (or vice versa). `image` itself is *not* merged field-wise: - a child that specifies it replaces the parent's block entirely. +Relative host path references in a given config file (e.g. `workdir: "../foo"`) +are always evaluated relative to *that* config file's location, before it +potentially gets merged with other configs. -## Config options -A detailed documentation of all config options is still work in progress. In the -meantime, please refer to [`/src/config/schema.ts`](../src/config/schema.ts). +**How inheritance works:** In general, top-level settings in the child config +override top-level settings in the parent config. However, in some cases +settings are deep-merged and the config inheritance algorithm descends down the +config schema tree, or values are concatenated with the parent config (e.g. in +case of lists), as indicated below: + +```jsonc +{ + "bootCommands": [], // concatenate with parent list (parent commands run first) + "env": {}, // concatenate/shallow-merge with parent dictionary + "guestUser?": {}, // override parent + "mounts": [], // concatenate with parent list + "network": { + "mode": "", // override parent + "allowedHosts": [], // concatenate with parent list + "allowedInternalHosts": [], // concatenate with parent list + }, + "qemu": { + "accel": "", // override parent + "cpu": "", // override parent + "machineType": "", // override parent + }, // ? + "resources": { + "cpus": "", // override parent + "memory": "", // override parent + }, // ? + "rootfs": { + "image": {}, // override parent + "size": "", // override parent + }, + "volumes": [], // concatenate with parent list + "workdir": {} /* or string value */, // override parent +} +``` ## Variables diff --git a/src/config/merge.ts b/src/config/merge.ts index 7cec681..efb3ff6 100644 --- a/src/config/merge.ts +++ b/src/config/merge.ts @@ -86,7 +86,12 @@ export function mergeConfigs(layers: ConfigLayer[]): TuorConfig { // --- Internals --- -/** Merge two configs where `child` overrides `parent`. */ +/** + * Merge two configs where `child` overrides `parent`. + * + * The behavior here should be kept in sync with the documentation in + * /docs/Configuration.md . + */ function mergeTwoConfigs(parent: TuorConfig, child: TuorConfig): TuorConfig { return { // Scalars: child wins, falling back to parent when the child omits the From 568ec03128eead38ebe6acea724077849121d049 Mon Sep 17 00:00:00 2001 From: codethief Date: Sat, 10 Oct 2026 06:55:35 +0200 Subject: [PATCH 5/5] Document upstream issues in QEMU and Gondolin related to custom builds --- docs/Limitations & known issues.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/Limitations & known issues.md b/docs/Limitations & known issues.md index 69d9c06..f489fa5 100644 --- a/docs/Limitations & known issues.md +++ b/docs/Limitations & known issues.md @@ -6,6 +6,20 @@ reason, the user (and his home dir) are currently hard-coded at the Tuor config level, though you could of course `su` to a non-root user inside the VM. +## VM might hang during boot when using custom images and memory is set to exactly 2 GiB +This is an [upstream issue in +QEMU](https://gitlab.com/qemu-project/qemu/-/work_items/3454). Whether or not +you will actually run into this bug depends on the size of the VM's initramfs +(mod 4096) that Gondolin produces, which [is a bit of a +gamble](https://github.com/earendil-works/gondolin/issues/166). If you do, as a +workaround set your VM's memory to a value slightly different from 2 GiB. + + +## The initramfs of custom images is unusually big (~ 50 MiB) and much bigger than the default image's one +See the note at the end of the aforementioned +https://github.com/earendil-works/gondolin/issues/166 . + + ## Mounts & volumes don't support creating Unix file sockets This is a limitation in Gondolin's `sandboxfs` FUSE, which does not support the `MKNOD` syscall.