@serverkgg/bridge 0.0.11 → 0.0.13

package/src/probes/minecraftPing.ts

@@ -0,0 +1,283 @@
+import type { BridgeMinecraftPingStatus } from "../context";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
+
+const STATUS_PROTOCOL_VERSION = -1;
+
+const STATUS_STATE = 1;
+
+const MAX_RESPONSE_BYTES = 256 * 1024;
+
+const VARINT_MAX_BYTES = 5;
+
+export interface BridgeMinecraftPingTarget {
+	address: string;
+	port: number;
+	serverName?: string;
+}
+
+interface StatusPayload {
+	players?: {
+		online?: unknown;
+		max?: unknown;
+	};
+	version?: {
+		name?: unknown;
+	};
+	description?: unknown;
+}
+
+interface DescriptionObject {
+	text?: unknown;
+}
+
+const writeVarInt = (value: number) => {
+	const bytes: number[] = [];
+
+	let current = value >>> 0;
+
+	while (true) {
+		if ((current & ~0x7f) === 0) {
+			bytes.push(current);
+
+			return bytes;
+		}
+
+		bytes.push((current & 0x7f) | 0x80);
+
+		current >>>= 7;
+	}
+};
+
+const readVarInt = (view: Uint8Array, offset: number) => {
+	let value = 0;
+	let size = 0;
+
+	while (size < VARINT_MAX_BYTES) {
+		const byte = view[offset + size];
+
+		if (byte === undefined) {
+			return null;
+		}
+
+		value |= (byte & 0x7f) << (7 * size);
+		size += 1;
+
+		if ((byte & 0x80) === 0) {
+			return {
+				value,
+				size,
+			};
+		}
+	}
+
+	throw new Error("minecraft ping varint is malformed");
+};
+
+const framed = (body: number[]) => {
+	return new Uint8Array([
+		...writeVarInt(body.length),
+		...body,
+	]);
+};
+
+const handshake = (serverName: string, hostPort: number) => {
+	const address = new TextEncoder().encode(serverName);
+
+	return framed([
+		0x00,
+		...writeVarInt(STATUS_PROTOCOL_VERSION),
+		...writeVarInt(address.length),
+		...address,
+		(hostPort >> 8) & 0xff,
+		hostPort & 0xff,
+		...writeVarInt(STATUS_STATE),
+	]);
+};
+
+const STATUS_REQUEST = framed([
+	0x00,
+]);
+
+const toDescription = (description: unknown): string | null => {
+	if (typeof description === "string") {
+		return description;
+	}
+
+	if (description === null || typeof description !== "object") {
+		return null;
+	}
+
+	const text = (description as DescriptionObject).text;
+
+	return typeof text === "string" ? text : null;
+};
+
+export const parseStatus = (view: Uint8Array): Omit<BridgeMinecraftPingStatus, "latencyMs"> | null => {
+	const frame = readVarInt(view, 0);
+
+	if (!frame) {
+		return null;
+	}
+
+	if (view.length < frame.size + frame.value) {
+		return null;
+	}
+
+	const packetId = readVarInt(view, frame.size);
+
+	if (!packetId) {
+		return null;
+	}
+
+	if (packetId.value !== 0x00) {
+		throw new Error("minecraft ping response has an unexpected packet id");
+	}
+
+	const length = readVarInt(view, frame.size + packetId.size);
+
+	if (!length) {
+		return null;
+	}
+
+	const start = frame.size + packetId.size + length.size;
+
+	if (view.length < start + length.value) {
+		return null;
+	}
+
+	const status = JSON.parse(new TextDecoder().decode(view.subarray(start, start + length.value))) as StatusPayload;
+
+	const online = status.players?.online;
+	const max = status.players?.max;
+
+	if (typeof online !== "number" || typeof max !== "number") {
+		throw new Error("minecraft ping response is missing player counts");
+	}
+
+	const version = status.version?.name;
+
+	return {
+		players: {
+			online: Math.max(0, Math.floor(online)),
+			max: Math.max(0, Math.floor(max)),
+		},
+		version: typeof version === "string" ? version : null,
+		description: toDescription(status.description),
+	};
+};
+
+const probeError = (code: BridgeProbeCode, message: string, cause: unknown) => {
+	if (cause instanceof BridgeProbeError) {
+		return cause;
+	}
+
+	const detail = cause instanceof Error && cause.message.length > 0 ? `: ${cause.message}` : "";
+
+	return new BridgeProbeError(code, `${message}${detail}`);
+};
+
+export const probeMinecraftPing = (target: BridgeMinecraftPingTarget, timeoutMs: number) => {
+	const label = `${target.address}:${target.port}`;
+	const serverName = target.serverName ?? target.address;
+
+	return new Promise<BridgeMinecraftPingStatus>((resolve, reject) => {
+		const startedAt = performance.now();
+
+		let socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
+		let received = new Uint8Array(0);
+		let settled = false;
+
+		const finish = (outcome: Omit<BridgeMinecraftPingStatus, "latencyMs"> | BridgeProbeError) => {
+			if (settled) {
+				return;
+			}
+
+			settled = true;
+
+			clearTimeout(timer);
+
+			try {
+				socket?.end();
+			} catch {}
+
+			if (outcome instanceof BridgeProbeError) {
+				reject(outcome);
+
+				return;
+			}
+
+			resolve({
+				...outcome,
+				latencyMs: Math.round(performance.now() - startedAt),
+			});
+		};
+
+		const timer = setTimeout(() => {
+			finish(new BridgeProbeError(BridgeProbeCode.TimedOut, `minecraft ping to ${label} timed out`));
+		}, timeoutMs);
+
+		const handle = (chunk: Uint8Array) => {
+			if (received.length + chunk.length > MAX_RESPONSE_BYTES) {
+				finish(new BridgeProbeError(BridgeProbeCode.Malformed, `minecraft ping response from ${label} is too large`));
+
+				return;
+			}
+
+			const merged = new Uint8Array(received.length + chunk.length);
+
+			merged.set(received);
+			merged.set(chunk, received.length);
+
+			received = merged;
+
+			try {
+				const status = parseStatus(received);
+
+				if (status) {
+					finish(status);
+				}
+			} catch (error) {
+				finish(probeError(BridgeProbeCode.Malformed, `minecraft ping response from ${label} could not be read`, error));
+			}
+		};
+
+		Bun.connect({
+			hostname: target.address,
+			port: target.port,
+			socket: {
+				data(_socket, data) {
+					handle(data);
+				},
+				error(_socket, error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `minecraft ping to ${label} failed`, error));
+				},
+				close() {
+					finish(
+						new BridgeProbeError(BridgeProbeCode.Unreachable, `minecraft ping to ${label} closed before answering`),
+					);
+				},
+			},
+		})
+			.then((created) => {
+				if (settled) {
+					created.end();
+
+					return;
+				}
+
+				socket = created;
+
+				try {
+					created.write(handshake(serverName, target.port));
+					created.write(STATUS_REQUEST);
+				} catch (error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `minecraft ping to ${label} could not be sent`, error));
+				}
+			})
+			.catch((error) => {
+				finish(
+					probeError(BridgeProbeCode.Unreachable, `minecraft ping socket for ${label} could not be opened`, error),
+				);
+			});
+	});
+};

