@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/src/features/webrtc/lib/to-frame.ts

@@ -0,0 +1,63 @@
+import type {
+	Direction,
+	FrameInit,
+	FrameKind,
+	FrameSource,
+} from "../../../entities/frame/index.js";
+import type { PageEntry, PageSource } from "../../../entities/plugin/index.js";
+import { fromBase64 } from "../../../shared/lib/bytes/index.js";
+
+interface Shape {
+	readonly kind: FrameKind;
+	readonly direction: Direction;
+	/** Who produced it: the app, the peer, or the stub that dropped it. */
+	readonly source: FrameSource;
+}
+
+/** Page entry types, as the page module emits them. */
+const SHAPES: Readonly<Record<string, Shape>> = {
+	out: { kind: "message", direction: "out", source: "page" },
+	in: { kind: "message", direction: "in", source: "network" },
+	open: { kind: "lifecycle", direction: "none", source: "page" },
+	close: { kind: "lifecycle", direction: "none", source: "page" },
+	suppressed: { kind: "fault", direction: "in", source: "stub" },
+	blocked: { kind: "fault", direction: "out", source: "stub" },
+};
+
+/** An entry type nobody declared: the page runtime's own `error`. */
+const BROKEN: Shape = { kind: "fault", direction: "none", source: "page" };
+
+/**
+ * One page entry as a frame. A lifecycle frame says which `event` it was, a
+ * fault says its `reason`, as every protocol's do, and an unknown type (the
+ * runtime's own `error`) still lands as a fault instead of vanishing.
+ */
+export function toFrame(
+	protocol: string,
+	entry: PageEntry,
+	origin: PageSource,
+): FrameInit {
+	const shape = SHAPES[entry.type] ?? BROKEN;
+	const label = entry.meta?.["label"];
+	return {
+		protocol,
+		kind: shape.kind,
+		direction: shape.direction,
+		endpoint: typeof label === "string" ? label : "",
+		// A message the test injected is the test's, not the peer's.
+		source: entry.meta?.["injected"] === true ? "test" : shape.source,
+		at: entry.at,
+		...(entry.data === undefined
+			? entry.text === undefined
+				? {}
+				: { data: entry.text }
+			: { data: fromBase64(entry.data) }),
+		meta: {
+			...entry.meta,
+			...(shape.kind === "lifecycle" ? { event: entry.type } : {}),
+			...(shape.kind === "fault" ? { reason: entry.type } : {}),
+		},
+		page: origin.page,
+		context: origin.context,
+	};
+}

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

