mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
refactor(process): classify owned command outcomes through one owner (#10628)
* fix(pcap): report a refused tool launch as an unavailable tool When a capture read's tool launch was refused with EPERM, pcap reported it as unreadable tool output (AnalysisProtocolError) instead of an unavailable tool. Pcap also never told "not executable" apart from "missing". Add classifyLaunchFailure in src/process as the one owner of which spawn errnos mean missing (ENOENT, ENOTDIR) and which mean present but not executable (EACCES, EPERM, ENOEXEC, EISDIR). Pcap, apktool and gdb used three different errno lists; all three now use it. * refactor(process): classify owned command outcomes through one owner Add ProviderOutcome, read once from the supervisor's facts, and classifyProviderOutcome, the one mapping from an outcome to a typed error. Migrate pcap and the shared artifact producer command failure (TShark, sigrok). Add the rea/provider-failure-classifier lint rule with a shrink-only baseline of per-site (cause: unknown) => AnalysisError functions. * refactor(process): classify Java and adb launch refusals with the shared owner (#10598) The Ghidra and JADX Java probes and adb's version probe now take missing-versus-not-executable from classifyLaunchFailure instead of their own errno checks. ELOOP and ENAMETOOLONG join the owner's missing set, so adb keeps its existing classification and both Java probes now treat a non-directory path component as a missing runtime. * fix(pcap): preserve command launch attribution * test(pcap): expect an unknown failing stage when a limited capture tool exits unsuccessfully * refactor(process): classify owned command outcomes through one owner Add ProviderOutcome, read once from the supervisor's facts, and classifyProviderOutcome, the one mapping from an outcome to a typed error. Migrate pcap and the shared artifact producer command failure (TShark, sigrok). Add the rea/provider-failure-classifier lint rule with a shrink-only baseline of per-site (cause: unknown) => AnalysisError functions. * test(lint): cover baselined files in the provider-failure classifier rule * fix(pcap): attribute a limited capture's exit through the prlimit wrapper * fix(process): identify the refused executable for every launcher shape Name the executable on errnos Node throws synchronously from spawn (ENOEXEC, ENOTDIR, ...) and read the Windows native launcher's executable-launch constraint, so pcap attributes those refusals to the selected tool or limiter instead of an unknown stage. * test(pcap): prove synchronous launch naming with ENOTDIR on every POSIX host * refactor(process): build classified cancellations with cancelledBy and the carried caller reason * chore(lint): count runOwned's close-failure mapper from main in the classifier baseline
This commit is contained in:
1 parent
b33e5c4867
commit
1f7884b5b9
13 files changed
+870
-213
No files matched your search
@@ -88,6 +88,7 @@
|
||||
{
|
||||
"files": ["src/**/*.ts"],
|
||||
"rules": {
|
||||
"rea/provider-failure-classifier": "error",
|
||||
"rea/typed-resource-refusal": "error",
|
||||
"rea/no-babel-visitor-keys": "error",
|
||||
"typescript/no-misused-promises": "error"
|
||||
@@ -101,6 +102,7 @@
|
||||
"src/**/*.fixture.ts"
|
||||
],
|
||||
"rules": {
|
||||
"rea/provider-failure-classifier": "off",
|
||||
"rea/typed-resource-refusal": "off",
|
||||
"rea/no-babel-visitor-keys": "off",
|
||||
"max-lines": "off",
|
||||
|
||||
@@ -262,6 +262,17 @@ activation independently of readiness. An owned registration may be disabled
|
||||
or stale; unresolved ownership remains unknown. Consumers use those facts
|
||||
instead of reclassifying the raw command.
|
||||
|
||||
Owned provider commands follow the same rule. `providerOutcomeOf` in
|
||||
`src/process/ProviderOutcome.ts` reads what the supervisor observed (launch
|
||||
refusal, cancellation, deadline, output or memory limit, resource signal, exit
|
||||
status with the owner's stop state, or stream failure) together with the
|
||||
retained output and whether it was truncated. `classifyProviderOutcome` maps
|
||||
that outcome to a typed error once; a provider supplies only its settings,
|
||||
recovery text and a dialect for what an exit or launch refusal means. The
|
||||
`rea/provider-failure-classifier` lint rule keeps new `(cause: unknown) =>
|
||||
AnalysisError` functions out of `src/`; existing ones are counted in a baseline
|
||||
that may only shrink.
|
||||
|
||||
A completed read can establish byte identity even when decoding or format
|
||||
validation fails. State which representation a digest identifies, such as file
|
||||
bytes, Fetch response-body bytes, or UTF-8 text. Preserve admitted source values
|
||||
|
||||
@@ -8,6 +8,7 @@ import noSharedModuleMock from "./rules/no-shared-module-mock.mjs";
|
||||
import noLocaleCompare from "./rules/no-locale-compare.mjs";
|
||||
import noBabelVisitorKeys from "./rules/no-babel-visitor-keys.mjs";
|
||||
import projectWaitDeadline from "./rules/project-wait-deadline.mjs";
|
||||
import providerFailureClassifier from "./rules/provider-failure-classifier.mjs";
|
||||
import typedResourceRefusal from "./rules/typed-resource-refusal.mjs";
|
||||
|
||||
export default {
|
||||
@@ -22,6 +23,7 @@ export default {
|
||||
"no-locale-compare": noLocaleCompare,
|
||||
"no-babel-visitor-keys": noBabelVisitorKeys,
|
||||
"project-wait-deadline": projectWaitDeadline,
|
||||
"provider-failure-classifier": providerFailureClassifier,
|
||||
"typed-resource-refusal": typedResourceRefusal,
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,84 @@
|
||||
{
|
||||
"src/adb/AdbProvider.ts": 1,
|
||||
"src/android/AndroidMappingFile.ts": 3,
|
||||
"src/android/JadxConfiguration.ts": 1,
|
||||
"src/apkSignature/apkSignatureFailures.ts": 2,
|
||||
"src/apktool/ApktoolCommandCleanup.ts": 1,
|
||||
"src/apktool/ApktoolConfiguration.ts": 1,
|
||||
"src/apktool/ApktoolProvider.ts": 1,
|
||||
"src/application/SetupCleanupOwner.ts": 2,
|
||||
"src/application/Uninstall.ts": 1,
|
||||
"src/application/WebScriptExportService.ts": 2,
|
||||
"src/application/apiContract/ApiContractRead.ts": 1,
|
||||
"src/application/binaryDiagnostics/ByteEntropyService.ts": 1,
|
||||
"src/application/desktop/DesktopBuildComputers.ts": 2,
|
||||
"src/application/desktop/DesktopCaptureFailure.ts": 1,
|
||||
"src/application/desktop/DesktopCaptureRefusals.ts": 1,
|
||||
"src/application/desktop/DesktopTaskReaderCleanup.ts": 2,
|
||||
"src/application/managed/ManagedMemberComparisonService.ts": 1,
|
||||
"src/application/ntfs/NtfsJournalService.ts": 1,
|
||||
"src/application/process/ProcessCli.ts": 1,
|
||||
"src/application/runOwned.ts": 1,
|
||||
"src/artifacts/ArtifactOperationFailure.ts": 1,
|
||||
"src/artifacts/ReleaseExposureReader.ts": 1,
|
||||
"src/artifacts/StableArtifactFailure.ts": 2,
|
||||
"src/browser/BrowserScenarioPartialObservation.ts": 1,
|
||||
"src/browser/CdpBrowserProvider.ts": 1,
|
||||
"src/browser/CdpElectronProvider.ts": 1,
|
||||
"src/browser/CdpEndpoint.ts": 1,
|
||||
"src/browser/ElectronFileScope.ts": 1,
|
||||
"src/browser/PlaywrightElectronActiveProvider.ts": 1,
|
||||
"src/browser/WebBundleAnalysisWorker.ts": 2,
|
||||
"src/browser/assets/WebArtifactReads.ts": 1,
|
||||
"src/browser/history/CaptureFailures.ts": 2,
|
||||
"src/browser/history/playwrightTrace/TraceFailure.ts": 1,
|
||||
"src/captures/TsharkCaptureProvider.ts": 1,
|
||||
"src/cutter/CutterBridgeClient.ts": 1,
|
||||
"src/dotnet/ManagedSnapshot.ts": 1,
|
||||
"src/electron/ElectronFuseFailures.ts": 1,
|
||||
"src/evm/EvmoleFailures.ts": 1,
|
||||
"src/firmware/FirmwareFailures.ts": 2,
|
||||
"src/flutter/FlutterBuildProvider.ts": 2,
|
||||
"src/frida/FridaInstrumentationManager.ts": 1,
|
||||
"src/ghidra/GhidraClient.ts": 1,
|
||||
"src/ghidra/GhidraFileArtifacts.ts": 1,
|
||||
"src/ghidra/GhidraJavaProbe.ts": 1,
|
||||
"src/ghidra/GhidraLoadImageAttest.ts": 1,
|
||||
"src/ghidra/GhidraNativeAotSnapshotOwner.ts": 1,
|
||||
"src/ghidra/GhidraPspExtension.ts": 1,
|
||||
"src/go/GoBinaryProvider.ts": 1,
|
||||
"src/hopper/HopperFileOffset.ts": 1,
|
||||
"src/il2cpp/Il2cppMetadataProvider.ts": 1,
|
||||
"src/inspector/V8InspectorProvider.ts": 1,
|
||||
"src/javascript/analysis/JavaScriptAnalysisWorker.ts": 3,
|
||||
"src/javascript/sourceMaps/SourceMapCommand.ts": 1,
|
||||
"src/jeb/JebProvider.ts": 1,
|
||||
"src/kuna/KunaCommand.ts": 1,
|
||||
"src/kuna/KunaProjectExport.ts": 1,
|
||||
"src/kuna/KunaSessionClient.ts": 1,
|
||||
"src/kuna/KunaTargetCommands.ts": 1,
|
||||
"src/native/AppleDispatchMetadata.ts": 1,
|
||||
"src/native/NativeCallTarget.ts": 1,
|
||||
"src/native/NativeMacOSProvider.ts": 4,
|
||||
"src/native/NativePlistSource.ts": 1,
|
||||
"src/native/SignatureTargetBinding.ts": 3,
|
||||
"src/native/exports/NativeExportsProvider.ts": 1,
|
||||
"src/native/hardening/BinaryHardeningProvider.ts": 1,
|
||||
"src/native/initializers/NativeInitializersProvider.ts": 1,
|
||||
"src/native/pe/PeBinaryFailure.ts": 1,
|
||||
"src/native/pe/PeImportsProvider.ts": 1,
|
||||
"src/native/pe/PeLoadConfigProvider.ts": 1,
|
||||
"src/native/pwntools/PwntoolsFailures.ts": 2,
|
||||
"src/native/windows/WindowsShortcutProvider.ts": 1,
|
||||
"src/pcap/PcapProvider.ts": 2,
|
||||
"src/process/ArtifactAnalysisResources.ts": 3,
|
||||
"src/process/capture/ProcessTerminalObservation.ts": 2,
|
||||
"src/process/privateWorkspaceFailure.ts": 1,
|
||||
"src/providers/AnalysisClientFailure.ts": 1,
|
||||
"src/providers/OwnedCommandCleanup.ts": 2,
|
||||
"src/rust/RustBinaryProvider.ts": 1,
|
||||
"src/signals/SigrokRecordingProvider.ts": 1,
|
||||
"src/sqlite/SqliteDatabaseFailures.ts": 1,
|
||||
"src/sqlite/SqliteDatabaseWorkerExecution.ts": 1,
|
||||
"src/wasm/WabtFailures.ts": 2
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
import type { RuleTester } from "oxlint/plugins-dev";
|
||||
|
||||
declare const rule: Parameters<RuleTester["run"]>[1];
|
||||
export default rule;
|
||||
@@ -0,0 +1,91 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
import { relative } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const root = fileURLToPath(new URL("../../../", import.meta.url));
|
||||
/**
|
||||
* Files that predate the rule, with their count of per-site classifier
|
||||
* functions. A count may only shrink: the rule reports a file above or below
|
||||
* its entry.
|
||||
*/
|
||||
const baseline = JSON.parse(
|
||||
readFileSync(
|
||||
new URL("./provider-failure-classifier-baseline.json", import.meta.url),
|
||||
"utf8",
|
||||
),
|
||||
);
|
||||
|
||||
const isUnknownParameter = (parameter) => {
|
||||
const target =
|
||||
parameter.type === "AssignmentPattern"
|
||||
? parameter.left
|
||||
: parameter.type === "TSParameterProperty"
|
||||
? parameter.parameter
|
||||
: parameter;
|
||||
return target?.typeAnnotation?.typeAnnotation?.type === "TSUnknownKeyword";
|
||||
};
|
||||
|
||||
const namesAnalysisError = (type) => {
|
||||
if (type === undefined || type === null) return false;
|
||||
if (type.type === "TSUnionType") return type.types.some(namesAnalysisError);
|
||||
return (
|
||||
type.type === "TSTypeReference" &&
|
||||
type.typeName.type === "Identifier" &&
|
||||
type.typeName.name === "AnalysisError"
|
||||
);
|
||||
};
|
||||
|
||||
/**
|
||||
* A per-site classifier takes an unexamined `unknown` failure and returns an
|
||||
* `AnalysisError`, re-deriving what kind of failure it was.
|
||||
*/
|
||||
const isClassifier = (node) =>
|
||||
node.params.some(isUnknownParameter) &&
|
||||
namesAnalysisError(node.returnType?.typeAnnotation);
|
||||
|
||||
export default {
|
||||
meta: {
|
||||
type: "problem",
|
||||
docs: {
|
||||
description:
|
||||
"Classify raw provider failures through the shared ProviderOutcome classifier, not a new per-site function.",
|
||||
},
|
||||
schema: [],
|
||||
messages: {
|
||||
classifier:
|
||||
"Do not add a per-site `(cause: unknown) => AnalysisError` classifier. Read the supervisor's facts with providerOutcomeOf(cause) and classify them with classifyProviderOutcome(...), putting provider-specific refusals in its dialect.",
|
||||
stale:
|
||||
"provider-failure-classifier-baseline.json allows {{allowed}} per-site classifiers in this file but {{actual}} remain; lower the entry to {{actual}}.",
|
||||
},
|
||||
},
|
||||
create(context) {
|
||||
const filename = relative(
|
||||
root,
|
||||
context.physicalFilename ?? context.filename,
|
||||
).replaceAll("\\", "/");
|
||||
const classifiers = [];
|
||||
const visit = (node) => {
|
||||
if (isClassifier(node)) classifiers.push(node);
|
||||
};
|
||||
return {
|
||||
ArrowFunctionExpression: visit,
|
||||
FunctionDeclaration: visit,
|
||||
FunctionExpression: visit,
|
||||
"Program:exit"(program) {
|
||||
const allowed = baseline[filename] ?? 0;
|
||||
if (classifiers.length > allowed)
|
||||
for (const node of classifiers)
|
||||
context.report({ node, messageId: "classifier" });
|
||||
else if (classifiers.length < allowed)
|
||||
context.report({
|
||||
node: program,
|
||||
messageId: "stale",
|
||||
data: {
|
||||
allowed: String(allowed),
|
||||
actual: String(classifiers.length),
|
||||
},
|
||||
});
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
@@ -153,12 +153,12 @@
|
||||
"src/native/pwntools/PwntoolsDecoder.ts": 8,
|
||||
"src/native/pwntools/PwntoolsFailures.ts": 2,
|
||||
"src/native/pwntools/PwntoolsRecordedCrashProvider.ts": 1,
|
||||
"src/pcap/PcapCommand.ts": 3,
|
||||
"src/pcap/PcapCommand.ts": 2,
|
||||
"src/pcap/PcapNativeBound.ts": 1,
|
||||
"src/pcap/PcapOutput.ts": 1,
|
||||
"src/pcap/PcapProvider.ts": 4,
|
||||
"src/pcap/PcapSnapshot.ts": 3,
|
||||
"src/process/ArtifactAnalysisResources.ts": 10,
|
||||
"src/process/ArtifactAnalysisResources.ts": 9,
|
||||
"src/process/RegexMatcher.ts": 2,
|
||||
"src/process/capture/ProcessCaptureError.ts": 2,
|
||||
"src/process/ownedDebuggerSession.ts": 1,
|
||||
|
||||
+134
-155
@@ -11,14 +11,13 @@ import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js";
|
||||
import {
|
||||
AnalysisError,
|
||||
type AnalysisCapturedOutput,
|
||||
type AnalysisErrorOptions,
|
||||
} from "../domain/analysisErrorBase.js";
|
||||
import { createPcapDiagnosticProjection } from "./PcapDiagnosticOutput.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisProtocolError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisTimeoutError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import {
|
||||
@@ -36,10 +35,9 @@ import {
|
||||
windowsBatchCommand,
|
||||
WindowsBatchCommandError,
|
||||
} from "../process/WindowsBatchCommand.js";
|
||||
import {
|
||||
classifyLaunchFailure,
|
||||
executableLaunchRefusalOf,
|
||||
} from "../process/launchFailure.js";
|
||||
import { providerOutcomeOf } from "../process/ProviderOutcome.js";
|
||||
import { classifyProviderOutcome } from "../process/classifyProviderOutcome.js";
|
||||
import { executableLaunchRefusalOf } from "../process/launchFailure.js";
|
||||
import { pcapToolUnavailable } from "./PcapConfiguration.js";
|
||||
import {
|
||||
attributePcapLimitedExit,
|
||||
@@ -113,6 +111,33 @@ export const runPcapCommand = async (options: {
|
||||
snapshot.diagnosticTruncated === true ||
|
||||
snapshot.outputIncomplete === true,
|
||||
});
|
||||
/** A version probe that fails names the tool; a capture read names the file. */
|
||||
const pcapToolFailure = (
|
||||
diagnostic: string,
|
||||
details: AnalysisErrorOptions,
|
||||
): AnalysisError => {
|
||||
if (options.inputPath === undefined)
|
||||
return pcapToolUnavailable(
|
||||
operation,
|
||||
`The selected tool ${command} cannot report its version: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
if (
|
||||
/not a capture file|file.*isn't a capture file|file format.*not supported/iu.test(
|
||||
diagnostic,
|
||||
)
|
||||
)
|
||||
return new AnalysisUnsupportedTargetError(
|
||||
operation,
|
||||
options.inputPath,
|
||||
diagnostic,
|
||||
details,
|
||||
);
|
||||
return new AnalysisProtocolError(
|
||||
`Packet capture tool ${command} failed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
};
|
||||
if (signal?.aborted)
|
||||
throw new AnalysisCancelledError(operation, { cause: signal.reason });
|
||||
const hostEnvironment = {
|
||||
@@ -231,14 +256,8 @@ export const runPcapCommand = async (options: {
|
||||
? { stdout: "", stderr: "", truncated: true }
|
||||
: captureDiagnostic(cause.snapshot),
|
||||
);
|
||||
const details = {
|
||||
cause,
|
||||
...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
|
||||
? {
|
||||
capturedOutput: captureDiagnostic(cause.snapshot),
|
||||
}
|
||||
: {}),
|
||||
...(cleanup !== undefined
|
||||
const cleanupDetails =
|
||||
cleanup !== undefined
|
||||
? { cleanup }
|
||||
: cause instanceof OwnedCommandFailure && cause.cleanupFailure !== null
|
||||
? {
|
||||
@@ -247,158 +266,118 @@ export const runPcapCommand = async (options: {
|
||||
resources: cause.resources,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
};
|
||||
if (cause instanceof OwnedCommandFailure && cause.reason === "cancelled")
|
||||
throw new AnalysisCancelledError(operation, {
|
||||
...details,
|
||||
cause: cause.cancellation?.reason,
|
||||
});
|
||||
if (
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
cause.snapshot?.memoryLimitReached === true
|
||||
)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
"The owned Windows tool tree reached its enforced committed-memory limit.",
|
||||
{
|
||||
process_memory_limit_bytes:
|
||||
options.nativeBound?.memoryLimitBytes ?? null,
|
||||
},
|
||||
details,
|
||||
);
|
||||
if (
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
(cause.snapshot?.signal === "SIGXCPU" ||
|
||||
cause.snapshot?.signal === "SIGXFSZ")
|
||||
)
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
cause.snapshot.signal === "SIGXCPU" ? "cpu" : "file-size",
|
||||
`Producer terminated with ${cause.snapshot.signal}; its exact cause is not independently established.`,
|
||||
null,
|
||||
details,
|
||||
);
|
||||
if (cause instanceof OwnedCommandFailure && cause.reason === "timeout")
|
||||
throw new AnalysisTimeoutError(operation, limits.timeoutMs, details);
|
||||
if (cause instanceof OwnedCommandFailure && cause.reason === "output-limit")
|
||||
throw new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
"Tool output exceeded its complete-output budget",
|
||||
{ max_output_bytes: limits.maxOutputBytes },
|
||||
{
|
||||
...details,
|
||||
...fixedAllowanceOptions(
|
||||
"The packet-tool output capture allowance",
|
||||
"capture",
|
||||
),
|
||||
},
|
||||
);
|
||||
: {};
|
||||
if (cause instanceof WindowsBatchCommandError)
|
||||
throw pcapToolUnavailable(
|
||||
operation,
|
||||
`Cannot run selected tool ${command}: ${cause.message}`,
|
||||
details,
|
||||
{ cause, ...cleanupDetails },
|
||||
);
|
||||
const selectedLimiter =
|
||||
options.nativeBound?.limiter?.command.invocationPath;
|
||||
const launchedPath = selectedLimiter ?? command;
|
||||
const launchRefusal = executableLaunchRefusalOf(cause);
|
||||
const spawnRefusal =
|
||||
launchRefusal?.executable === launchedPath ? launchRefusal : undefined;
|
||||
if (spawnRefusal !== undefined && selectedLimiter !== undefined) {
|
||||
const reason = `Selected capture limiter ${selectedLimiter} could not be launched (${spawnRefusal.code}).`;
|
||||
throw new AnalysisCapabilityUnavailableError("pcap", operation, reason, {
|
||||
...details,
|
||||
userMessage: `${reason} ${PCAP_LIMITER_REMEDIATION}`,
|
||||
remediationAction: PCAP_LIMITER_REMEDIATION,
|
||||
});
|
||||
}
|
||||
if (spawnRefusal !== undefined)
|
||||
throw pcapToolUnavailable(
|
||||
operation,
|
||||
spawnRefusal.kind === "missing"
|
||||
? `Selected tool ${command} was not found (${spawnRefusal.code})`
|
||||
: `Selected tool ${command} exists but could not be executed (${spawnRefusal.code})`,
|
||||
details,
|
||||
);
|
||||
const diagnostic =
|
||||
cause instanceof OwnedCommandFailure
|
||||
? cause.snapshot?.stderr.text.trim() || cause.message
|
||||
: cause instanceof Error
|
||||
? cause.message
|
||||
: String(cause);
|
||||
if (!commandAttempted)
|
||||
throw new AnalysisProtocolError(
|
||||
/** Only a launcher naming the launched path identifies who refused. */
|
||||
const refusedByLaunchedPath = (refused: unknown): boolean =>
|
||||
executableLaunchRefusalOf(refused)?.executable === launchedPath;
|
||||
const preparationFailure = (
|
||||
diagnostic: string,
|
||||
details: AnalysisErrorOptions,
|
||||
): AnalysisProtocolError =>
|
||||
new AnalysisProtocolError(
|
||||
`Preparing the owned packet command failed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
if (classifyLaunchFailure(cause) !== undefined)
|
||||
throw new AnalysisProtocolError(
|
||||
`The packet command could not start; the failing stage is unknown: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
if (
|
||||
selectedLimiter !== undefined &&
|
||||
cause instanceof OwnedCommandFailure &&
|
||||
cause.reason === "process"
|
||||
) {
|
||||
if (cause.collectionFailure || cause.snapshot === null)
|
||||
throw new AnalysisProtocolError(
|
||||
`The bounded packet command failed before its exit was observed; whether the limiter or selected tool failed is unknown: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
const attributed = attributePcapLimitedExit(selectedLimiter, {
|
||||
exitCode: cause.snapshot.exitCode,
|
||||
signal: cause.snapshot.signal,
|
||||
stderr: cause.snapshot.stderr.text,
|
||||
});
|
||||
if (attributed.stage === "limiter") {
|
||||
const reason = `Selected capture limiter ${selectedLimiter} failed before starting ${command}: ${diagnostic}`;
|
||||
throw new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
operation,
|
||||
reason,
|
||||
{
|
||||
...details,
|
||||
userMessage: `${reason} ${PCAP_LIMITER_REMEDIATION}`,
|
||||
remediationAction: PCAP_LIMITER_REMEDIATION,
|
||||
},
|
||||
);
|
||||
}
|
||||
if (attributed.stage === "tool-launch")
|
||||
throw pcapToolUnavailable(
|
||||
operation,
|
||||
attributed.refusal === "missing"
|
||||
? `Selected tool ${command} was not found: ${diagnostic}`
|
||||
: `Selected tool ${command} exists but could not be executed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
// Otherwise prlimit started the tool; its exit and output are the tool's.
|
||||
const outcome = providerOutcomeOf(cause);
|
||||
if (outcome === undefined) {
|
||||
const diagnostic = cause instanceof Error ? cause.message : String(cause);
|
||||
const details = { cause, ...cleanupDetails };
|
||||
throw commandAttempted
|
||||
? pcapToolFailure(diagnostic, details)
|
||||
: preparationFailure(diagnostic, details);
|
||||
}
|
||||
if (options.inputPath === undefined)
|
||||
throw pcapToolUnavailable(
|
||||
operation,
|
||||
`The selected tool ${command} cannot report its version: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
if (
|
||||
options.inputPath !== undefined &&
|
||||
/not a capture file|file.*isn't a capture file|file format.*not supported/iu.test(
|
||||
diagnostic,
|
||||
)
|
||||
)
|
||||
throw new AnalysisUnsupportedTargetError(
|
||||
operation,
|
||||
options.inputPath,
|
||||
diagnostic,
|
||||
details,
|
||||
);
|
||||
throw new AnalysisProtocolError(
|
||||
`Packet capture tool ${command} failed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
throw classifyProviderOutcome(outcome, {
|
||||
operation,
|
||||
capturedOutput: captureDiagnostic,
|
||||
details: cleanupDetails,
|
||||
timeout: { ms: limits.timeoutMs },
|
||||
outputLimit: {
|
||||
limits: { max_output_bytes: limits.maxOutputBytes },
|
||||
recovery: fixedAllowanceOptions(
|
||||
"The packet-tool output capture allowance",
|
||||
"capture",
|
||||
),
|
||||
},
|
||||
memoryLimitBytes: options.nativeBound?.memoryLimitBytes,
|
||||
dialect: (failure, details) => {
|
||||
if (
|
||||
failure.kind === "launch-refused" &&
|
||||
refusedByLaunchedPath(failure.cause)
|
||||
) {
|
||||
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})`,
|
||||
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(
|
||||
`The bounded packet command failed before its exit was observed; whether the limiter or selected tool failed is unknown: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
const attributed = attributePcapLimitedExit(selectedLimiter, {
|
||||
exitCode: failure.exitCode,
|
||||
signal: failure.signal,
|
||||
stderr: failure.output.snapshot.stderr.text,
|
||||
});
|
||||
if (attributed.stage === "limiter") {
|
||||
const reason = `Selected capture limiter ${selectedLimiter} failed before starting ${command}: ${diagnostic}`;
|
||||
return new AnalysisCapabilityUnavailableError(
|
||||
"pcap",
|
||||
operation,
|
||||
reason,
|
||||
{
|
||||
...details,
|
||||
userMessage: `${reason} ${PCAP_LIMITER_REMEDIATION}`,
|
||||
remediationAction: PCAP_LIMITER_REMEDIATION,
|
||||
},
|
||||
);
|
||||
}
|
||||
if (attributed.stage === "tool-launch")
|
||||
return pcapToolUnavailable(
|
||||
operation,
|
||||
attributed.refusal === "missing"
|
||||
? `Selected tool ${command} was not found: ${diagnostic}`
|
||||
: `Selected tool ${command} exists but could not be executed: ${diagnostic}`,
|
||||
details,
|
||||
);
|
||||
// Otherwise prlimit started the tool; its exit and output are the tool's.
|
||||
}
|
||||
return pcapToolFailure(diagnostic, details);
|
||||
},
|
||||
});
|
||||
}
|
||||
};
|
||||
@@ -23,7 +23,6 @@ import {
|
||||
AnalysisInputError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisOutputError,
|
||||
AnalysisTimeoutError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
||||
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
@@ -45,6 +44,8 @@ import type {
|
||||
ProviderProcessSupervisor,
|
||||
} from "./ProviderProcess.js";
|
||||
import { OwnedCommandFailure, ownedCommandResources } from "./OwnedCommand.js";
|
||||
import { providerOutcomeOf } from "./ProviderOutcome.js";
|
||||
import { classifyProviderOutcome } from "./classifyProviderOutcome.js";
|
||||
import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js";
|
||||
|
||||
/** Limitations shared by resource-limited artifact producer observations. */
|
||||
@@ -515,38 +516,21 @@ export class ArtifactAnalysisResources {
|
||||
operation = this.operation,
|
||||
budgetParameter?: "producer_limits",
|
||||
): AnalysisError {
|
||||
const capturedOutput =
|
||||
cause.snapshot === null
|
||||
? undefined
|
||||
: artifactCommandOutput(cause.snapshot);
|
||||
const detail = {
|
||||
cause,
|
||||
...(capturedOutput === undefined ? {} : { capturedOutput }),
|
||||
};
|
||||
if (cause.reason === "cancelled")
|
||||
return new AnalysisCancelledError(operation, {
|
||||
...detail,
|
||||
cause:
|
||||
cause.cancellation === undefined ? cause : cause.cancellation.reason,
|
||||
});
|
||||
if (cause.reason === "timeout")
|
||||
return new AnalysisTimeoutError(operation, limits.command_timeout_ms, {
|
||||
...detail,
|
||||
return classifyProviderOutcome(providerOutcomeOf(cause), {
|
||||
operation,
|
||||
capturedOutput: artifactCommandOutput,
|
||||
timeout: {
|
||||
ms: limits.command_timeout_ms,
|
||||
userMessage: `The owned producer command reached its ${String(limits.command_timeout_ms)} ms deadline. This is not a client-side timeout; extending only the MCP client's deadline does not change this budget.`,
|
||||
remediationAction:
|
||||
budgetParameter === undefined
|
||||
? `REA's fixed producer command deadline is ${String(limits.command_timeout_ms)} ms and this release has no runtime override. Inspect any partial output and cleanup before retrying. Repeating the unchanged request reaches the same deadline.`
|
||||
: `${limits.command_timeout_ms < MAX_NODE_TIMER_DELAY_MS ? `Increase ${budgetParameter}.command_timeout_ms above ${String(limits.command_timeout_ms)} milliseconds on the next call (range 1..${String(MAX_NODE_TIMER_DELAY_MS)}); no restart is required.` : `${budgetParameter}.command_timeout_ms is already at the runtime timer maximum ${String(MAX_NODE_TIMER_DELAY_MS)} milliseconds; no higher deadline is supported. Narrow the selected work if that preserves the required observation.`} Inspect retained observations and confirm cleanup before retrying. This does not raise CPU, memory, output, parser or external client limits.`,
|
||||
});
|
||||
if (cause.reason === "output-limit")
|
||||
return new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
cause.message,
|
||||
{ output_bytes: limits.output_bytes },
|
||||
{
|
||||
...detail,
|
||||
...(budgetParameter === undefined
|
||||
},
|
||||
outputLimit: {
|
||||
limits: { output_bytes: limits.output_bytes },
|
||||
recovery:
|
||||
budgetParameter === undefined
|
||||
? fixedAllowanceOptions(
|
||||
`The retained command-output allowance of ${String(limits.output_bytes)} bytes (this release has no runtime override)`,
|
||||
"capture",
|
||||
@@ -554,34 +538,26 @@ export class ArtifactAnalysisResources {
|
||||
: {
|
||||
retryable: false,
|
||||
remediationAction: `Increase ${budgetParameter}.output_bytes above ${String(limits.output_bytes)} bytes on the next call; no restart is required. Inspect captured output and confirm cleanup before retrying. This controls collection, not parser, transport, host memory or inherited OS limits. Repeating the unchanged request cannot raise it.`,
|
||||
}),
|
||||
},
|
||||
);
|
||||
if (
|
||||
cause.reason === "process" &&
|
||||
(cause.snapshot?.signal === "SIGXFSZ" ||
|
||||
cause.snapshot?.signal === "SIGXCPU")
|
||||
) {
|
||||
const signal = cause.snapshot.signal;
|
||||
const reported =
|
||||
effectiveLimits === undefined
|
||||
? "The effective inherited limit was not reported."
|
||||
: `The effective inherited limits are ${String(effectiveLimits.address_space_bytes)} bytes of address space, ${String(effectiveLimits.file_bytes)} bytes per file, and ${String(effectiveLimits.cpu_seconds)} CPU seconds.`;
|
||||
// A producer can raise SIGXCPU/SIGXFSZ without exhausting the retained
|
||||
// rlimit, so an unchanged retry is not a proven failure.
|
||||
return new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
signal === "SIGXFSZ" ? "file-size" : "cpu",
|
||||
`Producer terminated with ${signal}; the signal's exact cause is not independently established.`,
|
||||
effectiveLimits === undefined ? null : { ...effectiveLimits },
|
||||
{
|
||||
...detail,
|
||||
retryable: true,
|
||||
remediationAction: `${reported} REA retains the tighter inherited limit. ${budgetParameter === undefined ? "This release has no runtime override for that ceiling." : `Review ${budgetParameter}.${signal === "SIGXFSZ" ? "file_bytes" : "cpu_seconds"} for a new call; a higher requested policy cannot raise a tighter inherited soft or hard limit. No REA restart is needed for a per-call update.`} A smaller artifact may finish inside the retained limit. The signal does not prove that ceiling was exhausted, so an unchanged retry may succeed or may fail the same way.`,
|
||||
},
|
||||
);
|
||||
}
|
||||
return new AnalysisOutputError(operation, cause.message, detail);
|
||||
},
|
||||
},
|
||||
resourceSignal: (signal) => {
|
||||
const reported =
|
||||
effectiveLimits === undefined
|
||||
? "The effective inherited limit was not reported."
|
||||
: `The effective inherited limits are ${String(effectiveLimits.address_space_bytes)} bytes of address space, ${String(effectiveLimits.file_bytes)} bytes per file, and ${String(effectiveLimits.cpu_seconds)} CPU seconds.`;
|
||||
// A producer can raise SIGXCPU/SIGXFSZ without exhausting the retained
|
||||
// rlimit, so an unchanged retry is not a proven failure.
|
||||
return {
|
||||
limits: effectiveLimits === undefined ? null : { ...effectiveLimits },
|
||||
recovery: {
|
||||
retryable: true,
|
||||
remediationAction: `${reported} REA retains the tighter inherited limit. ${budgetParameter === undefined ? "This release has no runtime override for that ceiling." : `Review ${budgetParameter}.${signal === "SIGXFSZ" ? "file_bytes" : "cpu_seconds"} for a new call; a higher requested policy cannot raise a tighter inherited soft or hard limit. No REA restart is needed for a per-call update.`} A smaller artifact may finish inside the retained limit. The signal does not prove that ceiling was exhausted, so an unchanged retry may succeed or may fail the same way.`,
|
||||
},
|
||||
};
|
||||
},
|
||||
dialect: (outcome, details) =>
|
||||
new AnalysisOutputError(operation, outcome.message, details),
|
||||
});
|
||||
}
|
||||
|
||||
async finish<T>(
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
import { classifyLaunchFailure, type LaunchRefusal } from "./launchFailure.js";
|
||||
import { OwnedCommandFailure } from "./OwnedCommand.js";
|
||||
import type { ProviderProcessSnapshot } from "./ProviderProcess.js";
|
||||
|
||||
/** Output the supervisor retained for one outcome. */
|
||||
export interface ProviderOutcomeOutput {
|
||||
readonly snapshot: ProviderProcessSnapshot;
|
||||
/**
|
||||
* True when the retained output omits bytes: the retention budget was
|
||||
* exceeded or a provider stream was destroyed before it drained.
|
||||
*/
|
||||
readonly truncated: boolean;
|
||||
}
|
||||
|
||||
interface ProviderOutcomeFacts {
|
||||
/** The value the supervisor or launcher threw; kept as the error cause. */
|
||||
readonly cause: unknown;
|
||||
readonly message: string;
|
||||
/** Absent when the failure happened before any process output existed. */
|
||||
readonly output: ProviderOutcomeOutput | undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* What physically happened to one owned provider command, read once from the
|
||||
* supervisor's facts. Classification into a typed error belongs to
|
||||
* `classifyProviderOutcome`.
|
||||
*/
|
||||
export type ProviderOutcome =
|
||||
/** The operating system refused to start the selected executable. */
|
||||
| (ProviderOutcomeFacts & {
|
||||
readonly kind: "launch-refused";
|
||||
readonly refusal: LaunchRefusal;
|
||||
})
|
||||
/** The caller cancelled; `reason` is the caller's opaque abort reason. */
|
||||
| (ProviderOutcomeFacts & {
|
||||
readonly kind: "cancelled";
|
||||
readonly reason: unknown;
|
||||
})
|
||||
/** The owner's deadline elapsed. */
|
||||
| (ProviderOutcomeFacts & { readonly kind: "timeout" })
|
||||
/** Output exceeded the owner's complete-output budget. */
|
||||
| (ProviderOutcomeFacts & { readonly kind: "output-limit" })
|
||||
/** The process tree reached its enforced memory limit. */
|
||||
| (ProviderOutcomeFacts & { readonly kind: "memory-limit" })
|
||||
/** The process ended on an inherited CPU-time or file-size limit signal. */
|
||||
| (ProviderOutcomeFacts & {
|
||||
readonly kind: "resource-signal";
|
||||
readonly signal: "SIGXCPU" | "SIGXFSZ";
|
||||
})
|
||||
/**
|
||||
* The process ended with this status. `stopRequested` is true when the
|
||||
* owner had begun stopping it, so a signal may be the owner's.
|
||||
*/
|
||||
| (ProviderOutcomeFacts & {
|
||||
readonly kind: "exited";
|
||||
readonly exitCode: number | null;
|
||||
readonly signal: NodeJS.Signals | null;
|
||||
readonly stopRequested: boolean;
|
||||
})
|
||||
/** Collecting the command's streams failed, or no process facts exist. */
|
||||
| (ProviderOutcomeFacts & { readonly kind: "protocol" });
|
||||
|
||||
const outputOf = (
|
||||
snapshot: ProviderProcessSnapshot | null,
|
||||
): ProviderOutcomeOutput | undefined =>
|
||||
snapshot === null
|
||||
? undefined
|
||||
: {
|
||||
snapshot,
|
||||
truncated:
|
||||
snapshot.diagnosticTruncated === true ||
|
||||
snapshot.outputIncomplete === true,
|
||||
};
|
||||
|
||||
const ownedCommandOutcome = (failure: OwnedCommandFailure): ProviderOutcome => {
|
||||
const facts = {
|
||||
cause: failure,
|
||||
message: failure.message,
|
||||
output: outputOf(failure.snapshot),
|
||||
};
|
||||
if (failure.reason === "cancelled")
|
||||
return {
|
||||
...facts,
|
||||
kind: "cancelled",
|
||||
reason:
|
||||
failure.cancellation === undefined
|
||||
? failure
|
||||
: failure.cancellation.reason,
|
||||
};
|
||||
// An allocation refused by the enforced limit can surface as a hang, an
|
||||
// overflow or an exit; the limit is the fact that explains each of them.
|
||||
if (failure.snapshot?.memoryLimitReached === true)
|
||||
return { ...facts, kind: "memory-limit" };
|
||||
if (failure.reason !== "process") return { ...facts, kind: failure.reason };
|
||||
const snapshot = failure.snapshot;
|
||||
if (failure.collectionFailure || snapshot === null)
|
||||
return { ...facts, kind: "protocol" };
|
||||
if (snapshot.signal === "SIGXCPU" || snapshot.signal === "SIGXFSZ")
|
||||
return { ...facts, kind: "resource-signal", signal: snapshot.signal };
|
||||
return {
|
||||
...facts,
|
||||
kind: "exited",
|
||||
exitCode: snapshot.exitCode ?? null,
|
||||
signal: snapshot.signal ?? null,
|
||||
stopRequested: snapshot.stopRequested === true,
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
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);
|
||||
const refusal = classifyLaunchFailure(cause);
|
||||
if (refusal === undefined || !(cause instanceof Error)) return undefined;
|
||||
return {
|
||||
kind: "launch-refused",
|
||||
refusal,
|
||||
cause,
|
||||
message: cause.message,
|
||||
output: undefined,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import type {
|
||||
AnalysisCapturedOutput,
|
||||
AnalysisError,
|
||||
AnalysisErrorOptions,
|
||||
} from "../domain/analysisErrorBase.js";
|
||||
import {
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisTimeoutError,
|
||||
cancelledBy,
|
||||
carriedReason,
|
||||
type ResourceConstraintRecovery,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import type { ProviderOutcome } from "./ProviderOutcome.js";
|
||||
import type { ProviderProcessSnapshot } from "./ProviderProcess.js";
|
||||
|
||||
/** Outcomes whose meaning depends on the provider's own dialect. */
|
||||
export type ProviderDialectOutcome = Extract<
|
||||
ProviderOutcome,
|
||||
{ readonly kind: "launch-refused" | "exited" | "protocol" }
|
||||
>;
|
||||
|
||||
type ReportedLimits = Readonly<Record<string, JsonValue>> | null;
|
||||
|
||||
/** What one provider command needs to turn its outcome into a typed error. */
|
||||
export interface ProviderOutcomeContext {
|
||||
readonly operation: string;
|
||||
/** The provider's redacted projection of retained output. */
|
||||
readonly capturedOutput: (
|
||||
snapshot: ProviderProcessSnapshot,
|
||||
) => AnalysisCapturedOutput;
|
||||
/** Options every classified error carries, such as retained cleanup. */
|
||||
readonly details?: AnalysisErrorOptions;
|
||||
readonly timeout: {
|
||||
readonly ms: number;
|
||||
/** Which deadline elapsed, when the generic timeout text is not enough. */
|
||||
readonly userMessage?: string;
|
||||
/** The setting or action that changes that deadline. */
|
||||
readonly remediationAction?: string;
|
||||
};
|
||||
readonly outputLimit: {
|
||||
readonly limits: ReportedLimits;
|
||||
readonly recovery: ResourceConstraintRecovery;
|
||||
};
|
||||
/** The enforced process-tree memory limit, when one was requested. */
|
||||
readonly memoryLimitBytes?: number | undefined;
|
||||
/** Reported limits and recovery for an inherited CPU or file-size signal. */
|
||||
readonly resourceSignal?: (signal: "SIGXCPU" | "SIGXFSZ") => {
|
||||
readonly limits: ReportedLimits;
|
||||
readonly recovery: ResourceConstraintRecovery;
|
||||
};
|
||||
/** Provider-specific meaning of a launch refusal, an exit, or a stream failure. */
|
||||
readonly dialect: (
|
||||
outcome: ProviderDialectOutcome,
|
||||
details: AnalysisErrorOptions,
|
||||
) => AnalysisError;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
export const classifyProviderOutcome = (
|
||||
outcome: ProviderOutcome,
|
||||
context: ProviderOutcomeContext,
|
||||
): AnalysisError => {
|
||||
const { operation } = context;
|
||||
const details: AnalysisErrorOptions = {
|
||||
...context.details,
|
||||
cause: outcome.cause,
|
||||
...(outcome.output === undefined
|
||||
? {}
|
||||
: { capturedOutput: context.capturedOutput(outcome.output.snapshot) }),
|
||||
};
|
||||
switch (outcome.kind) {
|
||||
case "cancelled": {
|
||||
// The caller's abort reason is the cancellation's cause; the outcome's
|
||||
// own cause is the supervisor failure that observed it.
|
||||
const { cause: _observed, ...cancellationDetails } = details;
|
||||
return cancelledBy(
|
||||
operation,
|
||||
carriedReason(outcome.reason),
|
||||
cancellationDetails,
|
||||
);
|
||||
}
|
||||
case "timeout":
|
||||
return new AnalysisTimeoutError(operation, context.timeout.ms, {
|
||||
...details,
|
||||
...(context.timeout.userMessage === undefined
|
||||
? {}
|
||||
: { userMessage: context.timeout.userMessage }),
|
||||
...(context.timeout.remediationAction === undefined
|
||||
? {}
|
||||
: { remediationAction: context.timeout.remediationAction }),
|
||||
});
|
||||
case "output-limit":
|
||||
return new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
outcome.message,
|
||||
context.outputLimit.limits,
|
||||
{ ...details, ...context.outputLimit.recovery },
|
||||
);
|
||||
case "memory-limit":
|
||||
return new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
"memory",
|
||||
"The owned process tree reached its enforced committed-memory limit.",
|
||||
{ process_memory_limit_bytes: context.memoryLimitBytes ?? null },
|
||||
details,
|
||||
);
|
||||
case "resource-signal": {
|
||||
const reported = context.resourceSignal?.(outcome.signal);
|
||||
return new AnalysisResourceConstraintError(
|
||||
operation,
|
||||
outcome.signal === "SIGXFSZ" ? "file-size" : "cpu",
|
||||
`Producer terminated with ${outcome.signal}; the signal's exact cause is not independently established.`,
|
||||
reported?.limits ?? null,
|
||||
{ ...details, ...reported?.recovery },
|
||||
);
|
||||
}
|
||||
case "launch-refused":
|
||||
case "exited":
|
||||
case "protocol":
|
||||
return context.dialect(outcome, details);
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,185 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { beforeAll, expect, it } from "vitest";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisResourceConstraintError,
|
||||
AnalysisTimeoutError,
|
||||
AnalysisUnsupportedTargetError,
|
||||
} from "../../../src/domain/analysisErrorCore.js";
|
||||
import { runPcapCommand } from "../../../src/pcap/PcapCommand.js";
|
||||
import { runOwnedCommand } from "../../../src/process/OwnedCommand.js";
|
||||
import { prepareProcessOwnershipInspection } from "../../../src/process/ProcessOwnershipObservation.js";
|
||||
import { providerOutcomeOf } from "../../../src/process/ProviderOutcome.js";
|
||||
|
||||
const node = (script: string) => ({
|
||||
command: process.execPath,
|
||||
arguments: ["-e", script],
|
||||
runId: `rea-provider-outcome-test-${randomUUID()}`,
|
||||
});
|
||||
|
||||
const outcomeOf = async (
|
||||
spawn: ReturnType<typeof node>,
|
||||
limits: { readonly timeoutMs: number; readonly diagnosticBytes: number },
|
||||
signal?: AbortSignal,
|
||||
) => {
|
||||
const failure = await runOwnedCommand(
|
||||
spawn,
|
||||
limits,
|
||||
signal === undefined ? {} : { signal },
|
||||
).then(
|
||||
() => {
|
||||
throw new Error("The command was expected to fail");
|
||||
},
|
||||
(cause: unknown) => cause,
|
||||
);
|
||||
return providerOutcomeOf(failure);
|
||||
};
|
||||
|
||||
beforeAll(() => prepareProcessOwnershipInspection());
|
||||
|
||||
it("reads a nonzero exit with its retained output and the owner's stop state", async () => {
|
||||
const outcome = await outcomeOf(
|
||||
node('process.stderr.write("refused"); process.exitCode = 3'),
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
|
||||
);
|
||||
expect(outcome).toMatchObject({
|
||||
kind: "exited",
|
||||
exitCode: 3,
|
||||
signal: null,
|
||||
stopRequested: false,
|
||||
output: { truncated: false, snapshot: { stderr: { text: "refused" } } },
|
||||
});
|
||||
});
|
||||
|
||||
it("reads the owner's deadline, not the stop it sent, as the outcome", async () => {
|
||||
const outcome = await outcomeOf(node("setInterval(() => {}, 1000)"), {
|
||||
timeoutMs: 100,
|
||||
diagnosticBytes: 1024,
|
||||
});
|
||||
expect(outcome).toMatchObject({ kind: "timeout" });
|
||||
});
|
||||
|
||||
it("reads an exceeded complete-output budget as truncated output", async () => {
|
||||
const outcome = await outcomeOf(
|
||||
node('process.stderr.write("x".repeat(4096)); setInterval(() => {}, 1000)'),
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 64 },
|
||||
);
|
||||
expect(outcome).toMatchObject({ kind: "output-limit" });
|
||||
});
|
||||
|
||||
it("keeps the caller's opaque cancellation reason", async () => {
|
||||
const controller = new AbortController();
|
||||
const reason = { request: "caller cancel" };
|
||||
const running = outcomeOf(
|
||||
node("setInterval(() => {}, 1000)"),
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
|
||||
controller.signal,
|
||||
);
|
||||
setTimeout(() => controller.abort(reason), 50);
|
||||
const outcome = await running;
|
||||
expect(outcome?.kind).toBe("cancelled");
|
||||
expect(outcome?.kind === "cancelled" ? outcome.reason : undefined).toBe(
|
||||
reason,
|
||||
);
|
||||
});
|
||||
|
||||
it("reads a refused launch with the operating system's code", async () => {
|
||||
const outcome = await outcomeOf(
|
||||
{
|
||||
...node(""),
|
||||
command: `/nonexistent-${randomUUID()}/tool`,
|
||||
arguments: [],
|
||||
},
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
|
||||
);
|
||||
expect(outcome).toMatchObject({
|
||||
kind: "launch-refused",
|
||||
refusal: { kind: "missing", code: "ENOENT" },
|
||||
output: undefined,
|
||||
});
|
||||
});
|
||||
|
||||
it("is undefined for a failure that is not an owned command outcome", () => {
|
||||
expect(providerOutcomeOf(new Error("parse failure"))).toBeUndefined();
|
||||
});
|
||||
|
||||
it.skipIf(process.platform === "win32")(
|
||||
"reads an inherited resource-limit signal separately from an ordinary exit",
|
||||
async () => {
|
||||
const outcome = await outcomeOf(
|
||||
node('process.kill(process.pid, "SIGXCPU")'),
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 1024 },
|
||||
);
|
||||
expect(outcome).toMatchObject({
|
||||
kind: "resource-signal",
|
||||
signal: "SIGXCPU",
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
const readCapture = (
|
||||
script: string,
|
||||
limits = { timeoutMs: 10_000, maxOutputBytes: 1024 },
|
||||
) =>
|
||||
runPcapCommand({
|
||||
operation: "inspect_pcap_capture",
|
||||
command: process.execPath,
|
||||
arguments: ["-e", script],
|
||||
inputPath: "/authored-capture.pcap",
|
||||
limits,
|
||||
environment: {},
|
||||
signal: undefined,
|
||||
retain: () => {
|
||||
throw new Error("No cleanup is retained");
|
||||
},
|
||||
}).catch((cause: unknown) => cause);
|
||||
|
||||
it("classifies each owner-observed outcome once for a provider command", async () => {
|
||||
const timeout = await readCapture("setInterval(() => {}, 1000)", {
|
||||
timeoutMs: 100,
|
||||
maxOutputBytes: 1024,
|
||||
});
|
||||
expect(timeout).toBeInstanceOf(AnalysisTimeoutError);
|
||||
expect(timeout).toMatchObject({ timeoutMs: 100 });
|
||||
|
||||
const overflow = await readCapture(
|
||||
'process.stderr.write("x".repeat(4096)); setInterval(() => {}, 1000)',
|
||||
{ timeoutMs: 10_000, maxOutputBytes: 64 },
|
||||
);
|
||||
expect(overflow).toBeInstanceOf(AnalysisResourceConstraintError);
|
||||
expect(overflow).toMatchObject({
|
||||
reportedLimits: { max_output_bytes: 64 },
|
||||
fixedAllowance: { kind: "capture" },
|
||||
});
|
||||
});
|
||||
|
||||
it("leaves an exit's meaning to the provider dialect", async () => {
|
||||
const failure = await readCapture(
|
||||
'process.stderr.write("The file is not a capture file"); process.exitCode = 2',
|
||||
);
|
||||
expect(failure).toBeInstanceOf(AnalysisUnsupportedTargetError);
|
||||
expect(failure).toMatchObject({
|
||||
capturedOutput: { stderr: expect.stringContaining("not a capture file") },
|
||||
});
|
||||
});
|
||||
|
||||
it("classifies a caller cancellation through the shared owner", async () => {
|
||||
const controller = new AbortController();
|
||||
const reason = { request: "caller cancel" };
|
||||
const running = runPcapCommand({
|
||||
operation: "inspect_pcap_capture",
|
||||
command: process.execPath,
|
||||
arguments: ["-e", "setInterval(() => {}, 1000)"],
|
||||
inputPath: "/authored-capture.pcap",
|
||||
limits: { timeoutMs: 10_000, maxOutputBytes: 1024 },
|
||||
environment: {},
|
||||
signal: controller.signal,
|
||||
retain: () => {
|
||||
throw new Error("No cleanup is retained");
|
||||
},
|
||||
}).catch((cause: unknown) => cause);
|
||||
setTimeout(() => controller.abort(reason), 50);
|
||||
const failure = await running;
|
||||
expect(failure).toBeInstanceOf(AnalysisCancelledError);
|
||||
expect((failure as AnalysisCancelledError).cause).toBe(reason);
|
||||
});
|
||||
@@ -0,0 +1,68 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { RuleTester } from "oxlint/plugins-dev";
|
||||
import rule from "../../scripts/lint/rules/provider-failure-classifier.mjs";
|
||||
|
||||
/** A baselined file allowed exactly one per-site classifier. */
|
||||
const baselinedFile = fileURLToPath(
|
||||
new URL("../../src/adb/AdbProvider.ts", import.meta.url),
|
||||
);
|
||||
const classifier = "const failure = (cause: unknown): AnalysisError => error;";
|
||||
|
||||
RuleTester.describe = describe;
|
||||
RuleTester.it = it;
|
||||
|
||||
new RuleTester({ languageOptions: { parserOptions: { lang: "ts" } } }).run(
|
||||
"provider-failure-classifier",
|
||||
rule,
|
||||
{
|
||||
valid: [
|
||||
"const classify = (outcome: ProviderOutcome): AnalysisError => error;",
|
||||
"const message = (cause: unknown): string => String(cause);",
|
||||
"const recover = (cause: unknown): Result<number, AnalysisError> => ok(1);",
|
||||
"function dialect(outcome: ProviderDialectOutcome, details: AnalysisErrorOptions): AnalysisError { return error; }",
|
||||
{ code: classifier, filename: baselinedFile },
|
||||
],
|
||||
invalid: [
|
||||
{
|
||||
code: "const failure = (cause: unknown): AnalysisError => error;",
|
||||
errors: [{ messageId: "classifier" }],
|
||||
},
|
||||
{
|
||||
code: "function failure(operation: string, cause: unknown): AnalysisError | undefined { return undefined; }",
|
||||
errors: [{ messageId: "classifier" }],
|
||||
},
|
||||
{
|
||||
code: "class Provider { failure(cause: unknown, phase = 'read'): AnalysisError { return error; } }",
|
||||
errors: [{ messageId: "classifier" }],
|
||||
},
|
||||
{
|
||||
code: `${classifier}\n${classifier.replace("failure", "second")}`,
|
||||
filename: baselinedFile,
|
||||
errors: [{ messageId: "classifier" }, { messageId: "classifier" }],
|
||||
},
|
||||
{
|
||||
code: "const message = (cause: unknown): string => String(cause);",
|
||||
filename: baselinedFile,
|
||||
errors: [{ messageId: "stale", data: { allowed: "1", actual: "0" } }],
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
|
||||
it("keeps the classifier baseline to existing source files", async () => {
|
||||
const baseline = JSON.parse(
|
||||
await readFile(
|
||||
"scripts/lint/rules/provider-failure-classifier-baseline.json",
|
||||
"utf8",
|
||||
),
|
||||
) as Record<string, number>;
|
||||
for (const [file, count] of Object.entries(baseline)) {
|
||||
expect(file).toMatch(/^src\/.+\.ts$/u);
|
||||
expect(count).toBeGreaterThan(0);
|
||||
// The lint run reports an entry above a file's real count as stale; this
|
||||
// catches entries whose file no longer exists, which lint never visits.
|
||||
await expect(readFile(file, "utf8")).resolves.toBeTypeOf("string");
|
||||
}
|
||||
});
|
||||
Reference in new issue
Block a user