@heojeongbo/wirestage 0.0.0-stage → 0.1.0

package/src/shared/lib/async/arrivals.ts

@@ -0,0 +1,91 @@
+import type { Clock } from "../clock/index.js";
+import { WirestageError } from "../errors/index.js";
+
+export interface ArrivalWaitOptions {
+	/** Milliseconds to wait. Defaults to the value given at creation. */
+	readonly timeout?: number;
+}
+
+export interface Arrivals<T> {
+	push(item: T): void;
+	/**
+	 * The next item `next` has not returned yet, waiting for one if needed.
+	 * Items that arrived before the call count: a test that asks for the stream
+	 * the page opened during `goto` must not miss it by asking too late.
+	 */
+	next(options?: ArrivalWaitOptions): Promise<T>;
+	readonly items: readonly T[];
+	readonly latest: T | undefined;
+}
+
+export interface ArrivalsOptions {
+	readonly clock: Clock;
+	/** Names the thing being waited for in the TIMEOUT message. */
+	readonly label: string;
+	readonly timeout?: number;
+	/**
+	 * What the waiter knows about why nothing arrived, added to the TIMEOUT
+	 * message: "the page never asked" and "it asked, and the answer got
+	 * lost" call for different fixes.
+	 */
+	readonly hint?: () => string | undefined;
+}
+
+/** Things that show up over time — connections, calls, messages — and a way to await the next. */
+export function createArrivals<T>(options: ArrivalsOptions): Arrivals<T> {
+	const items: T[] = [];
+	let cursor = 0;
+	const waiters = new Set<() => void>();
+	const defaultTimeout = options.timeout ?? 5_000;
+
+	/** Resolves true on the next push, false when `ms` pass first. */
+	const pushedWithin = async (ms: number): Promise<boolean> => {
+		const abort = new AbortController();
+		let resolvePushed!: (pushed: boolean) => void;
+		const pushed = new Promise<boolean>((resolve) => {
+			resolvePushed = resolve;
+		});
+		const wake = () => resolvePushed(true);
+		waiters.add(wake);
+		const expired = options.clock
+			.sleep(ms, abort.signal)
+			.then(() => false)
+			.catch(() => true);
+		const result = await Promise.race([pushed, expired]);
+		waiters.delete(wake);
+		abort.abort();
+		return result;
+	};
+
+	return {
+		push(item) {
+			items.push(item);
+			for (const wake of [...waiters]) wake();
+		},
+		async next(waitOptions = {}) {
+			const timeout = waitOptions.timeout ?? defaultTimeout;
+			const deadline = options.clock.now() + timeout;
+			// A loop, not a single wait: two callers woken by one push race for
+			// one item, and the loser has to go back to waiting.
+			for (;;) {
+				if (cursor < items.length) return items[cursor++] as T;
+				const remaining = deadline - options.clock.now();
+				if (remaining <= 0 || !(await pushedWithin(remaining))) {
+					if (cursor < items.length) return items[cursor++] as T;
+					const hint = options.hint?.();
+					throw new WirestageError(
+						"TIMEOUT",
+						`no ${options.label} arrived within ${timeout} ms (${items.length} seen so far)${hint === undefined ? "" : `; ${hint}`}`,
+						{ details: { label: options.label, timeout, seen: items.length } },
+					);
+				}
+			}
+		},
+		get items() {
+			return items;
+		},
+		get latest() {
+			return items.at(-1);
+		},
+	};
+}

package/src/shared/lib/async/async-queue.ts

