@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/src/app/playwright/lib/fixture.ts

@@ -0,0 +1,201 @@
+import type { TestType } from "@playwright/test";
+
+import type { AnyWirePlugin } from "../../../entities/plugin/index.js";
+import type { ContextPort } from "../../../shared/api/playwright/index.js";
+import {
+	createScopedLogger,
+	type LogThreshold,
+	parseLogThreshold,
+	setLogThreshold,
+} from "../../../shared/lib/logger/index.js";
+import {
+	createStage,
+	type Stage,
+	type StageOptions,
+} from "../../../widgets/stage/index.js";
+
+/** When the timeline is attached to the test report. */
+export type ReportMode = "on-failure" | "always" | "never";
+
+export interface StageFixtureOptions<Plugins extends readonly AnyWirePlugin[]>
+	extends Omit<StageOptions<Plugins>, "baseURL" | "clock"> {
+	/**
+	 * Default `on-failure`. `WIRESTAGE_REPORT` overrides it. An empty timeline
+	 * is never attached.
+	 */
+	readonly report?: ReportMode;
+	/**
+	 * Frames a report holds, counting back from the newest. Default 1,000: a
+	 * report is read from its end, and one that grows with the test would
+	 * attach tens of megabytes to a long run.
+	 */
+	readonly reportLimit?: number;
+	/** Default `warn`. `WIRESTAGE_LOG` overrides it. */
+	readonly log?: LogThreshold;
+	/**
+	 * Attach the test's `context` before the body runs. Default true. Turn it
+	 * off when tests open their own contexts (`browser.newContext()`, two users
+	 * at once): the fixture then never asks Playwright for `context`, so no
+	 * unused one is created, and the test attaches what it opens.
+	 */
+	readonly attach?: boolean;
+}
+
+export interface StageFixtureArgs {
+	/** Absent when the fixture does not attach (`attach: false`). */
+	readonly context?: ContextPort;
+	readonly baseURL: string | undefined;
+}
+
+/** The part of Playwright's TestInfo the fixture uses. */
+export interface StageTestInfo {
+	readonly status?: string;
+	readonly expectedStatus: string;
+	attach(
+		name: string,
+		options: { readonly body: string; readonly contentType: string },
+	): Promise<void>;
+}
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+const REPORT_MODES: readonly ReportMode[] = ["on-failure", "always", "never"];
+
+/**
+ * The environment's say, read once when the fixture is made. A value it
+ * cannot use is ignored with one warning: a typo in CI config must neither
+ * turn reports off silently nor fail every test, and saying so once is
+ * enough.
+ */
+function readEnvironment(env: Environment): {
+	readonly report: ReportMode | undefined;
+	readonly log: LogThreshold | undefined;
+} {
+	const warn = (name: string, value: string, allowed: readonly string[]) =>
+		createScopedLogger("Fixture").warn(`ignoring an unknown ${name}`, {
+			value,
+			allowed,
+		});
+	const wantedReport = env["WIRESTAGE_REPORT"]?.trim().toLowerCase();
+	const report = REPORT_MODES.find((mode) => mode === wantedReport);
+	if (wantedReport !== undefined && report === undefined)
+		warn("WIRESTAGE_REPORT", wantedReport, REPORT_MODES);
+	const wantedLog = env["WIRESTAGE_LOG"];
+	const log = parseLogThreshold(wantedLog);
+	if (wantedLog !== undefined && log === undefined)
+		warn("WIRESTAGE_LOG", wantedLog, [
+			"debug",
+			"log",
+			"info",
+			"warn",
+			"error",
+			"silent",
+		]);
+	return { report, log };
+}
+
+/**
+ * The `stage` fixture as a plain function, so it can be tested without the
+ * Playwright runner: one stage per test, attached to the test's context
+ * before the test body runs, reported on failure, disposed afterwards.
+ */
+export function createStageFixture<
+	const Plugins extends readonly AnyWirePlugin[],
+>(
+	options: StageFixtureOptions<Plugins>,
+	env: Environment = process.env,
+): (
+	args: StageFixtureArgs,
+	use: (stage: Stage<Plugins>) => Promise<void>,
+	testInfo: StageTestInfo,
+) => Promise<void> {
+	const { report, reportLimit, log, attach = true, ...stageOptions } = options;
+	const fromEnv = readEnvironment(env);
+	const threshold = fromEnv.log ?? log;
+	if (threshold !== undefined) setLogThreshold(threshold);
+	const mode = fromEnv.report ?? report ?? "on-failure";
+	const fixtureLog = createScopedLogger("Fixture");
+
+	/** Attach the timeline to the test's report, when there is one to read. */
+	const attachReport = async (
+		stage: Stage<Plugins>,
+		testInfo: StageTestInfo,
+	): Promise<void> => {
+		const failed = testInfo.status !== testInfo.expectedStatus;
+		if (mode === "never" || (mode === "on-failure" && !failed)) return;
+		// What the pages still hold is often the frame the failure is about.
+		await stage.sync();
+		// Nothing on the timeline is nothing to read: no empty attachment.
+		if (stage.timeline.size === 0 && stage.timeline.evicted === 0) return;
+		const { snapshot, text } = stage.report(
+			undefined,
+			reportLimit === undefined ? {} : { limit: reportLimit },
+		);
+		await testInfo.attach("wirestage-timeline.txt", {
+			body: text,
+			contentType: "text/plain",
+		});
+		await testInfo.attach("wirestage-timeline.json", {
+			body: JSON.stringify(snapshot, null, 2),
+			contentType: "application/json",
+		});
+	};
+
+	const run = async (
+		context: ContextPort | undefined,
+		baseURL: string | undefined,
+		use: (stage: Stage<Plugins>) => Promise<void>,
+		testInfo: StageTestInfo,
+	): Promise<void> => {
+		const stage = createStage({
+			...stageOptions,
+			...(baseURL === undefined ? {} : { baseURL }),
+		});
+		try {
+			if (context !== undefined) await stage.attach(context);
+			await use(stage);
+		} finally {
+			try {
+				await attachReport(stage, testInfo);
+			} catch (error) {
+				// The report is a courtesy; failing to write one must not hide
+				// the test's own result, nor keep the stage from being disposed.
+				fixtureLog.warn("could not attach the timeline", {}, error);
+			} finally {
+				await stage.dispose();
+			}
+		}
+	};
+	// Playwright reads a fixture's dependencies off its SOURCE, so each mode
+	// is its own literal: naming `context` is what makes Playwright create one.
+	return attach
+		? async ({ context, baseURL }, use, testInfo) =>
+				run(context, baseURL, use, testInfo)
+		: async ({ baseURL }, use, testInfo) =>
+				run(undefined, baseURL, use, testInfo);
+}
+
+/**
+ * Extend a Playwright `test` with a `stage` fixture:
+ *
+ *     export const test = withStage(base, { plugins: [webrtc(), connect()] });
+ *     test("...", async ({ page, stage }) => { ... });
+ */
+export function withStage<
+	Args extends object,
+	Workers extends object,
+	const Plugins extends readonly AnyWirePlugin[],
+>(
+	test: TestType<Args, Workers>,
+	options: StageFixtureOptions<Plugins>,
+): TestType<Args & { stage: Stage<Plugins> }, Workers> {
+	// Playwright reads a fixture's dependencies off the SOURCE of its first
+	// parameter, so the fixture must be passed as written — with its
+	// `({ context, baseURL }, use, testInfo)` destructuring — not wrapped. The
+	// cast is only for the generic `extend` signature, which TypeScript cannot
+	// resolve against an arbitrary `Args`.
+	const extend = test.extend.bind(test) as unknown as (fixtures: {
+		readonly stage: ReturnType<typeof createStageFixture<Plugins>>;
+	}) => TestType<Args & { stage: Stage<Plugins> }, Workers>;
+	return extend({ stage: createStageFixture(options) });
+}

