@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,141 @@
 {
-  "name": "@heojeongbo/wirestage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@heojeongbo/wirestage",
+	"version": "0.1.0",
+	"description": "Record, fake and fault-inject browser wire traffic in Playwright: REST, Connect, gRPC-web, gRPC, SSE, WebSocket and WebRTC data channels on one timeline.",
+	"type": "module",
+	"license": "MIT",
+	"author": "heojeongbo <heojungbo@gmail.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/heojeongbo/wirestage.git"
+	},
+	"homepage": "https://github.com/heojeongbo/wirestage#readme",
+	"bugs": "https://github.com/heojeongbo/wirestage/issues",
+	"keywords": [
+		"playwright",
+		"testing",
+		"mock",
+		"grpc-web",
+		"connectrpc",
+		"grpc",
+		"websocket",
+		"webrtc",
+		"datachannel",
+		"sse",
+		"e2e"
+	],
+	"packageManager": "pnpm@11.16.0",
+	"engines": {
+		"node": ">=22.12"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/__fixtures__",
+		"README.md",
+		"LICENSE",
+		"LICENSES.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./playwright": {
+			"types": "./dist/playwright.d.ts",
+			"default": "./dist/playwright.js"
+		},
+		"./connect": {
+			"types": "./dist/connect.d.ts",
+			"default": "./dist/connect.js"
+		},
+		"./rest": {
+			"types": "./dist/rest.d.ts",
+			"default": "./dist/rest.js"
+		},
+		"./sse": {
+			"types": "./dist/sse.d.ts",
+			"default": "./dist/sse.js"
+		},
+		"./websocket": {
+			"types": "./dist/websocket.d.ts",
+			"default": "./dist/websocket.js"
+		},
+		"./webrtc": {
+			"types": "./dist/webrtc.d.ts",
+			"default": "./dist/webrtc.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+		"build": "pnpm clean && tsc -p tsconfig.build.json",
+		"type:check": "tsc --noEmit",
+		"lint": "biome check --error-on-warnings .",
+		"format": "biome check --write .",
+		"fsd:check": "tsx scripts/check-boundaries.ts",
+		"test": "vitest run --project unit",
+		"test:coverage": "vitest run --project unit --coverage",
+		"test:browser": "vitest run --project browser",
+		"e2e": "pnpm build && tsc --noEmit -p e2e/tsconfig.json && playwright test",
+		"bench": "vitest bench --run --config vitest.bench.config.ts",
+		"perf": "tsx scripts/perf.ts",
+		"perf:check": "tsx scripts/perf.ts --check",
+		"docs:check": "node scripts/check-docs.mjs",
+		"package:check": "node scripts/check-package.mjs",
+		"gen:proto": "buf generate",
+		"check": "pnpm lint && pnpm fsd:check && pnpm type:check && pnpm test:coverage && pnpm build && pnpm docs:check && pnpm package:check",
+		"check:browser": "pnpm test:browser && pnpm e2e && pnpm perf:check",
+		"prepare": "husky || true",
+		"prepack": "pnpm build",
+		"prepublishOnly": "pnpm check && pnpm check:browser"
+	},
+	"dependencies": {
+		"@heojeongbo/log-palette": "^0.2.2"
+	},
+	"peerDependencies": {
+		"@bufbuild/protobuf": "^2.10.0",
+		"@connectrpc/connect": "^2.1.0",
+		"@connectrpc/connect-node": "^2.1.0",
+		"@playwright/test": ">=1.50.0"
+	},
+	"peerDependenciesMeta": {
+		"@bufbuild/protobuf": {
+			"optional": true
+		},
+		"@connectrpc/connect": {
+			"optional": true
+		},
+		"@connectrpc/connect-node": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@bufbuild/buf": "1.73.0",
+		"@bufbuild/protobuf": "2.12.0",
+		"@bufbuild/protoc-gen-es": "2.12.0",
+		"@commitlint/cli": "20.1.0",
+		"@commitlint/config-conventional": "20.2.0",
+		"@connectrpc/connect": "2.1.1",
+		"@connectrpc/connect-node": "2.1.1",
+		"@connectrpc/connect-web": "2.1.1",
+		"@playwright/test": "1.60.0",
+		"@types/node": "24.3.0",
+		"@vitest/coverage-v8": "4.1.11",
+		"esbuild": "0.25.10",
+		"husky": "9.1.7",
+		"lint-staged": "16.2.7",
+		"tsx": "4.20.4",
+		"typescript": "5.9.3",
+		"vitest": "4.1.11"
+	},
+	"lint-staged": {
+		"*.{ts,mts,js,mjs,json,jsonc}": "biome check --write --no-errors-on-unmatched"
+	}
+}

package/src/app/playwright/index.ts

@@ -0,0 +1,7 @@
+export type {
+	ReportMode,
+	StageFixtureArgs,
+	StageFixtureOptions,
+	StageTestInfo,
+} from "./lib/fixture.js";
+export { createStageFixture, withStage } from "./lib/fixture.js";

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>;
+}