@serverkgg/bridge 0.0.11 → 0.0.13

package/src/install/installStamp.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import { INSTALL_STAMP_FILE, parseStamp, readStamp, writeStamp } from "./installStamp";
+
+interface TestStamp {
+	buildId: string | null;
+	rconPassword?: string;
+}
+
+const testContext = (seed: Record<string, string> = {}) => {
+	const stored = new Map(Object.entries(seed));
+
+	const context = {
+		files: {
+			async exists(path: string) {
+				return stored.has(path);
+			},
+			async read(path: string) {
+				return stored.get(path) ?? "";
+			},
+			async write(path: string, content: string) {
+				stored.set(path, content);
+			},
+		},
+	} as unknown as BridgeContext;
+
+	return {
+		context,
+		stored,
+	};
+};
+
+describe("parseStamp", () => {
+	test("reads a json object", () => {
+		expect(
+			parseStamp<TestStamp>(
+				JSON.stringify({
+					buildId: "123",
+				}),
+			),
+		).toEqual({
+			buildId: "123",
+		});
+	});
+
+	test("returns null for anything that is not a json object", () => {
+		expect(parseStamp("")).toBeNull();
+		expect(parseStamp("{")).toBeNull();
+		expect(parseStamp("null")).toBeNull();
+		expect(parseStamp("[1,2]")).toBeNull();
+		expect(parseStamp('"text"')).toBeNull();
+	});
+});
+
+describe("readStamp", () => {
+	test("returns null when the stamp file is absent", async () => {
+		const { context } = testContext();
+
+		expect(await readStamp(context)).toBeNull();
+	});
+
+	test("reads the stamp the writer left behind", async () => {
+		const { context } = testContext();
+
+		await writeStamp<TestStamp>(context, {
+			buildId: "4711",
+			rconPassword: "secret",
+		});
+
+		expect(await readStamp<TestStamp>(context)).toEqual({
+			buildId: "4711",
+			rconPassword: "secret",
+		});
+	});
+
+	test("writes pretty json ending in a newline", async () => {
+		const { context, stored } = testContext();
+
+		await writeStamp(context, {
+			buildId: "1",
+		});
+
+		expect(stored.get(INSTALL_STAMP_FILE)).toBe('{\n  "buildId": "1"\n}\n');
+	});
+
+	test("honours a custom stamp path", async () => {
+		const { context, stored } = testContext();
+
+		await writeStamp(
+			context,
+			{
+				ready: true,
+			},
+			".serverk-wine.json",
+		);
+
+		expect(stored.has(INSTALL_STAMP_FILE)).toBe(false);
+		expect(await readStamp(context, ".serverk-wine.json")).toEqual({
+			ready: true,
+		});
+	});
+
+	test("returns null when the read fails after the file was seen", async () => {
+		const context = {
+			files: {
+				async exists() {
+					return true;
+				},
+				async read() {
+					throw new Error("vanished");
+				},
+			},
+		} as unknown as BridgeContext;
+
+		expect(await readStamp(context)).toBeNull();
+	});
+
+	test("returns null when the stamp file is corrupt", async () => {
+		const { context } = testContext({
+			[INSTALL_STAMP_FILE]: "not json",
+		});
+
+		expect(await readStamp(context)).toBeNull();
+	});
+});

package/src/install/installStamp.ts

@@ -0,0 +1,40 @@
+import type { BridgeContext } from "../context";
+
+export const INSTALL_STAMP_FILE = ".serverk-install.json";
+
+export const parseStamp = <Stamp extends object = Record<string, unknown>>(raw: string): Stamp | null => {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+			return null;
+		}
+
+		return parsed as Stamp;
+	} catch {
+		return null;
+	}
+};
+
+export const readStamp = async <Stamp extends object = Record<string, unknown>>(
+	context: BridgeContext,
+	path: string = INSTALL_STAMP_FILE,
+): Promise<Stamp | null> => {
+	if (!(await context.files.exists(path))) {
+		return null;
+	}
+
+	try {
+		return parseStamp<Stamp>(await context.files.read(path));
+	} catch {
+		return null;
+	}
+};
+
+export const writeStamp = async <Stamp extends object>(
+	context: BridgeContext,
+	stamp: Stamp,
+	path: string = INSTALL_STAMP_FILE,
+): Promise<void> => {
+	await context.files.write(path, `${JSON.stringify(stamp, null, 2)}\n`);
+};

