@serverkgg/bridge 0.0.12 → 0.0.13

package/src/manifest/runtime.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import type { Manifest } from "./manifest";
+
+export enum ManifestPlatform {
+	Linux = "linux",
+	Wine = "wine",
+}
+
+export enum ManifestCapability {
+	SysNice = "SYS_NICE",
+	IpcLock = "IPC_LOCK",
+	SysPtrace = "SYS_PTRACE",
+}
+
+export const INSTALL_BUDGET_MIN_MINUTES = 5;
+
+export const INSTALL_BUDGET_MAX_MINUTES = 180;
+
+export const INSTALL_BUDGET_DEFAULT_MINUTES = 15;
+
+export const BOOT_BUDGET_MIN_MINUTES = 2;
+
+export const BOOT_BUDGET_MAX_MINUTES = 60;
+
+export const BOOT_BUDGET_DEFAULT_MINUTES = 12;
+
+export const SHM_MIN_MB = 64;
+
+export const SHM_MAX_MB = 4096;
+
+export const SHM_DEFAULT_MB = 64;
+
+export const WINE_MIN_SHM_MB = 256;
+
+export const PIDS_LIMIT_MIN = 128;
+
+export const PIDS_LIMIT_MAX = 4096;
+
+export const PIDS_LIMIT_DEFAULT = 512;
+
+export const MANIFEST_CAPABILITIES_LIMIT = 3;
+
+export const manifestRuntimeSchema = z.object({
+	platform: z.enum(ManifestPlatform).default(ManifestPlatform.Linux).meta({
+		description:
+			"Whether the game binary is a Linux executable or a Windows one the image runs through Wine or Proton.",
+	}),
+	installBudgetMinutes: z
+		.int()
+		.min(INSTALL_BUDGET_MIN_MINUTES)
+		.max(INSTALL_BUDGET_MAX_MINUTES)
+		.default(INSTALL_BUDGET_DEFAULT_MINUTES)
+		.meta({
+			description: "How long the first install may take before the platform gives up on it, in minutes.",
+		}),
+	bootBudgetMinutes: z
+		.int()
+		.min(BOOT_BUDGET_MIN_MINUTES)
+		.max(BOOT_BUDGET_MAX_MINUTES)
+		.default(BOOT_BUDGET_DEFAULT_MINUTES)
+		.meta({
+			description: "How long the game may take to report itself running after the install, in minutes.",
+		}),
+	shmMb: z
+		.int()
+		.min(SHM_MIN_MB)
+		.max(SHM_MAX_MB)
+		.default(SHM_DEFAULT_MB)
+		.meta({
+			description: `Size of /dev/shm inside the container, in MB. Wine and Proton games need at least ${WINE_MIN_SHM_MB}.`,
+		}),
+	pidsLimit: z.int().min(PIDS_LIMIT_MIN).max(PIDS_LIMIT_MAX).default(PIDS_LIMIT_DEFAULT).meta({
+		description: "How many processes and threads the container may hold at once.",
+	}),
+	capabilities: z.array(z.enum(ManifestCapability)).max(MANIFEST_CAPABILITIES_LIMIT).default([]).meta({
+		description: "Linux capabilities added back on top of the dropped set, from the allow-list this schema declares.",
+	}),
+});
+
+export type ManifestRuntime = z.infer<typeof manifestRuntimeSchema>;
+
+export const MANIFEST_RUNTIME_DEFAULTS: ManifestRuntime = manifestRuntimeSchema.parse({});
+
+export const manifestRuntimeOf = (manifest: Manifest): ManifestRuntime => {
+	return {
+		...MANIFEST_RUNTIME_DEFAULTS,
+		...manifest.container.runtime,
+	};
+};

package/src/net/index.ts

@@ -0,0 +1,2 @@
+export * from "./loopback";
+export * from "./loopbackMethod";

