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();