@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/src/features/rest/model/types.ts

@@ -0,0 +1,113 @@
+import type { Frame } from "../../../entities/frame/index.js";
+import type {
+	AbortErrorCode,
+	HttpRequestView,
+} from "../../../entities/plugin/index.js";
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+
+export type RestMethod =
+	| "GET"
+	| "POST"
+	| "PUT"
+	| "PATCH"
+	| "DELETE"
+	| "HEAD"
+	| "OPTIONS";
+
+export interface RestOptions {
+	/** A path prefix (`/api/v1`) or an origin (`https://api.example.test`) routes are relative to. */
+	readonly baseURL?: string;
+	/**
+	 * Record requests that no route answers, with their real responses.
+	 * `true` records everything under `baseURL`. A request a route does
+	 * answer is recorded by that route, not twice.
+	 */
+	readonly record?: boolean | UrlMatcher;
+}
+
+export interface RestRequest extends HttpRequestView {
+	/** `:name` segments of the matched path. */
+	readonly params: Readonly<Record<string, string>>;
+	readonly query: URLSearchParams;
+}
+
+/** What a resolver answers. Build one with the helpers: `json`, `text`, `abort`, ... */
+export type RestReply =
+	| {
+			readonly kind: "response";
+			readonly status: number;
+			readonly headers: Readonly<Record<string, string>>;
+			readonly body?: Uint8Array | string;
+	  }
+	| { readonly kind: "passthrough" }
+	| { readonly kind: "abort"; readonly error: AbortErrorCode }
+	| { readonly kind: "delay"; readonly ms: number; readonly reply: RestReply };
+
+export type RestResolver =
+	| RestReply
+	| ((request: RestRequest) => RestReply | Promise<RestReply>);
+
+export interface RestRouteOptions {
+	readonly times?: number;
+	readonly match?: (request: RestRequest) => boolean;
+}
+
+export interface RestRoute {
+	/** Requests this route answered. */
+	readonly hits: number;
+	readonly requests: readonly RestRequest[];
+	/** The next request this route answers (or answered and nobody took). */
+	next(options?: { readonly timeout?: number }): Promise<RestRequest>;
+	remove(): Promise<void>;
+}
+
+export interface RestCall {
+	readonly correlation: string;
+	readonly method: string;
+	readonly url: string;
+	readonly request: Frame;
+	readonly response: Frame | undefined;
+	/** The HTTP status; undefined for an aborted or unfinished request. */
+	readonly status: number | undefined;
+}
+
+export type RestPath = string | RegExp;
+
+export interface RestApi {
+	on(
+		method: RestMethod | "*",
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	get(
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	post(
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	put(
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	patch(
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	delete(
+		path: RestPath,
+		resolver: RestResolver,
+		options?: RestRouteOptions,
+	): Promise<RestRoute>;
+	/** Recorded REST exchanges, oldest first. */
+	calls(filter?: {
+		readonly method?: string;
+		readonly path?: RestPath;
+	}): Promise<RestCall[]>;
+}

package/src/features/sse/index.ts

@@ -0,0 +1,10 @@
+export { sse } from "./lib/create-sse.js";
+export { encodeSseEvent } from "./lib/encode.js";
+export type {
+	SseApi,
+	SseConnection,
+	SseEnd,
+	SseEvent,
+	SseStreamOptions,
+	SseStub,
+} from "./model/types.js";

package/src/features/sse/lib/create-sse.ts

@@ -0,0 +1,129 @@
+import {
+	definePlugin,
+	type WirePlugin,
+} from "../../../entities/plugin/index.js";
+import {
+	type Arrivals,
+	createArrivals,
+} from "../../../shared/lib/async/index.js";
+import type { SseApi, SseConnection, SseEvent } from "../model/types.js";
+import { encodeSseEvent } from "./encode.js";
+
+/**
+ * Server-sent events: answer an EventSource (or a fetch reading an event
+ * stream) with a response the test writes one event at a time, with clean
+ * ends and cuts that exercise the client's reconnect.
+ */
+export function sse(): WirePlugin<"sse", SseApi> {
+	return definePlugin({
+		name: "sse",
+		scope: "Sse",
+		setup(context) {
+			const { name } = context;
+			const api: SseApi = {
+				async stream(url, streamOptions = {}) {
+					/** Requests the stub answered: each should become a connection. */
+					let taken = 0;
+					const connections: Arrivals<SseConnection> = createArrivals({
+						clock: context.clock,
+						label: "SSE connection",
+						// The stub answered, yet no connection came of it: the
+						// redirect to the stream server is what went missing.
+						hint: (): string | undefined =>
+							taken > connections.items.length
+								? `${taken - connections.items.length} request(s) matched but never reached the local stream server — see "Live streams" in docs/troubleshooting.md`
+								: undefined,
+					});
+					const rule = await context.http.add({
+						protocol: name,
+						label: `sse ${String(url)}`,
+						url,
+						...(streamOptions.times === undefined
+							? {}
+							: { times: streamOptions.times }),
+						...(streamOptions.match === undefined
+							? {}
+							: { match: streamOptions.match }),
+						handle(view) {
+							taken += 1;
+							return {
+								type: "stream",
+								open(stream) {
+									stream.head(streamOptions.status ?? 200, {
+										"content-type": "text/event-stream; charset=utf-8",
+										"cache-control": "no-cache",
+										...streamOptions.headers,
+									});
+									// An EventSource opens on the headers, before any event.
+									stream.flush();
+									let sent = 0;
+									const connection: SseConnection = {
+										request: view,
+										lastEventId: stream.requestHeaders["last-event-id"],
+										get sent() {
+											return sent;
+										},
+										async send(event: SseEvent | string) {
+											const chunk = encodeSseEvent(event);
+											await stream.write(chunk);
+											sent += 1;
+											context.timeline.append({
+												protocol: name,
+												kind: "event",
+												direction: "in",
+												endpoint: view.url.pathname,
+												source: "stub",
+												data: chunk,
+												value: event,
+												correlation: view.correlation,
+												context: view.context,
+												...(view.page === undefined ? {} : { page: view.page }),
+											});
+										},
+										end: () => stream.end(),
+										async cut() {
+											stream.cut();
+											// The stage records the end before `closed` resolves.
+											await stream.closed;
+										},
+										closed: stream.closed,
+									};
+									if (streamOptions.retry !== undefined)
+										void stream
+											.write(`retry: ${streamOptions.retry}\n\n`)
+											.catch(() => {});
+									connections.push(connection);
+								},
+							};
+						},
+					});
+					return {
+						get hits() {
+							return rule.hits;
+						},
+						next: (waitOptions) => connections.next(waitOptions),
+						get connections() {
+							return connections.items;
+						},
+						async broadcast(event) {
+							for (const connection of connections.items)
+								await connection.send(event).catch(() => {});
+						},
+						remove: () => rule.remove(),
+					};
+				},
+				async events(filter = {}) {
+					await context.sync();
+					return context.timeline.frames({
+						protocol: name,
+						kind: "event",
+						...(filter.endpoint === undefined
+							? {}
+							: { endpoint: filter.endpoint }),
+					});
+				},
+			};
+			return { api };
+		},
+	});
+}

package/src/features/sse/lib/encode.ts

@@ -0,0 +1,28 @@
+import type { SseEvent } from "../model/types.js";
+
+/**
+ * Encode one event in the text/event-stream format. Multi-line data becomes
+ * several `data:` lines — a single line with an embedded newline would end
+ * the field early and the client would see half the payload.
+ */
+export function encodeSseEvent(event: SseEvent | string): string {
+	if (typeof event === "string") return `${dataLines(event)}\n`;
+	let out = "";
+	if (event.comment !== undefined)
+		for (const line of event.comment.split(/\r?\n/)) out += `: ${line}\n`;
+	if (event.event !== undefined) out += `event: ${event.event}\n`;
+	if (event.id !== undefined) out += `id: ${event.id}\n`;
+	if (event.retry !== undefined) out += `retry: ${event.retry}\n`;
+	if (event.data !== undefined)
+		out += dataLines(
+			typeof event.data === "string" ? event.data : JSON.stringify(event.data),
+		);
+	return `${out}\n`;
+}
+
+function dataLines(text: string): string {
+	return text
+		.split(/\r?\n/)
+		.map((line) => `data: ${line}\n`)
+		.join("");
+}

package/src/features/sse/model/types.ts

@@ -0,0 +1,72 @@
+import type { Frame } from "../../../entities/frame/index.js";
+import type {
+	HttpRequestView,
+	StreamEnd,
+} from "../../../entities/plugin/index.js";
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+
+/** One server-sent event. A non-string `data` is sent as JSON. */
+export interface SseEvent {
+	readonly data?: unknown;
+	readonly event?: string;
+	readonly id?: string;
+	/** Reconnection delay the client should use, in milliseconds. */
+	readonly retry?: number;
+	/** A `:` comment line, e.g. a keep-alive. */
+	readonly comment?: string;
+}
+
+/** How a connection ended. `cancelled` means the page closed it. */
+export type SseEnd = StreamEnd;
+
+export interface SseConnection {
+	readonly request: HttpRequestView;
+	/**
+	 * The `Last-Event-ID` the client reconnected with. Read off the request the
+	 * stream server received: the browser's network stack adds it after
+	 * Playwright's route has seen the request, so `request.headers` lacks it.
+	 */
+	readonly lastEventId: string | undefined;
+	/** Events written so far. */
+	readonly sent: number;
+	/** Write an event. A string is sent as `data`. Resolves once written. */
+	send(event: SseEvent | string): Promise<void>;
+	/**
+	 * Close cleanly; EventSource will reconnect after its retry delay.
+	 * Resolves once the end is on the timeline.
+	 */
+	end(): Promise<void>;
+	/**
+	 * Reset the connection, as a network drop would. Resolves once the cut is
+	 * on the timeline.
+	 */
+	cut(): Promise<void>;
+	readonly closed: Promise<SseEnd>;
+}
+
+export interface SseStreamOptions {
+	readonly times?: number;
+	readonly status?: number;
+	readonly headers?: Readonly<Record<string, string>>;
+	/** Sent before anything else: the client's reconnection delay. */
+	readonly retry?: number;
+	readonly match?: (request: HttpRequestView) => boolean;
+}
+
+export interface SseStub {
+	/** Requests this stub answered. */
+	readonly hits: number;
+	/** The next connection the page opens (or opened and nobody took). */
+	next(options?: { readonly timeout?: number }): Promise<SseConnection>;
+	readonly connections: readonly SseConnection[];
+	/** Send to every open connection. */
+	broadcast(event: SseEvent | string): Promise<void>;
+	remove(): Promise<void>;
+}
+
+export interface SseApi {
+	/** Answer matching requests with an event stream the test drives. */
+	stream(url: UrlMatcher, options?: SseStreamOptions): Promise<SseStub>;
+	/** Events sent so far, oldest first. */
+	events(filter?: { readonly endpoint?: string | RegExp }): Promise<Frame[]>;
+}

package/src/features/webrtc/index.ts

@@ -0,0 +1,6 @@
+export { webrtc } from "./lib/create-webrtc.js";
+export type {
+	RtcDirection,
+	WebRtcApi,
+	WebRtcOptions,
+} from "./model/types.js";

package/src/features/webrtc/lib/create-webrtc.ts

@@ -0,0 +1,149 @@
+import {
+	definePlugin,
+	type WirePlugin,
+} from "../../../entities/plugin/index.js";
+import { toBase64, toBytes } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type {
+	RtcInjectArgs,
+	RtcPageConfig,
+	RtcPageState,
+	WebRtcApi,
+	WebRtcOptions,
+} from "../model/types.js";
+import { installWebRtc } from "./rtc-page-module.js";
+import { toFrame } from "./to-frame.js";
+
+/** The calls in force on each label; a label with none is not suppressed. */
+type Suppressions = Map<string, Set<symbol>>;
+
+/**
+ * WebRTC data channels: record what the page sends and receives, drop
+ * messages on one channel while it stays open, and inject messages as the
+ * remote peer.
+ */
+export function webrtc(
+	options: WebRtcOptions = {},
+): WirePlugin<"webrtc", WebRtcApi> {
+	return definePlugin({
+		name: "webrtc",
+		scope: "Rtc",
+		setup(context) {
+			const { name } = context;
+			const suppressIn: Suppressions = new Map();
+			const blockOut: Suppressions = new Map();
+			const directions = options.record ?? ["in", "out"];
+			const config: RtcPageConfig = {
+				labels: options.labels ?? null,
+				recordIn: directions.includes("in"),
+				recordOut: directions.includes("out"),
+				lifecycle: options.lifecycle ?? true,
+			};
+			context.pages.register<RtcPageState, RtcPageConfig>({
+				id: name,
+				install: installWebRtc,
+				config,
+				state: () => ({
+					suppressIn: [...suppressIn.keys()],
+					blockOut: [...blockOut.keys()],
+				}),
+				receive(entries, origin) {
+					for (const entry of entries)
+						context.timeline.append(toFrame(name, entry, origin));
+				},
+			});
+			const refresh = () => context.pages.refresh(name);
+			const hold = (held: Suppressions, label: string, token: symbol) => {
+				const tokens = held.get(label) ?? new Set();
+				tokens.add(token);
+				held.set(label, tokens);
+			};
+			const release = (held: Suppressions, label: string, token: symbol) => {
+				const tokens = held.get(label);
+				// Gone already when `restore` cleared the label first.
+				if (tokens === undefined) return;
+				tokens.delete(token);
+				if (tokens.size === 0) held.delete(label);
+			};
+
+			const api: WebRtcApi = {
+				async frames(filter = {}) {
+					await context.sync();
+					return context.timeline.frames({ ...filter, protocol: name });
+				},
+				async messages(label, messageOptions = {}) {
+					await context.sync();
+					return context.timeline.frames({
+						protocol: name,
+						kind: "message",
+						endpoint: label,
+						...(messageOptions.direction === undefined
+							? {}
+							: { direction: messageOptions.direction }),
+					});
+				},
+				async suppress(label, suppressOptions = {}) {
+					const direction = suppressOptions.direction ?? "in";
+					const token = Symbol(label);
+					if (direction !== "out") hold(suppressIn, label, token);
+					if (direction !== "in") hold(blockOut, label, token);
+					await refresh();
+					return async () => {
+						release(suppressIn, label, token);
+						release(blockOut, label, token);
+						await refresh();
+					};
+				},
+				async restore(label) {
+					if (label === undefined) {
+						suppressIn.clear();
+						blockOut.clear();
+					} else {
+						suppressIn.delete(label);
+						blockOut.delete(label);
+					}
+					await refresh();
+				},
+				async inject(label, data, injectOptions = {}) {
+					const args: RtcInjectArgs =
+						typeof data === "string"
+							? { label, text: data }
+							: { label, data: toBase64(toBytes(data)) };
+					const results = await context.pages.command(
+						name,
+						"inject",
+						args,
+						injectOptions.page === undefined
+							? {}
+							: { page: context.pages.pageId(injectOptions.page) },
+					);
+					return results.reduce<number>(
+						(sum, delivered) => sum + Number(delivered),
+						0,
+					);
+				},
+				async waitForChannel(label, waitOptions = {}) {
+					if (!config.lifecycle)
+						// It would only ever time out: there is no open frame to wait for.
+						throw new WirestageError(
+							"INVALID_STATE",
+							`waitForChannel("${label}") needs lifecycle frames, and this plugin was created with \`lifecycle: false\``,
+						);
+					const [frame] = await context.waitFor(
+						{
+							protocol: name,
+							kind: "lifecycle",
+							endpoint: label,
+							where: (f) => f.meta["event"] === "open",
+						},
+						waitOptions.timeout === undefined
+							? {}
+							: { timeout: waitOptions.timeout },
+					);
+					return frame as NonNullable<typeof frame>;
+				},
+			};
+			return { api };
+		},
+	});
+}

package/src/features/webrtc/lib/rtc-page-module.ts

@@ -0,0 +1,189 @@
+import type { PageModuleEnv } from "../../../entities/plugin/index.js";
+import type {
+	RtcInjectArgs,
+	RtcPageConfig,
+	RtcPageState,
+} from "../model/types.js";
+
+/**
+ * Runs INSIDE the page (serialized): self-contained, `function` declaration.
+ *
+ * Three hooks, each placed so the page's own code is untouched:
+ *
+ * - `RTCDataChannel.prototype.send` is wrapped, so every send on every channel
+ *   is seen as it leaves — the last point the page and a real peer agree on.
+ * - `createDataChannel` is wrapped and the constructor is replaced by one that
+ *   adds a `datachannel` listener first, so every channel — page-created or
+ *   remote-created — gets OUR `message` listener before the page's. Only a
+ *   first listener can `stopImmediatePropagation()` the rest, which is what
+ *   suppression needs; wrapping `onmessage` instead would race the page's own
+ *   assignment of it.
+ * - Injected messages are dispatched as real `MessageEvent`s on the channel,
+ *   so the page's handlers cannot tell them from the peer's.
+ *
+ * All three come off again when the stage detaches.
+ */
+export function installWebRtc(
+	env: PageModuleEnv<RtcPageState, RtcPageConfig>,
+): void {
+	const win = env.window;
+	const PeerConnection = win.RTCPeerConnection;
+	const DataChannel = win.RTCDataChannel;
+	if (typeof PeerConnection !== "function" || typeof DataChannel !== "function")
+		return;
+	const config = env.config;
+	let suppressIn = new Set<string>();
+	let blockOut = new Set<string>();
+	const open = new Map<string, Set<RTCDataChannel>>();
+	const watched = new WeakSet<RTCDataChannel>();
+	const injected = new WeakSet<Event>();
+	/** Listeners added to the page's channels, to take off on detach. */
+	const unwatch: (() => void)[] = [];
+
+	const wanted = (label: string) =>
+		config.labels === null || config.labels.includes(label);
+
+	const emit = (
+		type: string,
+		label: string,
+		data: unknown,
+		extra: Record<string, unknown> = {},
+	) => {
+		const meta: Record<string, unknown> = { label, ...extra };
+		let payload: { data?: string; text?: string } = {};
+		if (typeof data === "string") payload = { text: data };
+		else if (data instanceof ArrayBuffer)
+			payload = { data: env.encode(new Uint8Array(data)) };
+		else if (ArrayBuffer.isView(data))
+			payload = {
+				data: env.encode(
+					new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+				),
+			};
+		// A Blob would need an async read, which would put it out of order with
+		// the frames around it; it is recorded as skipped instead.
+		else if (data !== undefined) meta["skipped"] = "blob";
+		env.emit({ type, at: env.now(), ...payload, meta });
+	};
+
+	const watch = (channel: RTCDataChannel) => {
+		if (watched.has(channel)) return;
+		watched.add(channel);
+		const label = channel.label;
+		const track = () => {
+			let set = open.get(label);
+			if (set === undefined) {
+				set = new Set();
+				open.set(label, set);
+			}
+			set.add(channel);
+			if (config.lifecycle && wanted(label))
+				emit("open", label, undefined, { id: channel.id });
+		};
+		const untrack = () => {
+			open.get(label)?.delete(channel);
+			if (config.lifecycle && wanted(label))
+				emit("close", label, undefined, { id: channel.id });
+		};
+		const onMessage = (event: MessageEvent) => {
+			const mine = injected.has(event);
+			// What the test injects is the point of suppressing the peer:
+			// silence the real one, speak in its place.
+			if (suppressIn.has(label) && !mine) {
+				event.stopImmediatePropagation();
+				if (wanted(label)) emit("suppressed", label, event.data);
+				return;
+			}
+			if (config.recordIn && wanted(label))
+				emit("in", label, event.data, mine ? { injected: true } : {});
+		};
+		if (channel.readyState === "open") track();
+		else channel.addEventListener("open", track, { once: true });
+		channel.addEventListener("close", untrack, { once: true });
+		channel.addEventListener("message", onMessage);
+		unwatch.push(() => {
+			channel.removeEventListener("open", track);
+			channel.removeEventListener("close", untrack);
+			channel.removeEventListener("message", onMessage);
+		});
+	};
+
+	const send = DataChannel.prototype.send;
+	DataChannel.prototype.send = function wirestageSend(
+		this: RTCDataChannel,
+		data: never,
+	): void {
+		const label = this.label;
+		if (blockOut.has(label)) {
+			if (wanted(label)) emit("blocked", label, data);
+			return;
+		}
+		// Recorded once it has left: a send the browser refuses (a channel not
+		// open yet) throws here, and must not land on the timeline as sent.
+		send.call(this, data);
+		if (config.recordOut && wanted(label)) emit("out", label, data);
+	};
+
+	const createDataChannel = PeerConnection.prototype.createDataChannel;
+	PeerConnection.prototype.createDataChannel = function wirestageCreate(
+		this: RTCPeerConnection,
+		label: string,
+		init?: RTCDataChannelInit,
+	): RTCDataChannel {
+		const channel = createDataChannel.call(this, label, init);
+		watch(channel);
+		return channel;
+	};
+
+	function WirestagePeerConnection(
+		...args: ConstructorParameters<typeof RTCPeerConnection>
+	): RTCPeerConnection {
+		// `new.target`, so a page's own subclass still gets its prototype —
+		// and, as with the real constructor, calling it without `new` throws.
+		const connection: RTCPeerConnection = Reflect.construct(
+			PeerConnection,
+			args,
+			new.target as never,
+		);
+		connection.addEventListener("datachannel", (event: RTCDataChannelEvent) =>
+			watch(event.channel),
+		);
+		return connection;
+	}
+	// Same prototype, so `instanceof RTCPeerConnection` and the patched
+	// methods above keep working; statics such as generateCertificate come
+	// through the prototype chain of the function itself.
+	WirestagePeerConnection.prototype = PeerConnection.prototype;
+	Object.setPrototypeOf(WirestagePeerConnection, PeerConnection);
+	win.RTCPeerConnection =
+		WirestagePeerConnection as unknown as typeof RTCPeerConnection;
+
+	env.onState((state) => {
+		suppressIn = new Set(state.suppressIn);
+		blockOut = new Set(state.blockOut);
+	});
+	env.onCommand("inject", (args: RtcInjectArgs) => {
+		let delivered = 0;
+		for (const channel of open.get(args.label) ?? []) {
+			if (channel.readyState !== "open") continue;
+			let data: unknown = args.text;
+			if (data === undefined) {
+				const buffer = env.decode(args.data ?? "").buffer as ArrayBuffer;
+				data = channel.binaryType === "blob" ? new win.Blob([buffer]) : buffer;
+			}
+			const event = new win.MessageEvent("message", { data });
+			injected.add(event);
+			channel.dispatchEvent(event);
+			delivered += 1;
+		}
+		return delivered;
+	});
+	env.onDetach(() => {
+		DataChannel.prototype.send = send;
+		PeerConnection.prototype.createDataChannel = createDataChannel;
+		win.RTCPeerConnection = PeerConnection;
+		for (const undo of unwatch.splice(0)) undo();
+		suppressIn = new Set();
+		blockOut = new Set();
+	});
+}