@heojeongbo/wirestage 0.1.0 → 0.1.1

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. */
@@ -79,9 +81,9 @@ 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[]>;