@serverkgg/bridge 0.0.18 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.18",
+	"version": "0.0.20",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/src/core/bridgeValue.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import type { BridgeRow } from "./bridgeValue";
 import { isLocalizedText } from "./bridgeValue";
 
 describe("isLocalizedText", () => {
@@ -27,3 +28,20 @@ describe("isLocalizedText", () => {
 		).toBe(false);
 	});
 });
+
+describe("BridgeRow", () => {
+	test('carries a localized cell beside its scalars so a driver never writes "English / عربي" into one string', () => {
+		const row: BridgeRow = {
+			id: "u-1",
+			kills: 12,
+			banned: false,
+			status: {
+				ar: "متصل",
+				en: "Online",
+			},
+		};
+
+		expect(isLocalizedText(row.status)).toBe(true);
+		expect(isLocalizedText(row.kills)).toBe(false);
+	});
+});

package/src/core/bridgeValue.ts

@@ -2,15 +2,19 @@ export type BridgeValue = boolean | number | string | null;
 
 export type BridgeValues = Record<string, BridgeValue>;
 
-export type BridgeRow = BridgeValues & {
-	id: string;
-};
-
 export interface LocalizedText {
 	ar: string;
 	en: string;
 }
 
+export type BridgeCell = BridgeValue | LocalizedText;
+
+export type BridgeCells = Record<string, BridgeCell>;
+
+export type BridgeRow = BridgeCells & {
+	id: string;
+};
+
 export type BridgeCopy = LocalizedText | string;
 
 export const isLocalizedText = (value: unknown): value is LocalizedText => {

package/src/modules/bridge.ts

@@ -1,5 +1,7 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
 import type {
+	BridgeCell,
+	BridgeCells,
 	BridgeCopy,
 	BridgeInstallHold,
 	BridgeInstallOutcome,
@@ -83,6 +85,8 @@ export namespace Bridge {
 	export type CatalogPage = BridgeCatalogPage;
 	export type CatalogProvider = BridgeCatalogProvider;
 	export type CatalogQuery = BridgeCatalogQuery;
+	export type Cell = BridgeCell;
+	export type Cells = BridgeCells;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
 	export type Copy = BridgeCopy;

package/src/rcon/rconAccess.test.ts

@@ -286,6 +286,35 @@ describe("rconAccessSections", () => {
 		expect(detail.empty).toBeDefined();
 	});
 
+	test("the two sections carry different titles so the panel never repeats a heading", () => {
+		const [form, detail] = rconAccessSections();
+
+		expect(form?.title).toEqual({
+			ar: "الوصول عن بُعد",
+			en: "Remote access",
+		});
+		expect(detail?.title).toEqual({
+			ar: "بيانات الوصول عن بُعد",
+			en: "Remote access details",
+		});
+		expect(detail?.title).not.toEqual(form?.title);
+	});
+
+	test("the detail is visible only while remote access is on", () => {
+		const [, detail] = rconAccessSections();
+
+		if (detail?.layout !== BridgeLayout.Detail) {
+			throw new Error("the second section is the detail");
+		}
+
+		expect(detail.visibleWhen).toEqual({
+			variable: RCON_ACCESS_VARIABLE,
+			values: [
+				"true",
+			],
+		});
+	});
+
 	test("a dedicated port opens a port and a shared one only turns access on", () => {
 		const [dedicated] = rconAccessSections({
 			portKey: RCON_ACCESS_PORT,

package/src/rcon/rconAccess.ts

@@ -49,6 +49,11 @@ const ACCESS_TITLE: LocalizedText = {
 	en: "Remote access",
 };
 
+const ACCESS_DETAIL_TITLE: LocalizedText = {
+	ar: "بيانات الوصول عن بُعد",
+	en: "Remote access details",
+};
+
 const ACCESS_DESCRIPTION: LocalizedText = {
 	ar: "الوصول عن بُعد يخلي أداة خارجية تتحكم بسيرفرك بكلمة المرور هذي. الكلمة تمشي على النت بدون تشفير، فاقفل الوصول لما ما فيه أداة تستخدمه، ولا تعطي الكلمة أحد. لو تسربت غيّرها على طول.",
 	en: "Remote access lets an external tool control your server with this password. The password crosses the internet in the clear, so turn remote access off when no tool is using it, and never share the password. Rotate it the moment it leaks.",
@@ -235,7 +240,7 @@ export const rconAccessSections = (options: RconAccessSectionsOptions = {}): Bri
 		{
 			layout: BridgeLayout.Detail,
 			id: DETAIL_SECTION_ID,
-			title: ACCESS_TITLE,
+			title: ACCESS_DETAIL_TITLE,
 			module: RCON_ACCESS_MODULE,
 			actions: [
 				{
@@ -255,6 +260,12 @@ export const rconAccessSections = (options: RconAccessSectionsOptions = {}): Bri
 				ar: "شغّل سيرفرك مرة عشان تتولد كلمة المرور.",
 				en: "Start your server once to generate the password.",
 			},
+			visibleWhen: {
+				variable: RCON_ACCESS_VARIABLE,
+				values: [
+					"true",
+				],
+			},
 		},
 	];
 };

package/src/runtime/bridgeFiles.test.ts

@@ -981,19 +981,73 @@ describe("list", () => {
 		expect((await files.list("mods/*/*.jar")).map((entry) => entry.path)).toEqual([
 			"mods/custom/plugin.jar",
 		]);
-		await expect(files.list("**/*.jar")).rejects.toThrow("directory depth limit");
+		expect((await files.list("**/*.jar")).map((entry) => entry.path).sort()).toEqual([
+			"mods/custom/plugin.jar",
+			"server.jar",
+		]);
+	});
+	test("prunes subtrees past the depth limit instead of failing the whole listing", async () => {
+		const nested = Array.from(
+			{
+				length: 14,
+			},
+			() => "nested",
+		).join("/");
+		await files.write("resource_packs/pack/manifest.json", "{}");
+		await files.write("resource_packs/pack/pack_icon.png", "icon");
+		await files.write(`resource_packs/pack/models/${nested}/obfuscated.json`, "{}");
+		expect((await files.list("**/*")).map((entry) => entry.path).sort()).toEqual([
+			"resource_packs/pack/manifest.json",
+			"resource_packs/pack/pack_icon.png",
+		]);
+		expect((await files.list("resource_packs/**/*.json")).map((entry) => entry.path)).toEqual([
+			"resource_packs/pack/manifest.json",
+		]);
+		expect(
+			(
+				await files.list("**/*", {
+					directory: "resource_packs/pack",
+				})
+			)
+				.map((entry) => entry.path)
+				.sort(),
+		).toEqual([
+			"resource_packs/pack/manifest.json",
+			"resource_packs/pack/pack_icon.png",
+		]);
 	});
-	test("refuses partial deep listings and unsafe listing roots", async () => {
-		await files.write(
-			`${Array.from(
+	test("warns about what a pruned listing left out", async () => {
+		const lines: string[] = [];
+		const noisy = createBridgeFiles({
+			root,
+			uid: 0,
+			gid: 0,
+			egress,
+			onLog: Object.assign(() => undefined, {
+				warn: (message: string) => {
+					lines.push(message);
+				},
+				error: () => undefined,
+			}),
+		});
+		await noisy.write("manifest.json", "{}");
+		await noisy.write(
+			`models/${Array.from(
 				{
 					length: 14,
 				},
 				() => "nested",
-			).join("/")}/file.txt`,
-			"data",
+			).join("/")}/obfuscated.json`,
+			"{}",
 		);
-		await expect(files.list("**/*")).rejects.toThrow("directory depth limit");
+		expect((await noisy.list("**/*.json")).map((entry) => entry.path)).toEqual([
+			"manifest.json",
+		]);
+		expect(lines).toEqual([
+			"file listing skipped directories deeper than its depth limit",
+		]);
+	});
+	test("refuses unsafe listing roots", async () => {
 		await expect(
 			files.list("**/*", {
 				directory: "../outside",

package/src/runtime/bridgeFiles.ts

@@ -209,10 +209,13 @@ const walk = async (
 	directoryPatterns: RegExp[],
 	scan: {
 		visited: number;
+		pruned: number;
 	},
 ) => {
 	if (depth > WALK_DEPTH) {
-		throw new BridgePathError("invalid", "file listing exceeded its directory depth limit");
+		scan.pruned += 1;
+
+		return;
 	}
 
 	let entries: Dirent[];
@@ -392,9 +395,18 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			if (!resolved.isDirectory) {
 				throw new BridgePathError("invalid", `path "${prefix}" is not a directory to list`);
 			}
-			await walk(resolved.target, prefix, 0, entries, pattern, directoryPatterns, {
+			const scan = {
 				visited: 0,
-			});
+				pruned: 0,
+			};
+			await walk(resolved.target, prefix, 0, entries, pattern, directoryPatterns, scan);
+			if (scan.pruned > 0) {
+				options.onLog.warn("file listing skipped directories deeper than its depth limit", {
+					glob,
+					depth: WALK_DEPTH,
+					skipped: scan.pruned,
+				});
+			}
 			return entries;
 		},
 

package/src/runtime/bridgeSupervisor.test.ts

@@ -4,7 +4,7 @@ import { BridgeRuntime } from "../core";
 import { BridgeCrashPhase, type BridgeCrashRecord } from "../protocol";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { readProcessGroup } from "./bridgeSignal";
-import { createSupervisor } from "./bridgeSupervisor";
+import { type BridgeSupervisor, createSupervisor } from "./bridgeSupervisor";
 
 const CHILD_PATTERN = /child=(?<pid>\d+)/;
 
@@ -169,6 +169,55 @@ const timedSupervisor = (command: () => string, ready: RegExp, stableAfterMs: nu
 	};
 };
 
+const racedSupervisor = (delayMs: number, resolve: () => string[]) => {
+	const pids: number[] = [];
+
+	let launches = 0;
+	let overlapped = false;
+
+	const supervisor: BridgeSupervisor = createSupervisor({
+		cwd: tmpdir(),
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds: 1,
+		onLog: silent,
+		async resolveCommand() {
+			launches += 1;
+
+			if (supervisor.running) {
+				overlapped = true;
+			}
+
+			await Bun.sleep(delayMs);
+
+			return resolve();
+		},
+	});
+
+	supervisor.subscribe((entry) => {
+		const pid = Number(entry.line.match(CHILD_PATTERN)?.groups?.pid);
+
+		if (Number.isSafeInteger(pid)) {
+			pids.push(pid);
+		}
+	});
+
+	return {
+		supervisor,
+		pids,
+		launches: () => launches,
+		overlapped: () => overlapped,
+	};
+};
+
+const wrapperArgv = () => {
+	return [
+		"bash",
+		"-c",
+		WRAPPER,
+	];
+};
+
 describe("createSupervisor", () => {
 	test("runs the game outside the bridge's own process group", async () => {
 		const { supervisor, pid } = await startWrapper(WRAPPER, 1);
@@ -397,4 +446,77 @@ describe("createSupervisor", () => {
 
 		await supervisor.stop();
 	}, 40_000);
+
+	test("spawns one game when two starts race inside the launch window", async () => {
+		const { supervisor, pids, launches, overlapped } = racedSupervisor(200, wrapperArgv);
+
+		await Promise.all([
+			supervisor.start(),
+			supervisor.start(),
+		]);
+
+		expect(launches(), "the second start entered the launch path beside the first").toBe(1);
+		expect(await waitFor(() => pids.length > 0, 10_000)).toBe(true);
+
+		await Bun.sleep(500);
+
+		expect(pids, "the race spawned a second game").toHaveLength(1);
+		expect(overlapped()).toBe(false);
+
+		await supervisor.stop();
+
+		expect(await waitGone(pids.at(0) ?? 0, 5000)).toBe(true);
+	}, 30_000);
+
+	test("never spawns beside the game a stop is taking down", async () => {
+		const { supervisor, pids, launches, overlapped } = racedSupervisor(0, wrapperArgv);
+
+		await supervisor.start();
+
+		expect(await waitFor(() => pids.length === 1, 10_000)).toBe(true);
+
+		const first = pids.at(0) ?? 0;
+
+		const stopping = supervisor.stop();
+		const starting = supervisor.start();
+
+		await stopping;
+		await starting;
+
+		expect(await waitFor(() => pids.length === 2, 10_000)).toBe(true);
+		expect(launches()).toBe(2);
+		expect(overlapped(), "the queued start spawned while the stopped game was still alive").toBe(false);
+		expect(await waitGone(first, 5000)).toBe(true);
+		expect(supervisor.running).toBe(true);
+
+		await supervisor.stop();
+
+		expect(await waitGone(pids.at(1) ?? 0, 5000)).toBe(true);
+	}, 30_000);
+
+	test("starts again after a launch that threw before the game was spawned", async () => {
+		let resolvable = false;
+
+		const { supervisor, pids } = racedSupervisor(0, () => {
+			if (!resolvable) {
+				throw new Error("the start command could not be resolved");
+			}
+
+			return wrapperArgv();
+		});
+
+		await expect(supervisor.start()).rejects.toThrow("the start command could not be resolved");
+		expect(supervisor.running).toBe(false);
+
+		resolvable = true;
+
+		await supervisor.start();
+
+		expect(supervisor.running, "the failed launch wedged the supervisor").toBe(true);
+		expect(await waitFor(() => pids.length === 1, 10_000)).toBe(true);
+
+		await supervisor.stop();
+
+		expect(await waitGone(pids.at(0) ?? 0, 5000)).toBe(true);
+	}, 30_000);
 });

package/src/runtime/bridgeSupervisor.ts

@@ -135,6 +135,21 @@ const drainPumps = async (pumps: readonly Promise<unknown>[]) => {
 	]);
 };
 
+const chain = () => {
+	let queue: Promise<unknown> = Promise.resolve();
+
+	return <Result>(run: () => Promise<Result>): Promise<Result> => {
+		const next = queue.then(run, run);
+
+		queue = next.then(
+			() => undefined,
+			() => undefined,
+		);
+
+		return next;
+	};
+};
+
 export const createSupervisor = (options: SupervisorOptions) => {
 	const tail: SupervisorLine[] = [];
 	const watchers = new Set<LineWatcher>();
@@ -151,7 +166,9 @@ export const createSupervisor = (options: SupervisorOptions) => {
 	let launchedAt = performance.now();
 	let stable = false;
 	let stableTimer: ReturnType<typeof setTimeout> | null = null;
-	let queue: Promise<unknown> = Promise.resolve();
+
+	const serialize = chain();
+	const transition = chain();
 
 	const markStable = () => {
 		if (stable) {
@@ -299,7 +316,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 
 			reported = true;
 
-			void handleExit(code, pumps).catch((error: unknown) => {
+			void handleExit(spawned, code, pumps).catch((error: unknown) => {
 				options.onLog.error("the game exit was not reported", {
 					error: errorText(error),
 				});
@@ -418,24 +435,24 @@ export const createSupervisor = (options: SupervisorOptions) => {
 	const restart = async () => {
 		await Bun.sleep(RESTART_DELAY_MS);
 
-		if (!shouldRun || breaker || child !== null) {
-			return;
-		}
+		await transition(async () => {
+			if (!shouldRun || breaker || child !== null) {
+				return;
+			}
 
-		try {
-			await launch();
-		} catch (error) {
-			runtime = BridgeRuntime.Crashed;
+			try {
+				await launch();
+			} catch (error) {
+				runtime = BridgeRuntime.Crashed;
 
-			options.onLog.error("game failed to restart", {
-				error: errorText(error),
-			});
-		}
+				options.onLog.error("game failed to restart", {
+					error: errorText(error),
+				});
+			}
+		});
 	};
 
-	async function handleExit(code: number, pumps: readonly Promise<unknown>[]) {
-		const finished = child;
-
+	const reap = (finished: SpawnedGame, code: number) => {
 		child = null;
 		exitCode = code;
 
@@ -445,11 +462,17 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			stableTimer = null;
 		}
 
-		if (finished) {
-			sweep(finished.pid, childGroup);
-		}
+		sweep(finished.pid, childGroup);
 
 		childGroup = null;
+	};
+
+	async function handleExit(finished: SpawnedGame, code: number, pumps: readonly Promise<unknown>[]) {
+		if (finished !== child) {
+			return;
+		}
+
+		reap(finished, code);
 
 		if (!shouldRun) {
 			outOfMemory = false;
@@ -535,17 +558,6 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		void restart();
 	}
 
-	const serialize = <Result>(run: () => Promise<Result>): Promise<Result> => {
-		const next = queue.then(run, run);
-
-		queue = next.then(
-			() => undefined,
-			() => undefined,
-		);
-
-		return next;
-	};
-
 	const writeLine = async (input: string) => {
 		if (!child) {
 			throw new Error("the game is not running");
@@ -578,73 +590,89 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		},
 
 		async start() {
-			shouldRun = true;
-			breaker = false;
-			outOfMemory = false;
-			restarts = 0;
-			restartStamps.length = 0;
-
-			if (child) {
-				return;
-			}
+			await transition(async () => {
+				shouldRun = true;
+				breaker = false;
+				outOfMemory = false;
+				restarts = 0;
+				restartStamps.length = 0;
+
+				if (child) {
+					return;
+				}
 
-			await launch();
+				await launch();
+			});
 		},
 
 		async stop() {
 			shouldRun = false;
 
-			if (!child) {
-				runtime = BridgeRuntime.Stopped;
+			await transition(async () => {
+				shouldRun = false;
 
-				options.onStopped?.();
+				if (!child) {
+					runtime = BridgeRuntime.Stopped;
 
-				return;
-			}
+					options.onStopped?.();
+
+					return;
+				}
 
-			const active = child;
-			const group = childGroup;
+				const active = child;
+				const group = childGroup;
 
-			runtime = BridgeRuntime.Stopping;
+				runtime = BridgeRuntime.Stopping;
 
-			if (options.gracefulStop) {
-				const graceful = options.gracefulStop().catch((error: unknown) => {
-					options.onLog.warn("graceful stop failed", {
-						error: errorText(error),
+				if (options.gracefulStop) {
+					const graceful = options.gracefulStop().catch((error: unknown) => {
+						options.onLog.warn("graceful stop failed", {
+							error: errorText(error),
+						});
 					});
-				});
 
-				await Promise.race([
-					graceful,
+					await Promise.race([
+						graceful,
+						active.exited,
+					]);
+				}
+
+				const settled = await Promise.race([
 					active.exited,
+					Bun.sleep(options.stopTimeoutSeconds * 1000).then(() => null),
 				]);
-			}
 
-			const settled = await Promise.race([
-				active.exited,
-				Bun.sleep(options.stopTimeoutSeconds * 1000).then(() => null),
-			]);
+				if (settled === null) {
+					terminate(active, group, "SIGTERM");
 
-			if (settled === null) {
-				terminate(active, group, "SIGTERM");
+					const afterTerm = await Promise.race([
+						active.exited,
+						Bun.sleep(KILL_GRACE_MS).then(() => null),
+					]);
 
-				const afterTerm = await Promise.race([
-					active.exited,
-					Bun.sleep(KILL_GRACE_MS).then(() => null),
-				]);
+					if (afterTerm === null) {
+						terminate(active, group, "SIGKILL");
 
-				if (afterTerm === null) {
-					terminate(active, group, "SIGKILL");
-
-					await active.exited;
+						await active.exited;
+					}
 				}
-			}
 
-			sweep(active.pid, group);
+				if (child === active) {
+					const code = exitCodeOf(active.exitCode, active.signalCode);
 
-			runtime = BridgeRuntime.Stopped;
+					reap(active, code);
+
+					outOfMemory = false;
+
+					options.onLog("game stopped", {
+						code,
+					});
+				}
 
-			options.onStopped?.();
+				runtime = BridgeRuntime.Stopped;
+
+				options.onStopped?.();
+			});
 		},
 
 		async command(input: string, commandOptions: BridgeCommandOptions = {}): Promise<BridgeReply> {

package/src/wire/panel.test.ts

@@ -15,7 +15,7 @@ import {
 	BridgeSetupStepKind,
 	BridgeUploadMode,
 } from "@serverkgg/bridge/protocol";
-import { bridgeManifestSchema } from "./panel";
+import { bridgeCellsSchema, bridgeManifestSchema } from "./panel";
 
 const text = (value: string) => ({
 	ar: value,
@@ -683,3 +683,37 @@ describe("the placement mirror", () => {
 		expect(bridgeManifestSchema.parse(source)).toEqual(source);
 	});
 });
+
+describe("the cell schema", () => {
+	test("accepts a scalar and a localized cell", () => {
+		expect(
+			bridgeCellsSchema.parse({
+				id: "u-1",
+				kills: 12,
+				banned: false,
+				status: {
+					ar: "متصل",
+					en: "Online",
+				},
+			}),
+		).toEqual({
+			id: "u-1",
+			kills: 12,
+			banned: false,
+			status: {
+				ar: "متصل",
+				en: "Online",
+			},
+		});
+	});
+
+	test("rejects a cell that carries only one language", () => {
+		expect(
+			bridgeCellsSchema.safeParse({
+				status: {
+					ar: "متصل",
+				},
+			}).success,
+		).toBe(false);
+	});
+});

package/src/wire/panel.ts

@@ -68,6 +68,17 @@ export const panelTextSchema = z.object({
 	en: z.string().min(1).max(PANEL_TEXT_LENGTH_LIMIT),
 });
 
+export const bridgeCellSchema = z.union([
+	bridgeValueSchema,
+	panelTextSchema,
+]);
+
+export type BridgeCellInput = z.infer<typeof bridgeCellSchema>;
+
+export const bridgeCellsSchema = z.record(zKey, bridgeCellSchema);
+
+export type BridgeCellsInput = z.infer<typeof bridgeCellsSchema>;
+
 export const bridgeOptionSchema = z.object({
 	value: z.string().min(1).max(128),
 	label: panelTextSchema,