@heojeongbo/wirestage 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heojeongbo/wirestage",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Record, fake and fault-inject browser wire traffic in Playwright: REST, Connect, gRPC-web, gRPC, SSE, WebSocket and WebRTC data channels on one timeline.",
 	"type": "module",
 	"license": "MIT",

package/src/features/rest/index.ts

@@ -20,4 +20,6 @@ export type {
 	RestResolver,
 	RestRoute,
 	RestRouteOptions,
+	RestServeOptions,
+	RestServer,
 } from "./model/types.js";

package/src/features/rest/lib/calls.ts

@@ -1,5 +1,27 @@
 import type { Frame } from "../../../entities/frame/index.js";
-import type { RestCall } from "../model/types.js";
+import type { RestCall, RestPath } from "../model/types.js";
+import { compilePath } from "./path.js";
+
+export interface CallFilter {
+	readonly method?: string;
+	readonly path?: RestPath;
+}
+
+/** The calls of `frames` a `calls()` filter asks for. */
+export function filterCalls(
+	frames: readonly Frame[],
+	filter: CallFilter,
+	baseURL: string | undefined,
+): RestCall[] {
+	const matcher =
+		filter.path === undefined ? undefined : compilePath(filter.path, baseURL);
+	const wanted = filter.method?.toUpperCase();
+	return assembleCalls(frames).filter(
+		(call) =>
+			(wanted === undefined || wanted === call.method) &&
+			(matcher === undefined || matcher.match(new URL(call.url)) !== undefined),
+	);
+}
 
 /**
  * Pair each recorded request with how it ended. One call per exchange,
@@ -25,6 +47,10 @@ export function assembleCalls(frames: readonly Frame[]): RestCall[] {
 			request,
 			response: end?.kind === "response" ? end : undefined,
 			status: typeof status === "number" ? status : undefined,
+			server:
+				typeof request.meta["server"] === "string"
+					? request.meta["server"]
+					: undefined,
 		});
 	}
 	return calls;

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

@@ -5,15 +5,18 @@ import {
 	type WirePlugin,
 } from "../../../entities/plugin/index.js";
 import { createArrivals } from "../../../shared/lib/async/index.js";
+import { createSequence } from "../../../shared/lib/id/index.js";
 import type {
 	RestApi,
 	RestMethod,
 	RestOptions,
 	RestReply,
 	RestRequest,
+	RestServer,
 } from "../model/types.js";
-import { assembleCalls } from "./calls.js";
+import { filterCalls } from "./calls.js";
 import { compilePath } from "./path.js";
+import { serveRest } from "./serve.js";
 
 /**
  * REST and other plain HTTP: routes by method and path with `:params`, replies
@@ -27,6 +30,9 @@ export function rest(options: RestOptions = {}): WirePlugin<"rest", RestApi> {
 			const { name } = context;
 			/** The record rule being added, once: every context gets it. */
 			let recording: Promise<unknown> | undefined;
