Skip to content

Code-first video & image, rendered natively on WebGPU.

7.2 KB
Raw Blame
import { spawn } from "node:child_process";
import { type ErrorCode, type JobPhase, RenderError } from "../errors.js";
import { redact } from "../redact.js";

export interface ExecOptions {
	cwd?: string;
	env?: NodeJS.ProcessEnv;
	timeoutMs?: number;
	signal?: AbortSignal;
	input?: string;
	/** Cap on captured stdout, to avoid buffering huge listings. */
	maxStdoutBytes?: number;
}

export interface ExecResult {
	stdout: string;
	stderr: string;
	code: number;
}

export class CommandError extends Error {
	constructor(
		readonly command: string,
		readonly result: ExecResult & { timedOut: boolean; aborted: boolean },
	) {
		super(
			`${command} ${result.timedOut ? "timed out" : `exited with ${result.code}`}: ${tail(result.stderr || result.stdout)}`,
		);
		this.name = "CommandError";
	}
}

/**
 * Spawns a command without a shell. Kills it (whole process group) on
 * timeout or abort. Rejects with CommandError on a non-zero exit.
 */
export function exec(
	file: string,
	args: readonly string[],
	options: ExecOptions = {},
): Promise<ExecResult> {
	return new Promise((resolve, reject) => {
		if (options.signal?.aborted) {
			reject(options.signal.reason);
			return;
		}
		const child = spawn(file, args, {
			cwd: options.cwd,
			env: options.env ?? process.env,
			// No stdin unless we have input: a child that exits without reading
			// it would otherwise raise EPIPE on our side.
			stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
			detached: process.platform !== "win32",
		});
		const max = options.maxStdoutBytes ?? 64 * 1024 * 1024;
		let stdout = "";
		let stderr = "";
		let timedOut = false;
		let aborted = false;

		child.stdout?.setEncoding("utf8").on("data", (d: string) => {
			if (stdout.length < max) stdout += d;
		});
		child.stderr?.setEncoding("utf8").on("data", (d: string) => {
			stderr = (stderr + d).slice(-64 * 1024);
		});

		const kill = () => {
			try {
				if (child.pid && process.platform !== "win32")
					process.kill(-child.pid, "SIGKILL");
				else child.kill("SIGKILL");
			} catch {
				// already gone
			}
		};
		const timer = options.timeoutMs
			? setTimeout(() => {
					timedOut = true;
					kill();
				}, options.timeoutMs)
			: undefined;
		const onAbort = () => {
			aborted = true;
			kill();
		};
		options.signal?.addEventListener("abort", onAbort, { once: true });

		child.on("error", (err) => {
			clearTimeout(timer);
			options.signal?.removeEventListener("abort", onAbort);
			reject(err);
		});
		child.on("close", (code) => {
			clearTimeout(timer);
			options.signal?.removeEventListener("abort", onAbort);
			if (aborted) {
				reject(options.signal?.reason);
				return;
			}
			const result = { stdout, stderr, code: code ?? -1 };
			if (code === 0 && !timedOut) resolve(result);
			else
				reject(
					new CommandError(`${file} ${args[0] ?? ""}`.trim(), {
						...result,
						timedOut,
						aborted,
					}),
				);
		});

		if (child.stdin) {
			child.stdin.on("error", () => {
				// EPIPE: the child exited before reading all input; its exit code says why.
			});
			child.stdin.end(options.input);
		}
	});
}

function tail(text: string, lines = 12): string {
	return redact(text.trim().split("\n").slice(-lines).join("\n"));
}

interface Rule {
	test: RegExp;
	code: ErrorCode;
	hint?: string;
}

