fix(capture): retain Electron observations and HAR resource failures
This commit is contained in:
@@ -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
|
||||
? [
|
||||
|
||||
@@ -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),
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
@@ -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,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user