@@ -0,0 +1,80 @@
+import type { Frame, FrameFilter } from "../../../entities/frame/index.js";
+import type { PagePort } from "../../../shared/api/playwright/index.js";
+
+export interface WebRtcOptions {
+	/**
+	 * Data channel labels to record. Every channel when omitted. Recording a
+	 * 60 Hz channel nobody asserts on costs a base64 copy per frame.
+	 */
+	readonly labels?: readonly string[];
+	/** Directions to record. Both by default. */
+	readonly record?: readonly ("in" | "out")[];
+	/** Record channel open/close as lifecycle frames. Default true. */
+	readonly lifecycle?: boolean;
+}
+
+export type RtcDirection = "in" | "out" | "both";
+
+export interface WebRtcApi {
+	/** Every WebRTC frame (messages, lifecycle, faults), narrowed by `filter`. */
+	frames(filter?: Omit<FrameFilter, "protocol">): Promise<Frame[]>;
+	/** Messages on one channel, oldest first. */
+	messages(
+		label: string,
+		options?: { readonly direction?: "in" | "out" },
+	): Promise<Frame[]>;
+	/**
+	 * Drop messages on `label` while the channel stays open — the lossy-link
+	 * case no server-side knob can produce, because the server is behaving.
+	 * `in` (the default) swallows what the peer sends the page; `out` swallows
+	 * what the page sends. Injected messages still get through, so a test can
+	 * silence the real peer and speak in its place.
+	 *
+	 * Returns a function that undoes exactly this call: the label stays
+	 * suppressed for as long as another call on it is still in force.
+	 */
+	suppress(
+		label: string,
+		options?: { readonly direction?: RtcDirection },
+	): Promise<() => Promise<void>>;
+	/** Undo every suppression on `label`, or on every label. */
+	restore(label?: string): Promise<void>;
+	/**
+	 * Deliver a message to the page as if the remote peer sent it, on every
+	 * open channel with this label (or one page's). Returns how many channels
+	 * received it.
+	 */
+	inject(
+		label: string,
+		data: Uint8Array | string,
+		options?: { readonly page?: PagePort },
+	): Promise<number>;
+	/**
+	 * Resolve with the channel's open frame. Needs `lifecycle` recording, and
+	 * says so at once when it is off.
+	 */
+	waitForChannel(
+		label: string,
+		options?: { readonly timeout?: number },
+	): Promise<Frame>;
+}
+
+/** The page module's fixed configuration. */
+export interface RtcPageConfig {
+	readonly labels: readonly string[] | null;
+	readonly recordIn: boolean;
+	readonly recordOut: boolean;
+	readonly lifecycle: boolean;
+}
+
+/** The page module's live state, pushed to every page on change. */
+export interface RtcPageState {
+	readonly suppressIn: readonly string[];
+	readonly blockOut: readonly string[];
+}
+
+export interface RtcInjectArgs {
+	readonly label: string;
+	readonly data?: string;
+	readonly text?: string;
+}

package/src/features/websocket/index.ts

@@ -0,0 +1,15 @@
+export { websocket } from "./lib/create-websocket.js";
+export type {
+	WebSocketApi,
+	WebSocketOptions,
+	WsCloseInfo,
+	WsCloseOptions,
+	WsConnection,
+	WsData,
+	WsMessage,
+	WsMock,
+	WsMockOptions,
+	WsProxy,
+	WsProxyConnection,
+	WsProxyOptions,
+} from "./model/types.js";

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

@@ -0,0 +1,41 @@
+import {
+	definePlugin,
+	type WirePlugin,
+} from "../../../entities/plugin/index.js";
+import type { WebSocketApi, WebSocketOptions } from "../model/types.js";
+import { createMock } from "./mock.js";
+import { createProxy } from "./proxy.js";
+
+/**
+ * WebSockets: fake servers driven from the test, and pass-through proxies
+ * that record and can drop messages. Both are rules on the stage's socket
+ * router, which owns the browser's side of it.
+ */
+export function websocket(
+	options: WebSocketOptions = {},
+): WirePlugin<"websocket", WebSocketApi> {
+	return definePlugin({
+		name: "websocket",
+		scope: "Ws",
+		setup(context) {
+			const { name } = context;
+			if (!options.lazy) context.sockets.prepare();
+			const api: WebSocketApi = {
+				mock: (url, mockOptions = {}) =>
+					createMock(context, name, url, mockOptions),
+				proxy: (url, proxyOptions = {}) =>
+					createProxy(context, name, url, proxyOptions),
+				async frames(filter = {}) {
+					await context.sync();
+					return context.timeline.frames({
+						protocol: name,
+						...(filter.endpoint === undefined
+							? {}
+							: { endpoint: filter.endpoint }),
+					});
+				},
+			};
+			return { api };
+		},
+	});
+}

package/src/features/websocket/lib/mock.ts