package/src/connect.ts

@@ -0,0 +1,6 @@
+/**
+ * @heojeongbo/wirestage/connect — Connect, gRPC-web and gRPC.
+ * Needs the optional peers @connectrpc/connect, @connectrpc/connect-node and
+ * @bufbuild/protobuf.
+ */
+export * from "./features/connect/index.js";

package/src/entities/frame/@x/plugin.ts

@@ -0,0 +1,8 @@
+/**
+ * The frame types the plugin contract is written in terms of.
+ *
+ * FSD's cross-import notation: `entities/plugin` may import this file and
+ * nothing else from `entities/frame`. It keeps the dependency between the two
+ * entities explicit and one-way — the frame model knows nothing of plugins.
+ */
+export type { Frame, FrameFilter, Timeline } from "../model/frame.js";

package/src/entities/frame/index.ts

@@ -0,0 +1,19 @@
+export { compileFilter } from "./lib/filter.js";
+export { createPayload } from "./lib/payload.js";
+export type { TimelineOptions } from "./lib/timeline.js";
+export { createTimeline } from "./lib/timeline.js";
+export type {
+	Direction,
+	Frame,
+	FrameFilter,
+	FrameInit,
+	FrameKind,
+	FrameSource,
+	Payload,
+	PayloadInput,
+	SnapshotFrame,
+	SnapshotOptions,
+	Timeline,
+	TimelineCursor,
+	TimelineSnapshot,
+} from "./model/frame.js";

