roxxie-proxy-u-prod 0.1.0

package/source/packages/roxxie-transport/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./binary.js";
+export * from "./config.js";
+export * from "./connection.js";
+export * from "./tracker.js";
+export * from "./transport.js";

package/source/packages/roxxie-transport/src/tracker.ts

@@ -0,0 +1,651 @@
+import {
+	CONTROL_LIMITS,
+	TRACKER_PATHS,
+	TRACKER_WEBSOCKET_PROTOCOLS,
+	assertBrowserServerMessage,
+	decodeControlJSON,
+	encodeControlJSON,
+	type BrowserCandidatesRequest,
+	type BrowserClientMessage,
+	type BrowserServerMessage,
+	type BrowserSessionOffer,
+	type CandidateNode,
+	type WebRTCAnswer,
+	type WebRTCOffer,
+} from "roxxie-transports-tracker-protocol";
+
+import {
+	parseTrackerBaseUrl,
+	type ConnectionTimeouts,
+	type TrackerDefinition,
+} from "./config.js";
+
+export const MAX_PENDING_TRACKER_REQUESTS = 32;
+const MAX_ICE_SERVERS_PER_NODE = 16;
+const MAX_URLS_PER_ICE_SERVER = 8;
+const MAX_ICE_URL_BYTES = 2_048;
+
+interface PendingRequest {
+	expectedType: "browser.candidates.result" | "browser.session.answer";
+	nodeId?: string;
+	resolve: (message: BrowserServerMessage) => void;
+	reject: (error: unknown) => void;
+	timer: ReturnType<typeof setTimeout>;
+	removeAbort?: () => void;
+}
+
+export interface TrackerClientDependencies {
+	fetch: typeof fetch;
+	createWebSocket: (url: URL, protocols: string[]) => WebSocket;
+}
+
+export interface TrackerSignaling {
+	requestCandidates(signal?: AbortSignal): Promise<readonly CandidateNode[]>;
+	requestSession(
+		nodeId: string,
+		offer: WebRTCOffer,
+		signal?: AbortSignal
+	): Promise<WebRTCAnswer>;
+	close(): void;
+}
+
+export class TrackerRequestError extends Error {
+	constructor(
+		message: string,
+		readonly code?: string
+	) {
+		super(message);
+		this.name = "TrackerRequestError";
+	}
+}
+
+function asError(value: unknown, fallback: string): Error {
+	return value instanceof Error
+		? value
+		: new Error(value === undefined ? fallback : String(value));
+}
+
+function abortError(signal?: AbortSignal): DOMException {
+	return new DOMException(
+		signal?.reason === undefined
+			? "The tracker request was aborted"
+			: String(signal.reason),
+		"AbortError"
+	);
+}
+
+function isAborted(signal?: AbortSignal): boolean {
+	return signal?.aborted === true;
+}
+
+function requestId(): string {
+	return `browser-${crypto.randomUUID()}`;
+}
+
+function endpoint(base: URL, path: string): URL {
+	return new URL(path, base);
+}
+
+function websocketEndpoint(base: URL): URL {
+	const result = endpoint(base, TRACKER_PATHS.browserWebSocket);
+	result.protocol = result.protocol === "https:" ? "wss:" : "ws:";
+	return result;
+}
+
+async function messageData(value: unknown): Promise<string | ArrayBuffer> {
+	if (typeof value === "string") {
+		if (value.length > CONTROL_LIMITS.maxMessageBytes) {
+			throw new Error("Tracker WebSocket message is too large");
+		}
+		return value;
+	}
+	if (value instanceof ArrayBuffer) {
+		if (value.byteLength > CONTROL_LIMITS.maxMessageBytes) {
+			throw new Error("Tracker WebSocket message is too large");
+		}
+		return value;
+	}
+	if (ArrayBuffer.isView(value)) {
+		if (value.byteLength > CONTROL_LIMITS.maxMessageBytes) {
+			throw new Error("Tracker WebSocket message is too large");
+		}
+		return new Uint8Array(
+			value.buffer,
+			value.byteOffset,
+			value.byteLength
+		).slice().buffer;
+	}
+	if (value instanceof Blob) {
+		if (value.size > CONTROL_LIMITS.maxMessageBytes) {
+			throw new Error("Tracker WebSocket message is too large");
+		}
+		return value.arrayBuffer();
+	}
+	throw new Error("Tracker sent an unsupported WebSocket message type");
+}
+
+async function boundedResponseBody(response: Response): Promise<ArrayBuffer> {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength !== null) {
+		if (!/^\d+$/u.test(contentLength)) {
+			throw new Error("Tracker returned an invalid Content-Length");
+		}
+		if (Number(contentLength) > CONTROL_LIMITS.maxMessageBytes) {
+			throw new Error("Tracker HTTP response is too large");
+		}
+	}
+	if (response.body === null) return new ArrayBuffer(0);
+
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > CONTROL_LIMITS.maxMessageBytes) {
+				void reader
+					.cancel("Tracker HTTP response is too large")
+					.catch(() => undefined);
+				throw new Error("Tracker HTTP response is too large");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const result = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return result.buffer;
+}
+
+function validateCandidateIceServers(
+	candidates: readonly CandidateNode[]
+): void {
+	for (const candidate of candidates) {
+		if (candidate.iceServers.length > MAX_ICE_SERVERS_PER_NODE) {
+			throw new Error(`Node ${candidate.nodeId} returned too many ICE servers`);
+		}
+		for (const server of candidate.iceServers) {
+			if (server === null || typeof server !== "object") {
+				throw new Error(
+					`Node ${candidate.nodeId} returned an invalid ICE server`
+				);
+			}
+			if (server.username !== undefined || server.credential !== undefined) {
+				throw new Error(
+					`Node ${candidate.nodeId} returned credentialed ICE configuration; TURN relays are disabled`
+				);
+			}
+			const values =
+				typeof server.urls === "string" ? [server.urls] : server.urls;
+			if (
+				!Array.isArray(values) ||
+				values.length === 0 ||
+				values.length > MAX_URLS_PER_ICE_SERVER
+			) {
+				throw new Error(`Node ${candidate.nodeId} returned invalid ICE URLs`);
+			}
+			for (const value of values) {
+				if (
+					typeof value !== "string" ||
+					value.length === 0 ||
+					new TextEncoder().encode(value).byteLength > MAX_ICE_URL_BYTES ||
+					!/^(?:stun|stuns):[^\s]+$/iu.test(value)
+				) {
+					throw new Error(
+						`Node ${candidate.nodeId} returned a non-STUN ICE URL; TURN relays are disabled`
+					);
+				}
+			}
+		}
+	}
+}
+
+export class RoxxieTrackerClient implements TrackerSignaling {
+	private readonly base: URL;
+	private readonly dependencies: TrackerClientDependencies;
+	private socket: WebSocket | undefined;
+	private socketPromise: Promise<WebSocket> | undefined;
+	private readonly pending = new Map<string, PendingRequest>();
+	private readonly httpControllers = new Set<AbortController>();
+	private messageQueue: Promise<void> = Promise.resolve();
+	private activeRequests = 0;
+	private closed = false;
+
+	constructor(
+		tracker: TrackerDefinition,
+		private readonly timeouts: ConnectionTimeouts,
+		dependencies: Partial<TrackerClientDependencies> = {}
+	) {
+		this.base = parseTrackerBaseUrl(tracker.url);
+		this.dependencies = {
+			// Firefox and some Chromium builds require the native fetch receiver to
+			// be their global object. Keeping `fetch` directly on this dependency
+			// object and invoking it as a method changes that receiver and makes the
+			// HTTPS signaling fallback fail with "Illegal invocation".
+			fetch:
+				dependencies.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+			createWebSocket:
+				dependencies.createWebSocket ??
+				((url, protocols) => new WebSocket(url, protocols)),
+		};
+	}
+
+	async requestCandidates(
+		signal?: AbortSignal
+	): Promise<readonly CandidateNode[]> {
+		return this.withRequestSlot(async () => {
+			const request: BrowserCandidatesRequest = {
+				type: "browser.candidates.request",
+				requestId: requestId(),
+			};
+			let response: BrowserServerMessage;
+			try {
+				response = await this.requestOverWebSocket(request, signal);
+			} catch (error) {
+				if (
+					this.closed ||
+					isAborted(signal) ||
+					error instanceof TrackerRequestError
+				) {
+					throw error;
+				}
+				response = await this.requestOverHTTP(request, signal);
+			}
+			if (response.type !== "browser.candidates.result") {
+				throw new Error("Tracker returned the wrong candidate response type");
+			}
+			validateCandidateIceServers(response.candidates);
+			return response.candidates;
+		});
+	}
+
+	async requestSession(
+		nodeId: string,
+		offer: WebRTCOffer,
+		signal?: AbortSignal
+	): Promise<WebRTCAnswer> {
+		return this.withRequestSlot(async () => {
+			const request: BrowserSessionOffer = {
+				type: "browser.session.offer",
+				requestId: requestId(),
+				nodeId,
+				offer,
+			};
+			let response: BrowserServerMessage;
+			try {
+				response = await this.requestOverWebSocket(request, signal);
+			} catch (error) {
+				if (
+					this.closed ||
+					isAborted(signal) ||
+					error instanceof TrackerRequestError
+				) {
+					throw error;
+				}
+				response = await this.requestOverHTTP(request, signal);
+			}
+			if (
+				response.type !== "browser.session.answer" ||
+				response.nodeId !== nodeId
+			) {
+				throw new Error("Tracker returned the wrong WebRTC session response");
+			}
+			return response.answer;
+		});
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		const error = new Error("Tracker client was closed");
+		this.rejectPending(error);
+		for (const controller of this.httpControllers) {
+			controller.abort("Tracker client was closed");
+		}
+		this.httpControllers.clear();
+		this.closeSocket(1000, "Client closed tracker signaling");
+	}
+
+	private async withRequestSlot<T>(operation: () => Promise<T>): Promise<T> {
+		if (this.activeRequests >= MAX_PENDING_TRACKER_REQUESTS) {
+			throw new TrackerRequestError(
+				`Tracker client allows at most ${MAX_PENDING_TRACKER_REQUESTS} concurrent requests`,
+				"CLIENT_CAPACITY"
+			);
+		}
+		this.activeRequests += 1;
+		try {
+			return await operation();
+		} finally {
+			this.activeRequests -= 1;
+		}
+	}
+
+	private async requestOverWebSocket(
+		request: BrowserClientMessage,
+		signal?: AbortSignal
+	): Promise<BrowserServerMessage> {
+		if (isAborted(signal)) throw abortError(signal);
+		const socket = await this.ensureSocket();
+		if (isAborted(signal)) throw abortError(signal);
+
+		return new Promise<BrowserServerMessage>((resolve, reject) => {
+			const cleanup = () => {
+				const pending = this.pending.get(request.requestId);
+				if (pending === undefined) return;
+				clearTimeout(pending.timer);
+				pending.removeAbort?.();
+				this.pending.delete(request.requestId);
+			};
+			const settleReject = (error: unknown) => {
+				cleanup();
+				reject(error);
+			};
+			const timer = setTimeout(
+				() =>
+					settleReject(
+						new Error(
+							`Tracker WebSocket request timed out after ${this.timeouts.signalingMs} ms`
+						)
+					),
+				this.timeouts.signalingMs
+			);
+			const pending: PendingRequest = {
+				expectedType:
+					request.type === "browser.candidates.request"
+						? "browser.candidates.result"
+						: "browser.session.answer",
+				...(request.type === "browser.session.offer"
+					? { nodeId: request.nodeId }
+					: {}),
+				resolve: (message) => {
+					cleanup();
+					resolve(message);
+				},
+				reject: settleReject,
+				timer,
+			};
+			if (signal !== undefined) {
+				const onAbort = () => settleReject(abortError(signal));
+				signal.addEventListener("abort", onAbort, { once: true });
+				pending.removeAbort = () =>
+					signal.removeEventListener("abort", onAbort);
+			}
+			this.pending.set(request.requestId, pending);
+			try {
+				socket.send(encodeControlJSON(request));
+			} catch (error) {
+				settleReject(error);
+			}
+		});
+	}
+
+	private async requestOverHTTP(
+		request: BrowserClientMessage,
+		signal?: AbortSignal
+	): Promise<BrowserServerMessage> {
+		if (this.closed) throw new Error("Tracker client is closed");
+		if (isAborted(signal)) throw abortError(signal);
+		const controller = new AbortController();
+		this.httpControllers.add(controller);
+		const onAbort = () => controller.abort(signal?.reason);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const timer = setTimeout(
+			() => controller.abort("Tracker request timed out"),
+			this.timeouts.signalingMs
+		);
+		try {
+			let url: URL;
+			let init: RequestInit;
+			if (request.type === "browser.candidates.request") {
+				url = endpoint(this.base, TRACKER_PATHS.browserCandidates);
+				url.searchParams.set("requestId", request.requestId);
+				init = {
+					method: "GET",
+					headers: { Accept: "application/json" },
+				};
+			} else {
+				url = endpoint(this.base, TRACKER_PATHS.browserSessions);
+				init = {
+					method: "POST",
+					headers: {
+						Accept: "application/json",
+						"Content-Type": "application/json",
+					},
+					body: encodeControlJSON(request),
+				};
+			}
+			let response: Response;
+			try {
+				response = await this.dependencies.fetch(url, {
+					...init,
+					cache: "no-store",
+					credentials: "omit",
+					signal: controller.signal,
+				});
+			} catch (error) {
+				if (controller.signal.aborted) {
+					throw isAborted(signal)
+						? abortError(signal)
+						: new Error(
+								`Tracker HTTP request timed out after ${this.timeouts.signalingMs} ms`,
+								{ cause: error }
+							);
+				}
+				throw error;
+			}
+			const parsed = decodeControlJSON(await boundedResponseBody(response));
+			assertBrowserServerMessage(parsed);
+			this.validateResponse(request, parsed);
+			if (!response.ok && parsed.type !== "browser.error") {
+				throw new Error(`Tracker HTTP request failed (${response.status})`);
+			}
+			return this.unwrapError(parsed);
+		} finally {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			this.httpControllers.delete(controller);
+		}
+	}
+
+	private async ensureSocket(): Promise<WebSocket> {
+		if (this.closed) throw new Error("Tracker client is closed");
+		if (this.socket?.readyState === WebSocket.OPEN) return this.socket;
+		if (this.socketPromise !== undefined) return this.socketPromise;
+
+		const attempt = this.openSocket();
+		this.socketPromise = attempt;
+		try {
+			return await attempt;
+		} finally {
+			if (this.socketPromise === attempt) this.socketPromise = undefined;
+		}
+	}
+
+	private async openSocket(): Promise<WebSocket> {
+		const socket = this.dependencies.createWebSocket(
+			websocketEndpoint(this.base),
+			[TRACKER_WEBSOCKET_PROTOCOLS.browser]
+		);
+		this.socket = socket;
+		socket.binaryType = "arraybuffer";
+
+		try {
+			await new Promise<void>((resolve, reject) => {
+				let settled = false;
+				const cleanup = () => {
+					clearTimeout(timer);
+					socket.removeEventListener("open", onOpen);
+					socket.removeEventListener("error", onError);
+					socket.removeEventListener("close", onClose);
+				};
+				const settle = (error?: Error) => {
+					if (settled) return;
+					settled = true;
+					cleanup();
+					if (error === undefined) resolve();
+					else reject(error);
+				};
+				const onOpen = () => {
+					if (socket.protocol !== TRACKER_WEBSOCKET_PROTOCOLS.browser) {
+						settle(new Error("Tracker selected an invalid WebSocket protocol"));
+						this.closeSocket(1002, "Invalid tracker protocol");
+						return;
+					}
+					settle();
+				};
+				const onError = () => settle(new Error("Tracker WebSocket failed"));
+				const onClose = () =>
+					settle(new Error("Tracker WebSocket closed before opening"));
+				const timer = setTimeout(() => {
+					settle(
+						new Error(
+							`Tracker WebSocket connection timed out after ${this.timeouts.signalingMs} ms`
+						)
+					);
+					this.closeSocket(4000, "Tracker connection timed out");
+				}, this.timeouts.signalingMs);
+				socket.addEventListener("open", onOpen);
+				socket.addEventListener("error", onError);
+				socket.addEventListener("close", onClose);
+			});
+		} catch (error) {
+			if (this.socket === socket) {
+				this.closeSocket(4000, "Tracker connection failed");
+			}
+			throw error;
+		}
+
+		if (this.closed) {
+			this.closeSocket(1000, "Tracker client closed");
+			throw new Error("Tracker client is closed");
+		}
+		socket.addEventListener("message", (event) => {
+			if (this.socket !== socket) return;
+			this.messageQueue = this.messageQueue
+				.then(async () => {
+					const data = await messageData(event.data);
+					if (this.socket === socket) this.handleSocketMessage(data);
+				})
+				.catch((error: unknown) => {
+					if (this.socket === socket) {
+						this.failSocket(asError(error, "Invalid tracker message"));
+					}
+				});
+		});
+		socket.addEventListener("close", () => {
+			if (this.socket !== socket) return;
+			this.socket = undefined;
+			this.rejectPending(new Error("Tracker WebSocket closed"));
+		});
+		socket.addEventListener("error", () => {
+			if (this.socket !== socket) return;
+			this.failSocket(new Error("Tracker WebSocket error"));
+		});
+		return socket;
+	}
+
+	private handleSocketMessage(data: string | ArrayBuffer): void {
+		let parsed: BrowserServerMessage;
+		try {
+			const decoded = decodeControlJSON(data);
+			assertBrowserServerMessage(decoded);
+			parsed = decoded;
+		} catch (error) {
+			throw new TrackerRequestError(
+				`Tracker returned invalid signaling data: ${asError(error, "invalid response").message}`,
+				"INVALID_RESPONSE"
+			);
+		}
+		const pending = this.pending.get(parsed.requestId);
+		if (pending === undefined) return;
+		if (parsed.type === "browser.error") {
+			pending.reject(new TrackerRequestError(parsed.message, parsed.code));
+			return;
+		}
+		if (parsed.type !== pending.expectedType) {
+			pending.reject(
+				new TrackerRequestError(
+					"Tracker returned an unexpected response type",
+					"INVALID_RESPONSE"
+				)
+			);
+			return;
+		}
+		if (
+			parsed.type === "browser.session.answer" &&
+			pending.nodeId !== parsed.nodeId
+		) {
+			pending.reject(
+				new TrackerRequestError(
+					"Tracker returned an answer for the wrong node",
+					"INVALID_RESPONSE"
+				)
+			);
+			return;
+		}
+		pending.resolve(parsed);
+	}
+
+	private validateResponse(
+		request: BrowserClientMessage,
+		response: BrowserServerMessage
+	): void {
+		if (response.requestId !== request.requestId) {
+			throw new Error("Tracker returned a mismatched request ID");
+		}
+		if (response.type === "browser.error") return;
+		if (
+			request.type === "browser.candidates.request" &&
+			response.type !== "browser.candidates.result"
+		) {
+			throw new Error("Tracker returned an unexpected candidate response");
+		}
+		if (
+			request.type === "browser.session.offer" &&
+			(response.type !== "browser.session.answer" ||
+				response.nodeId !== request.nodeId)
+		) {
+			throw new Error("Tracker returned an unexpected session response");
+		}
+	}
+
+	private unwrapError(message: BrowserServerMessage): BrowserServerMessage {
+		if (message.type === "browser.error") {
+			throw new TrackerRequestError(message.message, message.code);
+		}
+		return message;
+	}
+
+	private failSocket(error: Error): void {
+		this.rejectPending(error);
+		this.closeSocket(4000, "Tracker signaling failed");
+	}
+
+	private rejectPending(error: Error): void {
+		for (const pending of [...this.pending.values()]) pending.reject(error);
+	}
+
+	private closeSocket(code: number, reason: string): void {
+		const socket = this.socket;
+		this.socket = undefined;
+		if (
+			socket !== undefined &&
+			(socket.readyState === WebSocket.OPEN ||
+				socket.readyState === WebSocket.CONNECTING)
+		) {
+			try {
+				socket.close(code, reason.slice(0, 123));
+			} catch {
+				// The browser can reject close() while the constructor is still failing.
+			}
+		}
+	}
+}