@serverkgg/bridge 0.1.13 → 0.1.15

package/src/runtime/bridgeDriver.test.ts

@@ -4,10 +4,12 @@ import { BridgeKind, BridgeSetupStepKind, PortJoin, PortProtocol } from "../core
 import { GuideOpenTab } from "../guides";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
 import {
+	type BridgeCatalogModule,
 	type BridgeDriver,
 	BridgeLifecycleSubject,
 	type BridgePendingModule,
 	type BridgeSetupModule,
+	type BridgeSourcedCatalogModule,
 	BridgeStopSignal,
 } from "../modules";
 import {
@@ -23,7 +25,7 @@ import {
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
-import type { BridgeSetupStep } from "../protocol";
+import { type BridgeCatalogEntry, BridgeCatalogSourceKind, type BridgeSetupStep } from "../protocol";
 import { validateDriver, validatePortActivation } from "./bridgeDriver";
 
 const text = (value: string) => ({
@@ -1030,6 +1032,212 @@ describe("table uploads", () => {
 	});
 });
 
+describe("catalog sources and uploads", () => {
+	const entry = (id: string): BridgeCatalogEntry => ({
+		id,
+		provider: null,
+		path: `Mods/${id}`,
+		title: id,
+		version: null,
+		sizeBytes: 0,
+		enabled: true,
+		gameVersion: null,
+		stale: false,
+		pageUrl: null,
+		icon: null,
+	});
+
+	const sourced = (overrides: Partial<BridgeSourcedCatalogModule> = {}): BridgeSourcedCatalogModule => ({
+		kind: BridgeKind.Catalog,
+		source: {
+			kind: BridgeCatalogSourceKind.Workshop,
+			appId: 1_623_730,
+			provided: [
+				"UE4SS",
+			],
+		},
+		installed: async () => [],
+		install: async (_context, id) => entry(id),
+		remove: async () => {
+			return;
+		},
+		...overrides,
+	});
+
+	const modsUpload: BridgeSectionUpload = {
+		label: text("Upload a mod"),
+		extensions: [
+			"zip",
+		],
+		staging: ".serverk-staging/mods-upload",
+		mode: BridgeUploadMode.Archive,
+	};
+
+	const driverWithCatalog = (mods: BridgeCatalogModule, upload?: BridgeSectionUpload): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules: {
+			mods,
+		},
+		panel: {
+			tabs: [
+				{
+					id: "mods",
+					title: text("Mods"),
+					sections: [
+						{
+							layout: BridgeLayout.Catalog,
+							id: "mods",
+							module: "mods",
+							...(upload
+								? {
+										upload,
+									}
+								: {}),
+						},
+					],
+				},
+			],
+		},
+	});
+
+	it("accepts a sourced catalog that leaves search to the platform", () => {
+		expect(() => validateDriver(driverWithCatalog(sourced()))).not.toThrow();
+	});
+
+	it("rejects a catalog that has neither a source nor its own search", () => {
+		const { source: _source, ...unsourced } = sourced();
+
+		expect(() => validateDriver(driverWithCatalog(unsourced as unknown as BridgeCatalogModule))).toThrow(
+			'module "mods" declares no search — a catalog without a source answers its own search',
+		);
+	});
+
+	it("rejects a source the platform does not serve", () => {
+		const mods = sourced({
+			source: {
+				kind: "nexus" as BridgeCatalogSourceKind,
+				appId: 1_623_730,
+			},
+		});
+
+		expect(() => validateDriver(driverWithCatalog(mods))).toThrow(
+			'module "mods" declares source "nexus" — the platform serves only workshop',
+		);
+	});
+
+	it("rejects a source app id that is not a positive whole number", () => {
+		for (const appId of [
+			0,
+			-1,
+			1.5,
+		]) {
+			const mods = sourced({
+				source: {
+					kind: BridgeCatalogSourceKind.Workshop,
+					appId,
+				},
+			});
+
+			expect(() => validateDriver(driverWithCatalog(mods))).toThrow("it must be a positive whole number");
+		}
+	});
+
+	it("rejects a provided name that is not a non-empty string", () => {
+		for (const name of [
+			"",
+			7,
+		]) {
+			const mods = sourced({
+				source: {
+					kind: BridgeCatalogSourceKind.Workshop,
+					appId: 1_623_730,
+					provided: [
+						name as string,
+					],
+				},
+			});
+
+			expect(() => validateDriver(driverWithCatalog(mods))).toThrow(
+				"source declares a provided name that is not a non-empty string",
+			);
+		}
+	});
+
+	it("rejects more provided names than the platform takes", () => {
+		const mods = sourced({
+			source: {
+				kind: BridgeCatalogSourceKind.Workshop,
+				appId: 1_623_730,
+				provided: Array.from(
+					{
+						length: 17,
+					},
+					(_entry, index) => `Pack${index}`,
+				),
+			},
+		});
+
+		expect(() => validateDriver(driverWithCatalog(mods))).toThrow("declares 17 provided names");
+	});
+
+	it("rejects a sourced catalog that answers its own search", () => {
+		const mods = {
+			...sourced(),
+			search: async () => ({
+				hits: [],
+				total: 0,
+				providers: [],
+				categories: [],
+				sorts: [],
+			}),
+		} as unknown as BridgeCatalogModule;
+
+		expect(() => validateDriver(driverWithCatalog(mods))).toThrow(
+			'module "mods" declares a source and its own search — the platform answers search for a sourced catalog',
+		);
+	});
+
+	it("accepts a catalog upload whose module installs it through add", () => {
+		const mods = sourced({
+			add: async () => entry("upload"),
+		});
+
+		expect(() => validateDriver(driverWithCatalog(mods, modsUpload))).not.toThrow();
+	});
+
+	it("rejects a catalog upload whose module has no add handler", () => {
+		expect(() => validateDriver(driverWithCatalog(sourced(), modsUpload))).toThrow(
+			'tab "mods" section "mods" declares an upload control but module "mods" has no add handler',
+		);
+	});
+
+	it("checks a catalog upload as it checks a table upload", () => {
+		const mods = sourced({
+			add: async () => entry("upload"),
+		});
+
+		expect(() =>
+			validateDriver(
+				driverWithCatalog(mods, {
+					...modsUpload,
+					extensions: [],
+				}),
+			),
+		).toThrow("declares an upload control with no extensions");
+	});
+});
+
 describe("the pending module", () => {
 	const driverWithPending = (pending: BridgePendingModule): BridgeDriver => ({
 		install: {
@@ -1691,6 +1899,144 @@ describe("field patterns", () => {
 	});
 });
 
+describe("field defaults", () => {
+	it("takes a default on a boolean, a select and a text field of a variables form", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "WINDOWS_STEAM",
+						control: BridgeControl.Boolean,
+						label: text("Use Steam"),
+						default: "true",
+					},
+					{
+						key: "DIFFICULTY",
+						control: BridgeControl.Select,
+						label: text("Difficulty"),
+						options: [
+							{
+								value: "normal",
+								label: text("Normal"),
+							},
+						],
+						default: "normal",
+					},
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						maxLength: 8,
+						default: "Serverk",
+					},
+				]),
+			),
+		).not.toThrow();
+	});
+
+	it("rejects a boolean default other than true or false", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "WINDOWS_STEAM",
+						control: BridgeControl.Boolean,
+						label: text("Use Steam"),
+						default: "yes",
+					},
+				]),
+			),
+		).toThrow('declares default "yes" on a boolean control — use "true" or "false"');
+	});
+
+	it("rejects a select default that is not one of its options", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "DIFFICULTY",
+						control: BridgeControl.Select,
+						label: text("Difficulty"),
+						options: [
+							{
+								value: "normal",
+								label: text("Normal"),
+							},
+						],
+						default: "hard",
+					},
+				]),
+			),
+		).toThrow('declares default "hard", which is not one of its options');
+	});
+
+	it("rejects a default on a secret field", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "ADMIN_PASSWORD",
+						control: BridgeControl.Secret,
+						label: text("Admin password"),
+						default: "letmein1",
+					},
+				]),
+			),
+		).toThrow("declares a default on a secret control — a secret is never preset");
+	});
+
+	it("rejects a default longer than the field takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						maxLength: 4,
+						default: "Serverk",
+					},
+				]),
+			),
+		).toThrow("default is 7 characters — the platform takes at most 4");
+	});
+
+	it("rejects a default longer than the platform takes, even when the field takes more", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "MOTD",
+						control: BridgeControl.Text,
+						label: text("Message"),
+						maxLength: 1024,
+						default: "a".repeat(257),
+					},
+				]),
+			),
+		).toThrow("default is 257 characters — the platform takes at most 256");
+	});
+
+	it("rejects a default on an action field, which is no variable", () => {
+		expect(() =>
+			validateDriver(
+				driverWithActions([
+					{
+						id: "say",
+						label: text("Say"),
+						fields: [
+							{
+								...field("message"),
+								default: "hello",
+							},
+						],
+					},
+				]),
+			),
+		).toThrow("declares a default outside a form that targets variables");
+	});
+});
+
 describe("section placement", () => {
 	const anyVisibleWhen: BridgeVisibleWhen = {
 		variable: "MODPACK",

package/src/runtime/bridgeDriver.ts

@@ -1,6 +1,7 @@
 import {
 	BRIDGE_ID_PATTERN,
 	BRIDGE_MODULE_ID_PATTERN,
+	BridgeAction,
 	BridgeKind,
 	BridgeSetupStepKind,
 	isReadAction,
@@ -9,6 +10,7 @@ import {
 import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
 import {
+	type BridgeCatalogModule,
 	type BridgeDriver,
 	BridgeLifecycleSubject,
 	type BridgePanelModule,
@@ -24,12 +26,15 @@ import {
 	BridgePlace,
 	type BridgeSection,
 	type BridgeSectionAction,
+	type BridgeSectionUpload,
 	type BridgeTab,
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
 import {
 	BRIDGE_ACTION_FIELDS_LIMIT,
+	BRIDGE_CATALOG_PROVIDED_LIMIT,
+	BRIDGE_DEFAULT_LENGTH_LIMIT,
 	BRIDGE_DEPENDS_ON_LIMIT,
 	BRIDGE_EVENTS_LIMIT,
 	BRIDGE_EXTENSION_LENGTH_LIMIT,
@@ -44,6 +49,7 @@ import {
 	BRIDGE_PANEL_TABS_LIMIT,
 	BRIDGE_PATTERN_LENGTH_LIMIT,
 	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
+	BRIDGE_PROVIDED_NAME_LENGTH_LIMIT,
 	BRIDGE_ROW_ACTIONS_LIMIT,
 	BRIDGE_SECTION_ACTIONS_LIMIT,
 	BRIDGE_SETUP_STEPS_LIMIT,
@@ -53,11 +59,14 @@ import {
 	BRIDGE_TEXT_LENGTH_LIMIT,
 	BRIDGE_UPLOAD_EXTENSIONS_LIMIT,
 	BRIDGE_VISIBLE_VALUES_LIMIT,
+	BridgeCatalogSourceKind,
 } from "../protocol";
 import { actionsOf } from "./bridgeActions";
 
 const UPLOAD_MODES = new Set<string>(Object.values(BridgeUploadMode));
 
+const CATALOG_SOURCE_KINDS = new Set<string>(Object.values(BridgeCatalogSourceKind));
+
 const READY_TIMEOUT_MIN_SECONDS = 1;
 
 const READY_TIMEOUT_MAX_SECONDS = 3600;
@@ -256,7 +265,41 @@ const validateVisibleWhen = (visibleWhen: BridgeVisibleWhen | undefined, where:
 	countIn((visibleWhen.values ?? []).length, BRIDGE_VISIBLE_VALUES_LIMIT, "visible values", where);
 };
 
-const validateFields = (modules: Record<string, BridgePanelModule>, fields: BridgeField[], where: string) => {
+const validateDefault = (field: BridgeField, variables: boolean, at: string) => {
+	if (field.default === undefined) {
+		return;
+	}
+
+	if (!variables) {
+		fail(`${at} declares a default outside a form that targets variables — only a variable has one`);
+	}
+
+	if (field.control === BridgeControl.Secret) {
+		fail(`${at} declares a default on a secret control — a secret is never preset`);
+	}
+
+	if (field.control === BridgeControl.Boolean && field.default !== "true" && field.default !== "false") {
+		fail(`${at} declares default "${field.default}" on a boolean control — use "true" or "false"`);
+	}
+
+	if (Array.isArray(field.options) && !field.options.some((option) => option.value === field.default)) {
+		fail(`${at} declares default "${field.default}", which is not one of its options`);
+	}
+
+	lengthIn(
+		field.default,
+		Math.min(field.maxLength ?? BRIDGE_DEFAULT_LENGTH_LIMIT, BRIDGE_DEFAULT_LENGTH_LIMIT),
+		"default",
+		at,
+	);
+};
+
+const validateFields = (
+	modules: Record<string, BridgePanelModule>,
+	fields: BridgeField[],
+	where: string,
+	variables = false,
+) => {
 	const keys = new Set<string>();
 
 	for (const field of fields) {
@@ -274,6 +317,7 @@ const validateFields = (modules: Record<string, BridgePanelModule>, fields: Brid
 		validateText(field.warning, "warning", at);
 		validateText(field.patternHint, "pattern hint", at);
 		validateVisibleWhen(field.visibleWhen, at);
+		validateDefault(field, variables, at);
 
 		if (field.placeholder) {
 			lengthIn(field.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "placeholder", at);
@@ -388,6 +432,25 @@ const validateOffline = (section: BridgeSection, where: string) => {
 	}
 };
 
+const validateUpload = (upload: BridgeSectionUpload, where: string) => {
+	validateText(upload.label, "upload label", where);
+	lengthIn(upload.staging, BRIDGE_STAGING_LENGTH_LIMIT, "upload staging path", where);
+
+	if (upload.extensions.length === 0) {
+		fail(`${where} declares an upload control with no extensions`);
+	}
+
+	countIn(upload.extensions.length, BRIDGE_UPLOAD_EXTENSIONS_LIMIT, "upload extensions", where);
+
+	for (const extension of upload.extensions) {
+		lengthIn(extension, BRIDGE_EXTENSION_LENGTH_LIMIT, `upload extension "${extension}"`, where);
+	}
+
+	if (upload.mode !== undefined && !UPLOAD_MODES.has(upload.mode)) {
+		fail(`${where} declares an unknown upload mode "${upload.mode}"`);
+	}
+};
+
 const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
 	validateVisibleWhen(section.visibleWhen, where);
 	validateText(section.title, "title", where);
@@ -462,7 +525,7 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 			}
 
 			countIn(section.fields.length, BRIDGE_FORM_FIELDS_LIMIT, "fields", where);
-			validateFields(modules, section.fields, where);
+			validateFields(modules, section.fields, where, section.target === BridgeFormTarget.Variables);
 
 			const clears = section.clears ?? [];
 
@@ -558,22 +621,7 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				}
 
 				if (section.upload) {
-					validateText(section.upload.label, "upload label", where);
-					lengthIn(section.upload.staging, BRIDGE_STAGING_LENGTH_LIMIT, "upload staging path", where);
-
-					if (section.upload.extensions.length === 0) {
-						fail(`${where} declares an upload control with no extensions`);
-					}
-
-					countIn(section.upload.extensions.length, BRIDGE_UPLOAD_EXTENSIONS_LIMIT, "upload extensions", where);
-
-					for (const extension of section.upload.extensions) {
-						lengthIn(extension, BRIDGE_EXTENSION_LENGTH_LIMIT, `upload extension "${extension}"`, where);
-					}
-
-					if (section.upload.mode !== undefined && !UPLOAD_MODES.has(section.upload.mode)) {
-						fail(`${where} declares an unknown upload mode "${section.upload.mode}"`);
-					}
+					validateUpload(section.upload, where);
 				}
 			}
 
@@ -598,15 +646,75 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 
 			if (module.kind !== BridgeKind.Catalog) {
 				fail(`${where} references "${section.module}", which is not a catalog module`);
+
+				return;
 			}
 
 			validateText(section.confirmText, "confirm text", where);
 
+			if (section.upload) {
+				if (!module.add) {
+					fail(`${where} declares an upload control but module "${section.module}" has no add handler`);
+				}
+
+				validateUpload(section.upload, where);
+			}
+
 			return;
 		}
 	}
 };
 
+const validateCatalog = (module: BridgeCatalogModule, where: string) => {
+	if (module.source === undefined) {
+		if (typeof module.search !== "function") {
+			fail(`${where} declares no search — a catalog without a source answers its own search`);
+		}
+
+		return;
+	}
+
+	const { source } = module;
+
+	if (!CATALOG_SOURCE_KINDS.has(source.kind)) {
+		fail(
+			`${where} declares source "${String(source.kind)}" — the platform serves only ${[
+				...CATALOG_SOURCE_KINDS,
+			].join(" or ")}`,
+		);
+	}
+
+	if (!(Number.isSafeInteger(source.appId) && source.appId > 0)) {
+		fail(`${where} declares source app id ${String(source.appId)} — it must be a positive whole number`);
+	}
+
+	const provided: unknown[] = source.provided ?? [];
+
+	countIn(provided.length, BRIDGE_CATALOG_PROVIDED_LIMIT, "provided names", `${where} source`);
+
+	for (const name of provided) {
+		if (typeof name !== "string" || name.length === 0) {
+			fail(`${where} source declares a provided name that is not a non-empty string`);
+
+			continue;
+		}
+
+		lengthIn(name, BRIDGE_PROVIDED_NAME_LENGTH_LIMIT, `provided name "${name}"`, `${where} source`);
+	}
+
+	const platformAnswers: Record<string, unknown> = {
+		[BridgeAction.Search]: module.search,
+		[BridgeAction.Releases]: module.releases,
+		[BridgeAction.Preview]: module.preview,
+	};
+
+	for (const [action, handler] of Object.entries(platformAnswers)) {
+		if (handler !== undefined) {
+			fail(`${where} declares a source and its own ${action} — the platform answers ${action} for a sourced catalog`);
+		}
+	}
+};
+
 const validateLifecycle = (driver: BridgeDriver) => {
 	const environment: unknown = driver.lifecycle.environment;
 
@@ -827,6 +935,10 @@ export const validateDriver = (driver: BridgeDriver) => {
 			countIn((module.dependsOn ?? []).length, BRIDGE_DEPENDS_ON_LIMIT, "dependencies", `module "${id}"`);
 		}
 
+		if (module.kind === BridgeKind.Catalog) {
+			validateCatalog(module, `module "${id}"`);
+		}
+
 		if (
 			module.kind === BridgeKind.Actions
 			|| module.kind === BridgeKind.Collection