@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/src/features/connect/lib/serve.ts

@@ -0,0 +1,114 @@
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttp2Server } from "node:http2";
+import type { Server } from "node:net";
+
+import type { DescMethod, DescService } from "@bufbuild/protobuf";
+import {
+	type ConnectRouter,
+	createContextValues,
+	type ServiceImpl,
+} from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+
+import { listen } from "../../../shared/api/http-server/index.js";
+import type { RpcServer, ServeOptions } from "../model/types.js";
+import { detectFormat } from "./protocol.js";
+import { kCall, type Recorder, recordingImpl } from "./recorder.js";
+
+export interface ServeDeps {
+	readonly recorder: Recorder;
+	readonly correlation: () => string;
+}
+
+/**
+ * Route registrations, with every implementation wrapped for recording.
+ * The caller writes ordinary Connect routes; nothing about recording leaks
+ * into its code.
+ */
+function recordingRouter(
+	router: ConnectRouter,
+	deps: ServeDeps,
+): ConnectRouter {
+	// Bound to the object it came from: a class instance or a stateful fake
+	// reads its own fields, and Connect would have called it that way.
+	const wrap = (method: DescMethod, impl: unknown, owner?: unknown) =>
+		recordingImpl(
+			method,
+			(impl as (...args: never[]) => unknown).bind(owner) as never,
+			deps.recorder,
+		);
+	const proxy: ConnectRouter = {
+		get handlers() {
+			return router.handlers;
+		},
+		service(service, implementation, options) {
+			const wrapped: Record<string, unknown> = {};
+			for (const method of (service as DescService).methods) {
+				const impl = (implementation as Record<string, unknown>)[
+					method.localName
+				];
+				if (impl !== undefined)
+					wrapped[method.localName] = wrap(method, impl, implementation);
+			}
+			router.service(
+				service,
+				wrapped as Partial<ServiceImpl<typeof service>>,
+				options,
+			);
+			return proxy;
+		},
+		rpc(method, impl, options) {
+			router.rpc(method, wrap(method, impl) as typeof impl, options);
+			return proxy;
+		},
+	};
+	return proxy;
+}
+
+/** Serve Connect routes on a port of their own, recording every call. */
+export async function serveRoutes(
+	routes: (router: ConnectRouter) => void,
+	options: ServeOptions,
+	deps: ServeDeps,
+): Promise<RpcServer> {
+	const protocols = new Set(
+		options.protocols ?? ["connect", "grpc-web", "grpc"],
+	);
+	const handler = connectNodeAdapter({
+		connect: protocols.has("connect"),
+		grpcWeb: protocols.has("grpc-web"),
+		grpc: protocols.has("grpc"),
+		routes: (router) => routes(recordingRouter(router, deps)),
+		contextValues: (request) =>
+			createContextValues().set(kCall, {
+				correlation: deps.correlation(),
+				// A client outside the browser, answered by the served fake.
+				from: "network",
+				answeredBy: "server",
+				// Node always sets method and url on a server request; the types do
+				// not say so. A Connect GET carries no content type at all.
+				rpcProtocol: detectFormat({
+					method: String(request.method),
+					url: new URL(String(request.url), "http://localhost"),
+					headers: {
+						"content-type": String(request.headers["content-type"] ?? ""),
+					},
+				})?.protocol,
+			}),
+	});
+	const http2 = options.http2 ?? protocols.has("grpc");
+	const server: Server = http2
+		? createHttp2Server(handler)
+		: createHttpServer(handler);
+	const listening = await listen(server, {
+		name: "wirestage rpc server",
+		protocol: "http",
+		host: options.host,
+		port: options.port,
+	});
+	return {
+		url: listening.url,
+		port: listening.port,
+		close: () => listening.close(),
+	};
+}

package/src/features/connect/lib/status-of.ts

