@heojeongbo/wirestage 0.0.0-stage → 0.1.0

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

package/src/entities/frame/model/frame.ts

@@ -0,0 +1,191 @@
+/**
+ * Which way a frame travelled, from the page's point of view: `out` left the
+ * page (a request, a sent message), `in` reached it. Markers and lifecycle
+ * events travel nowhere.
+ */
+export type Direction = "out" | "in" | "none";
+
+export type FrameKind =
+	/** The opening half of an exchange: an HTTP request, an RPC's request message. */
+	| "request"
+	/** The closing half: an HTTP response, an RPC's status. */
+	| "response"
+	/** One message on a stream or channel. */
+	| "message"
+	/** One server-sent event. */
+	| "event"
+	/** A named point the test placed on the timeline. */
+	| "marker"
+	/** Something went wrong on purpose or by accident: an abort, a drop, a cut. */
+	| "fault"
+	/** A channel or connection opened or closed. */
+	| "lifecycle";
+
+/**
+ * Who produced what the frame carries. With `direction` it says who was
+ * talking to whom: `out` from `page` is the app speaking, `in` from `stub`
+ * is a stub answering it, `in` from `network` the real backend.
+ */
+export type FrameSource =
+	/** The app in the browser: its requests, the messages it sends. */
+	| "page"
+	/** The real backend, a real remote peer, or a client outside the browser. */
+	| "network"
+	/** A stub: its responses, its messages, the faults it injects. */
+	| "stub"
+	/** The test itself: markers, drive-client requests, injected messages. */
+	| "test"
+	/** A fake served on a port of its own (`serve()`). */
+	| "server";
+
+/**
+ * A payload as given: bytes, text, or a thunk that encodes on demand. The thunk
+ * keeps a high-rate stub from serializing every message twice when nobody ever
+ * reads the bytes back.
+ */
+export type PayloadInput = Uint8Array | string | (() => Uint8Array);
+
+export interface Payload {
+	/** True when the frame carries no payload at all. */
+	readonly empty: boolean;
+	bytes(): Uint8Array;
+	/** UTF-8 text of the bytes, or the text as given. */
+	text(): string;
+	/** `JSON.parse(text())`. Throws on invalid JSON. */
+	json<T = unknown>(): T;
+	/**
+	 * Decode with `decoder`, cached per decoder: asserting on the same frame
+	 * from three helpers decodes it once.
+	 */
+	decode<T>(decoder: (bytes: Uint8Array) => T): T;
+}
+
+export interface FrameInit {
+	/** The protocol plugin's name: `webrtc`, `connect`, `rest`, ... */
+	readonly protocol: string;
+	readonly kind: FrameKind;
+	readonly direction: Direction;
+	/**
+	 * What the frame is about, in the protocol's own terms: a URL path, an RPC
+	 * (`pkg.Service/Method`), a channel label, a WebSocket URL, a marker name.
+	 */
+	readonly endpoint: string;
+	readonly source: FrameSource;
+	/** Epoch milliseconds. Defaults to the stage clock's now. */
+	readonly at?: number;
+	readonly data?: PayloadInput;
+	/** An already-decoded form of the payload, e.g. a protobuf message. */
+	readonly value?: unknown;
+	readonly meta?: Readonly<Record<string, unknown>>;
+	/** The page the frame belongs to (`p1`, ...). */
+	readonly page?: string;
+	/** The browser context the frame belongs to (`c1`, ...). */
+	readonly context?: string;
+	/** Links the frames of one exchange: a request, its messages, its response. */
+	readonly correlation?: string;
+}
+
+export interface Frame {
+	/** Arrival order on the timeline, starting at 1. The order to trust. */
+	readonly seq: number;
+	/** Epoch milliseconds. Informational: page and Node clocks differ slightly. */
+	readonly at: number;
+	readonly protocol: string;
+	readonly kind: FrameKind;
+	readonly direction: Direction;
+	readonly endpoint: string;
+	readonly source: FrameSource;
+	readonly payload: Payload;
+	readonly value: unknown;
+	readonly meta: Readonly<Record<string, unknown>>;
+	readonly page: string | undefined;
+	readonly context: string | undefined;
+	readonly correlation: string | undefined;
+}
+
+export interface FrameFilter {
+	readonly protocol?: string | readonly string[];
+	readonly kind?: FrameKind | readonly FrameKind[];
+	readonly direction?: Direction;
+	/** Exact match, or a RegExp tested against the endpoint. */
+	readonly endpoint?: string | RegExp;
+	readonly source?: FrameSource;
+	readonly page?: string;
+	readonly context?: string;
+	readonly correlation?: string;
+	/** Only frames whose `seq` is greater. */
+	readonly after?: number;
+	/** Any further condition. Runs last, so cheap fields filter first. */
+	readonly where?: (frame: Frame) => boolean;
+}
+
+/** A consumer's position on the timeline: each `take` returns what is new. */
+export interface TimelineCursor {
+	/**
+	 * Frames appended since the previous `take` that match `filter`. The
+	 * cursor moves past ALL of them, matching or not: "what happened since I
+	 * last looked", narrowed.
+	 */
+	take(filter?: FrameFilter): Frame[];
+	/** The `seq` the cursor has read up to. */
+	readonly position: number;
+}
+
+export interface SnapshotFrame {
+	readonly seq: number;
+	readonly at: number;
+	readonly protocol: string;
+	readonly kind: FrameKind;
+	readonly direction: Direction;
+	readonly endpoint: string;
+	readonly source: FrameSource;
+	readonly page?: string;
+	readonly context?: string;
+	readonly correlation?: string;
+	readonly meta?: Readonly<Record<string, unknown>>;
+	/** Base64 of the payload, cut at the snapshot's byte limit. */
+	readonly data?: string;
+	readonly size?: number;
+	readonly truncated?: boolean;
+}
+
+/** A JSON-safe copy of the timeline, for a test report attachment. */
+export interface TimelineSnapshot {
+	readonly frames: readonly SnapshotFrame[];
+	/** Frames dropped from the front because the timeline hit its capacity. */
+	readonly evicted: number;
+	/** Earlier matching frames left out by the snapshot's `limit`. */
+	readonly omitted: number;
+}
+
+export interface SnapshotOptions {
+	/** Bytes of payload kept per frame. Default 4096. */
+	readonly maxBytes?: number;
+	/** Frames kept, counting back from the newest. Default: all of them. */
+	readonly limit?: number;
+}
+
+export interface Timeline {
+	/** Append a frame and notify subscribers. The only way frames enter. */
+	append(init: FrameInit): Frame;
+	frames(filter?: FrameFilter): Frame[];
+	last(filter?: FrameFilter): Frame | undefined;
+	/** The most recent marker with this name. */
+	marker(name: string): Frame | undefined;
+	/**
+	 * Called for every appended frame, synchronously, after it is on the
+	 * timeline. A listener that throws does not stop the others. Returns
+	 * unsubscribe.
+	 */
+	subscribe(listener: (frame: Frame) => void): () => void;
+	/** A new cursor starting at the current end. */
+	cursor(): TimelineCursor;
+	/** Drop every frame. `seq` keeps counting; `evicted` is left alone. */
+	clear(): void;
+	snapshot(filter?: FrameFilter, options?: SnapshotOptions): TimelineSnapshot;
+	/** A human-readable listing, one line per frame. */
+	format(filter?: FrameFilter, options?: { readonly limit?: number }): string;
+	readonly size: number;
+	readonly evicted: number;
+	readonly capacity: number;
+}

