@serverkgg/bridge 0.0.11 → 0.0.13

package/src/manifest/manifest.ts

@@ -16,8 +16,10 @@ import {
 	zHostPort,
 	zImageReference,
 	zPort,
+	zPortKey,
 	zSlug,
 } from "./primitives";
+import { ManifestPlatform, manifestRuntimeSchema, WINE_MIN_SHM_MB } from "./runtime";
 
 export const MANIFEST_SCHEMA_VERSION = "serverk.gg/v1";
 
@@ -50,12 +52,19 @@ const manifestPortActivationSchema = z
 
 export type ManifestPortActivation = z.infer<typeof manifestPortActivationSchema>;
 
+export const PORT_FOLLOW_MIN_OFFSET = 1;
+
+export const PORT_FOLLOW_MAX_OFFSET = 16;
+
+const manifestPortFollowSchema = z.object({
+	key: zPortKey,
+	offset: z.int().min(PORT_FOLLOW_MIN_OFFSET).max(PORT_FOLLOW_MAX_OFFSET),
+});
+
+export type ManifestPortFollow = z.infer<typeof manifestPortFollowSchema>;
+
 const manifestPortSchema = z.object({
-	key: z
-		.string()
-		.min(1)
-		.max(32)
-		.regex(/^[a-z][a-z0-9-]*$/, "must be lowercase letters, digits and dashes, starting with a letter"),
+	key: zPortKey,
 	containerPort: zPort,
 	protocol: z.enum(PortProtocol).default(PortProtocol.Tcp),
 	hostRange: manifestHostRangeSchema,
@@ -83,16 +92,47 @@ const manifestPortSchema = z.object({
 		description:
 			"Conditions on the server's variables that must all hold for the game to listen on this port. The port is still allocated; the panel hides the address otherwise.",
 	}),
+	mirror: z.boolean().default(false).meta({
+		description:
+			"Binds the allocated host port as the container port too, so the game advertises the number players dial. Declare it when the game reports its own port to a master server or an A2S client.",
+	}),
+	follows: manifestPortFollowSchema.optional().meta({
+		description:
+			"Allocates this port at the named port's host port plus the offset, for games that derive one port from another. The named port must use the same protocol.",
+	}),
 });
 
 export type ManifestPort = z.infer<typeof manifestPortSchema>;
 
-const manifestContainerSchema = z.object({
-	image: zImageReference.meta({
-		description: `Image repository, always "${IMAGE_NAMESPACE}/" followed by metadata.id.`,
-	}),
-	ports: z.array(manifestPortSchema).min(1).max(8),
-});
+const manifestContainerSchema = z
+	.object({
+		image: zImageReference.meta({
+			description: `Image repository, always "${IMAGE_NAMESPACE}/" followed by metadata.id.`,
+		}),
+		ports: z.array(manifestPortSchema).min(1).max(8),
+		runtime: manifestRuntimeSchema.prefault({}).meta({
+			description: "How the container is built and how long the platform waits for it.",
+		}),
+	})
+	.check((ctx) => {
+		if (ctx.issues.length > 0) {
+			return;
+		}
+
+		const { runtime } = ctx.value;
+
+		if (runtime.platform === ManifestPlatform.Wine && runtime.shmMb < WINE_MIN_SHM_MB) {
+			ctx.issues.push({
+				code: "custom",
+				message: `must be at least ${WINE_MIN_SHM_MB} when platform is "${ManifestPlatform.Wine}"`,
+				input: runtime.shmMb,
+				path: [
+					"runtime",
+					"shmMb",
+				],
+			});
+		}
+	});
 
 const manifestMetadataSchema = z.object({
 	id: zSlug.meta({
@@ -228,6 +268,91 @@ const hostRangesOverlap = (a: ManifestPort, b: ManifestPort) => {
 	return a.hostRange.min <= b.hostRange.max && b.hostRange.min <= a.hostRange.max;
 };
 
+const followLeaderKey = (port: ManifestPort) => {
+	return port.follows?.key ?? port.key;
+};
+
+const sameFollowGroup = (a: ManifestPort, b: ManifestPort) => {
+	if (!a.follows && !b.follows) {
+		return false;
+	}
+
+	return followLeaderKey(a) === followLeaderKey(b);
+};
+
+const followIssues = (ports: ManifestPort[]): CheckIssue[] => {
+	const issues: CheckIssue[] = [];
+	const byKey = new Map(
+		ports.map((port) => [
+			port.key,
+			port,
+		]),
+	);
+	const followed = new Set(ports.map((port) => port.follows?.key).filter((key): key is string => key !== undefined));
+
+	ports.forEach((port, index) => {
+		const follows = port.follows;
+
+		if (!follows) {
+			return;
+		}
+
+		const path = [
+			"container",
+			"ports",
+			index,
+			"follows",
+			"key",
+		];
+
+		if (follows.key === port.key) {
+			issues.push({
+				code: "custom",
+				message: `port "${port.key}" cannot follow itself`,
+				input: follows.key,
+				path,
+			});
+
+			return;
+		}
+
+		const leader = byKey.get(follows.key);
+
+		if (!leader) {
+			issues.push({
+				code: "custom",
+				message: `"${follows.key}" is not a declared port`,
+				input: follows.key,
+				path,
+			});
+
+			return;
+		}
+
+		if (leader.protocol !== port.protocol) {
+			issues.push({
+				code: "custom",
+				message: `"${follows.key}" is a ${leader.protocol} port — a port only follows one of its own protocol`,
+				input: follows.key,
+				path,
+			});
+
+			return;
+		}
+
+		if (followed.has(port.key)) {
+			issues.push({
+				code: "custom",
+				message: `port "${port.key}" is followed by another port and cannot follow one itself`,
+				input: follows.key,
+				path,
+			});
+		}
+	});
+
+	return issues;
+};
+
 const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 	const issues = duplicateIssues(
 		ports,
@@ -246,7 +371,7 @@ const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 			const a = ports[index];
 			const b = ports[other];
 
-			if (!a || !b || a.protocol !== b.protocol || !hostRangesOverlap(a, b)) {
+			if (!a || !b || a.protocol !== b.protocol || !hostRangesOverlap(a, b) || sameFollowGroup(a, b)) {
 				continue;
 			}
 
@@ -264,7 +389,10 @@ const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 		}
 	}
 
-	return issues;
+	return [
+		...issues,
+		...followIssues(ports),
+	];
 };
 
 const guideIssues = (guideTags: GuideTag[], guides: GuideEntry[]): CheckIssue[] => {

package/src/manifest/primitives.ts

@@ -20,6 +20,12 @@ export const zHostPort = z
 
 export const zHexColor = z.stringFormat("hexColor", /^#[0-9a-fA-F]{6}$/, "must be a six-digit hex colour like #4a8fd4");
 
+export const zPortKey = z
+	.string()
+	.min(1)
+	.max(32)
+	.regex(/^[a-z][a-z0-9-]*$/, "must be lowercase letters, digits and dashes, starting with a letter");
+
 export const zEnvKey = z
 	.string()
 	.min(2)

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