@serverkgg/bridge 0.0.12 → 0.0.13

package/src/manifest/manifest.test.ts

@@ -1,9 +1,27 @@
 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,
@@ -99,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,
@@ -751,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}`,
+			},
+		]);
+	});
+});

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)