@serverkgg/bridge 0.0.13 → 0.0.14

package/src/rcon/rconClient.ts

@@ -0,0 +1,275 @@
+import { BridgeRconCode, BridgeRconError } from "../core";
+import { rconTarget } from "./rconError";
+import { encodeRconFrame, RconRequest, RconResponse } from "./rconFrame";
+import { createRconIds, type RconIds } from "./rconIds";
+import { openRconLink, type RconLink } from "./rconLink";
+
+const DEFAULT_HOST = "127.0.0.1";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export interface RconClientOptions {
+	host?: string;
+	port: number;
+	password: string;
+	timeoutMs?: number;
+	multiPacket?: boolean;
+	mirroredIds?: boolean;
+	idSeed?: number;
+}
+
+export interface RconCommandOptions {
+	timeoutMs?: number;
+}
+
+interface RconClientFrames {
+	request: Uint8Array;
+	probe: Uint8Array | null;
+}
+
+export class RconClient {
+	readonly #host: string;
+	readonly #port: number;
+	readonly #password: string;
+	readonly #timeoutMs: number;
+	readonly #multiPacket: boolean;
+	readonly #mirroredIds: boolean;
+	readonly #target: string;
+	readonly #ids: RconIds;
+
+	#link: RconLink | null = null;
+	#dialing: Promise<RconLink> | null = null;
+	#locked: BridgeRconError | null = null;
+	#epoch = 0;
+	#queue: Promise<unknown> = Promise.resolve();
+
+	constructor(options: RconClientOptions) {
+		this.#host = options.host ?? DEFAULT_HOST;
+		this.#port = options.port;
+		this.#password = options.password;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#multiPacket = options.multiPacket !== false;
+		this.#mirroredIds = options.mirroredIds !== false;
+		this.#target = rconTarget(this.#host, this.#port);
+		this.#ids = createRconIds(options.idSeed);
+	}
+
+	get connected(): boolean {
+		return this.#link?.alive ?? false;
+	}
+
+	async connect(): Promise<void> {
+		this.#locked = null;
+
+		await this.#ensureLink();
+	}
+
+	command(text: string, options: RconCommandOptions = {}): Promise<string> {
+		const timeoutMs = options.timeoutMs ?? this.#timeoutMs;
+		const deadlineAt = performance.now() + timeoutMs;
+		const epoch = this.#epoch;
+
+		return new Promise<string>((resolve, reject) => {
+			let settled = false;
+
+			const timer = setTimeout(() => {
+				settled = true;
+
+				reject(this.#timedOut());
+			}, timeoutMs);
+
+			void this.#serialize(async () => {
+				if (settled) {
+					return;
+				}
+
+				try {
+					const reply = await this.#run(text, deadlineAt, epoch);
+
+					if (settled) {
+						return;
+					}
+
+					settled = true;
+
+					clearTimeout(timer);
+					resolve(reply);
+				} catch (error) {
+					if (settled) {
+						return;
+					}
+
+					settled = true;
+
+					clearTimeout(timer);
+					reject(error);
+				}
+			});
+		});
+	}
+
+	async disconnect(): Promise<void> {
+		this.#epoch += 1;
+		this.#dialing = null;
+
+		const link = this.#link;
+
+		this.#link = null;
+
+		if (!link) {
+			return;
+		}
+
+		await link.close(this.#closed());
+	}
+
+	#closed(): BridgeRconError {
+		return new BridgeRconError(BridgeRconCode.Closed, `the rcon connection to ${this.#target} was closed`);
+	}
+
+	#timedOut(): BridgeRconError {
+		return new BridgeRconError(BridgeRconCode.TimedOut, `${this.#target} did not answer the rcon request in time`);
+	}
+
+	#serialize<Result>(work: () => Promise<Result>): Promise<Result> {
+		const next = this.#queue.then(work, work);
+
+		this.#queue = next.then(
+			() => undefined,
+			() => undefined,
+		);
+
+		return next;
+	}
+
+	#frames(text: string, id: number, probeId: number | null): RconClientFrames {
+		const request = encodeRconFrame({
+			id,
+			type: RconRequest.Command,
+			body: text,
+		});
+
+		if (probeId === null) {
+			return {
+				request,
+				probe: null,
+			};
+		}
+
+		return {
+			request,
+			probe: encodeRconFrame({
+				id: probeId,
+				type: RconResponse.Value,
+				body: "",
+			}),
+		};
+	}
+
+	async #run(text: string, deadlineAt: number, epoch: number): Promise<string> {
+		for (let attempt = 0; ; attempt += 1) {
+			if (epoch !== this.#epoch) {
+				throw this.#closed();
+			}
+
+			if (this.#locked) {
+				throw this.#locked;
+			}
+
+			const pair = this.#ids.next();
+			const probeId = this.#multiPacket && this.#mirroredIds ? pair.probeId : null;
+			const frames = this.#frames(text, pair.id, probeId);
+			const link = await this.#ensureLink();
+
+			if (epoch !== this.#epoch) {
+				throw this.#closed();
+			}
+
+			if (performance.now() >= deadlineAt) {
+				throw this.#timedOut();
+			}
+
+			const sent = link.send({
+				id: pair.id,
+				probeId,
+				request: frames.request,
+				probe: frames.probe,
+				mirroredIds: this.#mirroredIds,
+				deadlineAt,
+			});
+
+			if (sent.written === 0 && !link.alive && attempt === 0) {
+				await sent.reply.catch(() => undefined);
+
+				continue;
+			}
+
+			return await sent.reply;
+		}
+	}
+
+	async #ensureLink(): Promise<RconLink> {
+		if (this.#locked) {
+			throw this.#locked;
+		}
+
+		const current = this.#link;
+
+		if (current?.alive) {
+			return current;
+		}
+
+		if (!this.#dialing) {
+			const dial = this.#dial();
+
+			this.#dialing = dial;
+
+			void dial
+				.catch(() => undefined)
+				.finally(() => {
+					if (this.#dialing === dial) {
+						this.#dialing = null;
+					}
+				});
+		}
+
+		return await this.#dialing;
+	}
+
+	async #dial(): Promise<RconLink> {
+		const epoch = this.#epoch;
+
+		try {
+			const link = await openRconLink({
+				host: this.#host,
+				port: this.#port,
+				password: this.#password,
+				timeoutMs: this.#timeoutMs,
+				ids: this.#ids,
+				onLost: () => {
+					if (this.#link === link) {
+						this.#link = null;
+					}
+				},
+			});
+
+			if (epoch !== this.#epoch) {
+				const closed = this.#closed();
+
+				await link.close(closed);
+
+				throw closed;
+			}
+
+			this.#link = link;
+
+			return link;
+		} catch (error) {
+			if (error instanceof BridgeRconError && error.code === BridgeRconCode.AuthFailed) {
+				this.#locked = error;
+			}
+
+			throw error;
+		}
+	}
+}

