From 025d1b365ff8b6b2b5376d232ddb21917c8b0912 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:39:05 +0800 Subject: [PATCH] refactor(browser): parse frame lifecycle events once by a registered event schema (#10730) * refactor(browser): parse frame lifecycle events once by a registered event schema CdpConnection admits each event through protocol/CdpEvents.ts, which parses the five Page frame lifecycle events once into identity facts plus a frame URL observation, like a frame-tree node. Screenshot, page capture, the observation timeline, WebMCP, Electron inspection and the execution window read those facts instead of re-parsing the raw payload; CdpFrameFacts no longer carries the raw source record. Playwright CDP session subscriptions name an event from Playwright's protocol table, and an architecture guard counts the remaining raw event payload reads so they can only shrink. * refactor(browser): admit transport events through the registered-event owner Remove the unused cdpFrameUrl wrapper; its fragment cases now exercise observeCdpFrameUrl. Add a connection-level test that two subscribers share one parsed payload and the raw params. --- .../verify/architecture-guard-baselines.json | 11 ++ scripts/verify/architecture-guards.mjs | 16 ++ .../CdpCaptureContextRetention.test.ts | 19 +- src/browser/CdpCaptureDocuments.test.ts | 22 ++- src/browser/CdpCaptureDocuments.ts | 8 - src/browser/CdpCaptureEventHandlers.ts | 19 +- .../CdpCaptureEvents.consoleTimestamp.test.ts | 5 +- .../CdpCaptureEvents.coverageStart.test.ts | 11 +- .../CdpCaptureEvents.eventBudget.test.ts | 155 ++++++++------- ...CdpCaptureEvents.redirectBodyShape.test.ts | 73 +++---- .../CdpCaptureEvents.shapeBudget.test.ts | 181 ++++++++++-------- src/browser/CdpCaptureEvents.ts | 8 +- .../CdpCaptureEvents.webSocketFrames.test.ts | 31 +-- src/browser/CdpConnection.ts | 34 +++- src/browser/CdpElectronInspection.test.ts | 14 +- src/browser/CdpElectronInspection.ts | 45 ++--- src/browser/CdpFrameIdentity.test.ts | 15 +- src/browser/CdpFrameIdentity.ts | 42 ++-- src/browser/CdpLargeBase64.test.ts | 85 ++++---- src/browser/CdpObservationSession.ts | 65 +++---- src/browser/CdpScreenshot.ts | 24 +-- src/browser/CdpWebMcpDiscovery.ts | 20 +- src/browser/PlaywrightCdpSession.ts | 16 +- .../execution/CdpExecutionWindow.test.ts | 45 +++-- src/browser/execution/CdpExecutionWindow.ts | 19 +- .../protocol/CdpCommands.types.test.ts | 17 ++ src/browser/protocol/CdpEvents.test.ts | 74 +++++++ src/browser/protocol/CdpEvents.ts | 118 ++++++++++++ src/browser/protocol/CdpFrameTree.ts | 9 + .../browser/cdpCaptureScriptMetadata.test.ts | 109 ++++++----- tests/boundary/browser/cdpConnection.test.ts | 45 +++++ .../browser/cdpJsonShapeComparison.test.ts | 63 +++--- 32 files changed, 897 insertions(+), 521 deletions(-) create mode 100644 src/browser/protocol/CdpEvents.test.ts create mode 100644 src/browser/protocol/CdpEvents.ts diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json index a7e5b3e254..654f7eded1 100644 --- a/scripts/verify/architecture-guard-baselines.json +++ b/scripts/verify/architecture-guard-baselines.json @@ -3,6 +3,17 @@ "src/gdb/GdbSessionManager.ts": 1, "src/process/ownedDebuggerSession.ts": 1 }, + "cdp-raw-event-params": { + "src/browser/CdpCaptureEvents.ts": 1, + "src/browser/CdpElectronScriptEvents.ts": 3, + "src/browser/CdpObservationSession.ts": 1, + "src/browser/CdpTargetEvents.ts": 1, + "src/browser/CdpWebMcpDiscovery.ts": 1, + "src/browser/PlaywrightScenarioServiceWorkers.ts": 2, + "src/browser/execution/CdpRuntimeRequests.ts": 1, + "src/browser/execution/CdpRuntimeSources.ts": 6, + "src/inspector/V8InspectorProvider.ts": 4 + }, "parser-json-parse": { "src/android/JadxProtocol.ts": 2, "src/android/JadxWorkspaceRoot.ts": 1, diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index b1ffcb9fc3..b95ccc36fc 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -364,6 +364,22 @@ checkCounted( ["src/gdb/GdbMiRecord.ts"], ); +// CDP event payloads are parsed once at the connection by the registered +// schema in src/browser/protocol/CdpEvents.ts; a subscriber reads +// `event.registered`, not the raw payload, so malformed members cannot be +// reinterpreted, dropped or defaulted differently by each subscriber. +checkCounted( + "raw CDP event payload read (register the event in src/browser/protocol/CdpEvents and read event.registered)", + "cdp-raw-event-params", + files.filter( + (file) => + file.path.startsWith("src/browser/") || + file.path.startsWith("src/inspector/"), + ), + /\bevent\.params\b/gu, + ["src/browser/CdpConnection.ts"], +); + // Byte-format parsers read untrusted input. Bounds, truncation and failure // kind belong to BinaryReader (src/native/metadata/BinaryContainer.ts) and // the ParseFailure algebra (src/domain/parseFailure.ts), not to each parser. diff --git a/src/browser/CdpCaptureContextRetention.test.ts b/src/browser/CdpCaptureContextRetention.test.ts index 94d05e673d..49d0daed98 100644 --- a/src/browser/CdpCaptureContextRetention.test.ts +++ b/src/browser/CdpCaptureContextRetention.test.ts @@ -9,6 +9,11 @@ import { ingestElectronScriptEvent, type ElectronScriptDraft, } from "./CdpElectronScriptEvents.js"; +import { receiveCdpEvent, type CdpEvent } from "./CdpConnection.js"; + +/** Deliver one producer event as the connection does, parsed by its registered schema. */ +const ingest = (events: CdpCaptureEvents, event: CdpEvent): void => + events.ingest(receiveCdpEvent(event)); describe("CDP execution-context retention", () => { it.each([ @@ -83,15 +88,15 @@ describe("CDP execution-context retention", () => { new Set(["https://app.example.test"]), ); browser.beginAuthorizedFrame({ frameId: "frame-old" }); - browser.ingest({ + ingest(browser, { method: "Runtime.executionContextCreated", params: { context: { id: 7, auxData: { frameId: "frame-old" } } }, }); - browser.ingest({ + ingest(browser, { method: "Runtime.executionContextDestroyed", params: { executionContextId: 7 }, }); - browser.ingest({ + ingest(browser, { method: "Debugger.scriptParsed", params: { scriptId: "script-1", @@ -138,11 +143,11 @@ describe("CDP execution-context retention", () => { ); browser.beginAuthorizedFrame({ frameId: "frame-old" }); browser.beginAuthorizedFrame({ frameId: "frame-new" }); - browser.ingest({ + ingest(browser, { method: "Runtime.executionContextCreated", params: { context: { id: 7, auxData: { frameId: "frame-old" } } }, }); - browser.ingest({ + ingest(browser, { method: "Debugger.scriptParsed", params: { scriptId: "script-1", @@ -150,7 +155,7 @@ describe("CDP execution-context retention", () => { executionContextId: 7, }, }); - browser.ingest({ + ingest(browser, { method: "Runtime.executionContextCreated", params: { context: { id: 7, auxData: { frameId: "frame-new" } } }, }); @@ -236,7 +241,7 @@ it.each([ }, ]; for (const event of events) { - browser.ingest(event); + ingest(browser, event); ingestElectronScriptEvent({ event, scripts, diff --git a/src/browser/CdpCaptureDocuments.test.ts b/src/browser/CdpCaptureDocuments.test.ts index 5e1e3f4777..9fd647a19a 100644 --- a/src/browser/CdpCaptureDocuments.test.ts +++ b/src/browser/CdpCaptureDocuments.test.ts @@ -5,7 +5,6 @@ import { captureDom, captureFrames, captureResources, - cdpFrameUrl, classifyCdpFrameUrl, observeCdpFrameUrl, } from "./CdpCaptureDocuments.js"; @@ -19,16 +18,25 @@ import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; const origin = "https://app.example.test"; it.each([ - [{ url: `${origin}/page?x=1#old` }, `${origin}/page?x=1#old`], + [ + { url: `${origin}/page?x=1#old` }, + { kind: "observed", url: `${origin}/page?x=1#old` }, + ], [ { url: `${origin}/page?x=1#old`, urlFragment: "#new" }, - `${origin}/page?x=1#new`, + { kind: "observed", url: `${origin}/page?x=1#new` }, + ], + [ + { url: `${origin}/page?x=1#old`, urlFragment: "" }, + { kind: "observed", url: `${origin}/page?x=1` }, + ], + [{ url: `${origin}/page`, urlFragment: null }, { kind: "invalid_fragment" }], + [ + { url: `${origin}/page`, urlFragment: "missing-hash" }, + { kind: "invalid_fragment" }, ], - [{ url: `${origin}/page?x=1#old`, urlFragment: "" }, `${origin}/page?x=1`], - [{ url: `${origin}/page`, urlFragment: null }, undefined], - [{ url: `${origin}/page`, urlFragment: "missing-hash" }, undefined], ])("preserves frame URL fragment semantics: %j", (frame, expected) => { - expect(cdpFrameUrl(frame)).toBe(expected); + expect(observeCdpFrameUrl(frame)).toMatchObject(expected); }); it("keeps source identity and scope independent while redacting transport credentials", () => { diff --git a/src/browser/CdpCaptureDocuments.ts b/src/browser/CdpCaptureDocuments.ts index bed78691d4..e4a8517e4e 100644 --- a/src/browser/CdpCaptureDocuments.ts +++ b/src/browser/CdpCaptureDocuments.ts @@ -146,14 +146,6 @@ export const classifyCdpFrameUrl = ( }; }; -/** Read the complete identity only when the protocol established it. */ -export const cdpFrameUrl = ( - frame: UnknownRecord | undefined, -): string | undefined => { - const observed = observeCdpFrameUrl(frame); - return observed.kind === "observed" ? observed.url : undefined; -}; - /** Normalize every allowed resource. */ export const captureResources = ( tree: CdpResourceTree, diff --git a/src/browser/CdpCaptureEventHandlers.ts b/src/browser/CdpCaptureEventHandlers.ts index 8f7e4db744..9b9a71f5a7 100644 --- a/src/browser/CdpCaptureEventHandlers.ts +++ b/src/browser/CdpCaptureEventHandlers.ts @@ -10,14 +10,11 @@ import { readCdpScriptParsed, selectCdpScriptFrame, } from "./CdpScriptContextFacts.js"; -import { - selectCdpFrameIdentity, - cdpFrameEventFacts, -} from "./CdpFrameIdentity.js"; +import { selectCdpFrameIdentity } from "./CdpFrameIdentity.js"; import type { WebPageInspection } from "../domain/browserObservationSchemas.js"; import { sanitizeBrowserUrl } from "../domain/browserObservation.js"; -import { observeCdpFrameUrl } from "./CdpCaptureDocuments.js"; -import { observedFrameUrl } from "./protocol/CdpFrameTree.js"; +import type { CdpFrameEvent } from "./protocol/CdpEvents.js"; +import { observedFrameUrl, reportedFrameUrl } from "./protocol/CdpFrameTree.js"; import { inferJsonShape, type JsonShapeCapacityFailure, @@ -738,14 +735,10 @@ export const handleWebSocketCreated = ( export const handleFrameNavigated = ( state: CdpCaptureEventsState, - params: unknown, + { facts: frameFacts, url }: CdpFrameEvent, ): void => { const document = state.document; if (document === undefined) return; - const frameFacts = cdpFrameEventFacts({ - method: "Page.frameNavigated", - params, - }); const identity = selectCdpFrameIdentity(frameFacts, document.current.frameId); if (identity.identityIssue !== null || identity.parentIssue !== null) { state.completeness.exclude("frames", "invalid_protocol_value"); @@ -774,10 +767,10 @@ export const handleFrameNavigated = ( const comparison = document.observe({ frameId: identity.frameId, loaderId: frameFacts.loaderId, - url: observedFrameUrl(observeCdpFrameUrl(frameFacts.source)), + url: observedFrameUrl(url), }); if (comparison === "same") return; - const rawUrl = cdpStringValue(frameFacts.source?.url); + const rawUrl = reportedFrameUrl(url); if ( isHttpUrl(rawUrl) && allowedSanitizedUrl(rawUrl, state.allowedOrigins) === undefined diff --git a/src/browser/CdpCaptureEvents.consoleTimestamp.test.ts b/src/browser/CdpCaptureEvents.consoleTimestamp.test.ts index fd5604d696..7c09fcc268 100644 --- a/src/browser/CdpCaptureEvents.consoleTimestamp.test.ts +++ b/src/browser/CdpCaptureEvents.consoleTimestamp.test.ts @@ -3,6 +3,7 @@ import { expect, it } from "vitest"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; const origin = "http://127.0.0.1:43127"; @@ -23,7 +24,9 @@ const captureWithConsoleTimestamp = (timestamp: unknown): CdpCaptureEvents => { }, }; if (timestamp !== undefined) params.timestamp = timestamp; - capture.ingest({ method: "Runtime.consoleAPICalled", params }); + capture.ingest( + receiveCdpEvent({ method: "Runtime.consoleAPICalled", params }), + ); return capture; }; diff --git a/src/browser/CdpCaptureEvents.coverageStart.test.ts b/src/browser/CdpCaptureEvents.coverageStart.test.ts index fe5b521b54..3061dc4031 100644 --- a/src/browser/CdpCaptureEvents.coverageStart.test.ts +++ b/src/browser/CdpCaptureEvents.coverageStart.test.ts @@ -1,6 +1,7 @@ import { afterEach, expect, it, vi } from "vitest"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; afterEach(() => vi.useRealTimers()); @@ -17,10 +18,12 @@ it("starts each domain at its first event or enable acknowledgment, preserving e ); events.beginAuthorizedFrame({ frameId: "main" }); vi.setSystemTime(new Date("2026-10-24T00:00:01.000Z")); - events.ingest({ - method: "Network.loadingFinished", - params: { requestId: "unobserved", encodedDataLength: 0 }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.loadingFinished", + params: { requestId: "unobserved", encodedDataLength: 0 }, + }), + ); vi.setSystemTime(new Date("2026-10-24T00:00:02.000Z")); events.markDomainEnabled("Network"); events.markDomainEnabled("Runtime"); diff --git a/src/browser/CdpCaptureEvents.eventBudget.test.ts b/src/browser/CdpCaptureEvents.eventBudget.test.ts index 166c366efb..260f85b626 100644 --- a/src/browser/CdpCaptureEvents.eventBudget.test.ts +++ b/src/browser/CdpCaptureEvents.eventBudget.test.ts @@ -3,6 +3,7 @@ import { expect, it } from "vitest"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; const origin = "http://127.0.0.1:43127"; @@ -25,19 +26,21 @@ it("admits console events until the shared retained-event budget and reports the const total = Math.ceil(WEB_RUNTIME_LIMITS.retainedEventBytes / text.length) + 2; for (let index = 0; index < total; index += 1) - events.ingest({ - method: "Runtime.consoleAPICalled", - params: { - type: "log", - timestamp: index, - args: [{ type: "string", value: text }], - stackTrace: { - callFrames: [ - { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, - ], + events.ingest( + receiveCdpEvent({ + method: "Runtime.consoleAPICalled", + params: { + type: "log", + timestamp: index, + args: [{ type: "string", value: text }], + stackTrace: { + callFrames: [ + { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, + ], + }, }, - }, - }); + }), + ); expect(events.console.length).toBeLessThan(total); expect(events.console.length).toBeGreaterThan(0); const snapshot = events.completeness.snapshot(); @@ -49,50 +52,58 @@ it("admits console events until the shared retained-event budget and reports the it("keeps a small console inventory admitted under the budget untouched", () => { const events = createEvents(); for (let index = 0; index < 16; index += 1) - events.ingest({ - method: "Runtime.consoleAPICalled", - params: { - type: "log", - timestamp: index, - args: [{ type: "string", value: `entry ${String(index)}` }], - stackTrace: { - callFrames: [ - { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, - ], + events.ingest( + receiveCdpEvent({ + method: "Runtime.consoleAPICalled", + params: { + type: "log", + timestamp: index, + args: [{ type: "string", value: `entry ${String(index)}` }], + stackTrace: { + callFrames: [ + { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, + ], + }, }, - }, - }); + }), + ); expect(events.console).toHaveLength(16); expect(events.completeness.snapshot().dropped_events.total).toBe(0); }); it("drops a websocket frame whose retained shape alone exceeds the shared budget", () => { const events = createEvents(); - events.ingest({ - method: "Network.webSocketCreated", - params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, - }); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { opcode: 1, payloadData: '{"small":"frame"}' }, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketCreated", + params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { opcode: 1, payloadData: '{"small":"frame"}' }, + }, + }), + ); const keys = Array.from( { length: 120_000 }, (_value, index) => `key${String(index)}`, ); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { - opcode: 1, - payloadData: `{${keys.map((key) => `"${key}":"v"`).join(",")}}`, + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { + opcode: 1, + payloadData: `{${keys.map((key) => `"${key}":"v"`).join(",")}}`, + }, }, - }, - }); + }), + ); const connection = events.webSocketConnectionsById.get("socket"); expect(connection?.events).toHaveLength(1); const snapshot = events.completeness.snapshot(); @@ -106,38 +117,44 @@ it("spends one shared allowance across console entries and websocket frames", () // Seven megabyte console entries leave roughly one megabyte of the shared // allowance, so a shape that fits an empty allowance no longer fits. for (let index = 0; index < 7; index += 1) - events.ingest({ - method: "Runtime.consoleAPICalled", - params: { - type: "log", - timestamp: index, - args: [{ type: "string", value: text }], - stackTrace: { - callFrames: [ - { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, - ], + events.ingest( + receiveCdpEvent({ + method: "Runtime.consoleAPICalled", + params: { + type: "log", + timestamp: index, + args: [{ type: "string", value: text }], + stackTrace: { + callFrames: [ + { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, + ], + }, }, - }, - }); + }), + ); expect(events.console).toHaveLength(7); - events.ingest({ - method: "Network.webSocketCreated", - params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketCreated", + params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, + }), + ); const keys = Array.from( { length: 20_000 }, (_value, index) => `key${String(index)}`, ); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { - opcode: 1, - payloadData: `{${keys.map((key) => `"${key}":"v"`).join(",")}}`, + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { + opcode: 1, + payloadData: `{${keys.map((key) => `"${key}":"v"`).join(",")}}`, + }, }, - }, - }); + }), + ); expect(events.webSocketConnectionsById.get("socket")?.events).toHaveLength(0); const snapshot = events.completeness.snapshot(); expect(snapshot.dropped_events.console_events).toBe(0); diff --git a/src/browser/CdpCaptureEvents.redirectBodyShape.test.ts b/src/browser/CdpCaptureEvents.redirectBodyShape.test.ts index 26cb7593ee..1ef9c76faa 100644 --- a/src/browser/CdpCaptureEvents.redirectBodyShape.test.ts +++ b/src/browser/CdpCaptureEvents.redirectBodyShape.test.ts @@ -2,6 +2,7 @@ import { expect, it } from "vitest"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; it("preserves an already captured response shape without marking it unavailable", () => { const origin = "http://127.0.0.1:43127"; @@ -14,31 +15,35 @@ it("preserves an already captured response shape without marking it unavailable" }), new Set([origin]), ); - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId: "request-1", - initiator: { type: "other" }, - request: { - url: `${origin}/prior`, - method: "POST", - headers: { "Content-Type": "application/json" }, - postData: '{"request":true}', + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId: "request-1", + initiator: { type: "other" }, + request: { + url: `${origin}/prior`, + method: "POST", + headers: { "Content-Type": "application/json" }, + postData: '{"request":true}', + }, + timestamp: 1, }, - timestamp: 1, - }, - }); - events.ingest({ - method: "Network.responseReceived", - params: { - requestId: "request-1", - response: { - url: `${origin}/prior`, - status: 200, - mimeType: "application/json", + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId: "request-1", + response: { + url: `${origin}/prior`, + status: 200, + mimeType: "application/json", + }, }, - }, - }); + }), + ); const candidate = events.responseBodyRequests()[0]; expect(candidate).toBeDefined(); events.ingestResponseBody(candidate!, { @@ -49,16 +54,18 @@ it("preserves an already captured response shape without marking it unavailable" expect(capturedShape).toBeDefined(); expect(capturedShape).not.toBeNull(); - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId: "request-1", - request: { url: `${origin}/continuation`, method: "GET" }, - initiator: { type: "other" }, - redirectResponse: null, - timestamp: 2, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId: "request-1", + request: { url: `${origin}/continuation`, method: "GET" }, + initiator: { type: "other" }, + redirectResponse: null, + timestamp: 2, + }, + }), + ); expect(events.network.get("request-1")?.body_shapes.response).toEqual( capturedShape, diff --git a/src/browser/CdpCaptureEvents.shapeBudget.test.ts b/src/browser/CdpCaptureEvents.shapeBudget.test.ts index 81e930f58f..3a203b8197 100644 --- a/src/browser/CdpCaptureEvents.shapeBudget.test.ts +++ b/src/browser/CdpCaptureEvents.shapeBudget.test.ts @@ -3,6 +3,7 @@ import { expect, it } from "vitest"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; const origin = "http://127.0.0.1:43127"; const deep = (depth: number) => '{"a":'.repeat(depth) + "0" + "}".repeat(depth); @@ -24,42 +25,46 @@ const request = ( body: string, redirect = false, ) => { - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId: id, - timestamp: redirect ? 2 : 1, - initiator: { type: "other" }, - request: { - url: `${origin}/${redirect ? "next" : "first"}`, - method: "POST", - headers: { "Content-Type": "application/json" }, - postData: body, + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId: id, + timestamp: redirect ? 2 : 1, + initiator: { type: "other" }, + request: { + url: `${origin}/${redirect ? "next" : "first"}`, + method: "POST", + headers: { "Content-Type": "application/json" }, + postData: body, + }, + ...(redirect + ? { + redirectResponse: { + url: `${origin}/first`, + status: 302, + encodedDataLength: 0, + }, + } + : {}), }, - ...(redirect - ? { - redirectResponse: { - url: `${origin}/first`, - status: 302, - encodedDataLength: 0, - }, - } - : {}), - }, - }); + }), + ); }; const response = (events: CdpCaptureEvents, id: string, body: string) => { - events.ingest({ - method: "Network.responseReceived", - params: { - requestId: id, - response: { - url: `${origin}/first`, - status: 200, - mimeType: "application/json", + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId: id, + response: { + url: `${origin}/first`, + status: 200, + mimeType: "application/json", + }, }, - }, - }); + }), + ); const candidate = events .responseBodyRequests() .find(({ requestId }) => requestId === id); @@ -69,15 +74,19 @@ const response = (events: CdpCaptureEvents, id: string, body: string) => { return candidate; }; const openSocket = (events: CdpCaptureEvents) => - events.ingest({ - method: "Network.webSocketCreated", - params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketCreated", + params: { requestId: "socket", url: `ws://${origin.slice(7)}/live` }, + }), + ); const frame = (events: CdpCaptureEvents, payloadData: string) => - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { requestId: "socket", response: { opcode: 1, payloadData } }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { requestId: "socket", response: { opcode: 1, payloadData } }, + }), + ); it.each([ ["\tAPPLICATION/JSON ; charset=utf-8\t", true], @@ -93,34 +102,38 @@ it.each([ "admits shapes only from valid media types while preserving %j", (mediaType, selected) => { const events = createEvents(); - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId: "typed", - timestamp: 1, - initiator: { type: "other" }, - request: { - url: `${origin}/typed`, - method: "POST", - headers: { "Content-Type": mediaType }, - postData: '{"count":1}', + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId: "typed", + timestamp: 1, + initiator: { type: "other" }, + request: { + url: `${origin}/typed`, + method: "POST", + headers: { "Content-Type": mediaType }, + postData: '{"count":1}', + }, }, - }, - }); + }), + ); expect(events.network.get("typed")?.body_shapes.request !== null).toBe( selected, ); - events.ingest({ - method: "Network.responseReceived", - params: { - requestId: "typed", - response: { - url: `${origin}/typed`, - status: 200, - mimeType: mediaType, + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId: "typed", + response: { + url: `${origin}/typed`, + status: 200, + mimeType: mediaType, + }, }, - }, - }); + }), + ); expect(events.responseBodyRequests().length).toBe(selected ? 1 : 0); expect(events.network.get("typed")?.mime_type).toBe(mediaType); }, @@ -201,13 +214,15 @@ it("refunds replaced and removed request records while ignoring stale response o events.ingestResponseBody(stale, { body: deep(760), base64Encoded: false }); expect(events.retainedEventBytes).toBe(retained); expect(events.network.get("redirect")?.body_shapes.response).toBeNull(); - events.ingest({ - method: "Network.responseReceived", - params: { - requestId: "redirect", - response: { url: "https://excluded.invalid/next", status: 200 }, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId: "redirect", + response: { url: "https://excluded.invalid/next", status: 200 }, + }, + }), + ); expect(events.network.has("redirect")).toBe(false); expect(events.retainedEventBytes).toBe(0); request(events, "fresh", deep(600)); @@ -222,19 +237,21 @@ it("refunds replaced and removed request records while ignoring stale response o it("shares the remaining allowance across console entries, body shapes and websocket shapes", () => { const events = createEvents(); - events.ingest({ - method: "Runtime.consoleAPICalled", - params: { - type: "log", - timestamp: 1, - args: [{ type: "string", value: "x".repeat(1024 * 1024) }], - stackTrace: { - callFrames: [ - { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, - ], + events.ingest( + receiveCdpEvent({ + method: "Runtime.consoleAPICalled", + params: { + type: "log", + timestamp: 1, + args: [{ type: "string", value: "x".repeat(1024 * 1024) }], + stackTrace: { + callFrames: [ + { url: `${origin}/app.js`, lineNumber: 0, columnNumber: 0 }, + ], + }, }, - }, - }); + }), + ); request(events, "body", deep(600)); expect(events.console).toHaveLength(1); expect(events.network.get("body")?.body_shapes.status).toBe("included"); diff --git a/src/browser/CdpCaptureEvents.ts b/src/browser/CdpCaptureEvents.ts index 4c2435da61..ff3a0c0c3d 100644 --- a/src/browser/CdpCaptureEvents.ts +++ b/src/browser/CdpCaptureEvents.ts @@ -2,7 +2,7 @@ import { readCdpRequestWillBeSent } from "./CdpNetworkEventFacts.js"; import type { CdpContextFrameClaim } from "./CdpScriptContextFacts.js"; import type { InspectWebPageInput } from "../domain/browserObservation.js"; import type { WebPageInspection } from "../domain/browserObservationSchemas.js"; -import type { CdpEvent } from "./CdpConnection.js"; +import type { CdpReceivedEvent } from "./CdpConnection.js"; import type { CdpCommandResult } from "./protocol/CdpCommands.js"; import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; import * as bodyShapes from "./CdpCaptureEventBodyShapes.js"; @@ -138,15 +138,15 @@ export class CdpCaptureEvents implements CdpCaptureEventsState { ); } - ingest(event: CdpEvent): void { + ingest(event: CdpReceivedEvent): void { if (this.document !== undefined) { if (event.method.startsWith("Network.")) this.markDomainEnabled("Network"); if (event.method.startsWith("Runtime.")) this.markDomainEnabled("Runtime"); } - if (event.method === "Page.frameNavigated") { - handlers.handleFrameNavigated(this, event.params); + if (event.registered?.method === "Page.frameNavigated") { + handlers.handleFrameNavigated(this, event.registered.payload); return; } const params = recordValue(event.params); diff --git a/src/browser/CdpCaptureEvents.webSocketFrames.test.ts b/src/browser/CdpCaptureEvents.webSocketFrames.test.ts index 3c3fa08439..876bc07f88 100644 --- a/src/browser/CdpCaptureEvents.webSocketFrames.test.ts +++ b/src/browser/CdpCaptureEvents.webSocketFrames.test.ts @@ -3,6 +3,7 @@ import { expect, it } from "vitest"; import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; const origin = "https://example.test"; @@ -24,20 +25,24 @@ const captureFrame = ( includePayload = true, ) => { const events = createEvents(); - events.ingest({ - method: "Network.webSocketCreated", - params: { requestId: "socket", url: "wss://example.test/live" }, - }); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { - ...(includeOpcode ? { opcode } : {}), - ...(includePayload ? { payloadData } : {}), + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketCreated", + params: { requestId: "socket", url: "wss://example.test/live" }, + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { + ...(includeOpcode ? { opcode } : {}), + ...(includePayload ? { payloadData } : {}), + }, }, - }, - }); + }), + ); return { events, frame: events.webSocketConnectionsById.get("socket")?.events[0], diff --git a/src/browser/CdpConnection.ts b/src/browser/CdpConnection.ts index 8e1d255c35..709ec24f9e 100644 --- a/src/browser/CdpConnection.ts +++ b/src/browser/CdpConnection.ts @@ -12,6 +12,10 @@ import { type CdpCommandParams, type CdpCommandResult, } from "./protocol/CdpCommands.js"; +import { + registeredCdpEvent, + type CdpRegisteredEvent, +} from "./protocol/CdpEvents.js"; import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js"; import { cdpCleanupGraceExpired, @@ -29,13 +33,26 @@ import { isRecord } from "../domain/isRecord.js"; // wrap to a negative number, which disables its limit check. const MAX_WEBSOCKET_PAYLOAD_BYTES = 0x7fff_ffff; +/** One event message as the producer sent it. */ export interface CdpEvent { readonly method: string; readonly params: unknown; readonly sessionId?: string | undefined; } -export interface CdpTransportEvent extends CdpEvent { +/** An event as subscribers receive it: raw payload plus its registered parse. */ +export interface CdpReceivedEvent extends CdpEvent { + /** The payload parsed once by its registered schema; undefined for an unregistered event. */ + readonly registered: CdpRegisteredEvent | undefined; +} + +/** Admit one event message: parse its payload once by its registered schema. */ +export const receiveCdpEvent = (event: CdpEvent): CdpReceivedEvent => ({ + ...event, + registered: registeredCdpEvent(event.method, event.params), +}); + +export interface CdpTransportEvent extends CdpReceivedEvent { /** Original WebSocket message payload size, before JSON parsing. */ readonly wireBytes: number; } @@ -334,14 +351,15 @@ class CdpTransportCore { this.#failPending("protocol_error"); return; } - const wireBytes = bytes.byteLength; const event: CdpTransportEvent = { - method: message.method, - params: "params" in message ? message.params : {}, - wireBytes, - ...(typeof message.sessionId === "string" - ? { sessionId: message.sessionId } - : {}), + ...receiveCdpEvent({ + method: message.method, + params: "params" in message ? message.params : {}, + ...(typeof message.sessionId === "string" + ? { sessionId: message.sessionId } + : {}), + }), + wireBytes: bytes.byteLength, }; for (const listener of this.#listeners) listener(event); } diff --git a/src/browser/CdpElectronInspection.test.ts b/src/browser/CdpElectronInspection.test.ts index ecf26ce85a..1f72f47c1c 100644 --- a/src/browser/CdpElectronInspection.test.ts +++ b/src/browser/CdpElectronInspection.test.ts @@ -16,7 +16,11 @@ import { captureFrames, inspectCdpElectronPage, } from "./CdpElectronInspection.js"; -import type { CdpEvent, CdpConnection } from "./CdpConnection.js"; +import { + receiveCdpEvent, + type CdpEvent, + type CdpConnection, +} from "./CdpConnection.js"; import { ingestElectronScriptEvent, type ElectronScriptDraft, @@ -119,7 +123,7 @@ it.each([ }; const connection = { onEvent: (value: typeof listener) => { - listener = value; + listener = (event) => value(receiveCdpEvent(event)); return () => {}; }, send: fakeCdpSend(async (method) => { @@ -329,7 +333,7 @@ it.each([ }; const connection = { onEvent: (value: typeof listener) => { - listener = value; + listener = (event) => value(receiveCdpEvent(event)); return () => {}; }, send: fakeCdpSend(async (method) => { @@ -773,7 +777,7 @@ it.each([ }; const connection = { onEvent: (value: typeof listener) => { - listener = value; + listener = (event) => value(receiveCdpEvent(event)); return () => {}; }, send: fakeCdpSend(async (method) => { @@ -907,7 +911,7 @@ it.each([ }; const connection = { onEvent: (value: typeof listener) => { - listener = value; + listener = (event) => value(receiveCdpEvent(event)); return () => {}; }, send: fakeCdpSend(async (method) => { diff --git a/src/browser/CdpElectronInspection.ts b/src/browser/CdpElectronInspection.ts index 9dd0da8d49..cd1854a578 100644 --- a/src/browser/CdpElectronInspection.ts +++ b/src/browser/CdpElectronInspection.ts @@ -8,7 +8,7 @@ import type { } from "../domain/javascript/electronObservation.js"; import { BrowserObservationError } from "../domain/browserObservationError.js"; import { cancelledBy } from "../domain/analysisErrorCore.js"; -import type { CdpConnection, CdpEvent } from "./CdpConnection.js"; +import type { CdpConnection, CdpReceivedEvent } from "./CdpConnection.js"; import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; import { delayWithCancellation, cdpStringValue } from "./CdpCaptureValues.js"; @@ -17,14 +17,15 @@ import { type CdpCommandResult, } from "./protocol/CdpCommands.js"; import { - cdpFrameUrl, snapshotDocuments, type CdpFrameUrlObservation, } from "./CdpCaptureDocuments.js"; -import { cdpFrameEventFacts, type CdpFrameFacts } from "./CdpFrameIdentity.js"; -import type { - CdpFrameTree, - CdpFrameTreeNode, +import type { CdpFrameFacts } from "./CdpFrameIdentity.js"; +import { cdpFrameEvent } from "./protocol/CdpEvents.js"; +import { + observedFrameUrl, + type CdpFrameTree, + type CdpFrameTreeNode, } from "./protocol/CdpFrameTree.js"; import { snapshotDocumentNodes, snapshotNodeAt } from "./CdpSnapshotNodes.js"; import { cdpSnapshotString } from "./CdpSnapshotStrings.js"; @@ -304,35 +305,30 @@ const unprovenFrameIds = ( /** Lifecycle events invalidate future attribution, never earlier script facts. */ const advanceFrameGeneration = ( - event: CdpEvent, + event: CdpReceivedEvent, state: ElectronInspectionState, ): void => { - const facts = cdpFrameEventFacts(event); + const frame = cdpFrameEvent(event); + if (frame === undefined) return; + const { facts, url: observation } = frame; // A same-document event changes the cached identity, never its generation // or authority. Later full-frame replay must compare with that current URL. - if (event.method === "Page.navigatedWithinDocument") { + if (facts.kind === "within_document") { const id = facts.frameId; if (id === null) return; if (id === state.mainFrameId) state.navigationDuringCapture = true; const previous = state.frameDocuments.get(id); if (previous === undefined) return; - const url = cdpFrameUrl(facts.source); + const url = observedFrameUrl(observation); if (url === undefined || url === "") state.frameDocuments.delete(id); else state.frameDocuments.set(id, { ...previous, url }); return; } - if ( - ![ - "Page.frameNavigated", - "Page.frameDetached", - "Page.frameAttached", - ].includes(event.method) - ) - return; + if (facts.kind === "requested") return; const id = facts.frameId; if (id === null) return; const document = - facts.kind === "navigated" ? frameDocument(facts) : undefined; + facts.kind === "navigated" ? frameDocument(facts, observation) : undefined; const previous = state.frameDocuments.get(id); if ( document !== undefined && @@ -411,14 +407,9 @@ const invalidateFrameGenerations = ( /** Only a known URL and loader together can prove a duplicate document event. */ const frameDocument = ( facts: CdpFrameFacts, - observation?: CdpFrameUrlObservation, + observation: CdpFrameUrlObservation, ): ElectronFrameDocument | undefined => { - const url = - observation === undefined - ? cdpFrameUrl(facts.source) - : observation.kind === "observed" - ? observation.url - : undefined; + const url = observedFrameUrl(observation); if ( url === undefined || url === "" || @@ -691,7 +682,7 @@ export const captureFrames = async ( parentId !== null && provedFrames.has(enclosing) && parentId === enclosing.facts.frameId; - if (facts.source === undefined || frameId === null || !ancestryKnown) { + if (frameId === null || !ancestryKnown) { completeness.exclude("frames", "invalid_protocol_value"); continue; } diff --git a/src/browser/CdpFrameIdentity.test.ts b/src/browser/CdpFrameIdentity.test.ts index f710793b2f..e7f80a43d1 100644 --- a/src/browser/CdpFrameIdentity.test.ts +++ b/src/browser/CdpFrameIdentity.test.ts @@ -1,8 +1,15 @@ import { describe, expect, it } from "vitest"; -import { - selectCdpFrameIdentity, - cdpFrameEventFacts, -} from "./CdpFrameIdentity.js"; +import { selectCdpFrameIdentity } from "./CdpFrameIdentity.js"; +import { receiveCdpEvent, type CdpEvent } from "./CdpConnection.js"; +import { cdpFrameEvent } from "./protocol/CdpEvents.js"; + +/** Frame facts as the connection's registered event schema parses them. */ +const cdpFrameEventFacts = (event: CdpEvent) => { + const frame = cdpFrameEvent(receiveCdpEvent(event)); + if (frame === undefined) + throw new Error(`${event.method} is not a frame event`); + return frame.facts; +}; describe("CDP frame identity ownership", () => { it.each([ diff --git a/src/browser/CdpFrameIdentity.ts b/src/browser/CdpFrameIdentity.ts index 8bc9963618..c5a5d11751 100644 --- a/src/browser/CdpFrameIdentity.ts +++ b/src/browser/CdpFrameIdentity.ts @@ -3,7 +3,6 @@ import { cdpStringValue, type UnknownRecord, } from "./CdpCaptureValues.js"; -import type { CdpEvent } from "./CdpConnection.js"; export type FrameSelection = "main" | "other" | "unknown"; export type FrameParentRelation = @@ -144,8 +143,6 @@ export interface CdpFrameFacts extends Pick< | "within_document" | "requested" | "not_applicable"; - /** Borrowed only for the frame URL observation owner. */ - readonly source: UnknownRecord | undefined; readonly loaderId: string | undefined; readonly loaderIssue: "invalid_loader_id" | null; } @@ -165,7 +162,6 @@ export const cdpFrameRecordFacts = ( const frameId = nonEmptyString(source?.id) ?? null; return { kind: "record", - source, frameId, identityIssue: identityIssueFor(true, source, source?.id), ...frameParentFacts(source), @@ -173,23 +169,25 @@ export const cdpFrameRecordFacts = ( }; }; -/** Event method selects its protocol shape; unrelated aliases never supply identity. */ -export const cdpFrameEventFacts = (event: CdpEvent): CdpFrameFacts => { - const kind = - event.method === "Page.frameNavigated" - ? "navigated" - : event.method === "Page.frameAttached" - ? "attached" - : event.method === "Page.frameDetached" - ? "detached" - : event.method === "Page.navigatedWithinDocument" - ? "within_document" - : event.method === "Page.frameRequestedNavigation" - ? "requested" - : "not_applicable"; +/** The frame lifecycle events whose payload carries frame identity. */ +export type CdpFrameEventKind = + | "navigated" + | "attached" + | "detached" + | "within_document" + | "requested"; + +/** + * Parse one frame lifecycle event payload by its declared protocol shape. The + * CDP event registry (`protocol/CdpEvents.ts`) is the only caller, so every + * subscriber reads these facts rather than the raw payload. + */ +export const cdpFrameEventPayloadFacts = ( + kind: CdpFrameEventKind, + rawParams: unknown, +): CdpFrameFacts => { const empty: CdpFrameFacts = { kind, - source: undefined, frameId: null, identityIssue: null, parentRelation: "not_applicable", @@ -198,20 +196,18 @@ export const cdpFrameEventFacts = (event: CdpEvent): CdpFrameFacts => { loaderId: undefined, loaderIssue: null, }; - if (kind === "not_applicable") return empty; - const params = recordValue(event.params); + const params = recordValue(rawParams); if (params === undefined) return { ...empty, identityIssue: - event.params === undefined ? "missing_params" : "invalid_params", + rawParams === undefined ? "missing_params" : "invalid_params", }; if (kind === "navigated") return { ...cdpFrameRecordFacts(recordValue(params.frame)), kind }; const frameId = nonEmptyString(params.frameId) ?? null; return { kind, - source: params, frameId, identityIssue: identityIssueFor(false, undefined, params.frameId), ...(kind === "attached" diff --git a/src/browser/CdpLargeBase64.test.ts b/src/browser/CdpLargeBase64.test.ts index ffe7e05e7e..57bbe4c7a4 100644 --- a/src/browser/CdpLargeBase64.test.ts +++ b/src/browser/CdpLargeBase64.test.ts @@ -6,6 +6,7 @@ import { inspectWebPageInputSchema } from "../domain/browserObservation.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; import { captureStorageFingerprints } from "./CdpCaptureStorageFingerprints.js"; import type { CdpConnection } from "./CdpConnection.js"; +import { receiveCdpEvent } from "./CdpConnection.js"; const ORIGIN = "https://example.test"; const CDP_ENDPOINT = "http://127.0.0.1:9222"; @@ -66,26 +67,30 @@ const startJsonResponse = ( requestId: string, path: string, ): void => { - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId, - request: { url: `${ORIGIN}${path}`, method: "GET" }, - initiator: { type: "other" }, - timestamp: 1, - }, - }); - events.ingest({ - method: "Network.responseReceived", - params: { - requestId, - response: { - url: `${ORIGIN}${path}`, - status: 200, - mimeType: "application/json", + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId, + request: { url: `${ORIGIN}${path}`, method: "GET" }, + initiator: { type: "other" }, + timestamp: 1, }, - }, - }); + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId, + response: { + url: `${ORIGIN}${path}`, + status: 200, + mimeType: "application/json", + }, + }, + }), + ); }; it("fingerprints large cached bodies and retains CDP padding-bit acceptance", async () => { @@ -151,28 +156,34 @@ it("decodes large JSON response bodies and preserves malformed and pad-bit behav it("counts large binary WebSocket frames without accepting malformed base64", () => { const events = createEvents(false); const encoded = Buffer.alloc(BODY_BYTES, 0x81).toString("base64"); - events.ingest({ - method: "Network.webSocketCreated", - params: { requestId: "socket", url: "wss://example.test/socket" }, - }); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { opcode: 2, payloadData: encoded }, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketCreated", + params: { requestId: "socket", url: "wss://example.test/socket" }, + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { opcode: 2, payloadData: encoded }, + }, + }), + ); expect( events.webSocketConnectionsById.get("socket")?.events[0]?.payload_bytes, ).toBe(BODY_BYTES); - events.ingest({ - method: "Network.webSocketFrameReceived", - params: { - requestId: "socket", - response: { opcode: 2, payloadData: "%%%not-base64%%%" }, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Network.webSocketFrameReceived", + params: { + requestId: "socket", + response: { opcode: 2, payloadData: "%%%not-base64%%%" }, + }, + }), + ); expect( events.webSocketConnectionsById.get("socket")?.events[1]?.payload_bytes, ).toBeNull(); diff --git a/src/browser/CdpObservationSession.ts b/src/browser/CdpObservationSession.ts index de6608cf9d..31525930a2 100644 --- a/src/browser/CdpObservationSession.ts +++ b/src/browser/CdpObservationSession.ts @@ -11,11 +11,7 @@ import { import { BrowserObservationError } from "../domain/browserObservationError.js"; import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js"; import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; -import { - CdpConnection, - type CdpEvent, - type CdpTransportEvent, -} from "./CdpConnection.js"; +import { CdpConnection, type CdpTransportEvent } from "./CdpConnection.js"; import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; import { authorizedMainFrame } from "./CdpAuthorizedMainFrame.js"; import { @@ -27,16 +23,11 @@ import { cdpStringValue, type UnknownRecord, } from "./CdpCaptureValues.js"; -import { - observeCdpFrameUrl, - classifyCdpFrameUrl, -} from "./CdpCaptureDocuments.js"; -import { - selectCdpFrameIdentity, - cdpFrameEventFacts, -} from "./CdpFrameIdentity.js"; +import { classifyCdpFrameUrl } from "./CdpCaptureDocuments.js"; +import { selectCdpFrameIdentity } from "./CdpFrameIdentity.js"; import type { CdpCommandResult } from "./protocol/CdpCommands.js"; -import { observedFrameUrl } from "./protocol/CdpFrameTree.js"; +import { observedFrameUrl, reportedFrameUrl } from "./protocol/CdpFrameTree.js"; +import { cdpFrameEvent, type CdpFrameEvent } from "./protocol/CdpEvents.js"; import { cdpTargetEventMatches } from "./CdpTargetEvents.js"; import { @@ -253,16 +244,14 @@ class TimelineCapture { const contextOnly = bufferedBeforeArm && hasNoComparableProducerTimestamp(event.method); if (contextOnly) this.#hasUnknownEventTime = true; + const frame = cdpFrameEvent(event); + if (frame?.facts.kind === "requested") + return this.#navigationRequested(frame, params, contextOnly); + if (frame?.facts.kind === "navigated") + return this.#navigationCommitted(frame, params, contextOnly); + if (frame?.facts.kind === "within_document") + return this.#sameDocument(frame, params, contextOnly); switch (event.method) { - case "Page.frameRequestedNavigation": - this.#navigationRequested(event, params, contextOnly); - break; - case "Page.frameNavigated": - this.#navigationCommitted(event, params, contextOnly); - break; - case "Page.navigatedWithinDocument": - this.#sameDocument(event, params, contextOnly); - break; case "Network.requestWillBeSent": { const facts = readCdpRequestWillBeSent(params); this.#requestStarted(facts); @@ -406,19 +395,16 @@ class TimelineCapture { } #navigationRequested( - event: CdpEvent, + frame: CdpFrameEvent, params: UnknownRecord, contextOnly: boolean, ): void { - const identity = selectCdpFrameIdentity( - cdpFrameEventFacts(event), - this.mainFrameId, - ); + const identity = selectCdpFrameIdentity(frame.facts, this.mainFrameId); if (identity.identityIssue !== null || identity.parentIssue !== null) this.completeness.exclude("timeline", "invalid_protocol_value"); if (identity.selection !== "main") return; const reason = safeDetail(params.reason); - const rawUrl = cdpStringValue(params.url); + const rawUrl = reportedFrameUrl(frame.url); const destination = rawUrl === undefined ? undefined : scopedUrl(rawUrl, this.allowedOrigins); if (!contextOnly) this.#pendingReload = reason === "reload"; @@ -434,21 +420,17 @@ class TimelineCapture { } #navigationCommitted( - event: CdpEvent, + { facts, url: observation }: CdpFrameEvent, params: UnknownRecord, contextOnly: boolean, ): void { + // The raw record is retained as timeline evidence only. const frame = recordValue(params.frame); - const identity = selectCdpFrameIdentity( - cdpFrameEventFacts(event), - this.mainFrameId, - ); + const identity = selectCdpFrameIdentity(facts, this.mainFrameId); if (identity.identityIssue !== null || identity.parentIssue !== null) this.completeness.exclude("timeline", "invalid_protocol_value"); if (identity.selection !== "main" && !identity.isRootReplacement) return; - const observation = observeCdpFrameUrl(frame); - const rawUrl = - observation.kind === "observed" ? observation.url : undefined; + const rawUrl = observedFrameUrl(observation); const destination = classifyCdpFrameUrl(observation, this.allowedOrigins); if (identity.isRootReplacement) { this.mainFrameId = identity.frameId ?? this.mainFrameId; @@ -481,18 +463,15 @@ class TimelineCapture { } #sameDocument( - event: CdpEvent, + frame: CdpFrameEvent, params: UnknownRecord, contextOnly: boolean, ): void { - const identity = selectCdpFrameIdentity( - cdpFrameEventFacts(event), - this.mainFrameId, - ); + const identity = selectCdpFrameIdentity(frame.facts, this.mainFrameId); if (identity.identityIssue !== null || identity.parentIssue !== null) this.completeness.exclude("timeline", "invalid_protocol_value"); if (identity.selection !== "main") return; - const rawUrl = cdpStringValue(params.url); + const rawUrl = reportedFrameUrl(frame.url); const destination = scopedUrl(rawUrl, this.allowedOrigins); this.#add({ type: "same_document_navigation", diff --git a/src/browser/CdpScreenshot.ts b/src/browser/CdpScreenshot.ts index acb35ba711..596f24d126 100644 --- a/src/browser/CdpScreenshot.ts +++ b/src/browser/CdpScreenshot.ts @@ -11,10 +11,8 @@ import { BrowserObservationError } from "../domain/browserObservationError.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisCancelledError } from "../domain/analysisErrorCore.js"; import { cdpOriginScopeRefusal } from "./CdpOriginScopeError.js"; -import { - selectCdpFrameIdentity, - cdpFrameEventFacts, -} from "./CdpFrameIdentity.js"; +import { selectCdpFrameIdentity } from "./CdpFrameIdentity.js"; +import { cdpFrameEvent } from "./protocol/CdpEvents.js"; import { observedFrameUrl, type CdpFrameTree, @@ -26,11 +24,8 @@ import { unverifiedDocumentLimitation, } from "./CdpTargetSession.js"; import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; -import type { CdpConnection, CdpEvent } from "./CdpConnection.js"; -import { - observeCdpFrameUrl, - classifyCdpFrameUrl, -} from "./CdpCaptureDocuments.js"; +import type { CdpConnection, CdpReceivedEvent } from "./CdpConnection.js"; +import { classifyCdpFrameUrl } from "./CdpCaptureDocuments.js"; import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; import { readPngHeaderDimensions } from "../domain/pngHeader.js"; @@ -329,12 +324,14 @@ interface ScreenshotNavigation { } const observeScreenshotNavigation = ( - event: CdpEvent, + event: CdpReceivedEvent, origins: ReadonlySet, state: ScreenshotNavigation, ): void => { const current = state.document.current; - const frameFacts = cdpFrameEventFacts(event); + const frameEvent = cdpFrameEvent(event); + if (frameEvent === undefined) return; + const { facts: frameFacts, url: observed } = frameEvent; const identity = selectCdpFrameIdentity(frameFacts, current.frameId); if (identity.applicability === "not_applicable") return; if (identity.identityIssue !== null || identity.parentIssue !== null) { @@ -357,11 +354,10 @@ const observeScreenshotNavigation = ( if (identity.selection === "other" && !identity.isRootReplacement) return; // A requested navigation does not establish a committed document change. // The frame-tree read after capture still verifies the selected URL. - if (event.method === "Page.frameRequestedNavigation") return; - const observed = observeCdpFrameUrl(frameFacts.source); + if (frameFacts.kind === "requested") return; const facts = classifyCdpFrameUrl(observed, origins); const comparison = state.document.observe( - event.method === "Page.frameNavigated" + frameFacts.kind === "navigated" ? { frameId: identity.frameId ?? current.frameId, loaderId: frameFacts.loaderId, diff --git a/src/browser/CdpWebMcpDiscovery.ts b/src/browser/CdpWebMcpDiscovery.ts index d7c19a5a73..fb2c269c13 100644 --- a/src/browser/CdpWebMcpDiscovery.ts +++ b/src/browser/CdpWebMcpDiscovery.ts @@ -1,4 +1,5 @@ -import { cdpFrameEventFacts, type CdpFrameFacts } from "./CdpFrameIdentity.js"; +import type { CdpFrameFacts } from "./CdpFrameIdentity.js"; +import { cdpFrameEvent } from "./protocol/CdpEvents.js"; import { createHash } from "node:crypto"; import type { ProgressReporter } from "../application/ProgressReporter.js"; @@ -13,7 +14,7 @@ import { compositeKey, } from "../domain/unicodeCodePointOrder.js"; import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; -import type { CdpConnection, CdpEvent } from "./CdpConnection.js"; +import type { CdpConnection, CdpReceivedEvent } from "./CdpConnection.js"; import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; import { BrowserObservationError } from "../domain/browserObservationError.js"; import { cdpOriginScopeRefusal } from "./CdpOriginScopeError.js"; @@ -27,7 +28,6 @@ import { } from "./CdpCaptureValues.js"; import { classifyCdpFrameUrl, - observeCdpFrameUrl, type CdpFrameUrlObservation, } from "./CdpCaptureDocuments.js"; import { @@ -200,10 +200,12 @@ const ingestInitialFrameTree = ( }; const ingestFrameScopeEvent = ( - event: CdpEvent, + event: CdpReceivedEvent, state: FrameScopeState, ): boolean => { - const facts = cdpFrameEventFacts(event); + const frame = cdpFrameEvent(event); + if (frame === undefined) return false; + const { facts, url } = frame; switch (facts.kind) { case "detached": if (facts.identityIssue !== null || facts.frameId === null) { @@ -215,9 +217,9 @@ const ingestFrameScopeEvent = ( state.resolvedTransientFrames.delete(facts.frameId); return true; case "navigated": - return handleFrameUpdate(facts, state, true); + return handleFrameUpdate(facts, state, true, url); case "within_document": - return handleFrameUpdate(facts, state, false); + return handleFrameUpdate(facts, state, false, url); default: return false; } @@ -239,7 +241,7 @@ const handleFrameUpdate = ( sourceFacts: CdpFrameFacts, state: FrameScopeState, documentCommitted: boolean, - observation: CdpFrameUrlObservation = observeCdpFrameUrl(sourceFacts.source), + observation: CdpFrameUrlObservation, ): boolean => { const frameId = sourceFacts.frameId; if ( @@ -426,7 +428,7 @@ const requiredDiscoveryFrame = ( }; interface WebMcpIngestOptions { - readonly event: CdpEvent; + readonly event: CdpReceivedEvent; readonly input: DiscoverWebMcpToolsInput; readonly frames: ReadonlyMap< string, diff --git a/src/browser/PlaywrightCdpSession.ts b/src/browser/PlaywrightCdpSession.ts index 14eccd3609..ad7f097b89 100644 --- a/src/browser/PlaywrightCdpSession.ts +++ b/src/browser/PlaywrightCdpSession.ts @@ -8,6 +8,7 @@ import { type CdpCommandResult, type CdpProtocolMethod, } from "./protocol/CdpCommands.js"; +import type { CdpProtocolEvent } from "./protocol/CdpEvents.js"; /** * A Playwright CDP session that sends only registered commands and admits each @@ -19,9 +20,13 @@ export interface PlaywrightCdpSession { method: M, params?: CdpCommandParams, ): Promise>; - /** Event payloads stay unknown; each subscriber parses its own events. */ - on(event: string, listener: (params: unknown) => void): void; - off(event: string, listener: (params: unknown) => void): void; + /** + * Subscribe to one protocol event by its name in Playwright's protocol + * table. Payloads stay unknown until the event is registered in + * `protocol/CdpEvents.ts`; the subscriber parses them meanwhile. + */ + on(event: CdpProtocolEvent, listener: (params: unknown) => void): void; + off(event: CdpProtocolEvent, listener: (params: unknown) => void): void; detach(): Promise; } @@ -37,11 +42,10 @@ const registeredSession = ( operation, ), on: (event, listener) => { - // Playwright's event names are not exported apart from its overloads. - session.on(event as never, listener); + session.on(event, listener); }, off: (event, listener) => { - session.off(event as never, listener); + session.off(event, listener); }, detach: () => session.detach(), }); diff --git a/src/browser/execution/CdpExecutionWindow.test.ts b/src/browser/execution/CdpExecutionWindow.test.ts index 4a6268148d..4a3e2a1638 100644 --- a/src/browser/execution/CdpExecutionWindow.test.ts +++ b/src/browser/execution/CdpExecutionWindow.test.ts @@ -1,5 +1,6 @@ import { expect, it, vi } from "vitest"; import { CdpExecutionWindow } from "./CdpExecutionWindow.js"; +import { receiveCdpEvent } from "../CdpConnection.js"; it("settles an already lost transport without arming a timer that cannot resolve", async () => { const window = new CdpExecutionWindow({ @@ -71,10 +72,12 @@ it("keeps a root document transition distinct from a child frame event", async ( options: {}, }); const rootResult = root.start(30_000); - root.ingest({ - method: "Page.frameNavigated", - params: { frame: { id: "new-main", url: "https://example.test/" } }, - }); + root.ingest( + receiveCdpEvent({ + method: "Page.frameNavigated", + params: { frame: { id: "new-main", url: "https://example.test/" } }, + }), + ); await expect(rootResult).resolves.toBe("document_changed"); const child = new CdpExecutionWindow({ @@ -83,16 +86,18 @@ it("keeps a root document transition distinct from a child frame event", async ( options: {}, }); const childResult = child.start(30_000); - child.ingest({ - method: "Page.frameNavigated", - params: { - frame: { - id: "child-frame", - parentId: "selected-main", - url: "https://example.test/child", + child.ingest( + receiveCdpEvent({ + method: "Page.frameNavigated", + params: { + frame: { + id: "child-frame", + parentId: "selected-main", + url: "https://example.test/child", + }, }, - }, - }); + }), + ); expect(child.active).toBe(true); child.end("window_elapsed"); await expect(childResult).resolves.toBe("window_elapsed"); @@ -105,12 +110,14 @@ it("surfaces malformed frame identity as a protocol failure without guessing a t options: {}, }); const result = window.start(30_000); - window.ingest({ - method: "Page.frameNavigated", - params: { - frame: { id: "child-frame", parentId: 7, url: "https://example.test/" }, - }, - }); + window.ingest( + receiveCdpEvent({ + method: "Page.frameNavigated", + params: { + frame: { id: "child-frame", parentId: 7, url: "https://example.test/" }, + }, + }), + ); await expect(result).rejects.toMatchObject({ _tag: "BrowserObservationError", reason: "protocol_error", diff --git a/src/browser/execution/CdpExecutionWindow.ts b/src/browser/execution/CdpExecutionWindow.ts index 1e840b4d14..7042841160 100644 --- a/src/browser/execution/CdpExecutionWindow.ts +++ b/src/browser/execution/CdpExecutionWindow.ts @@ -1,13 +1,11 @@ import { cancelledBy, carriedReason } from "../../domain/analysisErrorCore.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { WebExecution } from "../../domain/webExecution.js"; -import type { CdpEvent } from "../CdpConnection.js"; +import type { CdpReceivedEvent } from "../CdpConnection.js"; import type { CdpRuntimeSession } from "./CdpRuntimeSession.js"; import { BrowserObservationError } from "../../domain/browserObservationError.js"; -import { - selectCdpFrameIdentity, - cdpFrameEventFacts, -} from "../CdpFrameIdentity.js"; +import { selectCdpFrameIdentity } from "../CdpFrameIdentity.js"; +import { cdpFrameEvent } from "../protocol/CdpEvents.js"; type EndReason = WebExecution["window"]["end_reason"]; /** One finite document-scoped window, with an actual armed point and event-driven termination. */ @@ -27,7 +25,7 @@ export class CdpExecutionWindow { ) {} /** Collection ends on a main-document replacement, never follows source URLs into another context. */ - ingest(event: CdpEvent): void { + ingest(event: CdpReceivedEvent): void { if (event.method === "Target.detachedFromTarget") { this.end("session_detached"); return; @@ -39,9 +37,10 @@ export class CdpExecutionWindow { if (!this.active) return; if (event.method === "Runtime.executionContextsCleared") this.end("document_changed"); - if (event.method === "Page.frameNavigated") { + const frame = cdpFrameEvent(event)?.facts; + if (frame?.kind === "navigated") { const identity = selectCdpFrameIdentity( - cdpFrameEventFacts(event), + frame, this.session.target.frame_id, ); if (identity.identityIssue !== null || identity.parentIssue !== null) { @@ -68,8 +67,8 @@ export class CdpExecutionWindow { return; } if ( - event.method === "Page.frameDetached" && - cdpFrameEventFacts(event).frameId === this.session.target.frame_id + frame?.kind === "detached" && + frame.frameId === this.session.target.frame_id ) this.end("document_changed"); } diff --git a/src/browser/protocol/CdpCommands.types.test.ts b/src/browser/protocol/CdpCommands.types.test.ts index b29a617767..8b55391b76 100644 --- a/src/browser/protocol/CdpCommands.types.test.ts +++ b/src/browser/protocol/CdpCommands.types.test.ts @@ -7,6 +7,7 @@ import type { CdpCommandResult, CdpDomainWith, } from "./CdpCommands.js"; +import type { CdpEventName, CdpProtocolEvent } from "./CdpEvents.js"; // `npm run typecheck` compiles this file. A `@ts-expect-error` whose line // starts to compile fails the typecheck, so these are negative compile tests. @@ -49,3 +50,19 @@ it("resolves a send to the command's parsed result", () => { targetInfos: unknown[]; }>(); }); + +// A protocol event REA has not registered a payload schema for. +type UnregisteredEvent = "Network.dataReceived"; + +it("parses only events with a registered payload schema", () => { + expectTypeOf<"Page.frameNavigated">().toExtend(); + expectTypeOf().not.toExtend(); + expectTypeOf().toExtend(); + expectTypeOf<"Page.notAnEvent">().not.toExtend(); + + // Playwright subscriptions name an event from the protocol table. + const subscribe = (session: PlaywrightCdpSession) => + // @ts-expect-error An event name outside the protocol table does not compile. + session.on("Page.notAnEvent", () => undefined); + expectTypeOf(subscribe).toBeFunction(); +}); diff --git a/src/browser/protocol/CdpEvents.test.ts b/src/browser/protocol/CdpEvents.test.ts new file mode 100644 index 0000000000..8cff0fa33f --- /dev/null +++ b/src/browser/protocol/CdpEvents.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from "vitest"; + +import { receiveCdpEvent } from "../CdpConnection.js"; +import { cdpFrameEvent } from "./CdpEvents.js"; + +describe("registered CDP event payloads", () => { + it("parses a frame event's identity and URL once, keeping the raw payload", () => { + const params = { + frame: { + id: "main", + loaderId: "loader", + url: "https://app.test/page", + urlFragment: "#section", + }, + }; + const event = receiveCdpEvent({ method: "Page.frameNavigated", params }); + expect(event.params).toBe(params); + expect(cdpFrameEvent(event)).toEqual({ + facts: expect.objectContaining({ + kind: "navigated", + frameId: "main", + loaderId: "loader", + identityIssue: null, + }), + url: { + kind: "observed", + url: "https://app.test/page#section", + scopeUrl: "https://app.test/page", + }, + }); + }); + + it.each([ + ["a missing payload", undefined, "missing_params"], + ["a non-object payload", "frame", "invalid_params"], + [ + "a non-string frame id", + { frameId: 7, url: "https://app.test/" }, + "invalid_id", + ], + ])( + "keeps %s as an explicit identity issue, never as absence", + (_label, params, issue) => { + const frame = cdpFrameEvent( + receiveCdpEvent({ method: "Page.navigatedWithinDocument", params }), + ); + expect(frame?.facts.identityIssue).toBe(issue); + }, + ); + + it("records a malformed fragment as unreadable identity with its scope URL", () => { + const frame = cdpFrameEvent( + receiveCdpEvent({ + method: "Page.frameNavigated", + params: { + frame: { id: "main", url: "https://app.test/", urlFragment: 3 }, + }, + }), + ); + expect(frame?.url).toEqual({ + kind: "invalid_fragment", + scopeUrl: "https://app.test/", + }); + }); + + it("leaves an unregistered event unparsed", () => { + const event = receiveCdpEvent({ + method: "Network.dataReceived", + params: { requestId: "1" }, + }); + expect(event.registered).toBeUndefined(); + expect(cdpFrameEvent(event)).toBeUndefined(); + }); +}); diff --git a/src/browser/protocol/CdpEvents.ts b/src/browser/protocol/CdpEvents.ts new file mode 100644 index 0000000000..5ff8a6165b --- /dev/null +++ b/src/browser/protocol/CdpEvents.ts @@ -0,0 +1,118 @@ +import type { CDPSession } from "playwright-core"; +import { z } from "zod"; + +import { + observeCdpFrameUrl, + type CdpFrameUrlObservation, +} from "../CdpCaptureDocuments.js"; +import { recordValue } from "../CdpCaptureValues.js"; +import { + cdpFrameEventPayloadFacts, + type CdpFrameEventKind, + type CdpFrameFacts, +} from "../CdpFrameIdentity.js"; + +// Playwright ships the generated protocol event table only through the +// generic `CDPSession.on` overload, which precedes its `'close'` and +// `'event'` session overloads. +type ProtocolEventOverload = On extends { + (event: infer Event, listener: never): unknown; + (event: "close", listener: never): unknown; + (event: "event", listener: never): unknown; +} + ? Event + : never; + +/** Every event name in the protocol version Playwright ships. */ +export type CdpProtocolEvent = Exclude< + ProtocolEventOverload, + symbol +>; + +/** + * One frame lifecycle event, parsed once at the connection. It has the same + * shape as a frame-tree node: identity facts plus the frame URL observation. + * Malformed identity stays in `facts` as explicit issues, never as absence. + */ +export interface CdpFrameEvent { + readonly facts: CdpFrameFacts; + /** `missing` for attach and detach events, which carry no URL. */ + readonly url: CdpFrameUrlObservation; +} + +const frameEvent = (kind: CdpFrameEventKind) => + z.unknown().transform((params): CdpFrameEvent => { + const record = recordValue(params); + const urlSource = + kind === "navigated" + ? recordValue(record?.frame) + : kind === "within_document" || kind === "requested" + ? record + : undefined; + return { + facts: cdpFrameEventPayloadFacts(kind, params), + url: observeCdpFrameUrl(urlSource), + }; + }); + +/** + * One payload schema per subscribed event. The connection parses each + * registered event once, before any subscriber sees it. A schema never + * rejects: malformed members become explicit facts that each subscriber + * reports as a protocol failure or a recorded coverage gap. + */ +const CDP_EVENT_PAYLOADS = { + "Page.frameAttached": frameEvent("attached"), + "Page.frameDetached": frameEvent("detached"), + "Page.frameNavigated": frameEvent("navigated"), + "Page.frameRequestedNavigation": frameEvent("requested"), + "Page.navigatedWithinDocument": frameEvent("within_document"), +} as const satisfies { + readonly [E in CdpProtocolEvent]?: z.ZodType; +}; + +export type CdpEventName = keyof typeof CDP_EVENT_PAYLOADS; + +export type CdpEventPayload = z.output< + (typeof CDP_EVENT_PAYLOADS)[E] +>; + +/** A registered event with its parsed payload, discriminated by method. */ +export type CdpRegisteredEvent = { + readonly [E in CdpEventName]: { + readonly method: E; + readonly payload: CdpEventPayload; + }; +}[CdpEventName]; + +const isRegistered = (method: string): method is CdpEventName => + Object.hasOwn(CDP_EVENT_PAYLOADS, method); + +/** Parse one event's payload by its registered schema, or undefined when unregistered. */ +export const registeredCdpEvent = ( + method: string, + params: unknown, +): CdpRegisteredEvent | undefined => { + if (!isRegistered(method)) return undefined; + const schema: z.ZodType = CDP_EVENT_PAYLOADS[method]; + return { + method, + payload: schema.parse(params), + } as CdpRegisteredEvent; +}; + +const FRAME_EVENTS: ReadonlySet = new Set([ + "Page.frameAttached", + "Page.frameDetached", + "Page.frameNavigated", + "Page.frameRequestedNavigation", + "Page.navigatedWithinDocument", +]); + +/** The parsed frame lifecycle payload of a registered frame event. */ +export const cdpFrameEvent = (event: { + readonly registered: CdpRegisteredEvent | undefined; +}): CdpFrameEvent | undefined => + event.registered !== undefined && FRAME_EVENTS.has(event.registered.method) + ? event.registered.payload + : undefined; diff --git a/src/browser/protocol/CdpFrameTree.ts b/src/browser/protocol/CdpFrameTree.ts index c197d3e957..070fff2a08 100644 --- a/src/browser/protocol/CdpFrameTree.ts +++ b/src/browser/protocol/CdpFrameTree.ts @@ -147,6 +147,15 @@ export const cdpResourceTreeReplySchema = z }; }); +/** + * The URL member the producer reported, before fragment handling; undefined + * only when it is missing. Scope checks of the raw report read this. + */ +export const reportedFrameUrl = ( + observation: CdpFrameUrlObservation, +): string | undefined => + observation.kind === "missing" ? undefined : observation.scopeUrl; + /** The readable URL of an observed frame; malformed or missing identity is undefined. */ export const observedFrameUrl = ( observation: CdpFrameUrlObservation, diff --git a/tests/boundary/browser/cdpCaptureScriptMetadata.test.ts b/tests/boundary/browser/cdpCaptureScriptMetadata.test.ts index f3e14865b0..f5a8ea773f 100644 --- a/tests/boundary/browser/cdpCaptureScriptMetadata.test.ts +++ b/tests/boundary/browser/cdpCaptureScriptMetadata.test.ts @@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest"; import { CdpCaptureEvents } from "../../../src/browser/CdpCaptureEvents.js"; import { inspectWebPageInputSchema } from "../../../src/domain/browserObservation.js"; import { CDP_CAPTURE_SCRIPT_METADATA_LIMITS } from "../../../src/browser/CdpCaptureEventTypes.js"; +import { receiveCdpEvent } from "../../../src/browser/CdpConnection.js"; describe("CDP script metadata admission", () => { it("retains an invalid source-map declaration as unknown", () => { @@ -13,14 +14,16 @@ describe("CDP script metadata admission", () => { ["absent", undefined], ["empty", ""], ] as const) { - events.ingest({ - method: "Debugger.scriptParsed", - params: { - scriptId, - url: "https://app.example/app.js", - sourceMapURL, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { + scriptId, + url: "https://app.example/app.js", + sourceMapURL, + }, + }), + ); expect(events.scripts.get(scriptId)?.sourceMapUrl).toBeNull(); } expect(events.completeness.snapshot().excluded).toContainEqual({ @@ -35,14 +38,16 @@ describe("CDP script metadata admission", () => { const origin = "https://app.example"; events.beginAuthorizedFrame({ frameId: "frame-1" }); const emit = (scriptId: string, bytes: number): void => { - events.ingest({ - method: "Debugger.scriptParsed", - params: { - scriptId, - url: `${origin}/app.js`, - sourceMapURL: `/maps/${"x".repeat(bytes)}.map`, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { + scriptId, + url: `${origin}/app.js`, + sourceMapURL: `/maps/${"x".repeat(bytes)}.map`, + }, + }), + ); }; emit("same-id", 3 * 1024 * 1024); @@ -59,14 +64,16 @@ describe("CDP script metadata admission", () => { CDP_CAPTURE_SCRIPT_METADATA_LIMITS.retainedBytes, ); const normalizedAway = `./`.repeat(1_200_000) + "map.js.map"; - events.ingest({ - method: "Debugger.scriptParsed", - params: { - scriptId: "normalized-url", - url: `${origin}/app.js`, - sourceMapURL: normalizedAway, - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { + scriptId: "normalized-url", + url: `${origin}/app.js`, + sourceMapURL: normalizedAway, + }, + }), + ); expect(events.scripts.get("normalized-url")?.sourceMapUrl).toBe( `${origin}/map.js.map`, ); @@ -96,10 +103,12 @@ describe("CDP script metadata admission", () => { const origin = "https://app.example"; events.beginAuthorizedFrame({ frameId: "frame-1" }); const emit = (scriptId: string): void => { - events.ingest({ - method: "Debugger.scriptParsed", - params: { scriptId, url: `${origin}/app.js` }, - }); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { scriptId, url: `${origin}/app.js` }, + }), + ); }; emit("x".repeat(CDP_CAPTURE_SCRIPT_METADATA_LIMITS.retainedBytes + 1)); @@ -186,21 +195,25 @@ it.each([ ({ auxiliary, frame, invalid }) => { const events = captureEvents(); events.beginAuthorizedFrame({ frameId: "frame-1" }); - events.ingest({ - method: "Runtime.executionContextCreated", - params: { context: { id: 7, auxData: { frameId: "frame-1" } } }, - }); - events.ingest({ - method: "Debugger.scriptParsed", - params: { - scriptId: "script", - url: "https://app.example/app.js", - executionContextId: 7, - ...(auxiliary === undefined - ? {} - : { executionContextAuxData: auxiliary }), - }, - }); + events.ingest( + receiveCdpEvent({ + method: "Runtime.executionContextCreated", + params: { context: { id: 7, auxData: { frameId: "frame-1" } } }, + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { + scriptId: "script", + url: "https://app.example/app.js", + executionContextId: 7, + ...(auxiliary === undefined + ? {} + : { executionContextAuxData: auxiliary }), + }, + }), + ); const script = events.scripts.get("script"); if (script === undefined) throw new Error("Expected retained script metadata"); @@ -221,10 +234,12 @@ it.each([ it("rejects an empty script ID before retaining its metadata", () => { const events = captureEvents(); events.beginAuthorizedFrame({ frameId: "frame-1" }); - events.ingest({ - method: "Debugger.scriptParsed", - params: { scriptId: "", url: "https://app.example/app.js" }, - }); + events.ingest( + receiveCdpEvent({ + method: "Debugger.scriptParsed", + params: { scriptId: "", url: "https://app.example/app.js" }, + }), + ); expect(events.scripts.size).toBe(0); expect(events.retainedScriptMetadataBytes).toBe(0); expect(events.completeness.snapshot().excluded).toContainEqual({ diff --git a/tests/boundary/browser/cdpConnection.test.ts b/tests/boundary/browser/cdpConnection.test.ts index 1f16959079..41c60459d1 100644 --- a/tests/boundary/browser/cdpConnection.test.ts +++ b/tests/boundary/browser/cdpConnection.test.ts @@ -259,6 +259,51 @@ describe("CDP connection response correlation", () => { }); }); +describe("CDP connection event admission", () => { + it("parses a registered event once and shares it with every subscriber", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const connection = await CdpConnection.connect( + browser.browserWebSocketUrl, + "inspect_web_page", + ); + try { + const params = { + frame: { + id: "main", + loaderId: "loader-1", + url: "https://app.example.test/page", + }, + type: "Navigation", + }; + const subscriber = () => + new Promise((resolve) => { + connection.onEvent((event) => { + if (event.method === "Page.frameNavigated") resolve(event); + }); + }); + const first = subscriber(); + const second = subscriber(); + browser.emitRawMessage( + JSON.stringify({ method: "Page.frameNavigated", params }), + ); + const [left, right] = await Promise.all([first, second]); + + expect(left.registered).toMatchObject({ + method: "Page.frameNavigated", + payload: { + url: { kind: "observed", url: "https://app.example.test/page" }, + }, + }); + expect(right.registered).toBe(left.registered); + expect(left.params).toEqual(params); + expect(right.params).toBe(left.params); + } finally { + await connection.close(); + } + }); +}); + describe("CDP command cancellation causes", () => { it("preserves a supplied reason when a command starts with an aborted signal", async () => { const browser = await startFakeCdpBrowser(); diff --git a/tests/boundary/browser/cdpJsonShapeComparison.test.ts b/tests/boundary/browser/cdpJsonShapeComparison.test.ts index a56c94518f..ab3fc3dcce 100644 --- a/tests/boundary/browser/cdpJsonShapeComparison.test.ts +++ b/tests/boundary/browser/cdpJsonShapeComparison.test.ts @@ -12,6 +12,7 @@ import { import { parseEvidence } from "../../../src/domain/evidence.js"; import { webCaptureDiffSchema } from "../../../src/domain/webCaptureDiffSchemas.js"; import { passiveNetworkCapture } from "../../fixtures/passiveNetworkCapture.js"; +import { receiveCdpEvent } from "../../../src/browser/CdpConnection.js"; const ORIGIN = "https://example.test"; const CAPTURE_TIME = "2026-01-01T00:00:00.000Z"; @@ -430,35 +431,41 @@ const captureBody = ( new Set([ORIGIN]), ); events.beginAuthorizedFrame({ frameId: "main" }); - events.ingest({ - method: "Network.requestWillBeSent", - params: { - requestId: "request-1", - type: "Fetch", - request: { url: `${ORIGIN}/api`, ...request }, - initiator: { type: "script" }, - }, - }); - const responseBody = source === "request" ? "{}" : body; - events.ingest({ - method: "Network.responseReceived", - params: { - requestId: "request-1", - response: { - url: `${ORIGIN}/api`, - status: 200, - mimeType: "application/json", - headers: {}, + events.ingest( + receiveCdpEvent({ + method: "Network.requestWillBeSent", + params: { + requestId: "request-1", + type: "Fetch", + request: { url: `${ORIGIN}/api`, ...request }, + initiator: { type: "script" }, }, - }, - }); - events.ingest({ - method: "Network.loadingFinished", - params: { - requestId: "request-1", - encodedDataLength: Buffer.byteLength(responseBody), - }, - }); + }), + ); + const responseBody = source === "request" ? "{}" : body; + events.ingest( + receiveCdpEvent({ + method: "Network.responseReceived", + params: { + requestId: "request-1", + response: { + url: `${ORIGIN}/api`, + status: 200, + mimeType: "application/json", + headers: {}, + }, + }, + }), + ); + events.ingest( + receiveCdpEvent({ + method: "Network.loadingFinished", + params: { + requestId: "request-1", + encodedDataLength: Buffer.byteLength(responseBody), + }, + }), + ); const candidate = events.responseBodyRequests()[0]; expect(candidate?.requestId).toBe("request-1"); expect(candidate).toBeDefined();