package/src/probes/raknetPing.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
+import { parseUnconnectedPong, probeRaknetPing } from "./raknetPing";
+
+const HOST = "127.0.0.1";
+
+const CLOSED_PORT = 59_443;
+
+const MAGIC = [
+	0x00,
+	0xff,
+	0xff,
+	0x00,
+	0xfe,
+	0xfe,
+	0xfe,
+	0xfe,
+	0xfd,
+	0xfd,
+	0xfd,
+	0xfd,
+	0x12,
+	0x34,
+	0x56,
+	0x78,
+];
+
+const ADVERT = "MCPE;Serverk Bedrock;800;1.21.60;4;10;13253860808220445253;بيت الشباب;Survival;1;19132;19133";
+
+const pong = (
+	advert: string,
+	options: {
+		header?: number;
+		magic?: number[];
+		length?: number;
+	} = {},
+) => {
+	const payload = new TextEncoder().encode(advert);
+	const length = options.length ?? payload.length;
+
+	return new Uint8Array([
+		options.header ?? 0x1c,
+		...new Array(8).fill(0),
+		...new Array(8).fill(1),
+		...(options.magic ?? MAGIC),
+		(length >> 8) & 0xff,
+		length & 0xff,
+		...payload,
+	]);
+};
+
+const listen = async (reply: Uint8Array | null) => {
+	return await Bun.udpSocket({
+		hostname: HOST,
+		port: 0,
+		socket: {
+			data(socket, _data, port, address) {
+				if (reply) {
+					socket.send(reply, port, address);
+				}
+			},
+		},
+	});
+};
+
+describe("reading an unconnected pong", () => {
+	test("a full advertisement gives the players, the version and the motd", () => {
+		expect(parseUnconnectedPong(pong(ADVERT))).toEqual({
+			players: {
+				online: 4,
+				max: 10,
+			},
+			edition: "MCPE",
+			motd: "Serverk Bedrock",
+			subMotd: "بيت الشباب",
+			version: "1.21.60",
+			protocol: 800,
+			gamemode: "Survival",
+		});
+	});
+
+	test("an advertisement that stops after the player counts is still read", () => {
+		expect(parseUnconnectedPong(pong("MCPE;Serverk;800;1.21.60;2;8"))).toEqual({
+			players: {
+				online: 2,
+				max: 8,
+			},
+			edition: "MCPE",
+			motd: "Serverk",
+			subMotd: null,
+			version: "1.21.60",
+			protocol: 800,
+			gamemode: null,
+		});
+	});
+
+	test("a pong with another packet id is refused", () => {
+		expect(() =>
+			parseUnconnectedPong(
+				pong(ADVERT, {
+					header: 0x1d,
+				}),
+			),
+		).toThrow();
+	});
+
+	test("a pong without the raknet magic is refused", () => {
+		expect(() =>
+			parseUnconnectedPong(
+				pong(ADVERT, {
+					magic: new Array(16).fill(0),
+				}),
+			),
+		).toThrow();
+	});
+
+	test("a pong that advertises more payload than it carries is refused", () => {
+		expect(() =>
+			parseUnconnectedPong(
+				pong(ADVERT, {
+					length: 4096,
+				}),
+			),
+		).toThrow();
+	});
+
+	test("a pong without player counts is refused, because a sample without them is a lie", () => {
+		expect(() => parseUnconnectedPong(pong("MCPE;Serverk;800;1.21.60"))).toThrow();
+	});
+
+	test("a datagram larger than a pong can be is refused", () => {
+		expect(() => parseUnconnectedPong(pong("n".repeat(4096)))).toThrow();
+	});
+
+	test("a truncated datagram is refused", () => {
+		expect(() => parseUnconnectedPong(new Uint8Array(8))).toThrow();
+	});
+});
+
+describe("probeRaknetPing", () => {
+	test("answers with the advertisement a listening server sends back", async () => {
+		const server = await listen(pong(ADVERT));
+
+		try {
+			const sample = await probeRaknetPing(HOST, server.port, 2000);
+
+			expect(sample.players).toEqual({
+				online: 4,
+				max: 10,
+			});
+			expect(sample.motd).toBe("Serverk Bedrock");
+			expect(sample.latencyMs).toBeGreaterThanOrEqual(0);
+		} finally {
+			server.close();
+		}
+	});
+
+	test("rejects with an unreachable probe error when nothing listens on the port", async () => {
+		const probe = probeRaknetPing(HOST, CLOSED_PORT, 2000);
+
+		await expect(probe).rejects.toBeInstanceOf(BridgeProbeError);
+	});
+
+	test("times out against a port that never answers", async () => {
+		const silent = await listen(null);
+
+		try {
+			const error = await probeRaknetPing(HOST, silent.port, 250).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.TimedOut);
+		} finally {
+			silent.close();
+		}
+	});
+
+	test("rejects a reply that is not a raknet pong", async () => {
+		const noisy = await listen(
+			new Uint8Array([
+				1,
+				2,
+				3,
+				4,
+				5,
+			]),
+		);
+
+		try {
+			const error = await probeRaknetPing(HOST, noisy.port, 2000).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.Malformed);
+		} finally {
+			noisy.close();
+		}
+	});
+});