@@ -0,0 +1,114 @@
+import type { PluginContext } from "../../../entities/plugin/index.js";
+import {
+	createArrivals,
+	createDeferred,
+} from "../../../shared/lib/async/index.js";
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+import type {
+	WsCloseInfo,
+	WsConnection,
+	WsMessage,
+	WsMock,
+	WsMockOptions,
+} from "../model/types.js";
+import {
+	closedError,
+	createSocketLog,
+	encodeOutgoing,
+	toMessage,
+} from "./wire.js";
+
+/** A fake server: every matching socket becomes a connection the test drives. */
+export async function createMock(
+	context: PluginContext,
+	protocol: string,
+	url: UrlMatcher,
+	options: WsMockOptions,
+): Promise<WsMock> {
+	const connections = createArrivals<WsConnection>({
+		clock: context.clock,
+		label: "WebSocket connection",
+	});
+	/** Each connection, with whether it is over: `broadcast` skips those. */
+	const ended = new Map<WsConnection, () => boolean>();
+	const rule = await context.sockets.add({
+		protocol,
+		label: `mock ${String(url)}`,
+		url,
+		...(options.times === undefined ? {} : { times: options.times }),
+		async open(socket) {
+			const log = createSocketLog(context, protocol, socket);
+			const messages = createArrivals<WsMessage>({
+				clock: context.clock,
+				label: `message on ${socket.url.pathname}`,
+			});
+			const closed = createDeferred<WsCloseInfo>();
+			// The page hears of a close the stub starts through the same event
+			// as its own; whoever asked first is who closed.
+			let closedBy: "page" | "stub" = "page";
+			log("lifecycle", "none", "page", { event: "open", url: socket.url.href });
+			socket.page.onMessage((raw) => {
+				messages.push(toMessage("out", raw, context.clock.now()));
+				log("message", "out", "page", {}, raw);
+			});
+			socket.page.onClose((code, reason) => {
+				// Once per connection: a close is reported again when the route
+				// completes it, which the close below does.
+				if (closed.settled) return;
+				closed.resolve({ code, reason });
+				log("lifecycle", "none", closedBy, { event: "close", code, reason });
+				// A handler here turns off Playwright's own answer to the page's
+				// close, and without one the page's socket would hang in CLOSING.
+				if (closedBy === "page")
+					void socket.page.close({
+						...(code === undefined ? {} : { code }),
+						...(reason === undefined ? {} : { reason }),
+					});
+			});
+			// Over from the moment the stub closes it, before the page hears.
+			const over = () => closed.settled || closedBy === "stub";
+			const connection: WsConnection = {
+				url: socket.url.href,
+				get messages() {
+					return messages.items;
+				},
+				nextMessage: (waitOptions) => messages.next(waitOptions),
+				send(data) {
+					if (over()) throw closedError(socket);
+					const encoded = encodeOutgoing(data);
+					socket.page.send(encoded);
+					log("message", "in", "stub", {}, encoded);
+				},
+				async close(closeOptions) {
+					closedBy = "stub";
+					await socket.page.close(closeOptions);
+				},
+				closed: closed.promise,
+			};
+			connections.push(connection);
+			ended.set(connection, over);
+			try {
+				await options.onConnect?.(connection);
+			} catch (error) {
+				// The stage closes the socket of a rule that throws: the close
+				// the page then hears of is the stub's doing.
+				closedBy = "stub";
+				throw error;
+			}
+		},
+	});
+	return {
+		get hits() {
+			return rule.hits;
+		},
+		get connections() {
+			return connections.items;
+		},
+		next: (waitOptions) => connections.next(waitOptions),
+		broadcast(data) {
+			for (const [connection, isOver] of ended)
+				if (!isOver()) connection.send(data);
+		},
+		remove: () => rule.remove(),
+	};
+}

package/src/features/websocket/lib/proxy.ts

