@serverkgg/bridge 0.0.8 → 0.0.9

package/src/runtime/bridgeServer.ts

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeFailureError, BridgeSecretError, type BridgeValues } from "../core";
+import { BridgeFailureError, BridgeSecretError, BridgeUserError, type BridgeValues } from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
 	type BridgeAnnounceResult,
@@ -8,6 +8,7 @@ import {
 	type BridgeEventsResult,
 	type BridgeManifest,
 	BridgeMethod,
+	type BridgePendingResult,
 	type BridgeQuiesceResult,
 	type BridgeResponse,
 	type BridgeSampleResult,
@@ -30,6 +31,8 @@ export interface ServerOptions {
 	onRelease: () => Promise<void>;
 	onDescribe: () => Promise<BridgeDescribeResult>;
 	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
+	onPendingList: () => Promise<BridgePendingResult>;
+	onPendingAdd: (input: string) => Promise<BridgePendingResult>;
 	onLog: BridgeLogger;
 }
 
@@ -47,7 +50,7 @@ interface IncomingFrame {
 	message?: unknown;
 }
 
-const asMessage = (value: unknown): string | null => {
+const asText = (value: unknown): string | null => {
 	return typeof value === "string" && value.length > 0 ? value : null;
 };
 
@@ -136,7 +139,7 @@ export const createServer = (options: ServerOptions) => {
 			}
 
 			case BridgeMethod.Announce: {
-				const message = asMessage(request.message);
+				const message = asText(request.message);
 
 				if (!message) {
 					throw new Error("announce needs a message");
@@ -145,6 +148,20 @@ export const createServer = (options: ServerOptions) => {
 				return await options.onAnnounce(message);
 			}
 
+			case BridgeMethod.PendingList: {
+				return await options.onPendingList();
+			}
+
+			case BridgeMethod.PendingAdd: {
+				const input = asText(request.input);
+
+				if (!input) {
+					throw new Error("pendingAdd needs an input path");
+				}
+
+				return await options.onPendingAdd(input);
+			}
+
 			default: {
 				throw new Error(`unknown method "${method}"`);
 			}
@@ -249,6 +266,11 @@ export const createServer = (options: ServerOptions) => {
 												failure: error.code,
 											}
 										: {}),
+									...(error instanceof BridgeUserError
+										? {
+												text: error.text,
+											}
+										: {}),
 								}),
 							);
 						});

package/src/runtime/bridgeSupervisor.ts

@@ -18,6 +18,8 @@ const RESTART_LIMIT = 5;
 
 const GAME_OOM_SCORE_ADJ = 500;
 
