fix(process): classify every launcher failure once by errno in the shared launch owner (#11615)

* fix(process): classify every launcher failure once by errno in the shared launch owner

* fix(process): keep the launch owner's syscall, cause and facts in RE and pwntools unavailable reports
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 08:24:39 +08:00
1 parent 0884836abf
commit dbb4bc29f0
29 files changed
+712 -289

No files matched your search

+8 -3
View File
@@ -1508,7 +1508,7 @@ it.each(["first-selected.apk", "second-selected.apk"])(
},
);
it("reports launcher disappearance after version admission as a provider failure", async () => {
it("reports launcher disappearance after version admission as apktool unavailable", async () => {
const { command, root } = await writeApktoolStub(
() =>
`if [ "$1" = "--version" ]; then rm -- "$0"; ${VERSION_BLOCK}; exit 0; fi`,
@@ -1521,9 +1521,14 @@ it("reports launcher disappearance after version admission as a provider failure
input: { path: apk.path, include_strings: true },
});
if (result.ok) throw new Error("Expected missing launcher");
// The shared launch owner classifies the real ENOENT spawn failure.
expect(result.error).toMatchObject({
_tag: "ProviderAdapterError",
diagnostics: { target_path: apk.path, selected_command: command },
_tag: "AnalysisCapabilityUnavailableError",
providerId: "apktool",
diagnostics: {
boundary: "provider-launch",
system_code: "ENOENT",
},
});
expect(projectAnalysisError(result.error).code).not.toBe(
"unsupported_target",
+5 -2
View File
@@ -228,12 +228,14 @@ const apktoolCommandFailure = (
target_path: targetPath,
},
});
if (!(failure instanceof OwnedCommandFailure))
const outcome = providerOutcomeOf(failure);
if (outcome === undefined)
return commandFailure({
cause: failure,
...(capturedOutput === undefined ? {} : { capturedOutput }),
});
return classifyProviderOutcome(providerOutcomeOf(failure), {
return classifyProviderOutcome(outcome, {
providerId: APKTOOL_PROVIDER_IDENTITY.id,
operation,
capturedOutput: capturedProviderOutput,
// Ownership preparation can retain output before any process exists.
@@ -261,6 +263,7 @@ const apktoolCommandFailure = (
// Only a fully collected ordinary nonzero decode exit carries that meaning.
if (
exit.kind !== "exited" ||
!(failure instanceof OwnedCommandFailure) ||
failure.processError !== undefined ||
failure.preparationFailure !== undefined ||
exit.exitCode === null ||
@@ -40,6 +40,7 @@ import {
import {
AnalysisError,
type AnalysisCleanupObservation,
type AnalysisErrorOptions,
} from "../../domain/analysisErrorBase.js";
import { AnalysisCleanupRelease } from "../../domain/analysisCleanupRelease.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
@@ -62,10 +63,12 @@ import type {
ReverseEngineeringCommandUnavailable,
ReverseEngineeringProviderCommand,
} from "./ReverseEngineeringCommandPort.js";
import { execFileOutputFailure } from "../../process/ExecFileOutput.js";
import {
execFileOutputFailure,
HOST_SPAWN_CAPACITY_CODES,
} from "../../process/ExecFileOutput.js";
describeLaunchFailure,
launcherFailureOf,
} from "../../process/launchFailure.js";
import { classifyLaunchFailure } from "../../process/classifyProviderOutcome.js";
import {
OwnedCommandFailure,
runOwnedCommand,
@@ -775,43 +778,29 @@ export class ReverseEngineeringService {
: undefined);
if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER")
outputLimitReached = true;
if (earlyFailure === undefined && code === "E2BIG")
earlyFailure = new AnalysisResourceConstraintError(
operation,
"transport",
"The host rejected the provider command because its argument list exceeds the process launch limit.",
{
argument_bytes: args.reduce(
(bytes, argument, index) =>
bytes + Buffer.byteLength(argument) + (index === 0 ? 0 : 1),
0,
),
},
{ cause, ...ownedCleanupOptions(cause) },
);
// Host capacity and an oversized argument list are classified by the
// shared launch owner; a refusal keeps this provider's repair below.
const launch = launcherFailureOf(
cause instanceof LinuxOwnedProcessPrerequisiteError
? cause.cause
: cause,
);
if (
earlyFailure === undefined &&
typeof code === "string" &&
HOST_SPAWN_CAPACITY_CODES.has(code)
) {
earlyFailure = new AnalysisResourceConstraintError(
(launch?.kind === "host-exhausted" || launch?.kind === "argument-list")
)
earlyFailure = classifyLaunchFailure(launch, {
providerId: profile.identity.id,
operation,
"capacity",
`The host ran out of process, memory or file-descriptor capacity (${code}) to start ${provider}.`,
{ spawn_error: code, command },
{
cause,
retryable: true,
remediationAction: `The host ran out of process, memory or file-descriptor capacity (${code}). Close unused processes or files, or raise the process or open-file limit of the REA process, then retry; ${setting} does not need to change.`,
diagnostics: {
boundary: "host-capacity",
command,
system_code: code,
},
...ownedCleanupOptions(cause),
},
);
}
command,
selection: setting,
argumentBytes: args.reduce(
(bytes, argument, index) =>
bytes + Buffer.byteLength(argument) + (index === 0 ? 0 : 1),
0,
),
details: { cause, ...ownedCleanupOptions(cause) },
});
if (
earlyFailure === undefined &&
cause instanceof LinuxOwnedProcessPrerequisiteError
@@ -967,22 +956,45 @@ export class ReverseEngineeringService {
});
else {
const { provider, remediationAction } = profile.repair;
earlyFailure = new AnalysisCapabilityUnavailableError(
profile.identity.id,
operation,
`Unable to run configured command (${String(code ?? "unknown error")})`,
{
cause,
userMessage: `Could not launch the selected ${provider} executable ${JSON.stringify(command)} (${String(code ?? "unknown error")}).`,
remediationAction,
diagnostics: {
boundary: "provider-launch",
command,
system_code: code ?? null,
// This provider's repair names the configured executable; the
// shared launch owner supplies the errno and syscall facts.
const unavailable = (
description: string,
details: AnalysisErrorOptions,
): AnalysisError =>
new AnalysisCapabilityUnavailableError(
profile.identity.id,
operation,
`Unable to run configured command (${description})`,
{
...details,
userMessage: `Could not launch the selected ${provider} executable ${JSON.stringify(command)} (${description}).`,
remediationAction,
},
...ownedCleanupOptions(cause),
},
);
);
const details: AnalysisErrorOptions = {
cause,
...ownedCleanupOptions(cause),
};
earlyFailure =
launch === undefined
? unavailable(String(code ?? "unknown error"), {
...details,
diagnostics: {
boundary: "provider-launch",
command,
system_code: code ?? null,
},
})
: classifyLaunchFailure(launch, {
providerId: profile.identity.id,
operation,
command,
selection: setting,
details,
unavailable: (failure, launchDetails) =>
unavailable(describeLaunchFailure(failure), launchDetails),
});
}
}
if (earlyFailure === undefined && capture !== undefined) {
@@ -1408,13 +1420,11 @@ const runOwnedCommandOutput =
? "ETIMEDOUT"
: cause.reason === "output-limit"
? "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
: launchErrorCode === "E2BIG"
? "E2BIG"
: snapshot === null
? typeof launchErrorCode === "string"
? launchErrorCode
: "ERR_PROVIDER_LAUNCH"
: (snapshot.exitCode ?? null);
: snapshot === null
? typeof launchErrorCode === "string"
? launchErrorCode
: "ERR_PROVIDER_LAUNCH"
: (snapshot.exitCode ?? null);
throw new OwnedOutputFailure({
stdout: snapshot?.stdout.text ?? "",
stderr: snapshot?.stderr.text ?? "",
+11 -10
View File
@@ -11,6 +11,7 @@ import {
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import type { ProviderOutcomeContext } from "../process/classifyProviderOutcome.js";
import { describeLaunchFailure } from "../process/launchFailure.js";
import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js";
import {
DEFAULT_EVM_TIMEOUT_MS,
@@ -139,7 +140,7 @@ export const evmFailureDialect = (
/** The EVMole worker's dialect: its prlimit launcher and its reserved EFBIG exit. */
const evmCommandContext = (
context: ResolvedEvmFailureContext,
): ProviderOutcomeContext => {
): Omit<ProviderOutcomeContext, "providerId"> => {
const { workerLimits, limiter, fileFailure, timeoutMs, producerLimits } =
context;
return {
@@ -185,16 +186,16 @@ const evmCommandContext = (
remediationAction: `The EVMole worker's ${String(EVM_WORKER_HEAP_MIB)} MiB heap is fixed in this release; producer_limits and timeout_ms do not raise it. Select a smaller bytecode carrier; repeating the unchanged request is expected to fail the same way.`,
},
}),
launchUnavailable: (failure, details) => {
const reason = `Configured util-linux prlimit could not launch (${describeLaunchFailure(failure)}): ${limiter}. Check its executable/interpreter and host execute access.`;
return new AnalysisCapabilityUnavailableError(
EVMOLE_PROVIDER_IDENTITY.id,
OPERATION,
reason,
{ ...details, userMessage: reason },
);
},
dialect: (outcome, details) => {
if (outcome.kind === "launch-refused") {
const reason = `Configured util-linux prlimit could not launch (${outcome.refusal.code}): ${limiter}. Check its executable/interpreter and host execute access.`;
return new AnalysisCapabilityUnavailableError(
EVMOLE_PROVIDER_IDENTITY.id,
OPERATION,
reason,
{ ...details, userMessage: reason },
);
}
// The reserved exit means EFBIG only when the worker's marker says so.
if (
outcome.kind === "exited" &&
@@ -340,6 +340,31 @@ it.each(["ENOEXEC", "EACCES"])(
},
);
it("keeps the launch owner's cause and facts on an unavailable selected Python", () => {
const launch = Object.assign(new Error("spawn /python EIO"), {
code: "EIO",
syscall: "spawn /python",
path: "/python",
});
const failure = pwntoolsDecoderFailure(
launch,
"decoder",
"/selected",
"/python",
);
expect(failure.cause).toBe(launch);
expect(failure.diagnostics).toMatchObject({
boundary: "provider-launch",
system_code: "EIO",
syscall: "spawn /python",
command: "/python",
});
expect(projectAnalysisError(failure)).toMatchObject({
code: "provider_unavailable",
message: expect.stringContaining("EIO from spawn /python"),
});
});
it("does not read an errno from another syscall as a launch refusal", () => {
const unrelated = Object.assign(new Error("open EACCES"), {
code: "EACCES",
+21 -10
View File
@@ -6,7 +6,10 @@ import {
resolvePwntoolsLimits,
type PwntoolsProducerLimits,
} from "../../domain/native/pwntoolsResourceLimits.js";
import type { AnalysisCapturedOutput } from "../../domain/analysisErrorBase.js";
import type {
AnalysisCapturedOutput,
AnalysisErrorOptions,
} from "../../domain/analysisErrorBase.js";
import type { AnalysisControlLimit } from "../../domain/analysisSettings.js";
import type { ProviderProcessSnapshot } from "../../process/ProviderProcess.js";
import {
@@ -16,6 +19,7 @@ import {
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
import type { ProviderOutcomeContext } from "../../process/classifyProviderOutcome.js";
import { describeLaunchFailure } from "../../process/launchFailure.js";
import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
import type { ProviderFailureDialect } from "../../providers/classifyProviderFailure.js";
import type { PwntoolsFailureEvidence } from "./PwntoolsResourceLimits.js";
@@ -209,7 +213,7 @@ export const pwntoolsFailureDialect = (
const pwntoolsCommandContext = (
state: PwntoolsPhase,
limits: PwntoolsProducerLimits,
): ProviderOutcomeContext => {
): Omit<ProviderOutcomeContext, "providerId"> => {
const { executablePath, failureEvidence, context } = state;
const limitReport = failureEvidence.limits;
const budgetRecovery = pwntoolsBudgetRecovery(limits);
@@ -299,15 +303,16 @@ const pwntoolsCommandContext = (
PWNTOOLS_LIMITS.cpu_seconds,
),
},
launchUnavailable: (failure, details) =>
pwntoolsUnavailable(
`Selected Python could not launch (${describeLaunchFailure(failure)}): ${executablePath}. Check the configured executable, its interpreter and host execute access.`,
executablePath,
failure.code,
undefined,
context,
{ cause: details.cause, diagnostics: details.diagnostics },
),
dialect: (outcome, details) => {
if (outcome.kind === "launch-refused")
return pwntoolsUnavailable(
`Selected Python could not launch (${outcome.refusal.code}): ${executablePath}. Check the configured executable, its interpreter and host execute access.`,
executablePath,
outcome.refusal.code,
undefined,
context,
);
// A reserved exit means a resource failure only when the bridge's
// marker names that resource.
const reservedExit =
@@ -405,9 +410,15 @@ export const pwntoolsUnavailable = (
systemCode?: string,
capturedOutput?: AnalysisCapturedOutput,
context: PwntoolsFailureContext = DEFAULT_CONTEXT,
/** The shared launch owner's cause and parsed facts, for a launch failure. */
launch?: Pick<AnalysisErrorOptions, "cause" | "diagnostics">,
): ProviderSelectionError =>
new ProviderSelectionError({
...(capturedOutput === undefined ? {} : { capturedOutput }),
...(launch?.cause === undefined ? {} : { cause: launch.cause }),
...(launch?.diagnostics === undefined
? {}
: { diagnostics: launch.diagnostics }),
userMessage: reason,
operation: context.operation,
reason: "provider_unavailable",
+34 -29
View File
@@ -41,6 +41,7 @@ import {
} from "../process/WindowsBatchCommand.js";
import { providerOutcomeOf } from "../process/ProviderOutcome.js";
import { classifyProviderOutcome } from "../process/classifyProviderOutcome.js";
import { describeLaunchFailure } from "../process/launchFailure.js";
import { pcapToolUnavailable } from "./PcapConfiguration.js";
import {
attributePcapLimitedExit,
@@ -294,6 +295,7 @@ export const runPcapCommand = async (options: {
throw pcapToolFailure(diagnostic, details);
}
throw classifyProviderOutcome(outcome, {
providerId: "pcap",
operation,
capturedOutput: captureDiagnostic,
details: cleanupDetails,
@@ -306,41 +308,44 @@ export const runPcapCommand = async (options: {
),
},
memoryLimitBytes: options.nativeBound?.memoryLimitBytes,
dialect: (failure, details) => {
if (
failure.kind === "launch-refused" &&
// Only a launcher naming the launched path identifies who refused.
failure.refusal.executable === launchedPath
) {
if (selectedLimiter !== undefined) {
const reason = `Selected capture limiter ${selectedLimiter} could not be launched (${failure.refusal.code}).`;
return new AnalysisCapabilityUnavailableError(
"pcap",
operation,
reason,
{
...details,
userMessage: `${reason} ${PCAP_LIMITER_REMEDIATION}`,
remediationAction: PCAP_LIMITER_REMEDIATION,
},
);
}
return pcapToolUnavailable(
operation,
failure.refusal.kind === "missing"
? `Selected tool ${command} was not found (${failure.refusal.code})`
: `Selected tool ${command} exists but could not be executed (${failure.refusal.code})`,
launchUnavailable: (failure, details) => {
// Only a launcher naming the launched path identifies who failed.
if (failure.executable !== launchedPath) {
if (!commandAttempted)
return preparationFailure(outcome.message, details);
return new AnalysisProtocolError(
`The packet command could not start; the failing stage is unknown: ${outcome.message}`,
details,
);
}
const code = describeLaunchFailure(failure);
if (selectedLimiter !== undefined) {
const reason = `Selected capture limiter ${selectedLimiter} could not be launched (${code}).`;
return new AnalysisCapabilityUnavailableError(
"pcap",
operation,
reason,
{
...details,
userMessage: `${reason} ${PCAP_LIMITER_REMEDIATION}`,
remediationAction: PCAP_LIMITER_REMEDIATION,
},
);
}
return pcapToolUnavailable(
operation,
failure.kind === "missing"
? `Selected tool ${command} was not found (${code})`
: failure.kind === "not_executable"
? `Selected tool ${command} exists but could not be executed (${code})`
: `Selected tool ${command} could not be launched (${code})`,
details,
);
},
dialect: (failure, details) => {
const diagnostic =
failure.output?.snapshot.stderr.text.trim() || failure.message;
if (!commandAttempted) return preparationFailure(diagnostic, details);
if (failure.kind === "launch-refused")
return new AnalysisProtocolError(
`The packet command could not start; the failing stage is unknown: ${diagnostic}`,
details,
);
if (selectedLimiter !== undefined) {
if (failure.kind !== "exited" || failure.output === undefined)
return new AnalysisProtocolError(
+1
View File
@@ -467,6 +467,7 @@ export class ArtifactAnalysisResources {
budgetParameter?: "producer_limits",
): ProviderOutcomeContext {
return {
providerId: this.providerId,
operation,
capturedOutput: capturedProviderOutput,
timeout: {
+4 -12
View File
@@ -1,5 +1,6 @@
import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js";
import { HOST_PLATFORM } from "../platform/HostPlatform.js";
import { launchExhaustedResource } from "./launchFailure.js";
import {
execFile,
spawn,
@@ -136,25 +137,16 @@ export const execFileOutputFailure = (
};
};
/** Spawn errnos reporting exhausted host capacity rather than an unusable command. */
export const HOST_SPAWN_CAPACITY_CODES: ReadonlySet<string> = new Set([
"EAGAIN",
"EMFILE",
"ENFILE",
"ENOMEM",
]);
/**
* Whether the command never started because the host lacked process, memory
* or file-descriptor capacity. The command itself may be usable; a retry after
* capacity is freed can succeed.
* or file-descriptor capacity (classified by `launchExhaustedResource`). The
* command itself may be usable; a retry after capacity is freed can succeed.
*/
export const spawnCapacityExhausted = (
failure: ExecFileOutputFailure | undefined,
): boolean =>
failure?.spawnFailed === true &&
typeof failure.code === "string" &&
HOST_SPAWN_CAPACITY_CODES.has(failure.code);
launchExhaustedResource(failure.code) !== undefined;
/** Project admitted command failure facts without reinterpreting failure policy. */
export const execFileFailureCapturedOutput = (
+2 -3
View File
@@ -38,9 +38,9 @@ import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
import {
execFileOutput,
execFileOutputFailure,
HOST_SPAWN_CAPACITY_CODES,
spawnCapacityExhausted,
} from "./ExecFileOutput.js";
import { launchExhaustedResource } from "./launchFailure.js";
import {
createDarwinProcessRunTokenReader,
DarwinProcessOwnershipInspectionError,
@@ -1557,8 +1557,7 @@ export const createSystemProcessOwnershipHost = (
spawnCapacityExhausted(failure) ||
(typeof cause === "object" &&
cause !== null &&
typeof Reflect.get(cause, "code") === "string" &&
HOST_SPAWN_CAPACITY_CODES.has(Reflect.get(cause, "code") as string))
launchExhaustedResource(Reflect.get(cause, "code")) !== undefined)
)
throw cause;
const rawCode =
+11 -11
View File
@@ -1,4 +1,4 @@
import { launcherRefusalOf, type LauncherRefusal } from "./launchFailure.js";
import { launcherFailureOf, type LauncherFailure } from "./launchFailure.js";
import { OwnedCommandFailure } from "./OwnedCommand.js";
import type { ProviderProcessSnapshot } from "./ProviderProcess.js";
import type { RuntimeExhaustion } from "./RuntimeExhaustion.js";
@@ -27,10 +27,10 @@ interface ProviderOutcomeFacts {
* `classifyProviderOutcome`.
*/
export type ProviderOutcome =
/** The operating system refused to start the selected executable. */
/** A launcher failed to start the executable; `failure` says why, by errno. */
| (ProviderOutcomeFacts & {
readonly kind: "launch-refused";
readonly refusal: LauncherRefusal;
readonly kind: "launch-failed";
readonly failure: LauncherFailure;
})
/** The caller cancelled; `reason` is the caller's opaque abort reason. */
| (ProviderOutcomeFacts & {
@@ -133,19 +133,19 @@ const ownedCommandOutcome = (failure: OwnedCommandFailure): ProviderOutcome => {
/**
* Read the outcome of an owned command from what `runOwnedCommand` threw.
* Undefined when the value is neither a supervised command failure nor a
* launch refusal.
* Undefined when the value is neither a supervised command failure nor an
* error a launcher raised.
*/
export function providerOutcomeOf(cause: OwnedCommandFailure): ProviderOutcome;
export function providerOutcomeOf(cause: unknown): ProviderOutcome | undefined;
export function providerOutcomeOf(cause: unknown): ProviderOutcome | undefined {
if (cause instanceof OwnedCommandFailure) return ownedCommandOutcome(cause);
// Only a launcher's errno is a launch refusal; one from reading a file is not.
const refusal = launcherRefusalOf(cause);
if (refusal === undefined || !(cause instanceof Error)) return undefined;
// Only a launcher's errno is a launch failure; one from reading a file is not.
const failure = launcherFailureOf(cause);
if (failure === undefined || !(cause instanceof Error)) return undefined;
return {
kind: "launch-refused",
refusal,
kind: "launch-failed",
failure,
cause,
message: cause.message,
output: undefined,
+146 -5
View File
@@ -4,6 +4,7 @@ import type {
AnalysisErrorOptions,
} from "../domain/analysisErrorBase.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
cancelledBy,
@@ -12,6 +13,11 @@ import {
} from "../domain/analysisErrorCore.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { AnalysisLimit } from "../domain/analysisSettings.js";
import {
describeLaunchFailure,
type LaunchExhaustedResource,
type LauncherFailure,
} from "./launchFailure.js";
import type { ProviderOutcome } from "./ProviderOutcome.js";
import type { ProviderProcessSnapshot } from "./ProviderProcess.js";
import {
@@ -35,13 +41,134 @@ const AREA_NAMES = {
/** Outcomes whose meaning depends on the provider's own dialect. */
export type ProviderDialectOutcome = Extract<
ProviderOutcome,
{ readonly kind: "launch-refused" | "exited" | "protocol" }
{ readonly kind: "exited" | "protocol" }
>;
/** A launch failure that leaves the provider unavailable for this call. */
export type LaunchUnavailableFailure = Extract<
LauncherFailure,
{ readonly kind: "missing" | "not_executable" | "failed" }
>;
const EXHAUSTED_RESOURCE_NAMES = {
processes: "process",
memory: "memory",
"file-descriptors": "file-descriptor",
} as const satisfies Record<LaunchExhaustedResource, string>;
/** What one launch failure report needs beyond the launcher's facts. */
export interface LaunchFailureContext {
readonly providerId: string;
readonly operation: string;
/** Options every classified error carries, such as the cause and cleanup. */
readonly details?: AnalysisErrorOptions;
/** The command the caller selected, when the launcher did not name it. */
readonly command?: string;
/** The setting that selected the command; a host constraint leaves it unchanged. */
readonly selection?: string;
/** Bytes of the refused argument list, when the caller measured them. */
readonly argumentBytes?: number;
/**
* The provider's report that it cannot be started, such as a message naming
* its configured executable. Without it the shared report names the
* executable and the errno.
*/
readonly unavailable?: (
failure: LaunchUnavailableFailure,
details: AnalysisErrorOptions,
) => AnalysisError;
}
/**
* The one mapping from a launcher's failure to a typed error. Host capacity
* (EAGAIN, ENOMEM, EMFILE, ENFILE) and an oversized argument list (E2BIG) are
* resource constraints of this call, not provider faults; every other errno
* leaves the provider unavailable, reported with its errno and syscall.
*/
export const classifyLaunchFailure = (
failure: LauncherFailure,
context: LaunchFailureContext,
): AnalysisError => {
const { operation } = context;
const command = failure.executable ?? context.command;
const subject = command ?? "the provider command";
const launchFacts: Readonly<Record<string, JsonValue>> = {
system_code: failure.code ?? null,
...(failure.syscall === undefined ? {} : { syscall: failure.syscall }),
...(command === undefined ? {} : { command }),
};
const details: AnalysisErrorOptions = {
...context.details,
diagnostics: {
...context.details?.diagnostics,
...launchFacts,
boundary:
failure.kind === "host-exhausted" ? "host-capacity" : "provider-launch",
},
};
const unchanged = `${context.selection ?? "the selected command"} does not need to change`;
switch (failure.kind) {
case "host-exhausted": {
const name = EXHAUSTED_RESOURCE_NAMES[failure.resource];
return new AnalysisResourceConstraintError(
operation,
"capacity",
`The host ran out of ${name} capacity (${failure.code}) to start ${subject}.`,
{
spawn_error: failure.code,
exhausted_resource: failure.resource,
...(command === undefined ? {} : { command }),
},
{
...details,
retryable: true,
remediationAction: `The host ran out of ${name} capacity (${failure.code}). Close unused processes or files, or raise the process or open-file limit of the REA process, then retry; ${unchanged}.`,
},
);
}
case "argument-list":
return new AnalysisResourceConstraintError(
operation,
"transport",
`The host rejected ${subject} because its argument list and environment exceed the process launch limit (${failure.code}).`,
{
spawn_error: failure.code,
...(context.argumentBytes === undefined
? {}
: { argument_bytes: context.argumentBytes }),
},
{
...details,
retryable: false,
remediationAction: `Select less input for one call, or pass large values through a file, then retry; ${unchanged}. An unchanged request fails the same way.`,
},
);
case "missing":
case "not_executable":
case "failed": {
if (context.unavailable !== undefined)
return context.unavailable(failure, details);
const reason =
failure.kind === "missing"
? `${subject} was not found (${describeLaunchFailure(failure)}).`
: failure.kind === "not_executable"
? `${subject} exists but could not be executed (${describeLaunchFailure(failure)}).`
: `${subject} could not be launched (${describeLaunchFailure(failure)}).`;
return new AnalysisCapabilityUnavailableError(
context.providerId,
operation,
reason,
{ ...details, userMessage: reason },
);
}
}
};
type ReportedLimits = Readonly<Record<string, JsonValue>> | null;
/** What one provider command needs to turn its outcome into a typed error. */
export interface ProviderOutcomeContext {
readonly providerId: string;
readonly operation: string;
/** The provider's redacted projection of retained output. */
readonly capturedOutput: (
@@ -85,7 +212,13 @@ export interface ProviderOutcomeContext {
readonly limits: ReportedLimits;
readonly recovery: ResourceConstraintRecovery;
};
/** Provider-specific meaning of a launch refusal, an exit, or a stream failure. */
/**
* The provider's report that its command cannot be started; see
* `LaunchFailureContext.unavailable`. Host constraints are not the
* provider's to interpret.
*/
readonly launchUnavailable?: LaunchFailureContext["unavailable"];
/** Provider-specific meaning of an exit or a stream failure. */
readonly dialect: (
outcome: ProviderDialectOutcome,
details: AnalysisErrorOptions,
@@ -94,8 +227,8 @@ export interface ProviderOutcomeContext {
/**
* The one mapping from an owned command's physical outcome to a typed error.
* Owner-observed facts are classified here; only the provider's dialect
* decides what an exit or a launch refusal means for that provider.
* Owner-observed facts, including launch failures, are classified here; only
* the provider's dialect decides what an exit or a stream failure means.
*/
export const classifyProviderOutcome = (
outcome: ProviderOutcome,
@@ -198,7 +331,15 @@ export const classifyProviderOutcome = (
},
);
}
case "launch-refused":
case "launch-failed":
return classifyLaunchFailure(outcome.failure, {
providerId: context.providerId,
operation,
details,
...(context.launchUnavailable === undefined
? {}
: { unavailable: context.launchUnavailable }),
});
case "exited":
case "protocol":
return context.dialect(outcome, details);
+99 -14
View File
@@ -3,7 +3,9 @@ import { expect, it } from "vitest";
import {
classifyLaunchFailure,
classifyLaunchFailureCode,
launcherRefusalOf,
classifyLaunchErrno,
describeLaunchFailure,
launcherFailureOf,
} from "./launchFailure.js";
it.each([
@@ -29,11 +31,39 @@ it.each([["EAGAIN"], ["EMFILE"], ["ETIMEDOUT"], [1], [null], ["toString"]])(
},
);
it.each([
["EAGAIN", { kind: "host-exhausted", code: "EAGAIN", resource: "processes" }],
["ENOMEM", { kind: "host-exhausted", code: "ENOMEM", resource: "memory" }],
[
"EMFILE",
{ kind: "host-exhausted", code: "EMFILE", resource: "file-descriptors" },
],
[
"ENFILE",
{ kind: "host-exhausted", code: "ENFILE", resource: "file-descriptors" },
],
["E2BIG", { kind: "argument-list", code: "E2BIG" }],
["ENOENT", { kind: "missing", code: "ENOENT" }],
["EACCES", { kind: "not_executable", code: "EACCES" }],
["ENOEXEC", { kind: "not_executable", code: "ENOEXEC" }],
["EPERM", { kind: "not_executable", code: "EPERM" }],
["EIO", { kind: "failed", code: "EIO" }],
[undefined, { kind: "failed", code: undefined }],
["toString", { kind: "failed", code: "toString" }],
])("classifies launch errno %j once", (code, expected) => {
expect(classifyLaunchErrno(code)).toEqual(expected);
});
it.each([
[
"Node spawn",
{ code: "ENOENT", syscall: "spawn /tool", path: "/tool" },
{ kind: "missing", code: "ENOENT", executable: "/tool" },
{
kind: "missing",
code: "ENOENT",
executable: "/tool",
syscall: "spawn /tool",
},
],
[
"Windows native launcher",
@@ -46,22 +76,64 @@ it.each([
kind: "not_executable",
code: "EACCES",
executable: "C:\\tools\\tool.exe",
syscall: undefined,
},
],
[
"bare Node spawn",
{ code: "ENOTDIR", syscall: "spawn" },
{ kind: "missing", code: "ENOTDIR", executable: undefined },
{
kind: "missing",
code: "ENOTDIR",
executable: undefined,
syscall: "spawn",
},
],
[
"Node spawn naming another path",
{ code: "ENOENT", syscall: "spawn /other", path: "/tool" },
{ kind: "missing", code: "ENOENT", executable: undefined },
{
kind: "missing",
code: "ENOENT",
executable: undefined,
syscall: "spawn /other",
},
],
])("reads a %s refusal and the executable it names", (_, fields, expected) => {
expect(
launcherRefusalOf(Object.assign(new Error("refused"), fields)),
).toEqual(expected);
[
"host-capacity spawn",
{ code: "EAGAIN", syscall: "spawn /tool", path: "/tool" },
{
kind: "host-exhausted",
code: "EAGAIN",
resource: "processes",
executable: "/tool",
syscall: "spawn /tool",
},
],
[
"argument-list spawn",
{ code: "E2BIG", syscall: "spawn /tool", path: "/tool" },
{
kind: "argument-list",
code: "E2BIG",
executable: "/tool",
syscall: "spawn /tool",
},
],
[
"other errno spawn",
{ code: "EIO", syscall: "spawn /tool", path: "/tool" },
{
kind: "failed",
code: "EIO",
executable: "/tool",
syscall: "spawn /tool",
},
],
])("reads a %s failure and the executable it names", (_, fields, expected) => {
expect(launcherFailureOf(Object.assign(new Error("failed"), fields))).toEqual(
expected,
);
});
it.each([
@@ -75,12 +147,25 @@ it.each([
requestedPath: "C:\\tools\\tool.exe",
},
],
[
"a launcher error whose errno is not a refusal",
{ code: "EAGAIN", syscall: "spawn /tool", path: "/tool" },
],
])("does not read %s as a launcher refusal", (_, fields) => {
])("does not read %s as a launcher failure", (_, fields) => {
expect(
launcherRefusalOf(Object.assign(new Error("refused"), fields)),
launcherFailureOf(Object.assign(new Error("refused"), fields)),
).toBeUndefined();
});
it("names the syscall only for an errno that is neither a refusal nor a constraint", () => {
const read = (code: string) => {
const failure = launcherFailureOf(
Object.assign(new Error("failed"), {
code,
syscall: "spawn /tool",
path: "/tool",
}),
);
if (failure === undefined) throw new Error("Expected a launcher failure");
return describeLaunchFailure(failure);
};
expect(read("EIO")).toBe("EIO from spawn /tool");
expect(read("ENOENT")).toBe("ENOENT");
expect(read("EAGAIN")).toBe("EAGAIN");
});
+84 -10
View File
@@ -23,6 +23,62 @@ const LAUNCH_REFUSALS: Readonly<Record<string, LaunchRefusal["kind"]>> = {
EISDIR: "not_executable",
};
/** The host resource a launch could not obtain. */
export type LaunchExhaustedResource =
| "processes"
| "memory"
| "file-descriptors";
const HOST_EXHAUSTION: Readonly<Record<string, LaunchExhaustedResource>> = {
EAGAIN: "processes",
ENOMEM: "memory",
EMFILE: "file-descriptors",
ENFILE: "file-descriptors",
};
/**
* The host resource a spawn errno reports as exhausted; undefined for any
* other errno. The selected command may be usable once capacity is freed.
*/
export const launchExhaustedResource = (
code: unknown,
): LaunchExhaustedResource | undefined =>
typeof code === "string" && Object.hasOwn(HOST_EXHAUSTION, code)
? HOST_EXHAUSTION[code]
: undefined;
/**
* Why a process did not start, classified once by errno:
*
* - a launch refusal (`missing`, `not_executable`): the selected executable
* cannot be run;
* - `host-exhausted`: the host lacked process, memory or file-descriptor
* capacity (EAGAIN, ENOMEM, EMFILE, ENFILE);
* - `argument-list`: the request's argument list and environment exceed the
* launch limit (E2BIG);
* - `failed`: any other errno, or none; the provider cannot be started.
*/
export type LaunchFailure =
| LaunchRefusal
| {
readonly kind: "host-exhausted";
readonly code: string;
readonly resource: LaunchExhaustedResource;
}
| { readonly kind: "argument-list"; readonly code: "E2BIG" }
| { readonly kind: "failed"; readonly code: string | undefined };
/** Classify any spawn errno; see `LaunchFailure`. */
export const classifyLaunchErrno = (code: unknown): LaunchFailure => {
const refusal = classifyLaunchFailureCode(code);
if (refusal !== undefined) return refusal;
const resource = launchExhaustedResource(code);
if (resource !== undefined && typeof code === "string")
return { kind: "host-exhausted", code, resource };
if (code === "E2BIG") return { kind: "argument-list", code };
return { kind: "failed", code: typeof code === "string" ? code : undefined };
};
/** Classify a spawn errno; undefined when it is not a launch refusal. */
export const classifyLaunchFailureCode = (
code: unknown,
@@ -63,12 +119,14 @@ export const nameSpawnedExecutable = (
};
/**
* A launch refusal a launcher raised; `executable` when the launcher named the
* executable it refused, undefined when it did not (Node's bare `spawn`).
* A launch failure a launcher raised. `executable` names the executable when
* the launcher named it, undefined when it did not (Node's bare `spawn`);
* `syscall` is the launcher's own label, such as `spawn /usr/bin/tool`.
*/
export interface LauncherRefusal extends LaunchRefusal {
export type LauncherFailure = LaunchFailure & {
readonly executable: string | undefined;
}
readonly syscall: string | undefined;
};
/**
* Whether a launcher raised this error while starting a process, and the
@@ -96,15 +154,31 @@ const launcherIdentityOf = (
};
/**
* Classify a launcher's refusal to start an executable. Undefined when the
* errno is not a launch refusal or no launcher raised the error.
* Classify a launcher's failure to start an executable, by errno. Undefined
* when no launcher raised the error, such as an errno from reading a file or
* preparing process ownership.
*/
export const launcherRefusalOf = (
export const launcherFailureOf = (
cause: unknown,
): LauncherRefusal | undefined => {
): LauncherFailure | undefined => {
if (!(cause instanceof Error)) return undefined;
const identity = launcherIdentityOf(cause);
if (identity === undefined) return undefined;
const refusal = classifyLaunchFailure(cause);
return refusal === undefined ? undefined : { ...refusal, ...identity };
const syscall = Reflect.get(cause, "syscall");
return {
...classifyLaunchErrno(Reflect.get(cause, "code")),
...identity,
syscall: typeof syscall === "string" ? syscall : undefined,
};
};
/**
* How a launch failure reads in a report: the errno, and the launcher's
* syscall for a failure that is neither a refusal nor a host constraint.
*/
export const describeLaunchFailure = (failure: LauncherFailure): string => {
const code = failure.code ?? "no system code";
return failure.kind === "failed" && failure.syscall !== undefined
? `${code} from ${failure.syscall}`
: code;
};
+19 -6
View File
@@ -22,6 +22,7 @@ import { cancelledBy, carriedReason } from "../domain/analysisErrorCore.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
classifyLaunchFailure,
classifyProviderOutcome,
type ProviderOutcomeContext,
} from "../process/classifyProviderOutcome.js";
@@ -72,8 +73,13 @@ export interface ProviderFailureDialect {
cause: unknown,
details: AnalysisErrorOptions,
) => AnalysisError | undefined;
/** How this provider's owned commands report; absent when none ran. */
readonly command?: (outcome: ProviderOutcome) => ProviderOutcomeContext;
/**
* How this provider's owned commands report; absent when none ran. The
* dialect's `providerId` names the provider.
*/
readonly command?: (
outcome: ProviderOutcome,
) => Omit<ProviderOutcomeContext, "providerId">;
/**
* Report for a command whose cleanup failed, given its classified primary.
* Without it the primary is composed with the unresolved resources.
@@ -176,9 +182,9 @@ const commandFailure = (
cause: unknown,
outcome: ProviderOutcome,
dialect: ProviderFailureDialect,
command: (outcome: ProviderOutcome) => ProviderOutcomeContext,
command: NonNullable<ProviderFailureDialect["command"]>,
): AnalysisError => {
const context = command(outcome);
const context = { providerId: dialect.providerId, ...command(outcome) };
if (!cleanupFailed(cause)) return classifyProviderOutcome(outcome, context);
if (dialect.commandCleanup === undefined)
return analysisErrorWithCleanupFailure(
@@ -264,10 +270,17 @@ export const classifyProviderFailure = (
): AnalysisError => {
if (cause instanceof AnalysisError)
return dialect.attribute?.(cause) ?? cause;
const outcome =
dialect.command === undefined ? undefined : providerOutcomeOf(cause);
const outcome = providerOutcomeOf(cause);
if (outcome !== undefined && dialect.command !== undefined)
return commandFailure(cause, outcome, dialect, dialect.command);
// A launcher's failure is classified by the shared owner even for a phase
// whose dialect describes no command reports.
if (outcome?.kind === "launch-failed")
return classifyLaunchFailure(outcome.failure, {
providerId: dialect.providerId,
operation: dialect.operation,
details: { cause },
});
const { file } = dialect;
const observation =
file?.retainCompletedIdentity === true
+7 -2
View File
@@ -1,3 +1,4 @@
import { spawnFailure } from "../../tests/support/process/spawnFailure.js";
import { createHash } from "node:crypto";
import { access, chmod, readFile, realpath, writeFile } from "node:fs/promises";
import { join, resolve } from "node:path";
@@ -1851,7 +1852,7 @@ it("does not attribute wasm-objdump output to a wasm2wat launch failure", async
(input) => {
const version = input.arguments[0] === "--version";
if (!version && input.command.includes("wasm2wat"))
throw Object.assign(new Error("spawn E2BIG"), { code: "E2BIG" });
throw spawnFailure("E2BIG", input.command);
const script = version
? 'process.stdout.write("1.0.42\\n")'
: input.command.includes("objdump")
@@ -1871,7 +1872,11 @@ it("does not attribute wasm-objdump output to a wasm2wat launch failure", async
candidate_paths: [],
});
if (result.ok) throw new Error("Expected the wasm2wat launch to fail");
expect(result.error.message).toContain("spawn E2BIG");
expect(result.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "transport",
reportedLimits: { spawn_error: "E2BIG" },
});
expect(result.error.capturedOutput).toBeUndefined();
});
+27 -15
View File
@@ -7,7 +7,10 @@ import {
import { utf8HeadExcerpt } from "../domain/utf8HeadExcerpt.js";
import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js";
import { capturedProviderOutput } from "../process/capturedProviderOutput.js";
import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js";
import type {
AnalysisCapturedOutput,
AnalysisErrorOptions,
} from "../domain/analysisErrorBase.js";
import {
AnalysisInputError,
AnalysisOutputError,
@@ -110,6 +113,23 @@ export const wabtConfigurationRecoveryAction = (cause?: unknown): string => {
: "";
return `${action}Set absolute REA_WABT_BIN_DIRECTORY to a directory that contains wasm-validate, wasm-objdump and wasm2wat from one WABT installation; each --version must report ${WABT_ACCEPTED_RANGE} on stdout with empty stderr. Releases in that range other than ${WABT_VERSION} are admitted and reported as the observed banner. Correct the reported tool path, access or release before retrying, not the WASM input. Set this in the shell for the next CLI call, or in the MCP server launch environment and restart that server; a shell export does not update a running MCP server. Do not repeat the unchanged call or install tools implicitly.`;
};
/** The configured WABT installation cannot run this call. */
const wabtUnavailable = (
message: string,
cause: unknown,
details: AnalysisErrorOptions,
): AnalysisCapabilityUnavailableError =>
new AnalysisCapabilityUnavailableError(
WABT_PROVIDER_IDENTITY.id,
OPERATION,
message,
{
...details,
userMessage: `Configured WABT could not start. Check executable/interpreter access and WABT ${WABT_VERSION} profile; inspect retained diagnostics.`,
remediationAction: wabtConfigurationRecoveryAction(cause),
},
);
/** Past the output budget, retained text is a prefix of an oversized stream; keep a bounded excerpt of each. */
const outputLimitExcerpt = (snapshot: ProviderProcessSnapshot) => ({
stdout: utf8HeadExcerpt(snapshot.stdout.text, OUTPUT_LIMIT_EXCERPT_BYTES)
@@ -253,21 +273,13 @@ export const wabtFailureDialect = (
),
},
},
launchUnavailable: (_failure, details) =>
wabtUnavailable(outcome.message, outcome.cause, details),
dialect: (exit, details) =>
// A tool that cannot start, or a version probe that exits or whose
// output cannot be collected, leaves the configured installation
// unusable for this call.
exit.kind === "launch-refused" || phase === "configuration"
? new AnalysisCapabilityUnavailableError(
WABT_PROVIDER_IDENTITY.id,
OPERATION,
exit.message,
{
...details,
userMessage: `Configured WABT could not start. Check executable/interpreter access and WABT ${WABT_VERSION} profile; inspect retained diagnostics.`,
remediationAction: wabtConfigurationRecoveryAction(exit.cause),
},
)
// A version probe that exits or whose output cannot be collected
// leaves the configured installation unusable for this call.
phase === "configuration"
? wabtUnavailable(exit.message, exit.cause, details)
: new AnalysisOutputError(OPERATION, exit.message, details),
}),
...(phase === "artifact"
@@ -1,3 +1,4 @@
import { spawnFailure } from "../../support/process/spawnFailure.js";
import { AnalysisResourceConstraintError } from "../../../src/domain/analysisErrorCore.js";
import { packetFieldsCatalogSchema } from "../../../src/domain/captures/packetFields.js";
import { OwnedCommandFailure } from "../../../src/process/OwnedCommand.js";
@@ -77,7 +78,7 @@ else { if(readFileSync('capture', 'utf8') !== 'recording bytes') throw Error('wr
async (input) => {
calls++;
if (mode === "launch-failure" && !input.arguments.includes("--version"))
throw Object.assign(new Error("spawn E2BIG"), { code: "E2BIG" });
throw spawnFailure("E2BIG", input.command);
if (mode === "file-limit" && !input.arguments.includes("--version")) {
const stdout = { text: "", bytes: 0, observedBytes: 0 };
const stderr = {
@@ -536,7 +537,13 @@ it.each(["capture", "fields"] as const)(
: await f.service.inspectFields({ kind: "fields" });
if (result.ok) throw new Error("Expected launch failure");
expect(f.calls()).toBe(2);
expect(result.error.message).toContain("spawn E2BIG");
// A launch failure is not tool output: the shared owner reports the
// oversized argument list as a resource constraint.
expect(result.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "transport",
reportedLimits: { spawn_error: "E2BIG" },
});
expect(result.error.capturedOutput).toBeUndefined();
},
);
+25 -3
View File
@@ -95,17 +95,39 @@ it("reads a refused launch with the operating system's code", async () => {
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
);
expect(outcome).toMatchObject({
kind: "launch-refused",
refusal: { kind: "missing", code: "ENOENT" },
kind: "launch-failed",
failure: { kind: "missing", code: "ENOENT" },
output: undefined,
});
});
it.skipIf(process.platform === "win32")(
"reads a real oversized argument list as an argument-list launch failure",
async () => {
// One 4 MiB argument exceeds the POSIX launch limit (ARG_MAX on macOS,
// MAX_ARG_STRLEN on Linux), so the operating system refuses the exec.
const outcome = await outcomeOf(
{ ...node(""), arguments: ["-e", "", "x".repeat(4 * 1024 * 1024)] },
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
);
expect(outcome).toMatchObject({
kind: "launch-failed",
failure: {
kind: "argument-list",
code: "E2BIG",
executable: process.execPath,
syscall: `spawn ${process.execPath}`,
},
output: undefined,
});
},
);
it("is undefined for a failure that is not an owned command outcome", () => {
expect(providerOutcomeOf(new Error("parse failure"))).toBeUndefined();
});
it("does not read a file errno as a launch refusal", async () => {
it("does not read a file errno as a launch failure", async () => {
const read = await readFile(`/nonexistent-${randomUUID()}/carrier`).then(
() => undefined,
(cause: unknown) => cause,
@@ -1,3 +1,4 @@
import { spawnFailure } from "../../support/process/spawnFailure.js";
import {
AnalysisOutputError,
AnalysisResourceConstraintError,
@@ -120,7 +121,7 @@ const fixture = async (
async (input) => {
calls++;
if (mode === "launch-failure" && !input.arguments.includes("--version"))
throw Object.assign(new Error("spawn E2BIG"), { code: "E2BIG" });
throw spawnFailure("E2BIG", input.command);
if (mode === "file-limit" && !input.arguments.includes("--version")) {
const stdout = { text: "", bytes: 0, observedBytes: 0 };
const stderr = {
@@ -1022,7 +1023,13 @@ it.each(["decode", "discovery"] as const)(
: await f.service.inspectDecoders({});
if (result.ok) throw new Error("Expected launch failure");
expect(f.calls()).toBe(2);
expect(result.error.message).toContain("spawn E2BIG");
// A launch failure is not tool output: the shared owner reports the
// oversized argument list as a resource constraint.
expect(result.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "transport",
reportedLimits: { spawn_error: "E2BIG" },
});
expect(result.error.capturedOutput).toBeUndefined();
},
);
@@ -1,6 +1,13 @@
import { SqliteDatabaseProvider } from "../../../src/sqlite/SqliteDatabaseProvider.js";
import { createSqliteDatabaseFixture } from "../../fixtures/sqlite/database.js";
import { spawnFailure } from "../../support/process/spawnFailure.js";
import {
createTestWorkspace,
removeTestWorkspace,
} from "../../support/workspace/workspaceFixture.js";
import { ArtifactReaderFailure } from "../../../src/resources/ArtifactReader.js";
import { classifyProviderFailure } from "../../../src/providers/classifyProviderFailure.js";
import { expect, it } from "vitest";
import { expect, it, onTestFinished } from "vitest";
import { OwnedCommandFailure } from "../../../src/process/OwnedCommand.js";
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
import { sqliteDatabaseDialect } from "../../../src/sqlite/SqliteDatabaseFailures.js";
@@ -179,3 +186,38 @@ it("does not infer cancellation from a later signal when cleanup carries no canc
details: { resources: ["/owned/reply.json"] },
});
});
// A worker launch failure reaches the shared launch owner even though the
// SQLite dialect describes no command reports.
it.each([
["EAGAIN", "resource_constraint", { resource: "capacity" }],
["E2BIG", "resource_constraint", { resource: "transport" }],
["EIO", "capability_unavailable", { provider_id: "sqlite" }],
] as const)(
"classifies a SQLite worker launch failure %s once by errno",
async (code, projectedCode, details) => {
const workspace = await createTestWorkspace("rea-sqlite-launch-");
onTestFinished(() => removeTestWorkspace(workspace.root));
const database = createSqliteDatabaseFixture(workspace.root);
database.close();
const provider = new SqliteDatabaseProvider({}, async (input) => {
throw spawnFailure(code, input.command);
});
onTestFinished(() => provider.close());
const result = await provider.inspect({ path: database.path });
if (result.ok) throw new Error("Expected the worker launch to fail");
const projected = projectAnalysisError(result.error);
expect(projected).toMatchObject({
code: projectedCode,
details: {
...details,
diagnostics: {
system_code: code,
syscall: `spawn ${process.execPath}`,
},
},
});
expect(projected.message).toContain(code);
expect((await provider.inspect({ path: database.path })).ok).toBe(false);
},
);
+2 -2
View File
@@ -1,3 +1,4 @@
import { spawnFailure } from "../support/process/spawnFailure.js";
import { fileIdentity } from "../fixtures/evidenceSubject.js";
import { createHash } from "node:crypto";
import type { Stats } from "node:fs";
@@ -14,7 +15,6 @@ import { TestReverseEngineeringService as ReverseEngineeringService } from "../s
import {
fixtureCommandRepair,
ownedFailure,
ownedLaunchRefusal,
ownedOutput,
providerSnapshot,
} from "../support/reverseEngineeringCompositionFixtures.js";
@@ -200,7 +200,7 @@ describe("reverse engineering command services", () => {
await writeFile(path, "fixture");
const service = new ReverseEngineeringService({
runOwned: async (spawn) => {
throw ownedLaunchRefusal("ENOENT", spawn.command);
throw spawnFailure("ENOENT", spawn.command);
},
});
@@ -1,3 +1,4 @@
import { spawnFailure } from "../support/process/spawnFailure.js";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -7,7 +8,6 @@ import { expect, it } from "vitest";
import { TestReverseEngineeringService } from "../support/reverseEngineeringService.js";
import {
ownedFailure,
ownedLaunchRefusal,
ownedOutput,
} from "../support/reverseEngineeringCompositionFixtures.js";
@@ -34,8 +34,7 @@ it.each([
const service = new TestReverseEngineeringService({
runOwned: async (spawn) => {
calls += 1;
if (mode === "failure")
throw ownedLaunchRefusal("ENOENT", spawn.command);
if (mode === "failure") throw spawnFailure("ENOENT", spawn.command);
if (mode === "timeout") throw ownedFailure("timeout", null);
await gate;
return ownedOutput();
@@ -273,7 +272,7 @@ it.each([
const controller = new AbortController();
const failure =
code === "EACCES"
? ownedLaunchRefusal(code, "objdump")
? spawnFailure(code, "objdump")
: ownedFailure(
code,
captured
@@ -1,3 +1,4 @@
import { spawnFailure } from "../support/process/spawnFailure.js";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -12,7 +13,6 @@ import { createReverseEngineeringCommandPort } from "../../src/composition/rever
import type { runOwnedCommand } from "../../src/process/OwnedCommand.js";
import {
fixtureCommandRepair,
ownedLaunchRefusal,
ownedOutput,
} from "../support/reverseEngineeringCompositionFixtures.js";
@@ -402,7 +402,7 @@ it("reports a launch refusal with the repair the command port names", async () =
const service = new ReverseEngineeringService({
commands: { objdump: () => ok(profile), rizin: () => ok(profile) },
runOwned: async (spawn) => {
throw ownedLaunchRefusal("ENOENT", spawn.command);
throw spawnFailure("ENOENT", spawn.command);
},
});
try {
@@ -1,3 +1,4 @@
import { spawnFailure } from "../support/process/spawnFailure.js";
import { rm } from "node:fs/promises";
import type { Stats } from "node:fs";
@@ -1006,26 +1007,12 @@ it("preserves a provider timeout when cancellation arrives during the final dige
it("classifies E2BIG as a provider command resource constraint", async () => {
const { directory, path } = await createArtifact();
const cleanupOwner = {
stop: vi.fn(async () => ({ status: "verified-cleanup" as const })),
} as unknown as ProviderProcessSupervisor;
// The owned supervisor rethrows the launcher's spawn error unchanged.
const runOwned = vi
.fn<typeof runOwnedCommand>()
.mockRejectedValueOnce(
new OwnedCommandFailure(
"process",
"Command launch failed.",
null,
"owned descendant remains",
{
cause: Object.assign(new Error("argument list too long"), {
code: "E2BIG",
}),
},
["run-id", "pid:42"],
cleanupOwner,
),
)
.mockImplementationOnce(async (spawn) => {
throw spawnFailure("E2BIG", spawn.command);
})
.mockResolvedValue(providerSnapshot());
const service = new ReverseEngineeringService({
runOwned,
@@ -1033,31 +1020,20 @@ it("classifies E2BIG as a provider command resource constraint", async () => {
try {
const result = await service.executeRizinCommand({ path, command: "iI" });
expect(result).toMatchObject({
ok: false,
error: {
_tag: "AnalysisResourceConstraintError",
resource: "transport",
operation: "execute_rizin_command",
if (result.ok) throw new Error("Expected an argument-list constraint");
expect(result.error).toBeInstanceOf(AnalysisResourceConstraintError);
expect(result.error).toMatchObject({
resource: "transport",
operation: "execute_rizin_command",
reportedLimits: {
spawn_error: "E2BIG",
argument_bytes: expect.any(Number),
},
retryable: false,
});
if (!result.ok)
expect(result.error.message).toContain(
"The host rejected the provider command because its argument list exceeds the process launch limit.",
);
if (!result.ok) {
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanup?.resources).toEqual(["run-id", "pid:42"]);
expect(result.error).toBeInstanceOf(AnalysisResourceConstraintError);
if (result.error instanceof AnalysisResourceConstraintError)
expect(result.error.reportedLimits).toMatchObject({
argument_bytes: expect.any(Number),
});
}
expect(result.error.cleanupIncomplete).toBe(false);
const retried = await service.executeRizinCommand({ path, command: "iI" });
expect(retried.ok).toBe(true);
if (!result.ok) expect(result.error.cleanupIncomplete).toBe(false);
expect(cleanupOwner.stop).toHaveBeenCalledOnce();
expect(runOwned).toHaveBeenCalledTimes(2);
} finally {
await rm(directory, { recursive: true, force: true });
@@ -1,3 +1,4 @@
import { spawnFailure } from "../support/process/spawnFailure.js";
import { rm } from "node:fs/promises";
import { resolve } from "node:path";
import { expect, it, onTestFinished, vi } from "vitest";
@@ -34,21 +35,17 @@ import {
import { TestReverseEngineeringService } from "../support/reverseEngineeringService.js";
import { awaitAcknowledgement } from "../fixtures/lifecycleAcknowledgement.js";
it.each(["ENOENT", "EACCES", "EPERM", "ENOTDIR"] as const)(
it.each(["ENOENT", "EACCES", "EPERM", "ENOTDIR", "EIO"] as const)(
"preserves provider-launch %s and executable recovery independently of target admission",
async (code) => {
const { directory, path } = await createArtifact();
const command = resolve(directory, "configured-objdump");
const hostFailure = Object.assign(
new Error("controlled executable launch rejection"),
{ code },
);
// The owned supervisor rethrows the launcher's spawn error unchanged.
const hostFailure = spawnFailure(code, command);
const service = new TestReverseEngineeringService({
environment: { REA_OBJDUMP_COMMAND: command },
runOwned: async () => {
throw new OwnedCommandFailure("process", "launch failed", null, null, {
cause: hostFailure,
});
throw hostFailure;
},
});
try {
@@ -69,6 +66,7 @@ it.each(["ENOENT", "EACCES", "EPERM", "ENOTDIR"] as const)(
boundary: "provider-launch",
command,
system_code: code,
syscall: `spawn ${command}`,
},
},
remediation: {
@@ -76,7 +74,9 @@ it.each(["ENOENT", "EACCES", "EPERM", "ENOTDIR"] as const)(
},
});
expect(projected.message).toContain(command);
expect(projected.message).toContain(code);
expect(projected.message).toContain(
code === "EIO" ? `EIO from spawn ${command}` : code,
);
expect(projected.remediation.action).toContain("execute permission");
expect(projected.remediation.action).not.toContain("another target");
}
@@ -92,16 +92,12 @@ it.each(["EAGAIN", "EMFILE", "ENFILE", "ENOMEM"] as const)(
async (code) => {
const { directory, path } = await createArtifact();
const command = resolve(directory, "configured-objdump");
const hostFailure = Object.assign(
new Error("controlled host capacity rejection"),
{ code },
);
// The owned supervisor rethrows the launcher's spawn error unchanged.
const hostFailure = spawnFailure(code, command);
const service = new TestReverseEngineeringService({
environment: { REA_OBJDUMP_COMMAND: command },
runOwned: async () => {
throw new OwnedCommandFailure("process", "launch failed", null, null, {
cause: hostFailure,
});
throw hostFailure;
},
});
try {
@@ -150,16 +146,12 @@ it.each(["EAGAIN", "EMFILE", "ENFILE", "ENOMEM"] as const)(
async (code) => {
const { directory, path } = await createArtifact();
const command = resolve(directory, "configured-rizin");
const hostFailure = Object.assign(
new Error("controlled host capacity rejection"),
{ code },
);
// The owned supervisor rethrows the launcher's spawn error unchanged.
const hostFailure = spawnFailure(code, command);
const service = new TestReverseEngineeringService({
environment: { REA_RIZIN_COMMAND: command },
runOwned: async () => {
throw new OwnedCommandFailure("process", "launch failed", null, null, {
cause: hostFailure,
});
throw hostFailure;
},
});
try {
@@ -208,10 +200,7 @@ it.each(["EAGAIN", "EMFILE", "ENFILE", "ENOMEM"] as const)(
async (code) => {
const { directory } = await createArtifact();
const command = resolve(directory, "configured-objdump");
const hostFailure = Object.assign(
new Error("controlled ps host capacity rejection"),
{ code },
);
const hostFailure = spawnFailure(code, "/bin/ps");
const prepareSpy = vi
.spyOn(systemProcessOwnershipHost, "prepare")
.mockRejectedValue(hostFailure);
@@ -258,10 +247,7 @@ it.each(["EAGAIN", "EMFILE", "ENFILE", "ENOMEM"] as const)(
async (code) => {
const { directory } = await createArtifact();
const command = resolve(directory, "configured-objdump");
const hostFailure = Object.assign(
new Error("controlled ps host capacity rejection"),
{ code },
);
const hostFailure = spawnFailure(code, "/bin/ps");
const prepareSpy = vi
.spyOn(systemProcessOwnershipHost, "prepare")
.mockRejectedValue(new LinuxOwnedProcessPrerequisiteError(hostFailure));
+13
View File
@@ -0,0 +1,13 @@
/**
* The error Node's `spawn` emits when it cannot start `command`: the errno as
* `code`, `syscall: "spawn <command>"` and `path`. Owned supervision rethrows
* a launcher's error unchanged, and the shared launch owner recognises only
* this launcher-raised shape, so test launchers throw it rather than a bare
* errno.
*/
export const spawnFailure = (code: string, command = "provider"): Error =>
Object.assign(new Error(`spawn ${command} ${code}`), {
code,
syscall: `spawn ${command}`,
path: command,
});
+1 -1
View File
@@ -211,7 +211,7 @@ export const PROVIDER_LIFECYCLE_COVERAGE: Readonly<
launch: covered(
test(
"src/apktool/ApktoolProvider.test.ts",
"reports launcher disappearance after version admission as a provider failure",
"reports launcher disappearance after version admission as apktool unavailable",
),
),
handshake: ONE_SHOT,
@@ -55,17 +55,6 @@ export const ownedFailure = (
options,
);
/**
* A launcher's refusal to start the command. The owned supervisor rethrows
* the launcher's spawn error unchanged.
*/
export const ownedLaunchRefusal = (code: string, command = "provider"): Error =>
Object.assign(new Error(`spawn ${command} ${code}`), {
code,
syscall: `spawn ${command}`,
path: command,
});
/** Repair guidance for a test-built command profile. */
export const fixtureCommandRepair = {
provider: "fixture",