@heojeongbo/wirestage 0.1.0 → 0.2.0

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/lib/response-stream.ts

@@ -1,4 +1,8 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type {
+	IncomingMessage,
+	OutgoingHttpHeader,
+	ServerResponse,
+} from "node:http";
 
 import type {
 	ResponseStream,
@@ -8,59 +12,128 @@ 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.
+ * 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,
-): ResponseStream {
+	onClose: (end: StreamEnd, failed: boolean) => void,
+): ServedStream {
 	let state: "open" | "ended" | "cut" = "open";
+	let failed = false;
 	const closed = createDeferred<StreamEnd>();
-	response.once("close", () =>
+	response.once("close", () => {
 		// Not ended and not cut: the page let go of it.
-		closed.resolve(state === "open" ? "cancelled" : state),
-	);
+		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 {
-		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;
+		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);
 				}
-				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);
+			},
+			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,
 		},
-		cut() {
-			if (state !== "open") return;
-			state = "cut";
-			response.destroy();
+		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;
 		},
-		closed: closed.promise,
 	};
 }

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

@@ -108,24 +108,44 @@ export function createSocketRouter(deps: SocketRouterDeps): SocketRouterEngine {
 		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 => ({
-		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),
-	});
+	): 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 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.
+	 * 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,
@@ -178,16 +198,25 @@ export function createSocketRouter(deps: SocketRouterDeps): SocketRouterEngine {
 		// 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),
+			page: peer(route, failOnce),
 			connectToServer: () => {
 				if (server === undefined) {
 					const upstream = route.connectToServer();
 					upstream.onMessage(drop);
-					server = peer(upstream, forServer);
+					server = peer(upstream, failOnce, forServer);
 				}
 				return server;
 			},
@@ -200,7 +229,7 @@ export function createSocketRouter(deps: SocketRouterDeps): SocketRouterEngine {
 		} 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);
+			await failOnce(error);
 		}
 	};
 

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

@@ -30,9 +30,11 @@ export interface StageOptions<Plugins extends readonly AnyWirePlugin[]> {
 	 */
 	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.
+	 * 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. */
@@ -53,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;
@@ -79,16 +109,21 @@ export interface StageCore {
 	/** 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.
+	 * 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>;
+	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. */