@serverkgg/bridge 0.0.21 → 0.1.1

package/src/manifest/manifest.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { PortJoin, PortProtocol } from "../core";
+import { PORT_BLOCK_MAX_COUNT, PortJoin, PortProtocol, socketProtocolsOf } from "../core";
 import { BridgeIcon } from "../panel/bridgeIcon";
 import { BRIDGE_OPTION_VALUE_LENGTH_LIMIT, BRIDGE_VISIBLE_VALUES_LIMIT } from "../protocol/bridgeLimits";
 import { GameCategory } from "./category";
 import { type GuideEntry, type GuideTag, guideEntrySchema, guideTagSchema } from "./guide";
 import { IMAGE_NAMESPACE } from "./image";
+import { PackageKind } from "./kind";
 import { localizedText } from "./localized";
 import { type ManifestPresence, manifestPresenceSchema } from "./presence";
 import {
@@ -30,11 +31,7 @@ const manifestHostRangeSchema = z
 		max: zHostPort,
 	})
 	.refine((range) => range.min <= range.max, "min must not be greater than max")
-	.refine((range) => range.min <= range.default && range.default <= range.max, "default must fall inside min..max")
-	.refine(
-		(range) => range.max - range.min + 1 <= HOST_RANGE_MAX_SIZE,
-		`must span at most ${HOST_RANGE_MAX_SIZE} ports`,
-	);
+	.refine((range) => range.min <= range.default && range.default <= range.max, "default must fall inside min..max");
 
 export type ManifestHostRange = z.infer<typeof manifestHostRangeSchema>;
 
@@ -100,39 +97,55 @@ const manifestPortSchema = z.object({
 		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.",
 	}),
+	count: z.int().min(1).max(PORT_BLOCK_MAX_COUNT).default(1).meta({
+		description:
+			"Reserves this many contiguous host ports, bound one to one from containerPort upward. A block is infrastructure, never a player address: it takes no name, hint, join, srv or follows.",
+	}),
 });
 
 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),
-		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 MANIFEST_PORTS_LIMIT = 8;
 