package/src/net/loopback.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeNetError } from "../core";
+import { loopbackJson, loopbackText } from "./loopback";
+import { LoopbackMethod } from "./loopbackMethod";
+
+const serve = (handler: (request: Request) => Response | Promise<Response>) => {
+	return Bun.serve({
+		hostname: "127.0.0.1",
+		port: 0,
+		fetch: handler,
+	});
+};
+
+describe("loopbackJson", () => {
+	test("reads a json body from a loopback server", async () => {
+		const server = serve(() =>
+			Response.json({
+				online: 3,
+			}),
+		);
+
+		try {
+			expect(
+				await loopbackJson<{
+					online: number;
+				}>(`http://127.0.0.1:${server.port}/state`),
+			).toEqual({
+				online: 3,
+			});
+		} finally {
+			await server.stop(true);
+		}
+	});
+
+	test("sends the method, headers and body it is given", async () => {
+		let seen = "";
+
+		const server = serve(async (request) => {
+			seen = `${request.method} ${request.headers.get("x-token") ?? ""} ${await request.text()}`;
+
+			return Response.json({
+				ok: true,
+			});
+		});
+
+		try {
+			await loopbackJson(`http://127.0.0.1:${server.port}/run`, {
+				method: LoopbackMethod.Post,
+				headers: {
+					"x-token": "abc",
+				},
+				body: '{"command":"save"}',
+			});
+
+			expect(seen).toBe('POST abc {"command":"save"}');
+		} finally {
+			await server.stop(true);
+		}
+	});
+
+	test("raises a net error carrying the status when the server refuses", async () => {
+		const server = serve(
+			() =>
+				new Response("nope", {
+					status: 401,
+				}),
+		);
+
+		try {
+			const error = await loopbackJson(`http://127.0.0.1:${server.port}/`).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeNetError);
+			expect((error as BridgeNetError).status).toBe(401);
+		} finally {
+			await server.stop(true);
+		}
+	});
+
+	test("raises a net error when the body is not json", async () => {
+		const server = serve(() => new Response("not json"));
+
+		try {
+			const error = await loopbackJson(`http://127.0.0.1:${server.port}/`).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeNetError);
+			expect((error as BridgeNetError).status).toBeNull();
+		} finally {
+			await server.stop(true);
+		}
+	});
+
+	test("times out against a server that never answers", async () => {
+		const server = serve(async () => {
+			await Bun.sleep(600);
+
+			return new Response("late");
+		});
+
+		try {
+			const error = await loopbackText(`http://127.0.0.1:${server.port}/`, {
+				timeoutMs: 150,
+			}).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeNetError);
+		} finally {
+			await server.stop(true);
+		}
+	});
+});
+
+describe("loopback guard", () => {
+	test("refuses a host that is not loopback", async () => {
+		for (const url of [
+			"https://api.curseforge.com/v1",
+			"http://10.0.0.5:8080/",
+			"http://127.0.0.1.evil.test/",
+		]) {
+			const error = await loopbackText(url).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeNetError);
+			expect((error as BridgeNetError).message).toContain("is not a loopback host");
+		}
+	});
+
+	test("refuses a scheme that is not http", async () => {
+		const error = await loopbackText("file:///etc/passwd").catch((reason: unknown) => reason);
+
+		expect(error).toBeInstanceOf(BridgeNetError);
+		expect((error as BridgeNetError).message).toContain("is not an http url");
+	});
+
+	test("refuses a header carrying a line break", async () => {
+		const error = await loopbackText("http://127.0.0.1:1/", {
+			headers: {
+				"x-token": "a\r\nx-admin: yes",
+			},
+		}).catch((reason: unknown) => reason);
+
+		expect(error).toBeInstanceOf(BridgeNetError);
+		expect((error as BridgeNetError).message).toContain("line break");
+	});
+
+	test("accepts localhost", async () => {
+		const server = serve(() => new Response("pong"));
+
+		try {
+			expect(await loopbackText(`http://localhost:${server.port}/`)).toBe("pong");
+		} finally {
+			await server.stop(true);
+		}
+	});
+});

package/src/net/loopback.ts

