@heojeongbo/wirestage 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,132 @@
+import type {
+	DescMessage,
+	DescMethod,
+	DescMethodServerStreaming,
+	DescMethodUnary,
+	MessageInitShape,
+	MessageShape,
+} from "@bufbuild/protobuf";
+
+import type {
+	AbortErrorCode,
+	HttpOutcome,
+	PluginContext,
+} from "../../../entities/plugin/index.js";
+import {
+	createArrivals,
+	createDeferred,
+} from "../../../shared/lib/async/index.js";
+import type {
+	HeldCall,
+	HoldOptions,
+	HoldStub,
+	StubHandle,
+	StubOptions,
+} from "../model/types.js";
+import { endpointOf, type Recorder } from "./recorder.js";
+import type { AnyImpl, RpcRules } from "./rules.js";
+import { failingImpl, handleOf } from "./stubs.js";
+
+/** Fail every call to a method at the network level. */
+export async function stubAbort<I extends DescMessage>(
+	rules: RpcRules,
+	recorder: Recorder,
+	method: DescMethod & { readonly input: I },
+	options: StubOptions<I> & { readonly error?: AbortErrorCode },
+): Promise<StubHandle> {
+	const error = options.error ?? "failed";
+	return handleOf(
+		await rules.add({
+			method,
+			label: `abort ${endpointOf(method)}`,
+			options,
+			respond(view) {
+				recorder.fault(rules.callOf(view), method, "abort", { error });
+				return { type: "abort", error };
+			},
+		}),
+	);
+}
+
+/**
+ * Hold calls at the network boundary until the test decides each one. The
+ * returned `abandon` lets go of whatever is still held, for the stage's
+ * disposal: a route left undecided would keep its request open for good.
+ */
+export async function stubHold<I extends DescMessage, O extends DescMessage>(
+	context: PluginContext,
+	rules: RpcRules,
+	recorder: Recorder,
+	method: DescMethodUnary<I, O> | DescMethodServerStreaming<I, O>,
+	options: HoldOptions<I>,
+	pending: Set<() => void>,
+): Promise<HoldStub<I, O>> {
+	const calls = createArrivals<HeldCall<I, O>>({
+		clock: context.clock,
+		label: `${endpointOf(method)} held call`,
+	});
+	const rule = await rules.add({
+		method,
+		label: `hold ${endpointOf(method)}`,
+		options,
+		observe: true,
+		async respond(view, [request]) {
+			const decision =
+				createDeferred<() => HttpOutcome | Promise<HttpOutcome>>();
+			const carried = createDeferred<void>();
+			/** The first decision stands; each resolves once it is carried out. */
+			const decide = (make: () => HttpOutcome | Promise<HttpOutcome>) => {
+				decision.resolve(make);
+				return carried.promise;
+			};
+			const aborted = (error: AbortErrorCode) => () => {
+				recorder.fault(rules.callOf(view), method, "abort", { error });
+				return { type: "abort", error } as const;
+			};
+			const answered = (impl: AnyImpl) => () =>
+				rules.answer(rules.handler(method, impl), method, view);
+			const abandon = () => void decide(aborted("aborted"));
+			pending.add(abandon);
+			calls.push({
+				request: request as MessageShape<I> | undefined,
+				view,
+				release: () => decide(() => ({ type: "fallback" })),
+				reply: (message: MessageInitShape<O>) =>
+					decide(
+						answered(
+							(method.methodKind === "server_streaming"
+								? async function* () {
+										yield message;
+									}
+								: async () => message) as AnyImpl,
+						),
+					),
+				fail: (code, message) =>
+					decide(answered(failingImpl(method, code, message))),
+				abort: (error) => decide(aborted(error ?? "failed")),
+			});
+			try {
+				return await (await decision.promise)();
+			} finally {
+				pending.delete(abandon);
+				carried.resolve();
+			}
+		},
+	});
+	return {
+		...handleOf(rule),
+		get hits() {
+			return rule.hits;
+		},
+		next: (waitOptions) => calls.next(waitOptions),
+		get calls() {
+			return calls.items;
+		},
+		async releaseAll() {
+			// Removed first: a call on its way in as this runs is not the
+			// rule's any more, and goes straight on instead of being held.
+			await rule.remove();
+			await Promise.all(calls.items.map((call) => call.release()));
+		},
+	};
+}

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

