@serverkgg/bridge 0.0.9 → 0.0.11

package/src/runtime/bridgeSignal.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import { leadsGroup, readProcessGroup, signalGroup } from "./bridgeSignal";
+
+const MISSING_PID = 2 ** 22 - 1;
+
+describe("readProcessGroup", () => {
+	test("reads the process group of this process", async () => {
+		const group = await readProcessGroup(process.pid);
+
+		expect(group).not.toBeNull();
+		expect(group).toBeGreaterThan(0);
+	});
+
+	test("puts a detached child in a group of its own and an attached one in ours", async () => {
+		const detached = Bun.spawn(
+			[
+				"sleep",
+				"5",
+			],
+			{
+				detached: true,
+				stdout: "ignore",
+				stderr: "ignore",
+			},
+		);
+
+		const attached = Bun.spawn(
+			[
+				"sleep",
+				"5",
+			],
+			{
+				stdout: "ignore",
+				stderr: "ignore",
+			},
+		);
+
+		try {
+			expect(await readProcessGroup(detached.pid)).toBe(detached.pid);
+			expect(await readProcessGroup(attached.pid)).toBe(await readProcessGroup(process.pid));
+		} finally {
+			detached.kill("SIGKILL");
+			attached.kill("SIGKILL");
+
+			await Promise.all([
+				detached.exited,
+				attached.exited,
+			]);
+		}
+	});
+
+	test("answers null for a pid that does not exist", async () => {
+		expect(await readProcessGroup(MISSING_PID)).toBeNull();
+	});
+});
+
+describe("leadsGroup", () => {
+	test("only a pid equal to its own group leads it", () => {
+		expect(leadsGroup(1234, 1234)).toBe(true);
+		expect(leadsGroup(1234, 1200)).toBe(false);
+		expect(leadsGroup(1234, null)).toBe(false);
+	});
+});
+
+describe("signalGroup", () => {
+	test("signals every process sharing the leader's group", async () => {
+		const leader = Bun.spawn(
+			[
+				"bash",
+				"-c",
+				"sleep 30 & echo $!; wait",
+			],
+			{
+				detached: true,
+				stdout: "pipe",
+				stderr: "ignore",
+			},
+		);
+
+		const first = await leader.stdout.getReader().read();
+		const child = Number(new TextDecoder().decode(first.value).trim());
+
+		expect(Number.isSafeInteger(child)).toBe(true);
+
+		expect(signalGroup(leader.pid, await readProcessGroup(leader.pid), "SIGKILL")).toBe(true);
+
+		await leader.exited;
+		await Bun.sleep(200);
+
+		expect(() => process.kill(child, 0)).toThrow();
+	}, 20_000);
+
+	test("refuses to signal a group the pid does not lead", async () => {
+		const attached = Bun.spawn(
+			[
+				"sleep",
+				"5",
+			],
+			{
+				stdout: "ignore",
+				stderr: "ignore",
+			},
+		);
+
+		try {
+			expect(signalGroup(attached.pid, await readProcessGroup(attached.pid), "SIGKILL")).toBe(false);
+			expect(attached.killed).toBe(false);
+		} finally {
+			attached.kill("SIGKILL");
+
+			await attached.exited;
+		}
+	});
+});

package/src/runtime/bridgeSignal.ts

@@ -0,0 +1,31 @@
+const STAT_PGID_INDEX = 2;
+
+export const readProcessGroup = async (pid: number) => {
+	try {
+		const stat = await Bun.file(`/proc/${pid}/stat`).text();
+		const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+		const group = Number(fields.at(STAT_PGID_INDEX));
+
+		return Number.isSafeInteger(group) && group > 0 ? group : null;
+	} catch {
+		return null;
+	}
+};
+
+export const leadsGroup = (pid: number, group: number | null) => {
+	return group !== null && group === pid;
+};
+
+export const signalGroup = (pid: number, group: number | null, signal: NodeJS.Signals) => {
+	if (!leadsGroup(pid, group)) {
+		return false;
+	}
+
+	try {
+		process.kill(-pid, signal);
+
+		return true;
+	} catch {
+		return false;
+	}
+};

