@serverkgg/bridge 0.0.11 → 0.0.12

package/src/guides/compile.ts

@@ -52,49 +52,65 @@ const compileTags = (guideTags: GuideTag[], tags: string[]): CompiledGuideTag[]
 	});
 };
 
-export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entries: GuideEntry[]): GuidePack => {
-	const drafts: DraftGuide[] = [];
+export interface MarkdownBodyReader {
+	files: string[];
+	commands: string[];
+	images: Map<string, GuideImageAsset>;
+	read(path: string, text?: string): ParsedBlock[];
+}
+
+export const markdownBodyReader = (source: PackageSource): MarkdownBodyReader => {
 	const files: string[] = [];
 	const commands: string[] = [];
-	const imageByPath = new Map<string, GuideImageAsset>();
+	const images = new Map<string, GuideImageAsset>();
 
-	const readBody = (path: string) => {
-		const body = source.read(path);
+	return {
+		files,
+		commands,
+		images,
+		read(path, text) {
+			const body = source.read(path);
 
-		if (!body) {
-			throw new Error(`missing guide body ${path}`);
-		}
+			if (!body) {
+				throw new Error(`missing markdown body ${path}`);
+			}
 
-		files.push(path);
+			files.push(path);
 
-		const parsed = parseGuideMarkdown(path, new TextDecoder().decode(body));
+			const parsed = parseGuideMarkdown(path, text ?? new TextDecoder().decode(body));
 
-		commands.push(...parsed.commands);
+			commands.push(...parsed.commands);
 
-		for (const imagePath of parsed.images) {
-			if (imageByPath.has(imagePath)) {
-				continue;
-			}
+			for (const imagePath of parsed.images) {
+				if (images.has(imagePath)) {
+					continue;
+				}
 
-			const imageBytes = source.read(imagePath);
+				const imageBytes = source.read(imagePath);
 
-			if (!imageBytes) {
-				throw new Error(`missing guide image ${imagePath}`);
-			}
+				if (!imageBytes) {
+					throw new Error(`missing guide image ${imagePath}`);
+				}
 
-			const verified = verifyAsset(imagePath, imageBytes);
+				const verified = verifyAsset(imagePath, imageBytes);
 
-			imageByPath.set(imagePath, {
-				path: imagePath,
-				bytes: imageBytes,
-				mediaType: verified.mediaType,
-				width: verified.dimensions?.width ?? null,
-				height: verified.dimensions?.height ?? null,
-			});
-		}
+				images.set(imagePath, {
+					path: imagePath,
+					bytes: imageBytes,
+					mediaType: verified.mediaType,
+					width: verified.dimensions?.width ?? null,
+					height: verified.dimensions?.height ?? null,
+				});
+			}
 
-		return parsed.blocks;
+			return parsed.blocks;
+		},
 	};
+};
+
+export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entries: GuideEntry[]): GuidePack => {
+	const drafts: DraftGuide[] = [];
+	const reader = markdownBodyReader(source);
 
 	for (const entry of entries) {
 		drafts.push({
@@ -105,8 +121,8 @@ export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entr
 			surfaces: entry.surfaces,
 			videoId: entry.video ?? null,
 			body: {
-				ar: readBody(entry.bodyPath.ar),
-				en: readBody(entry.bodyPath.en),
+				ar: reader.read(entry.bodyPath.ar),
+				en: reader.read(entry.bodyPath.en),
 			},
 		});
 	}
@@ -114,13 +130,13 @@ export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entr
 	return {
 		drafts,
 		files: [
-			...files,
-			...imageByPath.keys(),
+			...reader.files,
+			...reader.images.keys(),
 		],
 		images: [
-			...imageByPath.values(),
+			...reader.images.values(),
 		],
-		commands,
+		commands: reader.commands,
 	};
 };
 
@@ -142,10 +158,7 @@ export interface ResolvedGuideImage {
 	height: number | null;
 }
 
-export const resolveGuideImages = (
-	drafts: DraftGuide[],
-	resolved: Map<string, ResolvedGuideImage>,
-): CompiledGuide[] => {
+export const resolveGuideBlocks = (blocks: ParsedBlock[], resolved: Map<string, ResolvedGuideImage>): GuideBlock[] => {
 	const resolveLeaf = (block: ParsedLeafBlock): GuideLeafBlock => {
 		if (block.type !== "image") {
 			return block;
@@ -166,27 +179,30 @@ export const resolveGuideImages = (
 		};
 	};
 
-	const resolveBlocks = (blocks: ParsedBlock[]): GuideBlock[] => {
-		return blocks.map((block) => {
-			if (block.type !== "conditional") {
-				return resolveLeaf(block);
-			}
+	return blocks.map((block) => {
+		if (block.type !== "conditional") {
+			return resolveLeaf(block);
+		}
 
-			return {
-				type: "conditional",
-				key: block.key,
-				when: block.when.map(resolveLeaf),
-				otherwise: block.otherwise.map(resolveLeaf),
-			};
-		});
-	};
+		return {
+			type: "conditional",
+			key: block.key,
+			when: block.when.map(resolveLeaf),
+			otherwise: block.otherwise.map(resolveLeaf),
+		};
+	});
+};
 
+export const resolveGuideImages = (
+	drafts: DraftGuide[],
+	resolved: Map<string, ResolvedGuideImage>,
+): CompiledGuide[] => {
 	return drafts.map((draft) => {
 		return compiledGuideSchema.parse({
 			...draft,
 			body: {
-				ar: resolveBlocks(draft.body.ar),
-				en: resolveBlocks(draft.body.en),
+				ar: resolveGuideBlocks(draft.body.ar, resolved),
+				en: resolveGuideBlocks(draft.body.en, resolved),
 			},
 		});
 	});

package/src/manifest/manifest.test.ts

@@ -10,6 +10,26 @@ const text = (value: string) => ({
 	en: value,
 });
 
+const guide = (id: string, extra: Record<string, unknown> = {}) => ({
+	id,
+	title: text(id),
+	summary: text(id),
+	bodyPath: {
+		ar: `guides/${id}/ar.md`,
+		en: `guides/${id}/en.md`,
+	},
+	...extra,
+});
+
+const guidePackage = (guides: unknown[]) => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: "GuidePackage",
+	metadata: {
+		id: "platform",
+	},
+	guides,
+});
+
 const base = () => ({
 	schemaVersion: MANIFEST_SCHEMA_VERSION,
 	kind: "GamePackage",
@@ -586,6 +606,19 @@ describe("packageSchema", () => {
 		expect(result.success).toBe(false);
 		expect(result.error && z.prettifyError(result.error)).toContain('tag "start" is not declared in guideTags');
 	});
+
+	test("carries up to 64 guides", () => {
+		const many = (count: number) =>
+			Array.from(
+				{
+					length: count,
+				},
+				(_, index) => guide(`guide-${index}`),
+			);
+
+		expect(guidePackageSchema.safeParse(guidePackage(many(64))).success).toBe(true);
+		expect(guidePackageSchema.safeParse(guidePackage(many(65))).success).toBe(false);
+	});
 });
 
 describe("presence", () => {

package/src/probes/index.ts

@@ -1 +1,10 @@
+export type {
+	BridgeA2sInfo,
+	BridgeMinecraftPingStatus,
+	BridgePingPlayers,
+	BridgeRaknetPingStatus,
+} from "../context";
+export { BridgeProbeCode, BridgeProbeError } from "../core";
 export * from "./a2s";
+export * from "./minecraftPing";
+export * from "./raknetPing";

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