@serverkgg/bridge 0.1.13 → 0.1.15

package/src/runtime/bridgeLiveConfig.test.ts

@@ -2,8 +2,11 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { BridgeKind } from "../core";
+import type { BridgeDriver } from "../modules";
+import { BridgeControl, BridgeFormTarget, BridgeLayout } from "../panel";
 import type { BridgeConfig } from "../protocol";
-import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { createBridgeLiveConfig, variableDefaultsOf } from "./bridgeLiveConfig";
 
 const configWith = (secrets: Record<string, string>, variables: Record<string, string> = {}): BridgeConfig => ({
 	code: "wsvv8fakxm",
@@ -146,4 +149,137 @@ describe("the bridge live config reader", () => {
 		expect(live.memoryMb()).toBe(4096);
 		expect(live.cpuPercent()).toBe(200);
 	});
+
+	it("answers a variable the config does not carry with the default the driver declares", async () => {
+		const config = configWith({});
+
+		await write(config);
+
+		const live = createBridgeLiveConfig(path, config, 0, {
+			WINDOWS_STEAM: "true",
+		});
+
+		expect(live.variable("WINDOWS_STEAM")).toBe("true");
+		expect(live.variables()).toEqual({
+			WINDOWS_STEAM: "true",
+			VERSION: "1.21",
+		});
+	});
+
+	it("answers the value the owner set over the default, and the default again once the value is gone", async () => {
+		const config = configWith(
+			{},
+			{
+				WINDOWS_STEAM: "false",
+			},
+		);
+
+		await write(config);
+
+		const live = createBridgeLiveConfig(path, config, 0, {
+			WINDOWS_STEAM: "true",
+		});
+
+		expect(live.variable("WINDOWS_STEAM")).toBe("false");
+
+		await write(configWith({}));
+
+		expect(live.variable("WINDOWS_STEAM")).toBe("true");
+	});
+
+	it("answers the default for a variable the owner cleared, as the form shows it", async () => {
+		const config = configWith(
+			{},
+			{
+				SERVER_NAME: "",
+			},
+		);
+
+		await write(config);
+
+		const live = createBridgeLiveConfig(path, config, 0, {
+			SERVER_NAME: "Serverk",
+		});
+
+		expect(live.variable("SERVER_NAME")).toBe("Serverk");
+	});
+});
+
+describe("variableDefaultsOf", () => {
+	it("collects the default of every form field that declares one", () => {
+		const driver: BridgeDriver = {
+			install: {
+				kind: BridgeKind.Install,
+				run: async () => {
+					return;
+				},
+			},
+			lifecycle: {
+				kind: BridgeKind.Lifecycle,
+				command: async () => [
+					"run",
+				],
+			},
+			panel: {
+				tabs: [
+					{
+						id: "server",
+						title: {
+							ar: "السيرفر",
+							en: "Server",
+						},
+						sections: [
+							{
+								layout: BridgeLayout.Form,
+								id: "steam",
+								target: BridgeFormTarget.Variables,
+								fields: [
+									{
+										key: "WINDOWS_STEAM",
+										control: BridgeControl.Boolean,
+										label: {
+											ar: "تفعيل Steam",
+											en: "Use Steam",
+										},
+										default: "true",
+									},
+									{
+										key: "SERVER_NAME",
+										control: BridgeControl.Text,
+										label: {
+											ar: "الاسم",
+											en: "Name",
+										},
+									},
+								],
+							},
+						],
+					},
+				],
+			},
+		};
+
+		expect(variableDefaultsOf(driver)).toEqual({
+			WINDOWS_STEAM: "true",
+		});
+	});
+
+	it("answers no defaults for a driver without a panel", () => {
+		expect(
+			variableDefaultsOf({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+			}),
+		).toEqual({});
+	});
 });

package/src/runtime/bridgeLiveConfig.ts

@@ -1,4 +1,6 @@
 import { readFileSync } from "node:fs";
+import type { BridgeDriver } from "../modules";
+import { BridgeLayout } from "../panel";
 import type { BridgeConfig } from "../protocol";
 import { parseConfig } from "./bridgeConfigReader";
 