package/src/entities/plugin/index.ts

@@ -0,0 +1,36 @@
+export { definePlugin } from "./lib/define-plugin.js";
+export { named } from "./lib/named.js";
+export type { Attachment } from "./model/attachment.js";
+export type {
+	AbortErrorCode,
+	HttpOutcome,
+	HttpRequestView,
+	HttpRouter,
+	HttpRule,
+	HttpRuleHandle,
+	PassthroughResponse,
+} from "./model/http.js";
+export type {
+	PageEntry,
+	PageHost,
+	PageInstaller,
+	PageModule,
+	PageModuleEnv,
+	PageSource,
+} from "./model/page.js";
+export type {
+	AnyWirePlugin,
+	PluginApis,
+	PluginContext,
+	PluginRuntime,
+	WaitForOptions,
+	WirePlugin,
+} from "./model/plugin.js";
+export type {
+	SocketPeer,
+	SocketRouter,
+	SocketRule,
+	SocketRuleHandle,
+	SocketView,
+} from "./model/socket.js";
+export type { ResponseStream, StreamEnd } from "./model/stream.js";

package/src/entities/plugin/lib/define-plugin.ts

@@ -0,0 +1,12 @@
+import type { WirePlugin } from "../model/plugin.js";
+
+/**
+ * Identity, for inference: it keeps the plugin's `name` a literal type, so
+ * `createStage({ plugins: [myPlugin()] })` types `stage.myPlugin` without the
+ * author writing the generic arguments out.
+ */
+export function definePlugin<const Name extends string, Api>(
+	plugin: WirePlugin<Name, Api>,
+): WirePlugin<Name, Api> {
+	return plugin;
+}

