fix(observation): validate document consistency during capture

This commit is contained in:
Ljy-0827 committed 2026-09-08 19:22:46 +08:00
1 parent 1f6faa7a0a
commit d7b2c6cccd
10 files changed
+355 -13

No files matched your search

@@ -29,6 +29,24 @@ function fakeApi() {
}
describe("ChromiumCdp", () => {
it("changes attachment identity only across real debugger attachments", async () => {
const { api, onEvent, onDetach } = fakeApi();
const cdp = new ChromiumCdp(api);
expect(cdp.getAttachmentId(4)).toBeUndefined();
await cdp.ensureAttached(4);
const first = cdp.getAttachmentId(4);
expect(first).toBeTruthy();
await cdp.ensureAttached(4);
onEvent.fire({ tabId: 4 }, "Target.attachedToTarget", { sessionId: "child" });
expect(cdp.getAttachmentId(4)).toBe(first);
onDetach.fire({ tabId: 4 }, "target_closed");
expect(cdp.getAttachmentId(4)).toBeUndefined();
await cdp.ensureAttached(4);
expect(cdp.getAttachmentId(4)).not.toBe(first);
await cdp.detach(4);
expect(cdp.getAttachmentId(4)).toBeUndefined();
});
it("discovers multiple iframe targets and recursively routes nested OOPIF commands", async () => {
const { api, onEvent } = fakeApi();
(api.sendCommand as ReturnType<typeof vi.fn>).mockImplementation(
@@ -2,6 +2,24 @@ import { describe, expect, it } from "vitest";
import { buildFrameGraph, type CdpFrameTreeNode, type CdpFrameTreeSource } from "../frame-graph";
describe("buildFrameGraph", () => {
it("preserves the owning target's loader identity", () => {
const graph = buildFrameGraph([
{
target: { tabId: 4 },
tree: {
frame: { id: "root", loaderId: "root-loader" },
childFrames: [{ frame: { id: "child", loaderId: "stale-placeholder" } }],
},
},
{
target: { tabId: 4, sessionId: "child-session" },
tree: { frame: { id: "child", loaderId: "child-loader" } },
},
]);
expect(graph?.frames.find((frame) => frame.frameId === "root")?.loaderId).toBe("root-loader");
expect(graph?.frames.find((frame) => frame.frameId === "child")?.loaderId).toBe("child-loader");
});
it("keeps sibling frames distinct and routes nested OOPIFs to their child sessions", () => {
const graph = buildFrameGraph([
{
@@ -164,6 +164,7 @@ async function settleBeforeDeadline(promises: Promise<void>[], deadline: number)
export class ChromiumCdp {
private readonly api: CdpDebuggerApi;
private readonly attachedTabs = new Set<number>();
private readonly attachmentIds = new Map<number, string>();
private readonly attachInFlight = new Map<number, Promise<void>>();
private readonly detachInFlight = new Map<number, Promise<void>>();
private readonly tabOwners = new Map<number, Set<string>>();
@@ -198,6 +199,11 @@ export class ChromiumCdp {
this.bindFrameTargetHandler();
}
/** Identity of this actual debugger attachment, independent of frame topology. */
getAttachmentId(tabId: number): string | undefined {
return this.attachmentIds.get(tabId);
}
/** Attach to `tabId` if we haven't already in this driver. */
async ensureAttached(tabId: number): Promise<void> {
// Returning a tab clears the cache before Chrome finishes detaching.
@@ -217,6 +223,7 @@ export class ChromiumCdp {
await this.enableConsoleDomains(tabId);
await this.enableNetworkDomainBestEffort(tabId);
this.attachedTabs.add(tabId);
this.attachmentIds.set(tabId, crypto.randomUUID());
await this.enableFrameDiscovery({ tabId }).catch((err) => {
console.debug("[bsk cdp] frame discovery unavailable", { tabId, err });
});
@@ -444,6 +451,7 @@ export class ChromiumCdp {
this.attachInFlight.delete(tabId);
if (!this.attachedTabs.has(tabId)) return;
this.attachedTabs.delete(tabId);
this.attachmentIds.delete(tabId);
this.clearDialogState(tabId);
this.clearConsoleState(tabId);
this.clearNetworkState(tabId);
@@ -502,6 +510,7 @@ export class ChromiumCdp {
this.attachInFlight.clear();
this.tabOwners.clear();
this.attachedTabs.clear();
this.attachmentIds.clear();
this.dialogBuffers.clear();
this.dialogSequences.clear();
this.consoleBuffers.clear();
@@ -848,6 +857,7 @@ export class ChromiumCdp {
const listener = (source: chrome.debugger.Debuggee, _reason: string) => {
if (typeof source.tabId === "number") {
this.attachedTabs.delete(source.tabId);
this.attachmentIds.delete(source.tabId);
this.attachInFlight.delete(source.tabId);
this.tabOwners.delete(source.tabId);
this.clearDialogState(source.tabId);
@@ -8,6 +8,7 @@ export interface CdpFrame {
parentFrameId?: string;
ownerBackendNodeId?: number;
url?: string;
loaderId?: string;
target: CdpTarget;
}
@@ -21,6 +22,7 @@ export interface CdpFrameTreeNode {
id: string;
parentId?: string;
url?: string;
loaderId?: string;
};
childFrames?: CdpFrameTreeNode[];
}
@@ -48,6 +50,7 @@ function mergeFrame(
frameId: node.frame.id,
...(parentFrameId ? { parentFrameId } : {}),
...(url ? { url } : {}),
...(node.frame.loaderId ? { loaderId: node.frame.loaderId } : {}),
target,
});
}
+1
View File
@@ -55,6 +55,7 @@ export interface CdpRunner {
sendToTarget?<T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T>;
detach?(tabId: number): Promise<void>;
getFrameGraph?(tabId: number): Promise<CdpFrameGraph>;
getAttachmentId?(tabId: number): string | undefined;
ensureAttachedToUrl?(tabId: number, expectedUrl: string | undefined): Promise<void>;
trackSessionTab?(sessionId: string, tabId: number): void;
releaseSessionTab?(sessionId: string, tabId: number): Promise<void>;
@@ -8,33 +8,48 @@ import { buildSemanticGraph } from "../semantic-graph/build";
import { REQUESTED_STYLES } from "../snapshot";
function fixture(
options: { frames?: CdpFrame[]; fail?: string; omitDocument?: string; overlay?: string } = {},
options: {
frames?: CdpFrame[];
after?: Record<string, { loader?: string; element?: number; missing?: boolean }>;
fail?: string;
missingIdentity?: boolean;
omitDocument?: string;
attachmentChanged?: boolean;
overlay?: string;
} = {},
) {
const frames = options.frames ?? [
{ frameId: "main", target: { tabId: 4 } },
{ frameId: "main", loaderId: "main-loader", target: { tabId: 4 } },
{
frameId: "same",
parentFrameId: "main",
ownerBackendNodeId: 3,
loaderId: "same-loader",
target: { tabId: 4 },
},
{
frameId: "nested",
parentFrameId: "same",
ownerBackendNodeId: 13,
loaderId: "nested-loader",
target: { tabId: 4 },
},
{
frameId: "remote",
parentFrameId: "main",
ownerBackendNodeId: 4,
loaderId: "remote-loader",
target: { tabId: 4, sessionId: "remote" },
},
];
const elements = new Map(
frames.map((frame, i) => [frame.frameId, frame.target.sessionId ? 1 : i * 10 + 1]),
);
const contexts = new Map(frames.map((frame, i) => [i + 1, frame.frameId]));
const reads = new Map<string, number>();
const logs: Array<{ target: CdpTarget; method: string; params: Record<string, unknown> }> = [];
let snapshots = 0;
const targetCount = new Set(frames.map((frame) => cdpTargetKey(frame.target))).size;
const send = vi.fn(
async <T>(target: CdpTarget, method: string, params: object = {}): Promise<T> => {
logs.push({ target, method, params: params as Record<string, unknown> });
@@ -42,9 +57,52 @@ function fixture(
if (options.fail === `${target.sessionId ?? "main"}:${method}`)
throw new Error("fixture failure");
let result: unknown = {};
if (method === "Page.createIsolatedWorld")
result = {
executionContextId: frames.findIndex((frame) => frame.frameId === args.frameId) + 1,
};
if (method === "Runtime.evaluate")
result = { result: { objectId: contexts.get(Number(args.contextId)) } };
if (method === "DOM.describeNode") {
const id = String(args.objectId);
const count = reads.get(id) ?? 0;
reads.set(id, count + 1);
result = options.missingIdentity
? {}
: {
node: {
backendNodeId:
count > 0 ? (options.after?.[id]?.element ?? elements.get(id)) : elements.get(id),
},
};
}
if (method === "Page.getFrameTree") {
const own = frames.filter(
(frame) =>
cdpTargetKey(frame.target) === cdpTargetKey(target) &&
!options.after?.[frame.frameId]?.missing,
);
const trees = new Map(
own.map((frame) => [
frame.frameId,
{
frame: {
id: frame.frameId,
loaderId: options.after?.[frame.frameId]?.loader ?? frame.loaderId,
},
childFrames: [] as unknown[],
},
]),
);
for (const frame of own)
if (frame.parentFrameId && trees.has(frame.parentFrameId))
trees.get(frame.parentFrameId)!.childFrames.push(trees.get(frame.frameId));
result = { frameTree: trees.get(own[0]?.frameId) };
}
if (method === "Page.getLayoutMetrics")
result = { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
if (method === "DOMSnapshot.captureSnapshot") {
snapshots++;
expect((params as { computedStyles: unknown }).computedStyles).toEqual(REQUESTED_STYLES);
result = {
strings: [
@@ -108,6 +166,8 @@ function fixture(
},
);
const cdp: CdpRunner = {
getAttachmentId: () =>
options.attachmentChanged && snapshots === targetCount ? "new-attachment" : "attachment",
getFrameGraph: async () => ({ rootFrameId: frames[0].frameId, frames }),
send: (tabId, method, params) =>
(send as NonNullable<CdpRunner["sendToTarget"]>)({ tabId }, method, params),
@@ -117,22 +177,48 @@ function fixture(
}
describe("captureObservationFacts", () => {
it("collects each target once and scopes equal backend IDs", async () => {
it("collects each target once, validates every document and scopes equal backend IDs", async () => {
const { cdp, logs } = fixture();
const facts = await captureObservationFacts(cdp, 4);
expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(2);
expect(logs.filter((call) => call.method === "Accessibility.enable")).toHaveLength(2);
expect(logs.filter((call) => call.method === "Accessibility.getFullAXTree")).toHaveLength(4);
expect(logs.filter((call) => call.method === "DOM.describeNode")).toHaveLength(8);
expect(logs.filter((call) => call.method === "Runtime.releaseObject")).toHaveLength(8);
expect(facts.documents.every((doc) => doc.identity)).toBe(true);
const main = facts.documents.find((doc) => doc.frame.frameId === "main")!;
const remote = facts.documents.find((doc) => doc.frame.frameId === "remote")!;
expect(main.index.nodes.get(2)).not.toBe(remote.index.nodes.get(2));
expect(main.index.children.get(1)).toEqual([2]);
expect(main.index.nodes.get(10001)?.nodeType).toBe(10);
expect(main.identity?.documentElementBackendNodeId).toBe(1);
expect(remote.axNodes[0].frameId).toBe("remote");
expect(main.index.nodes.get(2)).toBe(main.domNodes.find((node) => node.backendNodeId === 2));
expect(facts.finishedAt).toBeGreaterThanOrEqual(facts.startedAt);
});
it.each([
{ loader: "new-loader" },
{ element: 99 },
{ missing: true },
])("isolates changed child identity %j and dependent descendants", async (change) => {
const { cdp } = fixture({ after: { same: change } });
const facts = await captureObservationFacts(cdp, 4);
expect(facts.documents.map((doc) => doc.frame.frameId)).toEqual(["main", "remote"]);
expect(facts.issues).toContainEqual(
expect.objectContaining({ frameId: "same", reason: "document-changed" }),
);
});
it.each([
{ after: { main: { element: 99 } } },
{ attachmentChanged: true },
])("rejects a root replacement or reattachment %j", async (options) => {
await expect(captureObservationFacts(fixture(options).cdp, 4)).rejects.toThrow(
"document identity",
);
});
it("does not retry failed or missing documents and retains valid AX-only semantics", async () => {
const { cdp, logs } = fixture({
fail: "remote:DOMSnapshot.captureSnapshot",
@@ -151,6 +237,12 @@ describe("captureObservationFacts", () => {
);
});
it("keeps missing identity explicit without manufacturing a verified document", async () => {
const facts = await captureObservationFacts(fixture({ missingIdentity: true }).cdp, 4);
expect(facts.documents.every((doc) => !doc.identity)).toBe(true);
expect(facts.issues.filter((issue) => issue.reason === "identity-unverified")).toHaveLength(4);
});
it("excludes overlay AX in its own document without excluding equal IDs elsewhere", async () => {
const facts = await captureObservationFacts(fixture({ overlay: "remote" }).cdp, 4);
const { documents } = semanticCapture(facts);
@@ -1,16 +1,20 @@
import {
buildFrameGraph,
type CdpFrame,
type CdpFrameGraph,
type CdpFrameTreeNode,
type CdpTarget,
cdpTargetKey,
} from "@/browser-driver/frame-graph";
import { cssViewport, GeometryContext } from "../geometry/frame-context";
import { type CdpRunner, cdpRunnerForTarget } from "../shared";
import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
import { collectOverlayExcludedBackendIds } from "./capture";
import { readDocumentIdentity, sameDocument } from "./document-identity";
import type { CapturedSceneInput } from "./facts";
import {
buildDocumentIndex,
type CaptureIssue,
type DocumentIdentity,
isCaptureAbort,
type ObservationFacts,
throwCaptureAborted,
@@ -28,6 +32,7 @@ import { REQUESTED_STYLES, type SnapshotReply, snapshotFrameId } from "./snapsho
interface TargetBatch<T extends FrameOwnedAxNode> {
target: CdpTarget;
frames: CdpFrame[];
before: Map<string, DocumentIdentity>;
documents: NormalizedDocument[];
ax: FrameAxBatch<T>[];
fallbackExcluded: Set<number>;
@@ -101,6 +106,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
group = {
target: frame.target,
frames: [],
before: new Map(),
documents: [],
ax: [],
fallbackExcluded: new Set(),
@@ -113,6 +119,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
groups.set(cdpTargetKey({ tabId }), {
target: { tabId },
frames: [],
before: new Map(),
documents: [],
ax: [],
fallbackExcluded: new Set(),
@@ -125,6 +132,10 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
batches,
async (batch) => {
const scoped = cdpRunnerForTarget(cdp, batch.target);
for (const frame of batch.frames) {
const identity = await readDocumentIdentity(cdp, frame, signal);
if (identity) batch.before.set(frame.frameId, identity);
}
try {
throwCaptureAborted(signal);
await scoped.send(tabId, "DOMSnapshot.enable", {});
@@ -192,12 +203,114 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
signal,
);
const frames = batches.flatMap((batch) => batch.frames);
const rootFrameId = graph?.rootFrameId ?? frames[0]?.frameId ?? "root";
const decoded = new Map(
batches.flatMap((batch) => batch.documents).map((doc) => [doc.frame.frameId, doc]),
// Validate after every target's static data and geometry have been collected.
const identities = new Map<string, DocumentIdentity>();
const invalid = new Set<string>();
await collectTargets(
batches,
async (batch) => {
let fresh: Map<string, CdpFrame> | undefined;
if (batch.before.size) {
try {
throwCaptureAborted(signal);
const reply = await sendToCdpTarget<{ frameTree?: CdpFrameTreeNode }>(
cdp,
batch.target,
"Page.getFrameTree",
{},
);
const tree = reply.frameTree
? buildFrameGraph([{ target: batch.target, tree: reply.frameTree }])
: null;
fresh = new Map(tree?.frames.map((frame) => [frame.frameId, frame]));
} catch (error) {
if (isCaptureAbort(error)) throw error;
}
}
const docs = new Map(batch.documents.map((doc) => [doc.frame.frameId, doc]));
for (const frame of batch.frames) {
const before = batch.before.get(frame.frameId);
const currentFrame = fresh?.get(frame.frameId);
const after = currentFrame
? await readDocumentIdentity(cdp, currentFrame, signal)
: undefined;
const doc = docs.get(frame.frameId);
const snapshotMismatch =
before &&
doc?.documentElementBackendNodeId !== undefined &&
before.documentElementBackendNodeId !== doc.documentElementBackendNodeId;
if (
before &&
(snapshotMismatch ||
(fresh && !currentFrame) ||
(after && !sameDocument(before, after)) ||
cdp.getAttachmentId?.(tabId) !== before.attachmentId)
) {
invalid.add(frame.frameId);
issues.push({
target: frame.target,
frameId: frame.frameId,
stage: "identity",
reason: "document-changed",
});
} else if (before && !after) {
invalid.add(frame.frameId);
issues.push({
target: frame.target,
frameId: frame.frameId,
stage: "identity",
reason: "identity-unverified",
});
} else if (
before &&
after &&
sameDocument(before, after) &&
(!doc || doc.documentElementBackendNodeId === before.documentElementBackendNodeId)
)
identities.set(frame.frameId, after);
else
issues.push({
target: frame.target,
frameId: frame.frameId,
stage: "identity",
reason: "identity-unverified",
});
}
},
signal,
);
const ax = batches.flatMap((batch) => batch.ax);
const allFrames = batches.flatMap((batch) => batch.frames);
const rootFrameId = graph?.rootFrameId ?? allFrames[0]?.frameId ?? "root";
if (invalid.has(rootFrameId))
throw new Error(
"observation document identity changed or could not be verified; observe again",
);
// A descendant cannot retain geometry measured through an invalid ancestor.
const childFrames = new Map<string, string[]>();
for (const frame of allFrames)
if (frame.parentFrameId) {
const children = childFrames.get(frame.parentFrameId);
if (children) children.push(frame.frameId);
else childFrames.set(frame.parentFrameId, [frame.frameId]);
}
const queue = [...invalid];
for (let i = 0; i < queue.length; i++)
for (const child of childFrames.get(queue[i]) ?? []) {
if (!invalid.has(child)) {
invalid.add(child);
queue.push(child);
}
}
const frames = allFrames.filter((frame) => !invalid.has(frame.frameId));
const decoded = new Map(
batches
.flatMap((batch) => batch.documents)
.filter((doc) => !invalid.has(doc.frame.frameId))
.map((doc) => [doc.frame.frameId, doc]),
);
const ax = batches
.flatMap((batch) => batch.ax)
.filter((batch) => !invalid.has(batch.frame.frameId));
const documents = await buildFrameDocuments(
{ rootFrameId, frames },
ax,
@@ -230,6 +343,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
const { domNodes, axNodes, contextScopeId: _scope, ...frame } = document;
facts.push({
frame,
identity: identities.get(document.frameId),
index: fallback?.size ? { ...index, excludedBackendNodeIds: fallback } : index,
domNodes,
axNodes,
@@ -241,8 +355,8 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
return { rootFrameId, viewport, documents: facts, issues, startedAt, finishedAt: Date.now() };
}
/** Existing semantic consumers get a narrow view; no raw snapshot
* data can leak through recording's allowlisted output DTO. */
/** Existing semantic consumers get a narrow view; no raw snapshot or identity
* metadata can leak through recording's allowlisted output DTO. */
export function semanticCapture<T extends FrameOwnedAxNode>(
facts: ObservationFacts<T>,
): { captured: CapturedSceneInput; documents: FrameDocument<T>[] } {
@@ -0,0 +1,65 @@
import type { CdpFrame } from "@/browser-driver/frame-graph";
import type { CdpRunner } from "../shared";
import { sendToCdpTarget } from "../shared";
import { type DocumentIdentity, isCaptureAbort, throwCaptureAborted } from "./facts";
/** Fresh, frame-scoped identity read. An isolated world supplies the owning
* document without querying each node or installing a page observer. */
export async function readDocumentIdentity(
cdp: CdpRunner,
frame: CdpFrame,
signal?: AbortSignal,
): Promise<DocumentIdentity | undefined> {
const attachmentId = cdp.getAttachmentId?.(frame.target.tabId);
if (!attachmentId || !frame.loaderId) return undefined;
let objectId: string | undefined;
const send = <T>(method: string, params: object) => {
throwCaptureAborted(signal);
return sendToCdpTarget<T>(cdp, frame.target, method, params);
};
try {
const world = await send<{ executionContextId: number }>("Page.createIsolatedWorld", {
frameId: frame.frameId,
worldName: "bsk-document-identity",
});
const element = await send<{ result?: { objectId?: string } }>("Runtime.evaluate", {
expression: "document.documentElement",
contextId: world.executionContextId,
});
objectId = element.result?.objectId;
if (!objectId) return undefined;
const reply = await send<{ node?: { backendNodeId?: number } }>("DOM.describeNode", {
objectId,
depth: 0,
});
const backendNodeId = reply.node?.backendNodeId;
if (!backendNodeId || cdp.getAttachmentId?.(frame.target.tabId) !== attachmentId)
return undefined;
return {
attachmentId,
target: frame.target,
frameId: frame.frameId,
loaderId: frame.loaderId,
documentElementBackendNodeId: backendNodeId,
};
} catch (error) {
if (isCaptureAbort(error)) throw error;
return undefined;
} finally {
if (objectId)
await sendToCdpTarget(cdp, frame.target, "Runtime.releaseObject", { objectId }).catch(
() => {},
);
}
}
export function sameDocument(a: DocumentIdentity, b: DocumentIdentity): boolean {
return (
a.attachmentId === b.attachmentId &&
a.target.tabId === b.target.tabId &&
a.target.sessionId === b.target.sessionId &&
a.frameId === b.frameId &&
a.loaderId === b.loaderId &&
a.documentElementBackendNodeId === b.documentElementBackendNodeId
);
}
+16 -2
View File
@@ -55,6 +55,14 @@ export interface CapturedSceneInput {
excludedBackendNodeIds: ReadonlySet<number>;
}
export interface DocumentIdentity {
attachmentId: string;
target: CdpTarget;
frameId: string;
loaderId: string;
documentElementBackendNodeId: number;
}
/** Snapshot client/offset rectangles retain their protocol units. In particular,
* transformed bounds cannot be combined with unscaled client offsets. */
export interface SnapshotLayout {
@@ -97,12 +105,18 @@ export interface DecodedDocument {
export interface CaptureIssue {
target: CdpTarget;
frameId?: string;
stage: "dom" | "ax" | "ownership" | "geometry" | "forms";
reason: "capture-unavailable" | "frame-ownership-unresolved" | "geometry-unavailable";
stage: "dom" | "ax" | "identity" | "ownership" | "geometry" | "forms";
reason:
| "capture-unavailable"
| "document-changed"
| "identity-unverified"
| "frame-ownership-unresolved"
| "geometry-unavailable";
}
export interface DocumentFacts<T extends FrameOwnedAxNode> {
readonly frame: CdpFrame;
readonly identity?: DocumentIdentity;
readonly index: DocumentIndex;
readonly domNodes: CapturedNode[];
readonly axNodes: T[];
@@ -27,6 +27,7 @@ export interface NormalizedDocument {
index: DocumentIndex;
frame: CdpFrame;
domNodes: CapturedNode[];
documentElementBackendNodeId?: number;
}
/** One target's snapshot. Source ownership is checked before interpreting any
@@ -167,6 +168,12 @@ export async function normalizeSnapshot(
index,
frame,
domNodes,
documentElementBackendNodeId: nodes.find(
(node) =>
node.nodeType === 1 &&
node.parentBackendNodeId !== null &&
index.nodes.get(node.parentBackendNodeId)?.nodeType === 9,
)?.backendNodeId,
});
}
for (const frameId of sources.keys()) {