fix(native): share command supervision and retain failure output

This commit is contained in:
morluto
2026-10-09 05:15:23 +08:00
parent 4a45c14742
commit f2e9c491ea
8 changed files with 604 additions and 98 deletions
+170 -78
View File
@@ -1,9 +1,18 @@
import { createHash, randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
import { realpath } from "node:fs/promises";
import { spawn } from "node:child_process";
import { err, ok, type Result } from "../domain/result.js";
import {
OwnedCommandFailure,
runOwnedCommand,
} from "../process/OwnedCommand.js";
import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js";
/** Maximum wall-clock duration for one native command. */
export const NATIVE_COMMAND_TIMEOUT_MS = 60_000;
/** Retain complete command output up to a bounded aggregate size. */
export const NATIVE_COMMAND_OUTPUT_BUDGET_BYTES = 64 * 1024 * 1024;
export interface NativeCommandCapture {
readonly tool: string;
@@ -20,17 +29,38 @@ export interface NativeCommandCapture {
readonly signal: string | null;
}
/** Native command failure with retained partial output and cleanup status. */
export class NativeCommandFailure extends Error {
constructor(
readonly tool: string,
readonly reason: "unavailable" | "cancelled" | "nonzero-exit" | "io",
readonly reason:
| "unavailable"
| "cancelled"
| "timeout"
| "output-limit"
| "nonzero-exit"
| "io",
readonly exitCode: number | null = null,
options?: ErrorOptions,
readonly capture: NativeCommandFailureCapture | null = null,
readonly cleanupFailure: string | null = null,
readonly cleanupResources: readonly string[] = [],
) {
super(`Native command ${tool} failed: ${reason}`, options);
}
}
/** Partial output and lifecycle details retained when a native command fails. */
export interface NativeCommandFailureCapture {
readonly stdout: string;
readonly stderr: string;
readonly stdoutBytes: number;
readonly stderrBytes: number;
readonly exitCode: number | null;
readonly signal: string | null;
readonly truncated: boolean;
}
/** Cancellation and exit handling for one allowlisted native command. */
export interface NativeCommandOptions {
readonly signal?: AbortSignal;
@@ -136,20 +166,66 @@ export const resolveXcrunTool = async (
signal === undefined ? {} : { signal },
);
if (!found.ok) {
if (found.error.reason === "cancelled")
return err(new NativeCommandFailure(tool, "cancelled"));
return err(new NativeCommandFailure(tool, "unavailable"));
return err(
new NativeCommandFailure(
tool,
found.error.reason === "nonzero-exit" ||
found.error.reason === "unavailable"
? "unavailable"
: found.error.reason,
found.error.exitCode,
{ cause: found.error },
found.error.capture,
found.error.cleanupFailure,
found.error.cleanupResources,
),
);
}
if (found.value.exitCode !== 0)
return err(new NativeCommandFailure(tool, "unavailable"));
return err(
new NativeCommandFailure(
tool,
"unavailable",
found.value.exitCode,
undefined,
failureCapture(found.value, false),
),
);
const candidate = found.value.stdout.trim();
if (!candidate.startsWith("/"))
return err(new NativeCommandFailure(tool, "unavailable"));
return err(
new NativeCommandFailure(
tool,
"unavailable",
found.value.exitCode,
undefined,
failureCapture(found.value, false),
),
);
try {
const path = await realpath(candidate);
return ok({ path, sha256: await hashFile(path) });
return ok({ path, sha256: await hashFile(path, signal) });
} catch (cause: unknown) {
return err(new NativeCommandFailure(tool, "io", null, { cause }));
const capture = failureCapture(found.value, false);
if (signal?.aborted === true)
return err(
new NativeCommandFailure(
tool,
"cancelled",
capture.exitCode,
{ cause },
capture,
),
);
return err(
new NativeCommandFailure(
tool,
"io",
capture.exitCode,
{ cause },
capture,
),
);
}
};
@@ -163,7 +239,20 @@ type ProcessCapture = Omit<
| "arguments"
>;
const captureProcess = (
const failureCapture = (
capture: ProcessCapture,
truncated: boolean,
): NativeCommandFailureCapture => ({
stdout: capture.stdout,
stderr: capture.stderr,
stdoutBytes: capture.stdoutBytes,
stderrBytes: capture.stderrBytes,
exitCode: capture.exitCode,
signal: capture.signal,
truncated,
});
const captureProcess = async (
executable: string,
arguments_: readonly string[],
tool: string,
@@ -171,80 +260,83 @@ const captureProcess = (
readonly signal?: AbortSignal;
readonly acceptNonZero?: boolean;
},
): Promise<Result<ProcessCapture, NativeCommandFailure>> =>
new Promise((resolve) => {
if (options.signal?.aborted === true) {
resolve(err(new NativeCommandFailure(tool, "cancelled")));
return;
}
const runToken = randomUUID();
const child = spawn(executable, [...arguments_], {
shell: false,
stdio: ["ignore", "pipe", "pipe"],
env: {
PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
LC_ALL: "C",
LANG: "C",
REA_NATIVE_RUN_TOKEN: runToken,
): Promise<Result<ProcessCapture, NativeCommandFailure>> => {
const runId = `rea-native-command-${randomUUID()}`;
try {
const snapshot = await runOwnedCommand(
{
command: executable,
arguments: [...arguments_],
runId,
env: {
PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
LC_ALL: "C",
LANG: "C",
},
hostEnvironment: {},
...(options.signal === undefined ? {} : { signal: options.signal }),
},
{
timeoutMs: NATIVE_COMMAND_TIMEOUT_MS,
diagnosticBytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES,
acceptNonZeroExit: options.acceptNonZero === true,
},
});
const stdout: Buffer[] = [];
const stderr: Buffer[] = [];
let stdoutBytes = 0;
let stderrBytes = 0;
let settled = false;
let reason: NativeCommandFailure["reason"] | undefined;
const finish = (
result: Result<ProcessCapture, NativeCommandFailure>,
): void => {
if (settled) return;
settled = true;
options.signal?.removeEventListener("abort", onAbort);
resolve(result);
};
const stop = (failure: NativeCommandFailure["reason"]): void => {
reason ??= failure;
child.kill("SIGKILL");
};
const onAbort = (): void => stop("cancelled");
options.signal?.addEventListener("abort", onAbort, { once: true });
child.stdout.on("data", (chunk: Buffer) => {
stdoutBytes += chunk.length;
stdout.push(chunk);
});
child.stderr.on("data", (chunk: Buffer) => {
stderrBytes += chunk.length;
stderr.push(chunk);
});
child.once("error", (cause: unknown) =>
finish(err(new NativeCommandFailure(tool, "io", null, { cause }))),
);
child.once("close", (code, signal) => {
if (reason !== undefined) {
finish(err(new NativeCommandFailure(tool, reason, code)));
return;
}
if (signal !== null || (code !== 0 && options.acceptNonZero !== true)) {
finish(err(new NativeCommandFailure(tool, "nonzero-exit", code)));
return;
}
finish(
ok({
stdout: Buffer.concat(stdout).toString("utf8"),
stderr: Buffer.concat(stderr).toString("utf8"),
stdoutBytes,
stderrBytes,
exitCode: code,
signal,
}),
return ok(processCaptureFromSnapshot(snapshot));
} catch (cause: unknown) {
if (cause instanceof OwnedCommandFailure) {
const capture =
cause.snapshot === null
? null
: failureCapture(
processCaptureFromSnapshot(cause.snapshot),
cause.snapshot.diagnosticTruncated === true,
);
return err(
new NativeCommandFailure(
tool,
cause.reason === "process"
? processFailureReason(capture)
: cause.reason,
capture?.exitCode ?? null,
{ cause },
capture,
cause.cleanupFailure,
cause.resources,
),
);
});
});
}
return err(new NativeCommandFailure(tool, "io", null, { cause }));
}
};
const hashFile = (path: string): Promise<string> =>
const processFailureReason = (
capture: NativeCommandFailureCapture | null,
): "io" | "nonzero-exit" =>
capture !== null &&
(capture.signal !== null ||
(capture.exitCode !== null && capture.exitCode !== 0))
? "nonzero-exit"
: "io";
const processCaptureFromSnapshot = (
snapshot: ProviderProcessSnapshot,
): ProcessCapture => ({
stdout: snapshot.stdout.text,
stderr: snapshot.stderr.text,
stdoutBytes: snapshot.stdout.bytes,
stderrBytes: snapshot.stderr.bytes,
exitCode: snapshot.exitCode ?? null,
signal: snapshot.signal ?? null,
});
const hashFile = (path: string, signal?: AbortSignal): Promise<string> =>
new Promise((resolve, reject) => {
const hash = createHash("sha256");
const stream = createReadStream(path);
const stream = createReadStream(
path,
signal === undefined ? undefined : { signal },
);
stream.on("data", (chunk) => hash.update(chunk));
stream.once("error", reject);
stream.once("end", () => resolve(hash.digest("hex")));
+70 -3
View File
@@ -31,6 +31,8 @@ import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisOutputError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "../domain/analysisErrorCore.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -49,6 +51,8 @@ import {
} from "../domain/native/nativeInspection.js";
import { err, ok, type Result } from "../domain/result.js";
import {
NATIVE_COMMAND_TIMEOUT_MS,
NATIVE_COMMAND_OUTPUT_BUDGET_BYTES,
NativeCommandFailure,
XcrunCommandRunner,
type NativeCommandCapture,
@@ -641,15 +645,64 @@ const translateCommandFailure = (
operation: NativeToolName,
failure: NativeCommandFailure,
): AnalysisError => {
const capturedOutput =
failure.capture === null
? undefined
: {
stdout: failure.capture.stdout,
stderr: failure.capture.stderr,
truncated: failure.capture.truncated,
stdout_bytes: failure.capture.stdoutBytes,
stderr_bytes: failure.capture.stderrBytes,
exit_code: failure.capture.exitCode,
signal: failure.capture.signal,
};
const cleanup =
failure.cleanupFailure === null
? undefined
: {
reason: failure.cleanupFailure,
resources: [...failure.cleanupResources],
};
const errorOptions = {
...(capturedOutput === undefined ? {} : { capturedOutput }),
...(cleanup === undefined ? {} : { cleanup }),
};
if (failure.reason === "unavailable")
return new AnalysisCapabilityUnavailableError(
IDENTITY.id,
operation,
`${failure.tool} is unavailable through xcrun.`,
errorOptions,
);
if (failure.reason === "cancelled")
return new AnalysisCancelledError(operation);
return new ProviderAdapterError(IDENTITY.id, operation, { cause: failure });
return new AnalysisCancelledError(operation, errorOptions);
if (failure.reason === "timeout")
return new AnalysisTimeoutError(
operation,
NATIVE_COMMAND_TIMEOUT_MS,
errorOptions,
);
if (failure.reason === "output-limit")
return new AnalysisResourceConstraintError(
operation,
"memory",
`Native command output exceeded ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)} bytes; complete output is required for analysis.`,
{ max_output_bytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES },
errorOptions,
);
return new ProviderAdapterError(IDENTITY.id, operation, {
cause: failure,
...errorOptions,
diagnostics: {
tool: failure.tool,
reason: failure.reason,
exit_code: failure.capture?.exitCode ?? failure.exitCode,
signal: failure.capture?.signal ?? null,
stdout_bytes: failure.capture?.stdoutBytes ?? 0,
stderr_bytes: failure.capture?.stderrBytes ?? 0,
},
});
};
const translateCodeSignExitFailure = (
@@ -657,7 +710,21 @@ const translateCodeSignExitFailure = (
): AnalysisError =>
translateCommandFailure(
"inspect_signature",
new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode),
new NativeCommandFailure(
"codesign",
"nonzero-exit",
capture.exitCode,
undefined,
{
stdout: capture.stdout,
stderr: capture.stderr,
stdoutBytes: capture.stdoutBytes,
stderrBytes: capture.stderrBytes,
exitCode: capture.exitCode,
signal: capture.signal,
truncated: false,
},
),
);
const commandOutput = (capture: NativeCommandCapture): string =>