package/src/rcon/rconError.ts

@@ -0,0 +1,21 @@
+import { BridgeRconCode, BridgeRconError } from "../core";
+
+const DETAILED_CODES = new Set([
+	BridgeRconCode.Malformed,
+	BridgeRconCode.Unreachable,
+]);
+
+export const rconTarget = (host: string, port: number) => {
+	return `${host}:${port}`;
+};
+
+export const rconError = (code: BridgeRconCode, message: string, cause?: unknown) => {
+	if (cause instanceof BridgeRconError) {
+		return cause;
+	}
+
+	const detail =
+		DETAILED_CODES.has(code) && cause instanceof Error && cause.message.length > 0 ? ` — ${cause.message}` : "";
+
+	return new BridgeRconError(code, `${message}${detail}`);
+};

package/src/rcon/rconFrame.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeRconCode, BridgeRconError } from "../core";
+import {
+	concatBytes,
+	decodeRconFrames,
+	encodeRconFrame,
+	RCON_BODY_LIMIT,
+	RCON_REPLY_LIMIT,
+	RconRequest,
+	RconResponse,
+} from "./rconFrame";
+
+const HEADER_LENGTH = 4;
+
+const NUL = String.fromCharCode(0);
+
+const TRAILER_BODY = `${NUL}${String.fromCharCode(1)}${NUL}${NUL}`;
+
+const thrown = (run: () => unknown) => {
+	try {
+		run();
+
+		return null;
+	} catch (reason: unknown) {
+		return reason;
+	}
+};
+
+const declaredFrame = (size: number) => {
+	const packet = new Uint8Array(HEADER_LENGTH + Math.max(size, 0));
+
+	new DataView(packet.buffer).setInt32(0, size, true);
+
+	return packet;
+};
+
+describe("encodeRconFrame", () => {
+	test("writes size, id and type as little endian int32 followed by two nulls", () => {
+		const packet = encodeRconFrame({
+			id: 7,
+			type: RconRequest.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 = thrown(() =>
+			encodeRconFrame({
+				id: 1,
+				type: RconRequest.Command,
+				body: "x".repeat(RCON_BODY_LIMIT + 1),
+			}),
+		);
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Oversized);
+	});
+});
+
+describe("decodeRconFrames", () => {
+	test("round-trips a frame", () => {
+		const decoded = decodeRconFrames(
+			encodeRconFrame({
+				id: 3,
+				type: RconResponse.Value,
+				body: "hello",
+			}),
+		);
+
+		expect(decoded.frames).toEqual([
+			{
+				id: 3,
+				type: 0,
+				body: "hello",
+				bodyBytes: 5,
+			},
+		]);
+		expect(decoded.rest).toHaveLength(0);
+	});
+
+	test("reads several frames out of one buffer", () => {
+		const decoded = decodeRconFrames(
+			concatBytes(
+				encodeRconFrame({
+					id: 1,
+					type: RconResponse.Value,
+					body: "a",
+				}),
+				encodeRconFrame({
+					id: 2,
+					type: RconResponse.Auth,
+					body: "",
+				}),
+			),
+		);
+
+		expect(decoded.frames.map((frame) => frame.id)).toEqual([
+			1,
+			2,
+		]);
+	});
+
+	test("keeps a partial frame for the next chunk", () => {
+		const packet = encodeRconFrame({
+			id: 9,
+			type: RconResponse.Value,
+			body: "split",
+		});
+
+		const first = decodeRconFrames(packet.subarray(0, 8));
+
+		expect(first.frames).toEqual([]);
+		expect(first.rest).toHaveLength(8);
+
+		const second = decodeRconFrames(concatBytes(first.rest, packet.subarray(8)));
+
+		expect(second.frames).toEqual([
+			{
+				id: 9,
+				type: 0,
+				body: "split",
+				bodyBytes: 5,
+			},
+		]);
+	});
+
+	test("keeps a frame split inside the size prefix", () => {
+		const packet = encodeRconFrame({
+			id: 11,
+			type: RconResponse.Value,
+			body: "prefix",
+		});
+
+		const first = decodeRconFrames(packet.subarray(0, 2));
+
+		expect(first.frames).toEqual([]);
+		expect(first.rest).toHaveLength(2);
+
+		const second = decodeRconFrames(concatBytes(first.rest, packet.subarray(2)));
+
+		expect(second.frames.at(0)?.body).toBe("prefix");
+	});
+
+	test("reads an empty body", () => {
+		expect(
+			decodeRconFrames(
+				encodeRconFrame({
+					id: -1,
+					type: RconResponse.Auth,
+					body: "",
+				}),
+			).frames,
+		).toEqual([
+			{
+				id: -1,
+				type: 2,
+				body: "",
+				bodyBytes: 0,
+			},
+		]);
+	});
+
+	test("round-trips a multi-byte utf-8 body and counts its bytes", () => {
+		const body = "اللاعب انضم — 참가자";
+
+		const frame = decodeRconFrames(
+			encodeRconFrame({
+				id: 4,
+				type: RconResponse.Value,
+				body,
+			}),
+		).frames.at(0);
+
+		expect(frame?.body).toBe(body);
+		expect(frame?.bodyBytes).toBe(new TextEncoder().encode(body).length);
+	});
+
+	test("keeps a body with an embedded null", () => {
+		const body = `left${NUL}right`;
+
+		expect(
+			decodeRconFrames(
+				encodeRconFrame({
+					id: 5,
+					type: RconResponse.Value,
+					body,
+				}),
+			).frames.at(0)?.body,
+		).toBe(body);
+	});
+
+	test("reads the srcds trailer as an ordinary frame", () => {
+		expect(
+			decodeRconFrames(
+				encodeRconFrame({
+					id: 6,
+					type: RconResponse.Value,
+					body: TRAILER_BODY,
+				}),
+			).frames.at(0),
+		).toEqual({
+			id: 6,
+			type: 0,
+			body: TRAILER_BODY,
+			bodyBytes: 4,
+		});
+	});
+
+	test("rejects a packet declaring an impossible size", () => {
+		const error = thrown(() => decodeRconFrames(declaredFrame(2)));
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Malformed);
+	});
+
+	test("reads a frame of exactly the reply limit and rejects one byte more", () => {
+		const decoded = decodeRconFrames(declaredFrame(RCON_REPLY_LIMIT));
+
+		expect(decoded.frames).toHaveLength(1);
+		expect(decoded.frames.at(0)?.body).toHaveLength(RCON_REPLY_LIMIT - 10);
+
+		const error = thrown(() => decodeRconFrames(declaredFrame(RCON_REPLY_LIMIT + 1)));
+
+		expect(error).toBeInstanceOf(BridgeRconError);
+		expect((error as BridgeRconError).code).toBe(BridgeRconCode.Malformed);
+	});
+});
+
+describe("concatBytes", () => {
+	test("copies a non-empty left side and keeps the order", () => {
+		const left = new Uint8Array([
+			1,
+			2,
+		]);
+
+		const right = new Uint8Array([
+			3,
+			4,
+		]);
+
+		const joined = concatBytes(left, right);
+
+		left.set([
+			9,
+			9,
+		]);
+		right.set([
+			9,
+			9,
+		]);
+
+		expect(Array.from(joined)).toEqual([
+			1,
+			2,
+			3,
+			4,
+		]);
+	});
+});

