@serverkgg/bridge 0.0.1 → 0.0.2

package/src/manifest/manifest.ts

@@ -1,170 +1,404 @@
 import { z } from "zod";
 import { PortProtocol } from "../core";
-import { ASSET_EXTENSION } from "./assets";
+import { BridgeIcon } from "../panel/bridgeIcon";
 import { GameCategory } from "./category";
-import { guideEntrySchema } from "./guide";
+import { type GuideEntry, type GuideTag, guideEntrySchema, guideTagSchema } from "./guide";
 import { IMAGE_NAMESPACE } from "./image";
-import { localizedTextSchema } from "./localized";
+import { localizedText } from "./localized";
+import {
+	HOST_RANGE_MAX_SIZE,
+	zAssetPath,
+	zEnvKey,
+	zGlob,
+	zHexColor,
+	zHostPort,
+	zImageReference,
+	zPort,
+	zSlug,
+} from "./primitives";
 
-export const MANIFEST_API_VERSION = "serverk.gg/v1";
+export const MANIFEST_SCHEMA_VERSION = "serverk.gg/v1";
 
-export const BACKUP_SETTLE_SECONDS_DEFAULT = 5;
-
-const zRelativePath = z
-	.string()
-	.min(1)
-	.max(256)
-	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.[a-z0-9]+$/);
-
-const zAssetPath = zRelativePath.refine((value) => {
-	return value.endsWith(`.${ASSET_EXTENSION}`);
-});
-
-export const MANIFEST_HOST_PORT_MIN = 1024;
-
-export const MANIFEST_HOST_PORT_SPAN = 1000;
-
-export const manifestPortHostSchema = z
+const manifestHostRangeSchema = z
 	.object({
-		default: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
-		min: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
-		max: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
+		default: zHostPort,
+		min: zHostPort,
+		max: zHostPort,
 	})