package/src/entities/frame/lib/filter.ts

@@ -0,0 +1,58 @@
+import type { Frame, FrameFilter } from "../model/frame.js";
+
+const ALWAYS = () => true;
+
+/**
+ * Compile a filter into one predicate. Queries run over every frame of a long
+ * test, often in a polling loop, so the per-frame work is a handful of
+ * comparisons and the `where` callback runs only after the cheap fields pass.
+ */
+export function compileFilter(
+	filter: FrameFilter | undefined,
+): (frame: Frame) => boolean {
+	if (filter === undefined) return ALWAYS;
+	const checks: ((frame: Frame) => boolean)[] = [];
+	const { protocol, kind, endpoint, where } = filter;
+	if (protocol !== undefined) {
+		if (typeof protocol === "string")
+			checks.push((f) => f.protocol === protocol);
+		else {
+			const set = new Set(protocol);
+			checks.push((f) => set.has(f.protocol));
+		}
+	}
+	if (kind !== undefined) {
+		if (typeof kind === "string") checks.push((f) => f.kind === kind);
+		else {
+			const set = new Set(kind);
+			checks.push((f) => set.has(f.kind));
+		}
+	}
+	for (const key of [
+		"direction",
+		"source",
+		"page",
+		"context",
+		"correlation",
+	] as const) {
+		const expected = filter[key];
+		if (expected !== undefined) checks.push((f) => f[key] === expected);
+	}
+	if (endpoint !== undefined) {
+		if (typeof endpoint === "string")
+			checks.push((f) => f.endpoint === endpoint);
+		else
+			checks.push((f) => {
+				endpoint.lastIndex = 0;
+				return endpoint.test(f.endpoint);
+			});
+	}
+	const after = filter.after;
+	if (after !== undefined) checks.push((f) => f.seq > after);
+	if (where !== undefined) checks.push(where);
+	if (checks.length === 0) return ALWAYS;
+	return (frame) => {
+		for (const check of checks) if (!check(frame)) return false;
+		return true;
+	};
+}

package/src/entities/frame/lib/payload.ts

@@ -0,0 +1,42 @@
+import { toBytes, utf8 } from "../../../shared/lib/bytes/index.js";
+import type { Payload, PayloadInput } from "../model/frame.js";
+
+const EMPTY = new Uint8Array(0);
+
+/**
+ * A payload that converts lazily and remembers every conversion. Frames are
+ * written far more often than read, so nothing is encoded or decoded until a
+ * test asks, and asking twice costs once.
+ */
+export function createPayload(input: PayloadInput | undefined): Payload {
+	let bytes: Uint8Array | undefined =
+		input instanceof Uint8Array ? input : undefined;
+	let text: string | undefined = typeof input === "string" ? input : undefined;
+	let decoded: WeakMap<(bytes: Uint8Array) => unknown, unknown> | undefined;
+
+	const getBytes = (): Uint8Array => {
+		if (bytes !== undefined) return bytes;
+		if (typeof input === "function") bytes = input();
+		else if (text !== undefined) bytes = toBytes(text);
+		else bytes = EMPTY;
+		return bytes;
+	};
+	const getText = (): string => {
+		text ??= utf8(getBytes());
+		return text;
+	};
+
+	return {
+		empty: input === undefined,
+		bytes: getBytes,
+		text: getText,
+		json: <T>() => JSON.parse(getText()) as T,
+		decode<T>(decoder: (bytes: Uint8Array) => T): T {
+			decoded ??= new WeakMap();
+			if (decoded.has(decoder)) return decoded.get(decoder) as T;
+			const value = decoder(getBytes());
+			decoded.set(decoder, value);
+			return value;
+		},
+	};
+}