@@ -0,0 +1,101 @@
+import { WirestageError } from "../errors/index.js";
+import { createDeferred, type Deferred } from "./deferred.js";
+
+export interface AsyncQueue<T> extends AsyncIterable<T> {
+	/**
+	 * Queue a value. Resolves once the consumer has taken it and come back
+	 * for the next — for a stream being written, once the value is on the
+	 * wire. Rejects with `CLOSED` when the queue was closed first, or when
+	 * the consumer went away before getting through the value.
+	 */
+	push(value: T): Promise<void>;
+	/** End iteration once the queued values are consumed. */
+	close(): void;
+	/** End iteration with `reason` once the queued values are consumed. */
+	fail(reason: unknown): void;
+	readonly closed: boolean;
+	/** Values pushed but not consumed yet. */
+	readonly size: number;
+}
+
+interface Entry<T> {
+	readonly value: T;
+	readonly done: Deferred<void>;
+}
+
+/**
+ * A single-consumer queue that a test pushes into and a stream implementation
+ * iterates. Values pushed before the consumer starts are kept, so a test may
+ * queue the first messages before the page has even opened the stream.
+ */
+export function createAsyncQueue<T>(): AsyncQueue<T> {
+	const entries: Entry<T>[] = [];
+	let waiter: (() => void) | undefined;
+	let closed = false;
+	let failure: { readonly reason: unknown } | undefined;
+	const wake = () => {
+		const w = waiter;
+		waiter = undefined;
+		w?.();
+	};
+	const lost = () =>
+		new WirestageError(
+			"CLOSED",
+			"the queue closed before the value got through",
+		);
+	return {
+		push(value) {
+			const done = createDeferred<void>();
+			if (closed) done.reject(lost());
+			else {
+				entries.push({ value, done });
+				wake();
+			}
+			return done.promise;
+		},
+		close() {
+			closed = true;
+			wake();
+		},
+		fail(reason) {
+			if (!closed) failure = { reason };
+			closed = true;
+			wake();
+		},
+		get closed() {
+			return closed;
+		},
+		get size() {
+			return entries.length;
+		},
+		async *[Symbol.asyncIterator]() {
+			/** The value handed out last: through once the consumer is back. */
+			let out: Deferred<void> | undefined;
+			try {
+				for (;;) {
+					out?.resolve();
+					out = undefined;
+					const entry = entries.shift();
+					if (entry !== undefined) {
+						out = entry.done;
+						yield entry.value;
+						continue;
+					}
+					if (closed) {
+						if (failure) throw failure.reason;
+						return;
+					}
+					await new Promise<void>((resolve) => {
+						waiter = resolve;
+					});
+				}
+			} finally {
+				// The consumer stopped early: what it held, and what it never
+				// reached, did not get through.
+				closed = true;
+				out?.reject(lost());
+				for (const entry of entries.splice(0)) entry.done.reject(lost());
+			}
+		},
+	};
+}

package/src/shared/lib/async/deferred.ts

@@ -0,0 +1,38 @@
+export interface Deferred<T> {
+	readonly promise: Promise<T>;
+	resolve(value: T): void;
+	reject(reason: unknown): void;
+	readonly settled: boolean;
+}
+
+/**
+ * A promise with its resolvers. Settling twice is a no-op, so racing paths
+ * (a client disconnect and an explicit end) can both try without a guard.
+ */
+export function createDeferred<T>(): Deferred<T> {
+	let settled = false;
+	let resolveFn!: (value: T) => void;
+	let rejectFn!: (reason: unknown) => void;
+	const promise = new Promise<T>((resolve, reject) => {
+		resolveFn = resolve;
+		rejectFn = reject;
+	});
+	// A deferred nobody awaits must not surface as an unhandled rejection.
+	promise.catch(() => {});
+	return {
+		promise,
+		resolve(value) {
+			if (settled) return;
+			settled = true;
+			resolveFn(value);
+		},
+		reject(reason) {
+			if (settled) return;
+			settled = true;
+			rejectFn(reason);
+		},
+		get settled() {
+			return settled;
+		},
+	};
+}

package/src/shared/lib/async/index.ts

@@ -0,0 +1,11 @@
+export type {
+	Arrivals,
+	ArrivalsOptions,
+	ArrivalWaitOptions,
+} from "./arrivals.js";
+export { createArrivals } from "./arrivals.js";
+export type { AsyncQueue } from "./async-queue.js";
+export { createAsyncQueue } from "./async-queue.js";
+export type { Deferred } from "./deferred.js";
+export { createDeferred } from "./deferred.js";
+export { runAll } from "./run-all.js";

