@serverkgg/bridge 0.0.21 → 0.1.2

package/src/manifest/manifest.test.ts

@@ -1,14 +1,21 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
-import { PortJoin, PortProtocol } from "../core";
+import { PORT_BLOCK_MAX_COUNT, PortJoin, PortProtocol } from "../core";
 import { GameCategory } from "./category";
+import { buildJsonSchema } from "./jsonSchema";
+import { PackageKind } from "./kind";
 import {
+	botManifestSchema,
+	gameManifestSchema,
 	guidePackageSchema,
+	isBotManifest,
+	isGameManifest,
 	MANIFEST_SCHEMA_VERSION,
 	type Manifest,
 	manifestSchema,
 	PORT_FOLLOW_MIN_OFFSET,
 	packageSchema,
+	runnablePackageSchema,
 } from "./manifest";
 import { isServerkAvatarTemplate, PRESENCE_AVATAR_LENGTH_LIMIT } from "./presence";
 import {
@@ -22,6 +29,7 @@ import {
 	SHM_MAX_MB,
 	WINE_MIN_SHM_MB,
 } from "./runtime";
+import { MANIFEST_FILE, type PackageSource, readPackage } from "./source";
 
 const text = (value: string) => ({
 	ar: value,
@@ -610,7 +618,7 @@ describe("packageSchema", () => {
 	test("routes on kind without a separate pre-parse", () => {
 		const game = packageSchema.parse(base());
 
-		expect(game.kind).toBe("GamePackage");
+		expect(game.kind).toBe(PackageKind.Game);
 
 		const guides = packageSchema.parse({
 			schemaVersion: MANIFEST_SCHEMA_VERSION,
@@ -631,7 +639,7 @@ describe("packageSchema", () => {
 			],
 		});
 
-		expect(guides.kind).toBe("GuidePackage");
+		expect(guides.kind).toBe(PackageKind.Guide);
 	});
 
 	test("guide packages get the same guide checks", () => {
@@ -1176,3 +1184,622 @@ describe("port mirroring", () => {
 		]);
 	});
 });
+
+describe("port pairs and blocks", () => {
+	const pairPort = (key: string, port: number) => ({
+		...udpPort(key, port, port),
+		protocol: PortProtocol.TcpUdp,
+	});
+
+	const blockPort = (key: string, first: number, count: number) => ({
+		key,
+		containerPort: first,
+		protocol: PortProtocol.Udp,
+		mirror: true,
+		count,
+		hostRange: {
+			default: first,
+			min: first,
+			max: first + 959,
+		},
+	});
+
+	test("defaults a port to a single binding", () => {
+		const manifest = manifestSchema.parse(base());
+
+		expect(manifest.container.ports[0]?.count).toBe(1);
+	});
+
+	test("accepts a tcp+udp join port beside a udp media block", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				pairPort("game", 19_132),
+				blockPort("media", 20_000, 32),
+			]),
+		);
+
+		expect(
+			manifest.container.ports.map((port) => [
+				port.protocol,
+				port.count,
+			]),
+		).toEqual([
+			[
+				PortProtocol.TcpUdp,
+				1,
+			],
+			[
+				PortProtocol.Udp,
+				32,
+			],
+		]);
+	});
+
+	test("refuses a count above the block limit", () => {
+		expect(
+			failure(
+				withPorts([
+					blockPort("media", 20_000, PORT_BLOCK_MAX_COUNT + 1),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.count",
+				message: `Too big: expected number to be <=${PORT_BLOCK_MAX_COUNT}`,
+			},
+		]);
+	});
+
+	test("refuses a block whose host range cannot hold it", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...blockPort("media", 20_000, 32),
+						hostRange: {
+							default: 20_000,
+							min: 20_000,
+							max: 20_015,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.hostRange",
+				message: "must span at least 32 ports to hold the block",
+			},
+		]);
+	});
+
+	const spanning = (key: string, min: number, max: number, count: number) => ({
+		...blockPort(key, min, count),
+		hostRange: {
+			default: min,
+			min,
+			max,
+		},
+	});
+
+	test("lets a single port span the whole cap", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				spanning("game", 20_000, 20_999, 1),
+			]),
+		);
+
+		expect(manifest.container.ports[0]?.hostRange.max).toBe(20_999);
+	});
+
+	test("refuses a single port spanning one more than the cap", () => {
+		expect(
+			failure(
+				withPorts([
+					spanning("game", 20_000, 21_000, 1),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.hostRange",
+				message: "must span at most 1000 ports",
+			},
+		]);
+	});
+
+	test("counts the span of a block in slots, so 100 slots of 64 pass", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				spanning("media", 20_000, 26_399, 64),
+			]),
+		);
+
+		expect(manifest.container.ports[0]?.count).toBe(64);
+	});
+
+	test("refuses a block spanning more slots than the cap", () => {
+		expect(
+			failure(
+				withPorts([
+					spanning("media", 20_000, 22_000, 2),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.hostRange",
+				message: "must span at most 1000 slots of 2 ports",
+			},
+		]);
+	});
+
+	test("refuses a block whose default leaves no room for the whole block", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...blockPort("media", 20_000, 32),
+						hostRange: {
+							default: 20_950,
+							min: 20_000,
+							max: 20_959,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.hostRange.default",
+				message: "default must leave room for all 32 ports before max",
+			},
+		]);
+	});
+
+	test("refuses a non-mirrored block that runs past the last port", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...blockPort("media", 20_000, 32),
+						mirror: false,
+						containerPort: 65_520,
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.containerPort",
+				message: "a block of 32 ports starting here runs past 65535",
+			},
+		]);
+	});
+
+	test("refuses the player-address fields on a block", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...blockPort("media", 20_000, 32),
+						name: text("Media"),
+						hint: text("Nobody types this"),
+						join: PortJoin.Separate,
+						srv: {
+							service: "_minecraft",
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.name",
+				message: "a block of 32 ports is never a player address and takes no name",
+			},
+			{
+				path: "container.ports.0.hint",
+				message: "a block of 32 ports is never a player address and takes no hint",
+			},
+			{
+				path: "container.ports.0.srv",
+				message: "a block of 32 ports is never a player address and takes no srv",
+			},
+			{
+				path: "container.ports.0.join",
+				message: "a block of 32 ports is never a player address and takes no join",
+			},
+		]);
+	});
+
+	test("refuses a block that follows a port", () => {
+		expect(
+			failure(
+				withPorts([
+					udpPort("game", 20_000, 20_000),
+					{
+						...blockPort("media", 21_000, 4),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows",
+				message: "a block of 4 ports is never a player address and takes no follows",
+			},
+		]);
+	});
+
+	test("refuses a port that follows a block", () => {
+		expect(
+			failure(
+				withPorts([
+					blockPort("media", 20_000, 4),
+					{
+						...udpPort("query", 21_000, 21_000),
+						follows: {
+							key: "media",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.key",
+				message: '"media" is a block of 4 ports — a port only follows a single port',
+			},
+		]);
+	});
+
+	test("refuses srv on a tcp+udp port", () => {
+		expect(
+			failure(
+				withPorts([
+					{
+						...pairPort("game", 19_132),
+						srv: {
+							service: "_minecraft",
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.0.srv",
+				message: "a tcp+udp port takes no srv — an SRV record names one protocol",
+			},
+		]);
+	});
+
+	test("refuses a tcp+udp port that follows another", () => {
+		expect(
+			failure(
+				withPorts([
+					pairPort("game", 19_132),
+					{
+						...pairPort("query", 19_300),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.key",
+				message: 'port "query" carries tcp+udp and cannot follow another port',
+			},
+		]);
+	});
+
+	test("refuses a port that follows a tcp+udp port", () => {
+		expect(
+			failure(
+				withPorts([
+					pairPort("game", 19_132),
+					{
+						...udpPort("query", 19_300, 19_300),
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.follows.key",
+				message: '"game" is a tcp+udp port — a port only follows one of its own protocol',
+			},
+		]);
+	});
+
+	test("refuses a tcp+udp port overlapping a udp port on the shared protocol", () => {
+		expect(
+			failure(
+				withPorts([
+					pairPort("game", 19_132),
+					udpPort("query", 19_140, 19_140),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.hostRange",
+				message: 'host range overlaps port "game" — two udp ports cannot share host ports',
+			},
+		]);
+	});
+
+	test("lets a tcp port and a udp port share a host range", () => {
+		const [tcp] = base().container.ports;
+
+		if (!tcp) {
+			throw new Error("fixture is missing its port");
+		}
+
+		const manifest = manifestSchema.parse(
+			withPorts([
+				tcp,
+				udpPort("query", 25_565, 25_565),
+			]),
+		);
+
+		expect(manifest.container.ports).toHaveLength(2);
+	});
+
+	test("refuses a manifest whose pairs expand past the socket port limit", () => {
+		expect(
+			failure(
+				withPorts(
+					[
+						0,
+						1,
+						2,
+						3,
+						4,
+					].map((index) => pairPort(`p${index}`, 20_000 + index * 100)),
+				),
+			),
+		).toEqual([
+			{
+				path: "container.ports",
+				message: "expands to 10 socket ports — a tcp+udp port counts twice and the total must stay at most 8",
+			},
+		]);
+	});
+});
+
+const botBase = () => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: PackageKind.Bot,
+	metadata: {
+		id: "bot-node",
+		name: text("Node.js Bot"),
+		description: text("Run your own bot"),
+		tagline: text("Your code, always on"),
+		logo: "assets/logo.webp",
+		banner: "assets/banner.webp",
+	},
+	resources: {
+		minMemoryMb: 512,
+		recommendedMemoryMb: 1024,
+		minDiskMb: 2048,
+	},
+	container: {
+		image: "serverkgg/bot-node",
+		ports: [],
+		runtime: {
+			pidsLimit: 256,
+		},
+	},
+});
+
+const botFailure = (input: unknown) => {
+	const result = botManifestSchema.safeParse(input);
+
+	if (result.success) {
+		throw new Error("expected the bot manifest to be rejected");
+	}
+
+	return result.error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		message: issue.message,
+	}));
+};
+
+const yamlSource = (document: unknown): PackageSource => {
+	const files = new Map([
+		[
+			MANIFEST_FILE,
+			new TextEncoder().encode(JSON.stringify(document)),
+		],
+	]);
+
+	return {
+		list: () => [
+			...files.keys(),
+		],
+		read: (path) => files.get(path) ?? null,
+	};
+};
+
+describe("bot packages", () => {
+	test("parse with no ports and no category", () => {
+		const manifest = botManifestSchema.parse(botBase());
+
+		expect(manifest.kind).toBe(PackageKind.Bot);
+		expect(manifest.container.ports).toEqual([]);
+		expect("category" in manifest.metadata).toBe(false);
+		expect(manifest.secrets).toBeUndefined();
+		expect(manifest.presence).toBeUndefined();
+	});
+
+	test("default the ports to none when a bot declares no ports key", () => {
+		const { container, ...rest } = botBase();
+		const manifest = botManifestSchema.parse({
+			...rest,
+			container: {
+				image: container.image,
+			},
+		});
+
+		expect(manifest.container.ports).toEqual([]);
+	});
+
+	test("refuse a secrets list with the environment vault named as the place for per-bot values", () => {
+		expect(
+			botFailure({
+				...botBase(),
+				secrets: [],
+			}),
+		).toEqual([
+			{
+				path: "secrets",
+				message: "a bot package declares no platform secrets; per-bot values live in the environment vault",
+			},
+		]);
+	});
+
+	test("keep the environment vault off unless the package turns it on", () => {
+		expect(botManifestSchema.parse(botBase()).environment.vault).toBe(false);
+		expect(
+			botManifestSchema.parse({
+				...botBase(),
+				environment: {
+					vault: true,
+				},
+			}).environment.vault,
+		).toBe(true);
+	});
+
+	test("refuse a vault flag that is not a boolean", () => {
+		expect(
+			botFailure({
+				...botBase(),
+				environment: {
+					vault: "yes",
+				},
+			}).map((issue) => issue.path),
+		).toEqual([
+			"environment.vault",
+		]);
+	});
+
+	test("refuse a presence block", () => {
+		expect(
+			botFailure({
+				...botBase(),
+				presence: {
+					name: "player",
+				},
+			}),
+		).toEqual([
+			{
+				path: "presence",
+				message: "a bot package has no player presence",
+			},
+		]);
+	});
+
+	test("still run the shared package checks", () => {
+		expect(
+			botFailure({
+				...botBase(),
+				container: {
+					...botBase().container,
+					image: "serverkgg/bot-python",
+				},
+			}),
+		).toEqual([
+			{
+				path: "container.image",
+				message: 'must be "serverkgg/bot-node" to match metadata.id',
+			},
+		]);
+	});
+
+	test("keep a port a bot declares for a webhook", () => {
+		const manifest = botManifestSchema.parse({
+			...botBase(),
+			container: {
+				...botBase().container,
+				ports: base().container.ports,
+			},
+		});
+
+		expect(manifest.container.ports).toHaveLength(1);
+	});
+
+	test("reach the runtime reader like a game does", () => {
+		expect(manifestRuntimeOf(botManifestSchema.parse(botBase()))).toEqual({
+			...MANIFEST_RUNTIME_DEFAULTS,
+			pidsLimit: 256,
+		});
+	});
+});
+
+describe("package kinds", () => {
+	test("route all three kinds through packageSchema", () => {
+		expect(packageSchema.parse(base()).kind).toBe(PackageKind.Game);
+		expect(packageSchema.parse(botBase()).kind).toBe(PackageKind.Bot);
+		expect(
+			packageSchema.parse(
+				guidePackage([
+					guide("start"),
+				]),
+			).kind,
+		).toBe(PackageKind.Guide);
+	});
+
+	test("keep a game package on the game rules, so it still needs a port", () => {
+		const result = packageSchema.safeParse(withPorts([]));
+
+		expect(result.success).toBe(false);
+	});
+
+	test("refuse a guide package where a runnable package is expected", () => {
+		expect(
+			runnablePackageSchema.safeParse(
+				guidePackage([
+					guide("start"),
+				]),
+			).success,
+		).toBe(false);
+	});
+
+	test("tell a game from a bot", () => {
+		const game = runnablePackageSchema.parse(base());
+		const bot = runnablePackageSchema.parse(botBase());
+
+		expect(isGameManifest(game)).toBe(true);
+		expect(isBotManifest(game)).toBe(false);
+		expect(isBotManifest(bot)).toBe(true);
+		expect(isGameManifest(bot)).toBe(false);
+	});
+
+	test("keep the old game schema name pointing at the game schema for this release", () => {
+		expect(manifestSchema).toBe(gameManifestSchema);
+	});
+
+	test("read a bot package from its source", () => {
+		const { manifest } = readPackage(yamlSource(botBase()));
+
+		expect(manifest.kind).toBe(PackageKind.Bot);
+		expect(manifest.metadata.id).toBe("bot-node");
+	});
+
+	test("read a game package from its source unchanged", () => {
+		const { manifest } = readPackage(yamlSource(base()));
+
+		expect(isGameManifest(manifest) && manifest.secrets).toEqual([]);
+	});
+
+	test("render every kind literal into the JSON schema", () => {
+		const rendered = JSON.stringify(buildJsonSchema());
+
+		for (const kind of Object.values(PackageKind)) {
+			expect(rendered).toContain(`"${kind}"`);
+		}
+	});
+});