package/src/runtime/bridgeSupervisor.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { BridgeRuntime } from "../core";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { readProcessGroup } from "./bridgeSignal";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const CHILD_PATTERN = /child=(?<pid>\d+)/;
+
+const WRAPPER = "sleep 300 & echo child=$!; wait";
+
+const STUBBORN_WRAPPER = 'trap "" TERM; sleep 300 & echo child=$!; wait';
+
+const silent: BridgeLeveledLogger = Object.assign(() => {}, {
+	warn: () => {},
+	error: () => {},
+});
+
+const alive = (pid: number) => {
+	try {
+		process.kill(pid, 0);
+
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+const waitGone = async (pid: number, timeoutMs: number) => {
+	for (let waited = 0; waited < timeoutMs; waited += 50) {
+		if (!alive(pid)) {
+			return true;
+		}
+
+		await Bun.sleep(50);
+	}
+
+	return !alive(pid);
+};
+
+const wrapperSupervisor = (script: string, stopTimeoutSeconds: number) => {
+	return createSupervisor({
+		cwd: tmpdir(),
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds,
+		resolveCommand: async () => {
+			return [
+				"bash",
+				"-c",
+				script,
+			];
+		},
+		onLog: silent,
+	});
+};
+
+const startWrapper = async (script: string, stopTimeoutSeconds: number) => {
+	const supervisor = wrapperSupervisor(script, stopTimeoutSeconds);
+	const started = supervisor.watch(CHILD_PATTERN, 10_000);
+
+	await supervisor.start();
+
+	const match = await started;
+	const pid = Number(match?.groups?.pid);
+
+	expect(match, "the wrapper never reported the pid it spawned").not.toBeNull();
+	expect(Number.isSafeInteger(pid)).toBe(true);
+
+	return {
+		supervisor,
+		pid,
+	};
+};
+
+describe("createSupervisor", () => {
+	test("runs the game outside the bridge's own process group", async () => {
+		const { supervisor, pid } = await startWrapper(WRAPPER, 1);
+
+		try {
+			const gameGroup = await readProcessGroup(pid);
+			const bridgeGroup = await readProcessGroup(process.pid);
+
+			expect(gameGroup, "the game must land in a group of its own or a group kill would hit the bridge").not.toBe(
+				bridgeGroup,
+			);
+		} finally {
+			await supervisor.stop();
+		}
+
+		expect(await waitGone(pid, 5000)).toBe(true);
+	}, 20_000);
+
+	test("takes the wrapper's child down with it when the stop times out", async () => {
+		const { supervisor, pid } = await startWrapper(WRAPPER, 1);
+
+		await supervisor.stop();
+
+		expect(supervisor.runtime).toBe(BridgeRuntime.Stopped);
+		expect(await waitGone(pid, 5000), "the game was orphaned when the wrapper was signalled").toBe(true);
+	}, 20_000);
+
+	test("kills the wrapper's child through the escalation when the wrapper ignores SIGTERM", async () => {
+		const { supervisor, pid } = await startWrapper(STUBBORN_WRAPPER, 1);
+
+		await supervisor.stop();
+
+		expect(supervisor.runtime).toBe(BridgeRuntime.Stopped);
+		expect(await waitGone(pid, 5000), "the game outlived the SIGKILL escalation").toBe(true);
+	}, 30_000);
+});

package/src/runtime/bridgeSupervisor.ts

@@ -1,8 +1,10 @@
 import type { BridgeCommandOptions, BridgeReply } from "../context";
 import { BridgeRuntime, BridgeStream } from "../core";
+import { stripAnsi } from "../utils";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { errorText } from "./bridgeLog";
 import { settleUid, unprivilegedArgv } from "./bridgePrivilege";
+import { readProcessGroup, signalGroup } from "./bridgeSignal";
 
 const TAIL_LIMIT = 500;
 
@@ -39,6 +41,18 @@ export interface SupervisorOptions {
 
 type LineWatcher = (entry: SupervisorLine) => void;
 
+type SpawnedGame = Bun.Subprocess<"pipe", "pipe", "pipe">;
+
+const terminate = (spawned: SpawnedGame, group: number | null, signal: NodeJS.Signals) => {
+	if (!signalGroup(spawned.pid, group, signal)) {
+		spawned.kill(signal);
+	}
+};
+
+const sweep = (pid: number, group: number | null) => {
+	signalGroup(pid, group, "SIGKILL");
+};
+
 const preferOomVictim = async (pid: number) => {
 	try {
 		await Bun.write(`/proc/${pid}/oom_score_adj`, `${GAME_OOM_SCORE_ADJ}\n`);
@@ -110,7 +124,8 @@ export const createSupervisor = (options: SupervisorOptions) => {
 	const watchers = new Set<LineWatcher>();
 	const restartStamps: number[] = [];
 
-	let child: Bun.Subprocess<"pipe", "pipe", "pipe"> | null = null;
+	let child: SpawnedGame | null = null;
+	let childGroup: number | null = null;
 	let runtime: BridgeRuntime = BridgeRuntime.Stopped;
 	let shouldRun = false;
 	let breaker = false;
@@ -183,7 +198,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			}, timeoutMs);
 
 			const watcher: LineWatcher = (entry) => {
-				const match = entry.line.match(pattern);
+				const match = stripAnsi(entry.line).match(pattern);
 
 				if (!match) {
 					return;
@@ -225,6 +240,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		const spawned = Bun.spawn(spawnArgv, {
 			...credentials,
 			cwd: options.cwd,
+			detached: true,
 			stderr: "pipe",
 			stdin: "pipe",
 			stdout: "pipe",
@@ -233,6 +249,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			},
 		});
 
+		const group = await readProcessGroup(spawned.pid);
 		const observed = await settleUid(spawned.pid, options.uid);
 
 		if (observed !== options.uid) {
@@ -247,10 +264,12 @@ export const createSupervisor = (options: SupervisorOptions) => {
 				);
 			}
 
-			spawned.kill("SIGKILL");
+			terminate(spawned, group, "SIGKILL");
 
 			await spawned.exited;
 
+			sweep(spawned.pid, group);
+
 			throw new Error(
 				`the game process runs as uid ${String(observed)}, expected ${options.uid} — refusing to run it as the bridge`,
 			);
@@ -259,6 +278,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		await preferOomVictim(spawned.pid);
 
 		child = spawned;
+		childGroup = group;
 		exitCode = null;
 
 		void pump(spawned.stdout, BridgeStream.Stdout);
@@ -266,6 +286,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 
 		options.onLog("game started", {
 			pid: spawned.pid,
+			group,
 			uid: options.uid,
 		});
 
@@ -306,9 +327,17 @@ export const createSupervisor = (options: SupervisorOptions) => {
 	};
 
 	function handleExit(code: number) {
+		const finished = child;
+
 		child = null;
 		exitCode = code;
 
+		if (finished) {
+			sweep(finished.pid, childGroup);
+		}
+
+		childGroup = null;
+
 		if (!shouldRun) {
 			outOfMemory = false;
 
@@ -419,6 +448,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			}
 
 			const active = child;
+			const group = childGroup;
 
 			runtime = BridgeRuntime.Stopping;
 
@@ -441,7 +471,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			]);
 
 			if (settled === null) {
-				active.kill("SIGTERM");
+				terminate(active, group, "SIGTERM");
 
 				const afterTerm = await Promise.race([
 					active.exited,
@@ -449,12 +479,14 @@ export const createSupervisor = (options: SupervisorOptions) => {
 				]);
 
 				if (afterTerm === null) {
-					active.kill("SIGKILL");
+					terminate(active, group, "SIGKILL");
 
 					await active.exited;
 				}
 			}
 
+			sweep(active.pid, group);
+
 			runtime = BridgeRuntime.Stopped;
 		},
 

package/src/runtime/serve.ts

@@ -1,5 +1,5 @@
 import { chmod, chown, mkdir, rm } from "node:fs/promises";
-import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError } from "../core";
+import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError, type LocalizedText } from "../core";
 import type { BridgeDriver } from "../modules";
 import {
 	BRIDGE_INSTALL_ERROR_LIMIT,
@@ -18,6 +18,8 @@ import { errorText, log } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
+import { setupSummaryOf } from "./bridgeSetup";
+import { createSetupHandlers } from "./bridgeSetupHandlers";
 import { readDesired, writeDesired } from "./bridgeState";
 import { createSupervisor } from "./bridgeSupervisor";
 
@@ -67,8 +69,12 @@ export const serve = async (driver: BridgeDriver) => {
 
 	let installError: string | null = null;
 
+	let installErrorText: LocalizedText | null = null;
+
 	let installHold: BridgeInstallHold | null = null;
 
+	const setup = createSetupHandlers(driver, log);
+
 	const supervisor = createSupervisor({
 		cwd: config.cwd,
 		uid: config.gameUid,
@@ -98,6 +104,9 @@ export const serve = async (driver: BridgeDriver) => {
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
+		onSetup(runtime) {
+			setup.onSetup(runtime);
+		},
 	});
 
 	const registry = createRegistry(driver, context, supervisor, ring);
@@ -113,7 +122,9 @@ export const serve = async (driver: BridgeDriver) => {
 			outOfMemory: supervisor.outOfMemory,
 			restarts: supervisor.restarts,
 			installError,
+			installErrorText,
 			installHold,
+			setup: setupSummaryOf(setup.current()),
 		};
 	};
 
@@ -307,6 +318,12 @@ export const serve = async (driver: BridgeDriver) => {
 
 			return await pending();
 		},
+		onSetupStatus() {
+			return setup.onSetupStatus();
+		},
+		async onSetupSubmit(step, action, args) {
+			return await setup.onSetupSubmit(context, step, action, args);
+		},
 	});
 
 	await chmod(socketPath(config), SOCKET_MODE);
@@ -358,6 +375,7 @@ export const serve = async (driver: BridgeDriver) => {
 		log("install complete");
 	} catch (error) {
 		installError = errorText(error).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
+		installErrorText = error instanceof BridgeUserError ? error.text : null;
 
 		supervisor.setRuntime(BridgeRuntime.Crashed);
 

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from "./glob";
+export * from "./stripAnsi";

package/src/utils/stripAnsi.ts

@@ -0,0 +1,12 @@
+const ANSI_PATTERN = new RegExp(
+	[
+		"\\u001B\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+		"\\u001B\\[[0-9;?]*[ -/]*[@-~]",
+		"\\u001B[@-Z\\\\-_]",
+	].join("|"),
+	"g",
+);
+
+export const stripAnsi = (line: string): string => {
+	return line.replace(ANSI_PATTERN, "");
+};

package/src/wire/panel.test.ts

@@ -1,13 +1,17 @@
 import { describe, expect, test } from "bun:test";
+import { GuideOpenTab } from "@serverkgg/bridge/guides";
 import {
 	BridgeAccess,
 	BridgeAction,
 	BridgeConfirm,
 	BridgeControl,
+	type BridgeField,
 	BridgeFormTarget,
 	BridgeKind,
 	BridgeLayout,
 	type BridgeManifest,
+	type BridgeSetupManifest,
+	BridgeSetupStepKind,
 	BridgeUploadMode,
 } from "@serverkgg/bridge/protocol";
 import { bridgeManifestSchema } from "./panel";
@@ -98,6 +102,7 @@ const manifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "broadcast",
@@ -159,6 +164,7 @@ const previewManifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "transition",
@@ -337,6 +343,7 @@ const detailManifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "modpackStatus",
@@ -412,6 +419,7 @@ const uploadManifest = (mode?: BridgeUploadMode): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "pending",
@@ -449,3 +457,150 @@ describe("the upload mirror", () => {
 		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
 	});
 });
+
+const fieldManifest = (field: BridgeField): BridgeManifest => ({
+	version: "1.0.0",
+	panel: {
+		tabs: [
+			{
+				id: "license",
+				title: text("Licence"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "license",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field,
+						],
+					},
+				],
+			},
+		],
+	},
+	terminal: null,
+	setup: null,
+	modules: [],
+	events: [],
+});
+
+describe("secret fields", () => {
+	test("carries a secret control with its pattern and hint through unchanged", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: BridgeControl.Secret,
+			label: text("Licence key"),
+			pattern: "^cfxk_\\w{1,60}_\\w{1,20}$",
+			patternHint: text("A licence key starts with cfxk_"),
+		});
+
+		expect(bridgeManifestSchema.parse(source)).toEqual(source);
+	});
+
+	test("refuses a control the platform does not know", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: "password" as BridgeControl,
+			label: text("Licence key"),
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+
+	test("refuses a pattern longer than the platform takes", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: BridgeControl.Secret,
+			label: text("Licence key"),
+			pattern: `^${"a".repeat(256)}$`,
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+});
+
+const setupManifest = (setup: BridgeSetupManifest | null): BridgeManifest => ({
+	version: "1.0.0",
+	panel: null,
+	terminal: null,
+	setup,
+	modules: [],
+	events: [],
+});
+
+describe("the setup mirror", () => {
+	test("carries every step kind through unchanged", () => {
+		const source = setupManifest({
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Driver,
+					id: "sign-in",
+					title: text("Sign in"),
+					help: text("Sign in with your account"),
+					requiresRunning: true,
+				},
+				{
+					kind: BridgeSetupStepKind.Form,
+					id: "name",
+					title: text("Name your server"),
+					required: false,
+					tab: "settings",
+					section: "server",
+					fields: [
+						"SERVER_NAME",
+					],
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite your friends"),
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+		});
+
+		expect(bridgeManifestSchema.parse(source).setup).toEqual(source.setup);
+	});
+
+	test("takes a manifest that declares no setup", () => {
+		expect(bridgeManifestSchema.parse(setupManifest(null)).setup).toBeNull();
+	});
+
+	test("defaults a manifest from an older bridge that carries no setup block to null", () => {
+		const older = setupManifest(null);
+
+		delete (older as Partial<BridgeManifest>).setup;
+
+		expect(bridgeManifestSchema.parse(older).setup).toBeNull();
+	});
+
+	test("refuses a step kind the platform does not know", () => {
+		const source = setupManifest({
+			steps: [
+				{
+					kind: "wizard" as BridgeSetupStepKind.Driver,
+					id: "sign-in",
+					title: text("Sign in"),
+				},
+			],
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+
+	test("refuses more steps than the platform takes", () => {
+		const source = setupManifest({
+			steps: Array.from({
+				length: 9,
+			}).map((_entry, index) => ({
+				kind: BridgeSetupStepKind.Driver as const,
+				id: `step-${index}`,
+				title: text(`Step ${index}`),
+			})),
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+});