@heojeongbo/wirestage 0.0.0-stage → 0.1.0

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,66 @@
+import type { IncomingMessage, 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 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.
+ */
+export function createResponseStream(
+	request: IncomingMessage,
+	response: ServerResponse,
+): ResponseStream {
+	let state: "open" | "ended" | "cut" = "open";
+	const closed = createDeferred<StreamEnd>();
+	response.once("close", () =>
+		// Not ended and not cut: the page let go of it.
+		closed.resolve(state === "open" ? "cancelled" : state),
+	);
+	const requestHeaders: Record<string, string> = {};
+	for (const [name, value] of Object.entries(request.headers))
+		requestHeaders[name] = String(value);
+	return {
+		requestHeaders,
+		head(status, headers = {}) {
+			response.writeHead(status, { ...headers });
+		},
+		flush() {
+			response.flushHeaders();
+		},
+		write(chunk) {
+			return new Promise<void>((resolve, reject) => {
+				if (state !== "open" || response.destroyed) {
+					reject(new WirestageError("CLOSED", "the response stream is closed"));
+					return;
+				}
+				response.write(toBytes(chunk), (error) =>
+					error ? reject(error) : resolve(),
+				);
+			});
+		},
+		async end() {
+			if (state !== "open") return;
+			state = "ended";
+			// A response the page already let go of never calls back from
+			// end(): resolve on whichever comes first.
+			if (!response.destroyed)
+				await new Promise<void>((resolve) => {
+					response.once("close", resolve);
+					response.end(resolve);
+				});
+		},
+		cut() {
+			if (state !== "open") return;
+			state = "cut";
+			response.destroy();
+		},
+		closed: closed.promise,
+	};
+}

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

@@ -0,0 +1,271 @@
+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);
+	};
+
+	const peer = (
+		route: WebSocketRoutePort,
+		close: (options: CloseOptions) => CloseOptions = (options) => options,
+	): SocketPeer => ({
+		send: (data) =>
+			route.send(typeof data === "string" ? data : toBuffer(data)),
+		close: (options) => route.close(close(options)),
+		onMessage: (handler) => route.onMessage(handler),
+		onClose: (handler) => route.onClose(handler),
+	});
+
+	/**
+	 * A rule that throws 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;
+		const view: SocketView = {
+			correlation: deps.correlation(),
+			url,
+			context: attachment.id,
+			page: peer(route),
+			connectToServer: () => {
+				if (server === undefined) {
+					const upstream = route.connectToServer();
+					upstream.onMessage(drop);
+					server = peer(upstream, 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 fail(entry.rule, view, server, 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,108 @@
+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 before a read
+	 * goes on without it — and Playwright 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. 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>;