package/src/shared/lib/async/run-all.ts

@@ -0,0 +1,19 @@
+/**
+ * Run every step in order even when one fails, then throw what failed: the
+ * one error, or an `AggregateError` of several. For teardown, where stopping
+ * at the first failure leaves everything after it — a server, a route —
+ * behind.
+ */
+export async function runAll(steps: readonly (() => unknown)[]): Promise<void> {
+	const failures: unknown[] = [];
+	for (const step of steps) {
+		try {
+			await step();
+		} catch (error) {
+			failures.push(error);
+		}
+	}
+	if (failures.length === 1) throw failures[0];
+	if (failures.length > 1)
+		throw new AggregateError(failures, "several teardown steps failed");
+}

package/src/shared/lib/bytes/bytes.ts

@@ -0,0 +1,53 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Anything the wire can carry: binary views or text (encoded as UTF-8). */
+export type BytesLike = Uint8Array | ArrayBuffer | ArrayBufferView | string;
+
+/**
+ * View `value` as bytes without copying when it already is binary.
+ *
+ * A `Buffer` is a `Uint8Array`, so Playwright's buffers pass straight through;
+ * copying every recorded payload would double the memory a long test holds.
+ */
+export function toBytes(value: BytesLike): Uint8Array {
+	if (typeof value === "string") return encoder.encode(value);
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+
+/** Decode UTF-8. Invalid sequences become U+FFFD instead of throwing. */
+export function utf8(bytes: Uint8Array): string {
+	return decoder.decode(bytes);
+}
+
+/** Join chunks into one array. One chunk is returned as is. */
+export function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+	if (chunks.length === 1) return chunks[0] as Uint8Array;
+	let length = 0;
+	for (const chunk of chunks) length += chunk.byteLength;
+	const out = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return out;
+}
+
+export function toBase64(bytes: Uint8Array): string {
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString(
+		"base64",
+	);
+}
+
+export function fromBase64(text: string): Uint8Array {
+	const buffer = Buffer.from(text, "base64");
+	return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+
+/** A Node Buffer over the same memory, for APIs that insist on Buffer. */
+export function toBuffer(bytes: Uint8Array): Buffer {
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}

package/src/shared/lib/bytes/index.ts

@@ -0,0 +1,9 @@
+export type { BytesLike } from "./bytes.js";
+export {
+	concatBytes,
+	fromBase64,
+	toBase64,
+	toBuffer,
+	toBytes,
+	utf8,
+} from "./bytes.js";

package/src/shared/lib/clock/clock.ts

@@ -0,0 +1,114 @@
+/**
+ * Time, as a port. Waits, timeouts and frame timestamps all go through it, so a
+ * unit test can drive a 5-second timeout in microseconds with a manual clock
+ * instead of sleeping.
+ */
+export interface Clock {
+	/** Milliseconds since the Unix epoch, with sub-millisecond precision. */
+	now(): number;
+	/** Resolve after `ms`, or reject with the signal's reason if it aborts first. */
+	sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+
+/** The longest delay a Node timer takes: 2^31 - 1 ms, about 24.8 days. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * Wall-clock time built from `performance`, not `Date.now()`: it has
+ * sub-millisecond resolution, and a page's `performance.timeOrigin + now()` is on
+ * the same scale, so page frames and Node frames sort together.
+ */
+export function createSystemClock(): Clock {
+	return {
+		now: () => performance.timeOrigin + performance.now(),
+		sleep: (ms, signal) =>
+			new Promise<void>((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(signal.reason);
+					return;
+				}
+				const onAbort = () => {
+					clearTimeout(timer);
+					reject(signal?.reason);
+				};
+				const timer = setTimeout(
+					() => {
+						signal?.removeEventListener("abort", onAbort);
+						resolve();
+					},
+					// A longer delay overflows the timer to 1 ms: "wait forever"
+					// (`timeout: Infinity`) would time out at once.
+					Math.min(ms, MAX_TIMER_MS),
+				);
+				signal?.addEventListener("abort", onAbort, { once: true });
+			}),
+	};
+}
+
+export interface ManualClock extends Clock {
+	/**
+	 * Move time forward, resolving every sleep that falls due, earliest first.
+	 * Awaiting it lets the continuations of those sleeps run before it returns.
+	 */
+	advance(ms: number): Promise<void>;
+	/** Sleeps that have not fallen due yet. */
+	readonly pending: number;
+}
+
+interface Timer {
+	readonly due: number;
+	readonly resolve: () => void;
+}
+
+/** A clock that only moves when told to. For tests of timing behavior. */
+export function createManualClock(start = 0): ManualClock {
+	let time = start;
+	let timers: Timer[] = [];
+	const settle = async () => {
+		// Several turns: a resolved sleep's continuation may itself await
+		// another promise before reaching the code under test.
+		for (let i = 0; i < 10; i++) await Promise.resolve();
+	};
+	return {
+		now: () => time,
+		sleep(ms, signal) {
+			return new Promise<void>((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(signal.reason);
+					return;
+				}
+				const timer: Timer = {
+					due: time + ms,
+					resolve: () => {
+						signal?.removeEventListener("abort", onAbort);
+						resolve();
+					},
+				};
+				const onAbort = () => {
+					timers = timers.filter((t) => t !== timer);
+					reject(signal?.reason);
+				};
+				signal?.addEventListener("abort", onAbort, { once: true });
+				timers.push(timer);
+			});
+		},
+		async advance(ms) {
+			const target = time + ms;
+			for (;;) {
+				const next = timers
+					.filter((t) => t.due <= target)
+					.sort((a, b) => a.due - b.due)[0];
+				if (next === undefined) break;
+				timers = timers.filter((t) => t !== next);
+				time = next.due;
+				next.resolve();
+				await settle();
+			}
+			time = target;
+			await settle();
+		},
+		get pending() {
+			return timers.length;
+		},
+	};
+}

