@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/src/features/connect/model/types.ts

@@ -0,0 +1,305 @@
+import type {
+	DescMessage,
+	DescMethod,
+	DescMethodServerStreaming,
+	DescMethodUnary,
+	DescService,
+	JsonReadOptions,
+	JsonWriteOptions,
+	MessageInitShape,
+	MessageShape,
+} from "@bufbuild/protobuf";
+import type {
+	Client,
+	Code,
+	ConnectRouter,
+	HandlerContext,
+	ServiceImpl,
+} from "@connectrpc/connect";
+
+import type { Frame, FrameSource } from "../../../entities/frame/index.js";
+import type {
+	AbortErrorCode,
+	HttpRequestView,
+	StreamEnd as ResponseEnd,
+} from "../../../entities/plugin/index.js";
+import type { CookieJarPort } from "../../../shared/api/playwright/index.js";
+
+/** The three wire protocols connect-es speaks. Browsers use the first two. */
+export type RpcProtocol = "connect" | "grpc-web" | "grpc";
+
+export interface ConnectOptions {
+	/**
+	 * What the app's transport puts in front of `/<package>.<Service>/<Method>`:
+	 * a path prefix (`/api`) on any origin, or an origin with one
+	 * (`https://api.example.test/rpc`). Without it a stub matches that suffix
+	 * under any prefix. It is also where `client()` calls by default.
+	 */
+	readonly baseURL?: string;
+	/**
+	 * Protocols stubs answer. Default: connect and grpc-web — the two a browser
+	 * can speak. A call in another protocol passes every stub by. Native gRPC
+	 * is for `serve()`.
+	 */
+	readonly protocols?: readonly RpcProtocol[];
+	/**
+	 * Services whose traffic is recorded and decoded even when nothing stubs
+	 * it, so `calls()` sees the real backend's answers too.
+	 */
+	readonly record?: readonly DescService[];
+	/**
+	 * `live` (default) answers server streams from a local server, message by
+	 * message, as the stub produces them. `buffered` collects the whole stream
+	 * and fulfills it at once — the only choice on an https page without
+	 * `streamServer.tls`, and only useful for streams that end.
+	 */
+	readonly streaming?: "live" | "buffered";
+	/** The protocol `client()` uses by default. Default `connect`. */
+	readonly clientProtocol?: RpcProtocol;
+	readonly jsonOptions?: Partial<JsonReadOptions & JsonWriteOptions>;
+}
+
+export interface HoldOptions<I extends DescMessage = DescMessage> {
+	/** Take this many calls, then leave the rest to the next rule. */
+	readonly times?: number;
+	/**
+	 * Take only the calls this accepts; the rest go on to the next rule, or to
+	 * the real backend. Gets the decoded request message, and the raw request
+	 * for its headers. A request that does not decode never matches.
+	 */
+	readonly match?: (request: MessageShape<I>, view: HttpRequestView) => boolean;
+}
+
+export interface StubOptions<I extends DescMessage = DescMessage>
+	extends HoldOptions<I> {
+	/** Wait this long before answering. */
+	readonly delayMs?: number;
+}
+
+export interface StubHandle {
+	/** Calls this stub took. */
+	readonly hits: number;
+	remove(): Promise<void>;
+}
+
+export type UnaryReply<I extends DescMessage, O extends DescMessage> =
+	| MessageInitShape<O>
+	| ((
+			request: MessageShape<I>,
+			context: HandlerContext,
+	  ) => MessageInitShape<O> | Promise<MessageInitShape<O>>);
+
+export interface UnaryStub<I extends DescMessage> extends StubHandle {
+	/** Requests received so far, decoded. */
+	readonly requests: readonly MessageShape<I>[];
+	/** The next request this stub receives (or already received and nobody took). */
+	next(options?: { readonly timeout?: number }): Promise<MessageShape<I>>;
+}
+
+/**
+ * How a test-driven stream ended: cleanly, with an error status (`failed`),
+ * reset by the test (`cut`), or let go of by the page (`cancelled`).
+ */
+export type StreamEnd = ResponseEnd | "failed";
+
+export interface StreamCall<I extends DescMessage, O extends DescMessage> {
+	readonly request: MessageShape<I>;
+	readonly requestHeaders: Headers;
+	/** The protocol the page called with; undefined for an unidentified call. */
+	readonly protocol: RpcProtocol | undefined;
+	/**
+	 * Send a message. Messages go out in order; this resolves once the
+	 * message is written, and rejects with `CLOSED` when the stream ended
+	 * before it was.
+	 */
+	send(message: MessageInitShape<O>): Promise<void>;
+	/** End with OK. Resolves once the stream is over. */
+	end(): Promise<void>;
+	/** End with an error status. Resolves once the stream is over. */
+	fail(code: Code, message?: string): Promise<void>;
+	/**
+	 * Reset the connection mid-stream: no status, no trailer — what a network
+	 * drop looks like to the client. Recorded as a `cut` fault, not a status.
+	 */
+	cut(): Promise<void>;
+	readonly closed: Promise<StreamEnd>;
+}
+
+export interface StreamStub<I extends DescMessage, O extends DescMessage>
+	extends StubHandle {
+	/** The next call the page opens (or already opened and nobody took). */
+	next(options?: { readonly timeout?: number }): Promise<StreamCall<I, O>>;
+	readonly calls: readonly StreamCall<I, O>[];
+	/** Send to every open call. */
+	broadcast(message: MessageInitShape<O>): Promise<void>;
+}
+
+/**
+ * A call held at the network boundary until the test decides. Each decision
+ * resolves once it is carried out, so `calls()` right after one sees it; the
+ * first decision stands and later ones do nothing.
+ */
+export interface HeldCall<I extends DescMessage, O extends DescMessage> {
+	readonly request: MessageShape<I> | undefined;
+	readonly view: HttpRequestView;
+	/**
+	 * Let it go on: to the next rule that matches it, and to the real backend
+	 * when there is none.
+	 */
+	release(): Promise<void>;
+	/** Answer it with this message. */
+	reply(message: MessageInitShape<O>): Promise<void>;
+	/** Answer it with an error status. */
+	fail(code: Code, message?: string): Promise<void>;
+	/** Fail it at the network level. */
+	abort(error?: AbortErrorCode): Promise<void>;
+}
+
+export interface HoldStub<I extends DescMessage, O extends DescMessage>
+	extends StubHandle {
+	next(options?: { readonly timeout?: number }): Promise<HeldCall<I, O>>;
+	readonly calls: readonly HeldCall<I, O>[];
+	/**
+	 * Stop holding: every call held so far goes on, and so does every later
+	 * one. A call already decided stays decided.
+	 */
+	releaseAll(): Promise<void>;
+}
+
+/** One recorded RPC, reassembled from its frames. */
+export interface RpcCall<I extends DescMessage, O extends DescMessage> {
+	readonly correlation: string;
+	/**
+	 * Who made the call: `page`, `test` for a drive client, `network` for a
+	 * client outside the browser calling a served fake. Undefined when the
+	 * request never read as an RPC.
+	 */
+	readonly caller: FrameSource | undefined;
+	/**
+	 * Who answered: `stub`, `network` for the real backend, `server` for a
+	 * served fake. Undefined while nobody has.
+	 */
+	readonly answeredBy: FrameSource | undefined;
+	/** The page that made the call (`p1`, ...); undefined for a drive client's. */
+	readonly page: string | undefined;
+	/** Its browser context (`c1`, ...); undefined for a drive client's. */
+	readonly context: string | undefined;
+	readonly protocol: RpcProtocol | undefined;
+	/** The first request message. */
+	readonly request: MessageShape<I> | undefined;
+	readonly requests: readonly MessageShape<I>[];
+	readonly responses: readonly MessageShape<O>[];
+	/** Undefined while the call is open, and when it ended in a fault. Code 0 is OK. */
+	readonly status:
+		| { readonly code: number; readonly message: string }
+		| undefined;
+	/**
+	 * Why the call ended without a status: `abort` (a stub failed it), `cut`
+	 * (the test reset the stream), `cancelled` (the page let go), `network`
+	 * (the connection to the real backend failed).
+	 */
+	readonly fault: string | undefined;
+	readonly frames: readonly Frame[];
+}
+
+export interface ClientOptions {
+	/** Absolute, or a path resolved against the stage's base URL. */
+	readonly baseURL?: string;
+	readonly protocol?: RpcProtocol;
+	/** Protobuf binary (default) or JSON on the wire. */
+	readonly binary?: boolean;
+	/** Sent with every call that does not set the header itself. */
+	readonly headers?: Readonly<Record<string, string>>;
+	/**
+	 * Share a browser context's cookie jar: its cookies go out on the call, so
+	 * the call is made as the signed-in page, and the cookies a response sets
+	 * — an error response included — are kept in it. Pass the context.
+	 * Defaults to the first attached context; `null` uses none.
+	 */
+	readonly session?: CookieJarPort | null;
+	/** Accept self-signed certificates (dev servers). */
+	readonly ignoreHttpsErrors?: boolean;
+}
+
+export interface StandaloneClientOptions
+	extends Omit<ClientOptions, "baseURL" | "session"> {
+	readonly baseURL: string;
+	readonly session?: CookieJarPort;
+}
+
+export interface ServeOptions {
+	/** 0, the default, picks a free port. A fixed port fails loudly when taken. */
+	readonly port?: number;
+	readonly host?: string;
+	/** Protocols served. Default all three. */
+	readonly protocols?: readonly RpcProtocol[];
+	/**
+	 * HTTP/2 (h2c). Required by native gRPC clients; an HTTP/1.1-only client
+	 * (grpc-web, Connect over 1.1) needs it off. Default: on when `protocols`
+	 * includes grpc.
+	 */
+	readonly http2?: boolean;
+}
+
+export interface RpcServer {
+	readonly url: string;
+	readonly port: number;
+	close(): Promise<void>;
+}
+
+export interface ConnectApi {
+	/**
+	 * Stub a whole service, or the methods of it that `impl` defines. A
+	 * method a browser cannot call (client or bidirectional streaming) is
+	 * refused: `serve()` is where those are faked.
+	 */
+	service<S extends DescService>(
+		service: S,
+		impl: Partial<ServiceImpl<S>>,
+		options?: StubOptions,
+	): Promise<StubHandle>;
+	/** Stub one unary method with a message or a function of the request. */
+	unary<I extends DescMessage, O extends DescMessage>(
+		method: DescMethodUnary<I, O>,
+		reply: UnaryReply<I, O>,
+		options?: StubOptions<I>,
+	): Promise<UnaryStub<I>>;
+	/** Stub one server-streaming method and drive it from the test. */
+	stream<I extends DescMessage, O extends DescMessage>(
+		method: DescMethodServerStreaming<I, O>,
+		options?: StubOptions<I>,
+	): Promise<StreamStub<I, O>>;
+	/** Answer every call to `method` with an error status. */
+	fail<I extends DescMessage>(
+		method: DescMethod & { readonly input: I },
+		code: Code,
+		message?: string,
+		options?: StubOptions<I>,
+	): Promise<StubHandle>;
+	/** Fail every call to `method` at the network level. */
+	abort<I extends DescMessage>(
+		method: DescMethod & { readonly input: I },
+		options?: StubOptions<I> & { readonly error?: AbortErrorCode },
+	): Promise<StubHandle>;
+	/** Hold calls until the test releases, answers or aborts each one. */
+	hold<I extends DescMessage, O extends DescMessage>(
+		method: DescMethodUnary<I, O> | DescMethodServerStreaming<I, O>,
+		options?: HoldOptions<I>,
+	): Promise<HoldStub<I, O>>;
+	/** Record and decode calls to this service without answering them. */
+	record(service: DescService): Promise<StubHandle>;
+	/** Every recorded call to `method`, oldest first. */
+	calls<I extends DescMessage, O extends DescMessage>(
+		method: DescMethod & { readonly input: I; readonly output: O },
+	): Promise<RpcCall<I, O>[]>;
+	/** A typed client for the real backend, signed in as the page. */
+	client<S extends DescService>(service: S, options?: ClientOptions): Client<S>;
+	/**
+	 * Serve stubs on a port of their own, for clients outside the browser — a
+	 * native gRPC client, a backend service under test. Calls are recorded.
+	 */
+	serve(
+		routes: (router: ConnectRouter) => void,
+		options?: ServeOptions,
+	): Promise<RpcServer>;
+}