package/src/entities/plugin/lib/named.ts

@@ -0,0 +1,21 @@
+import type { WirePlugin } from "../model/plugin.js";
+
+/**
+ * The same plugin under another name: mounted as `stage.<name>`, and
+ * recording its frames under that name. What lets one protocol run twice —
+ * two backends, two sets of channels — with each instance's traffic apart:
+ *
+ *     plugins: [rest({ baseURL: "/api" }), named("billing", rest({ baseURL: "https://billing.test" }))]
+ */
+export function named<const Name extends string, Api>(
+	name: Name,
+	plugin: WirePlugin<string, Api>,
+): WirePlugin<Name, Api> {
+	return {
+		name,
+		scope: plugin.scope,
+		// Called on the plugin, not copied off it: a plugin written as a class
+		// has `setup` on its prototype, which a spread leaves behind.
+		setup: (context) => plugin.setup(context),
+	};
+}

package/src/entities/plugin/model/attachment.ts

@@ -0,0 +1,18 @@
+import type { CookieJarPort } from "../../../shared/api/playwright/index.js";
+
+/**
+ * One browser context the stage is attached to, as a plugin sees it: a
+ * frozen view, not the context. The context stays with the stage, and a
+ * plugin reaches the browser through the services of its `PluginContext`.
+ */
+export interface Attachment {
+	/** `c1`, `c2`, ... — what frames name in their `context` field. */
+	readonly id: string;
+	/** The context's base URL, when the caller supplied one. */
+	readonly baseURL: string | undefined;
+	/**
+	 * The context's cookie jar, for a client that calls as the signed-in
+	 * page: reads and adds go to the context, and nothing else does.
+	 */
+	readonly cookies: CookieJarPort;
+}

package/src/entities/plugin/model/http.ts