-		const { runtime } = ctx.value;
+const containerSchemaWith = <Ports extends z.ZodType<ManifestPort[]>>(ports: Ports) => {
+	return z
+		.object({
+			image: zImageReference.meta({
+				description: `Image repository, always "${IMAGE_NAMESPACE}/" followed by metadata.id.`,
+			}),
+			ports,
+			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;
+			}
 
-		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 { 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 gameContainerSchema = containerSchemaWith(z.array(manifestPortSchema).min(1).max(MANIFEST_PORTS_LIMIT));
+
+const botContainerSchema = containerSchemaWith(
+	z.array(manifestPortSchema).max(MANIFEST_PORTS_LIMIT).default([]).meta({
+		description: "A bot listens on nothing. Declare a port only when a webhook needs a public address.",
+	}),
+);
 
 const manifestMetadataSchema = z.object({
 	id: zSlug.meta({
@@ -146,6 +159,10 @@ const manifestMetadataSchema = z.object({
 	banner: zAssetPath,
 });
 
+const botMetadataSchema = manifestMetadataSchema.omit({
+	category: true,
+});
+
 const manifestResourcesSchema = z
 	.object({
 		minMemoryMb: z.int().min(128).max(1_048_576),
@@ -168,6 +185,13 @@ const manifestBackupSchema = z.object({
 	}),
 });
 
+const manifestEnvironmentSchema = z.object({
+	vault: z.boolean().default(false).meta({
+		description:
+			"Whether the customer keeps their own environment variables for this package. The platform stores them, hides sensitive values after saving, and delivers them to the process.",
+	}),
+});
+
 const manifestResetSchema = z.object({
 	keep: z.array(zGlob).max(32).default([]).meta({
 		description: "Paths that survive a server reset. Everything else is deleted.",
@@ -180,6 +204,8 @@ const manifestSecretSchema = z.object({
 	required: z.boolean().default(true),
 });
 
+type ManifestSecret = z.infer<typeof manifestSecretSchema>;
+
 const manifestFileNoteSchema = z.object({
 	match: zGlob,
 	label: localizedText(48),
@@ -202,6 +228,8 @@ const manifestFilesSchema = z.object({
 	}),
 });
 
+type ManifestFiles = z.infer<typeof manifestFilesSchema>;
+
 type CheckIssue = {
 	code: "custom";
 	message: string;
@@ -329,6 +357,28 @@ const followIssues = (ports: ManifestPort[]): CheckIssue[] => {
 			return;
 		}
 
+		if (port.protocol === PortProtocol.TcpUdp) {
+			issues.push({
+				code: "custom",
+				message: `port "${port.key}" carries ${PortProtocol.TcpUdp} and cannot follow another port`,
+				input: follows.key,
+				path,
+			});
+
+			return;
+		}
+
+		if (leader.count > 1) {
+			issues.push({
+				code: "custom",
+				message: `"${follows.key}" is a block of ${leader.count} ports — a port only follows a single port`,
+				input: follows.key,
+				path,
+			});
+
+			return;
+		}
+
 		if (leader.protocol !== port.protocol) {
 			issues.push({
 				code: "custom",
@@ -353,6 +403,161 @@ const followIssues = (ports: ManifestPort[]): CheckIssue[] => {
 	return issues;
 };
 
+const sharedSocketProtocols = (a: ManifestPort, b: ManifestPort) => {
+	const other = socketProtocolsOf(b.protocol);
+
+	return socketProtocolsOf(a.protocol).filter((protocol) => other.includes(protocol));
+};
+
+const BLOCK_REFUSED_FIELDS = [
+	"name",
+	"hint",
+	"srv",
+	"follows",
+] as const;
+
+const blockIssues = (port: ManifestPort, index: number): CheckIssue[] => {
+	const issues: CheckIssue[] = [];
+	const path = [
+		"container",
+		"ports",
+		index,
+	];
+
+	for (const field of BLOCK_REFUSED_FIELDS) {
+		if (port[field] === undefined) {
+			continue;
+		}
+
+		issues.push({
+			code: "custom",
+			message: `a block of ${port.count} ports is never a player address and takes no ${field}`,
+			input: port[field],
+			path: [
+				...path,
+				field,
+			],
+		});
+	}
+
+	if (port.join !== PortJoin.Combined) {
+		issues.push({
+			code: "custom",
+			message: `a block of ${port.count} ports is never a player address and takes no join`,
+			input: port.join,
+			path: [
+				...path,
+				"join",
+			],
+		});
+	}
+
+	if (port.hostRange.max - port.hostRange.min + 1 < port.count) {
+		issues.push({
+			code: "custom",
+			message: `must span at least ${port.count} ports to hold the block`,
+			input: port.hostRange,
+			path: [
+				...path,
+				"hostRange",
+			],
+		});
+	} else if (port.hostRange.default + port.count - 1 > port.hostRange.max) {
+		issues.push({
+			code: "custom",
+			message: `default must leave room for all ${port.count} ports before max`,
+			input: port.hostRange,
+			path: [
+				...path,
+				"hostRange",
+				"default",
+			],
+		});
+	}
+
+	if (!port.mirror && port.containerPort + port.count - 1 > 65_535) {
+		issues.push({
+			code: "custom",
+			message: `a block of ${port.count} ports starting here runs past 65535`,
+			input: port.containerPort,
+			path: [
+				...path,
+				"containerPort",
+			],
+		});
+	}
+
+	return issues;
+};
+
+const spanIssues = (port: ManifestPort, index: number): CheckIssue[] => {
+	const slots = Math.ceil((port.hostRange.max - port.hostRange.min + 1) / port.count);
+
+	if (slots <= HOST_RANGE_MAX_SIZE) {
+		return [];
+	}
+
+	return [
+		{
+			code: "custom",
+			message:
+				port.count > 1
+					? `must span at most ${HOST_RANGE_MAX_SIZE} slots of ${port.count} ports`
+					: `must span at most ${HOST_RANGE_MAX_SIZE} ports`,
+			input: port.hostRange,
+			path: [
+				"container",
+				"ports",
+				index,
+				"hostRange",
+			],
+		},
+	];
+};
+
+const portShapeIssues = (port: ManifestPort, index: number): CheckIssue[] => {
+	const issues = [
+		...spanIssues(port, index),
+		...(port.count > 1 ? blockIssues(port, index) : []),
+	];
+
+	if (port.protocol === PortProtocol.TcpUdp && port.srv !== undefined) {
+		issues.push({
+			code: "custom",
+			message: `a ${PortProtocol.TcpUdp} port takes no srv — an SRV record names one protocol`,
+			input: port.srv,
+			path: [
+				"container",
+				"ports",
+				index,
+				"srv",
+			],
+		});
+	}
+
+	return issues;
+};
+
+const socketBindingIssues = (ports: ManifestPort[]): CheckIssue[] => {
+	const bindings = ports.reduce((total, port) => total + socketProtocolsOf(port.protocol).length, 0);
+
+	if (bindings <= MANIFEST_PORTS_LIMIT) {
+		return [];
+	}
+
+	return [
+		{
+			code: "custom",
+			message: `expands to ${bindings} socket ports — a ${PortProtocol.TcpUdp} port counts twice and the total must stay at most ${MANIFEST_PORTS_LIMIT}`,
+			input: bindings,
+			path: [
+				"container",
+				"ports",
+			],
+		},
+	];
+};
+
 const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 	const issues = duplicateIssues(
 		ports,
@@ -371,13 +576,19 @@ const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 			const a = ports[index];
 			const b = ports[other];
 
-			if (!a || !b || a.protocol !== b.protocol || !hostRangesOverlap(a, b) || sameFollowGroup(a, b)) {
+			if (!a || !b || !hostRangesOverlap(a, b) || sameFollowGroup(a, b)) {
+				continue;
+			}
+
+			const shared = sharedSocketProtocols(a, b);
+
+			if (shared.length === 0) {
 				continue;
 			}
 
 			issues.push({
 				code: "custom",
-				message: `host range overlaps port "${a.key}" — two ${a.protocol} ports cannot share host ports`,
+				message: `host range overlaps port "${a.key}" — two ${shared.join(" and ")} ports cannot share host ports`,
 				input: b.hostRange,
 				path: [
 					"container",
@@ -391,6 +602,8 @@ const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 
 	return [
 		...issues,
+		...ports.flatMap(portShapeIssues),
+		...socketBindingIssues(ports),
 		...followIssues(ports),
 	];
 };
@@ -489,13 +702,88 @@ const guideIssues = (guideTags: GuideTag[], guides: GuideEntry[]): CheckIssue[]
 	return issues;
 };
 
-export const manifestSchema = z
+interface PackageShape {
+	metadata: {
+		id: string;
+	};
+	container: {
+		image: string;
+		ports: ManifestPort[];
+	};
+	files: ManifestFiles;
+	guideTags: GuideTag[];
+	guides: GuideEntry[];
+}
+
+const imageIssues = (manifest: PackageShape): CheckIssue[] => {
+	const expectedImage = `${IMAGE_NAMESPACE}/${manifest.metadata.id}`;
+
+	if (manifest.container.image === expectedImage) {
+		return [];
+	}
+
+	return [
+		{
+			code: "custom",
+			message: `must be "${expectedImage}" to match metadata.id`,
+			input: manifest.container.image,
+			path: [
+				"container",
+				"image",
+			],
+		},
+	];
+};
+
+const packageIssues = (manifest: PackageShape): CheckIssue[] => {
+	return [
+		...imageIssues(manifest),
+		...portIssues(manifest.container.ports),
+		...duplicateIssues(
+			manifest.files.protected,
+			(path) => path,
+			(index) => [
+				"files",
+				"protected",
+				index,
+			],
+			(key) => `"${key}" is protected twice`,
+		),
+		...duplicateIssues(
+			manifest.files.notable,
+			(note) => note.match,
+			(index) => [
+				"files",
+				"notable",
+				index,
+				"match",
+			],
+			(key) => `"${key}" already has a note`,
+		),
+		...guideIssues(manifest.guideTags, manifest.guides),
+	];
+};
+
+const secretIssues = (secrets: ManifestSecret[]): CheckIssue[] => {
+	return duplicateIssues(
+		secrets,
+		(secret) => secret.key,
+		(index) => [
+			"secrets",
+			index,
+			"key",
+		],
+		(key) => `secret "${key}" is declared twice`,
+	);
+};
+
+export const gameManifestSchema = z
 	.object({
 		schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
-		kind: z.literal("GamePackage"),
+		kind: z.literal(PackageKind.Game),
 		metadata: manifestMetadataSchema,
 		resources: manifestResourcesSchema,
-		container: manifestContainerSchema,
+		container: gameContainerSchema,
 		guideTags: z.array(guideTagSchema).max(16).default([]),
 		guides: z.array(guideEntrySchema).max(64).default([]),
 		backup: manifestBackupSchema.prefault({}),
@@ -510,64 +798,71 @@ export const manifestSchema = z
 		}
 
 		const manifest = ctx.value;
-		const expectedImage = `${IMAGE_NAMESPACE}/${manifest.metadata.id}`;
-
-		if (manifest.container.image !== expectedImage) {
-			ctx.issues.push({
-				code: "custom",
-				message: `must be "${expectedImage}" to match metadata.id`,
-				input: manifest.container.image,
-				path: [
-					"container",
-					"image",
-				],
-			});
-		}
 
 		ctx.issues.push(
-			...portIssues(manifest.container.ports),
-			...duplicateIssues(
-				manifest.secrets,
-				(secret) => secret.key,
-				(index) => [
-					"secrets",
-					index,
-					"key",
-				],
-				(key) => `secret "${key}" is declared twice`,
-			),
-			...duplicateIssues(
-				manifest.files.protected,
-				(path) => path,
-				(index) => [
-					"files",
-					"protected",
-					index,
-				],
-				(key) => `"${key}" is protected twice`,
-			),
-			...duplicateIssues(
-				manifest.files.notable,
-				(note) => note.match,
-				(index) => [
-					"files",
-					"notable",
-					index,
-					"match",
-				],
-				(key) => `"${key}" already has a note`,
-			),
-			...guideIssues(manifest.guideTags, manifest.guides),
+			...packageIssues(manifest),
+			...secretIssues(manifest.secrets),
 			...presenceIssues(manifest.presence),
 		);
 	});
 
-export type Manifest = z.infer<typeof manifestSchema>;
+export type GameManifest = z.infer<typeof gameManifestSchema>;
+
+export const manifestSchema = gameManifestSchema;
+
+export type Manifest = GameManifest;
+
+export const botManifestSchema = z
+	.object({
+		schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
+		kind: z.literal(PackageKind.Bot),
+		metadata: botMetadataSchema,
+		resources: manifestResourcesSchema,
+		container: botContainerSchema,
+		guideTags: z.array(guideTagSchema).max(16).default([]),
+		guides: z.array(guideEntrySchema).max(64).default([]),
+		backup: manifestBackupSchema.prefault({}),
+		reset: manifestResetSchema.prefault({}),
+		files: manifestFilesSchema.prefault({}),
+		environment: manifestEnvironmentSchema.prefault({}),
+		secrets: z
+			.never({
+				error: "a bot package declares no platform secrets; per-bot values live in the environment vault",
+			})
+			.optional()
+			.meta({
+				description: "Not declared by a bot package. Per-bot values live in the environment vault.",
+			}),
+		presence: z
+			.never({
+				error: "a bot package has no player presence",
+			})
+			.optional()
+			.meta({
+				description: "Not declared by a bot package. A bot has no player presence.",
+			}),
+	})
+	.check((ctx) => {
+		if (ctx.issues.length > 0) {
+			return;
+		}
+
+		ctx.issues.push(...packageIssues(ctx.value));
+	});
+
+export type BotManifest = z.infer<typeof botManifestSchema>;
+
+export const runnablePackageSchema = z.discriminatedUnion("kind", [
+	gameManifestSchema,
+	botManifestSchema,
+]);
+
+export type RunnableManifest = z.infer<typeof runnablePackageSchema>;
 
 export const guidePackageSchema = z
 	.object({
 		schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
-		kind: z.literal("GuidePackage"),
+		kind: z.literal(PackageKind.Guide),
 		metadata: z.object({
 			id: zSlug,
 		}),
@@ -585,8 +880,17 @@ export const guidePackageSchema = z
 export type GuidePackage = z.infer<typeof guidePackageSchema>;
 
 export const packageSchema = z.discriminatedUnion("kind", [
-	manifestSchema,
+	gameManifestSchema,
+	botManifestSchema,
 	guidePackageSchema,
 ]);
 
 export type Package = z.infer<typeof packageSchema>;
+
+export const isGameManifest = (document: Package): document is GameManifest => {
+	return document.kind === PackageKind.Game;
+};
+
+export const isBotManifest = (document: Package): document is BotManifest => {
+	return document.kind === PackageKind.Bot;
+};

package/src/manifest/runtime.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Manifest } from "./manifest";
+import type { RunnableManifest } from "./manifest";
 
 export enum ManifestPlatform {
 	Linux = "linux",
@@ -81,7 +81,7 @@ export type ManifestRuntime = z.infer<typeof manifestRuntimeSchema>;
 
 export const MANIFEST_RUNTIME_DEFAULTS: ManifestRuntime = manifestRuntimeSchema.parse({});
 
-export const manifestRuntimeOf = (manifest: Manifest): ManifestRuntime => {
+export const manifestRuntimeOf = (manifest: Pick<RunnableManifest, "container">): ManifestRuntime => {
 	return {
 		...MANIFEST_RUNTIME_DEFAULTS,
 		...manifest.container.runtime,

package/src/manifest/source.ts

@@ -1,5 +1,5 @@
 import { verifyAsset } from "./assets";
-import { type Manifest, manifestSchema, type Package, packageSchema } from "./manifest";
+import { type Package, packageSchema, type RunnableManifest, runnablePackageSchema } from "./manifest";
 
 export const MANIFEST_FILE = "serverk.yml";
 
@@ -39,14 +39,14 @@ const readAsset = (source: PackageSource, asset: string) => {
 	};
 };
 
-export const readAssets = (source: PackageSource, manifest: Manifest) => {
+export const readAssets = (source: PackageSource, manifest: RunnableManifest) => {
 	return {
 		logo: readAsset(source, manifest.metadata.logo),
 		banner: readAsset(source, manifest.metadata.banner),
 	};
 };
 
-export const declaredFiles = (manifest: Manifest, guideFiles: string[] = []) => {
+export const declaredFiles = (manifest: RunnableManifest, guideFiles: string[] = []) => {
 	return [
 		MANIFEST_FILE,
 		manifest.metadata.logo,
@@ -78,7 +78,7 @@ export const computeBundleDigest = (source: PackageSource, paths: string[]) => {
 };
 
 export const readPackage = (source: PackageSource) => {
-	const manifest: Manifest = manifestSchema.parse(readYaml(source, MANIFEST_FILE));
+	const manifest: RunnableManifest = runnablePackageSchema.parse(readYaml(source, MANIFEST_FILE));
 
 	return {
 		manifest,

package/src/modules/bridgeLifecycleSubject.ts

@@ -0,0 +1,8 @@
+export enum BridgeLifecycleSubject {
+	Game = "game",
+	Bot = "bot",
+}
+
+export const isBridgeLifecycleSubject = (value: unknown): value is BridgeLifecycleSubject => {
+	return Object.values(BridgeLifecycleSubject).some((subject) => subject === value);
+};

package/src/modules/bridgeModule.ts

@@ -11,6 +11,8 @@ import type { BridgeBackupSnapshot, BridgeDescribeResult, BridgePendingFile } fr
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeSetupStep } from "../protocol/bridgeSetup";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
+import type { BridgeLifecycleSubject } from "./bridgeLifecycleSubject";
+import type { BridgeStopSignal } from "./bridgeStopSignal";
 
 export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
 
@@ -25,7 +27,11 @@ export interface BridgeLifecycleModule {
 	ready?: RegExp;
 	failed?: RegExp;
 	stopTimeoutSeconds?: number;
+	readyTimeoutSeconds?: number;
+	stopSignal?: BridgeStopSignal;
+	subject?: BridgeLifecycleSubject;
 	command(context: BridgeContext): Promise<string[]>;
+	environment?(context: BridgeContext): Promise<Record<string, string>>;
 	stop?(context: BridgeContext): Promise<void>;
 	onReady?(context: BridgeContext): Promise<void>;
 }

package/src/modules/bridgeStopSignal.ts

@@ -0,0 +1,13 @@
+export enum BridgeStopSignal {
+	Term = "SIGTERM",
+	Interrupt = "SIGINT",
+}
+
+export const BRIDGE_STOP_SIGNALS: Record<BridgeStopSignal, NodeJS.Signals> = {
+	[BridgeStopSignal.Term]: "SIGTERM",
+	[BridgeStopSignal.Interrupt]: "SIGINT",
+};
+
+export const isBridgeStopSignal = (value: unknown): value is BridgeStopSignal => {
+	return typeof value === "string" && Object.hasOwn(BRIDGE_STOP_SIGNALS, value);
+};

package/src/modules/index.ts

@@ -1,3 +1,5 @@
 export * from "./bridge";
 export * from "./bridgeDriver";
+export * from "./bridgeLifecycleSubject";
 export * from "./bridgeModule";
+export * from "./bridgeStopSignal";