package/src/features/rest/index.ts

@@ -0,0 +1,23 @@
+export { rest } from "./lib/create-rest.js";
+export type { ReplyInit } from "./lib/reply.js";
+export {
+	abort,
+	bytes,
+	delay,
+	empty,
+	json,
+	passthrough,
+	text,
+} from "./lib/reply.js";
+export type {
+	RestApi,
+	RestCall,
+	RestMethod,
+	RestOptions,
+	RestPath,
+	RestReply,
+	RestRequest,
+	RestResolver,
+	RestRoute,
+	RestRouteOptions,
+} from "./model/types.js";

package/src/features/rest/lib/calls.ts

@@ -0,0 +1,31 @@
+import type { Frame } from "../../../entities/frame/index.js";
+import type { RestCall } from "../model/types.js";
+
+/**
+ * Pair each recorded request with how it ended. One call per exchange,
+ * oldest first; a frame with no correlation is an exchange of its own.
+ */
+export function assembleCalls(frames: readonly Frame[]): RestCall[] {
+	const byCall = new Map<string, { request?: Frame; end?: Frame }>();
+	for (const frame of frames) {
+		const key = frame.correlation ?? `#${frame.seq}`;
+		const entry = byCall.get(key) ?? {};
+		if (frame.kind === "request") entry.request = frame;
+		else entry.end = frame;
+		byCall.set(key, entry);
+	}
+	const calls: RestCall[] = [];
+	for (const [correlation, { request, end }] of byCall) {
+		if (request === undefined) continue;
+		const status = end?.meta["status"];
+		calls.push({
+			correlation,
+			method: String(request.meta["method"]),
+			url: String(request.meta["url"]),
+			request,
+			response: end?.kind === "response" ? end : undefined,
+			status: typeof status === "number" ? status : undefined,
+		});
+	}
+	return calls;
+}

