diff --git a/.oxlintrc.json b/.oxlintrc.json index 7f9f60d76e..62da245d22 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -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", diff --git a/docs/development/tool-design.md b/docs/development/tool-design.md index 3b77a73bde..569143d82e 100644 --- a/docs/development/tool-design.md +++ b/docs/development/tool-design.md @@ -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 diff --git a/scripts/lint/index.mjs b/scripts/lint/index.mjs index 6d47f85116..81f569f10e 100644 --- a/scripts/lint/index.mjs +++ b/scripts/lint/index.mjs @@ -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, }, }; diff --git a/scripts/lint/rules/provider-failure-classifier-baseline.json b/scripts/lint/rules/provider-failure-classifier-baseline.json new file mode 100644 index 0000000000..13b0df7c06 --- /dev/null +++ b/scripts/lint/rules/provider-failure-classifier-baseline.json @@ -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 +} diff --git a/scripts/lint/rules/provider-failure-classifier.d.mts b/scripts/lint/rules/provider-failure-classifier.d.mts new file mode 100644 index 0000000000..86d61729e2 --- /dev/null +++ b/scripts/lint/rules/provider-failure-classifier.d.mts @@ -0,0 +1,4 @@ +import type { RuleTester } from "oxlint/plugins-dev"; + +declare const rule: Parameters[1]; +export default rule; diff --git a/scripts/lint/rules/provider-failure-classifier.mjs b/scripts/lint/rules/provider-failure-classifier.mjs new file mode 100644 index 0000000000..fb528d87b6 --- /dev/null +++ b/scripts/lint/rules/provider-failure-classifier.mjs @@ -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), + }, + }); + }, + }; + }, +}; diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index 1aacd6efda..04c2289c01 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -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, diff --git a/src/pcap/PcapCommand.ts b/src/pcap/PcapCommand.ts index a91bbd0254..7078062b0b 100644 --- a/src/pcap/PcapCommand.ts +++ b/src/pcap/PcapCommand.ts @@ -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); + }, + }); } }; diff --git a/src/process/ArtifactAnalysisResources.ts b/src/process/ArtifactAnalysisResources.ts index 7dc07a2dc3..08bca13bab 100644 --- a/src/process/ArtifactAnalysisResources.ts +++ b/src/process/ArtifactAnalysisResources.ts @@ -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( diff --git a/src/process/ProviderOutcome.ts b/src/process/ProviderOutcome.ts new file mode 100644 index 0000000000..0c81dd623e --- /dev/null +++ b/src/process/ProviderOutcome.ts @@ -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, + }; +} diff --git a/src/process/classifyProviderOutcome.ts b/src/process/classifyProviderOutcome.ts new file mode 100644 index 0000000000..b151516103 --- /dev/null +++ b/src/process/classifyProviderOutcome.ts @@ -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> | 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); + } +}; diff --git a/tests/boundary/process/providerOutcome.test.ts b/tests/boundary/process/providerOutcome.test.ts new file mode 100644 index 0000000000..3d508d4830 --- /dev/null +++ b/tests/boundary/process/providerOutcome.test.ts @@ -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, + 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); +}); diff --git a/tests/evaluation/providerFailureClassifierRule.test.ts b/tests/evaluation/providerFailureClassifierRule.test.ts new file mode 100644 index 0000000000..13e64e4b2c --- /dev/null +++ b/tests/evaluation/providerFailureClassifierRule.test.ts @@ -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 => 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; + 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"); + } +});