mirror of
https://github.com/morluto/rea.git
synced 2026-11-15 19:23:24 +00:00
* refactor(browser): send only CDP commands with registered result schemas * refactor(browser): open Playwright CDP sessions only through the registered-command owner * fix(browser): keep the restore obligation for an applied override with a malformed reply A schema-rejected success reply means the browser applied the Emulation override, so the attached environment owner records the reset obligation before reporting the protocol error. Only a rejected or unanswered command leaves no obligation. * refactor(browser): open verifier-script CDP sessions through the registered-command owner (#10710) * fix(browser): register the CDP commands JavaScript verifiers send The verifier scripts send Browser.close, Page.createIsolatedWorld, Page.navigate, Page.reload, Target.activateTarget, Target.closeTarget and Target.createTarget through CdpConnection, which now admits every reply through its command's result schema. Register those schemas, refuse an unregistered run-time name as a typed malformed reply instead of a TypeError, and check script send literals against the registry. * fix(browser): keep Target.closeTarget's success member for the verifiers
347 lines
12 KiB
TypeScript
347 lines
12 KiB
TypeScript
import type { CDPSession } from "playwright-core";
|
|
import { z } from "zod";
|
|
|
|
import { BrowserObservationError } from "../../domain/browserObservationError.js";
|
|
import { cdpResourceColumnSchema } from "../../domain/cdpObservationSchemas.js";
|
|
import type { BrowserObservationOperation } from "../../domain/browserObservationErrors.js";
|
|
import { err, ok, type Result } from "../../domain/result.js";
|
|
import {
|
|
cdpFrameTreeReplySchema,
|
|
cdpResourceTreeReplySchema,
|
|
} from "./CdpFrameTree.js";
|
|
|
|
// Playwright ships the generated Chrome DevTools Protocol command table. Its
|
|
// names and parameter types are reused; its result types are unchecked casts,
|
|
// so REA validates each reply with its own schema below.
|
|
declare const protocolSend: CDPSession["send"];
|
|
|
|
/** Every command name in the protocol version Playwright ships. */
|
|
export type CdpProtocolMethod = Parameters<CDPSession["send"]>[0];
|
|
|
|
/** A command whose reply REA does not read beyond its success. */
|
|
const acknowledgement = z.object({});
|
|
|
|
const coverageOffset = z.int().min(0);
|
|
const nodeId = z.int().min(1);
|
|
const positive = z.number().positive();
|
|
|
|
/** CSS clip geometry and device-pixel viewport for one screenshot. */
|
|
const layoutMetricsReply = z.object({
|
|
visualViewport: z.object({
|
|
clientWidth: positive,
|
|
clientHeight: positive,
|
|
scale: positive,
|
|
}),
|
|
cssVisualViewport: z.object({
|
|
pageX: z.number(),
|
|
pageY: z.number(),
|
|
clientWidth: positive,
|
|
clientHeight: positive,
|
|
scale: positive,
|
|
}),
|
|
});
|
|
|
|
/** Native listener descriptors; live remote handles are not read. */
|
|
const eventListenersReply = z.object({
|
|
listeners: z.array(
|
|
z.object({
|
|
type: z.string(),
|
|
useCapture: z.boolean(),
|
|
passive: z.boolean(),
|
|
once: z.boolean(),
|
|
scriptId: z.string(),
|
|
lineNumber: z.int().min(0),
|
|
columnNumber: cdpResourceColumnSchema,
|
|
}),
|
|
),
|
|
});
|
|
|
|
/** Precise coverage keeps every nested producer range; counts are not flattened. */
|
|
const preciseCoverageReply = z.object({
|
|
timestamp: z.number().min(0),
|
|
result: z.array(
|
|
z.object({
|
|
scriptId: z.string().min(1),
|
|
url: z.string(),
|
|
functions: z.array(
|
|
z.object({
|
|
functionName: z.string(),
|
|
isBlockCoverage: z.boolean(),
|
|
ranges: z.array(
|
|
z.object({
|
|
startOffset: coverageOffset,
|
|
endOffset: coverageOffset,
|
|
count: coverageOffset,
|
|
}),
|
|
),
|
|
}),
|
|
),
|
|
}),
|
|
),
|
|
});
|
|
|
|
/** Browser identity read during browser-socket endpoint discovery. */
|
|
const browserVersionReply = z.object({
|
|
protocolVersion: z.string().min(1),
|
|
product: z.string().min(1),
|
|
revision: z.string(),
|
|
userAgent: z.string(),
|
|
jsVersion: z.string(),
|
|
});
|
|
|
|
/**
|
|
* An inventory whose entries the reading section admits one by one, so one
|
|
* malformed entry is counted there as a gap instead of rejecting the reply.
|
|
*/
|
|
const inventory = z.array(z.unknown());
|
|
|
|
/**
|
|
* IndexedDB versions are exact non-negative integers. An omitted or other value
|
|
* leaves only the version unknown; the database's stores stay readable.
|
|
*/
|
|
const indexedDbVersion = z
|
|
.unknown()
|
|
.transform((value) =>
|
|
typeof value === "number" && Number.isSafeInteger(value) && value >= 0
|
|
? value
|
|
: undefined,
|
|
)
|
|
.optional();
|
|
|
|
/**
|
|
* One result schema per command REA sends. Each schema is the only reader of
|
|
* that command's raw reply; consumers receive its parsed output. Senders accept
|
|
* only these names, so a new command needs its schema here before it compiles.
|
|
*/
|
|
const CDP_COMMAND_REPLIES = {
|
|
"DOM.describeNode": z.object({
|
|
node: z.object({
|
|
backendNodeId: nodeId,
|
|
nodeName: z.string(),
|
|
nodeType: z.int(),
|
|
// CDP omits isSVG for non-SVG nodes.
|
|
isSVG: z.boolean().optional(),
|
|
}),
|
|
}),
|
|
"DOM.disable": acknowledgement,
|
|
"DOM.enable": acknowledgement,
|
|
"DOM.getDocument": z.object({ root: z.object({ nodeId }) }),
|
|
// Zero is the protocol's "no match".
|
|
"DOM.querySelector": z.object({ nodeId: z.int().min(0) }),
|
|
"DOM.resolveNode": z.object({
|
|
object: z.object({ objectId: z.string().min(1) }),
|
|
}),
|
|
"DOMDebugger.getEventListeners": eventListenersReply,
|
|
"Accessibility.getFullAXTree": z.object({ nodes: inventory }),
|
|
"Browser.close": acknowledgement,
|
|
"Browser.getVersion": browserVersionReply,
|
|
"CacheStorage.requestCacheNames": z.object({ caches: inventory }),
|
|
"CacheStorage.requestCachedResponse": z.object({
|
|
response: z.object({ body: z.string() }),
|
|
}),
|
|
"CacheStorage.requestEntries": z.object({
|
|
cacheDataEntries: inventory,
|
|
returnCount: z.int().min(0),
|
|
}),
|
|
"DOMSnapshot.captureSnapshot": z.object({
|
|
// A snapshot always describes at least one document.
|
|
documents: inventory.min(1),
|
|
strings: inventory,
|
|
}),
|
|
"DOMStorage.getDOMStorageItems": z.object({ entries: inventory }),
|
|
"Debugger.disable": acknowledgement,
|
|
"Debugger.enable": acknowledgement,
|
|
"Debugger.evaluateOnCallFrame": z.object({
|
|
result: z.looseObject({}),
|
|
exceptionDetails: z.unknown().optional(),
|
|
}),
|
|
"Debugger.getScriptSource": z.object({ scriptSource: z.string() }),
|
|
"Debugger.resume": acknowledgement,
|
|
"Debugger.setBreakpointByUrl": z.object({ breakpointId: z.string() }),
|
|
"Emulation.clearDeviceMetricsOverride": acknowledgement,
|
|
"Emulation.setDeviceMetricsOverride": acknowledgement,
|
|
"Emulation.setPageScaleFactor": acknowledgement,
|
|
"Emulation.setEmulatedMedia": acknowledgement,
|
|
"Emulation.setFocusEmulationEnabled": acknowledgement,
|
|
"Emulation.setLocaleOverride": acknowledgement,
|
|
"Emulation.setTimezoneOverride": acknowledgement,
|
|
"IndexedDB.requestData": z.object({
|
|
objectStoreDataEntries: inventory,
|
|
hasMore: z.boolean(),
|
|
}),
|
|
"IndexedDB.requestDatabase": z.object({
|
|
databaseWithObjectStores: z.object({
|
|
name: z.string(),
|
|
version: indexedDbVersion,
|
|
objectStores: inventory,
|
|
}),
|
|
}),
|
|
"IndexedDB.requestDatabaseNames": z.object({ databaseNames: inventory }),
|
|
"Network.disable": acknowledgement,
|
|
"Network.enable": acknowledgement,
|
|
"Network.getCookies": z.object({ cookies: inventory }),
|
|
"Network.getResponseBody": z.object({
|
|
body: z.string(),
|
|
base64Encoded: z.boolean(),
|
|
}),
|
|
"Page.addScriptToEvaluateOnNewDocument": z.object({
|
|
identifier: z.string(),
|
|
}),
|
|
"Page.createIsolatedWorld": z.object({ executionContextId: z.int() }),
|
|
"Page.disable": acknowledgement,
|
|
"Page.enable": acknowledgement,
|
|
// `data` is base64 PNG; its canonical decoding stays with the screenshot owner.
|
|
"Page.captureScreenshot": z.object({ data: z.string() }),
|
|
"Page.getFrameTree": cdpFrameTreeReplySchema,
|
|
"Page.getLayoutMetrics": layoutMetricsReply,
|
|
"Page.getResourceTree": cdpResourceTreeReplySchema,
|
|
"Page.navigate": z.object({
|
|
frameId: z.string().min(1),
|
|
loaderId: z.string().min(1).optional(),
|
|
errorText: z.string().optional(),
|
|
}),
|
|
"Page.reload": acknowledgement,
|
|
"Page.removeScriptToEvaluateOnNewDocument": acknowledgement,
|
|
"Page.setLifecycleEventsEnabled": acknowledgement,
|
|
"Page.stopLoading": acknowledgement,
|
|
"Performance.enable": acknowledgement,
|
|
"Performance.getMetrics": z.object({
|
|
metrics: z.array(z.object({ name: z.string(), value: z.number() })),
|
|
}),
|
|
"Profiler.disable": acknowledgement,
|
|
"Profiler.enable": acknowledgement,
|
|
"Profiler.startPreciseCoverage": z.object({ timestamp: z.number().min(0) }),
|
|
"Profiler.stopPreciseCoverage": acknowledgement,
|
|
"Profiler.takePreciseCoverage": preciseCoverageReply,
|
|
"Runtime.disable": acknowledgement,
|
|
"Runtime.enable": acknowledgement,
|
|
// The caller reads `result.value`; a thrown evaluation has no usable value.
|
|
"Runtime.evaluate": z.object({
|
|
result: z.object({ type: z.string(), value: z.unknown().optional() }),
|
|
exceptionDetails: z.unknown().optional(),
|
|
}),
|
|
"Runtime.releaseObjectGroup": acknowledgement,
|
|
"Runtime.runIfWaitingForDebugger": acknowledgement,
|
|
"Storage.getStorageKey": z.object({ storageKey: z.string() }),
|
|
"Storage.getUsageAndQuota": z.object({
|
|
usage: z.number(),
|
|
quota: z.number(),
|
|
}),
|
|
"Target.activateTarget": acknowledgement,
|
|
"Target.attachToTarget": z.object({ sessionId: z.string().min(1) }),
|
|
// Deprecated in the protocol but still sent; the verifiers check it.
|
|
"Target.closeTarget": z.object({ success: z.boolean() }),
|
|
"Target.createTarget": z.object({ targetId: z.string().min(1) }),
|
|
"Target.detachFromTarget": acknowledgement,
|
|
"Target.getTargetInfo": z.object({
|
|
targetInfo: z.object({ targetId: z.string() }),
|
|
}),
|
|
// Each discovery or worker reader admits target rows one by one.
|
|
"Target.getTargets": z.object({ targetInfos: inventory }),
|
|
"Target.sendMessageToTarget": acknowledgement,
|
|
"Target.setAutoAttach": acknowledgement,
|
|
"WebMCP.disable": acknowledgement,
|
|
"WebMCP.enable": acknowledgement,
|
|
} as const satisfies { readonly [M in CdpProtocolMethod]?: z.ZodType };
|
|
|
|
export type CdpCommand = keyof typeof CDP_COMMAND_REPLIES;
|
|
|
|
/**
|
|
* Whether a run-time name has a registered result schema. TypeScript senders
|
|
* cannot name another command; this check covers JavaScript callers and keeps
|
|
* prototype members such as `toString` from being read as schemas.
|
|
*/
|
|
export const isCdpCommand = (method: string): method is CdpCommand =>
|
|
Object.hasOwn(CDP_COMMAND_REPLIES, method);
|
|
|
|
type DomainOf<C, Verb extends string> = C extends `${infer Domain}.${Verb}`
|
|
? Domain
|
|
: never;
|
|
|
|
/**
|
|
* A domain whose `${domain}.${verb}` command is registered. Code that builds a
|
|
* command name at run time takes its domain as this type, so an unregistered
|
|
* name fails to compile.
|
|
*/
|
|
export type CdpDomainWith<Verb extends string> = DomainOf<CdpCommand, Verb>;
|
|
|
|
export type CdpCommandParams<M extends CdpCommand> = NonNullable<
|
|
Parameters<typeof protocolSend<M>>[1]
|
|
>;
|
|
|
|
export type CdpCommandResult<M extends CdpCommand> = z.output<
|
|
(typeof CDP_COMMAND_REPLIES)[M]
|
|
>;
|
|
|
|
/** A well-formed JSON-RPC reply whose result does not match the command's schema. */
|
|
export interface CdpMalformedReplyFacts {
|
|
readonly command: CdpCommand;
|
|
/** RFC 6901 pointer to the first rejected member of `result`. */
|
|
readonly pointer: string;
|
|
readonly issue: string;
|
|
}
|
|
|
|
/** A command-level protocol failure; the connection itself stays usable. */
|
|
export class CdpMalformedReply extends BrowserObservationError {
|
|
readonly command: CdpCommand;
|
|
readonly pointer: string;
|
|
|
|
constructor(
|
|
operation: BrowserObservationOperation,
|
|
facts: CdpMalformedReplyFacts,
|
|
) {
|
|
super(operation, "protocol_error", {
|
|
detail: `CDP ${facts.command} returned a malformed result at ${facts.pointer === "" ? "/" : facts.pointer}: ${facts.issue}`,
|
|
});
|
|
this.command = facts.command;
|
|
this.pointer = facts.pointer;
|
|
}
|
|
}
|
|
|
|
const jsonPointer = (path: readonly PropertyKey[]): string =>
|
|
path
|
|
.map(
|
|
(segment) =>
|
|
`/${String(segment).replaceAll("~", "~0").replaceAll("/", "~1")}`,
|
|
)
|
|
.join("");
|
|
|
|
/** Parse one raw reply with its command's schema. Issue text never quotes producer values. */
|
|
export const parseCdpCommandResult = <M extends CdpCommand>(
|
|
command: M,
|
|
value: unknown,
|
|
): Result<CdpCommandResult<M>, CdpMalformedReplyFacts> => {
|
|
if (!isCdpCommand(command))
|
|
return err({
|
|
command,
|
|
pointer: "",
|
|
issue: "No result schema is registered for this command.",
|
|
});
|
|
const schema: z.ZodType = CDP_COMMAND_REPLIES[command];
|
|
const parsed = schema.safeParse(value) as z.ZodSafeParseResult<
|
|
CdpCommandResult<M>
|
|
>;
|
|
if (parsed.success) return ok(parsed.data);
|
|
const issue = parsed.error.issues[0];
|
|
return err({
|
|
command,
|
|
pointer: jsonPointer(issue?.path ?? []),
|
|
issue: issue?.message ?? "The result did not match its protocol schema.",
|
|
});
|
|
};
|
|
|
|
/**
|
|
* Admit one command reply at a transport boundary: `CdpConnection` and the
|
|
* Playwright CDP sessions both call this. Only registered commands can be
|
|
* sent, so every reply is parsed or rejected here.
|
|
*/
|
|
export const admitCdpReply = <M extends CdpCommand>(
|
|
method: M,
|
|
reply: unknown,
|
|
operation: BrowserObservationOperation,
|
|
): CdpCommandResult<M> => {
|
|
const parsed = parseCdpCommandResult(method, reply);
|
|
if (!parsed.ok) throw new CdpMalformedReply(operation, parsed.error);
|
|
return parsed.value;
|
|
};
|