@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/src/widgets/stage/lib/reads.ts

@@ -0,0 +1,128 @@
+import type {
+	Frame,
+	FrameFilter,
+	Timeline,
+} from "../../../entities/frame/index.js";
+import type { WaitForOptions } from "../../../entities/plugin/index.js";
+import type { Clock } from "../../../shared/lib/clock/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type { StageCore } from "../model/stage.js";
+
+export interface ReadsDeps {
+	readonly timeline: Timeline;
+	readonly clock: Clock;
+	/** Flush every page buffer into the timeline. */
+	readonly sync: () => Promise<void>;
+	/** Defaults for `waitFor`, in milliseconds. */
+	readonly wait: { readonly timeout: number; readonly interval: number };
+}
+
+/**
+ * Frames a report holds unless asked otherwise. A report is read from its
+ * end, and an unbounded one grows with the test: a long run would attach
+ * tens of megabytes, or fail to serialize at all.
+ */
+const REPORT_LIMIT = 1_000;
+
+export type StageReads = Pick<
+	StageCore,
+	"frames" | "drain" | "mark" | "since" | "between" | "waitFor" | "report"
+>;
+
+/**
+ * The stage's reads of its timeline. Every one flushes the page buffers
+ * first: that flush is what makes arrival order the order things happened in.
+ */
+export function createReads(deps: ReadsDeps): StageReads {
+	const { timeline, clock, sync } = deps;
+	const drainCursor = timeline.cursor();
+
+	const requireMarker = (name: string): Frame => {
+		const marker = timeline.marker(name);
+		if (marker === undefined)
+			throw new WirestageError(
+				"INVALID_ARGUMENT",
+				timeline.evicted > 0
+					? `no marker "${name}" on the timeline: it was never placed, or it was among the ${timeline.evicted} frame(s) dropped at capacity`
+					: `no marker "${name}" on the timeline; place one with stage.mark("${name}")`,
+			);
+		return marker;
+	};
+
+	return {
+		async frames(filter) {
+			await sync();
+			return timeline.frames(filter);
+		},
+		async drain(filter) {
+			await sync();
+			return drainCursor.take(filter);
+		},
+		async mark(name, meta) {
+			await sync();
+			return timeline.append({
+				protocol: "wirestage",
+				kind: "marker",
+				direction: "none",
+				endpoint: name,
+				source: "test",
+				...(meta === undefined ? {} : { meta }),
+			});
+		},
+		async since(marker, filter) {
+			await sync();
+			const after = requireMarker(marker).seq;
+			return timeline.frames({
+				...filter,
+				after: Math.max(after, filter?.after ?? 0),
+			});
+		},
+		async between(from, to, filter) {
+			await sync();
+			const start = requireMarker(from).seq;
+			const end = requireMarker(to).seq;
+			const where = filter?.where;
+			return timeline.frames({
+				...filter,
+				after: Math.max(start, filter?.after ?? 0),
+				where: (frame) =>
+					frame.seq < end && (where === undefined || where(frame)),
+			});
+		},
+		async waitFor(filter: FrameFilter, options: WaitForOptions = {}) {
+			const count = options.count ?? 1;
+			const timeout = options.timeout ?? deps.wait.timeout;
+			const interval = options.interval ?? deps.wait.interval;
+			const deadline = clock.now() + timeout;
+			for (;;) {
+				await sync();
+				const found = timeline.frames(filter);
+				if (found.length >= count) return found;
+				const remaining = deadline - clock.now();
+				if (remaining <= 0)
+					throw new WirestageError(
+						"TIMEOUT",
+						`waited ${timeout} ms for ${count} frame(s) matching ${describeFilter(filter)}; ${found.length} matched. Last frames:\n${timeline.format(undefined, { limit: 20 })}`,
+						{ details: { count, matched: found.length, timeout } },
+					);
+				await clock.sleep(Math.min(interval, remaining));
+			}
+		},
+		report(filter, options = {}) {
+			const limit = options.limit ?? REPORT_LIMIT;
+			return {
+				snapshot: timeline.snapshot(filter, { limit }),
+				text: timeline.format(filter, { limit }),
+			};
+		},
+	};
+}
+
+/** A filter as JSON, with RegExps and callbacks spelled out instead of lost. */
+function describeFilter(filter: FrameFilter): string {
+	return JSON.stringify(filter, (_key, value: unknown) => {
+		if (value instanceof RegExp) return value.toString();
+		if (typeof value === "function") return "[function]";
+		return value;
+	});
+}

