fix(browser)!: preserve unknown WebSocket frame facts
Keep malformed or missing CDP opcodes and payload facts unknown, retain observed zero and empty payloads, and avoid false capture differences while preserving independently known facts. Validation: 59 source tests; compiled public CLI and stdio MCP fake-CDP acceptance; check:fast; docs:check; changed-file formatting. Real Chromium malformed-event behavior was not tested. BREAKING CHANGE: WebSocket event opcode is nullable and numeric values are restricted to the four-bit protocol range. Fixes #5666
This commit is contained in:
1 parent
c38f96fa69
commit
0bc2b42001
7 files changed
+458
-26
No files matched your search
@@ -509,28 +509,41 @@ export const handleWebSocketFrame = (
|
||||
const connection = state.webSocketConnectionsById.get(requestId);
|
||||
if (connection === undefined) return;
|
||||
const response = recordValue(params.response);
|
||||
const payload = cdpStringValue(response?.payloadData) ?? "";
|
||||
const opcode = Math.max(0, Math.trunc(numberValue(response?.opcode) ?? 0));
|
||||
const decodedBytes =
|
||||
opcode === 1 ? undefined : paddedBase64ByteLength(payload);
|
||||
if (opcode !== 1 && decodedBytes === undefined)
|
||||
const opcodeValue = numberValue(response?.opcode);
|
||||
// RFC 6455 encodes opcodes in four bits; keep reserved values as observed data.
|
||||
const opcode =
|
||||
opcodeValue !== undefined &&
|
||||
Number.isInteger(opcodeValue) &&
|
||||
opcodeValue >= 0 &&
|
||||
opcodeValue <= 15
|
||||
? opcodeValue
|
||||
: null;
|
||||
const payload = cdpStringValue(response?.payloadData);
|
||||
const payloadBytes =
|
||||
opcode === null || payload === undefined
|
||||
? null
|
||||
: opcode === 1
|
||||
? Buffer.byteLength(payload)
|
||||
: (paddedBase64ByteLength(payload) ?? null);
|
||||
if (opcode === null || payloadBytes === null)
|
||||
state.completeness.exclude("websocket_frames", "invalid_protocol_value");
|
||||
connection.events.push({
|
||||
direction,
|
||||
opcode,
|
||||
payload_bytes:
|
||||
opcode === 1 ? Buffer.byteLength(payload) : (decodedBytes ?? null),
|
||||
payload_bytes: payloadBytes,
|
||||
payload_shape: captureWebSocketShape(state, payload, opcode),
|
||||
});
|
||||
};
|
||||
|
||||
const captureWebSocketShape = (
|
||||
state: CdpCaptureEventsState,
|
||||
payload: string,
|
||||
opcode: number,
|
||||
payload: string | undefined,
|
||||
opcode: number | null,
|
||||
): WebPageInspection["network"]["websocket_connections"][number]["events"][number]["payload_shape"] => {
|
||||
if (!state.input.include_websocket_shapes) return null;
|
||||
if (opcode === null) return null;
|
||||
if (opcode !== 1) return { format: "binary", json_shape: null };
|
||||
if (payload === undefined) return null;
|
||||
const shape = inferJsonShape(payload);
|
||||
return {
|
||||
format: shape === null ? "text" : "json",
|
||||
|
||||
@@ -0,0 +1,182 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { inspectWebPageInputSchema } from "../domain/browserObservation.js";
|
||||
import { webPageInspectionSchema } from "../domain/browserObservationSchemas.js";
|
||||
import { CdpCaptureEvents } from "./CdpCaptureEvents.js";
|
||||
|
||||
const origin = "https://example.test";
|
||||
|
||||
const createEvents = (): CdpCaptureEvents =>
|
||||
new CdpCaptureEvents(
|
||||
inspectWebPageInputSchema.parse({
|
||||
cdp_endpoint: "http://127.0.0.1:9222",
|
||||
allowed_origins: [origin],
|
||||
target_id: "page",
|
||||
include_websocket_shapes: true,
|
||||
}),
|
||||
new Set([origin]),
|
||||
);
|
||||
|
||||
const captureFrame = (
|
||||
opcode: unknown,
|
||||
payloadData: unknown,
|
||||
includeOpcode = true,
|
||||
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 } : {}),
|
||||
},
|
||||
},
|
||||
});
|
||||
return {
|
||||
events,
|
||||
frame: events.webSocketConnectionsById.get("socket")?.events[0],
|
||||
};
|
||||
};
|
||||
|
||||
it.each([
|
||||
{
|
||||
label: "missing",
|
||||
opcode: undefined,
|
||||
payload: "",
|
||||
hasOpcode: false,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "wrong type",
|
||||
opcode: "1",
|
||||
payload: "text",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "explicit null",
|
||||
opcode: null,
|
||||
payload: "",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "negative",
|
||||
opcode: -1,
|
||||
payload: "",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "fractional",
|
||||
opcode: 1.5,
|
||||
payload: "text",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "above opcode width",
|
||||
opcode: 16,
|
||||
payload: "",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
{
|
||||
label: "non-finite",
|
||||
opcode: Number.NaN,
|
||||
payload: "",
|
||||
hasOpcode: true,
|
||||
hasPayload: true,
|
||||
},
|
||||
] as const)(
|
||||
"keeps $label WebSocket opcode unknown",
|
||||
({ opcode, payload, hasOpcode, hasPayload }) => {
|
||||
const { events, frame } = captureFrame(
|
||||
opcode,
|
||||
payload,
|
||||
hasOpcode,
|
||||
hasPayload,
|
||||
);
|
||||
expect(frame).toEqual({
|
||||
direction: "received",
|
||||
opcode: null,
|
||||
payload_bytes: null,
|
||||
payload_shape: null,
|
||||
});
|
||||
expect(events.completeness.snapshot().excluded).toContainEqual({
|
||||
section: "websocket_frames",
|
||||
reason: "invalid_protocol_value",
|
||||
count: 1,
|
||||
});
|
||||
expect(
|
||||
webPageInspectionSchema.shape.network.shape.websocket_connections.element.safeParse(
|
||||
{
|
||||
request_id: "socket",
|
||||
url: "wss://example.test/live",
|
||||
events: [frame],
|
||||
},
|
||||
).success,
|
||||
).toBe(true);
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
{ label: "continuation", opcode: 0, payload: "", bytes: 0, format: "binary" },
|
||||
{ label: "empty text", opcode: 1, payload: "", bytes: 0, format: "text" },
|
||||
{
|
||||
label: "reserved four-bit opcode",
|
||||
opcode: 15,
|
||||
payload: "",
|
||||
bytes: 0,
|
||||
format: "binary",
|
||||
},
|
||||
] as const)(
|
||||
"preserves observed $label data",
|
||||
({ opcode, payload, bytes, format }) => {
|
||||
const { events, frame } = captureFrame(opcode, payload);
|
||||
expect(frame).toEqual({
|
||||
direction: "received",
|
||||
opcode,
|
||||
payload_bytes: bytes,
|
||||
payload_shape: { format, json_shape: null },
|
||||
});
|
||||
expect(events.completeness.snapshot().excluded).not.toContainEqual(
|
||||
expect.objectContaining({
|
||||
section: "websocket_frames",
|
||||
reason: "invalid_protocol_value",
|
||||
}),
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
{
|
||||
label: "missing payload",
|
||||
opcode: 1,
|
||||
payload: undefined,
|
||||
hasPayload: false,
|
||||
},
|
||||
{ label: "wrong-type payload", opcode: 1, payload: 42, hasPayload: true },
|
||||
] as const)(
|
||||
"does not fabricate an empty payload for $label",
|
||||
({ opcode, payload, hasPayload }) => {
|
||||
const { events, frame } = captureFrame(opcode, payload, true, hasPayload);
|
||||
expect(frame).toEqual({
|
||||
direction: "received",
|
||||
opcode,
|
||||
payload_bytes: null,
|
||||
payload_shape: null,
|
||||
});
|
||||
expect(events.completeness.snapshot().excluded).toContainEqual({
|
||||
section: "websocket_frames",
|
||||
reason: "invalid_protocol_value",
|
||||
count: 1,
|
||||
});
|
||||
},
|
||||
);
|
||||
@@ -185,7 +185,7 @@ const browserConsoleEventSchema = z.object({
|
||||
});
|
||||
const browserWebSocketFrameSchema = z.object({
|
||||
direction: z.enum(["sent", "received"]),
|
||||
opcode: z.number().int().min(0),
|
||||
opcode: z.number().int().min(0).max(15).nullable(),
|
||||
payload_bytes: z.number().int().min(0).nullable(),
|
||||
payload_shape: z
|
||||
.object({
|
||||
|
||||
@@ -219,6 +219,74 @@ describe("passive network inventory changes", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe("unknown WebSocket opcode evidence", () => {
|
||||
const captureWithWebSocketFrames = (
|
||||
events: WebPageInspection["network"]["websocket_connections"][number]["events"],
|
||||
): WebPageInspection => {
|
||||
const capture = unselectedShapes(passiveNetworkCapture([]));
|
||||
capture.network.websocket_connections.push({
|
||||
request_id: "capture-local-socket-id",
|
||||
url: "wss://app.example.test/live",
|
||||
events: structuredClone(events),
|
||||
});
|
||||
return capture;
|
||||
};
|
||||
|
||||
it("does not compare an unknown opcode as a real continuation frame", () => {
|
||||
const malformed = captureWithWebSocketFrames([
|
||||
{
|
||||
direction: "received",
|
||||
opcode: null,
|
||||
payload_bytes: null,
|
||||
payload_shape: null,
|
||||
},
|
||||
]);
|
||||
const observedZero = captureWithWebSocketFrames([
|
||||
{
|
||||
direction: "received",
|
||||
opcode: 0,
|
||||
payload_bytes: 0,
|
||||
payload_shape: { format: "binary", json_shape: null },
|
||||
},
|
||||
]);
|
||||
|
||||
for (const [before, after] of [
|
||||
[malformed, observedZero],
|
||||
[observedZero, malformed],
|
||||
] as const)
|
||||
expect(compare(before, after)).toMatchObject({
|
||||
status: "unknown",
|
||||
total_changes: 0,
|
||||
changes: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("still compares known payload facts in a stream with another unknown frame", () => {
|
||||
const before = captureWithWebSocketFrames([
|
||||
{
|
||||
direction: "received",
|
||||
opcode: null,
|
||||
payload_bytes: null,
|
||||
payload_shape: null,
|
||||
},
|
||||
{
|
||||
direction: "sent",
|
||||
opcode: 1,
|
||||
payload_bytes: 3,
|
||||
payload_shape: { format: "text", json_shape: null },
|
||||
},
|
||||
]);
|
||||
const after = structuredClone(before);
|
||||
after.network.websocket_connections[0]!.events[1]!.payload_bytes = 4;
|
||||
|
||||
expect(compare(before, after)).toMatchObject({
|
||||
status: "changed",
|
||||
total_changes: 1,
|
||||
changes: [{ change: "modified" }],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("passive network coverage uncertainty", () => {
|
||||
it.each([
|
||||
"attach_limited_sections",
|
||||
|
||||
@@ -367,6 +367,26 @@ const networkInventoryComplete = (
|
||||
(section) => inspection.completeness.dropped_events[section] === 0,
|
||||
);
|
||||
|
||||
type WebSocketEvent =
|
||||
WebPageInspection["network"]["websocket_connections"][number]["events"][number];
|
||||
|
||||
const webSocketEventHasOpcode = (
|
||||
event: WebSocketEvent | undefined,
|
||||
): event is WebSocketEvent => event !== undefined && event.opcode !== null;
|
||||
|
||||
const webSocketEventHasPayloadBytes = (
|
||||
event: WebSocketEvent | undefined,
|
||||
): boolean => webSocketEventHasOpcode(event) && event.payload_bytes !== null;
|
||||
|
||||
const webSocketEventHasPayloadShape = (
|
||||
event: WebSocketEvent | undefined,
|
||||
): boolean => webSocketEventHasOpcode(event) && event.payload_shape !== null;
|
||||
|
||||
const webSocketOpcodesKnown = (inspection: WebPageInspection): boolean =>
|
||||
inspection.network.websocket_connections.every((connection) =>
|
||||
connection.events.every(webSocketEventHasOpcode),
|
||||
);
|
||||
|
||||
const networkDimension = (
|
||||
before: WebPageInspection,
|
||||
after: WebPageInspection,
|
||||
@@ -374,11 +394,12 @@ const networkDimension = (
|
||||
const requestsComplete = [before, after].every((inspection) =>
|
||||
networkInventoryComplete(inspection, ["network_requests"]),
|
||||
);
|
||||
const webSocketInventoryComplete = [before, after].every((inspection) =>
|
||||
networkInventoryComplete(inspection, [
|
||||
"websocket_connections",
|
||||
"websocket_frames",
|
||||
]),
|
||||
const webSocketInventoryComplete = [before, after].every(
|
||||
(inspection) =>
|
||||
networkInventoryComplete(inspection, [
|
||||
"websocket_connections",
|
||||
"websocket_frames",
|
||||
]) && webSocketOpcodesKnown(inspection),
|
||||
);
|
||||
const requestIdentities = networkIdentityCoverage(before, after);
|
||||
const metadata = sharedNetworkMetadata(before, after);
|
||||
@@ -432,12 +453,12 @@ const networkDimension = (
|
||||
(inspection) =>
|
||||
sectionsComplete(inspection, ["websocket_shapes"]) &&
|
||||
inspection.network.websocket_connections.every((connection) =>
|
||||
connection.events.every((event) => event.payload_shape !== null),
|
||||
connection.events.every(webSocketEventHasPayloadShape),
|
||||
),
|
||||
);
|
||||
const webSocketPayloadBytesComplete = [before, after].every((inspection) =>
|
||||
inspection.network.websocket_connections.every((connection) =>
|
||||
connection.events.every((event) => event.payload_bytes !== null),
|
||||
connection.events.every(webSocketEventHasPayloadBytes),
|
||||
),
|
||||
);
|
||||
const beforeWebSockets = webSocketGroups(before);
|
||||
@@ -633,11 +654,11 @@ const webSocketPayloadMaps = (
|
||||
const comparableShapes = new Set<number>();
|
||||
for (let index = 0; index < eventCount; index += 1) {
|
||||
if (
|
||||
beforeGroup.connections.every(
|
||||
(connection) => connection.events[index]?.payload_bytes !== null,
|
||||
beforeGroup.connections.every((connection) =>
|
||||
webSocketEventHasPayloadBytes(connection.events[index]),
|
||||
) &&
|
||||
afterGroup.connections.every(
|
||||
(connection) => connection.events[index]?.payload_bytes !== null,
|
||||
afterGroup.connections.every((connection) =>
|
||||
webSocketEventHasPayloadBytes(connection.events[index]),
|
||||
)
|
||||
)
|
||||
comparableBytes.add(index);
|
||||
@@ -645,11 +666,11 @@ const webSocketPayloadMaps = (
|
||||
// on both sides; this avoids assigning an unknown shape to a known one.
|
||||
if (
|
||||
selected &&
|
||||
beforeGroup.connections.every(
|
||||
(connection) => connection.events[index]?.payload_shape !== null,
|
||||
beforeGroup.connections.every((connection) =>
|
||||
webSocketEventHasPayloadShape(connection.events[index]),
|
||||
) &&
|
||||
afterGroup.connections.every(
|
||||
(connection) => connection.events[index]?.payload_shape !== null,
|
||||
afterGroup.connections.every((connection) =>
|
||||
webSocketEventHasPayloadShape(connection.events[index]),
|
||||
)
|
||||
)
|
||||
comparableShapes.add(index);
|
||||
|
||||
Reference in new issue
Block a user