@serverkgg/bridge 0.0.10 → 0.0.12

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/bridgeLimits.ts

@@ -40,6 +40,8 @@ export const BRIDGE_PENDING_FILES_LIMIT = 64;
 
 export const BRIDGE_SETUP_STEPS_LIMIT = 8;
 
+export const BRIDGE_SETUP_ACTIONS_LIMIT = 4;
+
 export const BRIDGE_ID_LENGTH_LIMIT = 32;
 
 export const BRIDGE_KEY_LENGTH_LIMIT = 64;
@@ -53,3 +55,9 @@ export const BRIDGE_PLACEHOLDER_LENGTH_LIMIT = 256;
 export const BRIDGE_STAGING_LENGTH_LIMIT = 128;
 
 export const BRIDGE_EXTENSION_LENGTH_LIMIT = 16;
+
+export const BRIDGE_PATTERN_LENGTH_LIMIT = 256;
+
+export const BRIDGE_SETUP_CODE_LENGTH_LIMIT = 64;
+
+export const BRIDGE_SETUP_DETAIL_LENGTH_LIMIT = 256;

package/src/runtime/bridgeDriver.test.ts

@@ -1155,6 +1155,11 @@ const driverWithSetup = (setup: BridgeSetupModule): BridgeDriver => ({
 						fields: [
 							field("SERVER_NAME"),
 							field("MOTD"),
+							{
+								key: "ADMIN_PASSWORD",
+								control: BridgeControl.Secret,
+								label: text("Admin password"),
+							},
 						],
 					},
 				],
@@ -1172,6 +1177,40 @@ const driverStep = (id: string) => ({
 const setupWith = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
 	kind: BridgeKind.Setup,
 	steps,
+	submit: async () => {
+		return;
+	},
+});
+
+const setupWithoutSubmit = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps,
+});
+
+const driverWithFields = (fields: BridgeField[]): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	panel: {
+		tabs: [
+			{
+				id: "settings",
+				title: text("Settings"),
+				sections: [
+					formSection("server", fields),
+				],
+			},
+		],
+	},
 });
 
 describe("the setup singleton", () => {
@@ -1370,6 +1409,58 @@ describe("the setup singleton", () => {
 		).not.toThrow();
 	});
 
+	test("takes a form step over a secret field", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "password",
+							title: text("Password"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"ADMIN_PASSWORD",
+							],
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a driver step while the setup exports no submit", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWithoutSubmit([
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).toThrow("the setup module declares a driver step but exports no submit");
+	});
+
+	test("takes a setup with no submit while every step is answered elsewhere", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWithoutSubmit([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "invite",
+							title: text("Invite"),
+							target: {
+								tab: GuideOpenTab.Access,
+							},
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
 	test("reserves the setup module id for the singleton", () => {
 		expect(() =>
 			validateDriver({
@@ -1395,3 +1486,152 @@ describe("the setup singleton", () => {
 		).toThrow('module id "setup" is reserved');
 	});
 });
+
+describe("field patterns", () => {
+	test("takes a pattern on a text field and on a secret one", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Secret,
+						label: text("Licence key"),
+						pattern: "^cfxk_\\w{1,60}_\\w{1,20}$",
+						patternHint: text("A licence key starts with cfxk_"),
+					},
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						pattern: "^.{1,32}$",
+					},
+				]),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a pattern that is not a regular expression", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: "^cfxk_(",
+					},
+				]),
+			),
+		).toThrow('declares pattern "^cfxk_(", which is not a valid regular expression');
+	});
+
+	test("takes the FiveM licence pattern, whose repeats are all bounded", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Secret,
+						label: text("Licence key"),
+						pattern: "^(?:cfxk_\\w{1,60}_\\w{1,20}|\\w{32})$",
+					},
+				]),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a pattern that repeats a group which already repeats", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: "^(a+)+$",
+					},
+				]),
+			),
+		).toThrow('declares pattern "^(a+)+$", which repeats a group that already repeats');
+	});
+
+	test("rejects a starred group whose body repeats without a bound", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						pattern: "^(\\w+\\s?)*$",
+					},
+				]),
+			),
+		).toThrow("repeats a group that already repeats");
+	});
+
+	test("rejects a pattern longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: `^${"a".repeat(256)}$`,
+					},
+				]),
+			),
+		).toThrow("pattern is 258 characters — the platform takes at most 256");
+	});
+
+	test("rejects a pattern hint with no pattern to explain", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						patternHint: text("A licence key starts with cfxk_"),
+					},
+				]),
+			),
+		).toThrow("declares a pattern hint with no pattern to explain");
+	});
+
+	test("rejects a pattern on a control that never matches one", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "WHITELIST",
+						control: BridgeControl.Boolean,
+						label: text("Whitelist"),
+						pattern: "^true$",
+					},
+				]),
+			),
+		).toThrow('declares a pattern on a "boolean" control — only text and secret controls match one');
+	});
+
+	test("rejects a secret control that offers options", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "ADMIN_PASSWORD",
+						control: BridgeControl.Secret,
+						label: text("Admin password"),
+						options: [
+							{
+								value: "letmein",
+								label: text("letmein"),
+							},
+						],
+					},
+				]),
+			),
+		).toThrow("is a secret control with options — a secret is typed, never chosen from a list");
+	});
+});