@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,111 @@
+/**
+ * @heojeongbo/wirestage — the core: the stage, its timeline, and the plugin
+ * contract every protocol is written against. Protocols live in subpaths:
+ * `/connect`, `/rest`, `/sse`, `/websocket`, `/webrtc`; the Playwright
+ * fixture in `/playwright`.
+ */
+
+// The timeline: what every plugin writes and every test reads.
+export type {
+	Direction,
+	Frame,
+	FrameFilter,
+	FrameInit,
+	FrameKind,
+	FrameSource,
+	Payload,
+	PayloadInput,
+	SnapshotFrame,
+	SnapshotOptions,
+	Timeline,
+	TimelineCursor,
+	TimelineOptions,
+	TimelineSnapshot,
+} from "./entities/frame/index.js";
+export { createTimeline } from "./entities/frame/index.js";
+// The plugin contract: what a protocol is written against.
+export type {
+	AbortErrorCode,
+	AnyWirePlugin,
+	Attachment,
+	HttpOutcome,
+	HttpRequestView,
+	HttpRouter,
+	HttpRule,
+	HttpRuleHandle,
+	PageEntry,
+	PageHost,
+	PageInstaller,
+	PageModule,
+	PageModuleEnv,
+	PageSource,
+	PassthroughResponse,
+	PluginApis,
+	PluginContext,
+	PluginRuntime,
+	ResponseStream,
+	SocketPeer,
+	SocketRouter,
+	SocketRule,
+	SocketRuleHandle,
+	SocketView,
+	StreamEnd,
+	WaitForOptions,
+	WirePlugin,
+} from "./entities/plugin/index.js";
+export { definePlugin, named } from "./entities/plugin/index.js";
+// What the stage is handed: a browser context, its pages, its cookie jar.
+export type {
+	ContextPort,
+	CookieJarPort,
+	FramePort,
+	PagePort,
+} from "./shared/api/playwright/index.js";
+// For plugin authors: the pieces every built-in plugin is made of.
+export type {
+	Arrivals,
+	ArrivalsOptions,
+	AsyncQueue,
+	Deferred,
+} from "./shared/lib/async/index.js";
+export {
+	createArrivals,
+	createAsyncQueue,
+	createDeferred,
+} from "./shared/lib/async/index.js";
+export type { Clock, ManualClock } from "./shared/lib/clock/index.js";
+export {
+	createManualClock,
+	createSystemClock,
+} from "./shared/lib/clock/index.js";
+export type { CookieInit } from "./shared/lib/cookies/index.js";
+// The length-prefixed framing gRPC, gRPC-web and Connect streams share, for
+// a test that builds or reads a frame by hand.
+export type { Envelope } from "./shared/lib/envelope/index.js";
+export {
+	createEnvelopeReader,
+	decodeEnvelopes,
+	EnvelopeFlag,
+	encodeEnvelope,
+	encodeEnvelopes,
+	parseTrailerBlock,
+} from "./shared/lib/envelope/index.js";
+export type { WirestageErrorCode } from "./shared/lib/errors/index.js";
+export { isWirestageError, WirestageError } from "./shared/lib/errors/index.js";
+export type {
+	LogScope,
+	LogThreshold,
+	ScopedLogger,
+} from "./shared/lib/logger/index.js";
+export { getLogThreshold, setLogThreshold } from "./shared/lib/logger/index.js";
+export type { UrlMatcher } from "./shared/lib/match/index.js";
+export { compileUrlMatcher } from "./shared/lib/match/index.js";
+export type {
+	AttachOptions,
+	ReportOptions,
+	Stage,
+	StageCore,
+	StageOptions,
+	StageReport,
+} from "./widgets/stage/index.js";
+export { createStage } from "./widgets/stage/index.js";

package/src/playwright.ts

@@ -0,0 +1,8 @@
+/** @heojeongbo/wirestage/playwright — the `stage` fixture for @playwright/test. */
+export type {
+	ReportMode,
+	StageFixtureArgs,
+	StageFixtureOptions,
+	StageTestInfo,
+} from "./app/playwright/index.js";
+export { createStageFixture, withStage } from "./app/playwright/index.js";

package/src/rest.ts