@@ -0,0 +1,109 @@
+import { BridgeNetError } from "../core";
+import { LoopbackMethod } from "./loopbackMethod";
+
+const LOOPBACK_TIMEOUT_MS = 10_000;
+
+const LOOPBACK_HOSTS = [
+	"127.0.0.1",
+	"localhost",
+	"::1",
+	"[::1]",
+];
+
+const LINE_BREAK = /[\r\n]/;
+
+export interface LoopbackOptions {
+	method?: LoopbackMethod;
+	headers?: Record<string, string>;
+	body?: string;
+	timeoutMs?: number;
+	insecureTls?: boolean;
+}
+
+const loopbackUrl = (url: string) => {
+	let remote: URL;
+
+	try {
+		remote = new URL(url);
+	} catch {
+		throw new BridgeNetError(null, `"${url}" is not a url`);
+	}
+
+	if (remote.protocol !== "http:" && remote.protocol !== "https:") {
+		throw new BridgeNetError(null, `${remote.protocol} is not an http url`);
+	}
+
+	if (!LOOPBACK_HOSTS.includes(remote.hostname.toLowerCase())) {
+		throw new BridgeNetError(null, `${remote.hostname} is not a loopback host`);
+	}
+
+	return remote;
+};
+
+const loopbackHeaders = (headers: Record<string, string> = {}) => {
+	const checked: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(headers)) {
+		if (LINE_BREAK.test(key) || LINE_BREAK.test(value)) {
+			throw new BridgeNetError(null, "a header contains a line break");
+		}
+
+		checked[key] = value;
+	}
+
+	return checked;
+};
+
+const loopbackFetch = async (url: string, options: LoopbackOptions) => {
+	const remote = loopbackUrl(url);
+	const method = options.method ?? LoopbackMethod.Get;
+	const body = method === LoopbackMethod.Get || method === LoopbackMethod.Delete ? null : (options.body ?? null);
+
+	let response: Response;
+
+	try {
+		response = await fetch(remote, {
+			method,
+			headers: loopbackHeaders(options.headers),
+			...(body === null
+				? {}
+				: {
+						body,
+					}),
+			signal: AbortSignal.timeout(options.timeoutMs ?? LOOPBACK_TIMEOUT_MS),
+			...(options.insecureTls === true
+				? {
+						tls: {
+							rejectUnauthorized: false,
+						},
+					}
+				: {}),
+		});
+	} catch (error) {
+		const detail = error instanceof Error && error.message.length > 0 ? ` — ${error.message}` : "";
+
+		throw new BridgeNetError(null, `${remote.host} could not be reached${detail}`);
+	}
+
+	if (!response.ok) {
+		await response.text();
+
+		throw new BridgeNetError(response.status, `${remote.host} answered ${response.status}`);
+	}
+
+	return response;
+};
+
+export const loopbackText = async (url: string, options: LoopbackOptions = {}): Promise<string> => {
+	return await (await loopbackFetch(url, options)).text();
+};
+
+export const loopbackJson = async <Result>(url: string, options: LoopbackOptions = {}): Promise<Result> => {
+	const text = await loopbackText(url, options);
+
+	try {
+		return JSON.parse(text) as Result;
+	} catch {
+		throw new BridgeNetError(null, `${new URL(url).host} did not answer with json`);
+	}
+};

package/src/net/loopbackMethod.ts

@@ -0,0 +1,7 @@
+export enum LoopbackMethod {
+	Delete = "DELETE",
+	Get = "GET",
+	Patch = "PATCH",
+	Post = "POST",
+	Put = "PUT",
+}

package/src/presence/index.ts

@@ -0,0 +1 @@
+export * from "./rosterSync";

package/src/presence/rosterSync.test.ts