package/src/features/rest/lib/create-rest.ts

@@ -0,0 +1,169 @@
+import {
+	definePlugin,
+	type HttpOutcome,
+	type HttpRequestView,
+	type WirePlugin,
+} from "../../../entities/plugin/index.js";
+import { createArrivals } from "../../../shared/lib/async/index.js";
+import type {
+	RestApi,
+	RestMethod,
+	RestOptions,
+	RestReply,
+	RestRequest,
+} from "../model/types.js";
+import { assembleCalls } from "./calls.js";
+import { compilePath } from "./path.js";
+
+/**
+ * REST and other plain HTTP: routes by method and path with `:params`, replies
+ * built from small helpers, faults, and recording of the real responses.
+ */
+export function rest(options: RestOptions = {}): WirePlugin<"rest", RestApi> {
+	return definePlugin({
+		name: "rest",
+		scope: "Rest",
+		setup(context) {
+			const { name } = context;
+			/** The record rule being added, once: every context gets it. */
+			let recording: Promise<unknown> | undefined;
+
+			const toOutcome = async (reply: RestReply): Promise<HttpOutcome> => {
+				switch (reply.kind) {
+					case "response":
+						return {
+							type: "fulfill",
+							status: reply.status,
+							headers: reply.headers,
+							...(reply.body === undefined ? {} : { body: reply.body }),
+						};
+					case "passthrough":
+						return { type: "fallback" };
+					case "abort":
+						return { type: "abort", error: reply.error };
+					case "delay":
+						await context.clock.sleep(reply.ms);
+						return toOutcome(reply.reply);
+				}
+			};
+
+			const on: RestApi["on"] = async (
+				method,
+				path,
+				resolver,
+				routeOptions = {},
+			) => {
+				const matcher = compilePath(path, options.baseURL);
+				// Own, enumerable fields: a request spreads and prints whole.
+				const toRequest = (view: HttpRequestView): RestRequest => ({
+					get correlation() {
+						return view.correlation;
+					},
+					method: view.method,
+					url: view.url,
+					headers: view.headers,
+					page: view.page,
+					context: view.context,
+					resourceType: view.resourceType,
+					body: view.body,
+					text: view.text,
+					json: view.json,
+					// The rule's URL predicate is this matcher, so it matched.
+					params: matcher.match(view.url) as Record<string, string>,
+					query: view.url.searchParams,
+				});
+				const label = `${method} ${String(path)}`;
+				const requests = createArrivals<RestRequest>({
+					clock: context.clock,
+					label: `${label} request`,
+				});
+				const { match } = routeOptions;
+				const rule = await context.http.add({
+					protocol: name,
+					label,
+					url: (url) => matcher.match(url) !== undefined,
+					...(method === "*" ? {} : { method }),
+					...(routeOptions.times === undefined
+						? {}
+						: { times: routeOptions.times }),
+					...(match === undefined
+						? {}
+						: { match: (view) => match(toRequest(view)) }),
+					handle: async (view) => {
+						const request = toRequest(view);
+						requests.push(request);
+						return toOutcome(
+							typeof resolver === "function"
+								? await resolver(request)
+								: resolver,
+						);
+					},
+				});
+				return {
+					get hits() {
+						return rule.hits;
+					},
+					get requests() {
+						return requests.items;
+					},
+					next: (waitOptions) => requests.next(waitOptions),
+					remove: () => rule.remove(),
+				};
+			};
+
+			const verb =
+				(method: RestMethod): RestApi["get"] =>
+				(path, resolver, routeOptions) =>
+					on(method, path, resolver, routeOptions);
+
+			const api: RestApi = {
+				on,
+				get: verb("GET"),
+				post: verb("POST"),
+				put: verb("PUT"),
+				patch: verb("PATCH"),
+				delete: verb("DELETE"),
+				async calls(filter = {}) {
+					await context.sync();
+					const matcher =
+						filter.path === undefined
+							? undefined
+							: compilePath(filter.path, options.baseURL);
+					const wanted = filter.method?.toUpperCase();
+					return assembleCalls(
+						context.timeline.frames({ protocol: name }),
+					).filter(
+						(call) =>
+							(wanted === undefined || wanted === call.method) &&
+							(matcher === undefined ||
+								matcher.match(new URL(call.url)) !== undefined),
+					);
+				},
+			};
+
+			return {
+				api,
+				async attach() {
+					if (options.record === undefined || options.record === false) return;
+					const base = compilePath(`${options.baseURL ?? ""}/**`, undefined);
+					recording ??= context.http
+						.add({
+							protocol: name,
+							label: "record",
+							url:
+								options.record === true
+									? (url) => base.match(url) !== undefined
+									: options.record,
+							handle: () => ({ type: "fallback" }),
+						})
+						.catch((error: unknown) => {
+							// The router took the rule back: the next attach adds it again.
+							recording = undefined;
+							throw error;
+						});
+					await recording;
+				},
+			};
+		},
+	});
+}