@@ -0,0 +1,2 @@
+/** @heojeongbo/wirestage/rest — REST and other plain HTTP. */
+export * from "./features/rest/index.js";

package/src/shared/api/http-server/index.ts

@@ -0,0 +1,2 @@
+export type { Listening, ListenOptions } from "./listen.js";
+export { listen } from "./listen.js";

package/src/shared/api/http-server/listen.ts

@@ -0,0 +1,71 @@
+import type { AddressInfo, Server, Socket } from "node:net";
+
+import { WirestageError } from "../../lib/errors/index.js";
+
+export interface ListenOptions {
+	/** Names the server in the "port in use" error. */
+	readonly name: string;
+	readonly protocol: "http" | "https";
+	readonly host?: string;
+	/** 0, the default, picks a free port. */
+	readonly port?: number;
+}
+
+export interface Listening {
+	readonly url: string;
+	readonly port: number;
+	/** Stop accepting and drop open connections at once. */
+	close(): Promise<void>;
+}
+
+/**
+ * Start listening and return a handle whose `close` really is immediate.
+ * `server.close()` alone waits for every keep-alive and streaming connection to
+ * end on its own — a held-open stream would stall test teardown until the
+ * runner's timeout.
+ *
+ * Takes a `net.Server`, which http, https and http2 servers all are.
+ */
+export async function listen(
+	server: Server,
+	options: ListenOptions,
+): Promise<Listening> {
+	const host = options.host ?? "127.0.0.1";
+	const sockets = new Set<Socket>();
+	server.on("connection", (socket: Socket) => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+	});
+	await new Promise<void>((resolve, reject) => {
+		const onListening = () => {
+			server.off("error", onError);
+			resolve();
+		};
+		const onError = (error: NodeJS.ErrnoException) => {
+			server.off("listening", onListening);
+			reject(
+				error.code === "EADDRINUSE"
+					? new WirestageError(
+							"INVALID_STATE",
+							`${options.name}: ${host}:${options.port} is already in use`,
+							{ cause: error, details: { host, port: options.port } },
+						)
+					: error,
+			);
+		};
+		server.once("listening", onListening);
+		server.once("error", onError);
+		server.listen(options.port ?? 0, host);
+	});
+	const port = (server.address() as AddressInfo).port;
+	return {
+		// An IPv6 literal goes in brackets, or the port reads as part of it.
+		url: `${options.protocol}://${host.includes(":") ? `[${host}]` : host}:${port}`,
+		port,
+		close: () =>
+			new Promise<void>((resolve) => {
+				for (const socket of sockets) socket.destroy();
+				server.close(() => resolve());
+			}),
+	};
+}

package/src/shared/api/playwright/index.ts

@@ -0,0 +1,17 @@
+export type {
+	BindingSourcePort,
+	ContextPort,
+	ContinueOptions,
+	CookieJarPort,
+	CookiePort,
+	FramePort,
+	FulfillOptions,
+	HeaderMap,
+	PagePort,
+	RequestPort,
+	ResponsePort,
+	RouteHandler,
+	RoutePort,
+	UrlPredicate,
+	WebSocketRoutePort,
+} from "./ports.js";

package/src/shared/api/playwright/ports.ts

