@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/src/shared/lib/errors/index.ts

@@ -0,0 +1,5 @@
+export type {
+	WirestageErrorCode,
+	WirestageErrorOptions,
+} from "./wirestage-error.js";
+export { isWirestageError, WirestageError } from "./wirestage-error.js";

package/src/shared/lib/errors/wirestage-error.ts

@@ -0,0 +1,50 @@
+/**
+ * Every failure the library raises on purpose carries a code, so a test can
+ * assert on the kind of failure instead of on message text that will change.
+ */
+export type WirestageErrorCode =
+	/** A caller passed something the API cannot work with. */
+	| "INVALID_ARGUMENT"
+	/** The call is valid but not now: before attach, after dispose, twice. */
+	| "INVALID_STATE"
+	/** A wait ran out of time. The message lists what did arrive. */
+	| "TIMEOUT"
+	/** The environment cannot do this, e.g. a live stream on an https page without TLS. */
+	| "UNSUPPORTED"
+	/** The stream, connection or stage this call needs has already closed. */
+	| "CLOSED";
+
+export interface WirestageErrorOptions {
+	readonly cause?: unknown;
+	readonly details?: Readonly<Record<string, unknown>>;
+}
+
+export class WirestageError extends Error {
+	override readonly name = "WirestageError";
+	readonly code: WirestageErrorCode;
+	readonly details: Readonly<Record<string, unknown>>;
+
+	constructor(
+		code: WirestageErrorCode,
+		message: string,
+		options: WirestageErrorOptions = {},
+	) {
+		super(
+			message,
+			options.cause === undefined ? undefined : { cause: options.cause },
+		);
+		this.code = code;
+		this.details = options.details ?? {};
+	}
+}
+
+/** True when `value` is a WirestageError, optionally of one code. */
+export function isWirestageError(
+	value: unknown,
+	code?: WirestageErrorCode,
+): value is WirestageError {
+	return (
+		value instanceof WirestageError &&
+		(code === undefined || value.code === code)
+	);
+}

package/src/shared/lib/id/id.ts

@@ -0,0 +1,29 @@
+/** `prefix1`, `prefix2`, ... — short ids that read well in a frame dump. */
+export function createSequence(prefix: string): () => string {
+	let next = 0;
+	return () => `${prefix}${++next}`;
+}
+
+/**
+ * A stable id per object, without holding the object alive: a closed page
+ * must be collectable even though its frames still name it.
+ */
+export function createObjectIds<T extends object>(
+	prefix: string,
+): (value: T) => string {
+	const ids = new WeakMap<T, string>();
+	const nextId = createSequence(prefix);
+	return (value) => {
+		let id = ids.get(value);
+		if (id === undefined) {
+			id = nextId();
+			ids.set(value, id);
+		}
+		return id;
+	};
+}
+
+/** An unguessable token, for URLs a page could otherwise stumble onto. */
+export function randomToken(): string {
+	return crypto.randomUUID().replaceAll("-", "");
+}

package/src/shared/lib/id/index.ts

@@ -0,0 +1 @@
+export { createObjectIds, createSequence, randomToken } from "./id.js";

package/src/shared/lib/logger/index.ts

@@ -0,0 +1,12 @@
+export type {
+	LogFields,
+	LogScope,
+	LogThreshold,
+	ScopedLogger,
+} from "./logger.js";
+export {
+	createScopedLogger,
+	getLogThreshold,
+	parseLogThreshold,
+	setLogThreshold,
+} from "./logger.js";

package/src/shared/lib/logger/logger.ts