@@ -0,0 +1,20 @@
+import { ConnectError } from "@connectrpc/connect";
+
+/**
+ * The gRPC status a call ended with: 0 when it resolved, the server's code
+ * when it failed. For asserting a refusal without a try/catch:
+ *
+ *     expect(await statusOf(orders.cancel(ref))).toBe(Code.PermissionDenied);
+ *
+ * Anything that is not a `ConnectError` -- a bug in the test, say -- is
+ * rethrown rather than read as a status.
+ */
+export async function statusOf(call: Promise<unknown>): Promise<number> {
+	try {
+		await call;
+		return 0;
+	} catch (error) {
+		if (error instanceof ConnectError) return error.code;
+		throw error;
+	}
+}

package/src/features/connect/lib/stubs.ts

@@ -0,0 +1,282 @@
+import type {
+	DescMessage,
+	DescMethod,
+	DescMethodServerStreaming,
+	DescMethodUnary,
+	DescService,
+	MessageInitShape,
+	MessageShape,
+} from "@bufbuild/protobuf";
+import {
+	type Code,
+	Code as Codes,
+	ConnectError,
+	type HandlerContext,
+	type ServiceImpl,
+} from "@connectrpc/connect";
+
+import type {
+	HttpRuleHandle,
+	PluginContext,
+} from "../../../entities/plugin/index.js";
+import {
+	type Arrivals,
+	createArrivals,
+	createAsyncQueue,
+	createDeferred,
+} from "../../../shared/lib/async/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+import type {
+	StreamCall,
+	StreamEnd,
+	StreamStub,
+	StubHandle,
+	StubOptions,
+	UnaryReply,
+	UnaryStub,
+} from "../model/types.js";
+import { endpointOf, kCall, type Recorder } from "./recorder.js";
+import type { AnyImpl, RpcRules } from "./rules.js";
+
+export const handleOf = (rule: HttpRuleHandle): StubHandle => ({
+	get hits() {
+		return rule.hits;
+	},
+	remove: () => rule.remove(),
+});
+
+/** The status a stub fails a call with. */
+export const failure = (
+	code: Code,
+	message: string | undefined,
+): ConnectError => new ConnectError(message ?? `stubbed ${Codes[code]}`, code);
+
+/** An implementation that fails every call, for either kind a page can call. */
+export const failingImpl = (
+	method: DescMethod,
+	code: Code,
+	message: string | undefined,
+): AnyImpl =>
+	(method.methodKind === "server_streaming"
+		? async function* () {
+				yield* [];
+				throw failure(code, message);
+			}
+		: async () => {
+				throw failure(code, message);
+			}) as AnyImpl;
+
+/** One method answered by one implementation. */
+const stubMethod = <I extends DescMessage>(
+	rules: RpcRules,
+	method: DescMethod,
+	impl: AnyImpl,
+	options: StubOptions<I>,
+	label: string,
+): Promise<HttpRuleHandle> => {
+	const handler = rules.handler(method, impl);
+	return rules.add({
+		method,
+		label,
+		options,
+		respond: (view) => rules.answer(handler, method, view),
+	});
+};
+
+export async function stubService<S extends DescService>(
+	rules: RpcRules,
+	service: S,
+	impl: Partial<ServiceImpl<S>>,
+	options: StubOptions,
+): Promise<StubHandle> {
+	const added: HttpRuleHandle[] = [];
+	const remove = async () => {
+		await Promise.all(added.map((rule) => rule.remove()));
+	};
+	try {
+		for (const method of service.methods) {
+			const own = (impl as Record<string, AnyImpl | undefined>)[
+				method.localName
+			];
+			if (own !== undefined)
+				added.push(
+					await stubMethod(
+						rules,
+						method,
+						// A class instance or a stateful object: its methods need it.
+						own.bind(impl) as AnyImpl,
+						options,
+						`stub ${endpointOf(method)}`,
+					),
+				);
+		}
+	} catch (error) {
+		// All of the service or none of it.
+		await remove();
+		throw error;
+	}
+	if (added.length === 0)
+		throw new WirestageError(
+			"INVALID_ARGUMENT",
+			`stub for ${service.typeName} implements none of its methods`,
+		);
+	return {
+		get hits() {
+			return added.reduce((sum, rule) => sum + rule.hits, 0);
+		},
+		remove,
+	};
+}
+
+export async function stubUnary<I extends DescMessage, O extends DescMessage>(
+	context: PluginContext,
+	rules: RpcRules,
+	method: DescMethodUnary<I, O>,
+	reply: UnaryReply<I, O>,
+	options: StubOptions<I>,
+): Promise<UnaryStub<I>> {
+	const requests = createArrivals<MessageShape<I>>({
+		clock: context.clock,
+		label: `${endpointOf(method)} request`,
+	});
+	const impl = async (request: MessageShape<I>, handler: HandlerContext) => {
+		requests.push(request);
+		return typeof reply === "function" ? reply(request, handler) : reply;
+	};
+	const rule = await stubMethod(
+		rules,
+		method,
+		impl as AnyImpl,
+		options,
+		`unary ${endpointOf(method)}`,
+	);
+	return {
+		...handleOf(rule),
+		get hits() {
+			return rule.hits;
+		},
+		get requests() {
+			return requests.items;
+		},
+		next: (waitOptions) => requests.next(waitOptions),
+	};
+}
+
+export async function stubStream<I extends DescMessage, O extends DescMessage>(
+	context: PluginContext,
+	rules: RpcRules,
+	recorder: Recorder,
+	method: DescMethodServerStreaming<I, O>,
+	options: StubOptions<I>,
+	live: boolean,
+): Promise<StreamStub<I, O>> {
+	if (!live)
+		throw new WirestageError(
+			"UNSUPPORTED",
+			"stream() needs live streaming; it was configured as `buffered`",
+		);
+	/** Calls the stub took: each should become a stream. */
+	let taken = 0;
+	const calls: Arrivals<StreamCall<I, O>> = createArrivals({
+		clock: context.clock,
+		label: `${endpointOf(method)} stream`,
+		// The stub took the call, yet no stream came of it: the redirect to
+		// the stream server is what went missing.
+		hint: (): string | undefined =>
+			taken > calls.items.length
+				? `${taken - calls.items.length} call(s) matched but never reached the local stream server — see "Live streams" in docs/troubleshooting.md`
+				: undefined,
+	});
+	const impl = async function* (
+		request: MessageShape<I>,
+		handler: HandlerContext,
+	) {
+		const info = handler.values.get(kCall);
+		const queue = createAsyncQueue<MessageInitShape<O>>();
+		const closed = createDeferred<StreamEnd>();
+		/** Once the response itself is over, not merely decided. */
+		const over = async () => {
+			await info.over;
+		};
+		const call: StreamCall<I, O> = {
+			request,
+			requestHeaders: handler.requestHeader,
+			protocol: info.rpcProtocol,
+			send: (message) => queue.push(message),
+			async end() {
+				queue.close();
+				await over();
+			},
+			async fail(code, message) {
+				queue.fail(failure(code, message));
+				await over();
+			},
+			async cut() {
+				// Settled and recorded here, not by what follows: the connection
+				// resets asynchronously, after the queue has already ended, and
+				// the implementation returning then must not read as an OK.
+				closed.resolve("cut");
+				recorder.fault(info, method, "cut");
+				info.cut?.();
+				queue.close();
+				await over();
+			},
+			closed: closed.promise,
+		};
+		handler.signal.addEventListener("abort", () => {
+			if (closed.settled) return;
+			closed.resolve("cancelled");
+			recorder.fault(info, method, "cancelled", { by: "page" });
+			queue.close();
+		});
+		calls.push(call);
+		try {
+			for await (const message of queue) yield message;
+			closed.resolve("ended");
+		} catch (error) {
+			closed.resolve("failed");
+			throw error;
+		}
+	};
+	const handler = rules.handler(method, impl as AnyImpl);
+	const rule = await rules.add({
+		method,
+		label: `stream ${endpointOf(method)}`,
+		options,
+		respond(view) {
+			taken += 1;
+			return rules.answer(handler, method, view);
+		},
+	});
+	return {
+		...handleOf(rule),
+		get hits() {
+			return rule.hits;
+		},
+		next: (waitOptions) => calls.next(waitOptions),
+		get calls() {
+			return calls.items;
+		},
+		async broadcast(message) {
+			for (const call of calls.items) await call.send(message).catch(() => {});
+		},
+	};
+}
+
+export async function stubFailure<I extends DescMessage>(
+	rules: RpcRules,
+	method: DescMethod & { readonly input: I },
+	code: Code,
+	message: string | undefined,
+	options: StubOptions<I>,
+): Promise<StubHandle> {
+	return handleOf(
+		await stubMethod(
+			rules,
+			method,
+			failingImpl(method, code, message),
+			options,
+			`fail ${endpointOf(method)}`,
+		),
+	);
+}