@@ -0,0 +1,141 @@
+import type {
+	PluginContext,
+	SocketPeer,
+} from "../../../entities/plugin/index.js";
+import {
+	createArrivals,
+	createDeferred,
+} from "../../../shared/lib/async/index.js";
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+import type {
+	WsCloseInfo,
+	WsMessage,
+	WsProxy,
+	WsProxyConnection,
+	WsProxyOptions,
+} from "../model/types.js";
+import {
+	closedError,
+	createSocketLog,
+	encodeOutgoing,
+	toMessage,
+} from "./wire.js";
+
+/**
+ * A pass-through to the real server that records both directions and can
+ * drop or inject messages on the way.
+ */
+export async function createProxy(
+	context: PluginContext,
+	protocol: string,
+	url: UrlMatcher,
+	options: WsProxyOptions,
+): Promise<WsProxy> {
+	const connections = createArrivals<WsProxyConnection>({
+		clock: context.clock,
+		label: "WebSocket connection",
+	});
+	const rule = await context.sockets.add({
+		protocol,
+		label: `proxy ${String(url)}`,
+		url,
+		...(options.times === undefined ? {} : { times: options.times }),
+		open(socket) {
+			const log = createSocketLog(context, protocol, socket);
+			const page = socket.page;
+			const server = socket.connectToServer();
+			const messages = createArrivals<WsMessage>({
+				clock: context.clock,
+				label: `message on ${socket.url.pathname}`,
+			});
+			const closed = createDeferred<WsCloseInfo>();
+			log("lifecycle", "none", "page", { event: "open", url: socket.url.href });
+			const forward = (
+				direction: "in" | "out",
+				raw: string | Uint8Array,
+				to: SocketPeer,
+			) => {
+				const passing = toMessage(direction, raw, context.clock.now());
+				messages.push(passing);
+				if (options.drop?.(passing)) {
+					log("fault", direction, "stub", { reason: "dropped" }, raw);
+					return;
+				}
+				log(
+					"message",
+					direction,
+					direction === "out" ? "page" : "network",
+					{},
+					raw,
+				);
+				to.send(raw);
+			};
+			page.onMessage((raw) => forward("out", raw, server));
+			server.onMessage((raw) => forward("in", raw, page));
+			// A close handler turns off Playwright's own forwarding of the close,
+			// so whichever end closes first, both are closed by hand: the other
+			// end to pass the close on, and the end that started it to complete
+			// it — the page's socket hangs in CLOSING until its end is closed.
+			// Once: each of those closes is reported back through a handler.
+			let closedBy: "test" | undefined;
+			const relay =
+				(from: "page" | "network") =>
+				(code: number | undefined, reason: string | undefined) => {
+					if (closed.settled) return;
+					closed.resolve({ code, reason });
+					log("lifecycle", "none", closedBy ?? from, {
+						event: "close",
+						code,
+						reason,
+					});
+					const passed = {
+						...(code === undefined ? {} : { code }),
+						...(reason === undefined ? {} : { reason }),
+					};
+					void page.close(passed);
+					void server.close(passed);
+				};
+			page.onClose(relay("page"));
+			server.onClose(relay("network"));
+			// Over from the moment the test closes it, before either end hears.
+			const over = () => closed.settled || closedBy !== undefined;
+			connections.push({
+				url: socket.url.href,
+				get messages() {
+					return messages.items;
+				},
+				nextMessage: (waitOptions) => messages.next(waitOptions),
+				toPage(data) {
+					if (over()) throw closedError(socket);
+					const encoded = encodeOutgoing(data);
+					page.send(encoded);
+					log("message", "in", "test", { injected: true }, encoded);
+				},
+				toServer(data) {
+					if (over()) throw closedError(socket);
+					const encoded = encodeOutgoing(data);
+					server.send(encoded);
+					log("message", "out", "test", { injected: true }, encoded);
+				},
+				async close(closeOptions) {
+					closedBy = "test";
+					await Promise.all([
+						page.close(closeOptions),
+						server.close(closeOptions),
+					]);
+				},
+				closed: closed.promise,
+			});
+		},
+	});
+	return {
+		get hits() {
+			return rule.hits;
+		},
+		get connections() {
+			return connections.items;
+		},
+		next: (waitOptions) => connections.next(waitOptions),
+		remove: () => rule.remove(),
+	};
+}