@@ -0,0 +1,321 @@
+import { gunzipSync } from "node:zlib";
+
+import {
+	type DescMessage,
+	fromBinary,
+	fromJsonString,
+	type JsonReadOptions,
+	type MessageShape,
+} from "@bufbuild/protobuf";
+import { Code } from "@connectrpc/connect";
+import {
+	codeFromString,
+	codeFromHttpStatus as connectCodeFromHttpStatus,
+} from "@connectrpc/connect/protocol-connect";
+import { codeFromHttpStatus as grpcCodeFromHttpStatus } from "@connectrpc/connect/protocol-grpc";
+
+import type {
+	HttpRequestView,
+	PassthroughResponse,
+} from "../../../entities/plugin/index.js";
+import {
+	concatBytes,
+	fromBase64,
+	utf8,
+} from "../../../shared/lib/bytes/index.js";
+import {
+	decodeEnvelopes,
+	EnvelopeFlag,
+	parseTrailerBlock,
+} from "../../../shared/lib/envelope/index.js";
+import type { RpcProtocol } from "../model/types.js";
+
+/** How one request (and so its response) is encoded on the wire. */
+export interface WireFormat {
+	readonly protocol: RpcProtocol;
+	/** Protobuf binary, or JSON. */
+	readonly binary: boolean;
+	/** gRPC-web-text: the whole body is base64. */
+	readonly base64: boolean;
+	/** Length-prefixed envelopes (every protocol's streaming form). */
+	readonly enveloped: boolean;
+}
+
+/**
+ * Read the format off a request, the way a Connect server negotiates it.
+ * Undefined means "not an RPC this plugin understands" — a rule then falls
+ * through instead of mangling, say, a REST call that shares the path prefix.
+ */
+export function detectFormat(
+	request: Pick<HttpRequestView, "method" | "url" | "headers">,
+): WireFormat | undefined {
+	const contentType = (request.headers["content-type"] ?? "")
+		.split(";")[0]
+		?.trim()
+		.toLowerCase();
+	if (contentType?.startsWith("application/grpc-web-text"))
+		return {
+			protocol: "grpc-web",
+			binary: !contentType.endsWith("+json"),
+			base64: true,
+			enveloped: true,
+		};
+	if (contentType?.startsWith("application/grpc-web"))
+		return {
+			protocol: "grpc-web",
+			binary: !contentType.endsWith("+json"),
+			base64: false,
+			enveloped: true,
+		};
+	if (contentType?.startsWith("application/grpc"))
+		return {
+			protocol: "grpc",
+			binary: !contentType.endsWith("+json"),
+			base64: false,
+			enveloped: true,
+		};
+	if (contentType?.startsWith("application/connect+"))
+		return {
+			protocol: "connect",
+			binary: contentType === "application/connect+proto",
+			base64: false,
+			enveloped: true,
+		};
+	if (contentType === "application/proto" || contentType === "application/json")
+		return {
+			protocol: "connect",
+			binary: contentType === "application/proto",
+			base64: false,
+			enveloped: false,
+		};
+	// Connect's GET form for side-effect-free methods carries the message in
+	// the query string and sends no content type at all.
+	if (
+		request.method === "GET" &&
+		request.url.searchParams.get("connect") === "v1"
+	)
+		return {
+			protocol: "connect",
+			binary: request.url.searchParams.get("encoding") !== "json",
+			base64: false,
+			enveloped: false,
+		};
+	return undefined;
+}
+
+export interface RpcStatus {
+	/** 0 is OK; otherwise the gRPC / Connect code number. */
+	readonly code: number;
+	readonly message: string;
+}
+
+export interface DecodedBody {
+	/** Message payloads, decompressed when the encoding is gzip. */
+	readonly messages: readonly Uint8Array[];
+	readonly status: RpcStatus | undefined;
+}
+
+const OK: RpcStatus = { code: 0, message: "" };
+
+/** The request's messages, from its body or (Connect GET) its query. */
+export function decodeRequestBody(
+	format: WireFormat,
+	request: Pick<HttpRequestView, "url" | "headers" | "body">,
+): Uint8Array[] {
+	if (!format.enveloped) {
+		const query = request.url.searchParams;
+		if (query.get("connect") === "v1") {
+			const message = query.get("message") ?? "";
+			return [
+				query.get("base64") === "1"
+					? fromBase64(message.replaceAll("-", "+").replaceAll("_", "/"))
+					: new TextEncoder().encode(message),
+			];
+		}
+		return [request.body()];
+	}
+	const body = format.base64
+		? fromBase64Stream(request.body())
+		: request.body();
+	return dataEnvelopes(
+		body,
+		request.headers[
+			format.protocol === "connect"
+				? "connect-content-encoding"
+				: "grpc-encoding"
+		],
+	);
+}
+
+/** Messages and status from a response the real backend sent. */
+export function decodeResponseBody(
+	format: WireFormat,
+	response: PassthroughResponse,
+): DecodedBody {
+	const headers = response.headers;
+	const raw = response.body ?? new Uint8Array(0);
+	if (!format.enveloped) {
+		if (response.status !== 200)
+			return { messages: [], status: connectError(raw, response.status) };
+		// A 200 that is not a message is something on the way — a proxy's
+		// sign-in page, say — and a Connect client reports it as an error.
+		const contentType = headers["content-type"] ?? "";
+		if (!/^application\/(proto|json)\b/i.test(contentType))
+			return {
+				messages: [],
+				status: {
+					code: Code.Unknown,
+					message: `unexpected content type "${contentType}"`,
+				},
+			};
+		return { messages: [raw], status: OK };
+	}
+	const body = format.base64 ? fromBase64Stream(raw) : raw;
+	const { envelopes } = decodeEnvelopes(body);
+	const encoding =
+		headers[
+			format.protocol === "connect"
+				? "connect-content-encoding"
+				: "grpc-encoding"
+		];
+	const messages: Uint8Array[] = [];
+	let status: RpcStatus | undefined;
+	for (const envelope of envelopes) {
+		if (
+			format.protocol === "connect" &&
+			envelope.flags & EnvelopeFlag.endStream
+		)
+			status = endStream(inflate(envelope.flags, envelope.data, encoding));
+		else if (envelope.flags & EnvelopeFlag.trailer)
+			status = grpcStatus(parseTrailerBlock(envelope.data));
+		else messages.push(inflate(envelope.flags, envelope.data, encoding));
+	}
+	// A trailers-only response carries the status in the headers instead.
+	if (status === undefined && headers["grpc-status"] !== undefined)
+		status = grpcStatus(headers);
+	// No status anywhere and not a 200: a gateway answered, not the server.
+	// The client maps the HTTP status to a code, and so does the record.
+	if (status === undefined && response.status !== 200)
+		status = {
+			code:
+				format.protocol === "connect"
+					? connectCodeFromHttpStatus(response.status)
+					: grpcCodeFromHttpStatus(response.status),
+			message: `HTTP ${response.status}`,
+		};
+	return { messages, status };
+}
+
+/** Parse a message payload with the request's format. */
+export function parseMessage<Desc extends DescMessage>(
+	schema: Desc,
+	bytes: Uint8Array,
+	binary: boolean,
+	jsonOptions?: Partial<JsonReadOptions>,
+): MessageShape<Desc> {
+	return binary
+		? fromBinary(schema, bytes)
+		: fromJsonString(schema, utf8(bytes), {
+				ignoreUnknownFields: true,
+				...jsonOptions,
+			});
+}
+
+/**
+ * Connect's `{ "code": "not_found", "message": "..." }` error body. A body
+ * that is not one came from something on the way, and the HTTP status is all
+ * there is to go by — which is how a Connect client reads it too.
+ */
+export function connectError(body: Uint8Array, httpStatus: number): RpcStatus {
+	try {
+		const status = errorStatus(JSON.parse(utf8(body)));
+		if (status !== undefined) return status;
+	} catch {
+		// Not JSON at all.
+	}
+	return {
+		code: connectCodeFromHttpStatus(httpStatus),
+		message: `HTTP ${httpStatus}`,
+	};
+}
+
+/** The status in a Connect error object; undefined when it names no code. */
+function errorStatus(value: unknown): RpcStatus | undefined {
+	const error = (typeof value === "object" && value !== null ? value : {}) as {
+		readonly code?: unknown;
+		readonly message?: unknown;
+	};
+	const code =
+		typeof error.code === "string" ? codeFromString(error.code) : undefined;
+	if (code === undefined) return undefined;
+	return {
+		code,
+		message: typeof error.message === "string" ? error.message : "",
+	};
+}
+
+function grpcStatus(fields: Readonly<Record<string, string>>): RpcStatus {
+	const code = Number(fields["grpc-status"]);
+	return {
+		code: Number.isInteger(code) ? code : Code.Unknown,
+		message: safeDecodeURIComponent(fields["grpc-message"] ?? ""),
+	};
+}
+
+/** Connect's end-of-stream JSON: `{}` for OK, `{ "error": {...} }` otherwise. */
+function endStream(data: Uint8Array): RpcStatus {
+	try {
+		const parsed = JSON.parse(utf8(data)) as { readonly error?: unknown };
+		if (parsed.error === undefined) return OK;
+		return (
+			errorStatus(parsed.error) ?? {
+				code: Code.Unknown,
+				message: "end-of-stream error with no code",
+			}
+		);
+	} catch {
+		return { code: Code.Unknown, message: "malformed end-of-stream message" };
+	}
+}
+
+/**
+ * gRPC-web-text: base64, but not one base64 string. A server encodes each
+ * chunk it flushes on its own, padding included, so a stream is several
+ * encodings end to end, and decoding it as one stops at the first padding.
+ */
+function fromBase64Stream(body: Uint8Array): Uint8Array {
+	const parts = utf8(body).match(/[^=]+=*/g) ?? [];
+	return concatBytes(parts.map((part) => fromBase64(part)));
+}
+
+function dataEnvelopes(
+	body: Uint8Array,
+	encoding: string | undefined,
+): Uint8Array[] {
+	return decodeEnvelopes(body)
+		.envelopes.filter(
+			(e) =>
+				!(e.flags & EnvelopeFlag.trailer) &&
+				!(e.flags & EnvelopeFlag.endStream),
+		)
+		.map((e) => inflate(e.flags, e.data, encoding));
+}
+
+/** Decompress a compressed envelope when the encoding is gzip; otherwise as is. */
+function inflate(
+	flags: number,
+	data: Uint8Array,
+	encoding: string | undefined,
+): Uint8Array {
+	if (!(flags & EnvelopeFlag.compressed) || encoding !== "gzip") return data;
+	return new Uint8Array(gunzipSync(data));
+}
+
+/** gRPC percent-encodes `grpc-message`; a malformed escape must not throw. */
+function safeDecodeURIComponent(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}

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

