feat: add dev base image preflight
This commit is contained in:
HWLAB Code Queue
@@ -0,0 +1,471 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
import { ENVIRONMENT_DEV, SERVICE_IDS } from "../../internal/protocol/index.mjs";
|
||||
|
||||
const envVarName = "HWLAB_DEV_BASE_IMAGE";
|
||||
const dockerCommand = "docker";
|
||||
const dockerTimeoutMs = 15_000;
|
||||
const node20TagPattern = /^20-/u;
|
||||
const forbiddenImageFragments = Object.freeze([
|
||||
"unidesk",
|
||||
"backend-core",
|
||||
"provider-gateway",
|
||||
"microservice-proxy",
|
||||
"code-queue"
|
||||
]);
|
||||
const allowedExplicitBaseImages = Object.freeze([
|
||||
"node:20-*",
|
||||
"hwlab-dev-base:*",
|
||||
"*/hwlab-dev-base:*",
|
||||
"hwlab-node20-base:*",
|
||||
"*/hwlab-node20-base:*"
|
||||
]);
|
||||
|
||||
function runDocker(args) {
|
||||
const result = spawnSync(dockerCommand, args, {
|
||||
encoding: "utf8",
|
||||
timeout: dockerTimeoutMs
|
||||
});
|
||||
|
||||
return {
|
||||
ok: result.status === 0,
|
||||
status: result.status,
|
||||
signal: result.signal,
|
||||
errorCode: result.error?.code ?? null,
|
||||
stdout: result.stdout?.trim() ?? "",
|
||||
stderr: result.stderr?.trim() ?? "",
|
||||
timedOut: result.error?.code === "ETIMEDOUT"
|
||||
};
|
||||
}
|
||||
|
||||
function splitJsonLines(stdout) {
|
||||
return stdout
|
||||
.split("\n")
|
||||
.map((line) => line.trim())
|
||||
.filter(Boolean)
|
||||
.map((line) => JSON.parse(line));
|
||||
}
|
||||
|
||||
function candidateTag(image) {
|
||||
return `${image.Repository}:${image.Tag}`;
|
||||
}
|
||||
|
||||
function imageRefFromInspect(requestedImage, inspectDoc) {
|
||||
const repoTags = Array.isArray(inspectDoc.RepoTags) ? inspectDoc.RepoTags : [];
|
||||
if (repoTags.includes(requestedImage)) {
|
||||
return requestedImage;
|
||||
}
|
||||
return repoTags.find((tag) => !tag.includes("<none>")) ?? requestedImage;
|
||||
}
|
||||
|
||||
function isNode20BaseRef(imageRef) {
|
||||
const lowerRef = imageRef.toLowerCase();
|
||||
return lowerRef.startsWith("node:20-");
|
||||
}
|
||||
|
||||
function isHwlabDevBaseRef(imageRef) {
|
||||
const lowerRef = imageRef.toLowerCase();
|
||||
return /(^|\/)(hwlab-dev-base|hwlab-node20-base)(?=[:@]|$)/u.test(lowerRef);
|
||||
}
|
||||
|
||||
function approvalForBaseRef(imageRef) {
|
||||
if (isNode20BaseRef(imageRef)) {
|
||||
return {
|
||||
approved: true,
|
||||
reason: "local Node 20 builder base image"
|
||||
};
|
||||
}
|
||||
if (isHwlabDevBaseRef(imageRef)) {
|
||||
return {
|
||||
approved: true,
|
||||
reason: "explicit HWLAB DEV builder base image"
|
||||
};
|
||||
}
|
||||
return {
|
||||
approved: false,
|
||||
reason: `image reference is not one of the approved builder base patterns: ${allowedExplicitBaseImages.join(", ")}`
|
||||
};
|
||||
}
|
||||
|
||||
function forbiddenReasons(imageRef) {
|
||||
const lowerRef = imageRef.toLowerCase();
|
||||
const reasons = [];
|
||||
|
||||
for (const fragment of forbiddenImageFragments) {
|
||||
if (lowerRef.includes(fragment)) {
|
||||
reasons.push(`image reference contains forbidden runtime/build substitute fragment: ${fragment}`);
|
||||
}
|
||||
}
|
||||
|
||||
for (const serviceId of SERVICE_IDS) {
|
||||
if (
|
||||
lowerRef.includes(`/pikastech/${serviceId}:`) ||
|
||||
lowerRef.includes(`/pikastech/${serviceId}@`) ||
|
||||
lowerRef.startsWith(`${serviceId}:`) ||
|
||||
lowerRef.startsWith(`${serviceId}@`)
|
||||
) {
|
||||
reasons.push(`image reference points at HWLAB service artifact ${serviceId}, not a builder base image`);
|
||||
}
|
||||
}
|
||||
|
||||
return reasons;
|
||||
}
|
||||
|
||||
function inspectEvidenceStrings(inspectDoc) {
|
||||
const labels = inspectDoc.Config?.Labels ?? {};
|
||||
const env = Array.isArray(inspectDoc.Config?.Env) ? inspectDoc.Config.Env : [];
|
||||
return [
|
||||
...(Array.isArray(inspectDoc.RepoTags) ? inspectDoc.RepoTags : []),
|
||||
...(Array.isArray(inspectDoc.RepoDigests) ? inspectDoc.RepoDigests : []),
|
||||
...Object.entries(labels).map(([key, value]) => `${key}=${value}`),
|
||||
...env
|
||||
].filter((value) => typeof value === "string" && value.length > 0);
|
||||
}
|
||||
|
||||
function inspectEvidenceBlockers(inspectDoc) {
|
||||
const blockers = [];
|
||||
for (const evidence of inspectEvidenceStrings(inspectDoc)) {
|
||||
for (const reason of forbiddenReasons(evidence)) {
|
||||
blockers.push(`${reason} in image inspect evidence ${JSON.stringify(evidence)}`);
|
||||
}
|
||||
}
|
||||
return [...new Set(blockers)];
|
||||
}
|
||||
|
||||
function baseResult(overrides) {
|
||||
return {
|
||||
preflight: "hwlab-dev-base-image",
|
||||
environment: ENVIRONMENT_DEV,
|
||||
status: "blocked",
|
||||
publishUsable: false,
|
||||
artifactPublish: {
|
||||
issue: "#35",
|
||||
usable: false,
|
||||
reason: "No approved local DEV builder base image was selected."
|
||||
},
|
||||
imageSource: "none",
|
||||
requestedImage: null,
|
||||
localTag: null,
|
||||
imageId: null,
|
||||
repoDigests: [],
|
||||
candidates: [],
|
||||
blockers: [],
|
||||
nextSteps: [],
|
||||
constraints: {
|
||||
localOnly: true,
|
||||
doesNotPull: true,
|
||||
doesNotBuild: true,
|
||||
doesNotPush: true,
|
||||
doesNotDeploy: true,
|
||||
doesNotReadSecrets: true,
|
||||
allowedExplicitBaseImages,
|
||||
forbiddenImageFragments,
|
||||
forbiddenHwlabServiceImages: SERVICE_IDS
|
||||
},
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
function blocked(overrides) {
|
||||
return baseResult({
|
||||
status: "blocked",
|
||||
publishUsable: false,
|
||||
artifactPublish: {
|
||||
issue: "#35",
|
||||
usable: false,
|
||||
reason: "DEV artifact publish must stop until the blocker is resolved."
|
||||
},
|
||||
...overrides
|
||||
});
|
||||
}
|
||||
|
||||
function ready({ imageSource, approval, requestedImage, localTag, inspectDoc, candidates }) {
|
||||
return baseResult({
|
||||
status: "ready",
|
||||
publishUsable: true,
|
||||
artifactPublish: {
|
||||
issue: "#35",
|
||||
usable: true,
|
||||
reason: "A local approved DEV builder base image is available."
|
||||
},
|
||||
imageSource,
|
||||
approval,
|
||||
requestedImage,
|
||||
localTag,
|
||||
imageId: inspectDoc.Id ?? null,
|
||||
repoDigests: Array.isArray(inspectDoc.RepoDigests) ? inspectDoc.RepoDigests : [],
|
||||
candidates,
|
||||
blockers: [],
|
||||
nextSteps: [
|
||||
"Use the reported localTag as the DEV builder base image for artifact publish.",
|
||||
"Keep publish DEV-only and record the produced HWLAB service image tags and digests separately."
|
||||
]
|
||||
});
|
||||
}
|
||||
|
||||
function inspectLocalImage(imageRef) {
|
||||
const inspect = runDocker(["image", "inspect", imageRef]);
|
||||
if (!inspect.ok) {
|
||||
return {
|
||||
ok: false,
|
||||
inspect,
|
||||
docs: []
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
inspect,
|
||||
docs: JSON.parse(inspect.stdout)
|
||||
};
|
||||
}
|
||||
|
||||
function dockerUnavailableResult(versionResult) {
|
||||
const reason = versionResult.timedOut
|
||||
? "Docker CLI timed out during version detection."
|
||||
: "Docker CLI is not available in this runner.";
|
||||
return blocked({
|
||||
blockers: [reason],
|
||||
nextSteps: [
|
||||
"Run this preflight in the D601 builder environment with Docker available.",
|
||||
`Preload an approved local Node 20 builder image and set ${envVarName}=<local-image> when using a non-node:20-* tag.`,
|
||||
"Do not use a UniDesk, Code Queue, backend-core, provider-gateway, or microservice-proxy runtime image as a substitute."
|
||||
],
|
||||
containerEngine: {
|
||||
command: dockerCommand,
|
||||
available: false,
|
||||
version: null,
|
||||
errorCode: versionResult.errorCode,
|
||||
stderr: versionResult.stderr
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function selectNode20Candidate(images) {
|
||||
const candidates = images
|
||||
.filter((image) => image.Repository === "node" && node20TagPattern.test(image.Tag))
|
||||
.map((image) => ({
|
||||
source: "local-docker-node:20-*",
|
||||
approval: approvalForBaseRef(candidateTag(image)),
|
||||
localTag: candidateTag(image),
|
||||
imageId: image.ID ?? null,
|
||||
size: image.Size ?? null,
|
||||
createdSince: image.CreatedSince ?? null
|
||||
}))
|
||||
.sort((left, right) => left.localTag.localeCompare(right.localTag));
|
||||
|
||||
return {
|
||||
candidates,
|
||||
selected: candidates[0] ?? null
|
||||
};
|
||||
}
|
||||
|
||||
function explicitImageBlockers(requestedImage, localTag) {
|
||||
const approval = approvalForBaseRef(localTag);
|
||||
const requestedApproval = approvalForBaseRef(requestedImage);
|
||||
if (approval.approved || requestedApproval.approved) {
|
||||
return {
|
||||
approval: approval.approved ? approval : requestedApproval,
|
||||
blockers: []
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
approval,
|
||||
blockers: [approval.reason]
|
||||
};
|
||||
}
|
||||
|
||||
function readyFromExplicitImage({ requestedImage, inspectDoc, containerEngine }) {
|
||||
const localTag = imageRefFromInspect(requestedImage, inspectDoc);
|
||||
const localTagBlockers = forbiddenReasons(localTag);
|
||||
const evidenceBlockers = inspectEvidenceBlockers(inspectDoc);
|
||||
const localTagApproval = explicitImageBlockers(requestedImage, localTag);
|
||||
const blockers = [...localTagBlockers, ...evidenceBlockers, ...localTagApproval.blockers];
|
||||
if (blockers.length > 0) {
|
||||
return blocked({
|
||||
imageSource: `env:${envVarName}`,
|
||||
requestedImage,
|
||||
localTag,
|
||||
imageId: inspectDoc.Id ?? null,
|
||||
blockers,
|
||||
nextSteps: [
|
||||
`Set ${envVarName} to an approved local builder base image, not a runtime service image.`,
|
||||
"Allowed references are local node:20-* tags or HWLAB dev base tags such as hwlab-dev-base:<tag>.",
|
||||
"Do not continue #35 artifact publish with this image."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
...ready({
|
||||
imageSource: `env:${envVarName}`,
|
||||
approval: localTagApproval.approval,
|
||||
requestedImage,
|
||||
localTag,
|
||||
inspectDoc,
|
||||
candidates: [
|
||||
{
|
||||
source: `env:${envVarName}`,
|
||||
approval: localTagApproval.approval,
|
||||
localTag,
|
||||
imageId: inspectDoc.Id ?? null
|
||||
}
|
||||
]
|
||||
}),
|
||||
containerEngine
|
||||
};
|
||||
}
|
||||
|
||||
export async function runDevBaseImagePreflight({ env = process.env } = {}) {
|
||||
const requestedImage = env[envVarName]?.trim() || null;
|
||||
const version = runDocker(["--version"]);
|
||||
if (!version.ok) {
|
||||
return dockerUnavailableResult(version);
|
||||
}
|
||||
|
||||
const containerEngine = {
|
||||
command: dockerCommand,
|
||||
available: true,
|
||||
version: version.stdout,
|
||||
errorCode: null,
|
||||
stderr: ""
|
||||
};
|
||||
|
||||
if (requestedImage) {
|
||||
const refBlockers = forbiddenReasons(requestedImage);
|
||||
const requestedApproval = approvalForBaseRef(requestedImage);
|
||||
if (refBlockers.length > 0 || !requestedApproval.approved) {
|
||||
return blocked({
|
||||
imageSource: `env:${envVarName}`,
|
||||
requestedImage,
|
||||
blockers: [
|
||||
...refBlockers,
|
||||
...(requestedApproval.approved ? [] : [requestedApproval.reason])
|
||||
],
|
||||
nextSteps: [
|
||||
`Set ${envVarName} to an approved local builder base image, not a runtime service image.`,
|
||||
"Allowed references are local node:20-* tags or HWLAB dev base tags such as hwlab-dev-base:<tag>.",
|
||||
"Do not continue #35 artifact publish with this image."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
const inspected = inspectLocalImage(requestedImage);
|
||||
if (!inspected.ok || inspected.docs.length === 0) {
|
||||
return blocked({
|
||||
imageSource: `env:${envVarName}`,
|
||||
requestedImage,
|
||||
blockers: [`${envVarName} is set to ${requestedImage}, but that image is not present in the local Docker image cache.`],
|
||||
nextSteps: [
|
||||
"Preload or build the approved DEV builder base image locally before artifact publish.",
|
||||
`Keep ${envVarName} pointed at the exact local tag once the image is available.`,
|
||||
"Do not pull from third-party hosting or substitute a UniDesk runtime image during this preflight."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
return readyFromExplicitImage({
|
||||
requestedImage,
|
||||
inspectDoc: inspected.docs[0],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
const imageList = runDocker(["image", "ls", "--format", "{{json .}}"]);
|
||||
if (!imageList.ok) {
|
||||
return blocked({
|
||||
blockers: ["Docker image list failed; local base-image cache could not be inspected."],
|
||||
nextSteps: [
|
||||
"Start or repair the local Docker daemon for the D601 builder environment.",
|
||||
`Then set ${envVarName}=<approved-local-image> or provide a local node:20-* image.`,
|
||||
"Do not claim #35 artifact publish readiness until this preflight returns ready."
|
||||
],
|
||||
containerEngine: {
|
||||
...containerEngine,
|
||||
stderr: imageList.stderr,
|
||||
errorCode: imageList.errorCode
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
const { candidates, selected } = selectNode20Candidate(splitJsonLines(imageList.stdout));
|
||||
if (!selected) {
|
||||
return blocked({
|
||||
blockers: [`${envVarName} is not set and no local node:20-* image was found in the Docker image cache.`],
|
||||
candidates,
|
||||
nextSteps: [
|
||||
`Set ${envVarName} to an approved local DEV builder base image, or preload a local node:20-* image such as node:20-bookworm-slim.`,
|
||||
"Rerun this preflight and require status=ready before #35 artifact publish.",
|
||||
"Do not use UniDesk runtime, Code Queue runner, backend-core, provider-gateway, or microservice-proxy images as substitutes."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
const inspected = inspectLocalImage(selected.localTag);
|
||||
if (!inspected.ok || inspected.docs.length === 0) {
|
||||
return blocked({
|
||||
imageSource: selected.source,
|
||||
requestedImage: null,
|
||||
localTag: selected.localTag,
|
||||
candidates,
|
||||
blockers: [`Selected local candidate ${selected.localTag} could not be inspected.`],
|
||||
nextSteps: [
|
||||
`Set ${envVarName} to a known-good approved local base image and rerun this preflight.`,
|
||||
"Do not continue #35 artifact publish until image inspect succeeds."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
const evidenceBlockers = inspectEvidenceBlockers(inspected.docs[0]);
|
||||
if (evidenceBlockers.length > 0) {
|
||||
return blocked({
|
||||
imageSource: selected.source,
|
||||
requestedImage: null,
|
||||
localTag: selected.localTag,
|
||||
candidates,
|
||||
imageId: inspected.docs[0].Id ?? null,
|
||||
blockers: evidenceBlockers,
|
||||
nextSteps: [
|
||||
`Replace ${selected.localTag} with a clean approved Node 20 builder base image.`,
|
||||
"Do not continue #35 artifact publish with an image whose inspect metadata points at a forbidden runtime substitute."
|
||||
],
|
||||
containerEngine
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
...ready({
|
||||
imageSource: selected.source,
|
||||
approval: selected.approval,
|
||||
requestedImage: null,
|
||||
localTag: selected.localTag,
|
||||
inspectDoc: inspected.docs[0],
|
||||
candidates
|
||||
}),
|
||||
containerEngine
|
||||
};
|
||||
}
|
||||
|
||||
export function unexpectedPreflightErrorResult(error) {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return blocked({
|
||||
blockers: [`Unexpected preflight error: ${message}`],
|
||||
nextSteps: [
|
||||
"Treat this as a blocker and inspect the preflight command output.",
|
||||
"Do not continue #35 artifact publish until the preflight returns status=ready."
|
||||
]
|
||||
});
|
||||
}
|
||||
|
||||
export function formatPreflightResult(result) {
|
||||
return JSON.stringify(result, null, 2);
|
||||
}
|
||||
|
||||
export function exitCodeForPreflight(result) {
|
||||
return result.publishUsable ? 0 : 2;
|
||||
}
|
||||
Reference in New Issue
Block a user