@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import type { BridgeValues } from "../core";
+import { BridgeEventName } from "../protocol";
+import { createRosterSync } from "./rosterSync";
+
+interface Player {
+	id: string;
+	name: string;
+}
+
+interface Emitted {
+	event: string;
+	payload: BridgeValues | undefined;
+}
+
+const emitted: Emitted[] = [];
+
+const context = {
+	emit(event: string, payload?: BridgeValues) {
+		emitted.push({
+			event,
+			payload,
+		});
+	},
+} as unknown as BridgeContext;
+
+const roster = () => {
+	return createRosterSync<Player>({
+		id: (player) => player.id,
+		presenceOf: (player) => {
+			return {
+				player: player.name,
+				steamId: player.id,
+			};
+		},
+	});
+};
+
+beforeEach(() => {
+	emitted.length = 0;
+});
+
+describe("createRosterSync", () => {
+	test("emits a join for every player of the first sample", () => {
+		const sync = roster();
+
+		sync.sync(context, [
+			{
+				id: "1",
+				name: "sara",
+			},
+			{
+				id: "2",
+				name: "omar",
+			},
+		]);
+
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.PlayerJoined,
+				payload: {
+					player: "sara",
+					steamId: "1",
+				},
+			},
+			{
+				event: BridgeEventName.PlayerJoined,
+				payload: {
+					player: "omar",
+					steamId: "2",
+				},
+			},
+		]);
+	});
+
+	test("stays quiet while the roster does not change", () => {
+		const sync = roster();
+		const rows = [
+			{
+				id: "1",
+				name: "sara",
+			},
+		];
+
+		sync.sync(context, rows);
+		emitted.length = 0;
+		sync.sync(context, rows);
+
+		expect(emitted).toEqual([]);
+	});
+
+	test("emits a leave carrying the presence the player had", () => {
+		const sync = roster();
+
+		sync.sync(context, [
+			{
+				id: "1",
+				name: "sara",
+			},
+		]);
+		emitted.length = 0;
+		sync.sync(context, []);
+
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.PlayerLeft,
+				payload: {
+					player: "sara",
+					steamId: "1",
+				},
+			},
+		]);
+	});
+
+	test("emits both sides of a swap in one sample", () => {
+		const sync = roster();
+
+		sync.sync(context, [
+			{
+				id: "1",
+				name: "sara",
+			},
+		]);
+		emitted.length = 0;
+		sync.sync(context, [
+			{
+				id: "2",
+				name: "omar",
+			},
+		]);
+
+		expect(emitted.map((entry) => entry.event)).toEqual([
+			BridgeEventName.PlayerJoined,
+			BridgeEventName.PlayerLeft,
+		]);
+	});
+
+	test("reports who it believes is online", () => {
+		const sync = roster();
+
+		sync.sync(context, [
+			{
+				id: "1",
+				name: "sara",
+			},
+		]);
+
+		expect(sync.online()).toEqual([
+			{
+				id: "1",
+				name: "sara",
+			},
+		]);
+
+		sync.clear();
+
+		expect(sync.online()).toEqual([]);
+	});
+
+	test("emits a fresh join after a clear", () => {
+		const sync = roster();
+		const rows = [
+			{
+				id: "1",
+				name: "sara",
+			},
+		];
+
+		sync.sync(context, rows);
+		sync.clear();
+		emitted.length = 0;
+		sync.sync(context, rows);
+
+		expect(emitted.map((entry) => entry.event)).toEqual([
+			BridgeEventName.PlayerJoined,
+		]);
+	});
+});

package/src/presence/rosterSync.ts

@@ -0,0 +1,57 @@
+import type { BridgeContext } from "../context";
+import type { BridgeValues } from "../core";
+import { BridgeEventName } from "../protocol";
+
+export interface RosterSyncOptions<Row> {
+	id(row: Row): string;
+	presenceOf(row: Row): BridgeValues;
+}
+
+export interface RosterSync<Row> {
+	sync(context: BridgeContext, rows: Row[]): void;
+	clear(): void;
+	online(): Row[];
+}
+
+export const createRosterSync = <Row>(options: RosterSyncOptions<Row>): RosterSync<Row> => {
+	const present = new Map<string, Row>();
+
+	return {
+		sync(context, rows) {
+			const current = new Map(
+				rows.map((row) => [
+					options.id(row),
+					row,
+				]),
+			);
+
+			for (const [id, row] of current) {
+				if (!present.has(id)) {
+					context.emit(BridgeEventName.PlayerJoined, options.presenceOf(row));
+				}
+			}
+
+			for (const [id, row] of present) {
+				if (!current.has(id)) {
+					context.emit(BridgeEventName.PlayerLeft, options.presenceOf(row));
+				}
+			}
+
+			present.clear();
+
+			for (const [id, row] of current) {
+				present.set(id, row);
+			}
+		},
+
+		clear() {
+			present.clear();
+		},
+
+		online() {
+			return [
+				...present.values(),
+			];
+		},
+	};
+};

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";