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; /** Runtime implementations establish privacy before returning an owned directory. */ export interface SourceMapCodecRuntime { readonly path: string; close(): Promise; } /** Replaceable acquisition boundaries for an owned codec operation. */ export interface SourceMapDecoderDependencies { readonly launcher?: SourceMapCodecLauncher; readonly createRuntime?: () => Promise; readonly environment?: Readonly; /** Prepare host ownership inspection outside the codec execution deadline. */ readonly prepareOwnership?: (signal?: AbortSignal) => Promise; } export interface SourceMapCleanupOwner { close(): Promise; } /** 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>, ) { 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> => { 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; 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 { 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 { 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 { 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, 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 { 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, ); } }