package/src/main.ts

@@ -1,5 +1,6 @@
 export * from "./context";
 export * from "./core";
+export * from "./install";
 export * from "./modules";
 export * from "./panel";
 export * from "./runtime";

package/src/manifest/index.ts

@@ -8,4 +8,5 @@ export * from "./localized";
 export * from "./manifest";
 export * from "./presence";
 export * from "./primitives";
+export * from "./runtime";
 export * from "./source";

package/src/manifest/manifest.test.ts

@@ -1,15 +1,53 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
-import { PortJoin } from "../core";
+import { PortJoin, PortProtocol } from "../core";
 import { GameCategory } from "./category";
-import { guidePackageSchema, MANIFEST_SCHEMA_VERSION, manifestSchema, packageSchema } from "./manifest";
+import {
+	guidePackageSchema,
+	MANIFEST_SCHEMA_VERSION,
+	type Manifest,
+	manifestSchema,
+	PORT_FOLLOW_MIN_OFFSET,
+	packageSchema,
+} from "./manifest";
 import { isServerkAvatarTemplate, PRESENCE_AVATAR_LENGTH_LIMIT } from "./presence";
+import {
+	BOOT_BUDGET_MIN_MINUTES,
+	INSTALL_BUDGET_MAX_MINUTES,
+	MANIFEST_RUNTIME_DEFAULTS,
+	ManifestCapability,
+	ManifestPlatform,
+	manifestRuntimeOf,
+	PIDS_LIMIT_MIN,
+	SHM_MAX_MB,
+	WINE_MIN_SHM_MB,
+} from "./runtime";
 
 const text = (value: string) => ({
 	ar: value,
 	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",
@@ -79,6 +117,42 @@ const withPort = (extra: Record<string, unknown>) => {
 	};
 };
 
+const withPorts = (ports: unknown[]) => {
+	const manifest = base();
+
+	return {
+		...manifest,
+		container: {
+			...manifest.container,
+			ports,
+		},
+	};
+};
+
+const withRuntime = (runtime: Record<string, unknown>) => {
+	const manifest = base();
+
+	return {
+		...manifest,
+		container: {
+			...manifest.container,
+			runtime,
+		},
+	};
+};
+
+const udpPort = (key: string, containerPort: number, hostDefault: number) => ({
+	key,
+	containerPort,
+	protocol: PortProtocol.Udp,
+	hostRange: {
+		default: hostDefault,
+		min: hostDefault,
+		max: hostDefault + 99,
+	},
+	mirror: true,
+});
+
 const withPortSrv = (srv: unknown) => {
 	return withPort({
 		srv,
@@ -586,6 +660,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", () => {
@@ -718,3 +805,374 @@ describe("presence", () => {
 		expect(result.error && z.prettifyError(result.error)).toContain('"platform" is declared more than once');
 	});
 });
+
+describe("container runtime", () => {
+	test("materializes the defaults when the manifest declares no runtime", () => {
+		const manifest = manifestSchema.parse(base());
+
+		expect(manifest.container.runtime).toEqual({
+			platform: ManifestPlatform.Linux,
+			installBudgetMinutes: 15,
+			bootBudgetMinutes: 12,
+			shmMb: 64,
+			pidsLimit: 512,
+			capabilities: [],
+		});
+		expect(MANIFEST_RUNTIME_DEFAULTS).toEqual(manifest.container.runtime);
+	});
+
+	test("keeps every field a manifest declares", () => {
+		const manifest = manifestSchema.parse(
+			withRuntime({
+				platform: ManifestPlatform.Wine,
+				installBudgetMinutes: 60,
+				bootBudgetMinutes: 30,
+				shmMb: 512,
+				pidsLimit: 2048,
+				capabilities: [
+					ManifestCapability.SysNice,
+					ManifestCapability.IpcLock,
+				],
+			}),
+		);
+
+		expect(manifest.container.runtime).toEqual({
+			platform: ManifestPlatform.Wine,
+			installBudgetMinutes: 60,
+			bootBudgetMinutes: 30,
+			shmMb: 512,
+			pidsLimit: 2048,
+			capabilities: [
+				ManifestCapability.SysNice,
+				ManifestCapability.IpcLock,
+			],
+		});
+	});
+
+	test("clamps an install budget above the ceiling", () => {
+		expect(
+			failure(
+				withRuntime({
+					installBudgetMinutes: INSTALL_BUDGET_MAX_MINUTES + 1,
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.installBudgetMinutes",
+				message: `Too big: expected number to be <=${INSTALL_BUDGET_MAX_MINUTES}`,
+			},
+		]);
+	});
+
+	test("clamps a boot budget below the floor", () => {
+		expect(
+			failure(
+				withRuntime({
+					bootBudgetMinutes: BOOT_BUDGET_MIN_MINUTES - 1,
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.bootBudgetMinutes",
+				message: `Too small: expected number to be >=${BOOT_BUDGET_MIN_MINUTES}`,
+			},
+		]);
+	});
+
+	test("clamps shared memory and the pids limit to their range", () => {
+		expect(
+			failure(
+				withRuntime({
+					shmMb: SHM_MAX_MB + 1,
+					pidsLimit: PIDS_LIMIT_MIN - 1,
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.shmMb",
+				message: `Too big: expected number to be <=${SHM_MAX_MB}`,
+			},
+			{
+				path: "container.runtime.pidsLimit",
+				message: `Too small: expected number to be >=${PIDS_LIMIT_MIN}`,
+			},
+		]);
+	});
+
+	test("refuses a fourth capability", () => {
+		expect(
+			failure(
+				withRuntime({
+					capabilities: [
+						ManifestCapability.SysNice,
+						ManifestCapability.IpcLock,
+						ManifestCapability.SysPtrace,
+						ManifestCapability.SysNice,
+					],
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.capabilities",
+				message: "Too big: expected array to have <=3 items",
+			},
+		]);
+	});
+
+	test("refuses a capability outside the allow-list", () => {
+		expect(
+			failure(
+				withRuntime({
+					capabilities: [
+						"NET_ADMIN",
+					],
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.capabilities.0",
+				message: 'Invalid option: expected one of "SYS_NICE"|"IPC_LOCK"|"SYS_PTRACE"',
+			},
+		]);
+	});
+
+	test("refuses a wine platform running on the default shared memory", () => {
+		expect(
+			failure(
+				withRuntime({
+					platform: ManifestPlatform.Wine,
+				}),
+			),
+		).toEqual([
+			{
+				path: "container.runtime.shmMb",
+				message: `must be at least ${WINE_MIN_SHM_MB} when platform is "wine"`,
+			},
+		]);
+	});
+
+	test("accepts a wine platform once shared memory clears the floor", () => {
+		const manifest = manifestSchema.parse(
+			withRuntime({
+				platform: ManifestPlatform.Wine,
+				shmMb: WINE_MIN_SHM_MB,
+			}),
+		);
+
+		expect(manifest.container.runtime.shmMb).toBe(WINE_MIN_SHM_MB);
+	});
+});
+
+describe("manifestRuntimeOf", () => {
+	test("reads the runtime a manifest declares", () => {
+		const manifest = manifestSchema.parse(
+			withRuntime({
+				platform: ManifestPlatform.Wine,
+				shmMb: 512,
+			}),
+		);
+
+		expect(manifestRuntimeOf(manifest)).toEqual({
+			...MANIFEST_RUNTIME_DEFAULTS,
+			platform: ManifestPlatform.Wine,
+			shmMb: 512,
+		});
+	});
+
+	test("falls back to the defaults for a bundle published before the field existed", () => {
+		const manifest = manifestSchema.parse(base());
+		const legacy = {
+			...manifest,
+			container: {
+				image: manifest.container.image,
+				ports: manifest.container.ports,
+			},
+		} as Manifest;
+
+		expect(manifestRuntimeOf(legacy)).toEqual(MANIFEST_RUNTIME_DEFAULTS);
+	});
+});
+
+describe("port mirroring", () => {
+	test("defaults to no mirror and no follower", () => {
+		const manifest = manifestSchema.parse(base());
+
+		expect(manifest.container.ports[0]?.mirror).toBe(false);
+		expect(manifest.container.ports[0]?.follows).toBeUndefined();
+	});
+
+	test("keeps the mirror flag and the follow rule a manifest declares", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				udpPort("game", 27_015, 27_015),
+				{
+					...udpPort("query", 27_016, 27_115),
+					follows: {
+						key: "game",
+						offset: 1,
+					},
+				},
+			]),
+		);
+
+		expect(manifest.container.ports[0]?.mirror).toBe(true);
+		expect(manifest.container.ports[1]?.follows).toEqual({
+			key: "game",
+			offset: 1,
+		});
+	});
+
+	test("refuses a follow rule naming a port that is not declared", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...udpPort("game", 27_015, 27_015),
+						follows: {
+							key: "query",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.follows.key",
+				message: '"query" is not a declared port',
+			},
+		]);
+	});
+
+	test("refuses a port that follows itself", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...udpPort("game", 27_015, 27_015),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.follows.key",
+				message: 'port "game" cannot follow itself',
+			},
+		]);
+	});
+
+	test("refuses a follow rule crossing protocols", () => {
+		const [tcp] = base().container.ports;
+
+		if (!tcp) {
+			throw new Error("fixture is missing its port");
+		}
+
+		expect(
+			failure(
+				withPorts([
+					tcp,
+					{
+						...udpPort("query", 27_016, 27_115),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.key",
+				message: '"game" is a tcp port — a port only follows one of its own protocol',
+			},
+		]);
+	});
+
+	test("refuses a port that both follows and is followed", () => {
+		expect(
+			failure(
+				withPorts([
+					udpPort("game", 27_015, 27_015),
+					{
+						...udpPort("query", 27_016, 27_115),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+					{
+						...udpPort("raw", 27_017, 27_215),
+						follows: {
+							key: "query",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.key",
+				message: 'port "query" is followed by another port and cannot follow one itself',
+			},
+		]);
+	});
+
+	test("lets a follower's host range overlap the port it follows", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				udpPort("game", 27_015, 27_015),
+				{
+					...udpPort("query", 27_016, 27_016),
+					follows: {
+						key: "game",
+						offset: 1,
+					},
+				},
+			]),
+		);
+
+		expect(manifest.container.ports[1]?.hostRange.min).toBe(27_016);
+	});
+
+	test("still refuses two independent ports whose host ranges overlap", () => {
+		expect(
+			failure(
+				withPorts([
+					udpPort("game", 27_015, 27_015),
+					udpPort("query", 27_016, 27_016),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.hostRange",
+				message: 'host range overlaps port "game" — two udp ports cannot share host ports',
+			},
+		]);
+	});
+
+	test("refuses an offset outside its range", () => {
+		expect(
+			failure(
+				withPorts([
+					udpPort("game", 27_015, 27_015),
+					{
+						...udpPort("query", 27_016, 27_115),
+						follows: {
+							key: "game",
+							offset: 0,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.offset",
+				message: `Too small: expected number to be >=${PORT_FOLLOW_MIN_OFFSET}`,
+			},
+		]);
+	});
+});