Files
reverse-engineering-anything/src/javascript/sourceMaps/SourceMapCommand.ts
T
RRFZ 4c02ceb282 fix(source-maps): preserve launch admission failures during cancellation (#12565)
* fix(source-maps): preserve launch admission failures during cancellation

* fix(source-maps): distinguish launch rejection from observed cancellation
2026-11-19 18:29:28 -05:00

631 lines
22 KiB
TypeScript

import {
WEB_SOURCE_MAP_LIMITS,
sourceMapLimitSelection,
sourceMapLimitRecovery,
type SourceMapLimits,
} from "../../domain/sourceMapLimits.js";
import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisCleanupRelease } from "../../domain/analysisCleanupRelease.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import { analysisErrorWithCancellation } from "../../domain/analysisErrorCancellation.js";
import {
AnalysisOutputError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
cancelledBy,
carriedReason,
} from "../../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { err, type Result } from "../../domain/result.js";
import {
DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS,
webSourceMapDecodeTimeoutRecovery,
type WebSourceMapReport,
} from "../../domain/webSourceLocation.js";
import { parseSourceMapReply } from "./SourceMapReply.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import { DarwinProcessOwnershipInspectionError } from "../../process/DarwinProcessRunTokenReader.js";
import { ProcessAdmissionError } from "../../process/ProcessAdmissionError.js";
import {
RuntimeControlUnavailableError,
runtimeControlCapabilityError,
} from "../../domain/runtimeControlUnavailableError.js";
import { ProviderStartupDeadline } from "../../process/ProviderDeadline.js";
import { javaScriptWorkerMemoryLimitBytes } from "../../process/JavaScriptWorkerMemoryLimit.js";
import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
import {
ProviderProcessSupervisor,
spawnOwnedProviderProcess,
type OwnedProviderProcessSpawnOptions,
type ProviderProcessExitObservation,
type ProviderProcessSnapshot,
type SpawnedOwnedProviderProcess,
} from "../../process/ProviderProcess.js";
import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
import { capturedProviderOutput } from "../../process/capturedProviderOutput.js";
import { errorMessage } from "../../kernel/errorMessage.js";
const OPERATION = "trace_web_source_location";
const PROVIDER = "source-map-decoder";
/** Launcher seam retains the actual codec protocol and ownership supervisor. */
export type SourceMapCodecLauncher = (
options: OwnedProviderProcessSpawnOptions,
) => Promise<SpawnedOwnedProviderProcess>;
/** Runtime implementations establish privacy before returning an owned directory. */
export interface SourceMapCodecRuntime {
readonly path: string;
close(): Promise<void>;
}
/** Replaceable acquisition boundaries for an owned codec operation. */
export interface SourceMapDecoderDependencies {
readonly launcher?: SourceMapCodecLauncher;
readonly createRuntime?: () => Promise<SourceMapCodecRuntime>;
readonly environment?: Readonly<NodeJS.ProcessEnv>;
/** Prepare host ownership inspection outside the codec execution deadline. */
readonly prepareOwnership?: (signal?: AbortSignal) => Promise<void>;
}
export interface SourceMapCleanupOwner {
close(): Promise<ProviderCleanupError | undefined>;
}
/** The caller retains retry authority independently of the returned error. */
export interface SourceMapCleanupRetention {
owner?: SourceMapCleanupOwner | undefined;
}
type CodecPhysicalObservation =
| {
readonly kind: "exit";
readonly exit: ProviderProcessExitObservation;
}
| {
readonly kind: "process-error";
readonly message: string;
readonly cause: Error;
}
| { readonly kind: "output-limit"; readonly stream: "stdout" | "stderr" };
type CodecOutcome =
| {
readonly kind: "physical";
readonly observation: CodecPhysicalObservation;
}
| { readonly kind: "cancelled"; readonly callerReason: unknown }
| { readonly kind: "timeout" };
export class SourceMapCleanupFailure extends ProviderCleanupError {
constructor(
resources: readonly string[],
diagnostics: Readonly<Record<string, JsonValue>>,
) {
super(PROVIDER, resources, diagnostics, { operation: OPERATION });
}
}
/** Interpret a trusted codec reply, then release its process and private root. */
export const runSourceMapCommand = async (
request: string,
path: string,
options: ExecutionOptions | undefined,
dependencies: SourceMapDecoderDependencies,
retainedCleanup: SourceMapCleanupRetention,
decodeTimeoutMs: number = DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS,
limits: SourceMapLimits = WEB_SOURCE_MAP_LIMITS,
): Promise<Result<WebSourceMapReport, AnalysisError>> => {
try {
await (dependencies.prepareOwnership ?? prepareProcessOwnershipInspection)(
options?.signal,
);
} catch (cause: unknown) {
const signal = options?.signal;
const preparation =
cause !== signal?.reason &&
cause instanceof DarwinProcessOwnershipInspectionError
? cause
: undefined;
const knownPhysical =
cause !== signal?.reason &&
(cause instanceof AnalysisError ||
cause instanceof ProcessAdmissionError ||
(preparation !== undefined && preparation.cancellation === undefined));
const physical =
cause instanceof AnalysisError
? cause
: new ProviderAdapterError(PROVIDER, OPERATION, {
cause,
...(preparation?.capturedOutput === undefined
? {}
: { capturedOutput: preparation.capturedOutput }),
diagnostics: {
map_path: path,
error_message: errorMessage(cause),
phase: "process_ownership_preparation",
},
});
const primary = signal?.aborted
? analysisErrorWithCancellation(
knownPhysical ? physical : undefined,
cancelledBy(OPERATION, signal),
)
: physical;
if (preparation?.cleanupFailure === undefined) return err(primary);
const owner = new PreparationCleanup(preparation, path);
retainedCleanup.owner = owner;
return err(
analysisErrorWithCleanupFailure(
primary,
preparation.cleanupFailure,
OPERATION,
).bindCleanupDependencies([preparation.cleanupFailure], owner),
);
}
const deadline = new ProviderStartupDeadline(
decodeTimeoutMs,
options?.signal,
);
const command = new OwnedCodec(
path,
dependencies,
deadline,
decodeTimeoutMs,
limits,
);
let result: Result<WebSourceMapReport, AnalysisError>;
try {
await command.start(request);
result = parseSourceMapReply(
await command.collect(),
path,
javaScriptWorkerMemoryLimitBytes(limits.codecHeapMiB),
limits.codecHeapMiB,
);
} catch (cause: unknown) {
result = err(command.failure(cause));
} finally {
command.dispose();
deadline.dispose();
}
const cleanup = await command.close();
const observation = result.ok ? result.value : undefined;
const completed = options?.signal?.aborted
? err(
analysisErrorWithCancellation(
result.ok ? undefined : result.error,
cancelledBy(OPERATION, options.signal, {
partialObservation: observation,
}),
),
)
: result;
if (cleanup === undefined) return completed;
if (observation !== undefined) cleanup.retainPartialObservation(observation);
retainedCleanup.owner = command;
return completed.ok
? err(cleanup)
: err(
analysisErrorWithCleanupFailure(
completed.error,
cleanup,
OPERATION,
).bindCleanupDependencies([cleanup], command),
);
};
/** Keep the exact Darwin helper owner available after failed preparation cleanup. */
class PreparationCleanup implements SourceMapCleanupOwner {
constructor(
readonly preparation: DarwinProcessOwnershipInspectionError,
readonly path: string,
) {}
get cleanupResources(): readonly string[] {
return this.preparation.cleanupFailure?.cleanupResources ?? [];
}
async close(): Promise<ProviderCleanupError | undefined> {
const cleanup = this.preparation.cleanupFailure;
if (cleanup === undefined || !cleanup.cleanupIncomplete) return undefined;
try {
if (this.preparation.cleanupOwner !== undefined)
await this.preparation.cleanupOwner.close();
} catch (cause: unknown) {
return new SourceMapCleanupFailure(cleanup.cleanupResources, {
map_path: this.path,
cleanup_failures: [errorMessage(cause)],
}).bindCleanupDependencies([cleanup], this);
}
return cleanup.cleanupIncomplete
? new SourceMapCleanupFailure(cleanup.cleanupResources, {
map_path: this.path,
cleanup_failures: [
"Ownership preparation cleanup remains incomplete",
],
}).bindCleanupDependencies([cleanup], this)
: undefined;
}
}
class OwnedCodec implements SourceMapCleanupOwner {
readonly #runId = `rea-source-map-${randomUUID()}`;
#runtime: SourceMapCodecRuntime | undefined;
#supervisor: ProviderProcessSupervisor | undefined;
/** Reported by every close failure until a later close releases the codec. */
#cleanupRelease: AnalysisCleanupRelease | undefined;
#outcome: CodecOutcome | undefined;
#drainStop: CodecPhysicalObservation | undefined;
readonly #onInterruption: () => void;
constructor(
readonly path: string,
readonly dependencies: SourceMapDecoderDependencies,
readonly deadline: ProviderStartupDeadline,
readonly decodeTimeoutMs: number,
readonly limits: SourceMapLimits,
) {
this.#onInterruption = () => this.#observeInterruption();
if (deadline.signal.aborted) this.#observeInterruption();
else
deadline.signal.addEventListener("abort", this.#onInterruption, {
once: true,
});
}
/** Stop recording event order after an outcome has been selected. */
dispose(): void {
this.deadline.signal.removeEventListener("abort", this.#onInterruption);
}
async start(request: string): Promise<void> {
this.check();
this.#runtime = await (
this.dependencies.createRuntime ??
(() => PrivateRuntimeRoot.create({ prefix: "rea-source-map-" }))
)();
this.check();
const requestPath = join(this.#runtime.path, "request.json");
await writeFile(requestPath, request, {
flag: "wx",
mode: 0o600,
signal: this.deadline.signal,
});
this.check();
const environment: NodeJS.ProcessEnv = {
...(this.dependencies.environment ?? process.env),
UV_THREADPOOL_SIZE: "1",
};
delete environment.NODE_OPTIONS;
const spawned = await (
this.dependencies.launcher ?? spawnOwnedProviderProcess
)({
command: process.execPath,
arguments: [
`--max-old-space-size=${String(this.limits.codecHeapMiB)}`,
"--max-semi-space-size=8",
"--v8-pool-size=1",
"--single-threaded",
"--stack_size=2048",
fileURLToPath(new URL("./SourceMapCodecProcess.js", import.meta.url)),
requestPath,
JSON.stringify(sourceMapLimitSelection(this.limits)),
],
runId: this.#runId,
cwd: this.#runtime.path,
hostEnvironment: environment,
...(javaScriptWorkerMemoryLimitBytes(this.limits.codecHeapMiB) === null
? {}
: {
memoryLimitBytes: javaScriptWorkerMemoryLimitBytes(
this.limits.codecHeapMiB,
)!,
}),
signal: this.deadline.signal,
});
this.#supervisor = new ProviderProcessSupervisor(
{
...spawned,
ownsProcessLifetime: true,
cleanup:
spawned.cleanup ??
(() => cleanupOwnedProcessGroup(spawned.ownership)),
},
{
maxDiagnosticBytes: this.limits.outputBytes + 1024 * 1024,
onDiagnostic: (event) => {
if (
event.type === "exit" &&
(event.code !== 0 || event.signal !== null)
)
this.#recordPhysicalFailure({
kind: "exit",
exit: { code: event.code, signal: event.signal },
});
if (event.type === "error") {
this.#recordPhysicalFailure({
kind: "process-error",
message: event.message,
cause: event.cause ?? new Error(event.message),
});
}
if (
event.type === "output" &&
(event.truncated === true ||
event.totalBytes >
(event.stream === "stdout"
? this.limits.outputBytes
: 1024 * 1024))
) {
this.#recordPhysicalFailure({
kind: "output-limit",
stream: event.stream,
});
}
},
},
);
}
async collect(): Promise<string> {
const supervisor = this.#supervisor;
if (supervisor === undefined)
throw new Error("Codec process was not acquired");
while (!(await supervisor.waitForOutputClose(50))) {
const outcome = this.#outcome;
if (
outcome?.kind !== "physical" ||
outcome.observation.kind !== "exit" ||
this.deadline.signal.aborted ||
this.#drainStop !== undefined
)
this.check();
}
this.check();
const snapshot = supervisor.snapshot();
// No partial codec result exists; a reached limit fails the whole trace.
if (snapshot.memoryLimitReached === true)
throw this.#memoryLimitFailure(snapshot);
return snapshot.stdout.text;
}
check(): void {
this.#observeInterruption();
const outcome = this.#outcome;
if (outcome?.kind === "physical")
throw this.#physicalFailure(outcome.observation);
if (outcome?.kind === "cancelled")
throw cancelledBy(OPERATION, carriedReason(outcome.callerReason));
if (outcome?.kind === "timeout")
throw new AnalysisTimeoutError(
OPERATION,
this.decodeTimeoutMs,
webSourceMapDecodeTimeoutRecovery(this.decodeTimeoutMs),
);
}
failure(cause: unknown): AnalysisError {
this.#observeInterruption();
const outcome = this.#outcome;
if (outcome?.kind === "physical")
return this.#physicalFailure(outcome.observation);
// The launcher reports cancellation separately from a physical admission failure.
if (
outcome?.kind === "cancelled" &&
!(cause instanceof ProcessAdmissionError)
)
return cancelledBy(OPERATION, carriedReason(outcome.callerReason));
if (outcome?.kind === "timeout")
return new AnalysisTimeoutError(
OPERATION,
this.decodeTimeoutMs,
webSourceMapDecodeTimeoutRecovery(this.decodeTimeoutMs),
);
if (cause instanceof AnalysisError) return cause;
return cause instanceof RuntimeControlUnavailableError
? runtimeControlCapabilityError(PROVIDER, OPERATION, cause)
: new ProviderAdapterError(PROVIDER, OPERATION, {
cause,
diagnostics: {
map_path: this.path,
error_message: errorMessage(cause),
},
});
}
#observeInterruption(): void {
if (this.#outcome !== undefined) return;
if (!this.deadline.signal.aborted) return;
const interruption = this.deadline.interruption;
if (interruption === undefined) return;
this.#outcome =
interruption === "cancelled"
? { kind: "cancelled", callerReason: this.deadline.signal.reason }
: { kind: "timeout" };
}
#recordPhysicalFailure(observation: CodecPhysicalObservation): void {
this.#observeInterruption();
if (this.#outcome === undefined)
this.#outcome = { kind: "physical", observation };
else if (observation.kind !== "exit" && this.#drainStop === undefined)
this.#drainStop = observation;
}
#physicalFailure(observation: CodecPhysicalObservation): AnalysisError {
const snapshot = this.#supervisor?.snapshot();
if (observation.kind === "exit") {
if (snapshot?.memoryLimitReached === true)
return this.#memoryLimitFailure(snapshot);
return this.#exitFailure(observation.exit, snapshot);
}
if (observation.kind === "process-error")
return this.#processErrorFailure(observation, snapshot);
return this.#outputLimitFailure(snapshot, observation.stream);
}
#exitFailure(
exit: ProviderProcessExitObservation,
snapshot: ProviderProcessSnapshot | undefined,
): AnalysisError {
const outputComplete = this.#supervisor?.observedOutputClose() ?? false;
const capturedOutput = this.#capturedOutput(snapshot, exit, outputComplete);
return new ProviderAdapterError(PROVIDER, OPERATION, {
diagnostics: {
map_path: this.path,
exit_code: exit.code,
signal: exit.signal,
output_complete: outputComplete,
stderr: snapshot?.stderr.text ?? "",
...(this.#drainStop?.kind === "output-limit"
? { output_limit_reached: true }
: {}),
...(this.#drainStop?.kind === "process-error"
? { drain_error_message: this.#drainStop.message }
: {}),
},
...(capturedOutput === undefined ? {} : { capturedOutput }),
});
}
#processErrorFailure(
observation: Extract<CodecPhysicalObservation, { kind: "process-error" }>,
snapshot: ProviderProcessSnapshot | undefined,
): AnalysisError {
const outputComplete = this.#supervisor?.observedOutputClose() ?? false;
const capturedOutput = this.#capturedOutput(
snapshot,
undefined,
outputComplete,
);
return new ProviderAdapterError(PROVIDER, OPERATION, {
cause: observation.cause,
diagnostics: {
map_path: this.path,
error_message: observation.message,
output_complete: outputComplete,
},
...(capturedOutput === undefined ? {} : { capturedOutput }),
});
}
#outputLimitFailure(
snapshot: ProviderProcessSnapshot | undefined,
stream: "stdout" | "stderr",
): AnalysisError {
const outputComplete = this.#supervisor?.observedOutputClose() ?? false;
const capturedOutput = this.#capturedOutput(
snapshot,
undefined,
outputComplete,
);
return new AnalysisOutputError(
OPERATION,
stream === "stdout"
? "Codec output exceeds its complete-evidence budget."
: "Codec diagnostic output exceeds its 1048576-byte allowance.",
{
remediationAction:
stream === "stdout"
? sourceMapLimitRecovery("output_bytes", this.limits.outputBytes)
: "The codec stderr diagnostic allowance is fixed at 1048576 bytes; no source_map_limits field raises it. Inspect retained diagnostics before another call.",
capturedOutput: {
stdout: capturedOutput?.stdout ?? "",
stderr: capturedOutput?.stderr ?? "",
stdout_bytes: capturedOutput?.stdout_bytes ?? 0,
stderr_bytes: capturedOutput?.stderr_bytes ?? 0,
truncated: true,
},
},
);
}
#capturedOutput(
snapshot: ProviderProcessSnapshot | undefined,
exit: ProviderProcessExitObservation | undefined,
outputComplete: boolean,
) {
if (snapshot === undefined) return undefined;
const captured = capturedProviderOutput(
exit === undefined
? snapshot
: { ...snapshot, exitCode: exit.code, signal: exit.signal },
);
return {
...captured,
truncated: captured.truncated || !outputComplete,
};
}
#memoryLimitFailure(snapshot: ProviderProcessSnapshot): AnalysisError {
return new AnalysisResourceConstraintError(
OPERATION,
"memory",
`Source-map codec reached its ${javaScriptWorkerMemoryLimitBytes(this.limits.codecHeapMiB) === null ? "" : `${String(javaScriptWorkerMemoryLimitBytes(this.limits.codecHeapMiB))}-byte `}process memory limit for ${this.path}; no partial evidence was returned. ${sourceMapLimitRecovery("codec_heap_mib", this.limits.codecHeapMiB)}`,
{
codec_process_memory_limit_bytes: javaScriptWorkerMemoryLimitBytes(
this.limits.codecHeapMiB,
),
},
{
capturedOutput: {
stdout: "",
stderr: snapshot.stderr.text,
truncated:
snapshot.diagnosticTruncated === true ||
!(this.#supervisor?.observedOutputClose() ?? false),
},
remediationAction: sourceMapLimitRecovery(
"codec_heap_mib",
this.limits.codecHeapMiB,
),
},
);
}
/** Current ownership, independent of historical cleanup diagnostics. */
get cleanupResources(): readonly string[] {
return [
...(this.#supervisor === undefined ? [] : [this.#runId]),
...(this.#runtime === undefined ? [] : [this.#runtime.path]),
];
}
async close(): Promise<ProviderCleanupError | undefined> {
const failures: string[] = [];
let processReleased = this.#supervisor === undefined;
if (this.#supervisor !== undefined) {
const stopped = await this.#supervisor.stop();
if (stopped.status === "incomplete") failures.push(stopped.reason);
else {
processReleased = true;
this.#supervisor = undefined;
}
}
if (processReleased && this.#runtime !== undefined) {
try {
await this.#runtime.close();
this.#runtime = undefined;
} catch (cause: unknown) {
failures.push(errorMessage(cause));
}
}
if (failures.length === 0) {
this.#cleanupRelease?.confirm();
this.#cleanupRelease = undefined;
return undefined;
}
const failure = new SourceMapCleanupFailure(this.cleanupResources, {
map_path: this.path,
cleanup_failures: failures,
codec_pid: this.#supervisor?.launch.process.pid ?? null,
}).bindCleanupResourceOwner(this);
return (this.#cleanupRelease ??= new AnalysisCleanupRelease()).bind(
failure,
);
}
}