@@ -0,0 +1,145 @@
+/**
+ * The slice of Playwright the library drives, as structural types.
+ *
+ * Real Playwright objects satisfy these as they are — `tests/types` proves it
+ * against the pinned version — so the public API takes a `BrowserContext` and
+ * hands it inward unchanged. Inside, everything depends on the ports, never on
+ * Playwright, which is what lets the unit suite cover every branch with
+ * hand-written fakes instead of a browser.
+ */
+
+import type { CookieInit } from "../../lib/cookies/index.js";
+
+export type HeaderMap = Readonly<Record<string, string>>;
+
+export interface FramePort {
+	evaluate<R>(
+		// biome-ignore lint/suspicious/noExplicitAny: Playwright types the page function as PageFunction<Arg, R>, which unboxes Arg through a conditional type. No narrower parameter type accepts both that and the self-contained `(arg: T) => R` functions callers pass; `unknown` and `never` each fail one side. The arguments are JSON values either way.
+		pageFunction: (arg: any) => R | Promise<R>,
+		arg?: unknown,
+	): Promise<R>;
+}
+
+export interface PagePort {
+	/** The main frame and every iframe: page hooks run in each of them. */
+	frames(): FramePort[];
+	isClosed(): boolean;
+}
+
+export interface ResponsePort {
+	status(): number;
+	headers(): HeaderMap;
+	body(): Promise<Buffer>;
+}
+
+export interface RequestPort {
+	url(): string;
+	method(): string;
+	/** Playwright already lower-cases these names. */
+	headers(): HeaderMap;
+	/**
+	 * Every header, including the ones `headers()` leaves out (cookies, and
+	 * headers the network stack adds such as `last-event-id`).
+	 */
+	allHeaders(): Promise<HeaderMap>;
+	postDataBuffer(): Buffer | null;
+	resourceType(): string;
+	/** Throws for requests a service worker makes; callers must guard it. */
+	frame(): { page(): PagePort };
+	response(): Promise<ResponsePort | null>;
+	failure(): { errorText: string } | null;
+}
+
+export interface FulfillOptions {
+	readonly status?: number;
+	readonly headers?: Record<string, string>;
+	readonly body?: string | Buffer;
+}
+
+export interface ContinueOptions {
+	readonly url?: string;
+	readonly method?: string;
+	readonly headers?: Record<string, string>;
+	readonly postData?: string | Buffer;
+}
+
+export interface RoutePort {
+	request(): RequestPort;
+	fulfill(options: FulfillOptions): Promise<void>;
+	continue(options?: ContinueOptions): Promise<void>;
+	fallback(): Promise<void>;
+	abort(errorCode?: string): Promise<void>;
+}
+
+export type RouteHandler = (
+	route: RoutePort,
+	request: RequestPort,
+) => Promise<void>;
+
+export type UrlPredicate = (url: URL) => boolean;
+
+export interface WebSocketRoutePort {
+	url(): string;
+	onMessage(handler: (message: string | Buffer) => unknown): void;
+	onClose(
+		handler: (code: number | undefined, reason: string | undefined) => unknown,
+	): void;
+	send(message: string | Buffer): void;
+	close(options?: { code?: number; reason?: string }): Promise<void>;
+	connectToServer(): WebSocketRoutePort;
+}
+
+export interface BindingSourcePort {
+	readonly page: PagePort;
+}
+
+export interface CookiePort {
+	readonly name: string;
+	readonly value: string;
+}
+
+/**
+ * The cookie jar of a browser context: all a drive client needs of one, so
+ * that is all it is given.
+ */
+export interface CookieJarPort {
+	cookies(urls?: string | string[]): Promise<CookiePort[]>;
+	/**
+	 * Optional so a fake may omit it; every real BrowserContext has it. Drive
+	 * clients keep the cookies a response sets here, the way Playwright's own
+	 * request context does.
+	 */
+	addCookies?(cookies: CookieInit[]): Promise<void>;
+}
+
+export interface ContextPort extends CookieJarPort {
+	/** Required here: a context always has it, and a plugin's jar calls it. */
+	addCookies(cookies: CookieInit[]): Promise<void>;
+	route(url: UrlPredicate, handler: RouteHandler): Promise<unknown>;
+	unroute(url: UrlPredicate, handler?: RouteHandler): Promise<void>;
+	routeWebSocket(
+		url: UrlPredicate,
+		handler: (route: WebSocketRoutePort) => unknown,
+	): Promise<void>;
+	addInitScript(script: { content: string }): Promise<unknown>;
+	exposeBinding(
+		name: string,
+		binding: (source: BindingSourcePort, message: unknown) => unknown,
+	): Promise<unknown>;
+	pages(): PagePort[];
+	/** Optional so a fake may omit it; every real BrowserContext has it. */
+	grantPermissions?(
+		permissions: string[],
+		options?: { origin?: string },
+	): Promise<void>;
+	on(event: "close", listener: () => void): unknown;
+	on(
+		event: "requestfinished" | "requestfailed",
+		listener: (request: RequestPort) => void,
+	): unknown;
+	off(event: "close", listener: () => void): unknown;
+	off(
+		event: "requestfinished" | "requestfailed",
+		listener: (request: RequestPort) => void,
+	): unknown;
+}