package/src/features/connect/lib/universal.ts

@@ -0,0 +1,100 @@
+import type { ContextValues } from "@connectrpc/connect";
+import type {
+	UniversalServerRequest,
+	UniversalServerResponse,
+} from "@connectrpc/connect/protocol";
+
+import type {
+	HttpRequestView,
+	ResponseStream,
+} from "../../../entities/plugin/index.js";
+import { concatBytes } from "../../../shared/lib/bytes/index.js";
+import { WirestageError } from "../../../shared/lib/errors/index.js";
+
+/** A Playwright request, as the request Connect's handlers expect. */
+export function toUniversalRequest(
+	view: HttpRequestView,
+	contextValues: ContextValues,
+	signal: AbortSignal = new AbortController().signal,
+): UniversalServerRequest {
+	const body = view.body();
+	return {
+		httpVersion: "1.1",
+		url: view.url.href,
+		method: view.method,
+		header: new Headers(view.headers),
+		body: (async function* () {
+			if (body.byteLength > 0) yield body;
+		})(),
+		signal,
+		contextValues,
+	};
+}
+
+/**
+ * A response's headers as a plain record. `set-cookie` keeps every value,
+ * one per line, which is how a route and a Node response take several.
+ */
+function headersOf(response: UniversalServerResponse): Record<string, string> {
+	const headers: Record<string, string> = {};
+	response.header?.forEach((value, name) => {
+		headers[name] = value;
+	});
+	const cookies = response.header?.getSetCookie() ?? [];
+	if (cookies.length > 1) headers["set-cookie"] = cookies.join("\n");
+	return headers;
+}
+
+/**
+ * Connect and gRPC-web carry their trailers in the headers or the body; only
+ * native gRPC needs HTTP trailers, which neither a route nor the stream
+ * server sends — and which a browser could not have asked for anyway.
+ */
+function refuseTrailers(response: UniversalServerResponse): void {
+	let trailers = 0;
+	response.trailer?.forEach(() => {
+		trailers += 1;
+	});
+	if (trailers > 0)
+		throw new WirestageError(
+			"UNSUPPORTED",
+			"this response needs HTTP trailers (native gRPC), which a browser route cannot send; use serve() for gRPC clients",
+		);
+}
+
+export interface CollectedResponse {
+	readonly status: number;
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body: Uint8Array;
+}
+
+/** Read a handler's whole response, for `route.fulfill`. */
+export async function collectResponse(
+	response: UniversalServerResponse,
+): Promise<CollectedResponse> {
+	const chunks: Uint8Array[] = [];
+	for await (const chunk of response.body ?? []) chunks.push(chunk);
+	refuseTrailers(response);
+	return {
+		status: response.status,
+		headers: headersOf(response),
+		body: concatBytes(chunks),
+	};
+}
+
+/**
+ * Write a handler's response to an open stream as the handler produces it:
+ * the head with the first chunk, as a real Connect server sends it, and each
+ * message as soon as the implementation yields it.
+ */
+export async function pipeResponse(
+	response: UniversalServerResponse,
+	stream: ResponseStream,
+): Promise<void> {
+	stream.head(response.status, headersOf(response));
+	// A streaming handler always answers with a body, error trailers included.
+	for await (const chunk of response.body as AsyncIterable<Uint8Array>)
+		await stream.write(chunk);
+	refuseTrailers(response);
+	await stream.end();
+}