@heojeongbo/wirestage 0.0.0-stage → 0.1.1

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,156 @@
+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` is sent as a header line each,
+	 * any other header as one value, `, `-separated. A header Chromium
+	 * would refuse — a name that is not a token, a CR or NUL in a value — is
+	 * the rule's error.
+	 */
+	| {
+			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. An `open` that throws is the rule's
+	 * error, as a throwing `handle` is: the page gets the 500 while nothing
+	 * has gone out, and a cut connection after.
+	 */
+	| {
+			readonly type: "stream";
+			open(stream: ResponseStream): void | Promise<void>;
+	  }
+	/**
+	 * Send to the network, optionally rewritten. Lower rules are skipped.
+	 * `url` may be relative to the request's, and keeps its scheme:
+	 * Playwright rewrites a URL within its scheme only.
+	 */
+	| {
+			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;
+}

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

@@ -0,0 +1,96 @@
+import type { Clock } from "../../../shared/lib/clock/index.js";
+import type {
+	LogScope,
+	ScopedLogger,
+} from "../../../shared/lib/logger/index.js";
+import type { Frame, FrameFilter, Timeline } from "../../frame/@x/plugin.js";
+import type { Attachment } from "./attachment.js";
+import type { HttpRouter } from "./http.js";
+import type { PageHost } from "./page.js";
+import type { SocketRouter } from "./socket.js";
+
+export interface WaitForOptions {
+	/** Frames to wait for. Default 1. */
+	readonly count?: number;
+	/** Milliseconds. Default 5000. */
+	readonly timeout?: number;
+	/** Milliseconds between polls of the page buffers. Default 25. */
+	readonly interval?: number;
+}
+
+/**
+ * Everything a plugin may use. A plugin never drives the browser itself:
+ * routing and page hooks go through these services, built and owned by the
+ * stage, and that is the seam that lets each plugin be unit-tested against
+ * fakes and lets several plugins share one browser context without stepping
+ * on each other.
+ */
+export interface PluginContext {
+	/**
+	 * The name the plugin is set up under: its own, or the one `named()` gave
+	 * it. A plugin records its frames with this as their `protocol` (and
+	 * names its page modules by it), so two instances keep their traffic
+	 * apart.
+	 */
+	readonly name: string;
+	readonly timeline: Timeline;
+	readonly clock: Clock;
+	/** Scoped to the plugin's declared scope. */
+	readonly log: ScopedLogger;
+	/** HTTP: fetch, XHR, EventSource, and anything else a route can see. */
+	readonly http: HttpRouter;
+	/** WebSockets. */
+	readonly sockets: SocketRouter;
+	/** Code that runs inside every page, for what no route can see. */
+	readonly pages: PageHost;
+	readonly baseURL: string | undefined;
+	attachments(): readonly Attachment[];
+	/** Flush every page buffer into the timeline. Call before reading frames. */
+	sync(): Promise<void>;
+	waitFor(filter: FrameFilter, options?: WaitForOptions): Promise<Frame[]>;
+	/**
+	 * Build on another plugin: set it up inside this one and get its API. A
+	 * protocol layered on others (GraphQL over HTTP and WebSocket, say) is
+	 * written in terms of theirs instead of re-deriving them. The stage runs
+	 * the inner plugin's hooks with the outer's; it is not mounted on the
+	 * stage. Wrap it in `named()` to keep its frames apart from another
+	 * instance's.
+	 */
+	use<Api>(plugin: WirePlugin<string, Api>): Api;
+}
+
+export interface PluginRuntime<Api> {
+	/** Mounted on the stage under the plugin's name. */
+	readonly api: Api;
+	/** A context was attached. Page modules and HTTP rules are already in place. */
+	attach?(attachment: Attachment): void | Promise<void>;
+	/** A context is being detached. */
+	detach?(attachment: Attachment): void | Promise<void>;
+	/** The stage is being disposed; release servers and timers. */
+	dispose?(): void | Promise<void>;
+}
+
+/**
+ * A protocol, as the stage sees it. The stage knows nothing about any
+ * protocol in particular: REST, Connect, WebRTC and the rest are all plugins,
+ * and a new protocol is a new plugin, not a change to the stage.
+ */
+export interface WirePlugin<Name extends string = string, Api = unknown> {
+	/** The key its API is mounted under: `stage.<name>`. */
+	readonly name: Name;
+	/** The badge on the plugin's log lines; eight characters fit the column. */
+	readonly scope?: LogScope;
+	setup(context: PluginContext): PluginRuntime<Api>;
+}
+
+export type AnyWirePlugin = WirePlugin<string, unknown>;
+
+/** `{ webrtc: WebRtcApi, connect: ConnectApi }` from `[webrtc(), connect()]`. */
+export type PluginApis<Plugins extends readonly AnyWirePlugin[]> = {
+	readonly [Plugin in Plugins[number] as Plugin["name"]]: Plugin extends WirePlugin<
+		string,
+		infer Api
+	>
+		? Api
+		: never;
+};