@heojeongbo/wirestage 0.1.1 → 0.3.0

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/index.ts

@@ -102,9 +102,11 @@ export type { UrlMatcher } from "./shared/lib/match/index.js";
 export { compileUrlMatcher } from "./shared/lib/match/index.js";
 export type {
 	AttachOptions,
+	MarkOptions,
 	ReportOptions,
 	Stage,
 	StageCore,
+	StageCursor,
 	StageOptions,
 	StageReport,
 } from "./widgets/stage/index.js";

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;
+}

package/src/widgets/stage/index.ts

@@ -1,9 +1,11 @@
 export { createStage } from "./lib/create-stage.js";
 export type {
 	AttachOptions,
+	MarkOptions,
 	ReportOptions,
 	Stage,
 	StageCore,
+	StageCursor,
 	StageOptions,
 	StageReport,
 } from "./model/stage.js";

package/src/widgets/stage/lib/create-stage.ts

@@ -41,6 +41,7 @@ const RESERVED = new Set<string>([
 	"frames",
 	"drain",
 	"mark",
+	"cursor",
 	"since",
 	"between",
 	"waitFor",
@@ -123,6 +124,7 @@ export function createStage<const Plugins extends readonly AnyWirePlugin[]>(
 		timeline,
 		clock,
 		sync,
+		pageId,
 		wait: {
 			timeout: options.wait?.timeout ?? 5_000,
 			interval: options.wait?.interval ?? 25,

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

@@ -4,6 +4,7 @@ import type {
 	Timeline,
 } from "../../../entities/frame/index.js";
 import type { WaitForOptions } from "../../../entities/plugin/index.js";
+import type { PagePort } from "../../../shared/api/playwright/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";
@@ -13,6 +14,8 @@ export interface ReadsDeps {
 	readonly clock: Clock;
 	/** Flush every page buffer into the timeline. */
 	readonly sync: () => Promise<void>;
+	/** The id frames use for a page. */
+	readonly pageId: (page: PagePort) => string;
 	/** Defaults for `waitFor`, in milliseconds. */
 	readonly wait: { readonly timeout: number; readonly interval: number };
 }
@@ -26,7 +29,14 @@ const REPORT_LIMIT = 1_000;
 
 export type StageReads = Pick<
 	StageCore,
-	"frames" | "drain" | "mark" | "since" | "between" | "waitFor" | "report"
+	| "frames"
+	| "drain"
+	| "mark"
+	| "cursor"
+	| "since"
+	| "between"
+	| "waitFor"
+	| "report"
 >;
 
 /**
@@ -58,17 +68,49 @@ export function createReads(deps: ReadsDeps): StageReads {
 			await sync();
 			return drainCursor.take(filter);
 		},
-		async mark(name, meta) {
+		async mark(name, options = {}) {
 			await sync();
+			const { page, meta } = options;
 			return timeline.append({
 				protocol: "wirestage",
 				kind: "marker",
 				direction: "none",
 				endpoint: name,
 				source: "test",
+				...(page === undefined
+					? {}
+					: { page: typeof page === "string" ? page : deps.pageId(page) }),
 				...(meta === undefined ? {} : { meta }),
 			});
 		},
+		cursor(base = {}) {
+			let position = 0;
+			const read = async (filter: FrameFilter) => {
+				await sync();
+				const where = filter.where;
+				return timeline.frames({
+					...base,
+					...filter,
+					after: Math.max(position, base.after ?? 0, filter.after ?? 0),
+					where: (frame) =>
+						(base.where === undefined || base.where(frame)) &&
+						(where === undefined || where(frame)),
+				});
+			};
+			return {
+				async take(filter = {}) {
+					const frames = await read(filter);
+					// Past everything that arrived, not just what matched: the next
+					// take starts where this one looked.
+					position = Math.max(position, timeline.last()?.seq ?? 0);
+					return frames;
+				},
+				peek: (filter = {}) => read(filter),
+				get position() {
+					return position;
+				},
+			};
+		},
 		async since(marker, filter) {
 			await sync();
 			const after = requireMarker(marker).seq;

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

@@ -55,6 +55,34 @@ export interface StageReport {
 	readonly text: string;
 }
 
+export interface MarkOptions {
+	/**
+	 * The page the marker is about. The marker carries its id, so a read
+	 * narrowed to that page (`{ page }`) includes it.
+	 */
+	readonly page?: PagePort | string;
+	/** Anything else worth keeping on the marker. */
+	readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A reading position of its own on the timeline: what a helper that keeps a
+ * log per page, per channel or per check reads from, without moving the
+ * stage's `drain` or another cursor.
+ */
+export interface StageCursor {
+	/**
+	 * Bring the timeline up to date, then take what reached it since this
+	 * cursor last took — narrowed by the cursor's filter and `filter` — and
+	 * move past all of it, matching or not.
+	 */
+	take(filter?: FrameFilter): Promise<Frame[]>;
+	/** The same frames as `take`, without moving. */
+	peek(filter?: FrameFilter): Promise<Frame[]>;
+	/** The `seq` the cursor has read up to; 0 before its first take. */
+	readonly position: number;
+}
+
 export interface ReportOptions {
 	/** Frames kept, counting back from the newest. Default 1,000. */
 	readonly limit?: number;
@@ -90,7 +118,12 @@ export interface StageCore {
 	/** 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>;
+	mark(name: string, options?: MarkOptions): Promise<Frame>;
+	/**
+	 * A cursor of its own, from the start of the timeline: every `take`
+	 * returns what is new since the previous one.
+	 */
+	cursor(filter?: FrameFilter): StageCursor;
 	/** Frames after the most recent marker called `marker`. */
 	since(marker: string, filter?: FrameFilter): Promise<Frame[]>;
 	/** Frames between two markers, exclusive. */