@serverkgg/bridge 0.0.12 → 0.0.13

package/src/rcon/sourceRcon.test.ts

@@ -0,0 +1,308 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeRconCode, BridgeRconError } from "../core";
+import { sourceRcon } from "./sourceRcon";
+import {
+	concatBytes,
+	decodeSourceRconFrames,
+	encodeSourceRconFrame,
+	SOURCE_RCON_AUTH_FAILED_ID,
+	type SourceRconFrame,
+	SourceRconRequest,
+	SourceRconResponse,
+} from "./sourceRconFrame";
+
+type Reply = (frame: SourceRconFrame) => void;
+
+const HOST = "127.0.0.1";
+
+const rconServer = (handle: (frame: SourceRconFrame, reply: Reply) => void) => {
+	const pending = new WeakMap<object, Uint8Array>();
+
+	return Bun.listen({
+		hostname: HOST,
+		port: 0,
+		socket: {
+			data(socket, chunk) {
+				const decoded = decodeSourceRconFrames(concatBytes(pending.get(socket) ?? new Uint8Array(0), chunk));
+
+				pending.set(socket, decoded.rest);
+
+				for (const frame of decoded.frames) {
+					handle(frame, (out) => {
+						socket.write(encodeSourceRconFrame(out));
+					});
+				}
+			},
+		},
+	});
+};
+
+const authOk = (frame: SourceRconFrame, reply: Reply) => {
+	reply({
+		id: frame.id,
+		type: SourceRconResponse.Value,
+		body: "",
+	});
+	reply({
+		id: frame.id,
+		type: SourceRconResponse.Auth,
+		body: "",
+	});
+};
+
+describe("sourceRcon", () => {
+	test("rejects a wrong password with an auth-failed error", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type !== SourceRconRequest.Auth) {
+				return;
+			}
+
+			reply({
+				id: frame.id,
+				type: SourceRconResponse.Value,
+				body: "",
+			});
+			reply({
+				id: SOURCE_RCON_AUTH_FAILED_ID,
+				type: SourceRconResponse.Auth,
+				body: "",
+			});
+		});
+
+		try {
+			const error = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "wrong",
+				timeoutMs: 2000,
+			}).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeRconError);
+			expect((error as BridgeRconError).code).toBe(BridgeRconCode.AuthFailed);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("authenticates and returns a single-packet reply", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+
+				return;
+			}
+
+			reply({
+				id: frame.id,
+				type: SourceRconResponse.Value,
+				body: frame.body.length === 0 ? "" : `ran ${frame.body}`,
+			});
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 2000,
+			});
+
+			expect(await client.command("ListPlayers")).toBe("ran ListPlayers");
+
+			client.close();
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("joins a multi-packet reply at the probe echo", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+
+				return;
+			}
+
+			if (frame.type === SourceRconResponse.Value) {
+				reply({
+					id: frame.id,
+					type: SourceRconResponse.Value,
+					body: "",
+				});
+
+				return;
+			}
+
+			for (const part of [
+				"first-",
+				"second-",
+				"third",
+			]) {
+				reply({
+					id: frame.id,
+					type: SourceRconResponse.Value,
+					body: part,
+				});
+			}
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 2000,
+			});
+
+			expect(await client.command("status")).toBe("first-second-third");
+
+			client.close();
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("settles on the first value frame when multi-packet is off", async () => {
+		let probes = 0;
+
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+
+				return;
+			}
+
+			if (frame.type === SourceRconResponse.Value) {
+				probes += 1;
+
+				return;
+			}
+
+			reply({
+				id: frame.id,
+				type: SourceRconResponse.Value,
+				body: "single",
+			});
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 2000,
+				multiPacket: false,
+			});
+
+			expect(await client.command("/players")).toBe("single");
+			expect(probes).toBe(0);
+
+			client.close();
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("runs queued commands one after another", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+
+				return;
+			}
+
+			reply({
+				id: frame.id,
+				type: SourceRconResponse.Value,
+				body: frame.body.length === 0 ? "" : frame.body.toUpperCase(),
+			});
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 2000,
+			});
+
+			expect(
+				await Promise.all([
+					client.command("one"),
+					client.command("two"),
+					client.command("three"),
+				]),
+			).toEqual([
+				"ONE",
+				"TWO",
+				"THREE",
+			]);
+
+			client.close();
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("times out a command the server never answers", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+			}
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 250,
+			});
+
+			const error = await client.command("status").catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeRconError);
+			expect((error as BridgeRconError).code).toBe(BridgeRconCode.TimedOut);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("refuses a command body above the packet limit", async () => {
+		const server = rconServer((frame, reply) => {
+			if (frame.type === SourceRconRequest.Auth) {
+				authOk(frame, reply);
+			}
+		});
+
+		try {
+			const client = await sourceRcon({
+				host: HOST,
+				port: server.port,
+				password: "right",
+				timeoutMs: 2000,
+			});
+
+			const error = await client.command("x".repeat(5000)).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeRconError);
+			expect((error as BridgeRconError).code).toBe(BridgeRconCode.Oversized);
+
+			client.close();
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("reports an unreachable port", async () => {
+		const error = await sourceRcon({
+			host: HOST,
+			port: 59_431,
+			password: "right",
+			timeoutMs: 1000,
+		}).catch((reason: unknown) => reason);
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Unreachable);
+	});
+});