@@ -0,0 +1,126 @@
+import { createLogger, type LogLevel } from "@heojeongbo/log-palette";
+
+/**
+ * The library's logging surface, and the only module that imports log-palette.
+ *
+ * The loggers are the library's own. log-palette also keeps a process-wide
+ * registry (`getLogger`, `setGlobalLevel`, `disableAll`, `configure`) that an
+ * app or a test suite using the same package shares; going through it would
+ * let importing this library change the level of loggers that are not its
+ * own, so nothing here touches it.
+ *
+ * Output goes to the test runner's stdout. Node ignores the `%c` styling
+ * log-palette emits, so the badge reads as plain `[...Stage]` text there.
+ */
+
+/**
+ * The stage's own subsystems, plus whatever scope a plugin brings. The
+ * built-in names are spelled out so `"Http"` and `"HTTP"` cannot become two
+ * badges for one subsystem; eight characters fit the badge column, and a
+ * longer scope is cut to fit.
+ */
+export type LogScope =
+	| "Stage"
+	| "Http"
+	| "Socket"
+	| "Stream"
+	| "Page"
+	| "Connect"
+	| "Rest"
+	| "Sse"
+	| "Ws"
+	| "Rtc"
+	| "Fixture"
+	| "Plugin"
+	| (string & {});
+
+/** A level, or `silent` for no output at all. */
+export type LogThreshold = LogLevel | "silent";
+
+export type LogFields = Readonly<Record<string, unknown>>;
+
+export interface ScopedLogger {
+	debug(message: string, fields?: LogFields, error?: unknown): void;
+	info(message: string, fields?: LogFields, error?: unknown): void;
+	warn(message: string, fields?: LogFields, error?: unknown): void;
+	error(message: string, fields?: LogFields, error?: unknown): void;
+	/**
+	 * Log without paying for `build` when the level would drop the line.
+	 * log-palette checks the level inside its emit, so arguments are built
+	 * even for a dropped `debug` — a frame dump on every request adds up.
+	 */
+	lazy(level: LogLevel, message: string, build: () => LogFields): void;
+}
+
+const RANK: Record<LogThreshold, number> = {
+	debug: 0,
+	log: 1,
+	info: 2,
+	warn: 3,
+	error: 4,
+	silent: 5,
+};
+
+type Palette = ReturnType<typeof createLogger>;
+
+/** One logger per scope, so a scope's badge colour is stable. */
+const loggers = new Map<string, Palette>();
+let threshold: LogThreshold = "warn";
+
+function apply(logger: Palette): void {
+	logger.setEnabled(threshold !== "silent");
+	if (threshold !== "silent") logger.setLevel(threshold);
+}
+
+/**
+ * The default is `warn`: a test suite's output is for the test results, and
+ * the library only speaks up when something is wrong. `WIRESTAGE_LOG=debug`
+ * (read by the Playwright fixture) turns the rest on.
+ */
+export function setLogThreshold(next: LogThreshold): void {
+	threshold = next;
+	for (const logger of loggers.values()) apply(logger);
+}
+
+export function getLogThreshold(): LogThreshold {
+	return threshold;
+}
+
+/** Parse an environment value. Unknown values return `undefined`, never throw. */
+export function parseLogThreshold(
+	value: string | undefined,
+): LogThreshold | undefined {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && normalized in RANK
+		? (normalized as LogThreshold)
+		: undefined;
+}
+
+export function createScopedLogger(scope: LogScope): ScopedLogger {
+	let base = loggers.get(scope);
+	if (base === undefined) {
+		base = createLogger(scope);
+		apply(base);
+		loggers.set(scope, base);
+	}
+	const palette = base;
+	const emit =
+		(level: LogLevel) =>
+		(message: string, fields?: LogFields, error?: unknown): void => {
+			const args: unknown[] = [message];
+			if (fields !== undefined) args.push(fields);
+			// The error goes last and raw, so the stack survives.
+			if (error !== undefined) args.push(error);
+			palette[level](...args);
+		};
+	return {
+		debug: emit("debug"),
+		info: emit("info"),
+		warn: emit("warn"),
+		error: emit("error"),
+		lazy(level, message, build) {
+			if (RANK[level] < RANK[threshold]) return;
+			palette[level](message, build());
+		},
+	};
+}

package/src/shared/lib/match/index.ts

