fix(capture): retain Electron observations and HAR resource failures

This commit is contained in:
morluto
2026-10-09 06:49:02 +08:00
parent 6c13fc8e0a
commit 44fd18305f
27 changed files with 1462 additions and 145 deletions
+19 -42
View File
@@ -103,6 +103,8 @@ const metricSchema = z.strictObject({
const windowMetadataSchema = z.strictObject({
window_id: z.string(),
web_contents_id: z.string(),
url: z.string(),
title: z.string(),
visible: z.boolean().nullable(),
destroyed: z.boolean(),
});
@@ -114,11 +116,6 @@ export type ElectronHookSnapshot = z.infer<typeof hookSnapshotSchema>;
export type ElectronHookEvent = z.infer<typeof hookEventSchema>;
export type ElectronMetrics = z.infer<typeof metricSchema>[];
type ElectronWindowMetadata = z.infer<typeof windowMetadataSchema>;
type ElectronPageSnapshot = {
readonly index: number;
readonly url: string;
readonly title: string;
};
/** Run explicit actions against provider-owned Electron windows. */
export const runElectronActions = async (
@@ -128,12 +125,12 @@ export const runElectronActions = async (
): Promise<ElectronActions> => {
const actions: ElectronActions = [];
for (const action of input.actions) {
if (options.signal?.aborted === true)
throw new BrowserObservationError(OPERATION, "cancelled");
const actionStartedAt = Date.now();
const windowIndex = actionWindowIndex(action);
let selectedWindow: Page | undefined;
try {
if (options.signal?.aborted === true)
throw new BrowserObservationError(OPERATION, "cancelled");
selectedWindow =
windowIndex === null
? undefined
@@ -322,25 +319,23 @@ export const readApplicationState = async (
readonly electronVersion: string;
readonly hookSnapshot: ElectronHookSnapshot;
}> => {
const pages = application.windows();
const pageSnapshotsPromise: Promise<ElectronPageSnapshot[]> = Promise.all(
pages.map(async (page: Page, index): Promise<ElectronPageSnapshot> => ({
index,
url: page.url(),
title: await page.title(),
})),
);
const windowMetadataPromise: Promise<ElectronWindowMetadata[]> = application
.evaluate(({ BrowserWindow }) =>
BrowserWindow.getAllWindows().map(
(window: {
readonly id: number;
readonly webContents: { readonly id: number };
readonly webContents: {
readonly id: number;
getURL(): string;
getTitle(): string;
};
isDestroyed(): boolean;
isVisible(): boolean;
}) => ({
window_id: `window:${String(window.id)}`,
web_contents_id: `webContents:${String(window.webContents.id)}`,
url: window.webContents.getURL(),
title: window.webContents.getTitle(),
visible: window.isDestroyed() ? null : window.isVisible(),
destroyed: window.isDestroyed(),
}),
@@ -392,33 +387,15 @@ export const readApplicationState = async (
};
})
.then((value) => hookSnapshotSchema.parse(value));
const [
pageSnapshots,
windowMetadata,
processMetrics,
electronVersion,
hookSnapshot,
] = await Promise.all([
pageSnapshotsPromise,
windowMetadataPromise,
processMetricsPromise,
electronVersionPromise,
hookSnapshotPromise,
]);
const [windowMetadata, processMetrics, electronVersion, hookSnapshot] =
await Promise.all([
windowMetadataPromise,
processMetricsPromise,
electronVersionPromise,
hookSnapshotPromise,
]);
return {
windows: pageSnapshots.map((page) => {
const metadata = windowMetadata[page.index];
if (metadata === undefined)
throw new BrowserObservationError(OPERATION, "window_metadata_missing");
return {
window_id: metadata.window_id,
web_contents_id: metadata.web_contents_id,
url: page.url,
title: page.title,
visible: metadata.visible,
destroyed: metadata.destroyed,
};
}),
windows: windowMetadata,
metrics: processMetrics,
electronVersion,
hookSnapshot,
@@ -58,7 +58,10 @@ const eventFamily = (
kind: ElectronHookEvent["kind"],
processType: string | null,
): string => {
if (kind === "preload" && processType === "main")
if (
kind === "preload" &&
(processType === "main" || processType === "browser")
)
return "preload-configuration";
if (kind.startsWith("ipc-renderer"))
return processType === "renderer" ? "renderer-ipc" : "ipc";
@@ -163,6 +166,11 @@ export const projectElectronActiveCapture = (
"IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
"The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
"The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
...(!hookSnapshot.events.some(({ kind }) => kind === "preload")
? [
"Preload configuration was not exposed by the observed Electron window metadata. Preload paths and execution remain unavailable.",
]
: []),
"Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
...(hookSnapshot.dropped > 0
? [
+105 -16
View File
@@ -71,6 +71,12 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
let application: ElectronApplication | undefined;
let ownership: OwnedProcessGroup | undefined;
let lineage: ProcessLineageObservation | undefined;
let capture: ElectronActiveObservationResult | undefined;
let paths: ElectronPaths | undefined;
let initialState:
| Awaited<ReturnType<typeof readApplicationState>>
| undefined;
let actions: ElectronActiveObservationResult["actions"] = [];
let outcome: Result<ElectronActiveObservationResult, AnalysisError>;
const runId = randomUUID();
try {
@@ -78,7 +84,7 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
throw new BrowserObservationError(OPERATION, "cancelled");
await prepareProcessOwnershipInspection(options.signal);
const startupDeadline = Date.now() + STARTUP_TIMEOUT_MS;
const paths = await canonicalPaths(input);
paths = await canonicalPaths(input);
const captureBaseline =
await systemProcessOwnershipHost.captureBaseline?.(options.signal);
if (options.signal?.aborted)
@@ -109,24 +115,66 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
sweepTokenOwnedProcesses: true,
...(captureBaseline === undefined ? {} : { captureBaseline }),
};
const actions = await runElectronActions(application, input, options);
lineage = await observeOwnedProcessLineage(ownership);
initialState = await readApplicationState(application);
actions = await runElectronActions(application, input, options);
const state = await runWithExecutionLimits(
readApplicationState(application),
options.signal,
undefined,
options.signal?.aborted ? Date.now() + 5_000 : undefined,
);
outcome = ok(projectElectronActiveCapture(paths, actions, state));
capture = projectElectronActiveCapture(paths, actions, state);
outcome = options.signal?.aborted
? err(
new BrowserObservationError(OPERATION, "cancelled", {
partialObservation: {
kind: "electron-active-observation",
capture,
},
}),
)
: ok(capture);
} catch (cause: unknown) {
if (
options.signal?.aborted &&
paths !== undefined &&
initialState !== undefined
) {
const retainedCapture = projectElectronActiveCapture(
paths,
actions,
initialState,
);
capture = {
...retainedCapture,
limitations: [
...retainedCapture.limitations,
`Final Electron state was unavailable after cancellation: ${cause instanceof Error ? cause.message : String(cause)}. Windows, metrics, IPC, and timeline are the snapshot collected before actions and may omit their effects.`,
],
};
}
outcome = err(
options.signal?.aborted === true &&
(cause === options.signal.reason ||
(cause instanceof Error && cause.name === "AbortError"))
? new BrowserObservationError(OPERATION, "cancelled", { cause })
options.signal?.aborted === true
? new BrowserObservationError(OPERATION, "cancelled", {
cause,
...(capture === undefined
? {}
: {
partialObservation: {
kind: "electron-active-observation" as const,
capture,
},
}),
})
: providerError(cause),
);
}
if (application !== undefined) {
if (ownership !== undefined)
lineage = await observeOwnedProcessLineage(ownership);
if (ownership !== undefined) {
const currentLineage = await observeOwnedProcessLineage(ownership);
if (currentLineage.status === "verified" || lineage === undefined)
lineage = currentLineage;
}
let closeError: unknown;
try {
await runWithExecutionLimits(
@@ -146,13 +194,51 @@ export class PlaywrightElectronActiveProvider implements ElectronActiveObservati
: await cleanupElectronProcesses(ownership, lineage);
if (!cleanup.cleaned)
return err(
providerError(
new BrowserObservationError(OPERATION, "cleanup_failed", {
cause: new Error(cleanup.reason),
}),
),
new BrowserObservationError(OPERATION, "cleanup_failed", {
cause: outcome.ok ? new Error(cleanup.reason) : outcome.error,
detail: `Electron cleanup could not be verified: ${cleanup.reason}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`} Inspect the reported process resources before launching another capture.`,
cleanup: {
reason: cleanup.reason,
resources:
ownership === undefined
? ["owned_process_group"]
: [
"owned_process_group",
`run:${ownership.runId}`,
`process-group:${String(ownership.processGroupId)}`,
],
},
...(capture !== undefined
? {
partialObservation: {
kind: "electron-active-observation" as const,
capture: {
...capture,
application: {
...capture.application,
cleanup: "unverified" as const,
},
},
},
}
: {}),
}),
);
if (closeError !== undefined)
return err(
new BrowserObservationError(OPERATION, "cleanup_failed", {
cause: outcome.ok ? closeError : outcome.error,
detail: `Electron transport teardown failed after process cleanup: ${closeError instanceof Error ? closeError.message : String(closeError)}.${capture !== undefined ? " Collected observations are retained in partial_observation." : ""}${outcome.ok ? "" : ` Capture also failed: ${outcome.error.message}.`}`,
...(capture !== undefined
? {
partialObservation: {
kind: "electron-active-observation" as const,
capture,
},
}
: {}),
}),
);
if (closeError !== undefined) return err(providerError(closeError));
if (outcome.ok && cleanup.unverified !== undefined)
outcome = ok({
...outcome.value,
@@ -294,5 +380,8 @@ const providerError = (cause: unknown): AnalysisError =>
OPERATION,
{
cause,
diagnostics: {
message: cause instanceof Error ? cause.message : String(cause),
},
},
);
+55
View File
@@ -8,6 +8,7 @@ import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisOutputError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "../../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
@@ -17,6 +18,7 @@ import {
type InspectWebNetworkCaptureInput,
} from "../../domain/webNetworkCapture.js";
import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
import { HAR_CAPTURE_HEAP_LIMITS } from "./CaptureRelease.js";
const OPERATION = "inspect_web_network_capture";
/** Preserve the origin and typed cause of a historical capture failure. */
@@ -55,6 +57,18 @@ export const historicalCaptureFailure = (
);
if (cause.reason === "output-limit")
return new AnalysisOutputError(OPERATION, cause.message);
if (
phase === "decoder" &&
input.format === "har" &&
cause.reason === "process" &&
cause.snapshot?.signal === "SIGABRT" &&
/FATAL ERROR:[^\r\n]*heap out of memory/u.test(cause.snapshot.stderr.text)
)
return captureMemoryFailure(
input,
"The HAR decoder exhausted its fixed V8 heap",
cause,
);
}
if (options?.signal?.aborted) return new AnalysisCancelledError(OPERATION);
if (
@@ -144,3 +158,44 @@ export const historicalCaptureFailure = (
},
});
};
/** Preserve a decoder's observed memory failure and its actual workload limits. */
export const captureMemoryFailure = (
input: InspectWebNetworkCaptureInput,
reason: string,
cause?: unknown,
): AnalysisResourceConstraintError =>
new AnalysisResourceConstraintError(
OPERATION,
"memory",
`${reason}: ${input.capture_path}. No complete capture result is available.`,
{
boundary: "historical-capture-decoder",
capture_path: input.capture_path,
format: input.format,
maximum_input_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
maximum_reply_bytes: WEB_NETWORK_CAPTURE_LIMITS.outputBytes,
...(input.format === "har"
? {
old_generation_heap_mib: HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB,
semi_space_heap_mib: HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB,
}
: {}),
...(cause instanceof OwnedCommandFailure
? { observed_signal: cause.snapshot?.signal ?? null }
: {}),
},
{
cause,
remediationAction: `Use a smaller capture exported by its producer, or another decoder with sufficient capacity for the original capture. Preserve the original for provenance; a subset does not establish complete-capture coverage.${input.format === "har" ? ` REA's HAR old-generation heap is fixed at ${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB} MiB; inherited NODE_OPTIONS cannot raise it.` : ""}`,
...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
? {
capturedOutput: {
stdout: cause.snapshot.stdout.text,
stderr: cause.snapshot.stderr.text,
truncated: cause.snapshot.diagnosticTruncated ?? false,
},
}
: {}),
},
);
+6
View File
@@ -5,6 +5,12 @@ export const HAR_CAPTURE_PROVIDER_IDENTITY = {
version: "har-schema@2.0.0;jsonc-parser@3.3.1;lossless-json@4.3.1",
} as const;
/** Fixed V8 heap settings used by the owned HAR decoder process. */
export const HAR_CAPTURE_HEAP_LIMITS = {
oldGenerationMiB: 192,
semiSpaceMiB: 8,
} as const;
/** Native executable profile verified with unchanged mitmproxy raw-state decoding. */
export const MITMPROXY_CAPTURE_PROVIDER_IDENTITY = {
id: "mitmproxy-native-tnetstring",
+6 -3
View File
@@ -1,6 +1,9 @@
import { fileURLToPath } from "node:url";
import type { HistoricalCaptureFormatAdapter } from "./HistoricalCaptureFormatAdapter.js";
import { HAR_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
import {
HAR_CAPTURE_PROVIDER_IDENTITY,
HAR_CAPTURE_HEAP_LIMITS,
} from "./CaptureRelease.js";
/** HAR's parser/schema packages run in one bounded Node heap, without network or target execution. */
export class HarCaptureAdapter implements HistoricalCaptureFormatAdapter {
@@ -12,8 +15,8 @@ export class HarCaptureAdapter implements HistoricalCaptureFormatAdapter {
return {
command: process.execPath,
arguments: [
"--max-old-space-size=192",
"--max-semi-space-size=8",
`--max-old-space-size=${HAR_CAPTURE_HEAP_LIMITS.oldGenerationMiB}`,
`--max-semi-space-size=${HAR_CAPTURE_HEAP_LIMITS.semiSpaceMiB}`,
"--v8-pool-size=1",
"--single-threaded",
fileURLToPath(new URL("./HarCaptureProcess.js", import.meta.url)),
@@ -1,4 +1,7 @@
import { historicalCaptureFailure } from "./CaptureFailures.js";
import {
historicalCaptureFailure,
captureMemoryFailure,
} from "./CaptureFailures.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import type { HistoricalCaptureFormatAdapter } from "./HistoricalCaptureFormatAdapter.js";
import { randomUUID } from "node:crypto";
@@ -160,7 +163,9 @@ export class HistoricalCaptureDecoder {
},
},
]);
if (reply.reason === "decoder" || reply.reason === "resource-limit")
if (reply.reason === "resource-limit")
throw captureMemoryFailure(input, reply.message);
if (reply.reason === "decoder")
throw new ProviderAdapterError(input.format, OPERATION, {
diagnostics: {
phase: "decoder",