@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/src/widgets/stage/lib/page-host.ts

@@ -0,0 +1,375 @@
+import type {
+	PageEntry,
+	PageHost,
+	PageModule,
+} from "../../../entities/plugin/index.js";
+import type {
+	BindingSourcePort,
+	ContextPort,
+	FramePort,
+	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 { ScopedLogger } from "../../../shared/lib/logger/index.js";
+import type { AttachedContext } from "./attached-context.js";
+import {
+	buildPageScript,
+	type CommandResult,
+	commandRuntime,
+	detachRuntime,
+	flushRuntime,
+	type RuntimeMessage,
+} from "./page-runtime.js";
+
+export interface PageHostDeps {
+	readonly stage: string;
+	readonly log: ScopedLogger;
+	readonly clock: Clock;
+	readonly pageId: (page: PagePort) => string;
+	/** How long entries may wait for company before a batch leaves. */
+	readonly flushMs: number;
+	/**
+	 * How long a frame may take to answer a flush or a command, and Playwright
+	 * to take the binding or the init script out at detach. Whatever takes
+	 * longer is passed over, not waited for: a page stuck behind an open
+	 * dialog must not stall every read of the timeline, nor the teardown.
+	 */
+	readonly timeoutMs: number;
+}
+
+export interface PageHostEngine extends PageHost {
+	attach(attachment: AttachedContext): Promise<void>;
+	detach(attachment: AttachedContext): Promise<void>;
+	/** Flush every open frame's buffer into the modules, then return. */
+	sync(): Promise<void>;
+}
+
+/** What recent Playwright returns from `exposeBinding` / `addInitScript`. */
+type MaybeDisposable = { dispose?: () => Promise<void> } | undefined;
+
+/** What the host put into one browser context. */
+interface Installed {
+	/** The attachment its entries belong to; none while detached. */
+	current: AttachedContext | undefined;
+	/**
+	 * Take the binding and the init script back out. Unset until each is in,
+	 * and where this Playwright returned nothing to take them out with.
+	 */
+	removeBinding?: () => Promise<void>;
+	removeScript?: () => Promise<void>;
+}
+
+/** How to take a hook back out, where this Playwright can. */
+const remover = (handle: MaybeDisposable) =>
+	handle?.dispose === undefined
+		? undefined
+		: () => (handle.dispose as () => Promise<void>)();
+
+/**
+ * Node half of the page host: one binding and one init script per context,
+ * carrying every registered module.
+ *
+ * Modules are sealed at the first attach. An init script cannot be amended
+ * after the fact, so a module registered later would silently be missing from
+ * pages of the contexts already attached; failing loudly is the better DX.
+ */
+export function createPageHost(deps: PageHostDeps): PageHostEngine {
+	const modules = new Map<string, PageModule<unknown, unknown>>();
+	const attachments = new Set<AttachedContext>();
+	const installed = new WeakMap<ContextPort, Installed>();
+	const binding = `__wirestage_${deps.stage}`;
+	const { flushMs, timeoutMs } = deps;
+	let sealed = false;
+
+	/** Every frame of every open page: page hooks run in iframes too. */
+	const openFrames = (
+		among: Iterable<AttachedContext>,
+		pageFilter?: string,
+	): FramePort[] => {
+		const frames: FramePort[] = [];
+		for (const attachment of among)
+			for (const page of attachment.context.pages())
+				if (
+					!page.isClosed() &&
+					(pageFilter === undefined || deps.pageId(page) === pageFilter)
+				)
+					frames.push(...page.frames());
+		return frames;
+	};
+
+	/**
+	 * `work`'s value, or undefined once `timeoutMs` have passed — with `late`
+	 * logged, and the work left to finish on its own.
+	 */
+	const inTime = async <T>(
+		work: Promise<T>,
+		late: string,
+	): Promise<{ readonly value: T } | undefined> => {
+		const waiting = new AbortController();
+		try {
+			return await Promise.race([
+				work.then((value) => ({ value })),
+				deps.clock.sleep(timeoutMs, waiting.signal).then(
+					() => {
+						deps.log.warn(late, { timeoutMs });
+						return undefined;
+					},
+					// The work finished first.
+					() => undefined,
+				),
+			]);
+		} finally {
+			waiting.abort();
+		}
+	};
+
+	/**
+	 * Evaluate in one frame, within the time a frame is given. A frame that
+	 * is navigating or gone has nothing to say, which is not a failure.
+	 */
+	const ask = async <Arg, Result>(
+		frame: FramePort,
+		pageFunction: (arg: Arg) => Result | Promise<Result>,
+		arg: Arg,
+		what: string,
+	): Promise<{ readonly value: Awaited<Result> } | undefined> => {
+		try {
+			return await inTime(
+				frame.evaluate(pageFunction, arg) as Promise<Awaited<Result>>,
+				`a frame did not answer a ${what} in time and was passed over; what it recorded may be missing (is a dialog open?)`,
+			);
+		} catch (error) {
+			deps.log.debug(`${what} skipped`, {}, error);
+			return undefined;
+		}
+	};
+
+	/**
+	 * Take the binding or the init script back out, within the same time.
+	 * Playwright's `dispose()` reaches every page of the context, and a page
+	 * with a dialog open answers nothing until the dialog closes: a detach
+	 * that waited for it would hang the test's teardown.
+	 */
+	const release = async (
+		remove: () => Promise<void>,
+		what: string,
+	): Promise<void> => {
+		try {
+			await inTime(
+				remove(),
+				`the page ${what} was not taken out in time; detaching goes on, and Playwright removes it once the page responds (is a dialog open?)`,
+			);
+		} catch (error) {
+			// A context that closed first took it with it.
+			deps.log.debug("page hook already gone", {}, error);
+		}
+	};
+
+	const receive = (
+		source: BindingSourcePort,
+		message: RuntimeMessage,
+		attachment: AttachedContext,
+	): unknown => {
+		if (message.type === "hello") {
+			const states: Record<string, unknown> = {};
+			for (const [id, module] of modules)
+				try {
+					states[id] = module.state();
+				} catch (error) {
+					// One plugin's bug: its module starts without a state, every
+					// other module with its own, and the log says whose it was.
+					deps.log.error(
+						"page module failed to give its state",
+						{ module: id },
+						error,
+					);
+				}
+			return states;
+		}
+		const page = deps.pageId(source.page);
+		if (message.type === "failure") {
+			deps.log.error(
+				`page module failed in its ${message.handler} handler`,
+				{ module: message.module, page },
+				message.error,
+			);
+			return undefined;
+		}
+		const byModule = new Map<string, PageEntry[]>();
+		for (const { module, entry } of message.entries) {
+			const list = byModule.get(module) ?? [];
+			list.push(entry as PageEntry);
+			byModule.set(module, list);
+		}
+		for (const [id, entries] of byModule) {
+			const module = modules.get(id);
+			if (module === undefined) continue;
+			try {
+				module.receive(entries, { page, context: attachment.id });
+			} catch (error) {
+				deps.log.error(
+					"page module failed to receive entries",
+					{ module: id },
+					error,
+				);
+			}
+		}
+		return undefined;
+	};
+
+	const command = async (
+		module: string,
+		op: string,
+		args?: unknown,
+		options: { readonly page?: string } = {},
+	): Promise<unknown[]> => {
+		// No module, no runtime handler: a frame would have nothing to answer.
+		if (!modules.has(module)) return [];
+		const results = await Promise.all(
+			openFrames(attachments, options.page).map((frame) =>
+				ask(frame, commandRuntime, { binding, module, op, args }, "command"),
+			),
+		);
+		const answers: unknown[] = [];
+		const failures: string[] = [];
+		for (const result of results) {
+			// No answer, or a frame the init script never ran in.
+			const outcome: CommandResult | undefined = result?.value;
+			if (outcome === undefined) continue;
+			if ("error" in outcome) failures.push(outcome.error);
+			else answers.push(outcome.value);
+		}
+		if (failures.length > 0)
+			// Not "no frame answered": the module's own code failed in the page.
+			throw new WirestageError(
+				"INVALID_STATE",
+				`page module "${module}" failed to run "${op}" in ${failures.length} frame(s): ${failures[0]}`,
+				{ details: { module, op, failures } },
+			);
+		return answers;
+	};
+
+	return {
+		register(module) {
+			if (sealed)
+				throw new WirestageError(
+					"INVALID_STATE",
+					`page module "${module.id}" registered after the stage was attached; register every plugin before calling attach()`,
+				);
+			if (modules.has(module.id))
+				throw new WirestageError(
+					"INVALID_ARGUMENT",
+					`page module "${module.id}" is already registered`,
+				);
+			try {
+				// Parsed the way the init script will use it. A source that is
+				// not an expression — a method, a bound or a native function —
+				// is a SyntaxError there that takes every module down with it,
+				// and nothing in Node would say so.
+				new Function(`return (${module.install.toString()});`);
+			} catch (error) {
+				throw new WirestageError(
+					"INVALID_ARGUMENT",
+					`page module "${module.id}" cannot run in the page: its install does not serialize to a function expression (${String(error)}); declare it with \`function\` or as an arrow function, not as an object method or a bound function`,
+					{ cause: error },
+				);
+			}
+			modules.set(module.id, module as PageModule<unknown, unknown>);
+		},
+		async attach(attachment) {
+			sealed = true;
+			attachments.add(attachment);
+			if (modules.size === 0) return;
+			const before = installed.get(attachment.context);
+			if (before !== undefined) {
+				// Still in the context from an earlier attach this Playwright
+				// could not take back: point it at the new attachment.
+				before.current = attachment;
+				return;
+			}
+			const slot: Installed = { current: attachment };
+			installed.set(attachment.context, slot);
+			const installers: Record<string, (env: unknown) => void> = {};
+			for (const [id, module] of modules)
+				installers[id] = module.install as (env: unknown) => void;
+			try {
+				slot.removeBinding = remover(
+					(await attachment.context.exposeBinding(binding, (source, message) =>
+						slot.current === undefined
+							? undefined
+							: receive(source, message as RuntimeMessage, slot.current),
+					)) as MaybeDisposable,
+				);
+				slot.removeScript = remover(
+					(await attachment.context.addInitScript({
+						content: buildPageScript(
+							{
+								binding,
+								flushMs,
+								modules: [...modules].map(([id, m]) => ({
+									id,
+									config: m.config,
+								})),
+							},
+							installers,
+						),
+					})) as MaybeDisposable,
+				);
+			} catch (error) {
+				installed.delete(attachment.context);
+				// A binding left behind would make the next attach fail with
+				// "already registered".
+				if (slot.removeBinding !== undefined)
+					await release(slot.removeBinding, "binding");
+				throw error;
+			}
+		},
+		async detach(attachment) {
+			if (!attachments.delete(attachment)) return;
+			const slot = installed.get(attachment.context);
+			if (slot === undefined) return;
+			const { removeBinding, removeScript } = slot;
+			// A Playwright that cannot take a binding or an init script back
+			// leaves them in the context, switched off; they serve it again if
+			// it is attached again.
+			const removable =
+				removeBinding !== undefined && removeScript !== undefined;
+			if (removable) {
+				installed.delete(attachment.context);
+				// The init script first: a document that loaded while the open
+				// ones were being detached would start a runtime no detach
+				// reaches, and then lose its binding under it.
+				await release(removeScript, "init script");
+			}
+			// Undo the hooks in the documents that are open, and take what they
+			// still hold, while the binding is there to carry it.
+			await Promise.all(
+				openFrames([attachment]).map((frame) =>
+					ask(frame, detachRuntime, binding, "detach"),
+				),
+			);
+			slot.current = undefined;
+			if (removable) await release(removeBinding, "binding");
+		},
+		async sync() {
+			if (modules.size === 0) return;
+			await Promise.all(
+				openFrames(attachments).map((frame) =>
+					ask(frame, flushRuntime, binding, "flush"),
+				),
+			);
+		},
+		command,
+		async refresh(module) {
+			const target = modules.get(module);
+			if (target === undefined)
+				throw new WirestageError(
+					"INVALID_ARGUMENT",
+					`no page module "${module}" is registered`,
+				);
+			await command(module, "__state", target.state());
+		},
+		pageId: deps.pageId,
+	};
+}

package/src/widgets/stage/lib/page-runtime.ts

@@ -0,0 +1,314 @@
+/**
+ * The page half of the page host. Everything in this file that is exported as
+ * a function runs INSIDE the page: it is serialized with `toString()`, so it is
+ * self-contained — no imports, no references to module scope.
+ */
+
+export interface PageRuntimeInit {
+	/** The binding Node exposed; also the runtime's key in `__wirestage`. */
+	readonly binding: string;
+	/** How long entries may wait for company before the batch is flushed. */
+	readonly flushMs: number;
+	readonly modules: readonly {
+		readonly id: string;
+		readonly config: unknown;
+	}[];
+}
+
+/** Messages the runtime sends through the binding. */
+export type RuntimeMessage =
+	| { readonly type: "hello" }
+	| {
+			readonly type: "entries";
+			readonly entries: readonly {
+				readonly module: string;
+				readonly entry: unknown;
+			}[];
+	  }
+	| {
+			/** A module's own handler threw, with no call to reject: Node logs it. */
+			readonly type: "failure";
+			readonly module: string;
+			/** `install`, `onState` or `onDetach`. */
+			readonly handler: string;
+			readonly error: string;
+	  };
+
+/** What the runtime publishes on `globalThis.__wirestage[binding]`. */
+export interface RuntimeHandle {
+	flush(): Promise<unknown>;
+	command(module: string, op: string, args: unknown): unknown;
+	/** Undo every module's hooks, send what is still held, and step aside. */
+	detach(): Promise<unknown>;
+}
+
+/** A command's answer, or why its handler failed. */
+export type CommandResult =
+	| { readonly value: unknown }
+	| { readonly error: string };
+
+type Installer = (env: unknown) => void;
+
+/**
+ * Install every module, batch what they emit, and answer Node's flushes and
+ * commands.
+ *
+ * Batching is what keeps a 60 Hz channel cheap: one binding call per flush
+ * window instead of one per message. The first entry after a quiet spell is
+ * not held back, though — it leaves at once, so it reaches Node ahead of a
+ * request the page makes right after it and the two land on the timeline in
+ * the order they happened.
+ *
+ * `flush()` returns the binding's promise, so a Node-side `evaluate(flush)`
+ * resolves only after Node has appended the entries: a read that flushes
+ * first sees everything the page recorded before it.
+ *
+ * Nothing the runtime does throws into the page's own code: a module whose
+ * handler throws is reported to Node, and a binding that has been taken away
+ * makes the runtime step aside.
+ */
+export function pageRuntime(
+	scope: Record<string, unknown>,
+	init: PageRuntimeInit,
+	installers: Record<string, Installer>,
+): void {
+	scope["__wirestage"] ??= {};
+	const root = scope["__wirestage"] as Record<string, unknown>;
+	const bind = scope[init.binding];
+	// Init scripts run again in every frame and on every navigation; a second
+	// run in the same realm would double every entry.
+	if (root[init.binding] !== undefined || typeof bind !== "function") return;
+	const send = bind as (message: RuntimeMessage) => Promise<unknown>;
+
+	const queue: { module: string; entry: unknown }[] = [];
+	/** Set once the runtime steps aside: a module still emitting talks to nobody. */
+	let detached = false;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	/** When the last batch left; far enough back that the first entry is not held. */
+	let sentAt = Number.NEGATIVE_INFINITY;
+	const commands = new Map<string, (args: unknown) => unknown>();
+	const stateHandlers = new Map<string, ((state: unknown) => void)[]>();
+	const detachHandlers: { readonly module: string; undo(): void }[] = [];
+
+	const now = () => performance.timeOrigin + performance.now();
+	/** Undo every module's hooks, newest first: stacked hooks come off in order. */
+	const unhook = () => {
+		for (const { module, undo } of detachHandlers.splice(0).reverse()) {
+			try {
+				undo();
+			} catch (error) {
+				// One module failing to undo must not keep the rest hooked.
+				report(module, "onDetach", error);
+			}
+		}
+		delete root[init.binding];
+	};
+	/**
+	 * Send through the binding. Playwright's throws, synchronously, once it
+	 * has been removed — in a document the stage's detach did not reach, one
+	 * that loaded while the stage was detaching. Thrown on from `emit`, that
+	 * would fail the app's own call (`RTCDataChannel.send()`) or surface as a
+	 * page error; nothing the runtime holds can reach Node any more, so it
+	 * steps aside instead, putting back what the modules wrapped.
+	 */
+	const post = (message: RuntimeMessage): Promise<unknown> => {
+		try {
+			return send(message);
+		} catch {
+			detached = true;
+			queue.length = 0;
+			unhook();
+			return Promise.resolve(undefined);
+		}
+	};
+	/** Tell Node a module's handler threw, so it is logged against the module. */
+	const report = (module: string, handler: string, error: unknown) => {
+		// Stepping aside for want of a binding: there is nobody left to tell.
+		if (detached) return;
+		post({ type: "failure", module, handler, error: String(error) }).catch(
+			() => {},
+		);
+	};
+	const flush = (): Promise<unknown> => {
+		if (timer !== undefined) {
+			clearTimeout(timer);
+			timer = undefined;
+		}
+		if (queue.length === 0) return Promise.resolve(undefined);
+		sentAt = now();
+		return post({ type: "entries", entries: queue.splice(0, queue.length) });
+	};
+	const schedule = () => {
+		const wait = sentAt + init.flushMs - now();
+		if (wait <= 0) {
+			flush().catch(() => {});
+			return;
+		}
+		timer ??= setTimeout(() => {
+			timer = undefined;
+			flush().catch(() => {});
+		}, wait);
+	};
+	const encode = (bytes: Uint8Array): string => {
+		let binary = "";
+		// Chunked: spreading a large array into fromCharCode overflows the stack.
+		for (let i = 0; i < bytes.length; i += 0x8000)
+			binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+		return btoa(binary);
+	};
+	const decode = (text: string): Uint8Array => {
+		const binary = atob(text);
+		const out = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+		return out;
+	};
+	/** Run each of a module's state handlers, whatever the others do; return what threw. */
+	const applyState = (module: string, state: unknown): unknown[] => {
+		const failures: unknown[] = [];
+		for (const handler of stateHandlers.get(module) ?? [])
+			try {
+				handler(state);
+			} catch (error) {
+				failures.push(error);
+			}
+		return failures;
+	};
+
+	for (const module of init.modules) {
+		const install = installers[module.id];
+		if (install === undefined) continue;
+		const emit = (entry: unknown) => {
+			if (detached) return;
+			queue.push({ module: module.id, entry });
+			schedule();
+		};
+		try {
+			install({
+				window: scope,
+				config: module.config,
+				emit,
+				now,
+				encode,
+				decode,
+				onCommand: (op: string, handler: (args: unknown) => unknown) => {
+					commands.set(`${module.id}\u0000${op}`, handler);
+				},
+				onState: (handler: (state: unknown) => void) => {
+					const list = stateHandlers.get(module.id) ?? [];
+					list.push(handler);
+					stateHandlers.set(module.id, list);
+				},
+				onDetach: (handler: () => void) => {
+					detachHandlers.push({ module: module.id, undo: handler });
+				},
+			});
+		} catch (error) {
+			// A broken module must not take the page down with it: an entry puts
+			// the failure on its timeline, and Node logs it against the module.
+			emit({ type: "error", at: now(), text: String(error) });
+			report(module.id, "install", error);
+		}
+	}
+
+	const handle: RuntimeHandle = {
+		flush,
+		command(module, op, args) {
+			if (op === "__state") {
+				// Every handler gets the state; the command still fails when one
+				// threw, so the `refresh()` that sent it says which module broke.
+				const failures = applyState(module, args);
+				if (failures.length > 0) throw failures[0];
+				return true;
+			}
+			const handler = commands.get(`${module}\u0000${op}`);
+			return handler === undefined ? undefined : handler(args);
+		},
+		detach() {
+			unhook();
+			// After the undos: what they emit still leaves with the last flush.
+			detached = true;
+			return flush();
+		},
+	};
+	root[init.binding] = handle;
+	// Chromium loses a binding call made from `pagehide` when the main frame
+	// navigates — the document is gone before Node hears of it — while one
+	// made from `beforeunload` still arrives. `pagehide` stays for the ways
+	// out that fire no `beforeunload`: a page closed, an iframe removed.
+	for (const type of ["beforeunload", "pagehide"])
+		(scope as unknown as EventTarget).addEventListener(type, () => {
+			flush().catch(() => {});
+		});
+	post({ type: "hello" }).then(
+		(states) => {
+			const byModule = (states ?? {}) as Record<string, unknown>;
+			for (const module of stateHandlers.keys())
+				if (byModule[module] !== undefined)
+					// No call to fail: Node hears of each failure, and the
+					// modules after this one still get their state.
+					for (const error of applyState(module, byModule[module]))
+						report(module, "onState", error);
+		},
+		() => {},
+	);
+}
+
+/** Flush one frame's runtime. Runs in the page via `frame.evaluate`. */
+export function flushRuntime(binding: string): Promise<unknown> | undefined {
+	const root = (globalThis as Record<string, unknown>)["__wirestage"] as
+		| Record<string, RuntimeHandle | undefined>
+		| undefined;
+	return root?.[binding]?.flush();
+}
+
+/** Detach one frame's runtime. Runs in the page via `frame.evaluate`. */
+export function detachRuntime(binding: string): Promise<unknown> | undefined {
+	const root = (globalThis as Record<string, unknown>)["__wirestage"] as
+		| Record<string, RuntimeHandle | undefined>
+		| undefined;
+	return root?.[binding]?.detach();
+}
+
+/**
+ * Run one command in one frame's runtime. Runs in the page via
+ * `frame.evaluate`. Undefined when the frame has no runtime (a document the
+ * init script never ran in); otherwise the handler's answer, or its failure
+ * as text — an exception would cross back to Node as a rejected evaluate,
+ * indistinguishable from a frame that went away.
+ */
+export function commandRuntime(arg: {
+	readonly binding: string;
+	readonly module: string;
+	readonly op: string;
+	readonly args: unknown;
+}): Promise<CommandResult> | undefined {
+	const root = (globalThis as Record<string, unknown>)["__wirestage"] as
+		| Record<string, RuntimeHandle | undefined>
+		| undefined;
+	const handle = root?.[arg.binding];
+	if (handle === undefined) return undefined;
+	return Promise.resolve()
+		.then(() => handle.command(arg.module, arg.op, arg.args))
+		.then(
+			(value): CommandResult => ({ value }),
+			(error: unknown): CommandResult => ({ error: String(error) }),
+		);
+}
+
+/**
+ * The init script: the runtime, then every installer, then the call.
+ *
+ * Wrapped in a scope that defines `__name`: esbuild's `keepNames` (on by
+ * default in tsx) rewrites `const f = () => {}` into `__name(() => {}, "f")`,
+ * so code serialized from a tsx-run process calls a helper the page does not
+ * have, and the whole runtime dies with "__name is not defined".
+ */
+export function buildPageScript(
+	init: PageRuntimeInit,
+	installers: Readonly<Record<string, Installer>>,
+): string {
+	const list = Object.entries(installers)
+		.map(([id, install]) => `${JSON.stringify(id)}: (${install.toString()})`)
+		.join(",\n");
+	return `(() => {\nconst __name = (target) => target;\n(${pageRuntime.toString()})(globalThis, ${JSON.stringify(init)}, {\n${list}\n});\n})();`;
+}