package/src/shared/lib/clock/index.ts

@@ -0,0 +1,2 @@
+export type { Clock, ManualClock } from "./clock.js";
+export { createManualClock, createSystemClock } from "./clock.js";

package/src/shared/lib/cookies/index.ts

@@ -0,0 +1,2 @@
+export type { CookieInit } from "./set-cookie.js";
+export { parseSetCookie } from "./set-cookie.js";

package/src/shared/lib/cookies/set-cookie.ts

@@ -0,0 +1,105 @@
+/** A cookie the way a browser context stores one: Playwright's `addCookies` shape. */
+export interface CookieInit {
+	readonly name: string;
+	readonly value: string;
+	/** A leading dot covers subdomains, as Playwright spells it; none is host-only. */
+	readonly domain: string;
+	readonly path: string;
+	/** Seconds since the epoch; absent for a session cookie. */
+	readonly expires?: number;
+	readonly httpOnly: boolean;
+	readonly secure: boolean;
+	readonly sameSite?: "Strict" | "Lax" | "None";
+}
+
+/** The latest expiry a browser context accepts: 9999-12-31, in seconds. */
+const MAX_EXPIRES = 253_402_300_799;
+
+/**
+ * One `Set-Cookie` line, stored the way a browser would store it for a response
+ * from `url` (RFC 6265 §5.2-5.3): `Domain` covers subdomains and no `Domain`
+ * is host-only, no `Path` is the request path's directory, and `Max-Age` beats
+ * `Expires`. Undefined for a line a browser would ignore: one with no cookie
+ * name, or with a `Domain` the responding host does not belong to.
+ */
+export function parseSetCookie(
+	line: string,
+	url: string,
+	now: number = Date.now(),
+): CookieInit | undefined {
+	const [pair = "", ...attributes] = line.split(";");
+	const eq = pair.indexOf("=");
+	const name = eq < 0 ? "" : pair.slice(0, eq).trim();
+	if (name === "") return undefined;
+	const target = new URL(url);
+	let domain = target.hostname;
+	let path = defaultPath(target.pathname);
+	let expires: number | undefined;
+	let maxAge: number | undefined;
+	let httpOnly = false;
+	let secure = false;
+	let sameSite: CookieInit["sameSite"];
+	for (const attribute of attributes) {
+		const at = attribute.indexOf("=");
+		const key = (at < 0 ? attribute : attribute.slice(0, at))
+			.trim()
+			.toLowerCase();
+		const value = at < 0 ? "" : attribute.slice(at + 1).trim();
+		if (key === "domain" && value !== "") {
+			const covered = value.replace(/^\./, "").toLowerCase();
+			const host = target.hostname.toLowerCase();
+			// A server may not set a cookie for a site it is not part of.
+			if (host !== covered && !host.endsWith(`.${covered}`)) return undefined;
+			domain = `.${covered}`;
+		} else if (key === "path" && value.startsWith("/")) path = value;
+		// A date names its month; a bare number is not one, though
+		// `Date.parse` would take "1" for the year 2001.
+		else if (
+			key === "expires" &&
+			/[a-z]{3}/i.test(value) &&
+			!Number.isNaN(Date.parse(value))
+		)
+			expires = Math.floor(Date.parse(value) / 1000);
+		else if (key === "max-age" && /^-?\d+$/.test(value)) maxAge = Number(value);
+		else if (key === "httponly") httpOnly = true;
+		else if (key === "secure") secure = true;
+		else if (key === "samesite") sameSite = sameSiteOf(value) ?? sameSite;
+	}
+	const wanted =
+		maxAge === undefined ? expires : Math.floor(now / 1000) + maxAge;
+	// A context takes a positive timestamp only: one second past the epoch
+	// is "long expired", which is how a server deletes a cookie.
+	const until =
+		wanted === undefined
+			? undefined
+			: Math.min(Math.max(wanted, 1), MAX_EXPIRES);
+	return {
+		name,
+		value: pair.slice(eq + 1).trim(),
+		domain,
+		path,
+		...(until === undefined ? {} : { expires: until }),
+		httpOnly,
+		secure,
+		...(sameSite === undefined ? {} : { sameSite }),
+	};
+}
+
+function sameSiteOf(value: string): CookieInit["sameSite"] {
+	switch (value.toLowerCase()) {
+		case "strict":
+			return "Strict";
+		case "lax":
+			return "Lax";
+		case "none":
+			return "None";
+		default:
+			return undefined;
+	}
+}
+
+/** RFC 6265 §5.1.4: the request path up to, and not including, its last "/". */
+function defaultPath(pathname: string): string {
+	const last = pathname.lastIndexOf("/");
+	return last <= 0 ? "/" : pathname.slice(0, last);
+}