package/src/features/websocket/lib/wire.ts

@@ -0,0 +1,78 @@
+import type {
+	Direction,
+	FrameKind,
+	FrameSource,
+} from "../../../entities/frame/index.js";
+import type {
+	PluginContext,
+	SocketView,
+} from "../../../entities/plugin/index.js";
+import { toBytes, utf8 } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type { WsData, WsMessage } from "../model/types.js";
+
+/**
+ * What a send to a connection that is over throws. Playwright would drop
+ * the message without a word, and the timeline would show it delivered.
+ */
+export function closedError(socket: SocketView): WirestageError {
+	return new WirestageError(
+		"CLOSED",
+		`the WebSocket connection to ${socket.url.href} is closed`,
+	);
+}
+
+/** What a test passes to `send`, as the wire carries it. */
+export function encodeOutgoing(data: WsData): string | Uint8Array {
+	if (typeof data === "string") return data;
+	// Any binary form goes out as bytes; only what is left is a value.
+	if (data instanceof ArrayBuffer || ArrayBuffer.isView(data))
+		return toBytes(data);
+	return JSON.stringify(data);
+}
+
+export function toMessage(
+	direction: "in" | "out",
+	raw: string | Uint8Array,
+	at: number,
+): WsMessage {
+	const text = () => (typeof raw === "string" ? raw : utf8(raw));
+	return {
+		direction,
+		data: raw,
+		at,
+		text,
+		json: <T>() => JSON.parse(text()) as T,
+	};
+}
+
+/** Writes one connection's frames: same endpoint, correlation and context. */
+export type SocketLog = (
+	kind: FrameKind,
+	direction: Direction,
+	source: FrameSource,
+	meta: Readonly<Record<string, unknown>>,
+	data?: string | Uint8Array,
+) => void;
+
+export function createSocketLog(
+	context: Pick<PluginContext, "timeline">,
+	protocol: string,
+	socket: SocketView,
+): SocketLog {
+	return (kind, direction, source, meta, data) => {
+		context.timeline.append({
+			protocol,
+			kind,
+			direction,
+			// The path, like every HTTP frame: it reads the same on the dev
+			// server, the preview build and CI, whose origins all differ.
+			endpoint: socket.url.pathname,
+			source,
+			correlation: socket.correlation,
+			context: socket.context,
+			meta,
+			...(data === undefined ? {} : { data }),
+		});
+	};
+}

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