package/src/probes/raknetPing.ts

@@ -0,0 +1,228 @@
+import type { BridgeRaknetPingStatus } from "../context";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
+
+const UNCONNECTED_PING = 0x01;
+
+const UNCONNECTED_PONG = 0x1c;
+
+const MAGIC = new Uint8Array([
+	0x00,
+	0xff,
+	0xff,
+	0x00,
+	0xfe,
+	0xfe,
+	0xfe,
+	0xfe,
+	0xfd,
+	0xfd,
+	0xfd,
+	0xfd,
+	0x12,
+	0x34,
+	0x56,
+	0x78,
+]);
+
+const REQUEST_BYTES = 33;
+
+const MAGIC_OFFSET = 17;
+
+const LENGTH_OFFSET = MAGIC_OFFSET + MAGIC.length;
+
+const STRING_OFFSET = LENGTH_OFFSET + 2;
+
+const MAX_RESPONSE_BYTES = 2 * 1024;
+
+const FIELD_EDITION = 0;
+
+const FIELD_MOTD = 1;
+
+const FIELD_PROTOCOL = 2;
+
+const FIELD_VERSION = 3;
+
+const FIELD_ONLINE = 4;
+
+const FIELD_MAX = 5;
+
+const FIELD_SUB_MOTD = 7;
+
+const FIELD_GAMEMODE = 8;
+
+const DECODER = new TextDecoder();
+
+const pingRequest = () => {
+	const request = new Uint8Array(REQUEST_BYTES);
+	const view = new DataView(request.buffer);
+
+	const guid = new BigUint64Array(1);
+
+	crypto.getRandomValues(guid);
+
+	request[0] = UNCONNECTED_PING;
+
+	view.setBigInt64(1, BigInt(Math.trunc(performance.timeOrigin + performance.now())), false);
+	request.set(MAGIC, 9);
+	view.setBigUint64(25, guid[0] ?? 0n, false);
+
+	return request;
+};
+
+const text = (fields: string[], index: number): string | null => {
+	const value = fields[index]?.trim();
+
+	return value !== undefined && value.length > 0 ? value : null;
+};
+
+const count = (fields: string[], index: number): number | null => {
+	const value = text(fields, index);
+
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number.parseInt(value, 10);
+
+	return Number.isFinite(parsed) ? Math.max(0, Math.trunc(parsed)) : null;
+};
+
+export const parseUnconnectedPong = (view: Uint8Array): Omit<BridgeRaknetPingStatus, "latencyMs"> => {
+	if (view.length > MAX_RESPONSE_BYTES) {
+		throw new Error("raknet pong is larger than a pong can be");
+	}
+
+	if (view.length < STRING_OFFSET || view[0] !== UNCONNECTED_PONG) {
+		throw new Error("raknet pong has an unexpected header");
+	}
+
+	if (!MAGIC.every((byte, index) => view[MAGIC_OFFSET + index] === byte)) {
+		throw new Error("raknet pong does not carry the raknet magic");
+	}
+
+	const high = view[LENGTH_OFFSET];
+	const low = view[LENGTH_OFFSET + 1];
+
+	if (high === undefined || low === undefined) {
+		throw new Error("raknet pong is truncated");
+	}
+
+	const length = (high << 8) | low;
+
+	if (view.length < STRING_OFFSET + length) {
+		throw new Error("raknet pong advertises more payload than it carries");
+	}
+
+	const fields = DECODER.decode(view.subarray(STRING_OFFSET, STRING_OFFSET + length)).split(";");
+
+	const online = count(fields, FIELD_ONLINE);
+	const max = count(fields, FIELD_MAX);
+
+	if (online === null || max === null) {
+		throw new Error("raknet pong is missing player counts");
+	}
+
+	return {
+		players: {
+			online,
+			max,
+		},
+		edition: text(fields, FIELD_EDITION),
+		motd: text(fields, FIELD_MOTD),
+		subMotd: text(fields, FIELD_SUB_MOTD),
+		version: text(fields, FIELD_VERSION),
+		protocol: count(fields, FIELD_PROTOCOL),
+		gamemode: text(fields, FIELD_GAMEMODE),
+	};
+};
+
+const probeError = (code: BridgeProbeCode, message: string, cause: unknown) => {
+	if (cause instanceof BridgeProbeError) {
+		return cause;
+	}
+
+	const detail = cause instanceof Error && cause.message.length > 0 ? `: ${cause.message}` : "";
+
+	return new BridgeProbeError(code, `${message}${detail}`);
+};
+
+export const probeRaknetPing = (host: string, hostPort: number, timeoutMs: number) => {
+	const target = `${host}:${hostPort}`;
+
+	return new Promise<BridgeRaknetPingStatus>((resolve, reject) => {
+		const startedAt = performance.now();
+
+		let socket: Awaited<ReturnType<typeof Bun.udpSocket>> | null = null;
+		let settled = false;
+
+		const finish = (outcome: Omit<BridgeRaknetPingStatus, "latencyMs"> | BridgeProbeError) => {
+			if (settled) {
+				return;
+			}
+
+			settled = true;
+
+			clearTimeout(timer);
+
+			try {
+				socket?.close();
+			} catch {}
+
+			if (outcome instanceof BridgeProbeError) {
+				reject(outcome);
+
+				return;
+			}
+
+			resolve({
+				...outcome,
+				latencyMs: Math.round(performance.now() - startedAt),
+			});
+		};
+
+		const timer = setTimeout(() => {
+			finish(new BridgeProbeError(BridgeProbeCode.TimedOut, `raknet ping to ${target} timed out`));
+		}, timeoutMs);
+
+		const handle = (view: Uint8Array) => {
+			try {
+				finish(parseUnconnectedPong(view));
+			} catch (error) {
+				finish(probeError(BridgeProbeCode.Malformed, `raknet pong from ${target} could not be read`, error));
+			}
+		};
+
+		Bun.udpSocket({
+			connect: {
+				hostname: host,
+				port: hostPort,
+			},
+			socket: {
+				data(_socket, data) {
+					handle(data);
+				},
+				error(_socket, error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `raknet ping to ${target} failed`, error));
+				},
+			},
+		})
+			.then((created) => {
+				if (settled) {
+					created.close();
+
+					return;
+				}
+
+				socket = created;
+
+				try {
+					created.send(pingRequest());
+				} catch (error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `raknet ping to ${target} could not be sent`, error));
+				}
+			})
+			.catch((error) => {
+				finish(probeError(BridgeProbeCode.Unreachable, `raknet socket for ${target} could not be opened`, error));
+			});
+	});
+};

package/src/protocol/bridgeEvents.ts

@@ -3,14 +3,18 @@ export enum BridgeEventName {
 	MemoryUndersized = "MemoryUndersized",
 	MissingDependency = "MissingDependency",
 	ModCrashed = "ModCrashed",
+	ModLoaded = "ModLoaded",
 	PlayerAdvanced = "PlayerAdvanced",
+	PlayerBanned = "PlayerBanned",
 	PlayerDied = "PlayerDied",
 	PlayerJoined = "PlayerJoined",
+	PlayerKicked = "PlayerKicked",
 	PlayerLeft = "PlayerLeft",
 	PortBindFailed = "PortBindFailed",
 	ServerCrashed = "ServerCrashed",
 	ServerStarted = "ServerStarted",
 	ServerStopping = "ServerStopping",
+	ServerUpdated = "ServerUpdated",
 	TickLagging = "TickLagging",
 	WorldCorrupt = "WorldCorrupt",
 	WorldSaved = "WorldSaved",

package/src/rcon/index.ts

@@ -0,0 +1,3 @@
+export { BridgeRconCode, BridgeRconError } from "../core";
+export * from "./sourceRcon";
+export * from "./sourceRconFrame";