@heojeongbo/wirestage 0.0.0-stage → 0.1.1

package/dist/widgets/stage/lib/socket-router.js

@@ -0,0 +1,233 @@
+import { toBuffer } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import { compileUrlMatcher } from "../../../shared/lib/match/index.js";
+/** What a script may pass to `WebSocket.close()`: 1000, or 3000-4999. */
+const sendable = (code) => code === 1000 || (code >= 3000 && code <= 4999);
+const encoder = new TextEncoder();
+/**
+ * A close reason cut to what a close frame carries: 123 bytes of UTF-8 (the
+ * frame's 125, less the code), ending on a whole character.
+ */
+const fitReason = (reason) => 
+// `encodeInto` stops before the first character that does not fit whole.
+reason.slice(0, encoder.encodeInto(reason, new Uint8Array(123)).read);
+/**
+ * A close as the server's end can carry it out. Playwright closes that end
+ * with the browser's own `WebSocket.close(code, reason)`, which throws on a
+ * code a script may not send, on a reason without a code and on a reason
+ * over 123 bytes — and Playwright swallows the error, which leaves the
+ * connection open for good. Such a close goes out as a normal closure, 1000,
+ * with its reason cut to fit: the close is the point.
+ */
+const forServer = (options) => {
+    const { code, reason } = options ?? {};
+    if (code === undefined && reason === undefined)
+        return options;
+    return {
+        code: code !== undefined && sendable(code) ? code : 1000,
+        ...(reason === undefined ? {} : { reason: fitReason(reason) }),
+    };
+};
+/** The message handler of an end whose messages the rule does not take. */
+const drop = () => { };
+/**
+ * Turns WebSocket rules into ONE Playwright WebSocket route per attached
+ * context, whose predicate asks the live rule list.
+ *
+ * One route, because Playwright cannot take a WebSocket route out again: a
+ * removed rule, or a detached context, simply stops matching, which sends the
+ * socket to the real server. And not before it is needed, because routing
+ * replaces `WebSocket` in every document of the context — the first rule
+ * installs it, or `prepare()` does at attach.
+ */
+export function createSocketRouter(deps) {
+    /** Active rules, oldest first. */
+    const entries = [];
+    const attachments = new Set();
+    const routes = new Map();
+    let prepared = false;
+    /** The newest rule that wants a socket to `url`. */
+    const taker = (url) => entries.findLast((entry) => {
+        try {
+            return entry.matchesUrl(url);
+        }
+        catch (error) {
+            // The caller's predicate; one that throws must not break every
+            // socket of the context.
+            deps.log.error("rule's URL matcher failed", { rule: entry.rule.label, url: url.href }, error);
+            return false;
+        }
+    });
+    const retire = (entry) => {
+        if (!entry.active)
+            return;
+        entry.active = false;
+        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, onFailure, close = (options) => options) => {
+        const guarded = (handler) => (...args) => {
+            try {
+                // Typed `void`, yet an async function is a valid handler.
+                const result = 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, 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, view, server, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        deps.log.error("socket rule failed", { rule: rule.label, url: view.url.href }, error);
+        deps.timeline.append({
+            protocol: rule.protocol,
+            kind: "fault",
+            direction: "none",
+            endpoint: view.url.pathname,
+            source: "stub",
+            correlation: view.correlation,
+            context: view.context,
+            meta: { reason: "rule-error", rule: rule.label, error: message },
+        });
+        const closing = {
+            code: 1011,
+            // Cut like the server's end, though the page's would take it whole:
+            // no real server could send the page a longer one.
+            reason: fitReason(`wirestage: rule "${rule.label}" failed: ${message}`),
+        };
+        await Promise.all([view.page.close(closing), server?.close(closing)]);
+    };
+    const onSocket = async (attachment, route) => {
+        const url = new URL(route.url());
+        const entry = attachments.has(attachment) ? taker(url) : undefined;
+        // The rule went, or the context was detached, between Playwright's
+        // check and this call: the socket is the real server's.
+        if (entry === undefined) {
+            route.connectToServer();
+            return;
+        }
+        entry.hits += 1;
+        if (entry.remaining !== undefined && --entry.remaining === 0)
+            retire(entry);
+        // Playwright passes the messages of an end with no handler on to the
+        // other end, unrecorded: a rule that wires one direction would leak
+        // the other. So each end starts with a handler that drops them, which
+        // the rule's own replaces.
+        route.onMessage(drop);
+        let server;
+        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) => {
+            if (failed)
+                return;
+            failed = true;
+            await fail(entry.rule, view, server, error);
+        };
+        const view = {
+            correlation: deps.correlation(),
+            url,
+            context: attachment.id,
+            page: peer(route, failOnce),
+            connectToServer: () => {
+                if (server === undefined) {
+                    const upstream = route.connectToServer();
+                    upstream.onMessage(drop);
+                    server = peer(upstream, failOnce, forServer);
+                }
+                return server;
+            },
+        };
+        try {
+            // Awaited: Playwright opens the page's end of a socket the rule
+            // did not connect once this handler settles, so an async rule is
+            // wired up before the first message.
+            await entry.rule.open(view);
+        }
+        catch (error) {
+            // Never rejected to Playwright, where it would surface as an
+            // unhandled rejection in whichever test runs next.
+            await failOnce(error);
+        }
+    };
+    const ensureRoute = (attachment) => {
+        let installing = routes.get(attachment);
+        if (installing === undefined) {
+            installing = attachment.context.routeWebSocket((url) => attachments.has(attachment) && taker(url) !== undefined, (route) => onSocket(attachment, route));
+            routes.set(attachment, installing);
+            // A failed install must not be remembered as done.
+            installing.catch(() => routes.delete(attachment));
+        }
+        return installing;
+    };
+    return {
+        async add(rule) {
+            if (rule.times !== undefined &&
+                (!Number.isInteger(rule.times) || rule.times < 1))
+                throw new WirestageError("INVALID_ARGUMENT", `rule "${rule.label}": times must be a positive integer, got ${rule.times}`);
+            const entry = {
+                rule,
+                matchesUrl: compileUrlMatcher(rule.url),
+                remaining: rule.times,
+                hits: 0,
+                active: true,
+            };
+            entries.push(entry);
+            try {
+                await Promise.all([...attachments].map(ensureRoute));
+            }
+            catch (error) {
+                retire(entry);
+                throw error;
+            }
+            return {
+                get hits() {
+                    return entry.hits;
+                },
+                get active() {
+                    return entry.active;
+                },
+                async remove() {
+                    retire(entry);
+                },
+            };
+        },
+        prepare() {
+            prepared = true;
+        },
+        async attach(attachment) {
+            attachments.add(attachment);
+            if (prepared || entries.length > 0)
+                await ensureRoute(attachment);
+        },
+        detach(attachment) {
+            attachments.delete(attachment);
+            // The route stays in the browser; a context attached again gets a
+            // new one, and this one's predicate never matches again.
+            routes.delete(attachment);
+        },
+    };
+}
+//# sourceMappingURL=socket-router.js.map

package/dist/widgets/stage/lib/socket-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-router.js","sourceRoot":"","sources":["../../../../src/widgets/stage/lib/socket-router.ts"],"names":[],"mappings":"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"}

package/dist/widgets/stage/model/stage.d.ts

@@ -0,0 +1,88 @@
+import type { Frame, FrameFilter, Timeline, TimelineSnapshot } from "../../../entities/frame/index.js";
+import type { AnyWirePlugin, Attachment, PluginApis, WaitForOptions } from "../../../entities/plugin/index.js";
+import type { ContextPort, PagePort } from "../../../shared/api/playwright/index.js";
+import type { StreamServerOptions } from "../../../shared/api/stream-server/index.js";
+import type { Clock } from "../../../shared/lib/clock/index.js";
+export interface StageOptions<Plugins extends readonly AnyWirePlugin[]> {
+    /** The protocols this stage handles. Their APIs appear as `stage.<name>`. */
+    readonly plugins: Plugins;
+    /** Used by drive clients that are not given a URL of their own. */
+    readonly baseURL?: string;
+    /** Frames the timeline keeps. Default 100,000. */
+    readonly capacity?: number;
+    /**
+     * How long a page batches what it records before sending it on. Default
+     * 25 ms. The first entry after a quiet spell is sent at once.
+     */
+    readonly pageFlushMs?: number;
+    /**
+     * 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. */
+    readonly streamServer?: Pick<StreamServerOptions, "tls" | "host">;
+    /** Defaults for `waitFor`. */
+    readonly wait?: Pick<WaitForOptions, "timeout" | "interval">;
+    /** Replace time, for tests of the stage itself. */
+    readonly clock?: Clock;
+}
+export interface AttachOptions {
+    /** The context's base URL, for drive clients bound to it. */
+    readonly baseURL?: string;
+}
+export interface StageReport {
+    readonly snapshot: TimelineSnapshot;
+    readonly text: string;
+}
+export interface ReportOptions {
+    /** Frames kept, counting back from the newest. Default 1,000. */
+    readonly limit?: number;
+}
+/** The stage itself, before plugin APIs are mounted on it. */
+export interface StageCore {
+    readonly id: string;
+    /** The raw timeline. Reads here do NOT flush page buffers first; prefer the methods below. */
+    readonly timeline: Timeline;
+    readonly attachments: readonly Attachment[];
+    readonly disposed: boolean;
+    /**
+     * Start handling a browser context: install every plugin's routes and page
+     * hooks. Call before the first navigation. Returns a function that
+     * detaches. A failed attach is undone, so it can be tried again.
+     */
+    attach(context: ContextPort, options?: AttachOptions): Promise<() => Promise<void>>;
+    /** Detach one context, or all of them. */
+    detach(context?: ContextPort): Promise<void>;
+    /** 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 and the ends of the
+     * streams a stub closed. The reads below do it for you.
+     */
+    sync(): Promise<void>;
+    frames(filter?: FrameFilter): Promise<Frame[]>;
+    /** Frames since the previous `drain` (any filter), narrowed by `filter`. */
+    drain(filter?: FrameFilter): Promise<Frame[]>;
+    /** Put a named marker on the timeline, after everything that happened so far. */
+    mark(name: string, meta?: Readonly<Record<string, unknown>>): Promise<Frame>;
+    /** Frames after the most recent marker called `marker`. */
+    since(marker: string, filter?: FrameFilter): Promise<Frame[]>;
+    /** Frames between two markers, exclusive. */
+    between(from: string, to: string, filter?: FrameFilter): Promise<Frame[]>;
+    /** Resolve with the matching frames once `count` of them exist. */
+    waitFor(filter: FrameFilter, options?: WaitForOptions): Promise<Frame[]>;
+    /** The newest frames as JSON and as text. Does not flush: `sync()` first. */
+    report(filter?: FrameFilter, options?: ReportOptions): StageReport;
+    /**
+     * Detach everything, stop servers, release plugins. Idempotent. Every
+     * step runs even when one fails; what failed is thrown at the end.
+     */
+    dispose(): Promise<void>;
+}
+export type Stage<Plugins extends readonly AnyWirePlugin[] = readonly []> = StageCore & PluginApis<Plugins>;
+//# sourceMappingURL=stage.d.ts.map

package/dist/widgets/stage/model/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../../../src/widgets/stage/model/stage.ts"],"names":[],"mappings":"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"}

package/dist/widgets/stage/model/stage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stage.js.map

package/dist/widgets/stage/model/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","sourceRoot":"","sources":["../../../../src/widgets/stage/model/stage.ts"],"names":[],"mappings":""}

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.1",
+	"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";