@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/image-preflight.mjs

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { imageRefProblem } from "./image-ref.mjs";
 
 /**
  * Which image a job runs in, and whether it is on this host.
@@ -7,9 +8,9 @@ import { spawn } from "node:child_process";
  * `docker run` is handed. Both sides resolve through `resolveJobImage`, so there is one answer by
  * construction rather than by two call sites happening to match.
  *
- * This module imports nothing but `node:child_process` -- deliberately. `run-container.mjs` pulls in
- * `env-allowlist.mjs` and therefore `@earendil-works/pi-ai`, which is why its tests sit behind a
- * node-version skip guard. This is a money gate: it decides whether a budget slot is spent, so its tests
+ * This module imports nothing but `node:child_process` and the import-free `image-ref.mjs` -- deliberately.
+ * `run-container.mjs` pulls in `env-allowlist.mjs` and therefore `@earendil-works/pi-ai`, which is why its tests sit
+ * behind a node-version skip guard. This is a money gate: it decides whether a budget slot is spent, so its tests
  * must run everywhere, unconditionally.
  */
 
@@ -20,7 +21,16 @@ import { spawn } from "node:child_process";
  * is how that is guaranteed rather than hoped for.
  */
 export function resolveJobImage(job, defaultImage) {
-	return job?.image ?? defaultImage;
+	const image = job?.image ?? defaultImage;
+	// The one image rule (`image-ref.mjs`, issue #471 gate round 1), where every consumer resolves the image: a job queued
+	// with a value it refuses (enqueued before the rule reached the CLI, or by any other producer) is a config error here,
+	// which the processor refuses as `config-refused` before any spend, since the preflight resolves first. So no argv is
+	// ever handed a flag where the image belongs.
+	// A caller with no default and a job with none (`prepare.mjs`'s unwired stamp) resolves to nothing, as before.
+	if (image === null || image === undefined) return image;
+	const problem = imageRefProblem(image);
+	if (problem) throw Object.assign(new Error(`the job image ${problem.reason} (got ${JSON.stringify(image)})`), { piDispatchConfig: true });
+	return image;
 }
 
 /**
@@ -34,6 +44,8 @@ export function resolveJobImage(job, defaultImage) {
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
  *   { replicaUnsupported }-- present, but does not declare replica support for a replica job => POLICY
  *   { commandUnsupported }-- present, but does not declare command support for a command job => POLICY
+ *   { excludeToolsUnsupported } -- present, but does not declare exclude-tools support for a job that
+ *                            carries exclusions => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
  * so the failure path disambiguates POSITIVELY with `docker info` rather than by matching docker's stderr.
@@ -46,7 +58,9 @@ export function resolveJobImage(job, defaultImage) {
  * `unavailable` and retry; if it comes up between them we report `missing` on an image that is genuinely
  * absent. Nothing is cached, deliberately -- see the note at the call site in start.mjs.
  */