@@ -0,0 +1,130 @@
+import type { Frame } from "../../../entities/frame/index.js";
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+
+export interface WebSocketOptions {
+	/**
+	 * Leave `WebSocket` alone until the first `mock()` or `proxy()`.
+	 *
+	 * By default the plugin routes WebSockets from the moment a context is
+	 * attached, so a mock added mid-test reaches the pages that are already
+	 * open. Playwright routes by replacing `WebSocket` in every document as it
+	 * loads, and a socket no rule takes is passed through to the real server.
+	 * With `lazy`, nothing is replaced until the first rule exists — and that
+	 * rule then applies only to the documents loaded after it.
+	 */
+	readonly lazy?: boolean;
+}
+
+/** What a test may send: text, bytes in any binary form, or a value sent as JSON. */
+export type WsData = string | ArrayBuffer | ArrayBufferView | object;
+
+export interface WsMessage {
+	/** `out` came from the page, `in` went to it. */
+	readonly direction: "in" | "out";
+	readonly data: string | Uint8Array;
+	readonly at: number;
+	text(): string;
+	json<T = unknown>(): T;
+}
+
+export interface WsCloseInfo {
+	readonly code: number | undefined;
+	readonly reason: string | undefined;
+}
+
+export interface WsCloseOptions {
+	/**
+	 * The code the page's socket closes with: any a server may send. A proxy
+	 * also closes the real server's end, through the browser, which sends
+	 * only 1000 and 3000-4999 — another code reaches the page as given and
+	 * the server as a normal closure, 1000.
+	 */
+	readonly code?: number;
+	/**
+	 * The page gets it whole. A proxy's real server gets at most 123 bytes
+	 * of it, cut on a character: all a close frame carries, and all the
+	 * browser will send.
+	 */
+	readonly reason?: string;
+}
+
+export interface WsConnection {
+	readonly url: string;
+	/** Messages the page sent, oldest first. */
+	readonly messages: readonly WsMessage[];
+	/** The next message the page sends (or sent and nobody took). */
+	nextMessage(options?: { readonly timeout?: number }): Promise<WsMessage>;
+	/**
+	 * Send to the page. Throws `CLOSED` once the connection is over — from
+	 * the moment `close()` is called — since the page would never get it.
+	 */
+	send(data: WsData): void;
+	close(options?: WsCloseOptions): Promise<void>;
+	/** Resolves when the connection is over, whoever closed it. */
+	readonly closed: Promise<WsCloseInfo>;
+}
+
+export interface WsMockOptions {
+	/** Answer this many connections, then leave the rest to the next rule. */
+	readonly times?: number;
+	/**
+	 * Called for each new connection, e.g. to send a greeting. The page's
+	 * socket opens once it settles. If it throws, the stage closes the
+	 * page's socket with 1011 and records a `rule-error` fault.
+	 */
+	readonly onConnect?: (connection: WsConnection) => void | Promise<void>;
+}
+
+export interface WsMock {
+	/** Connections this mock took. */
+	readonly hits: number;
+	readonly connections: readonly WsConnection[];
+	/** The next connection the page opens (or opened and nobody took). */
+	next(options?: { readonly timeout?: number }): Promise<WsConnection>;
+	/** Send to every connection that is not over yet. */
+	broadcast(data: WsData): void;
+	/** New connections go to the real server again. */
+	remove(): Promise<void>;
+}
+
+export interface WsProxyOptions {
+	/** Proxy this many connections, then leave the rest to the next rule. */
+	readonly times?: number;
+	/** Drop a message instead of forwarding it. Dropped messages are recorded as faults. */
+	readonly drop?: (message: WsMessage) => boolean;
+}
+
+export interface WsProxyConnection {
+	readonly url: string;
+	/** Messages in both directions, oldest first. */
+	readonly messages: readonly WsMessage[];
+	nextMessage(options?: { readonly timeout?: number }): Promise<WsMessage>;
+	/**
+	 * Inject a message to the page, as if the server sent it. Throws
+	 * `CLOSED` once the connection is over, as `toServer` does.
+	 */
+	toPage(data: WsData): void;
+	/** Inject a message to the server, as if the page sent it. */
+	toServer(data: WsData): void;
+	/** Close both sides. */
+	close(options?: WsCloseOptions): Promise<void>;
+	/** Resolves when the connection is over, whoever closed it. */
+	readonly closed: Promise<WsCloseInfo>;
+}
+
+export interface WsProxy {
+	/** Connections this proxy took. */
+	readonly hits: number;
+	readonly connections: readonly WsProxyConnection[];
+	next(options?: { readonly timeout?: number }): Promise<WsProxyConnection>;
+	remove(): Promise<void>;
+}
+
+export interface WebSocketApi {
+	/** Answer matching WebSockets with a fake server the test drives. */
+	mock(url: UrlMatcher, options?: WsMockOptions): Promise<WsMock>;
+	/** Pass matching WebSockets through to the real server, recording and optionally dropping messages. */
+	proxy(url: UrlMatcher, options?: WsProxyOptions): Promise<WsProxy>;
+	/** Every recorded frame: opens, messages, drops, closes. */
+	frames(filter?: { readonly endpoint?: string | RegExp }): Promise<Frame[]>;
+}