@serverkgg/bridge 0.0.1

package/src/runtime/bridgeSupervisor.ts

@@ -0,0 +1,498 @@
+import type { BridgeCommandOptions, BridgeReply } from "../context";
+import { BridgeRuntime, BridgeStream } from "../core";
+import type { BridgeLogger } from "./bridgeLog";
+import { errorText } from "./bridgeLog";
+import { settleUid, unprivilegedArgv } from "./bridgePrivilege";
+
+const TAIL_LIMIT = 500;
+
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+
+const KILL_GRACE_MS = 5000;
+
+const RESTART_DELAY_MS = 2000;
+
+const RESTART_WINDOW_MS = 300_000;
+
+const RESTART_LIMIT = 5;
+
+const GAME_OOM_SCORE_ADJ = 500;
+
+export interface SupervisorLine {
+	stream: BridgeStream;
+	line: string;
+}
+
+export interface SupervisorOptions {
+	cwd: string;
+	uid: number;
+	gid: number;
+	stopTimeoutSeconds: number;
+	ready?: RegExp;
+	resolveCommand: () => Promise<string[]>;
+	gracefulStop?: () => Promise<void>;
+	onReady?: () => void;
+	onLog: BridgeLogger;
+}
+
+type LineWatcher = (entry: SupervisorLine) => void;
+
+const preferOomVictim = async (pid: number) => {
+	try {
+		await Bun.write(`/proc/${pid}/oom_score_adj`, `${GAME_OOM_SCORE_ADJ}\n`);
+	} catch {
+		return;
+	}
+};
+
+const SIGNAL_NUMBERS: Record<string, number> = {
+	SIGHUP: 1,
+	SIGINT: 2,
+	SIGQUIT: 3,
+	SIGABRT: 6,
+	SIGKILL: 9,
+	SIGSEGV: 11,
+	SIGTERM: 15,
+};
+
+const EARLY_OUTPUT_LIMIT = 2000;
+
+const earlyOutput = async (spawned: { stdout: unknown; stderr: unknown }) => {
+	const read = async (stream: unknown) => {
+		if (!(stream instanceof ReadableStream)) {
+			return "";
+		}
+
+		return await new Response(stream).text().catch(() => "");
+	};
+
+	const [stdout, stderr] = await Promise.all([
+		read(spawned.stdout),
+		read(spawned.stderr),
+	]);
+
+	const text = `${stdout}\n${stderr}`.trim();
+
+	return text.length === 0 ? "" : ` — ${text.slice(-EARLY_OUTPUT_LIMIT)}`;
+};
+
+const exitCodeOf = (code: number | null, signal: number | string | null) => {
+	if (code !== null) {
+		return code;
+	}
+
+	if (typeof signal === "number") {
+		return 128 + signal;
+	}
+
+	if (typeof signal === "string") {
+		return 128 + (SIGNAL_NUMBERS[signal] ?? 0);
+	}
+
+	return 0;
+};
+
+const splitLines = (buffer: string, chunk: string) => {
+	const merged = buffer + chunk;
+	const parts = merged.split("\n");
+	const rest = parts.pop() ?? "";
+
+	return {
+		lines: parts.map((line) => line.replace(/\r$/, "")),
+		rest,
+	};
+};
+
+export const createSupervisor = (options: SupervisorOptions) => {
+	const tail: SupervisorLine[] = [];
+	const watchers = new Set<LineWatcher>();
+	const restartStamps: number[] = [];
+
+	let child: Bun.Subprocess<"pipe", "pipe", "pipe"> | null = null;
+	let runtime: BridgeRuntime = BridgeRuntime.Stopped;
+	let shouldRun = false;
+	let breaker = false;
+	let exitCode: number | null = null;
+	let restarts = 0;
+	let queue: Promise<unknown> = Promise.resolve();
+
+	const emit = (entry: SupervisorLine) => {
+		if (entry.stream === BridgeStream.Stderr) {
+			process.stderr.write(`${entry.line}\n`);
+		} else {
+			process.stdout.write(`${entry.line}\n`);
+		}
+
+		tail.push(entry);
+
+		while (tail.length > TAIL_LIMIT) {
+			tail.shift();
+		}
+
+		for (const watcher of watchers) {
+			watcher(entry);
+		}
+	};
+
+	const pump = async (stream: ReadableStream<Uint8Array>, kind: BridgeStream) => {
+		const decoder = new TextDecoder();
+		const reader = stream.getReader();
+
+		let buffer = "";
+
+		while (true) {
+			const { done, value } = await reader.read();
+
+			if (done) {
+				break;
+			}
+
+			const split = splitLines(
+				buffer,
+				decoder.decode(value, {
+					stream: true,
+				}),
+			);
+
+			buffer = split.rest;
+
+			for (const line of split.lines) {
+				emit({
+					stream: kind,
+					line,
+				});
+			}
+		}
+
+		if (buffer.length > 0) {
+			emit({
+				stream: kind,
+				line: buffer,
+			});
+		}
+	};
+
+	const watch = (pattern: RegExp, timeoutMs: number) => {
+		return new Promise<RegExpMatchArray | null>((resolve) => {
+			const timer = setTimeout(() => {
+				watchers.delete(watcher);
+				resolve(null);
+			}, timeoutMs);
+
+			const watcher: LineWatcher = (entry) => {
+				const match = entry.line.match(pattern);
+
+				if (!match) {
+					return;
+				}
+
+				clearTimeout(timer);
+				watchers.delete(watcher);
+				resolve(match);
+			};
+
+			watchers.add(watcher);
+		});
+	};
+
+	const tripped = () => {
+		const cutoff = performance.now() - RESTART_WINDOW_MS;
+
+		while (restartStamps.length > 0 && (restartStamps[0] ?? 0) < cutoff) {
+			restartStamps.shift();
+		}
+
+		return restartStamps.length >= RESTART_LIMIT;
+	};
+
+	const launch = async () => {
+		const command = await options.resolveCommand();
+		const [executable, ...rest] = command;
+
+		if (!executable) {
+			throw new Error("the game start command is empty");
+		}
+
+		const argv = [
+			executable,
+			...rest,
+		];
+
+		const { argv: spawnArgv } = await unprivilegedArgv(argv, options.uid, options.gid);
+		const spawned = Bun.spawn(spawnArgv, {
+			cwd: options.cwd,
+			stderr: "pipe",
+			stdin: "pipe",
+			stdout: "pipe",
+			onExit(_subprocess, code, signal) {
+				handleExit(exitCodeOf(code, signal));
+			},
+		});
+
+		const observed = await settleUid(spawned.pid, options.uid);
+
+		if (observed !== options.uid) {
+			const finished = await Promise.race([
+				spawned.exited.then(() => true),
+				Bun.sleep(KILL_GRACE_MS).then(() => false),
+			]);
+
+			if (observed === null && finished) {
+				throw new Error(
+					`the game exited immediately with code ${exitCodeOf(spawned.exitCode, spawned.signalCode)}${await earlyOutput(spawned)}`,
+				);
+			}
+
+			spawned.kill("SIGKILL");
+
+			await spawned.exited;
+
+			throw new Error(
+				`the game process runs as uid ${String(observed)}, expected ${options.uid} — refusing to run it as the bridge`,
+			);
+		}
+
+		await preferOomVictim(spawned.pid);
+
+		child = spawned;
+		exitCode = null;
+
+		void pump(spawned.stdout, BridgeStream.Stdout);
+		void pump(spawned.stderr, BridgeStream.Stderr);
+
+		options.onLog("game started", {
+			pid: spawned.pid,
+			uid: options.uid,
+		});
+
+		if (!options.ready) {
+			runtime = BridgeRuntime.Running;
+
+			return;
+		}
+
+		runtime = BridgeRuntime.Starting;
+
+		void watch(options.ready, options.stopTimeoutSeconds * 1000 * 10).then((match) => {
+			if (match && runtime === BridgeRuntime.Starting) {
+				runtime = BridgeRuntime.Running;
+
+				options.onLog("game ready");
+				options.onReady?.();
+			}
+		});
+	};
+
+	const restart = async () => {
+		await Bun.sleep(RESTART_DELAY_MS);
+
+		if (!shouldRun || breaker || child !== null) {
+			return;
+		}
+
+		try {
+			await launch();
+		} catch (error) {
+			runtime = BridgeRuntime.Crashed;
+
+			options.onLog("game failed to restart", {
+				error: errorText(error),
+			});
+		}
+	};
+
+	function handleExit(code: number) {
+		child = null;
+		exitCode = code;
+
+		if (!shouldRun) {
+			runtime = BridgeRuntime.Stopped;
+
+			options.onLog("game stopped", {
+				code,
+			});
+
+			return;
+		}
+
+		restarts += 1;
+		restartStamps.push(performance.now());
+
+		if (tripped()) {
+			breaker = true;
+			runtime = BridgeRuntime.Crashed;
+
+			options.onLog("game crash loop detected, not restarting", {
+				code,
+				restarts,
+			});
+
+			return;
+		}
+
+		runtime = BridgeRuntime.Starting;
+
+		options.onLog("game exited, restarting", {
+			code,
+			restarts,
+		});
+
+		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");
+		}
+
+		child.stdin.write(`${input}\n`);
+
+		await child.stdin.flush();
+	};
+
+	return {
+		get runtime() {
+			return runtime;
+		},
+
+		get running() {
+			return child !== null;
+		},
+
+		get exitCode() {
+			return exitCode;
+		},
+
+		get restarts() {
+			return restarts;
+		},
+
+		async start() {
+			shouldRun = true;
+			breaker = false;
+			restartStamps.length = 0;
+
+			if (child) {
+				return;
+			}
+
+			await launch();
+		},
+
+		async stop() {
+			shouldRun = false;
+
+			if (!child) {
+				runtime = BridgeRuntime.Stopped;
+
+				return;
+			}
+
+			const active = child;
+
+			runtime = BridgeRuntime.Stopping;
+
+			if (options.gracefulStop) {
+				const graceful = options.gracefulStop().catch((error: unknown) => {
+					options.onLog("graceful stop failed", {
+						error: errorText(error),
+					});
+				});
+
+				await Promise.race([
+					graceful,
+					active.exited,
+				]);
+			}
+
+			const settled = await Promise.race([
+				active.exited,
+				Bun.sleep(options.stopTimeoutSeconds * 1000).then(() => null),
+			]);
+
+			if (settled === null) {
+				active.kill("SIGTERM");
+
+				const afterTerm = await Promise.race([
+					active.exited,
+					Bun.sleep(KILL_GRACE_MS).then(() => null),
+				]);
+
+				if (afterTerm === null) {
+					active.kill("SIGKILL");
+
+					await active.exited;
+				}
+			}
+
+			runtime = BridgeRuntime.Stopped;
+		},
+
+		async command(input: string, commandOptions: BridgeCommandOptions = {}): Promise<BridgeReply> {
+			return await serialize(async () => {
+				const pattern = commandOptions.expect;
+
+				if (!pattern) {
+					await writeLine(input);
+
+					return {
+						sent: input,
+						line: null,
+						groups: {},
+					};
+				}
+
+				const pending = watch(pattern, commandOptions.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+
+				await writeLine(input);
+
+				const match = await pending;
+
+				if (!match) {
+					throw new Error(`"${input}" produced no reply matching ${String(pattern)}`);
+				}
+
+				return {
+					sent: input,
+					line: match[0],
+					groups: {
+						...match.groups,
+					},
+				};
+			});
+		},
+
+		tail(lines: number) {
+			return tail.slice(-lines).map((entry) => entry.line);
+		},
+
+		watch(pattern: RegExp, timeoutMs: number) {
+			return watch(pattern, timeoutMs);
+		},
+
+		subscribe(watcher: LineWatcher) {
+			watchers.add(watcher);
+
+			return () => {
+				watchers.delete(watcher);
+			};
+		},
+
+		setRuntime(next: BridgeRuntime) {
+			runtime = next;
+		},
+	};
+};
+
+export type BridgeSupervisor = ReturnType<typeof createSupervisor>;

