@serverkgg/bridge 0.0.16 → 0.0.18

package/src/runtime/bridgeRegistry.ts

@@ -31,6 +31,18 @@ const requiresRunning = (module: BridgePanelModule) => {
 	return false;
 };
 
+export const protectedActionsOf = (module: BridgePanelModule): string[] => {
+	const protectedActions = "protectedActions" in module ? (module.protectedActions ?? []) : [];
+	const declared = actionsOf(module);
+	if (
+		protectedActions.some((action) => isReadAction(action) || !declared.includes(action))
+		|| (protectedActions.length > 0 && requiresRunning(module))
+	) {
+		throw new BridgeDriverError("protected actions must be declared mutations that work while stopped");
+	}
+	return protectedActions;
+};
+
 const refreshOf = (module: BridgePanelModule) => {
 	if (module.kind === BridgeKind.Collection || module.kind === BridgeKind.Detail) {
 		return module.refreshSeconds ?? null;
@@ -312,9 +324,7 @@ export const createRegistry = (
 				}
 
 				if (action === BridgeAction.Add && module.add) {
-					await module.add(context, asString(args, "input"));
-
-					return null;
+					return (await module.add(context, asString(args, "input"))) ?? null;
 				}
 
 				const rowAction = module.actions?.[action];
@@ -358,6 +368,12 @@ export const createRegistry = (
 			}
 
 			case BridgeKind.Catalog: {
+				if (action === BridgeAction.Releases && module.releases) {
+					return await module.releases(context, asString(args, "id"));
+				}
+				if (action === BridgeAction.Preview && module.preview) {
+					return await module.preview(context, asString(args, "id"), asOptional(args, "releaseId") ?? undefined);
+				}
 				if (action === BridgeAction.Search) {
 					return await module.search(context, {
 						query: asText(args, "query"),
@@ -373,7 +389,7 @@ export const createRegistry = (
 				}
 
 				if (action === BridgeAction.Install) {
-					return await module.install(context, asString(args, "id"));
+					return await module.install(context, asString(args, "id"), asOptional(args, "releaseId") ?? undefined);
 				}
 
 				if (action === BridgeAction.Remove) {
@@ -398,6 +414,7 @@ export const createRegistry = (
 	return {
 		manifest(): BridgeManifest {
 			const entries: BridgeModuleManifest[] = Object.entries(modules).map(([id, module]) => {
+				const protectedActions = protectedActionsOf(module);
 				return {
 					id,
 					kind: module.kind,
@@ -406,6 +423,11 @@ export const createRegistry = (
 					pageSize: pageSizeOf(module),
 					dependsOn: dependsOf(module),
 					actions: actionsOf(module),
+					...(protectedActions.length > 0
+						? {
+								protectedActions,
+							}
+						: {}),
 				};
 			});
 
@@ -419,13 +441,17 @@ export const createRegistry = (
 			};
 		},
 
-		async invoke(name: string, action: string, args: BridgeValues = {}) {
+		async invoke(name: string, action: string, args: BridgeValues = {}, recoveryOperationId?: string) {
 			const module = modules[name];
 
 			if (!module) {
 				throw new BridgeDriverError(`no module named "${name}"`);
 			}
 
+			if (protectedActionsOf(module).includes(action) && (!recoveryOperationId || supervisor.running)) {
+				throw new BridgeDriverError("this action needs a recovery operation with the game stopped");
+			}
+
 			if (requiresRunning(module) && !supervisor.running) {
 				throw new BridgeDriverError(`module "${name}" needs the game to be running`);
 			}

package/src/runtime/bridgeServer.test.ts

@@ -597,3 +597,60 @@ describe("error serialisation", () => {
 		});
 	});
 });
+
+describe("backup ownership dispatch", () => {
+	let dir = "";
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-lease-"));
+	});
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+	test("carries the lease token through renew and release frames", async () => {
+		const socket = join(dir, "bridge.sock");
+		const renewals: (string | undefined)[] = [];
+		const releases: (string | undefined)[] = [];
+		const server = createServer({
+			...baseOptions(socket),
+			onQuiesce: async (supportsSnapshot, leaseId) => {
+				expect(supportsSnapshot).toBe(true);
+				renewals.push(leaseId);
+				return {
+					supported: true,
+					quiesced: true,
+					settleSeconds: 0,
+					leaseId,
+				};
+			},
+			onRelease: async (leaseId) => {
+				releases.push(leaseId);
+			},
+		});
+		try {
+			await call(socket, {
+				id: "renew",
+				token: TOKEN,
+				method: BridgeMethod.Quiesce,
+				supportsSnapshot: true,
+				leaseId: "owner",
+			});
+			await call(socket, {
+				id: "release",
+				token: TOKEN,
+				method: BridgeMethod.Release,
+				leaseId: "owner",
+			});
+			expect(renewals).toEqual([
+				"owner",
+			]);
+			expect(releases).toEqual([
+				"owner",
+			]);
+		} finally {
+			server.stop();
+		}
+	});
+});

package/src/runtime/bridgeServer.ts

@@ -25,11 +25,11 @@ export interface ServerOptions {
 	onStart: () => Promise<void>;
 	onStop: () => Promise<void>;
 	onCommand: (input: string, expect: string | undefined, timeoutMs: number | undefined) => Promise<BridgeCommandResult>;
-	onInvoke: (module: string, action: string, args: BridgeValues) => Promise<unknown>;
+	onInvoke: (module: string, action: string, args: BridgeValues, recoveryOperationId?: string) => Promise<unknown>;
 	onEvents: (cursor: number) => BridgeEventsResult;
 	onSample: () => Promise<BridgeSampleResult>;
-	onQuiesce: () => Promise<BridgeQuiesceResult>;
-	onRelease: () => Promise<void>;
+	onQuiesce: (supportsSnapshot: boolean, leaseId?: string) => Promise<BridgeQuiesceResult>;
+	onRelease: (leaseId?: string) => Promise<void>;
 	onDescribe: () => Promise<BridgeDescribeResult>;
 	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
 	onPendingList: () => Promise<BridgePendingResult>;
@@ -40,6 +40,9 @@ export interface ServerOptions {
 }
 
 interface IncomingFrame {
+	leaseId?: unknown;
+	supportsSnapshot?: unknown;
+	recoveryOperationId?: unknown;
 	id?: unknown;
 	token?: unknown;
 	method?: unknown;
@@ -116,7 +119,12 @@ export const createServer = (options: ServerOptions) => {
 			}
 
 			case BridgeMethod.Invoke: {
-				return await options.onInvoke(String(request.module ?? ""), String(request.action ?? ""), asArgs(request.args));
+				return await options.onInvoke(
+					String(request.module ?? ""),
+					String(request.action ?? ""),
+					asArgs(request.args),
+					asText(request.recoveryOperationId) ?? undefined,
+				);
 			}
 
 			case BridgeMethod.Events: {
@@ -128,11 +136,11 @@ export const createServer = (options: ServerOptions) => {
 			}
 
 			case BridgeMethod.Quiesce: {
-				return await options.onQuiesce();
+				return await options.onQuiesce(request.supportsSnapshot === true, asText(request.leaseId) ?? undefined);
 			}
 
 			case BridgeMethod.Release: {
-				await options.onRelease();
+				await options.onRelease(asText(request.leaseId) ?? undefined);
 
 				return null;
 			}

package/src/runtime/bridgeZip.ts

@@ -1,4 +1,4 @@
-import { inflateRawSync } from "node:zlib";
+import { crc32, inflateRawSync } from "node:zlib";
 
 const EOCD_SIGNATURE = 0x06_05_4b_50;
 
@@ -32,11 +32,14 @@ const DEFLATED = 8;
 
 const ENCRYPTED_FLAG = 0x1;
 
+const DATA_DESCRIPTOR_FLAG = 0x8;
+
 export const ZIP_ENTRY_LIMIT = 2048;
 
 export const ZIP_TREE_ENTRY_LIMIT = 16_384;
 
 const MAX_ENTRY_BYTES = 128 * 1024 * 1024;
+const MAX_CONFIGURED_ENTRY_BYTES = 512 * 1024 * 1024;
 
 const UNIX_MODE_FORMAT_MASK = 0xf0_00;
 
@@ -48,6 +51,8 @@ export interface ZipEntry {
 	sizeBytes: number;
 	compressedSize: number;
 	method: number;
+	flags: number;
+	checksum: number;
 	localOffset: number;
 }
 
@@ -155,7 +160,14 @@ const readZip64Extra = (extra: Buffer, sizeBytes: number, compressedSize: number
 	return extended;
 };
 
-export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT): Promise<ZipArchive> => {
+export const openZip = async (
+	path: string,
+	maxEntries: number = ZIP_ENTRY_LIMIT,
+	maxEntryBytes: number = MAX_ENTRY_BYTES,
+): Promise<ZipArchive> => {
+	if (!Number.isSafeInteger(maxEntryBytes) || maxEntryBytes <= 0 || maxEntryBytes > MAX_CONFIGURED_ENTRY_BYTES) {
+		throw new Error("archive entry byte limit is invalid");
+	}
 	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);
@@ -174,6 +186,9 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 	if (directory.total > maxEntries) {
 		throw new Error(`archive has too many entries (${directory.total})`);
 	}
+	if (directory.sizeBytes > 16 * 1024 * 1024 || directory.offset + directory.sizeBytes > size) {
+		throw new Error("archive central directory exceeds its bounds");
+	}
 
 	const central = await readRange(path, directory.offset, directory.offset + directory.sizeBytes);
 	const entries: ZipEntry[] = [];
@@ -187,6 +202,7 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 
 		const flags = central.readUInt16LE(cursor + 8);
 		const method = central.readUInt16LE(cursor + 10);
+		const checksum = central.readUInt32LE(cursor + 16);
 		const compressedSize = central.readUInt32LE(cursor + 20);
 		const sizeBytes = central.readUInt32LE(cursor + 24);
 		const nameLength = central.readUInt16LE(cursor + 28);
@@ -200,8 +216,14 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 		const extended = readZip64Extra(extra, sizeBytes, compressedSize, localOffset);
 
 		cursor = nameStart + nameLength + extraLength + commentLength;
+		if (cursor > central.length) {
+			throw new Error("archive central entry exceeds its directory");
+		}
 
-		if (name.endsWith("/") || (flags & ENCRYPTED_FLAG) !== 0) {
+		if ((flags & ENCRYPTED_FLAG) !== 0) {
+			throw new Error("encrypted archive entries are not supported");
+		}
+		if (name.endsWith("/")) {
 			continue;
 		}
 
@@ -211,6 +233,8 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 			sizeBytes: extended.sizeBytes ?? sizeBytes,
 			compressedSize: extended.compressedSize ?? compressedSize,
 			method,
+			flags,
+			checksum,
 			localOffset: extended.localOffset ?? localOffset,
 		});
 	}
@@ -219,20 +243,59 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 		entries,
 
 		async read(entry) {
-			if (entry.sizeBytes > MAX_ENTRY_BYTES || entry.compressedSize > MAX_ENTRY_BYTES) {
+			if (entry.sizeBytes > maxEntryBytes || entry.compressedSize > maxEntryBytes) {
 				throw new Error(`archive entry "${entry.name}" is too large`);
 			}
 
+			if (entry.localOffset + LOCAL_HEADER_LENGTH > directory.offset) {
+				throw new Error(`archive entry "${entry.name}" has an out-of-bounds local header`);
+			}
+
 			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);
+			if (header.readUInt16LE(8) !== entry.method || header.readUInt16LE(6) !== entry.flags) {
+				throw new Error(`archive entry "${entry.name}" has inconsistent local compression flags or method`);
+			}
+			if ((entry.flags & DATA_DESCRIPTOR_FLAG) === 0 && header.readUInt32LE(14) !== entry.checksum) {
+				throw new Error(`archive entry "${entry.name}" has inconsistent local checksum`);
+			}
+			if ((entry.flags & DATA_DESCRIPTOR_FLAG) === 0) {
+				const localCompressed = header.readUInt32LE(18);
+				const localSize = header.readUInt32LE(22);
+				if (
+					(localCompressed !== SIZE_SENTINEL && localCompressed !== entry.compressedSize)
+					|| (localSize !== SIZE_SENTINEL && localSize !== entry.sizeBytes)
+				) {
+					throw new Error(`archive entry "${entry.name}" has inconsistent local sizes`);
+				}
+			}
+
+			const nameOffset = entry.localOffset + LOCAL_HEADER_LENGTH;
+			const nameLength = header.readUInt16LE(26);
+			const dataOffset = nameOffset + nameLength + header.readUInt16LE(28);
+			if (dataOffset > directory.offset || entry.compressedSize > directory.offset - dataOffset) {
+				throw new Error(`archive entry "${entry.name}" data exceeds its local bounds`);
+			}
+			const name = await readRange(path, nameOffset, nameOffset + nameLength);
+			if (name.toString("utf8") !== entry.name) {
+				throw new Error(`archive entry "${entry.name}" has an inconsistent local name`);
+			}
 			const compressed = await readRange(path, dataOffset, dataOffset + entry.compressedSize);
+			if (compressed.length !== entry.compressedSize) {
+				throw new Error(`archive entry "${entry.name}" has truncated compressed data`);
+			}
 
 			if (entry.method === STORED) {
+				if (compressed.length !== entry.sizeBytes || compressed.length !== entry.compressedSize) {
+					throw new Error(`archive entry "${entry.name}" does not match its declared size`);
+				}
+				if (crc32(compressed) !== entry.checksum) {
+					throw new Error(`archive entry "${entry.name}" failed its CRC32 checksum`);
+				}
 				return compressed;
 			}
 
@@ -241,13 +304,17 @@ export const openZip = async (path: string, maxEntries: number = ZIP_ENTRY_LIMIT
 			}
 
 			const data = inflateRawSync(compressed, {
-				maxOutputLength: MAX_ENTRY_BYTES,
+				maxOutputLength: maxEntryBytes,
 			});
 
 			if (data.length !== entry.sizeBytes) {
 				throw new Error(`archive entry "${entry.name}" did not inflate to its declared size`);
 			}
 
+			if (crc32(data) !== entry.checksum) {
+				throw new Error(`archive entry "${entry.name}" failed its CRC32 checksum`);
+			}
+
 			return data;
 		},
 	};

package/src/runtime/serve.ts

@@ -9,6 +9,7 @@ import {
 	type BridgeSampleResult,
 	type BridgeStatus,
 } from "../protocol";
+import { createBackupLease } from "./bridgeBackupLease";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
 import { createConsoleHandler } from "./bridgeConsoleHandler";
 import { createContext } from "./bridgeContext";
@@ -120,6 +121,18 @@ export const serve = async (driver: BridgeDriver) => {
 	});
 
 	const registry = createRegistry(driver, context, supervisor, ring);
+	const backupLease = createBackupLease(async () => {
+		if (supervisor.running) {
+			await driver.backup?.release?.(context);
+		}
+	});
+	setInterval(() => {
+		void backupLease.expire().catch((error: unknown) => {
+			log.error("could not resume saves after the backup lease expired", {
+				error: errorText(error),
+			});
+		});
+	}, 10_000).unref();
 
 	const runConsole = createConsoleHandler({
 		driver,
@@ -229,8 +242,8 @@ export const serve = async (driver: BridgeDriver) => {
 				timeoutMs,
 			});
 		},
-		async onInvoke(module, action, args) {
-			return await registry.invoke(module, action, args);
+		async onInvoke(module, action, args, recoveryOperationId) {
+			return await registry.invoke(module, action, args, recoveryOperationId);
 		},
 		onEvents(cursor) {
 			return ring.drain(cursor);
@@ -238,7 +251,18 @@ export const serve = async (driver: BridgeDriver) => {
 		async onSample() {
 			return await sample();
 		},
-		async onQuiesce() {
+		async onQuiesce(supportsSnapshot, leaseId) {
+			if (leaseId) {
+				return {
+					supported: true,
+					quiesced: true,
+					settleSeconds: 0,
+					leaseId: backupLease.renew(leaseId),
+				};
+			}
+			if (backupLease.active) {
+				throw new Error("a backup already owns the save hold");
+			}
 			const backup = driver.backup;
 
 			if (!backup?.quiesce) {
@@ -257,19 +281,29 @@ export const serve = async (driver: BridgeDriver) => {
 				};
 			}
 
-			await backup.quiesce(context);
-
-			return {
-				supported: true,
-				quiesced: true,
-				settleSeconds: backup.settleSeconds ?? 0,
-			};
-		},
-		async onRelease() {
-			if (supervisor.running) {
-				await driver.backup?.release?.(context);
+			const quiesce = backup.quiesce;
+			const owner = backupLease.begin(!supportsSnapshot);
+			try {
+				const prepared = await backupLease.prepare(owner, () => quiesce(context));
+				if (prepared?.snapshot && !supportsSnapshot) {
+					throw new Error("this backup requires an agent that supports bounded snapshots");
+				}
+				backupLease.renew(owner);
+				return {
+					supported: true,
+					quiesced: true,
+					settleSeconds: backup.settleSeconds ?? 0,
+					snapshot: prepared?.snapshot,
+					leaseId: supportsSnapshot ? owner : undefined,
+				};
+			} catch (error) {
+				await backupLease.finish(owner);
+				throw error;
 			}
 		},
+		async onRelease(leaseId) {
+			await backupLease.finish(leaseId);
+		},
 		async onDescribe() {
 			const describe = driver.install.describe;
 

package/src/wire/panel.ts

@@ -337,6 +337,7 @@ export const bridgeModuleManifestSchema = z.object({
 	pageSize: z.int().positive().nullable().default(null),
 	dependsOn: z.array(zKey).max(8),
 	actions: z.array(z.string().min(1).max(64)).max(16),
+	protectedActions: z.array(z.string().min(1).max(64)).max(16).optional(),
 });
 
 export const bridgeManifestSchema: z.ZodType<BridgeManifest> = z.object({