+const SIGKILL_EXIT_CODE = 128 + 9;
+
 export interface SupervisorLine {
 	stream: BridgeStream;
 	line: string;
@@ -113,6 +115,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 	let shouldRun = false;
 	let breaker = false;
 	let exitCode: number | null = null;
+	let outOfMemory = false;
 	let restarts = 0;
 	let queue: Promise<unknown> = Promise.resolve();
 
@@ -307,6 +310,8 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		exitCode = code;
 
 		if (!shouldRun) {
+			outOfMemory = false;
+
 			runtime = BridgeRuntime.Stopped;
 
 			options.onLog("game stopped", {
@@ -316,6 +321,14 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			return;
 		}
 
+		outOfMemory = code === SIGKILL_EXIT_CODE;
+
+		if (outOfMemory) {
+			options.onLog.error("the game was killed for running out of memory", {
+				code,
+			});
+		}
+
 		restarts += 1;
 		restartStamps.push(performance.now());
 
@@ -375,6 +388,10 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			return exitCode;
 		},
 
+		get outOfMemory() {
+			return outOfMemory;
+		},
+
 		get restarts() {
 			return restarts;
 		},
@@ -382,6 +399,7 @@ export const createSupervisor = (options: SupervisorOptions) => {
 		async start() {
 			shouldRun = true;
 			breaker = false;
+			outOfMemory = false;
 			restartStamps.length = 0;
 
 			if (child) {

package/src/runtime/bridgeZip.ts

@@ -6,12 +6,26 @@ const CENTRAL_SIGNATURE = 0x02_01_4b_50;
 
 const LOCAL_SIGNATURE = 0x04_03_4b_50;
 
+const ZIP64_LOCATOR_SIGNATURE = 0x07_06_4b_50;
+
+const ZIP64_EOCD_SIGNATURE = 0x06_06_4b_50;
+
 const EOCD_MIN_LENGTH = 22;
 
 const EOCD_SEARCH_LIMIT = 65_557;
 
+const ZIP64_LOCATOR_LENGTH = 20;
+
+const ZIP64_EOCD_MIN_LENGTH = 56;
+
+const ZIP64_EXTRA_ID = 0x00_01;
+
+const CENTRAL_HEADER_LENGTH = 46;
+
 const LOCAL_HEADER_LENGTH = 30;
 
+const SIZE_SENTINEL = 0xff_ff_ff_ff;
+
 const STORED = 0;
 
 const DEFLATED = 8;
@@ -20,7 +34,7 @@ const ENCRYPTED_FLAG = 0x1;
 
 export const ZIP_ENTRY_LIMIT = 2048;
 
-export const ZIP_TREE_ENTRY_LIMIT = 8192;
+export const ZIP_TREE_ENTRY_LIMIT = 16_384;
 
 const MAX_ENTRY_BYTES = 128 * 1024 * 1024;
 
@@ -30,14 +44,34 @@ const UNIX_MODE_SYMLINK = 0xa0_00;
 
 export interface ZipEntry {
 	name: string;
-	data: Uint8Array;
 	symlink: boolean;
+	sizeBytes: number;
+	compressedSize: number;
+	method: number;
+	localOffset: number;
 }
 
-const findEndOfCentralDirectory = (buffer: Buffer) => {
-	const start = Math.max(0, buffer.length - EOCD_SEARCH_LIMIT);
+export interface ZipArchive {
+	entries: ZipEntry[];
+	read(entry: ZipEntry): Promise<Uint8Array>;
+}
+
+const readRange = async (path: string, start: number, end: number) => {
+	return Buffer.from(await Bun.file(path).slice(start, end).arrayBuffer());
+};
+
+const readOffset = (buffer: Buffer, offset: number) => {
+	const value = buffer.readBigUInt64LE(offset);
+
+	if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+		throw new Error("archive declares an offset this runtime cannot address");
+	}
+
+	return Number(value);
+};
 
-	for (let offset = buffer.length - EOCD_MIN_LENGTH; offset >= start; offset--) {
+const findEndOfCentralDirectory = (buffer: Buffer) => {
+	for (let offset = buffer.length - EOCD_MIN_LENGTH; offset >= 0; offset--) {
 		if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) {
 			return offset;
 		}
@@ -46,88 +80,175 @@ const findEndOfCentralDirectory = (buffer: Buffer) => {
 	return -1;
 };
 
-export const readZip = (buffer: Buffer, maxEntries: number = ZIP_ENTRY_LIMIT): ZipEntry[] => {
-	const eocd = findEndOfCentralDirectory(buffer);
+interface CentralDirectory {
+	total: number;
+	offset: number;
+	sizeBytes: number;
+}
 
-	if (eocd === -1) {
-		throw new Error("archive has no zip central directory");
+const readZip64Directory = async (path: string, tail: Buffer, eocd: number): Promise<CentralDirectory | null> => {
+	const locator = eocd - ZIP64_LOCATOR_LENGTH;
+
+	if (locator < 0 || tail.readUInt32LE(locator) !== ZIP64_LOCATOR_SIGNATURE) {
+		return null;
 	}
 
-	const total = buffer.readUInt16LE(eocd + 10);
-	const directoryOffset = buffer.readUInt32LE(eocd + 16);
+	const record = readOffset(tail, locator + 8);
+	const buffer = await readRange(path, record, record + ZIP64_EOCD_MIN_LENGTH);
 
-	if (total > maxEntries) {
-		throw new Error(`archive has too many entries (${total})`);
+	if (buffer.length < ZIP64_EOCD_MIN_LENGTH || buffer.readUInt32LE(0) !== ZIP64_EOCD_SIGNATURE) {
+		throw new Error("archive has a corrupt zip64 central directory record");
 	}
 
-	const entries: ZipEntry[] = [];
+	return {
+		total: readOffset(buffer, 32),
+		sizeBytes: readOffset(buffer, 40),
+		offset: readOffset(buffer, 48),
+	};
+};
 
-	let cursor = directoryOffset;
+interface Zip64Extended {
+	sizeBytes: number | null;
+	compressedSize: number | null;
+	localOffset: number | null;
+}
 
-	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 readZip64Extra = (extra: Buffer, sizeBytes: number, compressedSize: number, localOffset: number) => {
+	const extended: Zip64Extended = {
+		sizeBytes: null,
+		compressedSize: null,
+		localOffset: null,
+	};
 
-		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 externalAttributes = buffer.readUInt32LE(cursor + 38);
-		const localOffset = buffer.readUInt32LE(cursor + 42);
-		const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
-		const symlink = ((externalAttributes >>> 16) & UNIX_MODE_FORMAT_MASK) === UNIX_MODE_SYMLINK;
+	let cursor = 0;
 
-		cursor += 46 + nameLength + extraLength + commentLength;
+	while (cursor + 4 <= extra.length) {
+		const id = extra.readUInt16LE(cursor);
+		const length = extra.readUInt16LE(cursor + 2);
+		const body = extra.subarray(cursor + 4, cursor + 4 + length);
 
-		if (name.endsWith("/") || (flags & ENCRYPTED_FLAG) !== 0) {
+		cursor += 4 + length;
+
+		if (id !== ZIP64_EXTRA_ID) {
 			continue;
 		}
 
-		if (uncompressedSize > MAX_ENTRY_BYTES) {
-			throw new Error(`archive entry "${name}" is too large`);
+		let field = 0;
+
+		if (sizeBytes === SIZE_SENTINEL && field + 8 <= body.length) {
+			extended.sizeBytes = readOffset(body, field);
+			field += 8;
+		}
+
+		if (compressedSize === SIZE_SENTINEL && field + 8 <= body.length) {
+			extended.compressedSize = readOffset(body, field);
+			field += 8;
 		}
 
-		if (localOffset + LOCAL_HEADER_LENGTH > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL_SIGNATURE) {
-			throw new Error(`archive entry "${name}" has a corrupt local header`);
+		if (localOffset === SIZE_SENTINEL && field + 8 <= body.length) {
+			extended.localOffset = readOffset(body, field);
 		}
 
-		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);
+		return extended;
+	}
 
-		if (method === STORED) {
-			entries.push({
-				name,
-				data: compressed,
-				symlink,
-			});
+	return extended;
+};
 
-			continue;
-		}
+export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT): Promise<ZipArchive> => {
+	const size = Bun.file(path).size;
+	const tailStart = Math.max(0, size - (EOCD_SEARCH_LIMIT + ZIP64_LOCATOR_LENGTH));
+	const tail = await readRange(path, tailStart, size);
+	const eocd = tail.length < EOCD_MIN_LENGTH ? -1 : findEndOfCentralDirectory(tail);
+
+	if (eocd === -1) {
+		throw new Error("archive has no zip central directory");
+	}
+
+	const directory = (await readZip64Directory(path, tail, eocd)) ?? {
+		total: tail.readUInt16LE(eocd + 10),
+		sizeBytes: tail.readUInt32LE(eocd + 12),
+		offset: tail.readUInt32LE(eocd + 16),
+	};
+
+	if (directory.total > maxEntries) {
+		throw new Error(`archive has too many entries (${directory.total})`);
+	}
+
+	const central = await readRange(path, directory.offset, directory.offset + directory.sizeBytes);
+	const entries: ZipEntry[] = [];
 
-		if (method !== DEFLATED) {
-			throw new Error(`archive entry "${name}" uses unsupported compression ${method}`);
+	let cursor = 0;
+
+	for (let index = 0; index < directory.total; index++) {
+		if (cursor + CENTRAL_HEADER_LENGTH > central.length || central.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+			throw new Error("archive central directory is corrupt");
 		}
 
-		const data = inflateRawSync(compressed, {
-			maxOutputLength: MAX_ENTRY_BYTES,
-		});
+		const flags = central.readUInt16LE(cursor + 8);
+		const method = central.readUInt16LE(cursor + 10);
+		const compressedSize = central.readUInt32LE(cursor + 20);
+		const sizeBytes = central.readUInt32LE(cursor + 24);
+		const nameLength = central.readUInt16LE(cursor + 28);
+		const extraLength = central.readUInt16LE(cursor + 30);
+		const commentLength = central.readUInt16LE(cursor + 32);
+		const externalAttributes = central.readUInt32LE(cursor + 38);
+		const localOffset = central.readUInt32LE(cursor + 42);
+		const nameStart = cursor + CENTRAL_HEADER_LENGTH;
+		const name = central.subarray(nameStart, nameStart + nameLength).toString("utf8");
+		const extra = central.subarray(nameStart + nameLength, nameStart + nameLength + extraLength);
+		const extended = readZip64Extra(extra, sizeBytes, compressedSize, localOffset);
+
+		cursor = nameStart + nameLength + extraLength + commentLength;
 
-		if (data.length !== uncompressedSize) {
-			throw new Error(`archive entry "${name}" did not inflate to its declared size`);
+		if (name.endsWith("/") || (flags & ENCRYPTED_FLAG) !== 0) {
+			continue;
 		}
 
 		entries.push({
 			name,
-			data,
-			symlink,
+			symlink: ((externalAttributes >>> 16) & UNIX_MODE_FORMAT_MASK) === UNIX_MODE_SYMLINK,
+			sizeBytes: extended.sizeBytes ?? sizeBytes,
+			compressedSize: extended.compressedSize ?? compressedSize,
+			method,
+			localOffset: extended.localOffset ?? localOffset,
 		});
 	}
 
-	return entries;
+	return {
+		entries,
+
+		async read(entry) {
+			if (entry.sizeBytes > MAX_ENTRY_BYTES || entry.compressedSize > MAX_ENTRY_BYTES) {
+				throw new Error(`archive entry "${entry.name}" is too large`);
+			}
+
+			const header = await readRange(path, entry.localOffset, entry.localOffset + LOCAL_HEADER_LENGTH);
+
+			if (header.length < LOCAL_HEADER_LENGTH || header.readUInt32LE(0) !== LOCAL_SIGNATURE) {
+				throw new Error(`archive entry "${entry.name}" has a corrupt local header`);
+			}
+
+			const dataOffset = entry.localOffset + LOCAL_HEADER_LENGTH + header.readUInt16LE(26) + header.readUInt16LE(28);
+			const compressed = await readRange(path, dataOffset, dataOffset + entry.compressedSize);
+
+			if (entry.method === STORED) {
+				return compressed;
+			}
+
+			if (entry.method !== DEFLATED) {
+				throw new Error(`archive entry "${entry.name}" uses unsupported compression ${entry.method}`);
+			}
+
+			const data = inflateRawSync(compressed, {
+				maxOutputLength: MAX_ENTRY_BYTES,
+			});
+
+			if (data.length !== entry.sizeBytes) {
+				throw new Error(`archive entry "${entry.name}" did not inflate to its declared size`);
+			}
+
+			return data;
+		},
+	};
 };

package/src/runtime/serve.ts

@@ -1,10 +1,11 @@
 import { chmod, chown, mkdir, rm } from "node:fs/promises";
-import { BridgeDesired, BridgeRuntime } from "../core";
+import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError } from "../core";
 import type { BridgeDriver } from "../modules";
 import {
 	BRIDGE_INSTALL_ERROR_LIMIT,
 	BRIDGE_VERSION,
 	type BridgeConfig,
+	type BridgePendingResult,
 	type BridgeSampleResult,
 	type BridgeStatus,
 } from "../protocol";
@@ -12,7 +13,9 @@ import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigRea
 import { createContext } from "./bridgeContext";
 import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
+import { decideInstall, recountHold } from "./bridgeInstall";
 import { errorText, log } from "./bridgeLog";
+import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
 import { readDesired, writeDesired } from "./bridgeState";
@@ -64,6 +67,8 @@ export const serve = async (driver: BridgeDriver) => {
 
 	let installError: string | null = null;
 
+	let installHold: BridgeInstallHold | null = null;
+
 	const supervisor = createSupervisor({
 		cwd: config.cwd,
 		uid: config.gameUid,
@@ -105,8 +110,10 @@ export const serve = async (driver: BridgeDriver) => {
 			runtime: supervisor.runtime,
 			desired: current,
 			exitCode: supervisor.exitCode,
+			outOfMemory: supervisor.outOfMemory,
 			restarts: supervisor.restarts,
 			installError,
+			installHold,
 		};
 	};
 
@@ -152,6 +159,20 @@ export const serve = async (driver: BridgeDriver) => {
 		return value;
 	};
 
+	const pending = async (): Promise<BridgePendingResult> => {
+		const module = driver.pending;
+
+		if (!module) {
+			return unsupportedPending();
+		}
+
+		const files = await module.list(context);
+
+		installHold = recountHold(installHold, files.length);
+
+		return pendingResult(module.staging, module.extensions, files, log);
+	};
+
 	const server = createServer({
 		socket: socketPath(config),
 		token: config.token,
@@ -260,6 +281,32 @@ export const serve = async (driver: BridgeDriver) => {
 				delivered: true,
 			};
 		},
+		async onPendingList() {
+			return await pending();
+		},
+		async onPendingAdd(input) {
+			const module = driver.pending;
+
+			if (!module) {
+				return unsupportedPending();
+			}
+
+			try {
+				await module.add(context, input);
+			} catch (error) {
+				if (!(error instanceof BridgeUserError)) {
+					throw error;
+				}
+
+				log.warn("pending upload rejected", {
+					error: error.message,
+				});
+
+				return rejectedPending(await pending());
+			}
+
+			return await pending();
+		},
 	});
 
 	await chmod(socketPath(config), SOCKET_MODE);
@@ -303,8 +350,10 @@ export const serve = async (driver: BridgeDriver) => {
 
 	log("installing");
 
+	let decision = decideInstall(undefined, current);
+
 	try {
-		await driver.install.run(context);
+		decision = decideInstall(await driver.install.run(context), current);
 
 		log("install complete");
 	} catch (error) {
@@ -319,9 +368,20 @@ export const serve = async (driver: BridgeDriver) => {
 		return;
 	}
 
-	supervisor.setRuntime(current === BridgeDesired.Running ? BridgeRuntime.Starting : BridgeRuntime.Stopped);
+	installHold = decision.hold;
+
+	supervisor.setRuntime(decision.runtime);
+
+	if (installHold) {
+		log("install held", {
+			reason: installHold.reason,
+			count: installHold.count,
+		});
+
+		return;
+	}
 
-	if (current === BridgeDesired.Running) {
+	if (decision.start) {
 		try {
 			await supervisor.start();
 		} catch (error) {