package/src/rcon/sourceRcon.ts

@@ -0,0 +1,276 @@
+import { BridgeRconCode, BridgeRconError } from "../core";
+import {
+	concatBytes,
+	decodeSourceRconFrames,
+	encodeSourceRconFrame,
+	SOURCE_RCON_AUTH_FAILED_ID,
+	type SourceRconFrame,
+	SourceRconRequest,
+	SourceRconResponse,
+} from "./sourceRconFrame";
+
+const DEFAULT_HOST = "127.0.0.1";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+const AUTH_ID = 1;
+
+const RESPONSE_LIMIT = 1024 * 1024;
+
+export interface SourceRconOptions {
+	host?: string;
+	port: number;
+	password: string;
+	timeoutMs?: number;
+	multiPacket?: boolean;
+}
+
+export interface SourceRconClient {
+	command(text: string): Promise<string>;
+	close(): void;
+}
+
+interface Waiter {
+	id: number;
+	auth: boolean;
+	probeId: number | null;
+	parts: string[];
+	settle(outcome: string | BridgeRconError): void;
+}
+
+const rconError = (code: BridgeRconCode, message: string, cause?: unknown) => {
+	if (cause instanceof BridgeRconError) {
+		return cause;
+	}
+
+	const detail = cause instanceof Error && cause.message.length > 0 ? ` — ${cause.message}` : "";
+
+	return new BridgeRconError(code, `${message}${detail}`);
+};
+
+export const sourceRcon = async (options: SourceRconOptions): Promise<SourceRconClient> => {
+	const host = options.host ?? DEFAULT_HOST;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const multiPacket = options.multiPacket !== false;
+	const target = `${host}:${options.port}`;
+
+	let buffer: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	let waiter: Waiter | null = null;
+	let failure: BridgeRconError | null = null;
+	let nextId = AUTH_ID + 1;
+	let queue: Promise<unknown> = Promise.resolve();
+
+	const fail = (error: BridgeRconError) => {
+		failure ??= error;
+
+		const waiting = waiter;
+
+		waiter = null;
+		waiting?.settle(error);
+	};
+
+	const accept = (frame: SourceRconFrame) => {
+		const waiting = waiter;
+
+		if (!waiting) {
+			return;
+		}
+
+		if (waiting.auth) {
+			if (frame.type !== SourceRconResponse.Auth) {
+				return;
+			}
+
+			waiter = null;
+
+			waiting.settle(
+				frame.id === SOURCE_RCON_AUTH_FAILED_ID
+					? new BridgeRconError(BridgeRconCode.AuthFailed, `${target} rejected the rcon password`)
+					: "",
+			);
+
+			return;
+		}
+
+		if (frame.type !== SourceRconResponse.Value) {
+			return;
+		}
+
+		if (waiting.probeId !== null && frame.id === waiting.probeId) {
+			waiter = null;
+			waiting.settle(waiting.parts.join(""));
+
+			return;
+		}
+
+		if (frame.id !== waiting.id) {
+			return;
+		}
+
+		waiting.parts.push(frame.body);
+
+		if (waiting.parts.reduce((total, part) => total + part.length, 0) > RESPONSE_LIMIT) {
+			fail(
+				new BridgeRconError(
+					BridgeRconCode.Malformed,
+					`${target} sent an rcon reply larger than ${RESPONSE_LIMIT} bytes`,
+				),
+			);
+
+			return;
+		}
+
+		if (waiting.probeId === null) {
+			waiter = null;
+			waiting.settle(waiting.parts.join(""));
+		}
+	};
+
+	const receive = (chunk: Uint8Array) => {
+		buffer = concatBytes(buffer, chunk);
+
+		try {
+			const decoded = decodeSourceRconFrames(buffer);
+
+			buffer = decoded.rest;
+
+			for (const frame of decoded.frames) {
+				accept(frame);
+			}
+		} catch (error) {
+			fail(rconError(BridgeRconCode.Malformed, `${target} sent an unreadable rcon packet`, error));
+		}
+	};
+
+	const connect = async () => {
+		let guard: ReturnType<typeof setTimeout> | undefined;
+
+		try {
+			return await Promise.race([
+				Bun.connect({
+					hostname: host,
+					port: options.port,
+					socket: {
+						data(_socket, data) {
+							receive(data);
+						},
+						close() {
+							fail(new BridgeRconError(BridgeRconCode.Closed, `${target} closed the rcon connection`));
+						},
+						error(_socket, error) {
+							fail(rconError(BridgeRconCode.Unreachable, `the rcon connection to ${target} failed`, error));
+						},
+					},
+				}),
+				new Promise<never>((_resolve, reject) => {
+					guard = setTimeout(() => {
+						reject(new BridgeRconError(BridgeRconCode.TimedOut, `the rcon connection to ${target} timed out`));
+					}, timeoutMs);
+				}),
+			]);
+		} catch (error) {
+			throw rconError(BridgeRconCode.Unreachable, `the rcon connection to ${target} could not be opened`, error);
+		} finally {
+			clearTimeout(guard);
+		}
+	};
+
+	const socket = await connect();
+
+	const exchange = (id: number, type: SourceRconRequest, body: string, probeId: number | null) => {
+		return new Promise<string>((resolve, reject) => {
+			if (failure) {
+				reject(failure);
+
+				return;
+			}
+
+			let settled = false;
+
+			const timer = setTimeout(() => {
+				fail(new BridgeRconError(BridgeRconCode.TimedOut, `${target} did not answer the rcon request in time`));
+				socket.end();
+			}, timeoutMs);
+
+			waiter = {
+				id,
+				auth: type === SourceRconRequest.Auth,
+				probeId,
+				parts: [],
+				settle(outcome) {
+					if (settled) {
+						return;
+					}
+
+					settled = true;
+
+					clearTimeout(timer);
+
+					if (outcome instanceof BridgeRconError) {
+						reject(outcome);
+
+						return;
+					}
+
+					resolve(outcome);
+				},
+			};
+
+			try {
+				socket.write(
+					encodeSourceRconFrame({
+						id,
+						type,
+						body,
+					}),
+				);
+
+				if (probeId !== null) {
+					socket.write(
+						encodeSourceRconFrame({
+							id: probeId,
+							type: SourceRconResponse.Value,
+							body: "",
+						}),
+					);
+				}
+			} catch (error) {
+				fail(rconError(BridgeRconCode.Closed, `the rcon request to ${target} could not be sent`, error));
+			}
+		});
+	};
+
+	const serialize = <Result>(work: () => Promise<Result>): Promise<Result> => {
+		const next = queue.then(work, work);
+
+		queue = next.then(
+			() => undefined,
+			() => undefined,
+		);
+
+		return next;
+	};
+
+	try {
+		await serialize(() => exchange(AUTH_ID, SourceRconRequest.Auth, options.password, null));
+	} catch (error) {
+		socket.end();
+
+		throw error;
+	}
+
+	return {
+		async command(text) {
+			return await serialize(async () => {
+				const id = nextId++;
+				const probeId = multiPacket ? nextId++ : null;
+
+				return await exchange(id, SourceRconRequest.Command, text, probeId);
+			});
+		},
+
+		close() {
+			socket.end();
+		},
+	};
+};