/** Git and git-lfs messages → stable codes. Host-specific rules come first. */
const COMMON_RULES: Rule[] = [
	{ test: /No space left on device|ENOSPC/i, code: "DISK_FULL" },
	{
		test: /SSL certificate problem|unable to get local issuer certificate|certificate verify failed/i,
		code: "GIT_TLS_FAILED",
		hint: "For a self-signed server, set FF_GIT_CA_BUNDLE to its CA certificate (PEM).",
	},
	{
		test: /Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED/i,
		code: "GIT_AUTH_FAILED",
		hint: "Add the server's key to GIT_SSH_KNOWN_HOSTS (or set FF_SSH_ACCEPT_NEW=true).",
	},
	{
		test: /SAML|single sign-on|SSO/i,
		code: "GIT_AUTH_FAILED",
		hint: "Authorize the token for the organization's SSO.",
	},
	{
		test: /Authentication failed|could not read (Username|Password)|terminal prompts disabled|Permission denied \(publickey|HTTP Basic: Access denied|invalid credentials|\b401\b|Invalid username or (password|token)/i,
		code: "GIT_AUTH_FAILED",
		hint: "Check GIT_TOKEN / FF_GIT_CREDENTIALS (or GIT_SSH_KEY) and that it can read this repo.",
	},
	{
		test: /Repository not found|repository '.*' not found|does not appear to be a git repository|Project not found|The project you were looking for could not be found|\b404\b/i,
		code: "REPO_NOT_FOUND",
		hint: "Private repos also report 'not found' when the token lacks access.",
	},
	{
		test: /Could not resolve host|Connection (timed out|refused|reset)|Operation timed out|early EOF|RPC failed|unexpected disconnect|\b50[234]\b|SSL_ERROR_SYSCALL|TLS connection was non-properly terminated|Failed to connect/i,
		code: "GIT_NETWORK",
	},
];

const LFS_RULES: Rule[] = [
	{ test: /No space left on device|ENOSPC/i, code: "DISK_FULL" },
	{
		test: /over its data quota|exceeded its LFS (budget|bandwidth)|bandwidth limit|storage limit|LFS objects are not available|repository storage limit|quota/i,
		code: "LFS_QUOTA_EXCEEDED",
		hint: "The host's LFS quota is used up; buy more bandwidth/storage or move LFS to another server (.lfsconfig).",
	},
	{
		test: /LFS (is )?(not enabled|disabled)|LFS support is disabled|Git LFS is disabled/i,
		code: "LFS_UNAVAILABLE",
	},
	{
		test: /Object does not exist on the server|\[404\] Object|object .* not found|missing object/i,
		code: "LFS_OBJECT_MISSING",
		hint: "A pointer was committed without pushing its object; run `git lfs push --all` from a machine that has it.",
	},
	{
		test: /Authentication failed|\b401\b|\b403\b|credentials|Permission denied/i,
		code: "LFS_AUTH_FAILED",
	},
	{
		test: /Could not resolve host|timed out|Connection (refused|reset)|\b50[234]\b|EOF/i,
		code: "GIT_NETWORK",
	},
];

/**
 * Maps a failed git / git-lfs command to a RenderError. `extraRules` are host
 * specific and checked first.
 */
export function classifyGitError(
	err: unknown,
	phase: JobPhase,
	options: {
		lfs?: boolean;
		extraRules?: readonly Rule[];
		fallback?: ErrorCode;
	} = {},
): RenderError {
	if (err instanceof RenderError) return err;
	if (!(err instanceof CommandError)) {
		const message = err instanceof Error ? err.message : String(err);
		if (/ENOENT/.test(message)) {
			return new RenderError(
				"TOOL_MISSING",
				`A required tool is missing: ${message}`,
				{ phase },
			);
		}
		return new RenderError(options.fallback ?? "INTERNAL", redact(message), {
			phase,
			cause: err,
		});
	}
	if (err.result.timedOut) {
		return new RenderError("GIT_NETWORK", `${err.command} timed out.`, {
			phase,
			hint: "Raise FF_TIMEOUT_GIT_SEC / FF_TIMEOUT_LFS_SEC for very large repos.",
		});
	}
	const output = `${err.result.stderr}\n${err.result.stdout}`;
	const rules = [
		...(options.extraRules ?? []),
		...(options.lfs ? LFS_RULES : COMMON_RULES),
	];
	for (const rule of rules) {
		if (rule.test.test(output)) {
			return new RenderError(rule.code, err.message, {
				phase,
				hint: rule.hint,
				cause: err,
			});
		}
	}
	return new RenderError(options.fallback ?? "INTERNAL", err.message, {
		phase,
		cause: err,
	});
}

export type { Rule as ErrorRule };