-	.refine((host) => host.min <= host.max)
-	.refine((host) => host.min <= host.default && host.default <= host.max)
-	.refine((host) => host.max - host.min + 1 <= MANIFEST_HOST_PORT_SPAN);
+	.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`,
+	);
 
-export type ManifestPortHost = z.infer<typeof manifestPortHostSchema>;
+export type ManifestHostRange = z.infer<typeof manifestHostRangeSchema>;
 
-export const manifestPortSchema = z.object({
+const manifestPortSchema = z.object({
 	key: z
 		.string()
 		.min(1)
 		.max(32)
-		.regex(/^[a-z][a-z0-9-]*$/),
-	port: z.int().min(1).max(65_535),
+		.regex(/^[a-z][a-z0-9-]*$/, "must be lowercase letters, digits and dashes, starting with a letter"),
+	containerPort: zPort,
 	protocol: z.enum(PortProtocol).default(PortProtocol.Tcp),
-	host: manifestPortHostSchema,
+	hostRange: manifestHostRangeSchema,
 });
 
 export type ManifestPort = z.infer<typeof manifestPortSchema>;
 
-const zImageReference = z
-	.string()
-	.min(1)
-	.max(256)
-	.regex(new RegExp(`^${IMAGE_NAMESPACE}/[a-z0-9][a-z0-9-]*$`));
-
-export const manifestRuntimeSchema = z.object({
-	image: zImageReference,
+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),
 });
 
-export const manifestMetadataSchema = z.object({
-	id: z
-		.string()
-		.min(1)
-		.max(64)
-		.regex(/^[a-z0-9][a-z0-9-]*$/),
-	name: localizedTextSchema,
-	description: localizedTextSchema,
-	tagline: localizedTextSchema,
+const manifestMetadataSchema = z.object({
+	id: zSlug.meta({
+		description: "Slug for the game. Also the catalogue URL segment and the image name.",
+	}),
+	name: localizedText(64),
+	description: localizedText(600),
+	tagline: localizedText(120),
 	category: z.enum(GameCategory),
 	logo: zAssetPath,
 	banner: zAssetPath,
 });
 
-export const manifestResourcesSchema = z
+const manifestResourcesSchema = z
 	.object({
 		minMemoryMb: z.int().min(128).max(1_048_576),
 		recommendedMemoryMb: z.int().min(128).max(1_048_576),
 		minDiskMb: z.int().min(512),
-		playersPerGb: z.int().min(1).max(1024).optional(),
-		maxPlayers: z.int().min(1).max(100_000).optional(),
+		playersPerMemoryGb: z.int().min(1).max(1024).optional(),
+		maxRecommendedPlayers: z.int().min(1).max(100_000).optional(),
 	})
-	.refine((resources) => resources.recommendedMemoryMb >= resources.minMemoryMb);
-
-const zRelativeGlob = z
-	.string()
-	.min(1)
-	.max(256)
-	.regex(/^[^/\\][^\\]*$/)
-	.refine((value) => !value.split("/").includes(".."));
-
-export const manifestQuiesceSchema = z.object({
-	before: z.string().max(256).optional(),
-	flush: z.string().max(256).optional(),
-	after: z.string().max(256).optional(),
-	await: z.string().max(256).optional(),
-	settleSeconds: z.int().min(0).max(120).default(BACKUP_SETTLE_SECONDS_DEFAULT),
-});
+	.refine(
+		(resources) => resources.recommendedMemoryMb >= resources.minMemoryMb,
+		"recommendedMemoryMb must not be below minMemoryMb",
+	);
 
-export const manifestBackupSchema = z.object({
-	include: z.array(zRelativeGlob).max(32).default([]),
-	exclude: z.array(zRelativeGlob).max(64).default([]),
-	quiesce: manifestQuiesceSchema.optional(),
+const manifestBackupSchema = z.object({
+	only: z.array(zGlob).max(32).default([]).meta({
+		description: "When set, only these paths are archived. Empty means the whole game directory.",
+	}),
+	except: z.array(zGlob).max(64).default([]).meta({
+		description: "Paths excluded from the archive, applied after only.",
+	}),
 });
 
-export const manifestResetSchema = z.object({
-	keep: z.array(zRelativeGlob).max(32).default([]),
+const manifestResetSchema = z.object({
+	keep: z.array(zGlob).max(32).default([]).meta({
+		description: "Paths that survive a server reset. Everything else is deleted.",
+	}),
 });
 
-const zEnvKey = z
-	.string()
-	.min(2)
-	.max(32)
-	.regex(/^[A-Z][A-Z0-9_]*$/);
-
-export const manifestSecretSchema = z.object({
+const manifestSecretSchema = z.object({
 	key: zEnvKey,
-	description: localizedTextSchema,
+	description: localizedText(300),
 	required: z.boolean().default(true),
 });
 
-export type ManifestSecret = z.infer<typeof manifestSecretSchema>;
-
-export const manifestFilesSchema = z.object({
-	hidden: z
-		.array(
-			z
-				.string()
-				.min(1)
-				.max(128)
-				.regex(/^[^/\\][^\\]*$/)
-				.refine((value) => !value.split("/").includes("..")),
-		)
-		.max(64)
-		.default([]),
+const manifestFileNoteSchema = z.object({
+	match: zGlob,
+	label: localizedText(48),
+	note: localizedText(400),
+	icon: z.enum(BridgeIcon).optional(),
+	color: zHexColor.optional(),
+	restart: z.boolean().default(false).meta({
+		description: "Whether editing this path needs a server restart to take effect.",
+	}),
 });
 
-export const manifestSchema = z.object({
-	apiVersion: z.literal(MANIFEST_API_VERSION),
-	kind: z.literal("GamePackage"),
-	metadata: manifestMetadataSchema,
-	resources: manifestResourcesSchema,
-	runtime: manifestRuntimeSchema,
-	guides: z.array(guideEntrySchema).max(64).default([]),
-	backup: manifestBackupSchema.optional(),
-	reset: manifestResetSchema.optional(),
-	secrets: z.array(manifestSecretSchema).max(16).default([]),
-	files: manifestFilesSchema.default({
-		hidden: [],
+export type ManifestFileNote = z.infer<typeof manifestFileNoteSchema>;
+
+const manifestFilesSchema = z.object({
+	protected: z.array(zGlob).max(64).default([]).meta({
+		description: "Paths the player cannot edit, rename or delete from the file manager.",
+	}),
+	notable: z.array(manifestFileNoteSchema).max(32).default([]).meta({
+		description: "Paths the file manager annotates with a label, note and icon.",
 	}),
 });
 
+type CheckIssue = {
+	code: "custom";
+	message: string;
+	input: unknown;
+	path: (string | number)[];
+};
+
+const duplicates = <Item>(items: Item[], keyOf: (item: Item) => string) => {
+	const seen = new Set<string>();
+	const found: {
+		key: string;
+		index: number;
+	}[] = [];
+
+	items.forEach((item, index) => {
+		const key = keyOf(item);
+
+		if (seen.has(key)) {
+			found.push({
+				key,
+				index,
+			});
+		}
+
+		seen.add(key);
+	});
+
+	return found;
+};
+
+const duplicateIssues = <Item>(
+	items: Item[],
+	keyOf: (item: Item) => string,
+	path: (index: number) => (string | number)[],
+	message: (key: string) => string,
+): CheckIssue[] => {
+	return duplicates(items, keyOf).map(({ key, index }) => ({
+		code: "custom" as const,
+		message: message(key),
+		input: key,
+		path: path(index),
+	}));
+};
+
+const hostRangesOverlap = (a: ManifestPort, b: ManifestPort) => {
+	return a.hostRange.min <= b.hostRange.max && b.hostRange.min <= a.hostRange.max;
+};
+
+const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
+	const issues = duplicateIssues(
+		ports,
+		(port) => port.key,
+		(index) => [
+			"container",
+			"ports",
+			index,
+			"key",
+		],
+		(key) => `port "${key}" is declared twice`,
+	);
+
+	for (let index = 0; index < ports.length; index += 1) {
+		for (let other = index + 1; other < ports.length; other += 1) {
+			const a = ports[index];
+			const b = ports[other];
+
+			if (!a || !b || a.protocol !== b.protocol || !hostRangesOverlap(a, b)) {
+				continue;
+			}
+
+			issues.push({
+				code: "custom",
+				message: `host range overlaps port "${a.key}" — two ${a.protocol} ports cannot share host ports`,
+				input: b.hostRange,
+				path: [
+					"container",
+					"ports",
+					other,
+					"hostRange",
+				],
+			});
+		}
+	}
+
+	return issues;
+};
+
+const guideIssues = (guideTags: GuideTag[], guides: GuideEntry[]): CheckIssue[] => {
+	const issues = [
+		...duplicateIssues(
+			guideTags,
+			(tag) => tag.id,
+			(index) => [
+				"guideTags",
+				index,
+				"id",
+			],
+			(key) => `guide tag "${key}" is declared twice`,
+		),
+		...duplicateIssues(
+			guides,
+			(guide) => guide.id,
+			(index) => [
+				"guides",
+				index,
+				"id",
+			],
+			(key) => `guide "${key}" is declared twice`,
+		),
+	];
+
+	const declared = new Set(guideTags.map((tag) => tag.id));
+	const bodyPaths = new Set<string>();
+
+	guides.forEach((guide, index) => {
+		if (guide.bodyPath.ar === guide.bodyPath.en) {
+			issues.push({
+				code: "custom",
+				message: `guide "${guide.id}" reuses one body file for both locales`,
+				input: guide.bodyPath,
+				path: [
+					"guides",
+					index,
+					"bodyPath",
+				],
+			});
+		}
+
+		guide.tags.forEach((tag, tagIndex) => {
+			if (declared.has(tag)) {
+				return;
+			}
+
+			issues.push({
+				code: "custom",
+				message: `tag "${tag}" is not declared in guideTags`,
+				input: tag,
+				path: [
+					"guides",
+					index,
+					"tags",
+					tagIndex,
+				],
+			});
+		});
+
+		const ownPaths = new Set<string>();
+
+		for (const locale of [
+			"ar",
+			"en",
+		] as const) {
+			const path = guide.bodyPath[locale];
+
+			if (ownPaths.has(path)) {
+				continue;
+			}
+
+			ownPaths.add(path);
+
+			if (bodyPaths.has(path)) {
+				issues.push({
+					code: "custom",
+					message: `body file "${path}" is already used by another guide`,
+					input: path,
+					path: [
+						"guides",
+						index,
+						"bodyPath",
+						locale,
+					],
+				});
+			}
+
+			bodyPaths.add(path);
+		}
+	});
+
+	return issues;
+};
+
+export const manifestSchema = z
+	.object({
+		schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
+		kind: z.literal("GamePackage"),
+		metadata: manifestMetadataSchema,
+		resources: manifestResourcesSchema,
+		container: manifestContainerSchema,
+		guideTags: z.array(guideTagSchema).max(16).default([]),
+		guides: z.array(guideEntrySchema).max(64).default([]),
+		backup: manifestBackupSchema.prefault({}),
+		reset: manifestResetSchema.prefault({}),
+		secrets: z.array(manifestSecretSchema).max(16).default([]),
+		files: manifestFilesSchema.prefault({}),
+	})
+	.check((ctx) => {
+		if (ctx.issues.length > 0) {
+			return;
+		}
+
+		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),
+		);
+	});
+
 export type Manifest = z.infer<typeof manifestSchema>;
 
-export const guidePackageSchema = z.object({
-	apiVersion: z.literal(MANIFEST_API_VERSION),
-	kind: z.literal("GuidePackage"),
-	metadata: z.object({
-		id: z
-			.string()
-			.min(1)
-			.max(64)
-			.regex(/^[a-z0-9][a-z0-9-]*$/),
-	}),
-	guides: z.array(guideEntrySchema).min(1).max(64),
-});
+export const guidePackageSchema = z
+	.object({
+		schemaVersion: z.literal(MANIFEST_SCHEMA_VERSION),
+		kind: z.literal("GuidePackage"),
+		metadata: z.object({
+			id: zSlug,
+		}),
+		guideTags: z.array(guideTagSchema).max(16).default([]),
+		guides: z.array(guideEntrySchema).min(1).max(64),
+	})
+	.check((ctx) => {
+		if (ctx.issues.length > 0) {
+			return;
+		}
+
+		ctx.issues.push(...guideIssues(ctx.value.guideTags, ctx.value.guides));
+	});
 
 export type GuidePackage = z.infer<typeof guidePackageSchema>;
+
+export const packageSchema = z.discriminatedUnion("kind", [
+	manifestSchema,
+	guidePackageSchema,
+]);
+
+export type Package = z.infer<typeof packageSchema>;

package/src/manifest/primitives.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { IMAGE_NAMESPACE } from "./image";
+
+export const HOST_RANGE_MIN_PORT = 1024;
+
+export const HOST_RANGE_MAX_SIZE = 1000;
+
+export const zSlug = z
+	.string()
+	.min(1)
+	.max(64)
+	.regex(/^[a-z0-9][a-z0-9-]*$/, "must be lowercase letters, digits and dashes, starting with a letter or digit");
+
+export const zPort = z.int("must be a whole number").min(1, "must be at least 1").max(65_535, "must be at most 65535");
+
+export const zHostPort = z
+	.int("must be a whole number")
+	.min(HOST_RANGE_MIN_PORT, `must be at least ${HOST_RANGE_MIN_PORT} — lower ports are reserved`)
+	.max(65_535, "must be at most 65535");
+
+export const zHexColor = z.stringFormat("hexColor", /^#[0-9a-fA-F]{6}$/, "must be a six-digit hex colour like #4a8fd4");
+
+export const zEnvKey = z
+	.string()
+	.min(2)
+	.max(32)
+	.regex(/^[A-Z][A-Z0-9_]*$/, "must be SCREAMING_SNAKE_CASE, starting with a letter");
+
+export const zImageReference = z.templateLiteral([
+	`${IMAGE_NAMESPACE}/`,
+	zSlug,
+]);
+
+const RELATIVE_PATH_MAX = 256;
+
+const withoutTraversal = (value: string) => {
+	return !value.split("/").includes("..");
+};
+
+export const zRelativePath = z
+	.string()
+	.min(1)
+	.max(RELATIVE_PATH_MAX)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.[a-z0-9]+$/, "must be a relative file path with an extension");
+
+export const zAssetPath = z
+	.string()
+	.min(1)
+	.max(RELATIVE_PATH_MAX)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.webp$/, "must be a relative path to a .webp file");
+
+export const zMarkdownPath = z
+	.string()
+	.min(1)
+	.max(RELATIVE_PATH_MAX)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.md$/, "must be a relative path to a .md file");
+
+export const zGlob = z
+	.string()
+	.min(1)
+	.max(RELATIVE_PATH_MAX)
+	.regex(/^[^/\\][^\\]*$/, "must be a relative pattern using forward slashes")
+	.refine(withoutTraversal, 'must not contain ".."');

package/src/manifest/source.ts

@@ -1,6 +1,5 @@
 import { verifyAsset } from "./assets";
-import { checkManifest } from "./checks";
-import { type Manifest, manifestSchema } from "./manifest";
+import { type Manifest, manifestSchema, type Package, packageSchema } from "./manifest";
 
 export const MANIFEST_FILE = "serverk.yml";
 
@@ -81,9 +80,11 @@ export const computeBundleDigest = (source: PackageSource, paths: string[]) => {
 export const readPackage = (source: PackageSource) => {
 	const manifest: Manifest = manifestSchema.parse(readYaml(source, MANIFEST_FILE));
 
-	checkManifest(manifest);
-
 	return {
 		manifest,
 	};
 };
+
+export const readPackageDocument = (source: PackageSource): Package => {
+	return packageSchema.parse(readYaml(source, MANIFEST_FILE));
+};

package/src/modules/bridge.ts

@@ -1,13 +1,20 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
 import type { BridgeOption, BridgeRow, BridgeValue, BridgeValues, LocalizedText } from "../core";
 import type { BridgeField, BridgePanel, BridgeSection, BridgeTab } from "../panel";
-import type { BridgeDriver } from "./bridgeDriver";
 import type {
-	BridgeBackupModule,
 	BridgeCatalogEntry,
+	BridgeCatalogFacet,
 	BridgeCatalogHit,
-	BridgeCatalogModule,
 	BridgeCatalogPage,
+	BridgeCatalogProvider,
+	BridgeCatalogQuery,
+} from "../protocol/bridgeCatalog";
+import type { BridgeTerminalArg, BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
+import type { BridgeDriver } from "./bridgeDriver";
+import type {
+	BridgeAnnounceModule,
+	BridgeBackupModule,
+	BridgeCatalogModule,
 	BridgeCollectionModule,
 	BridgeEventPattern,
 	BridgeEventsModule,
@@ -18,14 +25,19 @@ import type {
 	BridgeRowAction,
 	BridgeSample,
 	BridgeSettingsModule,
+	BridgeTerminalModule,
 } from "./bridgeModule";
 
 export namespace Bridge {
+	export type Announce = BridgeAnnounceModule;
 	export type Backup = BridgeBackupModule;
 	export type Catalog = BridgeCatalogModule;
 	export type CatalogEntry = BridgeCatalogEntry;
+	export type CatalogFacet = BridgeCatalogFacet;
 	export type CatalogHit = BridgeCatalogHit;
 	export type CatalogPage = BridgeCatalogPage;
+	export type CatalogProvider = BridgeCatalogProvider;
+	export type CatalogQuery = BridgeCatalogQuery;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
 	export type Driver = BridgeDriver;
@@ -46,6 +58,10 @@ export namespace Bridge {
 	export type Sample = BridgeSample;
 	export type Section = BridgeSection;
 	export type Settings = BridgeSettingsModule;
+	export type Terminal = BridgeTerminalModule;
+	export type TerminalArg = BridgeTerminalArg;
+	export type TerminalCommand = BridgeTerminalCommand;
+	export type TerminalRule = BridgeTerminalRule;
 	export type Tab = BridgeTab;
 	export type Text = LocalizedText;
 	export type Value = BridgeValue;

package/src/modules/bridgeDriver.ts

@@ -1,11 +1,13 @@
 import type { BridgePanel } from "../panel";
 import type {
+	BridgeAnnounceModule,
 	BridgeBackupModule,
 	BridgeEventsModule,
 	BridgeInstallModule,
 	BridgeLifecycleModule,
 	BridgePanelModule,
 	BridgeQueryModule,
+	BridgeTerminalModule,
 } from "./bridgeModule";
 
 export interface BridgeDriver {
@@ -14,6 +16,8 @@ export interface BridgeDriver {
 	events?: BridgeEventsModule;
 	query?: BridgeQueryModule;
 	backup?: BridgeBackupModule;
+	announce?: BridgeAnnounceModule;
+	terminal?: BridgeTerminalModule;
 	panel?: BridgePanel;
 	modules?: Record<string, BridgePanelModule>;
 }