diff --git a/docs/guides/web/browser-observation.md b/docs/guides/web/browser-observation.md index 6658425b70..f756f8543e 100644 --- a/docs/guides/web/browser-observation.md +++ b/docs/guides/web/browser-observation.md @@ -423,14 +423,17 @@ main frame. The web-session timeline uses CDP monotonic seconds where the event producer provides a comparable timestamp; absent or invalid timestamps are `null` rather -than a synthetic zero. Events buffered while REA samples the window boundary are -retained only when their timestamp places them after that boundary; older events -are excluded. A buffered event without a comparable timestamp may remain as -contextual evidence with `timestamp: null`, accompanied by a limitation stating -that it does not establish activity in the selected window. Main-frame scope -enforcement still applies to contextual navigation events. Network redirect -events retain their paired prior-hop response context when the timestamped -next-request event falls inside the window. Every redirect row, and only a redirect row, has a +than a synthetic zero. After enabling the Page domain, REA buffers timeline +events through preparation and clock sampling. Timestamped rows describe +events after the sampled boundary; earlier requests can still identify a +document load failure that occurs inside the window. A buffered event without a +comparable timestamp may remain as contextual evidence with `timestamp: null`, +accompanied by a limitation stating that it does not establish activity in the +selected window. Main-frame scope enforcement still applies to contextual +navigation events. + +Network redirect events retain their paired prior-hop response context when the +timestamped next-request event falls inside the window. Every redirect row, and only a redirect row, has a `redirect_response` that contains the prior response `url`, CDP-reported `status`, and `scope`. The URL has transport credentials removed; URL and status are withheld unless its origin is approved. Missing or malformed response URLs have diff --git a/src/browser/CdpObservationSession.ts b/src/browser/CdpObservationSession.ts index ba04b6121d..0154e1bb5f 100644 --- a/src/browser/CdpObservationSession.ts +++ b/src/browser/CdpObservationSession.ts @@ -93,6 +93,14 @@ export const observeCdpSession = async ( context.sessionId, context.signal, ); + // Page.enable can replay earlier Page history. Observe subsequent events + // before enabling Network so preparation retains new navigation and the + // request identities needed for failures inside the armed window. + removeListener = onCdpTargetEvent( + context.connection, + context.sessionId, + (event) => capture.ingest(event), + ); await context.connection.send( "Network.enable", {}, @@ -105,11 +113,6 @@ export const observeCdpSession = async ( context.sessionId, context.signal, ); - removeListener = onCdpTargetEvent( - context.connection, - context.sessionId, - (event) => capture.ingest(event), - ); // Host wall time marks command dispatch. The returned browser monotonic // timestamp is the authoritative cutoff for timestamped lifecycle facts. const armedAt = new Date().toISOString(); diff --git a/tests/boundary/browser/cdpObservationWindowBuffer.test.ts b/tests/boundary/browser/cdpObservationWindowBuffer.test.ts index e990fc126b..98d0456669 100644 --- a/tests/boundary/browser/cdpObservationWindowBuffer.test.ts +++ b/tests/boundary/browser/cdpObservationWindowBuffer.test.ts @@ -29,6 +29,20 @@ const clockResponseEvents: NonNullable = ( }, }, ]; + if (command.method === "Network.enable") + return [ + { + method: "Network.requestWillBeSent", + sessionId: command.sessionId, + params: { + requestId: "failure-window", + type: "Document", + frameId: "frame-main", + timestamp: 18, + request: { url: `${origin}/document`, method: "GET" }, + }, + }, + ]; if (command.method === "Performance.getMetrics") return [ { @@ -95,17 +109,6 @@ const clockResponseEvents: NonNullable = ( errorText: "net::ERR_CONNECTION_REFUSED", }, }, - { - method: "Network.requestWillBeSent", - sessionId: command.sessionId, - params: { - requestId: "failure-window", - type: "Document", - frameId: "frame-main", - timestamp: 21, - request: { url: `${origin}/document`, method: "GET" }, - }, - }, { method: "Network.loadingFailed", sessionId: command.sessionId, @@ -137,6 +140,7 @@ it("buffers clock-response events while dropping lifecycle history before the cl const browser = await startFakeCdpBrowser({ eventsBeforeReply: [ "Page.enable", + "Network.enable", "Performance.getMetrics", "Page.setLifecycleEventsEnabled", ], diff --git a/tests/boundary/browser/cdpObservationWindowScope.test.ts b/tests/boundary/browser/cdpObservationWindowScope.test.ts index d0cbb8128f..87bc58327a 100644 --- a/tests/boundary/browser/cdpObservationWindowScope.test.ts +++ b/tests/boundary/browser/cdpObservationWindowScope.test.ts @@ -8,11 +8,11 @@ import { } from "../../fixtures/fakeCdpBrowser.js"; import { frameNavigated, trackBrowser } from "./cdpBrowserProvider.support.js"; -const observeDuringClockSampling = async ( +const observeDuringPreparation = async ( commandEvents: NonNullable, ) => { return observeWithFake({ - eventsBeforeReply: ["Performance.getMetrics"], + eventsBeforeReply: ["Network.enable", "Performance.getMetrics"], commandResult: (command) => command.method === "Performance.getMetrics" ? { metrics: [{ name: "Timestamp", value: 20 }] } @@ -24,6 +24,7 @@ const observeDuringClockSampling = async ( const observeWithFake = async (options: FakeOptions) => { const browser = await startFakeCdpBrowser(options); trackBrowser(browser); + const progress: number[] = []; const result = await new CdpBrowserProvider().observeSession( observeWebSessionInputSchema.parse({ cdp_endpoint: browser.endpoint, @@ -31,9 +32,16 @@ const observeWithFake = async (options: FakeOptions) => { target_id: "allowed-page", observation_ms: 20, }), + { + progress: { + report: async (update) => { + progress.push(update.completed); + }, + }, + }, ); if (!result.ok) throw result.error; - return { browser, observation: result.value }; + return { browser, progress, observation: result.value }; }; const laterInWindowRequest = ( @@ -52,39 +60,90 @@ const laterInWindowRequest = ( }, }); -it("fails closed on an untimestamped cross-origin main-frame commit during clock sampling", async () => { - const { observation } = await observeDuringClockSampling( - (command, origin) => { - if (command.method !== "Performance.getMetrics") return undefined; - return [ - frameNavigated(command, { - id: "frame-main", - loaderId: "outside-loader", - url: "https://outside.invalid/path", - }), - laterInWindowRequest(command, origin), - ]; - }, - ); - - expect(observation.window.end_reason).toBe("target_left_scope"); - expect(observation.target.final_url).toBeNull(); - expect(observation.timeline).toContainEqual( - expect.objectContaining({ - type: "navigation_committed", - loader_id: "outside-loader", - timestamp: null, - destination_scope: "outside_policy", - url: null, +const foreignUrl = "https://outside.invalid/path"; +type WireCommand = Parameters>[0]; +const outsideNavigation = { + navigation_committed: (command: WireCommand) => + frameNavigated(command, { + id: "frame-main", + loaderId: "outside-loader", + url: foreignUrl, }), - ); - expect(observation.timeline).not.toContainEqual( - expect.objectContaining({ request_id: "later-in-window-request" }), - ); -}); + navigation_requested: (command: WireCommand) => ({ + method: "Page.frameRequestedNavigation", + sessionId: command.sessionId, + params: { + frameId: "frame-main", + url: foreignUrl, + reason: "scriptInitiated", + }, + }), + redirect: (command: WireCommand, origin: string) => ({ + method: "Network.requestWillBeSent", + sessionId: command.sessionId, + params: { + requestId: "outside-redirect", + type: "Document", + frameId: "frame-main", + redirectResponse: { url: `${origin}/prior`, status: 302 }, + request: { url: foreignUrl }, + }, + }), +}; + +it.each([ + ["Network.enable", "navigation_committed", { loader_id: "outside-loader" }], + [ + "Performance.getMetrics", + "navigation_committed", + { loader_id: "outside-loader" }, + ], + ["Performance.getMetrics", "navigation_requested", {}], + ["Performance.getMetrics", "redirect", { request_id: "outside-redirect" }], +] as const)( + "ends preparation for a foreign %s event of type %s", + async (phase, type, identity) => { + const { browser, observation, progress } = await observeDuringPreparation( + (command, origin) => { + const later = + command.method === "Performance.getMetrics" + ? [laterInWindowRequest(command, origin)] + : []; + if (command.method === phase) + return [outsideNavigation[type](command, origin), ...later]; + return later.length === 0 ? undefined : later; + }, + ); + + expect(observation.window.end_reason).toBe("target_left_scope"); + expect(progress).toEqual([2]); + expect(observation.target.final_url).toBeNull(); + expect(observation.timeline).toContainEqual( + expect.objectContaining({ + ...identity, + type, + timestamp: null, + destination_scope: "outside_policy", + url: null, + ...(type === "redirect" + ? { + redirect_response: { + scope: "approved", + status: 302, + url: `${browser.allowedOrigin}/prior`, + }, + } + : {}), + }), + ); + expect(observation.timeline).not.toContainEqual( + expect.objectContaining({ request_id: "later-in-window-request" }), + ); + }, +); it("accounts for each malformed frame commit without inventing a main-frame navigation", async () => { - const { observation } = await observeDuringClockSampling((command) => + const { observation } = await observeDuringPreparation((command) => command.method === "Performance.getMetrics" ? [ frameNavigated(command, { url: "https://outside.invalid/unknown" }), @@ -112,7 +171,7 @@ it("accounts for each malformed frame commit without inventing a main-frame navi }); it("updates the main frame from a pre-arm root replacement without inventing a navigation row", async () => { - const { observation } = await observeDuringClockSampling((command, origin) => + const { observation } = await observeDuringPreparation((command, origin) => command.method === "Performance.getMetrics" ? [ frameNavigated(command, { @@ -170,87 +229,6 @@ it("updates the main frame from a pre-arm root replacement without inventing a n ); }); -it("fails closed on an untimestamped out-of-scope main-frame request during clock sampling", async () => { - const { observation } = await observeDuringClockSampling( - (command, origin) => { - if (command.method !== "Performance.getMetrics") return undefined; - return [ - { - method: "Page.frameRequestedNavigation", - sessionId: command.sessionId, - params: { - frameId: "frame-main", - url: "https://outside.invalid/path", - reason: "scriptInitiated", - }, - }, - laterInWindowRequest(command, origin), - ]; - }, - ); - - expect(observation.window.end_reason).toBe("target_left_scope"); - expect(observation.timeline).toContainEqual( - expect.objectContaining({ - type: "navigation_requested", - timestamp: null, - destination_scope: "outside_policy", - url: null, - }), - ); - expect(observation.timeline).not.toContainEqual( - expect.objectContaining({ request_id: "later-in-window-request" }), - ); -}); - -it("fails closed on an untimestamped out-of-scope redirect during clock sampling", async () => { - const { observation } = await observeDuringClockSampling( - (command, origin) => { - if (command.method !== "Performance.getMetrics") return undefined; - return [ - { - method: "Network.requestWillBeSent", - sessionId: command.sessionId, - params: { - requestId: "unknown-time-outside-redirect", - type: "Document", - frameId: "frame-main", - redirectResponse: { url: `${origin}/prior` }, - request: { url: "https://outside.invalid/redirected" }, - }, - }, - { - method: "Network.requestWillBeSent", - sessionId: command.sessionId, - params: { - requestId: "later-in-window-request", - timestamp: 21, - type: "Document", - frameId: "frame-main", - redirectResponse: { url: `${origin}/prior` }, - request: { url: `${origin}/later` }, - }, - }, - ]; - }, - ); - - expect(observation.window.end_reason).toBe("target_left_scope"); - expect(observation.target.final_url).toBeNull(); - expect(observation.timeline).toContainEqual( - expect.objectContaining({ - type: "redirect", - request_id: "unknown-time-outside-redirect", - timestamp: null, - destination_scope: "outside_policy", - url: null, - }), - ); - expect(observation.timeline).not.toContainEqual( - expect.objectContaining({ request_id: "later-in-window-request" }), - ); -}); - it.each([ [ "Inspector.targetCrashed", @@ -396,29 +374,27 @@ it("ends an armed observation at a fatal protocol failure without waiting out it }); it("does not join an empty document request identity to a later loading failure", async () => { - const { observation } = await observeDuringClockSampling( - (command, origin) => { - if (command.method !== "Performance.getMetrics") return undefined; - return [ - { - ...laterInWindowRequest(command, origin), - params: { - ...laterInWindowRequest(command, origin).params, - requestId: "", - }, + const { observation } = await observeDuringPreparation((command, origin) => { + if (command.method !== "Performance.getMetrics") return undefined; + return [ + { + ...laterInWindowRequest(command, origin), + params: { + ...laterInWindowRequest(command, origin).params, + requestId: "", }, - { - method: "Network.loadingFailed", - sessionId: command.sessionId, - params: { - requestId: "", - timestamp: 22, - errorText: "net::ERR_FAILED", - }, + }, + { + method: "Network.loadingFailed", + sessionId: command.sessionId, + params: { + requestId: "", + timestamp: 22, + errorText: "net::ERR_FAILED", }, - ]; - }, - ); + }, + ]; + }); expect(observation.window.end_reason).toBe("window_elapsed"); expect(observation.timeline).toContainEqual( expect.objectContaining({ type: "redirect", request_id: null }), @@ -521,7 +497,7 @@ const redirectCases = [ ]; it("retains scoped redirect response facts for each request", async () => { - const { browser, observation } = await observeDuringClockSampling( + const { browser, observation } = await observeDuringPreparation( (command, origin) => { if (command.method !== "Performance.getMetrics") return undefined; return redirectCases.map(({ name, response }, index) => ({