@@ -20,15 +22,54 @@ export interface BridgeLiveConfig {
 	memoryMb: () => number;
 	cpuPercent: () => number;
 	publicAddress: () => string | null;
+	playerAddress: () => string | null;
 	reload: () => void;
 }
 
+export const variableDefaultsOf = (driver: BridgeDriver): Record<string, string> => {
+	const defaults: Record<string, string> = {};
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (section.layout !== BridgeLayout.Form) {
+				continue;
+			}
+
+			for (const field of section.fields) {
+				if (field.default !== undefined) {
+					defaults[field.key] = field.default;
+				}
+			}
+		}
+	}
+
+	return defaults;
+};
+
 export const createBridgeLiveConfig = (
 	path: string,
 	config: BridgeConfig,
 	refreshMs: number = BRIDGE_CONFIG_REFRESH_MS,
+	defaults: Readonly<Record<string, string>> = {},
 ): BridgeLiveConfig => {
-	let current = config;
+	const withDefaults = (read: BridgeConfig): BridgeConfig => {
+		const variables = {
+			...read.variables,
+		};
+
+		for (const [key, value] of Object.entries(defaults)) {
+			if (!variables[key]) {
+				variables[key] = value;
+			}
+		}
+
+		return {
+			...read,
+			variables,
+		};
+	};
+
+	let current = withDefaults(config);
 
 	let checkedAt: number | null = null;
 
@@ -42,7 +83,7 @@ export const createBridgeLiveConfig = (
 		checkedAt = stamp;
 
 		try {
-			current = parseConfig(readFileSync(path, "utf8"));
+			current = withDefaults(parseConfig(readFileSync(path, "utf8")));
 		} catch {
 			return current;
 		}
@@ -72,6 +113,9 @@ export const createBridgeLiveConfig = (
 		publicAddress() {
 			return refresh().publicAddress ?? null;
 		},
+		playerAddress() {
+			return refresh().playerAddress ?? null;
+		},
 		reload() {
 			checkedAt = null;
 

package/src/runtime/bridgeRegistry.test.ts

@@ -14,6 +14,9 @@ import { BridgeControl, BridgeFormTarget, BridgeLayout } from "../panel";
 import {
 	BRIDGE_ACTIVITY_KEYS,
 	BRIDGE_TEXT_LENGTH_LIMIT,
+	type BridgeCatalogEntry,
+	type BridgeCatalogPage,
+	BridgeCatalogSourceKind,
 	type BridgeConfig,
 	BridgeConfirm,
 	BridgeEventName,
@@ -742,6 +745,223 @@ describe("detail modules", () => {
 	});
 });
 
+describe("catalog modules", () => {
+	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 emptyPage = async (): Promise<BridgeCatalogPage> => ({
+		hits: [],
+		total: 0,
+		providers: [],
+		categories: [],
+		sorts: [],
+	});
+
+	const WORKSHOP = {
+		kind: BridgeCatalogSourceKind.Workshop,
+		appId: 1_623_730,
+		provided: [
+			"UE4SS",
+			"PalSchema",
+		],
+	};
+
+	const driver = (added: string[] = []): BridgeDriver => ({
+		...baseDriver(),
+		modules: {
+			mods: {
+				kind: BridgeKind.Catalog,
+				source: WORKSHOP,
+				installed: async () => [],
+				install: async (_context, id) => entry(id),
+				add: async (_context, input) => {
+					added.push(input);
+
+					return entry("upload:BetterMap");
+				},
+				remove: async () => {
+					return;
+				},
+				toggle: async () => {
+					return;
+				},
+			},
+			addons: {
+				kind: BridgeKind.Catalog,
+				search: emptyPage,
+				releases: async () => [],
+				preview: async () => ({
+					confirm: BridgeConfirm.Normal,
+					lines: [],
+				}),
+				installed: async () => [],
+				install: async (_context, id) => entry(id),
+				remove: async () => {
+					return;
+				},
+			},
+		},
+	});
+
+	it("advertises search and preview for a sourced catalog, never releases, and carries its source", () => {
+		expect(registryFor(driver()).manifest().modules).toEqual([
+			{
+				id: "mods",
+				kind: BridgeKind.Catalog,
+				requiresRunning: false,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					BridgeAction.Preview,
+					BridgeAction.Install,
+					BridgeAction.Installed,
+					BridgeAction.Remove,
+					BridgeAction.Search,
+					BridgeAction.Add,
+					BridgeAction.Toggle,
+				],
+				source: WORKSHOP,
+			},
+			{
+				id: "addons",
+				kind: BridgeKind.Catalog,
+				requiresRunning: false,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					BridgeAction.Releases,
+					BridgeAction.Preview,
+					BridgeAction.Install,
+					BridgeAction.Installed,
+					BridgeAction.Remove,
+					BridgeAction.Search,
+				],
+			},
+		]);
+	});
+
+	it("hands add the staged input and answers the entry it installed", async () => {
+		const added: string[] = [];
+		const { result } = await registryFor(driver(added)).invoke("mods", BridgeAction.Add, {
+			input: ".serverk-staging/mods-upload/BetterMap",
+		});
+
+		expect(added).toEqual([
+			".serverk-staging/mods-upload/BetterMap",
+		]);
+		expect(result).toEqual(entry("upload:BetterMap"));
+	});
+
+	it("refuses an add with no staged input before the driver is entered", async () => {
+		const added: string[] = [];
+
+		await expect(registryFor(driver(added)).invoke("mods", BridgeAction.Add, {})).rejects.toThrow(
+			'"input" must be a non-empty string',
+		);
+		expect(added).toEqual([]);
+	});
+
+	it("refuses an add on a catalog that defines none", async () => {
+		await expect(
+			registryFor(driver()).invoke("addons", BridgeAction.Add, {
+				input: ".serverk-staging/mods-upload/BetterMap",
+			}),
+		).rejects.toThrow('module "addons" does not support "add"');
+	});
+
+	it("refuses search, preview and releases on a sourced catalog, which the platform answers", async () => {
+		const registry = registryFor(driver());
+
+		for (const action of [
+			BridgeAction.Search,
+			BridgeAction.Preview,
+			BridgeAction.Releases,
+		]) {
+			const refused = registry.invoke("mods", action, {
+				id: "3762839811",
+			});
+
+			await expect(refused).rejects.toBeInstanceOf(BridgeRefusalError);
+			await expect(refused).rejects.toThrow(
+				`module "mods" takes its items from the workshop source, so the platform answers "${action}"`,
+			);
+		}
+	});
+
+	it("hands back the note an entry carries, unchanged through the wire's JSON", async () => {
+		const noted: BridgeCatalogEntry = {
+			...entry("3762839811"),
+			note: {
+				ar: "يشتغل بعد إعادة التشغيل",
+				en: "Runs after a restart",
+			},
+		};
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				mods: {
+					kind: BridgeKind.Catalog,
+					source: WORKSHOP,
+					installed: async () => [
+						noted,
+					],
+					install: async () => noted,
+					remove: async () => {
+						return;
+					},
+				},
+			},
+		});
+
+		const { result: installed } = await registry.invoke("mods", BridgeAction.Installed);
+		const { result: install } = await registry.invoke("mods", BridgeAction.Install, {
+			id: "3762839811",
+		});
+
+		expect(JSON.parse(JSON.stringify(installed))).toEqual([
+			noted,
+		]);
+		expect(JSON.parse(JSON.stringify(install))).toEqual(noted);
+	});
+
+	it("still answers search, releases and preview on a catalog that answers its own search", async () => {
+		const registry = registryFor(driver());
+
+		expect((await registry.invoke("addons", BridgeAction.Search)).result).toEqual(await emptyPage());
+		expect(
+			(
+				await registry.invoke("addons", BridgeAction.Releases, {
+					id: "sodium",
+				})
+			).result,
+		).toEqual([]);
+		expect(
+			(
+				await registry.invoke("addons", BridgeAction.Preview, {
+					id: "sodium",
+				})
+			).result,
+		).toEqual({
+			confirm: BridgeConfirm.Normal,
+			lines: [],
+		});
+	});
+});
+
 describe("the setup singleton", () => {
 	it("rides the manifest as its own block and never joins the panel modules", () => {
 		const steps = [

package/src/runtime/bridgeRegistry.ts

@@ -97,6 +97,16 @@ const pageSizeOf = (module: BridgePanelModule) => {
 	return module.kind === BridgeKind.Catalog ? (module.pageSize ?? null) : null;
 };
 
+const sourceOf = (module: BridgePanelModule) => {
+	return module.kind === BridgeKind.Catalog ? (module.source ?? null) : null;
+};
+
+const SOURCED_CATALOG_ACTIONS: readonly string[] = [
+	BridgeAction.Preview,
+	BridgeAction.Releases,
+	BridgeAction.Search,
+];
+
 const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTerminalManifest | null => {
 	if (!module) {
 		return null;
@@ -750,13 +760,19 @@ export const createRegistry = (
 			}
 
 			case BridgeKind.Catalog: {
+				if (module.source && SOURCED_CATALOG_ACTIONS.includes(action)) {
+					throw new BridgeRefusalError(
+						`module "${name}" takes its items from the ${module.source.kind} source, so the platform answers "${action}"`,
+					);
+				}
+
 				if (action === BridgeAction.Releases && module.releases) {
 					return await module.releases(context, asString(args, "id"));
 				}
 				if (action === BridgeAction.Preview && module.preview) {
 					return await module.preview(context, asString(args, "id"), asOptional(args, "releaseId") ?? undefined);
 				}
-				if (action === BridgeAction.Search) {
+				if (action === BridgeAction.Search && module.search) {
 					return await module.search(context, {
 						query: asText(args, "query"),
 						page: asPage(args),
@@ -774,6 +790,10 @@ export const createRegistry = (
 					return await module.install(context, asString(args, "id"), asOptional(args, "releaseId") ?? undefined);
 				}
 
+				if (action === BridgeAction.Add && module.add) {
+					return await module.add(context, asString(args, "input"));
+				}
+
 				if (action === BridgeAction.Remove) {
 					const id = asString(args, "id");
 
@@ -803,6 +823,7 @@ export const createRegistry = (
 		manifest(): BridgeManifest {
 			const entries: BridgeModuleManifest[] = Object.entries(modules).map(([id, module]) => {
 				const protectedActions = protectedActionsOf(module);
+				const source = sourceOf(module);
 				return {
 					id,
 					kind: module.kind,
@@ -816,6 +837,11 @@ export const createRegistry = (
 								protectedActions,
 							}
 						: {}),
+					...(source
+						? {
+								source,
+							}
+						: {}),
 				};
 			});
 

package/src/runtime/bridgeSample.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import { idleSample, sampleResultOf } from "./bridgeSample";
+
+describe("sampleResultOf", () => {
+	it("serves no tick for an older driver that reports only its players", () => {
+		expect(
+			sampleResultOf({
+				online: 3,
+				max: 16,
+			}),
+		).toEqual({
+			online: 3,
+			max: 16,
+			tick: null,
+		});
+	});
+
+	it("carries the milliseconds per tick a driver measured", () => {
+		expect(
+			sampleResultOf({
+				online: 3,
+				max: 16,
+				tick: 21.4,
+			}).tick,
+		).toBe(21.4);
+	});
+
+	it("keeps a tick a driver could not measure as null", () => {
+		expect(
+			sampleResultOf({
+				online: null,
+				max: null,
+				tick: null,
+			}).tick,
+		).toBeNull();
+	});
+
+	for (const tick of [
+		-1,
+		Number.NaN,
+		Number.POSITIVE_INFINITY,
+	]) {
+		it(`drops a tick of ${tick}, which no game measures`, () => {
+			expect(
+				sampleResultOf({
+					online: 3,
+					max: 16,
+					tick,
+				}).tick,
+			).toBeNull();
+		});
+	}
+});
+
+describe("idleSample", () => {
+	it("reports no players and no tick while the game is not running", () => {
+		expect(idleSample()).toEqual({
+			online: null,
+			max: null,
+			tick: null,
+		});
+	});
+});

package/src/runtime/bridgeSample.ts

@@ -0,0 +1,22 @@
+import type { BridgeSample } from "../modules";
+import type { BridgeSampleResult } from "../protocol";
+
+export const idleSample = (): BridgeSampleResult => {
+	return {
+		online: null,
+		max: null,
+		tick: null,
+	};
+};
+
+const tickOf = (tick: number | null | undefined): number | null => {
+	return typeof tick === "number" && Number.isFinite(tick) && tick >= 0 ? tick : null;
+};
+
+export const sampleResultOf = (sample: BridgeSample): BridgeSampleResult => {
+	return {
+		online: sample.online,
+		max: sample.max,
+		tick: tickOf(sample.tick),
+	};
+};

package/src/runtime/serve.ts

@@ -18,7 +18,7 @@ import { createContext } from "./bridgeContext";
 import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
 import { decideInstall, recountHold } from "./bridgeInstall";
-import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { BRIDGE_CONFIG_REFRESH_MS, createBridgeLiveConfig, variableDefaultsOf } from "./bridgeLiveConfig";
 import { errorDetail, errorText, print, log as stdoutLog } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
 import {
@@ -29,6 +29,7 @@ import {
 	secretFieldKeys,
 } from "./bridgeRedaction";
 import { createRegistry } from "./bridgeRegistry";
+import { idleSample, sampleResultOf } from "./bridgeSample";
 import { createServer } from "./bridgeServer";
 import { setupSummaryOf } from "./bridgeSetup";
 import { createSetupHandlers } from "./bridgeSetupHandlers";
@@ -90,7 +91,7 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const desired = await readDesired(statePath(config));
 
-	const live = createBridgeLiveConfig(configPath(), config);
+	const live = createBridgeLiveConfig(configPath(), config, BRIDGE_CONFIG_REFRESH_MS, variableDefaultsOf(driver));
 
 	const redact = createBridgeRedaction(secretFieldKeys(driver), live);
 
@@ -266,10 +267,7 @@ export const serve = async (driver: BridgeDriver) => {
 		}
 
 		if (!supervisor.running) {
-			return {
-				online: null,
-				max: null,
-			};
+			return idleSample();
 		}
 
 		const stamp = performance.now();
@@ -278,12 +276,7 @@ export const serve = async (driver: BridgeDriver) => {
 			return sampled.value;
 		}
 
-		const result = await query.sample(context);
-
-		const value: BridgeSampleResult = {
-			online: result.online,
-			max: result.max,
-		};
+		const value = sampleResultOf(await query.sample(context));
 
 		sampled = {
 			value,

package/src/steam/workshop.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "bun:test";
-import { workshopContentPath, workshopDownloadArgs, workshopFormBody } from "./workshop";
+import {
+	workshopArchivePath,
+	workshopContentPath,
+	workshopDownloadArgs,
+	workshopFormBody,
+	workshopItemPageUrl,
+} from "./workshop";
 
 describe("workshopFormBody", () => {
 	it("writes the count and the indexed ids", () => {
@@ -43,3 +49,15 @@ describe("workshopContentPath", () => {
 		expect(workshopContentPath("440900", "12345")).toBe("steamapps/workshop/content/440900/12345");
 	});
 });
+
+describe("workshopArchivePath", () => {
+	it("names the archive the platform pushes for one item", () => {
+		expect(workshopArchivePath(1_623_730, "3762839811")).toBe(".serverk/snapshots/workshop-1623730-3762839811.zip");
+	});
+});
+
+describe("workshopItemPageUrl", () => {
+	it("links the item's steam community page", () => {
+		expect(workshopItemPageUrl("3762839811")).toBe("https://steamcommunity.com/sharedfiles/filedetails/?id=3762839811");
+	});
+});