package/src/widgets/stage/lib/response-stream.ts

@@ -0,0 +1,139 @@
+import type {
+	IncomingMessage,
+	OutgoingHttpHeader,
+	ServerResponse,
+} from "node:http";
+
+import type {
+	ResponseStream,
+	StreamEnd,
+} from "../../../entities/plugin/index.js";
+import { createDeferred } from "../../../shared/lib/async/index.js";
+import { toBytes } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+
+/** A stream as the stage serves it: the rule's end of it, and the stage's. */
+export interface ServedStream {
+	/** What the rule writes. */
+	readonly stream: ResponseStream;
+	/** The stub asked for the end, and `closed` is on its way. */
+	readonly closing: boolean;
+	/**
+	 * The rule writing the stream failed: answer 500 with `body` while
+	 * nothing has gone out, and cut the connection after. False when the
+	 * response was over first — ended, cut, or let go of by the page.
+	 */
+	fail(body: string): boolean;
+}
+
+/**
+ * A Node response as the stream a rule writes: the adapter between the
+ * stream server's sockets and the plugin contract, which knows nothing of
+ * Node. `onClose` hears how the response ended before `closed` resolves, so
+ * whoever awaits `closed` finds the end already on record.
+ */
+export function createResponseStream(
+	request: IncomingMessage,
+	response: ServerResponse,
+	onClose: (end: StreamEnd, failed: boolean) => void,
+): ServedStream {
+	let state: "open" | "ended" | "cut" = "open";
+	let failed = false;
+	const closed = createDeferred<StreamEnd>();
+	response.once("close", () => {
+		// Not ended and not cut: the page let go of it.
+		const end = state === "open" ? "cancelled" : state;
+		onClose(end, failed);
+		closed.resolve(end);
+	});
+	/** The stream server's own headers (CORS, `connection`), before the rule's. */
+	const own = Object.entries(response.getHeaders());
+	/** Back to those: what a rule's head set is gone, what it replaced is back. */
+	const restore = () => {
+		for (const name of response.getHeaderNames()) response.removeHeader(name);
+		for (const [name, value] of own)
+			response.setHeader(name, value as OutgoingHttpHeader);
+	};
+	/**
+	 * Whether a write can reach the page. Node drops a write — callback and
+	 * all — into a socket destroyed or closed for writing, which is what the
+	 * page letting go leaves, well before the response reports its close.
+	 */
+	const writable = () => state === "open" && response.socket?.writable === true;
+	const requestHeaders: Record<string, string> = {};
+	for (const [name, value] of Object.entries(request.headers))
+		requestHeaders[name] = String(value);
+	return {
+		stream: {
+			requestHeaders,
+			head(status, headers = {}) {
+				// Node checks a status only as the head goes out, and refused by
+				// `end()` it leaves the response broken: a 500 after it has no body.
+				if (!Number.isInteger(status) || status < 100 || status > 999)
+					throw new WirestageError(
+						"INVALID_ARGUMENT",
+						`a response status is an integer from 100 to 999, got ${status}`,
+					);
+				// Kept off the wire until the first write or flush, so a rule that
+				// fails before then can still be answered with its 500.
+				restore();
+				response.statusCode = status;
+				for (const [name, value] of Object.entries(headers)) {
+					// The stream server's to say: one response per connection.
+					if (name.toLowerCase() === "connection") continue;
+					// Several values, one per line (`set-cookie`): Node sends a
+					// header line for each, and refuses a value with a newline.
+					const values = value.split("\n");
+					response.setHeader(name, values.length > 1 ? values : value);
+				}
+			},
+			flush() {
+				response.flushHeaders();
+			},
+			write(chunk) {
+				return new Promise<void>((resolve, reject) => {
+					if (!writable()) {
+						reject(
+							new WirestageError("CLOSED", "the response stream is closed"),
+						);
+						return;
+					}
+					response.write(toBytes(chunk), (error) =>
+						error ? reject(error) : resolve(),
+					);
+				});
+			},
+			async end() {
+				if (writable()) {
+					state = "ended";
+					response.end();
+				}
+				await closed.promise;
+			},
+			cut() {
+				if (!writable()) return;
+				state = "cut";
+				response.destroy();
+			},
+			closed: closed.promise,
+		},
+		get closing() {
+			return state !== "open" && !closed.settled;
+		},
+		fail(body) {
+			if (!writable()) return false;
+			failed = true;
+			if (response.headersSent) {
+				state = "cut";
+				response.destroy();
+				return true;
+			}
+			state = "ended";
+			restore();
+			response
+				.writeHead(500, { "content-type": "text/plain; charset=utf-8" })
+				.end(body);
+			return true;
+		},
+	};
+}