package/src/shared/api/stream-server/index.ts

@@ -0,0 +1,7 @@
+export type {
+	NodeHandler,
+	StreamServer,
+	StreamServerOptions,
+	StreamSession,
+} from "./stream-server.js";
+export { createStreamServer } from "./stream-server.js";

package/src/shared/api/stream-server/stream-server.ts

@@ -0,0 +1,246 @@
+import {
+	createServer as createHttpServer,
+	type IncomingMessage,
+	type ServerResponse,
+} from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+
+import { WirestageError } from "../../lib/errors/index.js";
+import { randomToken } from "../../lib/id/index.js";
+import type { ScopedLogger } from "../../lib/logger/index.js";
+import { type Listening, listen } from "../http-server/index.js";
+
+export type NodeHandler = (
+	request: IncomingMessage,
+	response: ServerResponse,
+) => void | Promise<void>;
+
+export interface StreamSession {
+	readonly id: string;
+	/** Where the browser's request is redirected to. Single use. */
+	readonly url: string;
+	/** Forget the session if the redirect never arrives. */
+	dispose(): void;
+}
+
+export interface StreamServerOptions {
+	/** Key and certificate for pages served over https. */
+	readonly tls?: {
+		readonly key: string | Buffer;
+		readonly cert: string | Buffer;
+	};
+	readonly host?: string;
+	readonly log?: ScopedLogger;
+}
+
+export interface StreamServer {
+	/**
+	 * Register a handler and return the URL to redirect one request to.
+	 * `secure` is whether the page's request was https: Playwright only lets
+	 * `route.continue` change the URL within the same scheme.
+	 */
+	open(
+		handler: NodeHandler,
+		options: { readonly secure: boolean },
+	): Promise<StreamSession>;
+	/** Stop every listener and refuse further sessions. */
+	close(): Promise<void>;
+	readonly sessions: number;
+}
+
+const PATH = "/__wirestage/";
+
+/**
+ * Headers a browser script may read on a response from another origin. The
+ * redirect makes the stream server a different origin from the page as far
+ * as CORS is concerned in some engines, and connect-web reads these.
+ */
+const EXPOSED_HEADERS = [
+	"grpc-status",
+	"grpc-message",
+	"grpc-status-details-bin",
+	"grpc-encoding",
+	"connect-protocol-version",
+	"content-encoding",
+	"content-type",
+].join(", ");
+
+/**
+ * Open responses one listener carries. A browser keeps at most six
+ * connections to one host and port, and an open stream holds its connection
+ * for as long as it lives: the seventh would wait for one of the six to end,
+ * which in a test is never. Four leaves room for the preflights the browser
+ * sends on the same connection pool.
+ */
+const STREAMS_PER_LISTENER = 4;
+
+interface Listener {
+	readonly listening: Promise<Listening>;
+	/** Sessions given this listener's URL whose response has not closed. */
+	open: number;
+}
+
+interface Session {
+	readonly handler: NodeHandler;
+	readonly listener: Listener;
+}
+
+/**
+ * A local server for responses that must stay open — server streams, SSE —
+ * which `route.fulfill` cannot express because it takes the whole body at
+ * once. A stub answers by redirecting the browser's request here, and the
+ * handler then writes to a real socket at whatever pace the test drives.
+ *
+ * It starts lazily on the first session, so a suite that never streams never
+ * opens a port, and adds a port whenever the ones it has are full.
+ */
+export function createStreamServer(
+	options: StreamServerOptions = {},
+): StreamServer {
+	const secure = options.tls !== undefined;
+	const sessions = new Map<string, Session>();
+	const listeners = new Set<Listener>();
+	let closed = false;
+
+	const release = (id: string, session: Session) => {
+		if (sessions.delete(id)) session.listener.open -= 1;
+	};
+
+	const onRequest = (request: IncomingMessage, response: ServerResponse) => {
+		allowCors(request, response);
+		if (request.method === "OPTIONS") {
+			response.writeHead(204);
+			response.end();
+			return;
+		}
+		const id = request.url?.startsWith(PATH)
+			? request.url.slice(PATH.length)
+			: "";
+		const session = sessions.get(id);
+		if (session === undefined) {
+			response.writeHead(404);
+			response.end();
+			return;
+		}
+		// One request per session: a client that reconnects goes through the
+		// page's route again and gets a session of its own. The session keeps
+		// its place on the listener until the response is over.
+		sessions.delete(id);
+		response.once("close", () => {
+			session.listener.open -= 1;
+		});
+		Promise.resolve()
+			.then(() => session.handler(request, response))
+			.catch((error: unknown) => {
+				// A write into a connection the client closed, or a test cut, is
+				// the expected end of a stream, not a failure worth an error line.
+				if (response.destroyed) {
+					options.log?.debug(
+						"stream ended by a closed connection",
+						{ session: id },
+						error,
+					);
+					return;
+				}
+				options.log?.error("stream handler failed", { session: id }, error);
+				if (!response.headersSent) response.writeHead(500);
+				response.end();
+			});
+	};
+
+	/** A listener with room, starting another when the rest are full. */
+	const listenerWithRoom = (): Listener => {
+		for (const listener of listeners)
+			if (listener.open < STREAMS_PER_LISTENER) return listener;
+		const listener: Listener = {
+			listening: listen(
+				options.tls === undefined
+					? createHttpServer(onRequest)
+					: createHttpsServer(options.tls, onRequest),
+				{
+					name: "wirestage stream server",
+					protocol: secure ? "https" : "http",
+					host: options.host,
+				},
+			),
+			open: 0,
+		};
+		listeners.add(listener);
+		// A listener that could not start must not be offered again.
+		listener.listening.catch(() => listeners.delete(listener));
+		return listener;
+	};
+
+	return {
+		async open(handler, { secure: pageIsSecure }) {
+			if (closed)
+				throw new WirestageError(
+					"CLOSED",
+					"the stream server is closed: the stage was disposed while a stream was being opened",
+				);
+			if (pageIsSecure !== secure)
+				throw new WirestageError(
+					"UNSUPPORTED",
+					pageIsSecure
+						? "a live stream on an https page needs `streamServer.tls`: Playwright only redirects a request to a URL with the same scheme"
+						: "the stream server was given TLS but the page is http; drop `streamServer.tls` for http pages",
+					{ details: { pageIsSecure, serverIsSecure: secure } },
+				);
+			const listener = listenerWithRoom();
+			const session: Session = { handler, listener };
+			const id = randomToken();
+			listener.open += 1;
+			sessions.set(id, session);
+			try {
+				const { url } = await listener.listening;
+				return {
+					id,
+					url: `${url}${PATH}${id}`,
+					dispose: () => release(id, session),
+				};
+			} catch (error) {
+				release(id, session);
+				throw error;
+			}
+		},
+		async close() {
+			closed = true;
+			sessions.clear();
+			const stopping = [...listeners];
+			listeners.clear();
+			await Promise.all(
+				stopping.map((listener) =>
+					listener.listening.then(
+						(listening) => listening.close(),
+						// It never started; there is nothing to stop.
+						() => undefined,
+					),
+				),
+			);
+		},
+		get sessions() {
+			return sessions.size;
+		},
+	};
+}
+
+function allowCors(request: IncomingMessage, response: ServerResponse): void {
+	const origin = request.headers.origin;
+	if (origin === undefined) return;
+	response.setHeader("access-control-allow-origin", origin);
+	response.setHeader("vary", "origin");
+	response.setHeader("access-control-allow-credentials", "true");
+	response.setHeader(
+		"access-control-allow-methods",
+		"GET, POST, PUT, PATCH, DELETE, OPTIONS",
+	);
+	response.setHeader(
+		"access-control-allow-headers",
+		request.headers["access-control-request-headers"] ?? "*",
+	);
+	response.setHeader("access-control-expose-headers", EXPOSED_HEADERS);
+	// Private Network Access: a page on a public origin must be told the
+	// loopback stream server agrees to be reached, or Chromium refuses.
+	if (request.headers["access-control-request-private-network"] === "true")
+		response.setHeader("access-control-allow-private-network", "true");
+}