@@ -0,0 +1,147 @@
+import type { UrlMatcher } from "../../../shared/lib/match/index.js";
+import type { ResponseStream } from "./stream.js";
+
+/**
+ * A request a rule is deciding about, read-only and decoded on demand.
+ *
+ * One per request: every rule the request reaches is given this same object,
+ * so a plugin may key what it knows about a request on it (a `WeakMap`), and
+ * the frames different rules record for one request share one `correlation`.
+ */
+export interface HttpRequestView {
+	/** Links every frame of this exchange. */
+	readonly correlation: string;
+	readonly method: string;
+	readonly url: URL;
+	/** Lower-cased names. */
+	readonly headers: Readonly<Record<string, string>>;
+	/** The page that sent it; undefined for service-worker requests. */
+	readonly page: string | undefined;
+	readonly context: string;
+	readonly resourceType: string;
+	body(): Uint8Array;
+	text(): string;
+	json<T = unknown>(): T;
+}
+
+/** Playwright's `route.abort` error codes. */
+export type AbortErrorCode =
+	| "aborted"
+	| "accessdenied"
+	| "addressunreachable"
+	| "blockedbyclient"
+	| "blockedbyresponse"
+	| "connectionaborted"
+	| "connectionclosed"
+	| "connectionfailed"
+	| "connectionrefused"
+	| "connectionreset"
+	| "internetdisconnected"
+	| "namenotresolved"
+	| "timedout"
+	| "failed";
+
+/**
+ * What a rule decided. A closed union: the router carries each member out
+ * through a table keyed by `type`, so a new outcome does not compile until
+ * the router knows what to do with it.
+ */
+export type HttpOutcome =
+	/**
+	 * Answer with a complete response. A header may carry several values
+	 * separated by a newline (`set-cookie`).
+	 */
+	| {
+			readonly type: "fulfill";
+			readonly status?: number;
+			readonly headers?: Readonly<Record<string, string>>;
+			readonly body?: Uint8Array | string;
+	  }
+	/**
+	 * Answer with a response that stays open (server streams, SSE): `open`
+	 * gets the stream to write. The request is redirected to the stage's
+	 * local stream server, which `route.fulfill` cannot stand in for because
+	 * it takes the whole body at once.
+	 */
+	| {
+			readonly type: "stream";
+			open(stream: ResponseStream): void | Promise<void>;
+	  }
+	/** Send to the network, optionally rewritten. Lower rules are skipped. */
+	| {
+			readonly type: "continue";
+			readonly url?: string;
+			readonly method?: string;
+			readonly headers?: Readonly<Record<string, string>>;
+			readonly body?: Uint8Array | string;
+	  }
+	/** Let the next matching rule (or the network) decide. */
+	| { readonly type: "fallback" }
+	/** Fail the request at the network level. */
+	| { readonly type: "abort"; readonly error?: AbortErrorCode };
+
+/** The network's answer to a request a rule passed through. */
+export interface PassthroughResponse {
+	readonly status: number;
+	readonly headers: Readonly<Record<string, string>>;
+	/** Undefined when the browser did not keep the body (redirects, some errors). */
+	readonly body: Uint8Array | undefined;
+}
+
+export interface HttpRule {
+	/** The `protocol` of the frames this rule records. */
+	readonly protocol: string;
+	/** Names the rule in logs and diagnostics. */
+	readonly label: string;
+	readonly url: UrlMatcher;
+	/** Upper-case HTTP methods. Any method when omitted. */
+	readonly method?: string | readonly string[];
+	/** Stop matching after this many handled requests. */
+	readonly times?: number;
+	/** A last, request-aware condition; false falls back to the next rule. */
+	readonly match?: (request: HttpRequestView) => boolean;
+	/**
+	 * Record the raw request and how it ended as frames. Default true. A plugin
+	 * that records decoded frames of its own (Connect) turns this off. A
+	 * request several recording rules of one protocol see is recorded once.
+	 */
+	readonly record?: boolean;
+	/** The frame endpoint for a request. Defaults to the URL path. */
+	readonly endpoint?: (request: HttpRequestView) => string;
+	handle(request: HttpRequestView): HttpOutcome | Promise<HttpOutcome>;
+	/**
+	 * Called with the network's response to a request this rule passed on
+	 * (`continue` or `fallback`). Not called when another rule answered it:
+	 * that response is a stub's, not the network's.
+	 */
+	readonly onPassthroughResponse?: (
+		response: PassthroughResponse,
+		request: HttpRequestView,
+	) => void;
+	/**
+	 * Called when a request this rule passed on failed at the network level,
+	 * with the browser's error text (`net::ERR_CONNECTION_RESET`, ...).
+	 */
+	readonly onPassthroughFailure?: (
+		error: string | undefined,
+		request: HttpRequestView,
+	) => void;
+}
+
+export interface HttpRuleHandle {
+	/** Requests this rule handled (matched and decided), not merely saw. */
+	readonly hits: number;
+	readonly active: boolean;
+	/** Stop matching, in every attached context. */
+	remove(): Promise<void>;
+}
+
+/**
+ * Where plugins put HTTP rules. Rules apply to every attached context, present
+ * and future. Later rules win, like Playwright routes and MSW's `use()`, so a
+ * test can override a suite-wide stub for one case; a rule that answers
+ * `fallback` hands the request to the next one down.
+ */
+export interface HttpRouter {
+	add(rule: HttpRule): Promise<HttpRuleHandle>;
+}

package/src/entities/plugin/model/page.ts