package/src/rcon/{sourceRconFrame.ts → rconFrame.ts}

@@ -1,42 +1,48 @@
 import { BridgeRconCode, BridgeRconError } from "../core";
 
-export enum SourceRconRequest {
+export enum RconRequest {
 	Command = 2,
 	Auth = 3,
 }
 
-export enum SourceRconResponse {
+export enum RconResponse {
 	Value = 0,
 	Auth = 2,
 }
 
-export const SOURCE_RCON_BODY_LIMIT = 4096;
+export const RCON_BODY_LIMIT = 4096;
 
-export const SOURCE_RCON_AUTH_FAILED_ID = -1;
+export const RCON_REPLY_LIMIT = 1024 * 1024;
+
+export const RCON_SPLIT_THRESHOLD = 4000;
+
+export const RCON_AUTH_FAILED_ID = -1;
 
 const HEADER_LENGTH = 4;
 
 const MIN_FRAME_SIZE = 10;
 
-const MAX_FRAME_SIZE = 65_536;
-
 const ENCODER = new TextEncoder();
 
 const DECODER = new TextDecoder();
 
-export interface SourceRconFrame {
+export interface RconFrame {
 	id: number;
 	type: number;
 	body: string;
 }
 
-export const encodeSourceRconFrame = (frame: SourceRconFrame) => {
+export interface RconDecodedFrame extends RconFrame {
+	bodyBytes: number;
+}
+
+export const encodeRconFrame = (frame: RconFrame) => {
 	const body = ENCODER.encode(frame.body);
 
-	if (body.length > SOURCE_RCON_BODY_LIMIT) {
+	if (body.length > RCON_BODY_LIMIT) {
 		throw new BridgeRconError(
 			BridgeRconCode.Oversized,
-			`an rcon body of ${body.length} bytes exceeds the ${SOURCE_RCON_BODY_LIMIT} byte limit`,
+			`an rcon body of ${body.length} bytes exceeds the ${RCON_BODY_LIMIT} byte limit`,
 		);
 	}
 
@@ -52,15 +58,15 @@ export const encodeSourceRconFrame = (frame: SourceRconFrame) => {
 	return packet;
 };
 
-export const decodeSourceRconFrames = (buffer: Uint8Array) => {
-	const frames: SourceRconFrame[] = [];
+export const decodeRconFrames = (buffer: Uint8Array) => {
+	const frames: RconDecodedFrame[] = [];
 
 	let offset = 0;
 
 	while (buffer.length - offset >= HEADER_LENGTH) {
 		const size = new DataView(buffer.buffer, buffer.byteOffset + offset, HEADER_LENGTH).getInt32(0, true);
 
-		if (size < MIN_FRAME_SIZE || size > MAX_FRAME_SIZE) {
+		if (size < MIN_FRAME_SIZE || size > RCON_REPLY_LIMIT) {
 			throw new BridgeRconError(BridgeRconCode.Malformed, `an rcon packet declares an impossible size of ${size}`);
 		}
 
@@ -69,11 +75,14 @@ export const decodeSourceRconFrames = (buffer: Uint8Array) => {
 		}
 
 		const head = new DataView(buffer.buffer, buffer.byteOffset + offset + HEADER_LENGTH, 8);
+		const bodyStart = offset + 12;
+		const bodyEnd = offset + HEADER_LENGTH + size - 2;
 
 		frames.push({
 			id: head.getInt32(0, true),
 			type: head.getInt32(4, true),
-			body: DECODER.decode(buffer.subarray(offset + 12, offset + HEADER_LENGTH + size - 2)),
+			body: DECODER.decode(buffer.subarray(bodyStart, bodyEnd)),
+			bodyBytes: bodyEnd - bodyStart,
 		});
 
 		offset += HEADER_LENGTH + size;

package/src/rcon/rconIds.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { createRconIds } from "./rconIds";
+
+const LAST_ID = 2_147_483_646;
+
+describe("createRconIds", () => {
+	test("hands out one and two first", () => {
+		expect(createRconIds().next()).toEqual({
+			id: 1,
+			probeId: 2,
+		});
+	});
+
+	test("hands out strictly increasing pairs", () => {
+		const ids = createRconIds();
+
+		let previous = ids.next();
+
+		for (let index = 0; index < 100; index += 1) {
+			const pair = ids.next();
+
+			expect(pair.id).toBeGreaterThan(previous.probeId);
+			expect(pair.probeId).toBeGreaterThan(pair.id);
+
+			previous = pair;
+		}
+	});
+
+	test("wraps back to one without ever handing out zero or minus one", () => {
+		const ids = createRconIds(LAST_ID - 3);
+
+		const pairs = [
+			ids.next(),
+			ids.next(),
+			ids.next(),
+		];
+
+		expect(pairs).toEqual([
+			{
+				id: LAST_ID - 3,
+				probeId: LAST_ID - 2,
+			},
+			{
+				id: LAST_ID - 1,
+				probeId: LAST_ID,
+			},
+			{
+				id: 1,
+				probeId: 2,
+			},
+		]);
+
+		for (const pair of pairs) {
+			expect(pair.id).toBeGreaterThan(0);
+			expect(pair.probeId).toBeGreaterThan(pair.id);
+			expect(pair.probeId).toBeLessThanOrEqual(LAST_ID);
+		}
+	});
+});