package/src/widgets/stage/lib/socket-router.ts

@@ -0,0 +1,300 @@
+import type { Timeline } from "../../../entities/frame/index.js";
+import type {
+	SocketPeer,
+	SocketRouter,
+	SocketRule,
+	SocketRuleHandle,
+	SocketView,
+} from "../../../entities/plugin/index.js";
+import type { WebSocketRoutePort } from "../../../shared/api/playwright/index.js";
+import { toBuffer } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type { ScopedLogger } from "../../../shared/lib/logger/index.js";
+import { compileUrlMatcher } from "../../../shared/lib/match/index.js";
+import type { AttachedContext } from "./attached-context.js";
+
+export interface SocketRouterDeps {
+	readonly timeline: Timeline;
+	readonly log: ScopedLogger;
+	readonly correlation: () => string;
+}
+
+export interface SocketRouterEngine extends SocketRouter {
+	attach(attachment: AttachedContext): Promise<void>;
+	detach(attachment: AttachedContext): void;
+}
+
+interface Entry {
+	readonly rule: SocketRule;
+	readonly matchesUrl: (url: URL) => boolean;
+	remaining: number | undefined;
+	hits: number;
+	active: boolean;
+}
+
+type CloseOptions = Parameters<SocketPeer["close"]>[0];
+
+/** What a script may pass to `WebSocket.close()`: 1000, or 3000-4999. */
+const sendable = (code: number): boolean =>
+	code === 1000 || (code >= 3000 && code <= 4999);
+
+const encoder = new TextEncoder();
+
+/**
+ * A close reason cut to what a close frame carries: 123 bytes of UTF-8 (the
+ * frame's 125, less the code), ending on a whole character.
+ */
+const fitReason = (reason: string): string =>
+	// `encodeInto` stops before the first character that does not fit whole.
+	reason.slice(0, encoder.encodeInto(reason, new Uint8Array(123)).read);
+
+/**
+ * A close as the server's end can carry it out. Playwright closes that end
+ * with the browser's own `WebSocket.close(code, reason)`, which throws on a
+ * code a script may not send, on a reason without a code and on a reason
+ * over 123 bytes — and Playwright swallows the error, which leaves the
+ * connection open for good. Such a close goes out as a normal closure, 1000,
+ * with its reason cut to fit: the close is the point.
+ */
+const forServer = (options: CloseOptions): CloseOptions => {
+	const { code, reason } = options ?? {};
+	if (code === undefined && reason === undefined) return options;
+	return {
+		code: code !== undefined && sendable(code) ? code : 1000,
+		...(reason === undefined ? {} : { reason: fitReason(reason) }),
+	};
+};
+
+/** The message handler of an end whose messages the rule does not take. */
+const drop = (): void => {};
+
+/**
+ * Turns WebSocket rules into ONE Playwright WebSocket route per attached
+ * context, whose predicate asks the live rule list.
+ *
+ * One route, because Playwright cannot take a WebSocket route out again: a
+ * removed rule, or a detached context, simply stops matching, which sends the
+ * socket to the real server. And not before it is needed, because routing
+ * replaces `WebSocket` in every document of the context — the first rule
+ * installs it, or `prepare()` does at attach.
+ */
+export function createSocketRouter(deps: SocketRouterDeps): SocketRouterEngine {
+	/** Active rules, oldest first. */
+	const entries: Entry[] = [];
+	const attachments = new Set<AttachedContext>();
+	const routes = new Map<AttachedContext, Promise<void>>();
+	let prepared = false;
+
+	/** The newest rule that wants a socket to `url`. */
+	const taker = (url: URL): Entry | undefined =>
+		entries.findLast((entry) => {
+			try {
+				return entry.matchesUrl(url);
+			} catch (error) {
+				// The caller's predicate; one that throws must not break every
+				// socket of the context.
+				deps.log.error(
+					"rule's URL matcher failed",
+					{ rule: entry.rule.label, url: url.href },
+					error,
+				);
+				return false;
+			}
+		});
+
+	const retire = (entry: Entry) => {
+		if (!entry.active) return;
+		entry.active = false;
+		entries.splice(entries.indexOf(entry), 1);
+	};
+
+	/**
+	 * One end, as a rule drives it. Playwright calls the rule's handlers from
+	 * its own event dispatch, where a throw is an uncaught exception and a
+	 * rejection an unhandled one — either surfacing in whichever test runs
+	 * next. A handler that fails fails the rule instead, as `open` does.
+	 */
+	const peer = (
+		route: WebSocketRoutePort,
+		onFailure: (error: unknown) => Promise<void>,
+		close: (options: CloseOptions) => CloseOptions = (options) => options,
+	): SocketPeer => {
+		const guarded =
+			<Args extends unknown[]>(handler: (...args: Args) => void) =>
+			(...args: Args): void => {
+				try {
+					// Typed `void`, yet an async function is a valid handler.
+					const result: unknown = handler(...args);
+					if (result instanceof Promise) result.catch(onFailure);
+				} catch (error) {
+					void onFailure(error);
+				}
+			};
+		return {
+			send: (data) =>
+				route.send(typeof data === "string" ? data : toBuffer(data)),
+			close: (options) => route.close(close(options)),
+			onMessage: (handler) => route.onMessage(guarded(handler)),
+			onClose: (handler) => route.onClose(guarded(handler)),
+		};
+	};
+
+	/**
+	 * A rule that throws, in `open` or in a handler it set, is a bug in the
+	 * test. Say which rule failed — in the log, on the timeline, and in the
+	 * reason the page's socket closes with — and close both ends: the page's
+	 * socket would otherwise sit open with nobody answering it, and a server
+	 * the rule connected would stay connected. 1011 is a server's "internal
+	 * error"; the server's end gets 1000, as a script may not send 1011.
+	 */
+	const fail = async (
+		rule: SocketRule,
+		view: SocketView,
+		server: SocketPeer | undefined,
+		error: unknown,
+	): Promise<void> => {
+		const message = error instanceof Error ? error.message : String(error);
+		deps.log.error(
+			"socket rule failed",
+			{ rule: rule.label, url: view.url.href },
+			error,
+		);
+		deps.timeline.append({
+			protocol: rule.protocol,
+			kind: "fault",
+			direction: "none",
+			endpoint: view.url.pathname,
+			source: "stub",
+			correlation: view.correlation,
+			context: view.context,
+			meta: { reason: "rule-error", rule: rule.label, error: message },
+		});
+		const closing = {
+			code: 1011,
+			// Cut like the server's end, though the page's would take it whole:
+			// no real server could send the page a longer one.
+			reason: fitReason(`wirestage: rule "${rule.label}" failed: ${message}`),
+		};
+		await Promise.all([view.page.close(closing), server?.close(closing)]);
+	};
+
+	const onSocket = async (
+		attachment: AttachedContext,
+		route: WebSocketRoutePort,
+	): Promise<void> => {
+		const url = new URL(route.url());
+		const entry = attachments.has(attachment) ? taker(url) : undefined;
+		// The rule went, or the context was detached, between Playwright's
+		// check and this call: the socket is the real server's.
+		if (entry === undefined) {
+			route.connectToServer();
+			return;
+		}
+		entry.hits += 1;
+		if (entry.remaining !== undefined && --entry.remaining === 0) retire(entry);
+		// Playwright passes the messages of an end with no handler on to the
+		// other end, unrecorded: a rule that wires one direction would leak
+		// the other. So each end starts with a handler that drops them, which
+		// the rule's own replaces.
+		route.onMessage(drop);
+		let server: SocketPeer | undefined;
+		let failed = false;
+		// Once per socket, for whatever fails first. Marked before failing:
+		// the closes that follow are reported to the rule's handlers, and a
+		// broken one throws again.
+		const failOnce = async (error: unknown): Promise<void> => {
+			if (failed) return;
+			failed = true;
+			await fail(entry.rule, view, server, error);
+		};
+		const view: SocketView = {
+			correlation: deps.correlation(),
+			url,
+			context: attachment.id,
+			page: peer(route, failOnce),
+			connectToServer: () => {
+				if (server === undefined) {
+					const upstream = route.connectToServer();
+					upstream.onMessage(drop);
+					server = peer(upstream, failOnce, forServer);
+				}
+				return server;
+			},
+		};
+		try {
+			// Awaited: Playwright opens the page's end of a socket the rule
+			// did not connect once this handler settles, so an async rule is
+			// wired up before the first message.
+			await entry.rule.open(view);
+		} catch (error) {
+			// Never rejected to Playwright, where it would surface as an
+			// unhandled rejection in whichever test runs next.
+			await failOnce(error);
+		}
+	};
+
+	const ensureRoute = (attachment: AttachedContext): Promise<void> => {
+		let installing = routes.get(attachment);
+		if (installing === undefined) {
+			installing = attachment.context.routeWebSocket(
+				(url) => attachments.has(attachment) && taker(url) !== undefined,
+				(route) => onSocket(attachment, route),
+			);
+			routes.set(attachment, installing);
+			// A failed install must not be remembered as done.
+			installing.catch(() => routes.delete(attachment));
+		}
+		return installing;
+	};
+
+	return {
+		async add(rule): Promise<SocketRuleHandle> {
+			if (
+				rule.times !== undefined &&
+				(!Number.isInteger(rule.times) || rule.times < 1)
+			)
+				throw new WirestageError(
+					"INVALID_ARGUMENT",
+					`rule "${rule.label}": times must be a positive integer, got ${rule.times}`,
+				);
+			const entry: Entry = {
+				rule,
+				matchesUrl: compileUrlMatcher(rule.url),
+				remaining: rule.times,
+				hits: 0,
+				active: true,
+			};
+			entries.push(entry);
+			try {
+				await Promise.all([...attachments].map(ensureRoute));
+			} catch (error) {
+				retire(entry);
+				throw error;
+			}
+			return {
+				get hits() {
+					return entry.hits;
+				},
+				get active() {
+					return entry.active;
+				},
+				async remove() {
+					retire(entry);
+				},
+			};
+		},
+		prepare() {
+			prepared = true;
+		},
+		async attach(attachment) {
+			attachments.add(attachment);
+			if (prepared || entries.length > 0) await ensureRoute(attachment);
+		},
+		detach(attachment) {
+			attachments.delete(attachment);
+			// The route stays in the browser; a context attached again gets a
+			// new one, and this one's predicate never matches again.
+			routes.delete(attachment);
+		},
+	};
+}