package/src/entities/frame/lib/snapshot.ts

@@ -0,0 +1,105 @@
+import { toBase64 } from "../../../shared/lib/bytes/index.js";
+import type {
+	Frame,
+	SnapshotFrame,
+	SnapshotOptions,
+	TimelineSnapshot,
+} from "../model/frame.js";
+
+/**
+ * A JSON-safe copy of `frames`, with payloads cut at `maxBytes` and, given a
+ * `limit`, only the newest frames kept: a report is read from its end.
+ */
+export function snapshotFrames(
+	frames: readonly Frame[],
+	evicted: number,
+	options: SnapshotOptions = {},
+): TimelineSnapshot {
+	const maxBytes = options.maxBytes ?? 4096;
+	const kept =
+		options.limit === undefined || frames.length <= options.limit
+			? frames
+			: frames.slice(frames.length - options.limit);
+	return {
+		evicted,
+		omitted: frames.length - kept.length,
+		frames: kept.map((frame): SnapshotFrame => {
+			const base: SnapshotFrame = {
+				seq: frame.seq,
+				at: frame.at,
+				protocol: frame.protocol,
+				kind: frame.kind,
+				direction: frame.direction,
+				endpoint: frame.endpoint,
+				source: frame.source,
+				...(frame.page === undefined ? {} : { page: frame.page }),
+				...(frame.context === undefined ? {} : { context: frame.context }),
+				...(frame.correlation === undefined
+					? {}
+					: { correlation: frame.correlation }),
+				...(Object.keys(frame.meta).length === 0
+					? {}
+					: { meta: jsonSafe(frame.meta) }),
+			};
+			if (frame.payload.empty) return base;
+			const bytes = frame.payload.bytes();
+			return {
+				...base,
+				size: bytes.byteLength,
+				data: toBase64(bytes.subarray(0, maxBytes)),
+				...(bytes.byteLength > maxBytes ? { truncated: true } : {}),
+			};
+		}),
+	};
+}
+
+/**
+ * One line per frame: `#12  +3.2ms  connect  out request  pkg.Svc/Method  42B`.
+ * Times are relative to the first frame listed, which is what a reader of a
+ * failure report compares.
+ */
+export function formatFrames(
+	frames: readonly Frame[],
+	options: { readonly limit?: number } = {},
+): string {
+	const limit = options.limit ?? 200;
+	// Not `slice(-limit)`: a limit of 0 would be `slice(-0)`, every frame.
+	const shown =
+		frames.length > limit ? frames.slice(frames.length - limit) : frames;
+	const origin = shown[0]?.at ?? 0;
+	const lines = shown.map((frame) => {
+		const size = frame.payload.empty
+			? ""
+			: `  ${frame.payload.bytes().byteLength}B`;
+		const page = frame.page === undefined ? "" : `  ${frame.page}`;
+		return `#${frame.seq}  +${(frame.at - origin).toFixed(1)}ms  ${frame.protocol}  ${frame.direction} ${frame.kind}  ${frame.endpoint}${page}${size}`;
+	});
+	if (frames.length > limit)
+		lines.unshift(`… ${frames.length - limit} earlier frames not shown`);
+	return lines.join("\n");
+}
+
+/**
+ * Make `meta` survive `JSON.stringify`: a bigint (protobuf int64) or a cycle
+ * would otherwise throw while writing the report — at the exact moment a test
+ * has already failed and the report is the only evidence.
+ */
+function jsonSafe(
+	meta: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+	// The objects on the path from the root to the value being written. Only
+	// those make a cycle: an object met again elsewhere is merely shared.
+	const ancestors: object[] = [];
+	return JSON.parse(
+		JSON.stringify(meta, function (this: unknown, _key, value: unknown) {
+			if (typeof value === "bigint") return value.toString();
+			if (value instanceof Uint8Array) return toBase64(value);
+			if (typeof value !== "object" || value === null) return value;
+			// `this` holds `value`: whatever was above it is finished.
+			while (ancestors.length > 0 && ancestors.at(-1) !== this) ancestors.pop();
+			if (ancestors.includes(value)) return "[circular]";
+			ancestors.push(value);
+			return value;
+		}),
+	) as Record<string, unknown>;
+}

package/src/entities/frame/lib/timeline.ts

