@serverkgg/bridge 0.0.19 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.19",
+	"version": "0.0.21",
 	"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/modules/bridgeModule.ts

@@ -23,6 +23,7 @@ export interface BridgeInstallModule {
 export interface BridgeLifecycleModule {
 	kind: BridgeKind.Lifecycle;
 	ready?: RegExp;
+	failed?: RegExp;
 	stopTimeoutSeconds?: number;
 	command(context: BridgeContext): Promise<string[]>;
 	stop?(context: BridgeContext): Promise<void>;

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+)/;
 
@@ -32,6 +32,14 @@ const TIGHT_LAST_LINE_CRASH = `sleep 0.2; echo "${LAST_LINE}"; exit 3`;
 
 const INSTANT_EXIT = "false";
 
+const FAILED_BOOT_LINE = "[main/FATAL] [minecraft/Main]: Failed to start the minecraft server";
+
+const FAILED_BOOT = /Failed to start the minecraft server/;
+
+const FAILED_BOOT_WRAPPER = `sleep 300 & echo child=$!; echo "${FAILED_BOOT_LINE}"; wait`;
+
+const LATE_FAILED_LINE_WRAPPER = `echo ready; sleep 0.6; echo "${FAILED_BOOT_LINE}"; sleep 300`;
+
 const silent: BridgeLeveledLogger = Object.assign(() => {}, {
 	warn: () => {},
 	error: () => {},
@@ -169,6 +177,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 +454,158 @@ 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);
+
+	test("stops a game that reports a failed boot instead of waiting for a ready line that never comes", async () => {
+		const records: BridgeCrashRecord[] = [];
+		const pids: number[] = [];
+
+		const supervisor = createSupervisor({
+			cwd: tmpdir(),
+			uid: process.getuid?.() ?? 0,
+			gid: process.getgid?.() ?? 0,
+			stopTimeoutSeconds: 1,
+			ready: READY,
+			failed: FAILED_BOOT,
+			onLog: silent,
+			resolveCommand: async () => {
+				return [
+					"bash",
+					"-c",
+					FAILED_BOOT_WRAPPER,
+				];
+			},
+			onExit(record) {
+				records.push(record);
+			},
+		});
+
+		supervisor.subscribe((entry) => {
+			const match = CHILD_PATTERN.exec(entry.line);
+
+			if (match?.groups?.pid) {
+				pids.push(Number(match.groups.pid));
+			}
+		});
+
+		await supervisor.start();
+
+		expect(await waitFor(() => records.length > 0, 10_000)).toBe(true);
+
+		const record = records.at(0);
+
+		expect(record?.phase).toBe(BridgeCrashPhase.Booting);
+		expect(record?.outOfMemory).toBe(false);
+		expect(record?.restarting).toBe(false);
+		expect(record?.lastLine).toBe(FAILED_BOOT_LINE);
+		expect(supervisor.running).toBe(false);
+		expect(supervisor.runtime).toBe(BridgeRuntime.Crashed);
+		expect(await waitGone(pids.at(0) ?? 0, 5000)).toBe(true);
+	}, 30_000);
+
+	test("ignores the failed pattern once the game has been running long enough to count as stable", async () => {
+		const records: BridgeCrashRecord[] = [];
+
+		const supervisor = createSupervisor({
+			cwd: tmpdir(),
+			uid: process.getuid?.() ?? 0,
+			gid: process.getgid?.() ?? 0,
+			stopTimeoutSeconds: 1,
+			ready: READY,
+			failed: FAILED_BOOT,
+			stableAfterMs: 200,
+			onLog: silent,
+			resolveCommand: async () => {
+				return [
+					"bash",
+					"-c",
+					LATE_FAILED_LINE_WRAPPER,
+				];
+			},
+			onExit(record) {
+				records.push(record);
+			},
+		});
+
+		await supervisor.start();
+
+		await Bun.sleep(1500);
+
+		expect(records).toHaveLength(0);
+		expect(supervisor.running).toBe(true);
+
+		await supervisor.stop();
+	}, 30_000);
 });

package/src/runtime/bridgeSupervisor.ts

@@ -36,6 +36,7 @@ export interface SupervisorOptions {
 	gid: number;
 	stopTimeoutSeconds: number;
 	ready?: RegExp;
+	failed?: RegExp;
 	resolveCommand: () => Promise<string[]>;
 	gracefulStop?: () => Promise<void>;
 	stableAfterMs?: number;
@@ -135,6 +136,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 +167,10 @@ 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();
+	let bootFailure: string | null = null;
+
+	const serialize = chain();
+	const transition = chain();
 
 	const markStable = () => {
 		if (stable) {
@@ -281,6 +300,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 
 		launchedAt = performance.now();
 		stable = false;
+		bootFailure = null;
 
 		if (stableTimer) {
 			clearTimeout(stableTimer);
@@ -299,7 +319,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),
 				});
@@ -379,6 +399,31 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			return;
 		}
 
+		if (options.failed) {
+			void watch(options.failed, options.stopTimeoutSeconds * 1000 * 10).then((match) => {
+				if (!match || launchStamp !== launchedAt || child === null || stable) {
+					return;
+				}
+
+				bootFailure = (match.input ?? match[0]).trim().slice(0, BRIDGE_CRASH_LINE_LIMIT);
+
+				options.onLog.error("the game reported a failed boot, stopping it", {
+					line: bootFailure,
+				});
+
+				const failing = child;
+				const failingGroup = childGroup;
+
+				terminate(failing, failingGroup, "SIGTERM");
+
+				void Bun.sleep(KILL_GRACE_MS).then(() => {
+					if (child === failing) {
+						terminate(failing, failingGroup, "SIGKILL");
+					}
+				});
+			});
+		}
+
 		if (!options.ready) {
 			runtime = BridgeRuntime.Running;
 
@@ -418,24 +463,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 +490,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;
@@ -466,7 +517,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		const uptimeMs = performance.now() - launchedAt;
 		const phase = stable ? BridgeCrashPhase.Running : BridgeCrashPhase.Booting;
 
-		outOfMemory = code === SIGKILL_EXIT_CODE;
+		outOfMemory = code === SIGKILL_EXIT_CODE && bootFailure === null;
 
 		if (outOfMemory) {
 			options.onLog.error("the game was killed for running out of memory", {
@@ -489,7 +540,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 
 			options.onExit?.({
 				...settled,
-				lastLine: lastLine(),
+				lastLine: bootFailure ?? lastLine(),
 			});
 		};
 
@@ -535,17 +586,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 +618,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?.();
 
-			const active = child;
-			const group = childGroup;
+					return;
+				}
+
+				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,
+					});
+				}
+
+				runtime = BridgeRuntime.Stopped;
 
-			options.onStopped?.();
+				options.onStopped?.();
+			});
 		},
 
 		async command(input: string, commandOptions: BridgeCommandOptions = {}): Promise<BridgeReply> {

package/src/runtime/serve.ts

@@ -83,6 +83,7 @@ export const serve = async (driver: BridgeDriver) => {
 		gid: config.gameGid,
 		stopTimeoutSeconds: driver.lifecycle.stopTimeoutSeconds ?? DEFAULT_STOP_TIMEOUT_SECONDS,
 		ready: driver.lifecycle.ready,
+		failed: driver.lifecycle.failed,
 		onLog: log,
 		async resolveCommand() {
 			return await driver.lifecycle.command(context);