-export function makeImagePreflight({ image, spawnFn = spawn }) {
+export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
+	// Issue #354: `bin` is the venue's CLI. Both probes go through it, because a `podman image inspect` answered by one
+	// store and an `info` answered by another daemon would tell "absent" from "unavailable" about two different hosts.
 	return async function imagePreflight(job) {
 		const wanted = resolveJobImage(job, image);
 		// --format keeps docker from serialising the whole image manifest to a pipe we ignore.
@@ -68,7 +82,7 @@ export function makeImagePreflight({ image, spawnFn = spawn }) {
 		// HARD_RULES.md whose rule 3 hard-codes `pi/issue-<n>` -- and that is the SYSTEM prompt, which the
 		// model treats as authoritative. Both replicas would converge on one branch and the feature would
 		// become the push race it exists to avoid, with nothing in the run record saying so.
-		const probe = await runDocker(spawnFn, ["image", "inspect", `--format={{.Id}}${FIELD_SEP}${PI_VERSION_TEMPLATE}${FIELD_SEP}${FORGES_TEMPLATE}${FIELD_SEP}${CAPABILITIES_TEMPLATE}`, wanted], true);
+		const probe = await runDocker(bin, spawnFn, ["image", "inspect", `--format={{.Id}}${FIELD_SEP}${PI_VERSION_TEMPLATE}${FIELD_SEP}${FORGES_TEMPLATE}${FIELD_SEP}${CAPABILITIES_TEMPLATE}`, wanted], true);
 		if (probe.code === 0) {
 			const [piVersion, forges, capabilities, imageDigest] = parseLabels(probe.stdout);
 			const kind = job?.kind;
@@ -96,9 +110,19 @@ export function makeImagePreflight({ image, spawnFn = spawn }) {
 			if (job?.command !== undefined && !(capabilities ?? []).includes("commands")) {
 				return { commandUnsupported: wanted, declared: capabilities ?? [] };
 			}
-			return { ok: true, image: wanted, piVersion, imageDigest };
+			// Same inclusion-list polarity again, and here the stale-image failure is a PERMISSION quietly
+			// not enforced (issue #291): a runner that predates run.excludeTools reads no PI_EXCLUDE_TOOLS,
+			// so a "read-only" trigger's job would run with every tool the file says to remove and record a
+			// clean exit -- the silent fail-open this field exists to close. Unreachable for a job without
+			// exclusions, so the existing fleet pays nothing for it.
+			if (job?.excludeTools !== undefined && !(capabilities ?? []).includes("excludeTools")) {
+				return { excludeToolsUnsupported: wanted, declared: capabilities ?? [] };
+			}
+			// `capabilities` rides the ok result for issue #341's job-user gate, which needs `anyUid` and runs after
+			// this preflight; an image that declares nothing reads as [].
+			return { ok: true, image: wanted, piVersion, imageDigest, capabilities: capabilities ?? [] };
 		}
-		if ((await runDocker(spawnFn, ["info"])).code === 0) return { missing: wanted };
+		if ((await runDocker(bin, spawnFn, ["info"])).code === 0) return { missing: wanted };
 		return { unavailable: wanted };
 	};
 }
@@ -139,13 +163,24 @@ function parseLabels(stdout) {
 	// string had four fields and was thrown away until issue #57, which needs it to answer "are these two
 	// hosts running the same image?" -- a question `OQ-012` records as unanswerable and which turns out to
 	// cost nothing to answer, because the inspect that would have asked it already runs.
-	const imageDigest = label(parts[0]);
+	const imageDigest = normalizeImageId(label(parts[0]));
 	const piVersion = label(parts[1]);
 	// A label that is present but parses to nothing usable is treated as ABSENT rather than as an empty
 	// list -- on `forges` the latter would refuse every job on an image whose label was merely malformed.
 	return [piVersion, list(parts[2]), list(parts[3]), imageDigest];
 }
 
+/**
+ * One spelling of an image id across runtimes (issue #354): Podman's `{{.Id}}` is the bare 64-hex digest where docker's
+ * carries `sha256:` (both measured). The id is published to the fleet registry and compared host against host by
+ * `doctor`, so without this a podman host and a docker host running one image would disagree on every read. ONLY the
+ * exact bare form gains the prefix; anything else passes through untouched, so a string this rule does not recognise is
+ * never made to look like a digest it is not.
+ */
+export function normalizeImageId(id) {
+	return typeof id === "string" && /^[0-9a-f]{64}$/.test(id) ? `sha256:${id}` : id;
+}
+
 /** One comma-separated label value as a non-empty array, or `null` when it declares nothing usable. */
 function list(raw) {
 	const value = label(raw);
@@ -170,11 +205,11 @@ function label(raw) {
  * answer "did the daemon reply", and piping output we would not read is how a probe becomes a place a
  * large payload can arrive.
  */
-function runDocker(spawnFn, args, capture = false) {
+function runDocker(bin, spawnFn, args, capture = false) {
 	return new Promise((resolve) => {
 		let child;
 		try {
-			child = spawnFn("docker", args, { stdio: capture ? ["ignore", "pipe", "ignore"] : "ignore" });
+			child = spawnFn(bin, args, { stdio: capture ? ["ignore", "pipe", "ignore"] : "ignore" });
 		} catch {
 			resolve({ code: null, stdout: "" });
 			return;

package/src/image-ref.mjs

@@ -0,0 +1,21 @@
+/**
+ * THE one rule for an image reference this project hands a container runtime as its image positional (issue #471):
+ * `run.image` in the triggers file (`triggers.mjs`), `PI_JOB_IMAGE` at the worker's boot (`config.mjs`), and the image
+ * doctor inspects and runs (`doctor.mjs`). Before #471 only `run.image` was judged, so a `PI_JOB_IMAGE` of `--help`
+ * booted a worker whose every job handed docker a flag where the image belongs.
+ *
+ * Deliberately NOT the OCI grammar (`triggers.mjs` says why: docker validates its own grammar, and an over-strict regex
+ * takes a valid deployment down at boot). Each refusal names a value that corrupts something on OUR side: a blank one
+ * throws inside the argv builder after a budget slot is reserved, surrounding whitespace means the file disagrees with
+ * what runs, a leading `-` is read as a flag by the runtime's parser, and a control character reaches argv, logs and a
+ * terminal as bytes nobody wrote on purpose.
+ *
+ * Returns null for an acceptable reference, else `{ code, reason }`, `reason` a clause to follow the value's name.
+ */
+export function imageRefProblem(image) {
+	if (typeof image !== "string" || image.trim() === "") return { code: "blank", reason: "must be a non-empty string" };
+	if (image !== image.trim()) return { code: "padded", reason: "must not have leading or trailing whitespace" };
+	if (image.startsWith("-")) return { code: "dash", reason: 'must not start with "-", which the runtime reads as a flag where the image belongs' };
+	if (/[\u0000-\u001f\u007f-\u009f]/.test(image)) return { code: "control", reason: "must not hold a control character" };
+	return null;
+}