@@ -0,0 +1,147 @@
+import type { Clock } from "../../../shared/lib/clock/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type {
+	Frame,
+	FrameFilter,
+	FrameInit,
+	Timeline,
+	TimelineCursor,
+} from "../model/frame.js";
+import { compileFilter } from "./filter.js";
+import { createPayload } from "./payload.js";
+import { formatFrames, snapshotFrames } from "./snapshot.js";
+
+export interface TimelineOptions {
+	readonly clock: Clock;
+	/**
+	 * Frames kept before the oldest are dropped. A 60 Hz data channel makes
+	 * 3,600 frames a minute; the default holds a long test without letting a
+	 * soak run grow without bound.
+	 */
+	readonly capacity?: number;
+	/**
+	 * Told when a subscriber throws. By default the first such error is
+	 * thrown to whoever appended the frame, once every subscriber has run.
+	 */
+	readonly onListenerError?: (error: unknown) => void;
+}
+
+const DEFAULT_CAPACITY = 100_000;
+
+/**
+ * The append-only log every protocol writes to. Order is arrival order (`seq`),
+ * not timestamp order: the stage flushes page buffers before every read, so
+ * arrival order is also the order things happened in.
+ */
+export function createTimeline(options: TimelineOptions): Timeline {
+	const capacity = options.capacity ?? DEFAULT_CAPACITY;
+	if (!Number.isInteger(capacity) || capacity < 1)
+		throw new WirestageError(
+			"INVALID_ARGUMENT",
+			`timeline capacity must be a positive integer, got ${capacity}`,
+		);
+	let frames: Frame[] = [];
+	let evicted = 0;
+	let seq = 0;
+	const listeners = new Set<(frame: Frame) => void>();
+
+	const query = (filter: FrameFilter | undefined): Frame[] => {
+		if (filter === undefined) return frames.slice();
+		return frames.filter(compileFilter(filter));
+	};
+
+	/** Index of the first frame with `seq` greater than `position`. */
+	const indexAfter = (position: number): number => {
+		const first = frames[0];
+		if (first === undefined) return 0;
+		return Math.max(0, position - first.seq + 1);
+	};
+
+	return {
+		append(init: FrameInit): Frame {
+			const frame: Frame = {
+				seq: ++seq,
+				at: init.at ?? options.clock.now(),
+				protocol: init.protocol,
+				kind: init.kind,
+				direction: init.direction,
+				endpoint: init.endpoint,
+				source: init.source,
+				payload: createPayload(init.data),
+				value: init.value,
+				meta: init.meta ?? {},
+				page: init.page,
+				context: init.context,
+				correlation: init.correlation,
+			};
+			frames.push(frame);
+			if (frames.length > capacity) {
+				// Drop a tenth at once: shifting one frame per append would make a
+				// full timeline O(n) per frame.
+				const drop = Math.max(1, Math.floor(capacity / 10));
+				frames = frames.slice(drop);
+				evicted += drop;
+			}
+			// The frame is on the timeline whatever a subscriber does with it,
+			// and one that throws does not starve the rest.
+			const failures: unknown[] = [];
+			for (const listener of listeners) {
+				try {
+					listener(frame);
+				} catch (error) {
+					failures.push(error);
+				}
+			}
+			if (failures.length > 0) {
+				if (options.onListenerError === undefined) throw failures[0];
+				for (const failure of failures) options.onListenerError(failure);
+			}
+			return frame;
+		},
+		frames: query,
+		last(filter) {
+			const match = compileFilter(filter);
+			return frames.findLast(match);
+		},
+		marker(name) {
+			return frames.findLast((f) => f.kind === "marker" && f.endpoint === name);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		cursor(): TimelineCursor {
+			let position = seq;
+			return {
+				take(filter) {
+					const fresh = frames.slice(indexAfter(position));
+					position = seq;
+					return filter === undefined
+						? fresh
+						: fresh.filter(compileFilter(filter));
+				},
+				get position() {
+					return position;
+				},
+			};
+		},
+		clear() {
+			frames = [];
+		},
+		snapshot(filter, snapshotOptions) {
+			return snapshotFrames(query(filter), evicted, snapshotOptions);
+		},
+		format(filter, formatOptions) {
+			return formatFrames(query(filter), formatOptions);
+		},
+		get size() {
+			return frames.length;
+		},
+		get evicted() {
+			return evicted;
+		},
+		capacity,
+	};
+}