package/src/runtime/bridgeZip.ts

@@ -0,0 +1,122 @@
+import { inflateRawSync } from "node:zlib";
+
+const EOCD_SIGNATURE = 0x06_05_4b_50;
+
+const CENTRAL_SIGNATURE = 0x02_01_4b_50;
+
+const LOCAL_SIGNATURE = 0x04_03_4b_50;
+
+const EOCD_MIN_LENGTH = 22;
+
+const EOCD_SEARCH_LIMIT = 65_557;
+
+const LOCAL_HEADER_LENGTH = 30;
+
+const STORED = 0;
+
+const DEFLATED = 8;
+
+const ENCRYPTED_FLAG = 0x1;
+
+const MAX_ENTRIES = 2048;
+
+const MAX_ENTRY_BYTES = 128 * 1024 * 1024;
+
+export interface ZipEntry {
+	name: string;
+	data: Uint8Array;
+}
+
+const findEndOfCentralDirectory = (buffer: Buffer) => {
+	const start = Math.max(0, buffer.length - EOCD_SEARCH_LIMIT);
+
+	for (let offset = buffer.length - EOCD_MIN_LENGTH; offset >= start; offset--) {
+		if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) {
+			return offset;
+		}
+	}
+
+	return -1;
+};
+
+export const readZip = (buffer: Buffer): ZipEntry[] => {
+	const eocd = findEndOfCentralDirectory(buffer);
+
+	if (eocd === -1) {
+		throw new Error("archive has no zip central directory");
+	}
+
+	const total = buffer.readUInt16LE(eocd + 10);
+	const directoryOffset = buffer.readUInt32LE(eocd + 16);
+
+	if (total > MAX_ENTRIES) {
+		throw new Error(`archive has too many entries (${total})`);
+	}
+
+	const entries: ZipEntry[] = [];
+
+	let cursor = directoryOffset;
+
+	for (let index = 0; index < total; index++) {
+		if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+			throw new Error("archive central directory is corrupt");
+		}
+
+		const flags = buffer.readUInt16LE(cursor + 8);
+		const method = buffer.readUInt16LE(cursor + 10);
+		const compressedSize = buffer.readUInt32LE(cursor + 20);
+		const uncompressedSize = buffer.readUInt32LE(cursor + 24);
+		const nameLength = buffer.readUInt16LE(cursor + 28);
+		const extraLength = buffer.readUInt16LE(cursor + 30);
+		const commentLength = buffer.readUInt16LE(cursor + 32);
+		const localOffset = buffer.readUInt32LE(cursor + 42);
+		const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
+
+		cursor += 46 + nameLength + extraLength + commentLength;
+
+		if (name.endsWith("/") || (flags & ENCRYPTED_FLAG) !== 0) {
+			continue;
+		}
+
+		if (uncompressedSize > MAX_ENTRY_BYTES) {
+			throw new Error(`archive entry "${name}" is too large`);
+		}
+
+		if (localOffset + LOCAL_HEADER_LENGTH > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL_SIGNATURE) {
+			throw new Error(`archive entry "${name}" has a corrupt local header`);
+		}
+
+		const localNameLength = buffer.readUInt16LE(localOffset + 26);
+		const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+		const dataOffset = localOffset + LOCAL_HEADER_LENGTH + localNameLength + localExtraLength;
+		const compressed = buffer.subarray(dataOffset, dataOffset + compressedSize);
+
+		if (method === STORED) {
+			entries.push({
+				name,
+				data: compressed,
+			});
+
+			continue;
+		}
+
+		if (method !== DEFLATED) {
+			throw new Error(`archive entry "${name}" uses unsupported compression ${method}`);
+		}
+
+		const data = inflateRawSync(compressed, {
+			maxOutputLength: MAX_ENTRY_BYTES,
+		});
+
+		if (data.length !== uncompressedSize) {
+			throw new Error(`archive entry "${name}" did not inflate to its declared size`);
+		}
+
+		entries.push({
+			name,
+			data,
+		});
+	}
+
+	return entries;
+};

package/src/runtime/index.ts

@@ -0,0 +1,18 @@
+export * from "./bridgeCodec";
+export * from "./bridgeConfigReader";
+export * from "./bridgeContext";
+export * from "./bridgeDriver";
+export * from "./bridgeEvents";
+export * from "./bridgeExec";
+export * from "./bridgeFiles";
+export * from "./bridgeLog";
+export * from "./bridgeNet";
+export * from "./bridgePath";
+export * from "./bridgePrivilege";
+export * from "./bridgeProbe";
+export * from "./bridgeRegistry";
+export * from "./bridgeServer";
+export * from "./bridgeState";
+export * from "./bridgeSupervisor";
+export * from "./bridgeZip";
+export * from "./serve";