package/src/features/rest/lib/path.ts

@@ -0,0 +1,70 @@
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import { globSource } from "../../../shared/lib/match/index.js";
+import type { RestPath } from "../model/types.js";
+
+export interface PathMatcher {
+	/** The `:name` params when `url` matches, undefined when it does not. */
+	match(url: URL): Record<string, string> | undefined;
+}
+
+/**
+ * `/rooms/:id/files/*` against a URL's path, or — for a pattern that starts
+ * with a scheme — against origin plus path. The glob is the one every other
+ * pattern of the library takes (`*` one segment, `**` any number, none
+ * included, `{a,b}` either), plus `:name` params. The query never takes
+ * part: a route for `/search` should answer `/search?q=x`.
+ */
+export function compilePath(
+	path: RestPath,
+	baseURL: string | undefined,
+): PathMatcher {
+	if (path instanceof RegExp)
+		return {
+			match(url) {
+				path.lastIndex = 0;
+				const found = path.exec(url.pathname);
+				return found === null ? undefined : { ...found.groups };
+			},
+		};
+	if (path.includes("?"))
+		// It would compile, and then never match anything.
+		throw new WirestageError(
+			"INVALID_ARGUMENT",
+			`route "${path}" names a query, and a route matches the path alone: drop the "?…" and check \`request.query\` in the resolver or in \`match\``,
+		);
+	const full = joinBase(baseURL, path);
+	const absolute = /^[a-z][a-z\d+.-]*:\/\//i.test(full);
+	const { source, params: keys } = globSource(full, { params: true });
+	const pattern = new RegExp(`^${source}/?$`);
+	return {
+		match(url) {
+			const subject = absolute ? `${url.origin}${url.pathname}` : url.pathname;
+			const found = pattern.exec(subject);
+			if (found === null) return undefined;
+			const params: Record<string, string> = {};
+			keys.forEach((key, index) => {
+				params[key] = decode(found[index + 1] as string);
+			});
+			return params;
+		},
+	};
+}
+
+/**
+ * A path segment, percent-decoded. A malformed escape is kept as it came:
+ * this runs for every request of the context, and must not throw for one
+ * odd URL.
+ */
+function decode(segment: string): string {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return segment;
+	}
+}
+
+function joinBase(baseURL: string | undefined, path: string): string {
+	if (baseURL === undefined || /^[a-z][a-z\d+.-]*:\/\//i.test(path))
+		return path;
+	return `${baseURL.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}

package/src/features/rest/lib/reply.ts

@@ -0,0 +1,74 @@
+import type { AbortErrorCode } from "../../../entities/plugin/index.js";
+import type { RestReply } from "../model/types.js";
+
+export interface ReplyInit {
+	readonly status?: number;
+	readonly headers?: Readonly<Record<string, string>>;
+}
+
+const response = (
+	body: Uint8Array | string | undefined,
+	contentType: string | undefined,
+	init: ReplyInit,
+	defaultStatus: number,
+): RestReply => ({
+	kind: "response",
+	status: init.status ?? defaultStatus,
+	headers: {
+		...(contentType === undefined ? {} : { "content-type": contentType }),
+		...init.headers,
+	},
+	...(body === undefined ? {} : { body }),
+});
+
+/** A JSON body. A bigint field (protobuf int64) is written as a string. */
+export function json(value: unknown, init: ReplyInit = {}): RestReply {
+	return response(
+		JSON.stringify(value, (_key, v: unknown) =>
+			typeof v === "bigint" ? v.toString() : v,
+		),
+		"application/json",
+		init,
+		200,
+	);
+}
+
+export function text(value: string, init: ReplyInit = {}): RestReply {
+	return response(value, "text/plain; charset=utf-8", init, 200);
+}
+
+export function bytes(
+	value: Uint8Array,
+	init: ReplyInit & { readonly contentType?: string } = {},
+): RestReply {
+	return response(
+		value,
+		init.contentType ?? "application/octet-stream",
+		init,
+		200,
+	);
+}
+
+/** No body. 204 unless `status` says otherwise. */
+export function empty(init: ReplyInit = {}): RestReply {
+	return response(undefined, undefined, init, 204);
+}
+
+/**
+ * Decline to answer: the request goes on to the next route that matches it,
+ * and to the real server when there is none. A route that only watches —
+ * `route.next()`, `route.requests` — answers with this.
+ */
+export function passthrough(): RestReply {
+	return { kind: "passthrough" };
+}
+
+/** Fail the request at the network level, as a dropped connection would. */
+export function abort(error: AbortErrorCode = "failed"): RestReply {
+	return { kind: "abort", error };
+}
+
+/** Answer `reply`, `ms` later. (Not named `then`, so a reply never looks like a thenable.) */
+export function delay(ms: number, reply: RestReply): RestReply {
+	return { kind: "delay", ms, reply };
+}