+			const servers = new Set<RestServer>();
+			// Under the plugin's own name: two instances never share an id.
+			const servedCorrelation = createSequence(`${name}-`);
 
 			const toOutcome = async (reply: RestReply): Promise<HttpOutcome> => {
 				switch (reply.kind) {
@@ -125,24 +131,34 @@ export function rest(options: RestOptions = {}): WirePlugin<"rest", RestApi> {
 				delete: verb("DELETE"),
 				async calls(filter = {}) {
 					await context.sync();
-					const matcher =
-						filter.path === undefined
-							? undefined
-							: compilePath(filter.path, options.baseURL);
-					const wanted = filter.method?.toUpperCase();
-					return assembleCalls(
+					return filterCalls(
 						context.timeline.frames({ protocol: name }),
-					).filter(
-						(call) =>
-							(wanted === undefined || wanted === call.method) &&
-							(matcher === undefined ||
-								matcher.match(new URL(call.url)) !== undefined),
+						filter,
+						options.baseURL,
 					);
 				},
+				async serve(serveOptions = {}) {
+					const server = await serveRest(
+						{
+							protocol: name,
+							timeline: context.timeline,
+							clock: context.clock,
+							log: context.log,
+							correlation: servedCorrelation,
+							onClose: (closed) => servers.delete(closed),
+						},
+						serveOptions,
+					);
+					servers.add(server);
+					return server;
+				},
 			};
 
 			return {
 				api,
+				async dispose() {
+					await Promise.all([...servers].map((server) => server.close()));
+				},
 				async attach() {
 					if (options.record === undefined || options.record === false) return;
 					const base = compilePath(`${options.baseURL ?? ""}/**`, undefined);

package/src/features/rest/lib/serve.ts

@@ -0,0 +1,338 @@
+import type { FrameInit, Timeline } from "../../../entities/frame/index.js";
+import {
+	type ServedRequest,
+	type ServedResponse,
+	serveHttp,
+} from "../../../shared/api/http-server/index.js";
+import {
+	type Arrivals,
+	createArrivals,
+} from "../../../shared/lib/async/index.js";
+import type { Clock } from "../../../shared/lib/clock/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type { ScopedLogger } from "../../../shared/lib/logger/index.js";
+import type {
+	RestApi,
+	RestMethod,
+	RestReply,
+	RestRequest,
+	RestResolver,
+	RestServeOptions,
+	RestServer,
+} from "../model/types.js";
+import { filterCalls } from "./calls.js";
+import { compilePath, type PathMatcher } from "./path.js";
+
+export interface ServeDeps {
+	/** The protocol the server's frames are recorded under. */
+	readonly protocol: string;
+	readonly timeline: Timeline;
+	readonly clock: Clock;
+	readonly log: ScopedLogger;
+	readonly correlation: () => string;
+	/** Told when the server closes, so the plugin can forget it. */
+	readonly onClose: (server: RestServer) => void;
+}
+
+interface Route {
+	readonly label: string;
+	readonly method: string | undefined;
+	readonly matcher: PathMatcher;
+	readonly resolver: RestResolver;
+	readonly match: ((request: RestRequest) => boolean) | undefined;
+	readonly requests: Arrivals<RestRequest>;
+	remaining: number | undefined;
+	hits: number;
+	active: boolean;
+}
+
+const TEXT = { "content-type": "text/plain; charset=utf-8" };
+
+const failureOf = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);
+
+/** A served request as a route sees it, with that route's params. */
+function restRequest(
+	request: ServedRequest,
+	correlation: string,
+	params: Record<string, string>,
+): RestRequest {
+	const text = () => new TextDecoder().decode(request.body);
+	return {
+		correlation,
+		method: request.method,
+		url: request.url,
+		headers: request.headers,
+		page: undefined,
+		context: "",
+		resourceType: "other",
+		body: () => request.body,
+		text,
+		json: <T>() => JSON.parse(text()) as T,
+		params,
+		query: request.url.searchParams,
+	};
+}
+
+/**
+ * A served fake: routes, newest first, as the browser's are; every exchange
+ * on the timeline, the client's request as `network` and the answer as
+ * `server`.
+ */
+export async function serveRest(
+	deps: ServeDeps,
+	options: RestServeOptions,
+): Promise<RestServer> {
+	const name = options.name ?? `${deps.protocol} server`;
+	/** Routes, oldest first. */
+	const routes: Route[] = [];
+	let url = "";
+
+	const record = (
+		init: Omit<FrameInit, "protocol" | "endpoint">,
+		path: string,
+	) =>
+		deps.timeline.append({
+			protocol: deps.protocol,
+			endpoint: path,
+			...init,
+			meta: { ...init.meta, server: url },
+		});
+
+	const retire = (route: Route) => {
+		if (!route.active) return;
+		route.active = false;
+		routes.splice(routes.indexOf(route), 1);
+	};
+
+	/** Carry a reply out; `undefined` when it passes the request on. */
+	const answer = async (
+		reply: RestReply,
+		response: ServedResponse,
+		path: string,
+		correlation: string,
+	): Promise<"answered" | undefined> => {
+		switch (reply.kind) {
+			case "response": {
+				const body = reply.body ?? "";
+				// Recorded before it is sent: a client that reads its answer and
+				// asks for `calls()` at once must find it there.
+				record(
+					{
+						kind: "response",
+						direction: "in",
+						source: "server",
+						data: body,
+						meta: { status: reply.status, headers: reply.headers },
+						correlation,
+					},
+					path,
+				);
+				await response.send(reply.status, reply.headers, body);
+				return "answered";
+			}
+			case "passthrough":
+				return undefined;
+			case "abort":
+				record(
+					{
+						kind: "fault",
+						direction: "none",
+						source: "server",
+						meta: { reason: "abort", error: reply.error },
+						correlation,
+					},
+					path,
+				);
+				response.reset();
+				return "answered";
+			case "delay":
+				await deps.clock.sleep(reply.ms);
+				return answer(reply.reply, response, path, correlation);
+		}
+	};
+
+	/** A route's bug: logged, on the timeline, and the client gets a 500 saying so. */
+	const fail = async (
+		route: Route,
+		error: unknown,
+		response: ServedResponse,
+		path: string,
+		correlation: string,
+	) => {
+		deps.log.error("rule failed", { rule: route.label, server: name }, error);
+		record(
+			{
+				kind: "fault",
+				direction: "none",
+				source: "server",
+				meta: {
+					reason: "rule-error",
+					rule: route.label,
+					error: failureOf(error),
+				},
+				correlation,
+			},
+			path,
+		);
+		await response.send(
+			500,
+			TEXT,
+			`wirestage: rule "${route.label}" failed: ${failureOf(error)}`,
+		);
+	};
+
+	const handle = async (request: ServedRequest, response: ServedResponse) => {
+		const correlation = deps.correlation();
+		const path = request.url.pathname;
+		record(
+			{
+				kind: "request",
+				direction: "out",
+				source: "network",
+				data: request.body,
+				meta: {
+					method: request.method,
+					url: request.url.href,
+					headers: request.headers,
+				},
+				correlation,
+			},
+			path,
+		);
+		// The chain as it stands now: a route added while this one waits on a
+		// resolver takes the next request, not this one.
+		for (const route of [...routes].reverse()) {
+			if (!route.active) continue;
+			if (route.method !== undefined && route.method !== request.method)
+				continue;
+			const params = route.matcher.match(request.url);
+			if (params === undefined) continue;
+			const view = restRequest(request, correlation, params);
+			try {
+				if (route.match !== undefined && !route.match(view)) continue;
+				// Claimed before the resolver runs, which may wait: two requests
+				// at once cannot both take a route's last turn.
+				route.hits += 1;
+				if (route.remaining !== undefined && --route.remaining === 0)
+					retire(route);
+				route.requests.push(view);
+				const reply =
+					typeof route.resolver === "function"
+						? await route.resolver(view)
+						: route.resolver;
+				if ((await answer(reply, response, path, correlation)) !== undefined)
+					return;
+			} catch (error) {
+				await fail(route, error, response, path, correlation);
+				return;
+			}
+		}
+		record(
+			{
+				kind: "response",
+				direction: "in",
+				source: "server",
+				data: "",
+				meta: { status: 404, headers: TEXT, unmatched: true },
+				correlation,
+			},
+			path,
+		);
+		await response.send(
+			404,
+			TEXT,
+			`wirestage: ${name} has no route for ${request.method} ${path}`,
+		);
+	};
+
+	const listening = await serveHttp(
+		{
+			name,
+			...(options.host === undefined ? {} : { host: options.host }),
+			...(options.port === undefined ? {} : { port: options.port }),
+		},
+		handle,
+	);
+	url = listening.url;
+
+	const on: RestApi["on"] = async (
+		method,
+		path,
+		resolver,
+		routeOptions = {},
+	) => {
+		if (
+			routeOptions.times !== undefined &&
+			(!Number.isInteger(routeOptions.times) || routeOptions.times < 1)
+		)
+			throw new WirestageError(
+				"INVALID_ARGUMENT",
+				`route "${method} ${String(path)}": times must be a positive integer, got ${routeOptions.times}`,
+			);
+		const label = `${method} ${String(path)}`;
+		const route: Route = {
+			label,
+			method: method === "*" ? undefined : method,
+			matcher: compilePath(path, options.baseURL),
+			resolver,
+			match: routeOptions.match,
+			requests: createArrivals<RestRequest>({
+				clock: deps.clock,
+				label: `${label} request to ${name}`,
+			}),
+			remaining: routeOptions.times,
+			hits: 0,
+			active: true,
+		};
+		routes.push(route);
+		return {
+			get hits() {
+				return route.hits;
+			},
+			get requests() {
+				return route.requests.items;
+			},
+			next: (waitOptions) => route.requests.next(waitOptions),
+			async remove() {
+				retire(route);
+			},
+		};
+	};
+
+	const verb =
+		(method: RestMethod): RestApi["get"] =>
+		(path, resolver, routeOptions) =>
+			on(method, path, resolver, routeOptions);
+
+	let closing: Promise<void> | undefined;
+	const server: RestServer = {
+		url,
+		port: listening.port,
+		on,
+		get: verb("GET"),
+		post: verb("POST"),
+		put: verb("PUT"),
+		patch: verb("PATCH"),
+		delete: verb("DELETE"),
+		async calls(filter = {}) {
+			return filterCalls(
+				deps.timeline.frames({
+					protocol: deps.protocol,
+					where: (frame) => frame.meta["server"] === url,
+				}),
+				filter,
+				options.baseURL,
+			);
+		},
+		close() {
+			closing ??= (async () => {
+				for (const route of [...routes]) retire(route);
+				deps.onClose(server);
+				await listening.close();
+			})();
+			return closing;
+		},
+	};
+	return server;
+}

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

@@ -25,6 +25,11 @@ export interface RestOptions {
 	readonly record?: boolean | UrlMatcher;
 }
 
+/**
+ * A request a route is deciding about. For a request a served fake received
+ * (`serve()`), `page` is undefined, `context` is empty and `resourceType` is
+ * `other`.
+ */
 export interface RestRequest extends HttpRequestView {
 	/** `:name` segments of the matched path. */
 	readonly params: Readonly<Record<string, string>>;
@@ -69,6 +74,38 @@ export interface RestCall {
 	readonly response: Frame | undefined;
 	/** The HTTP status; undefined for an aborted or unfinished request. */
 	readonly status: number | undefined;
+	/** The served fake that received it (its URL); undefined for a page's. */
+	readonly server: string | undefined;
+}
+
+export interface RestServeOptions {
+	/** 0, the default, picks a free port. A fixed port that is taken fails, naming the server. */
+	readonly port?: number;
+	/** Default 127.0.0.1. */
+	readonly host?: string;
+	/** Names the server in errors, 404s and logs. Default `<plugin> server`. */
+	readonly name?: string;
+	/** A path prefix the server's routes are relative to. */
+	readonly baseURL?: string;
+}
+
+/**
+ * A fake HTTP backend for clients outside the browser — a service under
+ * test, an agent — routed and recorded like the page's own requests. A route
+ * that passes a request through hands it to the next older route; with none
+ * left, the server answers 404.
+ */
+export interface RestServer
+	extends Pick<RestApi, "on" | "get" | "post" | "put" | "patch" | "delete"> {
+	readonly url: string;
+	readonly port: number;
+	/** This server's calls, oldest first. */
+	calls(filter?: {
+		readonly method?: string;
+		readonly path?: RestPath;
+	}): Promise<RestCall[]>;
+	/** Stop accepting and drop open connections. The stage closes it too. */
+	close(): Promise<void>;
 }
 
 export type RestPath = string | RegExp;
@@ -105,9 +142,11 @@ export interface RestApi {
 		resolver: RestResolver,
 		options?: RestRouteOptions,
 	): Promise<RestRoute>;
-	/** Recorded REST exchanges, oldest first. */
+	/** Recorded REST exchanges, oldest first: the pages' and served fakes'. */
 	calls(filter?: {
 		readonly method?: string;
 		readonly path?: RestPath;
 	}): Promise<RestCall[]>;
+	/** Serve routes on a port of their own, for clients outside the browser. */
+	serve(options?: RestServeOptions): Promise<RestServer>;
 }

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

@@ -1,2 +1,8 @@
 export type { Listening, ListenOptions } from "./listen.js";
 export { listen } from "./listen.js";
+export type {
+	RequestHandler,
+	ServedRequest,
+	ServedResponse,
+} from "./serve.js";
+export { serveHttp } from "./serve.js";

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

@@ -0,0 +1,112 @@
+import {
+	createServer,
+	type IncomingMessage,
+	type ServerResponse,
+} from "node:http";
+
+import { type Listening, type ListenOptions, listen } from "./listen.js";
+
+/** A request a served fake received, read in full before it is handed on. */
+export interface ServedRequest {
+	readonly method: string;
+	/** Absolute: the server's origin, then the path and query the client sent. */
+	readonly url: URL;
+	/** Lower-cased names; a repeated header's values joined with `, `. */
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body: Uint8Array;
+}
+
+/** The answer to a {@link ServedRequest}: one of the two, once. */
+export interface ServedResponse {
+	/**
+	 * Send a complete response. A header may carry several values separated
+	 * by a newline (`set-cookie`). Resolves once it is written.
+	 */
+	send(
+		status: number,
+		headers: Readonly<Record<string, string>>,
+		body: Uint8Array | string,
+	): Promise<void>;
+	/** Drop the connection: no status, no body — a network failure. */
+	reset(): void;
+}
+
+export type RequestHandler = (
+	request: ServedRequest,
+	response: ServedResponse,
+) => void | Promise<void>;
+
+const headersOf = (message: IncomingMessage): Record<string, string> =>
+	Object.fromEntries(
+		Object.entries(message.headersDistinct as Record<string, string[]>).map(
+			([name, values]) => [name, values.join(", ")],
+		),
+	);
+
+const readBody = (message: IncomingMessage): Promise<Uint8Array> =>
+	new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		message.on("data", (chunk: Buffer) => chunks.push(chunk));
+		message.once("end", () => resolve(new Uint8Array(Buffer.concat(chunks))));
+		message.once("error", reject);
+	});
+
+function responderOf(response: ServerResponse): ServedResponse {
+	return {
+		send(status, headers, body) {
+			for (const [name, value] of Object.entries(headers))
+				response.setHeader(
+					name,
+					value.includes("\n") ? value.split("\n") : value,
+				);
+			response.statusCode = status;
+			return new Promise<void>((resolve) => {
+				// `close` too: a client that went away never sees `finish`.
+				response.once("close", () => resolve());
+				response.end(body);
+			});
+		},
+		reset() {
+			response.destroy();
+		},
+	};
+}
+
+/**
+ * An HTTP/1.1 server for clients outside the browser, handing each request,
+ * body read, to `handle`. The handler is the caller's to make safe; one that
+ * throws anyway gets a 500 rather than a client left waiting, and closing the
+ * server drops open connections at once (`listen`).
+ */
+export async function serveHttp(
+	options: Omit<ListenOptions, "protocol">,
+	handle: RequestHandler,
+): Promise<Listening> {
+	const server = createServer((message, response) => {
+		const responder = responderOf(response);
+		readBody(message)
+			.then((body) =>
+				handle(
+					{
+						// Always set on a request an http.Server received.
+						method: message.method as string,
+						url: new URL(message.url as string, listening.url),
+						headers: headersOf(message),
+						body,
+					},
+					responder,
+				),
+			)
+			.catch((error: unknown) => {
+				if (response.headersSent) response.destroy();
+				else
+					void responder.send(
+						500,
+						{ "content-type": "text/plain; charset=utf-8" },
+						`wirestage: ${options.name} failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+			});
+	});
+	const listening = await listen(server, { ...options, protocol: "http" });
+	return listening;
+}