@@ -0,0 +1,6 @@
+export type { GlobSource, UrlMatcher } from "./url-matcher.js";
+export {
+	compileUrlMatcher,
+	globSource,
+	globToRegExp,
+} from "./url-matcher.js";

package/src/shared/lib/match/url-matcher.ts

@@ -0,0 +1,107 @@
+import { WirestageError } from "../errors/index.js";
+
+/**
+ * What a rule matches: a glob, a RegExp over the full URL, or a predicate.
+ *
+ * Globs follow Playwright's routing semantics (`*` stops at `/`, `**` does
+ * not, a `**` directory may be absent, `{a,b}` alternates), with one
+ * addition: a glob that starts with `/` matches the PATH on any origin, and
+ * so ignores the query. A stub for `/api/...` means the same thing on the
+ * dev server, the preview build and CI, whose origins all differ.
+ */
+export type UrlMatcher = string | RegExp | ((url: URL) => boolean);
+
+export function compileUrlMatcher(matcher: UrlMatcher): (url: URL) => boolean {
+	if (typeof matcher === "function") return matcher;
+	if (matcher instanceof RegExp) {
+		return (url) => {
+			// A /g or /y RegExp is stateful: without the reset every other
+			// request to the same URL would miss.
+			matcher.lastIndex = 0;
+			return matcher.test(url.href);
+		};
+	}
+	const pattern = globToRegExp(matcher);
+	if (!matcher.startsWith("/")) return (url) => pattern.test(url.href);
+	if (matcher.includes("?"))
+		// It would compile, and then never match anything.
+		throw new WirestageError(
+			"INVALID_ARGUMENT",
+			`"${matcher}" matches the path, which has no query: drop the "?…", or match the whole URL ("**${matcher}")`,
+		);
+	return (url) => pattern.test(url.pathname);
+}
+
+/** Characters with a meaning in a RegExp: escaped wherever a glob means them literally. */
+const SPECIAL = /[.*+?^${}()|[\]\\/]/;
+
+/** Translate a glob into an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+	return new RegExp(`^${globSource(glob).source}$`);
+}
+
+/** A glob as RegExp source (unanchored), and the params it captures, in order. */
+export interface GlobSource {
+	readonly source: string;
+	readonly params: readonly string[];
+}
+
+/**
+ * The RegExp source of a glob. With `params`, a `:name` (a letter or `_`,
+ * then word characters) matches one segment and captures it: the routes of a
+ * REST plugin, in the same glob language as every other pattern.
+ */
+export function globSource(
+	glob: string,
+	options: { readonly params?: boolean } = {},
+): GlobSource {
+	const params: string[] = [];
+	let source = "";
+	let inGroup = false;
+	for (let i = 0; i < glob.length; i++) {
+		const char = glob.charAt(i);
+		if (char === "\\" && i + 1 < glob.length) {
+			source += escapeChar(glob.charAt(++i));
+		} else if (char === "*") {
+			if (glob.charAt(i + 1) !== "*") {
+				source += "[^/]*";
+			} else if (glob.charAt(i + 2) === "/") {
+				// `a/**/b` matches `a/b` too: the directories may be none.
+				source += "(?:.+/)?";
+				i += 2;
+			} else {
+				source += ".*";
+				i++;
+			}
+		} else if (char === "{") {
+			inGroup = true;
+			source += "(?:";
+		} else if (char === "}" && inGroup) {
+			inGroup = false;
+			source += ")";
+		} else if (char === "," && inGroup) {
+			source += "|";
+		} else if (char === ":" && options.params) {
+			// `:8080` in an origin is not a param: a name starts with a letter.
+			const name = /^[A-Za-z_]\w*/.exec(glob.slice(i + 1))?.[0];
+			if (name === undefined) source += char;
+			else {
+				params.push(name);
+				source += "([^/]+)";
+				i += name.length;
+			}
+		} else {
+			source += escapeChar(char);
+		}
+	}
+	if (inGroup)
+		throw new WirestageError(
+			"INVALID_ARGUMENT",
+			`glob "${glob}" opens a "{" it never closes; write a literal brace as "\\{"`,
+		);
+	return { source, params };
+}
+
+function escapeChar(char: string): string {
+	return SPECIAL.test(char) ? `\\${char}` : char;
+}

