fix(inspector): bound retained metadata and preserve cancellation

This commit is contained in:
morluto
2026-10-09 05:15:23 +08:00
parent f983c718c3
commit e714fb027a
9 changed files with 296 additions and 76 deletions
@@ -2,7 +2,10 @@ import type { ExecutionOptions } from "../AnalysisProvider.js";
import type { JavaScriptRuntimeObservationPort } from "./JavaScriptRuntimeObservationPort.js";
import { createJavaScriptRuntimeObservationEvidence } from "./JavaScriptRuntimeObservationEvidence.js";
import type { Evidence } from "../../domain/evidence.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
} from "../../domain/analysisErrorCore.js";
import { type AnalysisError } from "../../domain/analysisErrorBase.js";
import type {
ListJavaScriptRuntimeTargetsInput,
@@ -40,6 +43,8 @@ export const observeJavaScriptRuntime = async (
const ready = requireProvider(provider, "observe_javascript_runtime");
if (!ready.ok) return ready;
const result = await ready.value.observe(input, options);
if (options.signal?.aborted === true)
return err(new AnalysisCancelledError("observe_javascript_runtime"));
return result.ok
? ok(
createJavaScriptRuntimeObservationEvidence(
+7 -4
View File
@@ -25,7 +25,9 @@ interface PendingCommand {
export class CdpConnection {
readonly #pending = new Map<number, PendingCommand>();
readonly #listeners = new Set<(event: CdpEvent) => void>();
readonly #disconnectListeners = new Set<() => void>();
readonly #disconnectListeners = new Set<
(error: BrowserObservationError) => void
>();
readonly #protocolFailureListeners = new Set<
(error: BrowserObservationError) => void
>();
@@ -74,9 +76,9 @@ export class CdpConnection {
}
/** Subscribe to an unexpected transport loss while an operation is active. */
onDisconnect(listener: () => void): () => void {
onDisconnect(listener: (error: BrowserObservationError) => void): () => void {
if (this.#closed) {
listener();
listener(this.#transportError(this.#transportFailure));
return () => undefined;
}
this.#disconnectListeners.add(listener);
@@ -281,7 +283,8 @@ export class CdpConnection {
if (!wasClosed) this.#transportFailure = reason;
this.#failPending(reason);
if (wasClosed) return;
for (const listener of this.#disconnectListeners) listener();
const error = this.#transportError(reason);
for (const listener of this.#disconnectListeners) listener(error);
this.#disconnectListeners.clear();
}
+12
View File
@@ -9,6 +9,7 @@ import type {
JavaScriptRuntimeLocation,
JavaScriptRuntimeTargetLocation,
} from "../domain/javascript/javascriptRuntimeObservation.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { authorizedElectronFile } from "../browser/ElectronFileScope.js";
export type RuntimeLocationDecision =
@@ -18,6 +19,14 @@ export type RuntimeLocationDecision =
readonly reason: BrowserExclusionReason;
};
/** Throw the operation's typed cancellation error whenever its signal is aborted. */
export const throwIfRuntimeObservationCancelled = (
signal?: AbortSignal,
): void => {
if (signal?.aborted === true)
throw new AnalysisCancelledError("observe_javascript_runtime");
};
/**
* Wire bucket for inspector script exclusions. The V8 observation schemas
* fix the `unsupported_location` key, so every canonical denial reason maps
@@ -35,7 +44,9 @@ export const inspectorExclusionKey = (
/** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */
export const authorizeRuntimeLocation = async (
value: string,
signal?: AbortSignal,
): Promise<RuntimeLocationDecision> => {
throwIfRuntimeObservationCancelled(signal);
if (value.startsWith("node:") && value.length > 0)
return {
allowed: true,
@@ -43,6 +54,7 @@ export const authorizeRuntimeLocation = async (
};
if (value.startsWith("file:")) {
const filePath = await authorizedElectronFile(value);
throwIfRuntimeObservationCancelled(signal);
return filePath === undefined
? { allowed: false, reason: "not_approved" }
: { allowed: true, location: { kind: "file", file_path: filePath } };
@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
import { afterAll, beforeAll, expect, it } from "vitest";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { finalizeInspectorCapture } from "./V8InspectorCaptureProjection.js";
import type { CaptureState } from "./V8InspectorProvider.js";
@@ -214,3 +215,48 @@ it("waits for active authorization workers to settle before returning a failure"
expect(new Set(startedUrls)).toEqual(initialStarted);
expect(active).toBe(0);
});
it("stops finalization when cancellation arrives during location authorization", async () => {
const controller = new AbortController();
let authorizationStarted = false;
const state = stateFor([
{
rawUrl: "https://example.test/script.js",
executionContextKey: null,
cdpHash: null,
length: 0,
isModule: false,
},
]);
const finalization = finalizeInspectorCapture({
input: {
inspector_endpoint: "http://127.0.0.1:9222",
target_id: target.id,
observation_ms: 100,
},
runtime: {
product: "Node.js/v24.18.0",
protocol_version: "1.3",
v8_version: null,
},
target,
state,
signal: controller.signal,
authorizeLocation: async () => {
authorizationStarted = true;
controller.abort();
return {
allowed: true,
location: {
kind: "url",
origin: "https://example.test",
sanitized_url: "https://example.test/script.js",
},
};
},
});
await expect(finalization).rejects.toBeInstanceOf(AnalysisCancelledError);
expect(authorizationStarted).toBe(true);
});
+13 -2
View File
@@ -9,6 +9,7 @@ import type {
import {
authorizeRuntimeLocation,
inspectorExclusionKey,
throwIfRuntimeObservationCancelled,
} from "./JavaScriptRuntimeScope.js";
import type { CaptureState, ScriptDraft } from "./V8InspectorProvider.js";
import type { AuthorizedV8InspectorTarget } from "./V8InspectorEndpoint.js";
@@ -38,7 +39,11 @@ interface FinalizeCaptureInput {
readonly runtime: JavaScriptRuntimeTargetList["runtime"];
readonly target: AuthorizedV8InspectorTarget;
readonly state: CaptureState;
readonly authorizeLocation?: typeof authorizeRuntimeLocation;
readonly authorizeLocation?: (
rawUrl: string,
signal?: AbortSignal,
) => ReturnType<typeof authorizeRuntimeLocation>;
readonly signal?: AbortSignal;
}
const LOCATION_AUTHORIZATION_WORKERS = 8;
@@ -55,7 +60,9 @@ export const finalizeInspectorCapture = async ({
target,
state,
authorizeLocation = authorizeRuntimeLocation,
signal,
}: FinalizeCaptureInput): Promise<JavaScriptRuntimeObservation> => {
throwIfRuntimeObservationCancelled(signal);
const exclusions = createInspectorExclusionCounts();
const scripts = new Map<
string,
@@ -74,6 +81,7 @@ export const finalizeInspectorCapture = async ({
const worker = async (): Promise<void> => {
try {
for (;;) {
throwIfRuntimeObservationCancelled(signal);
if (stopScheduling) return;
const index = nextGroup;
nextGroup += 1;
@@ -82,8 +90,9 @@ export const finalizeInspectorCapture = async ({
const [rawUrl, drafts] = group;
authorizedGroups[index] = {
drafts,
decision: await authorizeLocation(rawUrl),
decision: await authorizeLocation(rawUrl, signal),
};
throwIfRuntimeObservationCancelled(signal);
}
} catch (cause: unknown) {
stopScheduling = true;
@@ -99,6 +108,7 @@ export const finalizeInspectorCapture = async ({
const failedWorker = workerResults.find(
(result) => result.status === "rejected",
);
throwIfRuntimeObservationCancelled(signal);
if (failedWorker?.status === "rejected") throw failedWorker.reason;
for (const { drafts, decision } of authorizedGroups) {
for (const draft of drafts) {
@@ -131,6 +141,7 @@ export const finalizeInspectorCapture = async ({
? 1
: 0,
);
throwIfRuntimeObservationCancelled(signal);
return {
runtime,
target: {
+53 -18
View File
@@ -42,6 +42,12 @@ import {
export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
/** Maximum decoded CDP message accepted while observing one Inspector target. */
export const INSPECTOR_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
/** Aggregate retained metadata budget, including an estimate of JS object overhead. */
export const INSPECTOR_MAX_RETAINED_METADATA_BYTES = 8 * 1024 * 1024;
const RETAINED_OBJECT_OVERHEAD_BYTES = 512;
export interface ScriptDraft {
readonly rawUrl: string;
readonly executionContextKey: string | null;
@@ -147,6 +153,7 @@ export class V8InspectorProvider implements JavaScriptRuntimeObservationPort {
target.webSocketUrl,
"observe_javascript_runtime",
options.signal,
{ maxPayloadBytes: INSPECTOR_MAX_PAYLOAD_BYTES },
);
const state = emptyCaptureState();
const removeListener = connection.onEvent((event) =>
@@ -164,6 +171,7 @@ export class V8InspectorProvider implements JavaScriptRuntimeObservationPort {
runtime: discovery.runtime,
target,
state,
...(options.signal === undefined ? {} : { signal: options.signal }),
});
outcome = ok(javascriptRuntimeObservationSchema.parse(result));
} catch (cause: unknown) {
@@ -344,8 +352,8 @@ const ingestScript = (
length: nonnegativeInteger(value?.length),
isModule: value?.isModule === true,
};
const bytes = metadataBytes(draft);
retainEvent(state, bytes);
const bytes = retainedMetadataBytes(draft);
if (!retainEvent(state, bytes)) return;
state.scripts.push(draft);
};
@@ -355,8 +363,16 @@ const ingestContext = (
state: CaptureState,
): void => {
if (event.method === "Runtime.executionContextsCleared") {
for (const context of state.contexts.values()) context.state = "cleared";
retainEvent(state, 0);
let byteDelta = 0;
for (const context of state.contexts.values()) {
byteDelta +=
retainedMetadataBytes({ ...context, state: "cleared" }) -
retainedMetadataBytes(context);
}
if (replaceRetainedMetadata(state, byteDelta)) {
for (const context of state.contexts.values()) context.state = "cleared";
retainEvent(state, 0);
}
return;
}
const parameters = recordValue(event.params);
@@ -385,14 +401,32 @@ const ingestContext = (
: "destroyed",
origin: origin === "" ? null : origin,
};
const bytes = metadataBytes(draft);
retainEvent(state, bytes);
const previous = state.contexts.get(key);
const bytes =
retainedMetadataBytes(draft) -
(previous === undefined ? 0 : retainedMetadataBytes(previous));
if (!retainEvent(state, bytes)) return;
state.contexts.set(key, draft);
};
const retainEvent = (state: CaptureState, bytes: number): void => {
state.metadataBytes += bytes;
const retainEvent = (state: CaptureState, bytes: number): boolean => {
if (!replaceRetainedMetadata(state, bytes)) return false;
state.eventsRetained += 1;
return true;
};
const replaceRetainedMetadata = (
state: CaptureState,
byteDelta: number,
): boolean => {
if (state.metadataBytes + byteDelta > INSPECTOR_MAX_RETAINED_METADATA_BYTES) {
state.eventsDropped += 1;
state.truncated = true;
state.truncationReasons.add("retained_metadata_budget_exceeded");
return false;
}
state.metadataBytes += byteDelta;
return true;
};
const waitForCapture = async (
@@ -402,14 +436,7 @@ const waitForCapture = async (
): Promise<void> => {
let removeDisconnect = (): void => undefined;
const disconnected = new Promise<never>((_resolve, reject) => {
removeDisconnect = connection.onDisconnect(() =>
reject(
new BrowserObservationError(
"observe_javascript_runtime",
"disconnected",
),
),
);
removeDisconnect = connection.onDisconnect((error) => reject(error));
});
try {
await Promise.race([
@@ -425,8 +452,16 @@ const waitForCapture = async (
}
};
const metadataBytes = (value: object): number =>
Buffer.byteLength(JSON.stringify(value));
const retainedMetadataBytes = (value: ScriptDraft | ContextDraft): number => {
const strings =
"rawUrl" in value
? [value.rawUrl, value.rawUrl, value.executionContextKey, value.cdpHash]
: [value.contextKey, value.origin];
return (
RETAINED_OBJECT_OVERHEAD_BYTES +
strings.reduce((total, text) => total + (text?.length ?? 0) * 2, 0)
);
};
const nonnegativeInteger = (value: unknown): number => {
const parsed = numberValue(value);