package/src/rcon/sourceRconFrame.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeRconCode, BridgeRconError } from "../core";
+import {
+	concatBytes,
+	decodeSourceRconFrames,
+	encodeSourceRconFrame,
+	SOURCE_RCON_BODY_LIMIT,
+	SourceRconRequest,
+	SourceRconResponse,
+} from "./sourceRconFrame";
+
+describe("encodeSourceRconFrame", () => {
+	test("writes size, id and type as little endian int32 followed by two nulls", () => {
+		const packet = encodeSourceRconFrame({
+			id: 7,
+			type: SourceRconRequest.Auth,
+			body: "pass",
+		});
+
+		const view = new DataView(packet.buffer);
+
+		expect(packet).toHaveLength(18);
+		expect(view.getInt32(0, true)).toBe(14);
+		expect(view.getInt32(4, true)).toBe(7);
+		expect(view.getInt32(8, true)).toBe(3);
+		expect(new TextDecoder().decode(packet.subarray(12, 16))).toBe("pass");
+		expect(packet.at(16)).toBe(0);
+		expect(packet.at(17)).toBe(0);
+	});
+
+	test("refuses a body above the 4096 byte cap", () => {
+		const error = (() => {
+			try {
+				encodeSourceRconFrame({
+					id: 1,
+					type: SourceRconRequest.Command,
+					body: "x".repeat(SOURCE_RCON_BODY_LIMIT + 1),
+				});
+
+				return null;
+			} catch (reason: unknown) {
+				return reason;
+			}
+		})();
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Oversized);
+	});
+});
+
+describe("decodeSourceRconFrames", () => {
+	test("round-trips a frame", () => {
+		const decoded = decodeSourceRconFrames(
+			encodeSourceRconFrame({
+				id: 3,
+				type: SourceRconResponse.Value,
+				body: "hello",
+			}),
+		);
+
+		expect(decoded.frames).toEqual([
+			{
+				id: 3,
+				type: 0,
+				body: "hello",
+			},
+		]);
+		expect(decoded.rest).toHaveLength(0);
+	});
+
+	test("reads several frames out of one buffer", () => {
+		const decoded = decodeSourceRconFrames(
+			concatBytes(
+				encodeSourceRconFrame({
+					id: 1,
+					type: SourceRconResponse.Value,
+					body: "a",
+				}),
+				encodeSourceRconFrame({
+					id: 2,
+					type: SourceRconResponse.Auth,
+					body: "",
+				}),
+			),
+		);
+
+		expect(decoded.frames.map((frame) => frame.id)).toEqual([
+			1,
+			2,
+		]);
+	});
+
+	test("keeps a partial frame for the next chunk", () => {
+		const packet = encodeSourceRconFrame({
+			id: 9,
+			type: SourceRconResponse.Value,
+			body: "split",
+		});
+
+		const first = decodeSourceRconFrames(packet.subarray(0, 8));
+
+		expect(first.frames).toEqual([]);
+		expect(first.rest).toHaveLength(8);
+
+		const second = decodeSourceRconFrames(concatBytes(first.rest, packet.subarray(8)));
+
+		expect(second.frames).toEqual([
+			{
+				id: 9,
+				type: 0,
+				body: "split",
+			},
+		]);
+	});
+
+	test("reads an empty body", () => {
+		expect(
+			decodeSourceRconFrames(
+				encodeSourceRconFrame({
+					id: -1,
+					type: SourceRconResponse.Auth,
+					body: "",
+				}),
+			).frames,
+		).toEqual([
+			{
+				id: -1,
+				type: 2,
+				body: "",
+			},
+		]);
+	});
+
+	test("rejects a packet declaring an impossible size", () => {
+		const packet = new Uint8Array(14);
+
+		new DataView(packet.buffer).setInt32(0, 2, true);
+
+		const error = (() => {
+			try {
+				decodeSourceRconFrames(packet);
+
+				return null;
+			} catch (reason: unknown) {
+				return reason;
+			}
+		})();
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Malformed);
+	});
+});