package/src/sse.ts

@@ -0,0 +1,2 @@
+/** @heojeongbo/wirestage/sse — server-sent events. */
+export * from "./features/sse/index.js";

package/src/webrtc.ts

@@ -0,0 +1,2 @@
+/** @heojeongbo/wirestage/webrtc — WebRTC data channels. */
+export * from "./features/webrtc/index.js";

package/src/websocket.ts

@@ -0,0 +1,2 @@
+/** @heojeongbo/wirestage/websocket — WebSockets. */
+export * from "./features/websocket/index.js";

package/src/widgets/stage/index.ts

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

package/src/widgets/stage/lib/attached-context.ts

@@ -0,0 +1,10 @@
+import type { Attachment } from "../../../entities/plugin/index.js";
+import type { ContextPort } from "../../../shared/api/playwright/index.js";
+
+/**
+ * An attachment as the stage's engines see it: with the browser context that
+ * plugins are not given.
+ */
+export interface AttachedContext extends Attachment {
+	readonly context: ContextPort;
+}

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

@@ -0,0 +1,307 @@
+import { createTimeline } from "../../../entities/frame/index.js";
+import type {
+	AnyWirePlugin,
+	Attachment,
+	PluginContext,
+	PluginRuntime,
+} from "../../../entities/plugin/index.js";
+import type {
+	ContextPort,
+	CookieJarPort,
+	PagePort,
+} from "../../../shared/api/playwright/index.js";
+import { createStreamServer } from "../../../shared/api/stream-server/index.js";
+import { runAll } from "../../../shared/lib/async/index.js";
+import { createSystemClock } from "../../../shared/lib/clock/index.js";
+import type { CookieInit } from "../../../shared/lib/cookies/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import {
+	createObjectIds,
+	createSequence,
+	randomToken,
+} from "../../../shared/lib/id/index.js";
+import { createScopedLogger } from "../../../shared/lib/logger/index.js";
+import type { Stage, StageCore, StageOptions } from "../model/stage.js";
+import type { AttachedContext } from "./attached-context.js";
+import { createHttpRouter } from "./http-router.js";
+import { createPageHost } from "./page-host.js";
+import { createReads } from "./reads.js";
+import { createSocketRouter } from "./socket-router.js";
+
+/** Names a plugin may not take: they would shadow the stage's own API. */
+const RESERVED = new Set<string>([
+	"id",
+	"timeline",
+	"attachments",
+	"disposed",
+	"attach",
+	"detach",
+	"pageId",
+	"sync",
+	"frames",
+	"drain",
+	"mark",
+	"since",
+	"between",
+	"waitFor",
+	"report",
+	"dispose",
+]);
+
+interface Attached {
+	readonly attachment: AttachedContext;
+	/** What plugins and callers are given of the context: never the context. */
+	readonly view: Attachment;
+	readonly onClose: () => void;
+	/** Plugins whose `attach` was started for this context, in order. */
+	readonly runtimes: PluginRuntime<unknown>[];
+	/** Settles once the attach has finished installing, however it ended. */
+	readonly installing: Promise<void>;
+}
+
+/**
+ * Build a stage: one timeline, the shared services plugins are given, and the
+ * plugins themselves, each mounted as `stage.<name>`.
+ *
+ * The stage is the composition root of everything below it. It is the only
+ * place the routers, the page host and the stream server are constructed, so
+ * a plugin can only ever reach them through its `PluginContext`.
+ */
+export function createStage<const Plugins extends readonly AnyWirePlugin[]>(
+	options: StageOptions<Plugins>,
+): Stage<Plugins> {
+	const clock = options.clock ?? createSystemClock();
+	const id = randomToken().slice(0, 12);
+	const log = createScopedLogger("Stage");
+	const timeline = createTimeline({
+		clock,
+		capacity: options.capacity,
+		// A subscriber is the test's own code; its failure is its own, and
+		// must not break the route handler or page flush that appended.
+		onListenerError: (error) =>
+			log.error("a timeline subscriber threw", {}, error),
+	});
+	const pageId = createObjectIds<PagePort>("p");
+	const contextId = createSequence("c");
+	const streamServer = createStreamServer({
+		...options.streamServer,
+		log: createScopedLogger("Stream"),
+	});
+	const http = createHttpRouter({
+		timeline,
+		log: createScopedLogger("Http"),
+		streams: streamServer,
+		pageId,
+		correlation: createSequence("x"),
+		clock,
+		timeoutMs: options.pageTimeoutMs ?? 2_000,
+	});
+	const sockets = createSocketRouter({
+		timeline,
+		log: createScopedLogger("Socket"),
+		correlation: createSequence("w"),
+	});
+	const pages = createPageHost({
+		stage: id,
+		log: createScopedLogger("Page"),
+		clock,
+		pageId,
+		flushMs: options.pageFlushMs ?? 25,
+		timeoutMs: options.pageTimeoutMs ?? 2_000,
+	});
+	const attached = new Map<ContextPort, Attached>();
+	/** Every plugin's runtime, a plugin's own dependencies before it. */
+	const runtimes: PluginRuntime<unknown>[] = [];
+	let disposed = false;
+	let built = false;
+
+	const sync = async (): Promise<void> => {
+		await pages.sync();
+		await http.settle();
+	};
+	const reads = createReads({
+		timeline,
+		clock,
+		sync,
+		wait: {
+			timeout: options.wait?.timeout ?? 5_000,
+			interval: options.wait?.interval ?? 25,
+		},
+	});
+
+	/**
+	 * Undo an attach. One still installing is waited for first: undoing half
+	 * of it would leave the rest installed for good. Every step runs even when
+	 * one fails: a plugin's bug must not leak a route.
+	 */
+	const detachOne = async (context: ContextPort): Promise<void> => {
+		const entry = attached.get(context);
+		if (entry === undefined) return;
+		attached.delete(context);
+		await entry.installing;
+		context.off("close", entry.onClose);
+		const { attachment, view } = entry;
+		await runAll([
+			...[...entry.runtimes]
+				.reverse()
+				.map((runtime) => () => runtime.detach?.(view)),
+			() => sockets.detach(attachment),
+			() => http.detach(attachment),
+			() => pages.detach(attachment),
+		]);
+		log.debug("detached", { context: attachment.id });
+	};
+
+	const core: StageCore = {
+		id,
+		timeline,
+		get attachments() {
+			return [...attached.values()].map((entry) => entry.view);
+		},
+		get disposed() {
+			return disposed;
+		},
+		async attach(context, attachOptions = {}) {
+			if (disposed)
+				throw new WirestageError(
+					"INVALID_STATE",
+					"cannot attach: the stage is disposed",
+				);
+			if (attached.has(context))
+				throw new WirestageError(
+					"INVALID_STATE",
+					"this context is already attached to the stage",
+				);
+			// The context stays with the stage and its engines. A plugin gets its
+			// id, its base URL and a jar that only reads and adds cookies: what
+			// it could do with the context itself would go round the engines.
+			const cookies: CookieJarPort = Object.freeze({
+				cookies: (urls?: string | string[]) => context.cookies(urls),
+				addCookies: (init: CookieInit[]) => context.addCookies(init),
+			});
+			const view: Attachment = Object.freeze({
+				id: contextId(),
+				baseURL: attachOptions.baseURL ?? options.baseURL,
+				cookies,
+			});
+			const attachment: AttachedContext = { ...view, context };
+			// A closed context takes its routes with it; forgetting it here keeps
+			// the next sync from evaluating in pages that no longer exist.
+			const onClose = () => {
+				detachOne(context).catch((error: unknown) =>
+					log.debug("detaching a closed context failed", {}, error),
+				);
+			};
+			const started: PluginRuntime<unknown>[] = [];
+			const installing = (async () => {
+				await pages.attach(attachment);
+				await http.attach(attachment);
+				await sockets.attach(attachment);
+				for (const runtime of runtimes) {
+					started.push(runtime);
+					await runtime.attach?.(view);
+				}
+			})();
+			const entry: Attached = {
+				attachment,
+				view,
+				onClose,
+				runtimes: started,
+				installing: installing.then(
+					() => undefined,
+					() => undefined,
+				),
+			};
+			attached.set(context, entry);
+			context.on("close", onClose);
+			try {
+				await installing;
+			} catch (error) {
+				// Half-attached is worse than not attached: undo what took, so the
+				// caller can fix the cause and attach this context again.
+				await detachOne(context).catch((secondary: unknown) =>
+					log.debug("undoing a failed attach failed", {}, secondary),
+				);
+				throw error;
+			}
+			if (attached.get(context) !== entry)
+				// Detached, or closed, while it was installing: that detach is
+				// undoing all of it, so this attach did not take.
+				throw new WirestageError(
+					"INVALID_STATE",
+					"the context was detached while it was being attached",
+				);
+			log.debug("attached", { context: attachment.id });
+			return () => detachOne(context);
+		},
+		async detach(context) {
+			if (context !== undefined) return detachOne(context);
+			await runAll([...attached.keys()].map((each) => () => detachOne(each)));
+		},
+		pageId,
+		sync,
+		...reads,
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			await runAll([
+				() => core.detach(),
+				...[...runtimes].reverse().map((runtime) => () => runtime.dispose?.()),
+				() => streamServer.close(),
+			]);
+		},
+	};
+
+	// The services, not the engines behind them: attaching, detaching and
+	// settling are the stage's to do.
+	const services = {
+		http: Object.freeze({ add: http.add }),
+		sockets: Object.freeze({ add: sockets.add, prepare: sockets.prepare }),
+		pages: Object.freeze({
+			register: pages.register,
+			command: pages.command,
+			refresh: pages.refresh,
+			pageId: pages.pageId,
+		}),
+	} satisfies Pick<PluginContext, "http" | "sockets" | "pages">;
+
+	/** Set a plugin up, and whatever it builds on first. */
+	const mount = (plugin: AnyWirePlugin): PluginRuntime<unknown> => {
+		const context: PluginContext = {
+			name: plugin.name,
+			timeline,
+			clock,
+			log: createScopedLogger(plugin.scope ?? "Plugin"),
+			...services,
+			baseURL: options.baseURL,
+			attachments: () => core.attachments,
+			sync,
+			waitFor: reads.waitFor,
+			use(inner) {
+				if (built)
+					throw new WirestageError(
+						"INVALID_STATE",
+						`plugin "${plugin.name}" asked for "${inner.name}" after setup; call use() inside setup(), before any context is attached`,
+					);
+				return mount(inner).api as never;
+			},
+		};
+		const runtime = plugin.setup(context);
+		runtimes.push(runtime);
+		return runtime;
+	};
+
+	const apis = new Map<string, unknown>();
+	for (const plugin of options.plugins) {
+		if (RESERVED.has(plugin.name) || apis.has(plugin.name))
+			throw new WirestageError(
+				"INVALID_ARGUMENT",
+				RESERVED.has(plugin.name)
+					? `plugin name "${plugin.name}" is reserved by the stage`
+					: `two plugins are named "${plugin.name}"`,
+			);
+		apis.set(plugin.name, mount(plugin).api);
+	}
+	built = true;
+	return Object.assign(core, Object.fromEntries(apis)) as Stage<Plugins>;
+}