@serverkgg/bridge 0.0.10 → 0.0.12

package/src/probes/minecraftPing.test.ts

@@ -0,0 +1,344 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
+import { parseStatus, probeMinecraftPing } from "./minecraftPing";
+
+const HOST = "127.0.0.1";
+
+const CLOSED_PORT = 59_441;
+
+const varInt = (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 < 5) {
+		const byte = view[offset + size];
+
+		if (byte === undefined) {
+			throw new Error("varint is truncated");
+		}
+
+		value |= (byte & 0x7f) << (7 * size);
+		size += 1;
+
+		if ((byte & 0x80) === 0) {
+			return {
+				value,
+				size,
+			};
+		}
+	}
+
+	throw new Error("varint is malformed");
+};
+
+const response = (payload: unknown, packetId = 0x00) => {
+	const json = new TextEncoder().encode(JSON.stringify(payload));
+
+	const body = [
+		...varInt(packetId),
+		...varInt(json.length),
+		...json,
+	];
+
+	return new Uint8Array([
+		...varInt(body.length),
+		...body,
+	]);
+};
+
+const status = {
+	players: {
+		online: 3,
+		max: 20,
+	},
+	version: {
+		name: "1.21.11",
+	},
+	description: "A Serverk Minecraft Server",
+};
+
+const handshakeServerName = (frame: Uint8Array) => {
+	const length = readVarInt(frame, 0);
+	const packetId = readVarInt(frame, length.size);
+	const protocol = readVarInt(frame, length.size + packetId.size);
+	const address = readVarInt(frame, length.size + packetId.size + protocol.size);
+	const start = length.size + packetId.size + protocol.size + address.size;
+
+	return new TextDecoder().decode(frame.subarray(start, start + address.value));
+};
+
+const listen = async (reply: Uint8Array | null, onServerName?: (serverName: string) => void) => {
+	return Bun.listen({
+		hostname: HOST,
+		port: 0,
+		socket: {
+			data(socket, data) {
+				if (onServerName) {
+					onServerName(handshakeServerName(data));
+				}
+
+				if (reply) {
+					socket.write(reply);
+				}
+			},
+			error() {},
+		},
+	});
+};
+
+describe("reading a status response off the wire", () => {
+	test("a complete response gives the player counts, the version and the motd", () => {
+		expect(parseStatus(response(status))).toEqual({
+			players: {
+				online: 3,
+				max: 20,
+			},
+			version: "1.21.11",
+			description: "A Serverk Minecraft Server",
+		});
+	});
+
+	test("a response longer than one packet is still read, because the frame carries its own length", () => {
+		const packet = response(status);
+		const padded = new Uint8Array(packet.length + 4);
+
+		padded.set(packet);
+
+		expect(parseStatus(padded)?.players).toEqual({
+			online: 3,
+			max: 20,
+		});
+	});
+
+	test("a modern description object is read through its text", () => {
+		expect(
+			parseStatus(
+				response({
+					...status,
+					description: {
+						text: "hello",
+					},
+				}),
+			)?.description,
+		).toBe("hello");
+	});
+
+	test("a description we cannot read is dropped rather than failing the sample", () => {
+		expect(
+			parseStatus(
+				response({
+					...status,
+					description: {
+						extra: [],
+					},
+				}),
+			)?.description,
+		).toBeNull();
+		expect(
+			parseStatus(
+				response({
+					...status,
+					description: null,
+				}),
+			)?.description,
+		).toBeNull();
+	});
+
+	test("a missing version name is dropped rather than failing the sample", () => {
+		expect(
+			parseStatus(
+				response({
+					players: status.players,
+				}),
+			)?.version,
+		).toBeNull();
+	});
+
+	test("fractional or negative counts are clamped to whole players", () => {
+		expect(
+			parseStatus(
+				response({
+					players: {
+						online: -1,
+						max: 20.7,
+					},
+				}),
+			)?.players,
+		).toEqual({
+			online: 0,
+			max: 20,
+		});
+	});
+
+	test("a response we have not fully received yet asks for more bytes", () => {
+		const packet = response(status);
+
+		expect(parseStatus(new Uint8Array(0))).toBeNull();
+		expect(parseStatus(packet.subarray(0, 1))).toBeNull();
+		expect(parseStatus(packet.subarray(0, packet.length - 4))).toBeNull();
+	});
+
+	test("a large payload whose length needs two varint bytes is read whole", () => {
+		const long = {
+			players: status.players,
+			description: "n".repeat(400),
+		};
+
+		expect(parseStatus(response(long))?.description).toBe(long.description);
+	});
+
+	test("a packet that is not a status response is refused", () => {
+		expect(() => parseStatus(response(status, 0x01))).toThrow();
+	});
+
+	test("a response with no player counts is refused, because a sample without them is a lie", () => {
+		expect(() =>
+			parseStatus(
+				response({
+					version: {
+						name: "1.21.11",
+					},
+				}),
+			),
+		).toThrow();
+	});
+});
+
+describe("probeMinecraftPing", () => {
+	test("answers with the status a listening server sends back", async () => {
+		const server = await listen(response(status));
+
+		try {
+			const sample = await probeMinecraftPing(
+				{
+					address: HOST,
+					port: server.port,
+				},
+				2000,
+			);
+
+			expect(sample.players).toEqual({
+				online: 3,
+				max: 20,
+			});
+			expect(sample.version).toBe("1.21.11");
+			expect(sample.latencyMs).toBeGreaterThanOrEqual(0);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("puts the server name in the handshake so a virtual host still answers", async () => {
+		const seen: string[] = [];
+
+		const server = await listen(response(status), (serverName) => {
+			seen.push(serverName);
+		});
+
+		try {
+			await probeMinecraftPing(
+				{
+					address: HOST,
+					port: server.port,
+					serverName: "play.example.com",
+				},
+				2000,
+			);
+
+			expect(seen.at(0)).toBe("play.example.com");
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("falls back to the address when no server name is given", async () => {
+		const seen: string[] = [];
+
+		const server = await listen(response(status), (serverName) => {
+			seen.push(serverName);
+		});
+
+		try {
+			await probeMinecraftPing(
+				{
+					address: HOST,
+					port: server.port,
+				},
+				2000,
+			);
+
+			expect(seen.at(0)).toBe(HOST);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	test("rejects as unreachable when nothing listens on the port", async () => {
+		const error = await probeMinecraftPing(
+			{
+				address: HOST,
+				port: CLOSED_PORT,
+			},
+			2000,
+		).catch((reason: unknown) => reason);
+
+		expect(error).toBeInstanceOf(BridgeProbeError);
+		expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.Unreachable);
+	});
+
+	test("times out against a port that never answers", async () => {
+		const silent = await listen(null);
+
+		try {
+			const error = await probeMinecraftPing(
+				{
+					address: HOST,
+					port: silent.port,
+				},
+				250,
+			).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.TimedOut);
+		} finally {
+			silent.stop(true);
+		}
+	});
+
+	test("rejects a reply that is not a status response", async () => {
+		const noisy = await listen(response(status, 0x01));
+
+		try {
+			const error = await probeMinecraftPing(
+				{
+					address: HOST,
+					port: noisy.port,
+				},
+				2000,
+			).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.Malformed);
+		} finally {
+			noisy.stop(true);
+		}
+	});
+});

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),
+				);
+			});
+	});
+};