fix(source-maps): preserve physical codec launch failures during cancellation (#12579)

* fix(source-maps): classify launch failure by process owner

* fix(source-maps): retain preparation cleanup ownership during cancellation (#12582)

fix(source-maps): preserve ownership preparation failure origins
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 23:49:00 +00:00
1 parent 184ed690d6
commit 8f72740592
4 files changed
+206 -105

No files matched your search

@@ -6,6 +6,7 @@ import * as processOutput from "../../process/ExecFileOutput.js";
import {
AnalysisCancelledError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "../../domain/analysisErrorCore.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import {
@@ -17,6 +18,7 @@ import {
spawnOwnedProviderProcess,
} from "../../process/ProviderProcess.js";
import { WEB_SOURCE_MAP_LIMITS } from "../../domain/sourceMapLimits.js";
import { WindowsNativeControlUnavailableError } from "../../windows/WindowsOwnedProcess.js";
import type { WebSourceMapReport } from "../../domain/webSourceLocation.js";
import { traceSourceMap } from "./TraceSourceMap.js";
import {
@@ -413,3 +415,71 @@ it.each([
}
},
);
it.each([
[
"physical OS spawn error",
Object.assign(new Error("spawn resource unavailable"), { code: "EAGAIN" }),
"ProviderAdapterError",
],
[
"Windows memory capability refusal",
new WindowsNativeControlUnavailableError("job-memory-limit"),
"AnalysisCapabilityUnavailableError",
],
] as const)(
"keeps a %s alongside caller cancellation",
async (_name, physical, errorTag) => {
const controller = new AbortController();
const reason = { caller: "during process spawn" };
const result = await runSourceMapCommand(
"{}",
"/probe/source.map",
{ signal: controller.signal },
{
prepareOwnership: async () => {},
launcher: async () => {
controller.abort(reason);
throw physical;
},
},
unexpectedCleanup,
);
if (result.ok) throw new Error("expected launch rejection");
expect(result.error._tag).toBe(errorTag);
expect(result.error.cause).toBe(physical);
expect(result.error.secondaryFailures).toHaveLength(1);
expect(result.error.secondaryFailures[0]).toBeInstanceOf(
AnalysisCancelledError,
);
expect(result.error.secondaryFailures[0]?.cause).toBe(reason);
},
);
it("keeps an observed launcher interruption at the codec deadline a timeout", async () => {
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance"] });
try {
const result = await runSourceMapCommand(
"{}",
"/probe/source.map",
undefined,
{
prepareOwnership: async () => {},
launcher: async ({ signal }) => {
await vi.advanceTimersByTimeAsync(1000);
assertProcessOwnershipInspectionActive(signal);
throw new Error(
"expected the codec deadline to interrupt the launcher",
);
},
},
unexpectedCleanup,
1000,
);
if (result.ok) throw new Error("expected launch timeout");
expect(result.error).toBeInstanceOf(AnalysisTimeoutError);
expect(result.error.secondaryFailures).toHaveLength(0);
} finally {
vi.useRealTimers();
}
});
+73 -50
View File
@@ -23,7 +23,7 @@ import {
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 { err, ok, type Result } from "../../domain/result.js";
import {
DEFAULT_WEB_SOURCE_MAP_DECODE_TIMEOUT_MS,
webSourceMapDecodeTimeoutRecovery,
@@ -32,7 +32,7 @@ import {
import { parseSourceMapReply } from "./SourceMapReply.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import { DarwinProcessOwnershipInspectionError } from "../../process/DarwinProcessRunTokenReader.js";
import { ProcessAdmissionError } from "../../process/ProcessAdmissionError.js";
import { isProcessOwnershipInspectionCancellation } from "../../process/ProcessInspectionCancellation.js";
import {
RuntimeControlUnavailableError,
runtimeControlCapabilityError,
@@ -50,6 +50,10 @@ import {
} from "../../process/ProviderProcess.js";
import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
import { capturedProviderOutput } from "../../process/capturedProviderOutput.js";
import {
classifyProviderFailure,
type ProviderFailureDialect,
} from "../../providers/classifyProviderFailure.js";
import { errorMessage } from "../../kernel/errorMessage.js";
const OPERATION = "trace_web_source_location";
@@ -68,7 +72,7 @@ export interface SourceMapDecoderDependencies {
readonly launcher?: SourceMapCodecLauncher;
readonly createRuntime?: () => Promise<SourceMapCodecRuntime>;
readonly environment?: Readonly<NodeJS.ProcessEnv>;
/** Prepare host ownership inspection outside the codec execution deadline. */
/** Prepare host inspection outside the codec deadline, using its typed cancellation outcome. */
readonly prepareOwnership?: (signal?: AbortSignal) => Promise<void>;
}
@@ -126,35 +130,31 @@ export const runSourceMapCommand = async (
} 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 cancellation = isProcessOwnershipInspectionCancellation(cause)
? cause
: preparation?.cancellation;
const failure =
cancellation !== undefined
? cancelledBy(OPERATION, carriedReason(cancellation.reason))
: 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;
? analysisErrorWithCancellation(failure, cancelledBy(OPERATION, signal))
: failure;
if (preparation?.cleanupFailure === undefined) return err(primary);
const owner = new PreparationCleanup(preparation, path);
retainedCleanup.owner = owner;
@@ -179,13 +179,15 @@ export const runSourceMapCommand = async (
);
let result: Result<WebSourceMapReport, AnalysisError>;
try {
await command.start(request);
result = parseSourceMapReply(
await command.collect(),
path,
javaScriptWorkerMemoryLimitBytes(limits.codecHeapMiB),
limits.codecHeapMiB,
);
const started = await command.start(request);
result = started.ok
? parseSourceMapReply(
await command.collect(),
path,
javaScriptWorkerMemoryLimitBytes(limits.codecHeapMiB),
limits.codecHeapMiB,
)
: started;
} catch (cause: unknown) {
result = err(command.failure(cause));
} finally {
@@ -281,7 +283,7 @@ class OwnedCodec implements SourceMapCleanupOwner {
this.deadline.signal.removeEventListener("abort", this.#onInterruption);
}
async start(request: string): Promise<void> {
async start(request: string): Promise<Result<void, AnalysisError>> {
this.check();
this.#runtime = await (
this.dependencies.createRuntime ??
@@ -300,9 +302,7 @@ class OwnedCodec implements SourceMapCleanupOwner {
UV_THREADPOOL_SIZE: "1",
};
delete environment.NODE_OPTIONS;
const spawned = await (
this.dependencies.launcher ?? spawnOwnedProviderProcess
)({
const launchOptions: OwnedProviderProcessSpawnOptions = {
command: process.execPath,
arguments: [
`--max-old-space-size=${String(this.limits.codecHeapMiB)}`,
@@ -325,7 +325,22 @@ class OwnedCodec implements SourceMapCleanupOwner {
)!,
}),
signal: this.deadline.signal,
});
};
let spawned: SpawnedOwnedProviderProcess;
try {
spawned = await (this.dependencies.launcher ?? spawnOwnedProviderProcess)(
launchOptions,
);
} catch (cause: unknown) {
this.#observeInterruption();
if (this.#outcome?.kind === "timeout") return err(this.failure(cause));
// Only the process owner can say the rejection was caused by cancellation.
return err(
isProcessOwnershipInspectionCancellation(cause)
? cancelledBy(OPERATION, carriedReason(cause.reason))
: classifyProviderFailure(cause, this.#failureDialect()),
);
}
this.#supervisor = new ProviderProcessSupervisor(
{
...spawned,
@@ -368,6 +383,7 @@ class OwnedCodec implements SourceMapCleanupOwner {
},
},
);
return ok(undefined);
}
async collect(): Promise<string> {
@@ -412,11 +428,7 @@ class OwnedCodec implements SourceMapCleanupOwner {
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)
)
if (outcome?.kind === "cancelled")
return cancelledBy(OPERATION, carriedReason(outcome.callerReason));
if (outcome?.kind === "timeout")
return new AnalysisTimeoutError(
@@ -424,16 +436,27 @@ class OwnedCodec implements SourceMapCleanupOwner {
this.decodeTimeoutMs,
webSourceMapDecodeTimeoutRecovery(this.decodeTimeoutMs),
);
if (cause instanceof AnalysisError) return cause;
return cause instanceof RuntimeControlUnavailableError
? runtimeControlCapabilityError(PROVIDER, OPERATION, cause)
: new ProviderAdapterError(PROVIDER, OPERATION, {
return classifyProviderFailure(cause, this.#failureDialect());
}
#failureDialect(): ProviderFailureDialect {
return {
providerId: PROVIDER,
operation: OPERATION,
recognise: (cause) =>
cause instanceof RuntimeControlUnavailableError
? runtimeControlCapabilityError(PROVIDER, OPERATION, cause)
: undefined,
unclassified: (cause, details) =>
new ProviderAdapterError(PROVIDER, OPERATION, {
...details,
cause,
diagnostics: {
map_path: this.path,
error_message: errorMessage(cause),
},
});
}),
};
}
#observeInterruption(): void {
@@ -10,6 +10,7 @@ import {
type SourceMapDecoderDependencies,
} from "./SourceMapCommand.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import { assertProcessOwnershipInspectionActive } from "../../process/ProcessInspectionCancellation.js";
import { spawnOwnedProviderProcess } from "../../process/ProviderProcess.js";
import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
import {
@@ -315,61 +316,67 @@ it("retains cancellation while retrying an earlier failed cleanup", async () =>
}
});
it("retains Darwin preparation cleanup ownership and cancellation through retry", async () => {
const root = await PrivateRuntimeRoot.create({
prefix: "rea-source-map-prep-owner-",
});
const controller = new AbortController();
const reason = { caller: "after preparation failure" };
const cleanup = new ProviderCleanupError("darwin-helper", [root.path], {
reason: "held",
});
let release = false;
const physical = new DarwinProcessOwnershipInspectionError(
"compiler failure",
{
cleanupFailure: cleanup,
cleanupOwner: {
close: async () => {
if (!release) throw new Error("still held");
await root.close();
releaseOwnedCleanup(cleanup);
it.each(["distinct", "shared"] as const)(
"retains physical Darwin preparation and cleanup for a %s caller reason",
async (reasonKind) => {
const root = await PrivateRuntimeRoot.create({
prefix: "rea-source-map-prep-owner-",
});
const controller = new AbortController();
const cleanup = new ProviderCleanupError("darwin-helper", [root.path], {
reason: "held",
});
let release = false;
const physical = new DarwinProcessOwnershipInspectionError(
"compiler failure",
{
cleanupFailure: cleanup,
cleanupOwner: {
close: async () => {
if (!release) throw new Error("still held");
await root.close();
releaseOwnedCleanup(cleanup);
},
},
},
},
);
const decoder = new SourceMapDecoder({
prepareOwnership: async () => {
controller.abort(reason);
throw physical;
},
});
try {
const failed = await decoder.trace(input, { signal: controller.signal });
if (failed.ok) throw new Error("expected failed preparation");
expect(failed.error.cleanupIncomplete).toBe(true);
expect(failed.error.cleanupResources).toContain(root.path);
expect(failed.error.cleanupPrimary?.cause).toBe(physical);
expect(
failed.error.cleanupPrimary?.secondaryFailures.find(
(entry) => entry instanceof AnalysisCancelledError,
)?.cause,
).toBe(reason);
await expect(decoder.close()).rejects.toMatchObject({
cleanupIncomplete: true,
);
const reason =
reasonKind === "shared"
? physical
: { caller: "after preparation failure" };
const decoder = new SourceMapDecoder({
prepareOwnership: async () => {
controller.abort(reason);
throw physical;
},
});
expect(failed.error.cleanupResources).toContain(root.path);
await expect(access(root.path)).resolves.toBeUndefined();
release = true;
await decoder.close();
await expect(access(root.path)).rejects.toMatchObject({ code: "ENOENT" });
expect(failed.error.cleanupIncomplete).toBe(false);
} finally {
release = true;
await decoder.close();
await root.close();
}
});
try {
const failed = await decoder.trace(input, { signal: controller.signal });
if (failed.ok) throw new Error("expected failed preparation");
expect(failed.error.cleanupIncomplete).toBe(true);
expect(failed.error.cleanupResources).toContain(root.path);
expect(failed.error.cleanupPrimary?.cause).toBe(physical);
expect(
failed.error.cleanupPrimary?.secondaryFailures.find(
(entry) => entry instanceof AnalysisCancelledError,
)?.cause,
).toBe(reason);
await expect(decoder.close()).rejects.toMatchObject({
cleanupIncomplete: true,
});
expect(failed.error.cleanupResources).toContain(root.path);
await expect(access(root.path)).resolves.toBeUndefined();
release = true;
await decoder.close();
await expect(access(root.path)).rejects.toMatchObject({ code: "ENOENT" });
expect(failed.error.cleanupIncomplete).toBe(false);
} finally {
release = true;
await decoder.close();
await root.close();
}
},
);
it("does not claim an opaque caller reason's Darwin cleanup owner", async () => {
const controller = new AbortController();
@@ -389,9 +396,9 @@ it("does not claim an opaque caller reason's Darwin cleanup owner", async () =>
},
);
const decoder = new SourceMapDecoder({
prepareOwnership: async () => {
prepareOwnership: async (signal) => {
controller.abort(reason);
throw reason;
assertProcessOwnershipInspectionActive(signal);
},
});
const result = await decoder.trace(input, { signal: controller.signal });
@@ -8,6 +8,7 @@ import { projectAnalysisError } from "../../../src/domain/analysisErrorProjectio
import { SourceMapDecoder } from "../../../src/javascript/sourceMaps/SourceMapDecoder.js";
import type { SourceMapDecoderDependencies } from "../../../src/javascript/sourceMaps/SourceMapCommand.js";
import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";
import { assertProcessOwnershipInspectionActive } from "../../../src/process/ProcessInspectionCancellation.js";
import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";
import { waitForProviderProcessReady } from "../../fixtures/providerProcess.js";
import {
@@ -69,7 +70,7 @@ it.each([
const decoder = realDecoder({
prepareOwnership: async (signal) => {
controller.abort(reason);
signal?.throwIfAborted();
assertProcessOwnershipInspectionActive(signal);
},
createRuntime,
launcher,