package/src/widgets/stage/model/stage.ts

@@ -0,0 +1,110 @@
+import type {
+	Frame,
+	FrameFilter,
+	Timeline,
+	TimelineSnapshot,
+} from "../../../entities/frame/index.js";
+import type {
+	AnyWirePlugin,
+	Attachment,
+	PluginApis,
+	WaitForOptions,
+} from "../../../entities/plugin/index.js";
+import type {
+	ContextPort,
+	PagePort,
+} from "../../../shared/api/playwright/index.js";
+import type { StreamServerOptions } from "../../../shared/api/stream-server/index.js";
+import type { Clock } from "../../../shared/lib/clock/index.js";
+
+export interface StageOptions<Plugins extends readonly AnyWirePlugin[]> {
+	/** The protocols this stage handles. Their APIs appear as `stage.<name>`. */
+	readonly plugins: Plugins;
+	/** Used by drive clients that are not given a URL of their own. */
+	readonly baseURL?: string;
+	/** Frames the timeline keeps. Default 100,000. */
+	readonly capacity?: number;
+	/**
+	 * How long a page batches what it records before sending it on. Default
+	 * 25 ms. The first entry after a quiet spell is sent at once.
+	 */
+	readonly pageFlushMs?: number;
+	/**
+	 * How long a page may take to answer a flush or a command, or the
+	 * browser to hand over a response's body, before a read goes on without
+	 * it; how long a live stream's request may take to reach the stream
+	 * server before the stream is given up; and how long Playwright may take
+	 * to take the page hooks out before a detach goes on. Default 2000 ms.
+	 */
+	readonly pageTimeoutMs?: number;
+	/** TLS for live streams on https pages, and the bind host. */
+	readonly streamServer?: Pick<StreamServerOptions, "tls" | "host">;
+	/** Defaults for `waitFor`. */
+	readonly wait?: Pick<WaitForOptions, "timeout" | "interval">;
+	/** Replace time, for tests of the stage itself. */
+	readonly clock?: Clock;
+}
+
+export interface AttachOptions {
+	/** The context's base URL, for drive clients bound to it. */
+	readonly baseURL?: string;
+}
+
+export interface StageReport {
+	readonly snapshot: TimelineSnapshot;
+	readonly text: string;
+}
+
+export interface ReportOptions {
+	/** Frames kept, counting back from the newest. Default 1,000. */
+	readonly limit?: number;
+}
+
+/** The stage itself, before plugin APIs are mounted on it. */
+export interface StageCore {
+	readonly id: string;
+	/** The raw timeline. Reads here do NOT flush page buffers first; prefer the methods below. */
+	readonly timeline: Timeline;
+	readonly attachments: readonly Attachment[];
+	readonly disposed: boolean;
+	/**
+	 * Start handling a browser context: install every plugin's routes and page
+	 * hooks. Call before the first navigation. Returns a function that
+	 * detaches. A failed attach is undone, so it can be tried again.
+	 */
+	attach(
+		context: ContextPort,
+		options?: AttachOptions,
+	): Promise<() => Promise<void>>;
+	/** Detach one context, or all of them. */
+	detach(context?: ContextPort): Promise<void>;
+	/** The id frames use for this page. */
+	pageId(page: PagePort): string;
+	/**
+	 * Bring the timeline up to date: flush every page's buffer, and wait for
+	 * the responses already back from the network and the ends of the
+	 * streams a stub closed. The reads below do it for you.
+	 */
+	sync(): Promise<void>;
+	frames(filter?: FrameFilter): Promise<Frame[]>;
+	/** Frames since the previous `drain` (any filter), narrowed by `filter`. */
+	drain(filter?: FrameFilter): Promise<Frame[]>;
+	/** Put a named marker on the timeline, after everything that happened so far. */
+	mark(name: string, meta?: Readonly<Record<string, unknown>>): Promise<Frame>;
+	/** Frames after the most recent marker called `marker`. */
+	since(marker: string, filter?: FrameFilter): Promise<Frame[]>;
+	/** Frames between two markers, exclusive. */
+	between(from: string, to: string, filter?: FrameFilter): Promise<Frame[]>;
+	/** Resolve with the matching frames once `count` of them exist. */
+	waitFor(filter: FrameFilter, options?: WaitForOptions): Promise<Frame[]>;
+	/** The newest frames as JSON and as text. Does not flush: `sync()` first. */
+	report(filter?: FrameFilter, options?: ReportOptions): StageReport;
+	/**
+	 * Detach everything, stop servers, release plugins. Idempotent. Every
+	 * step runs even when one fails; what failed is thrown at the end.
+	 */
+	dispose(): Promise<void>;
+}
+
+export type Stage<Plugins extends readonly AnyWirePlugin[] = readonly []> =
+	StageCore & PluginApis<Plugins>;