@@ -0,0 +1,48 @@
+import type { DescService } from "@bufbuild/protobuf";
+
+import type { HttpRuleHandle } from "../../../entities/plugin/index.js";
+import type { StubHandle } from "../model/types.js";
+import { endpointOf } from "./recorder.js";
+import type { RpcRules } from "./rules.js";
+
+/**
+ * Record and decode a service's calls without answering them: the request
+ * as it leaves, the real backend's messages and status as they come back,
+ * or the fault when the connection fails.
+ *
+ * A call a stub answers is recorded by that stub. Where this rule sits among
+ * the stubs does not matter: a request is one exchange however many rules
+ * see it, so it lands once either way.
+ */
+export async function recordService(
+	rules: RpcRules,
+	service: DescService,
+): Promise<StubHandle> {
+	const added: HttpRuleHandle[] = [];
+	for (const method of service.methods) {
+		// A page cannot call the others; there is nothing of theirs to record.
+		if (
+			method.methodKind !== "unary" &&
+			method.methodKind !== "server_streaming"
+		)
+			continue;
+		added.push(
+			await rules.add({
+				method,
+				label: `record ${endpointOf(method)}`,
+				options: {},
+				anyProtocol: true,
+				observe: true,
+				respond: () => ({ type: "fallback" }),
+			}),
+		);
+	}
+	return {
+		get hits() {
+			return added.reduce((sum, rule) => sum + rule.hits, 0);
+		},
+		async remove() {
+			await Promise.all(added.map((rule) => rule.remove()));
+		},
+	};
+}