@@ -0,0 +1,110 @@
+import type { PagePort } from "../../../shared/api/playwright/index.js";
+
+/** One thing an in-page module observed, on its way to the timeline. */
+export interface PageEntry {
+	/** The module's own discriminator: `out`, `in`, `open`, ... */
+	readonly type: string;
+	/** Epoch milliseconds, by the page's clock. */
+	readonly at: number;
+	/** A binary payload, base64. */
+	readonly data?: string;
+	/** A text payload. */
+	readonly text?: string;
+	readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+/** What the page runtime hands an installer, inside the page. */
+export interface PageModuleEnv<State = unknown, Config = unknown> {
+	readonly window: Window & typeof globalThis;
+	readonly config: Config;
+	/**
+	 * Queue an entry. Entries are batched and flushed to Node: a document
+	 * that navigates sends what it holds on `beforeunload`, one that closes
+	 * (or an iframe removed) on `pagehide`. What it emits after that, on its
+	 * way out, can be lost.
+	 */
+	emit(entry: PageEntry): void;
+	/** The page's epoch-millisecond clock. */
+	now(): number;
+	/** Bytes to base64. */
+	encode(bytes: Uint8Array): string;
+	/** Base64 to bytes, in a fresh ArrayBuffer of exactly that size. */
+	decode(text: string): Uint8Array;
+	/** Answer a command the test sends with `PageHost.command`. */
+	onCommand(op: string, handler: (args: never) => unknown): void;
+	/**
+	 * Receive the module's state: shortly after load (it comes from Node, so
+	 * the document's first script may run before it), and on every change.
+	 * One that throws does not keep the state from the others: it is logged
+	 * in Node, or fails the `refresh()` that sent the state.
+	 */
+	onState(handler: (state: State) => void): void;
+	/**
+	 * Undo what `install` did to the page: put back what was wrapped. Runs
+	 * when the stage detaches, so a document that outlives the stage is left
+	 * as the stage found it — and in a document the detach did not reach, as
+	 * soon as the runtime finds the binding gone. One that throws does not
+	 * stop the others, and is logged in Node while the binding lasts.
+	 */
+	onDetach(handler: () => void): void;
+}
+
+/**
+ * Runs INSIDE the page, so it is serialized with `Function.prototype.toString`.
+ * It must be self-contained — no imports, no closure over module scope — and
+ * declared with `function`, since an object-method body does not serialize to
+ * a valid expression. `register` refuses one whose source is not a function
+ * expression: a method, a bound or a native function.
+ */
+export type PageInstaller<State = unknown, Config = unknown> = (
+	env: PageModuleEnv<State, Config>,
+) => void;
+
+export interface PageSource {
+	readonly page: string;
+	readonly context: string;
+}
+
+export interface PageModule<State = unknown, Config = unknown> {
+	/** Unique per stage; the key commands and entries are routed by. */
+	readonly id: string;
+	readonly install: PageInstaller<State, Config>;
+	/** JSON-serializable; fixed for the life of the attachment. */
+	readonly config: Config;
+	/** The state a freshly loaded page should start with. JSON-serializable. */
+	state(): State;
+	/** Entries flushed from a page, in emission order. */
+	receive(entries: readonly PageEntry[], source: PageSource): void;
+}
+
+/**
+ * Where plugins put code that runs in every page. Modules register at setup;
+ * the host injects them all as one init script per attached context, with one
+ * binding back to Node.
+ */
+export interface PageHost {
+	/**
+	 * Add a module to the init script. Throws `INVALID_ARGUMENT` for an id
+	 * already taken or an installer that does not serialize to a function
+	 * expression, and `INVALID_STATE` once the stage has been attached.
+	 */
+	register<State, Config>(module: PageModule<State, Config>): void;
+	/**
+	 * Run a module's command handler in every frame of every open page (or of
+	 * one page, by id) and return each frame's answer. Frames that are going
+	 * away are skipped; a handler that throws rejects the call.
+	 */
+	command(
+		module: string,
+		op: string,
+		args?: unknown,
+		options?: { readonly page?: string },
+	): Promise<unknown[]>;
+	/**
+	 * Send the module's current `state()` to every frame of every open page.
+	 * Documents loaded later ask for it when their runtime starts.
+	 */
+	refresh(module: string): Promise<void>;
+	/** The id frames use for `page`. */
+	pageId(page: PagePort): string;
+}