package/src/shared/lib/envelope/envelope.ts

@@ -0,0 +1,133 @@
+import { concatBytes, utf8 } from "../bytes/index.js";
+
+/**
+ * The length-prefixed message framing that gRPC, gRPC-web and Connect
+ * streaming share: one flag byte, a 4-byte big-endian length, the payload.
+ *
+ * Every hand-written gRPC-web stub ends up re-deriving this; getting the
+ * trailer bit or the length endianness wrong produces a response the client
+ * rejects with an error that names neither.
+ */
+export const EnvelopeFlag = {
+	/** gRPC / gRPC-web / Connect: the payload is compressed. */
+	compressed: 0b0000_0001,
+	/** Connect streaming: the payload is the end-of-stream JSON. */
+	endStream: 0b0000_0010,
+	/** gRPC-web: the payload is the trailer block, not a message. */
+	trailer: 0b1000_0000,
+} as const;
+
+export interface Envelope {
+	readonly flags: number;
+	readonly data: Uint8Array;
+}
+
+const HEADER = 5;
+
+export function encodeEnvelope(flags: number, data: Uint8Array): Uint8Array {
+	const out = new Uint8Array(HEADER + data.byteLength);
+	out[0] = flags;
+	new DataView(out.buffer).setUint32(1, data.byteLength, false);
+	out.set(data, HEADER);
+	return out;
+}
+
+export function encodeEnvelopes(envelopes: readonly Envelope[]): Uint8Array {
+	return concatBytes(envelopes.map((e) => encodeEnvelope(e.flags, e.data)));
+}
+
+export interface EnvelopeReader {
+	/** Feed bytes; returns every envelope they complete, in order. */
+	push(chunk: Uint8Array): Envelope[];
+	/** Bytes held back because they do not complete an envelope yet. */
+	readonly buffered: number;
+}
+
+/**
+ * Incremental reader for a byte stream that may split an envelope anywhere,
+ * including inside the 5-byte header — which is exactly how HTTP chunking
+ * delivers a long server stream.
+ *
+ * Chunks that do not complete an envelope are kept as they came and joined
+ * only once it is complete, so a large message arriving in small chunks is
+ * copied once, not once per chunk.
+ */
+export function createEnvelopeReader(): EnvelopeReader {
+	let pending: Uint8Array[] = [];
+	let buffered = 0;
+
+	/** Whether the pending chunks hold at least one whole envelope. */
+	const complete = (): boolean => {
+		if (buffered < HEADER) return false;
+		// The header may itself straddle chunks: gather just those five bytes.
+		const header = new Uint8Array(HEADER);
+		let filled = 0;
+		for (const chunk of pending) {
+			const part = chunk.subarray(0, HEADER - filled);
+			header.set(part, filled);
+			filled += part.byteLength;
+			if (filled === HEADER) break;
+		}
+		const length = new DataView(header.buffer).getUint32(1, false);
+		return buffered >= HEADER + length;
+	};
+
+	return {
+		push(chunk) {
+			pending.push(chunk);
+			buffered += chunk.byteLength;
+			if (!complete()) return [];
+			const bytes = concatBytes(pending);
+			const out: Envelope[] = [];
+			let offset = 0;
+			while (bytes.byteLength - offset >= HEADER) {
+				const view = new DataView(
+					bytes.buffer,
+					bytes.byteOffset + offset,
+					HEADER,
+				);
+				const length = view.getUint32(1, false);
+				if (bytes.byteLength - offset - HEADER < length) break;
+				out.push({
+					flags: view.getUint8(0),
+					data: bytes.subarray(offset + HEADER, offset + HEADER + length),
+				});
+				offset += HEADER + length;
+			}
+			const rest = bytes.subarray(offset);
+			pending = rest.byteLength === 0 ? [] : [rest];
+			buffered = rest.byteLength;
+			return out;
+		},
+		get buffered() {
+			return buffered;
+		},
+	};
+}
+
+/** Decode a complete body. `rest` holds a truncated tail, if any. */
+export function decodeEnvelopes(bytes: Uint8Array): {
+	readonly envelopes: Envelope[];
+	readonly rest: number;
+} {
+	const reader = createEnvelopeReader();
+	const envelopes = reader.push(bytes);
+	return { envelopes, rest: reader.buffered };
+}
+
+/**
+ * Parse a gRPC-web trailer block (`name: value\r\n` lines). Names are
+ * lower-cased; HTTP/1.1 header names are case-insensitive and gRPC-web
+ * servers disagree on the spelling.
+ */
+export function parseTrailerBlock(data: Uint8Array): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const line of utf8(data).split(/\r?\n/)) {
+		const colon = line.indexOf(":");
+		if (colon <= 0) continue;
+		out[line.slice(0, colon).trim().toLowerCase()] = line
+			.slice(colon + 1)
+			.trim();
+	}
+	return out;
+}

package/src/shared/lib/envelope/index.ts

@@ -0,0 +1,9 @@
+export type { Envelope, EnvelopeReader } from "./envelope.js";
+export {
+	createEnvelopeReader,
+	decodeEnvelopes,
+	EnvelopeFlag,
+	encodeEnvelope,
+	encodeEnvelopes,
+	parseTrailerBlock,
+} from "./envelope.js";