@serverkgg/bridge 0.0.8 → 0.0.9

package/src/runtime/bridgeFiles.ts

@@ -1,21 +1,28 @@
 import type { Dirent } from "node:fs";
 import { chown, mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
-import type { BridgeDownloadOptions, BridgeExtractOptions, BridgeFileEntry, BridgeFiles } from "../context";
-import { compileGlob } from "../utils";
+import type {
+	BridgeDigestAlgorithm,
+	BridgeDownloadOptions,
+	BridgeExtractOptions,
+	BridgeFileEntry,
+	BridgeFiles,
+} from "../context";
+import { BridgeDownloadError } from "../core";
+import { compileGlob, compileGlobs, matchesAny } from "../utils";
 import { type BridgeEgress, BridgeEgressCallError, BridgeEgressUnavailableError } from "./bridgeEgress";
-import type { BridgeLogger } from "./bridgeLog";
+import type { BridgeLeveledLogger } from "./bridgeLog";
 import { USER_AGENT } from "./bridgeNet";
 import { BridgePathError, resolveWithin, toSegments } from "./bridgePath";
 import { isPrivileged } from "./bridgePrivilege";
-import { readZip, ZIP_ENTRY_LIMIT, ZIP_TREE_ENTRY_LIMIT } from "./bridgeZip";
+import { openZip, ZIP_ENTRY_LIMIT, ZIP_TREE_ENTRY_LIMIT } from "./bridgeZip";
 
 const READ_LIMIT = 4 * 1024 * 1024;
 
-const DOWNLOAD_LIMIT = 512 * 1024 * 1024;
+const DOWNLOAD_LIMIT = 2 * 1024 * 1024 * 1024;
 
 const DOWNLOAD_TIMEOUT_MS = 300_000;
 
-const ARCHIVE_LIMIT = 256 * 1024 * 1024;
+const ARCHIVE_LIMIT = 2 * 1024 * 1024 * 1024;
 
 const WALK_DEPTH = 12;
 
@@ -23,18 +30,22 @@ const WALK_LIMIT = 4096;
 
 const MILESTONE_STEP = 25;
 
-const DIGEST_LENGTHS: Record<string, number> = {
+const DIGEST_LENGTHS: Record<BridgeDigestAlgorithm, number> = {
 	sha1: 40,
 	sha256: 64,
 	sha512: 128,
 };
 
+const isDigestAlgorithm = (value: string): value is BridgeDigestAlgorithm => {
+	return Object.hasOwn(DIGEST_LENGTHS, value);
+};
+
 export interface BridgeFilesOptions {
 	root: string;
 	uid: number;
 	gid: number;
 	egress: BridgeEgress;
-	onLog: BridgeLogger;
+	onLog: BridgeLeveledLogger;
 }
 
 interface DownloadSource {
@@ -45,12 +56,12 @@ interface DownloadSource {
 const parseDigest = (digest: string) => {
 	const [algo, expected] = digest.split(":");
 
-	if (!algo || !expected || DIGEST_LENGTHS[algo] !== expected.length) {
+	if (!algo || !expected || !isDigestAlgorithm(algo) || DIGEST_LENGTHS[algo] !== expected.length) {
 		throw new BridgePathError("invalid", `digest "${digest}" is not supported`);
 	}
 
 	return {
-		algo: algo as "sha1" | "sha256" | "sha512",
+		algo,
 		expected,
 	};
 };
@@ -93,22 +104,87 @@ const directorySize = async (path: string, depth: number): Promise<number> => {
 	return total;
 };
 
-const selectPrefix = (select: string | undefined) => {
-	if (select === undefined) {
-		return null;
+const SUFFIX_PREFIX = "**/";
+
+type ArchiveSelect =
+	| {
+			kind: "entry";
+			value: string;
+	  }
+	| {
+			kind: "prefix";
+			value: string;
+	  }
+	| {
+			kind: "suffix";
+			value: string;
+	  };
+
+const prefixSelect = (select: string): ArchiveSelect => {
+	const segments = toSegments(select);
+
+	return {
+		kind: "prefix",
+		value: segments.length === 0 ? "" : `${segments.join("/")}/`,
+	};
+};
+
+const entrySelect = (select: string): ArchiveSelect => {
+	return {
+		kind: "entry",
+		value: toSegments(select).join("/"),
+	};
+};
+
+const suffixSelect = (select: string): ArchiveSelect => {
+	return {
+		kind: "suffix",
+		value: toSegments(select.slice(SUFFIX_PREFIX.length)).join("/"),
+	};
+};
+
+const compileSelect = (select: string): ArchiveSelect => {
+	if (select.startsWith(SUFFIX_PREFIX)) {
+		return suffixSelect(select);
 	}
 
-	const segments = toSegments(select);
+	return select.endsWith("/") ? prefixSelect(select) : entrySelect(select);
+};
+
+const compileSelects = (select: string | undefined, selects: string[] | undefined) => {
+	const compiled: ArchiveSelect[] = [];
 
-	return segments.length === 0 ? null : `${segments.join("/")}/`;
+	if (select !== undefined) {
+		compiled.push(prefixSelect(select));
+	}
+
+	for (const entry of selects ?? []) {
+		compiled.push(compileSelect(entry));
+	}
+
+	return compiled;
 };
 
-const selectedName = (name: string, prefix: string | null) => {
-	if (prefix === null) {
+const selectedName = (name: string, selects: ArchiveSelect[]) => {
+	if (selects.length === 0) {
 		return name;
 	}
 
-	return name.startsWith(prefix) ? name.slice(prefix.length) : null;
+	for (const select of selects) {
+		if (select.kind === "prefix" && name.startsWith(select.value)) {
+			return name.slice(select.value.length);
+		}
+
+		if (select.kind === "entry" && name === select.value) {
+			return name;
+		}
+
+		if (select.kind === "suffix" && (name === select.value || name.endsWith(`/${select.value}`))) {
+			return select.value;
+		}
+	}
+
+	return null;
 };
 
 const treeSegments = (name: string) => {
@@ -207,6 +283,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				const shared = await options.egress.download(remote.href, {
 					digest: downloadOptions.digest,
 					sizeBytes: downloadOptions.sizeBytes,
+					timeoutMs: downloadOptions.timeoutMs,
 				});
 
 				return {
@@ -215,7 +292,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				};
 			} catch (error) {
 				if (error instanceof BridgeEgressCallError) {
-					throw new BridgePathError("missing", `${remote.host} answered ${error.status ?? error.message}`);
+					throw new BridgeDownloadError(error.status, `${remote.host} answered ${error.status ?? error.message}`);
 				}
 
 				if (!(error instanceof BridgeEgressUnavailableError)) {
@@ -229,11 +306,11 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				"user-agent": USER_AGENT,
 			},
 			redirect: "error",
-			signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+			signal: AbortSignal.timeout(downloadOptions.timeoutMs ?? DOWNLOAD_TIMEOUT_MS),
 		});
 
 		if (!response.ok || !response.body) {
-			throw new BridgePathError("missing", `${remote.host} answered ${response.status}`);
+			throw new BridgeDownloadError(response.status, `${remote.host} answered ${response.status}`);
 		}
 
 		const declared = Number(response.headers.get("content-length"));
@@ -333,6 +410,22 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			return resolved.isDirectory ? await directorySize(resolved.target, 0) : resolved.sizeBytes;
 		},
 
+		async digest(path, algorithm) {
+			const resolved = await resolveWithin(options.root, path);
+
+			if (!resolved.exists || resolved.isDirectory) {
+				throw new BridgePathError("missing", `path "${path}" is not a readable file`);
+			}
+
+			const hasher = new Bun.CryptoHasher(algorithm);
+
+			for await (const chunk of Bun.file(resolved.target).stream()) {
+				hasher.update(chunk);
+			}
+
+			return hasher.digest("hex");
+		},
+
 		async download(path, url, downloadOptions: BridgeDownloadOptions = {}) {
 			const remote = new URL(url);
 
@@ -340,12 +433,15 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				throw new BridgePathError("invalid", `${remote.host} is not https`);
 			}
 
-			const limit = downloadOptions.sizeBytes ?? DOWNLOAD_LIMIT;
+			const declared = downloadOptions.sizeBytes;
 
-			if (limit > DOWNLOAD_LIMIT) {
-				throw new BridgePathError("invalid", `download of ${limit} bytes exceeds the limit`);
+			if (declared !== undefined && declared > DOWNLOAD_LIMIT) {
+				throw new BridgePathError("invalid", `download of ${declared} bytes exceeds the limit`);
 			}
 
+			const verified = downloadOptions.digest !== undefined;
+			const limit = verified ? DOWNLOAD_LIMIT : (declared ?? DOWNLOAD_LIMIT);
+
 			const source = await openSource(remote, downloadOptions);
 
 			await ensureParent(path);
@@ -357,11 +453,14 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 
 			const hasher = downloadOptions.digest ? new Bun.CryptoHasher(parseDigest(downloadOptions.digest).algo) : null;
 			const writer = Bun.file(staging).writer();
+			const quiet = downloadOptions.quiet === true;
 
-			options.onLog("downloading", {
-				file: resolved.relative,
-				sizeBytes: totalBytes,
-			});
+			if (!quiet) {
+				options.onLog("downloading", {
+					file: resolved.relative,
+					sizeBytes: totalBytes,
+				});
+			}
 
 			let readBytes = 0;
 
@@ -380,7 +479,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 
 					await writer.flush();
 
-					if (totalBytes !== null) {
+					if (totalBytes !== null && !quiet) {
 						const reached = Math.floor((readBytes / totalBytes) * 100);
 
 						if (reached >= milestone + MILESTONE_STEP && reached < 100) {
@@ -396,11 +495,8 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 
 				await writer.end();
 
-				if (downloadOptions.sizeBytes !== undefined && readBytes !== downloadOptions.sizeBytes) {
-					throw new BridgePathError(
-						"invalid",
-						`${remote.host} returned ${readBytes} bytes, expected ${downloadOptions.sizeBytes}`,
-					);
+				if (!verified && declared !== undefined && readBytes !== declared) {
+					throw new BridgePathError("invalid", `${remote.host} returned ${readBytes} bytes, expected ${declared}`);
 				}
 
 				if (hasher && downloadOptions.digest) {
@@ -410,6 +506,14 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 						throw new BridgePathError("invalid", `${remote.host} failed digest verification`);
 					}
 				}
+
+				if (verified && declared !== undefined && readBytes !== declared) {
+					options.onLog.warn("the source declared a different size, the checksum passed so we kept the file", {
+						file: resolved.relative,
+						sizeBytes: readBytes,
+						declaredBytes: declared,
+					});
+				}
 			} catch (error) {
 				writer.end();
 
@@ -423,10 +527,12 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			await rename(staging, resolved.target);
 			await own(resolved.target);
 
-			options.onLog("downloaded", {
-				file: resolved.relative,
-				sizeBytes: readBytes,
-			});
+			if (!quiet) {
+				options.onLog("downloaded", {
+					file: resolved.relative,
+					sizeBytes: readBytes,
+				});
+			}
 		},
 
 		async extract(path, destination, extractOptions: BridgeExtractOptions = {}) {
@@ -442,17 +548,18 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 
 			const tree = extractOptions.tree === true;
 			const allowed = extractOptions.extensions?.map((extension) => extension.toLowerCase());
-			const prefix = selectPrefix(extractOptions.select);
+			const selects = compileSelects(extractOptions.select, extractOptions.selects);
+			const excluded = compileGlobs(extractOptions.exclude ?? []);
 			const base = toSegments(destination);
 			const target = await ensureDirectory(destination);
-			const buffer = Buffer.from(await Bun.file(resolved.target).arrayBuffer());
+			const archive = await openZip(resolved.target, tree ? ZIP_TREE_ENTRY_LIMIT : ZIP_ENTRY_LIMIT);
 			const directories = new Set<string>();
 			const written: string[] = [];
 
-			for (const entry of readZip(buffer, tree ? ZIP_TREE_ENTRY_LIMIT : ZIP_ENTRY_LIMIT)) {
-				const selected = selectedName(entry.name, prefix);
+			for (const entry of archive.entries) {
+				const selected = selectedName(entry.name, selects);
 
-				if (selected === null) {
+				if (selected === null || matchesAny(selected, excluded)) {
 					continue;
 				}
 
@@ -495,13 +602,13 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 					...segments,
 				].join("/");
 
-				await Bun.write(`${target}/${segments.join("/")}`, entry.data);
+				await Bun.write(`${target}/${segments.join("/")}`, await archive.read(entry));
 				await own(`${target}/${segments.join("/")}`);
 
 				written.push(relative);
 			}
 
-			if (written.length === 0) {
+			if (written.length === 0 && extractOptions.selects === undefined) {
 				throw new BridgePathError("invalid", `archive "${path}" contained no matching files`);
 			}
 

package/src/runtime/bridgeInstall.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeDesired, BridgeHoldReason, BridgeRuntime } from "../core";
+import { decideInstall, recountHold } from "./bridgeInstall";
+
+describe("decideInstall", () => {
+	test("starts the game when the install returns nothing and the server wants to run", () => {
+		expect(decideInstall(undefined, BridgeDesired.Running)).toEqual({
+			hold: null,
+			runtime: BridgeRuntime.Starting,
+			start: true,
+		});
+	});
+
+	test("stays stopped when the install returns nothing and the server wants to stay down", () => {
+		expect(decideInstall(undefined, BridgeDesired.Stopped)).toEqual({
+			hold: null,
+			runtime: BridgeRuntime.Stopped,
+			start: false,
+		});
+	});
+
+	test("starts the game when the install answers with no hold", () => {
+		expect(
+			decideInstall(
+				{
+					hold: null,
+				},
+				BridgeDesired.Running,
+			),
+		).toEqual({
+			hold: null,
+			runtime: BridgeRuntime.Starting,
+			start: true,
+		});
+	});
+
+	test("holds the game stopped when the install answers with a hold", () => {
+		const hold = {
+			reason: BridgeHoldReason.PendingFiles,
+			count: 2,
+		};
+
+		expect(
+			decideInstall(
+				{
+					hold,
+				},
+				BridgeDesired.Running,
+			),
+		).toEqual({
+			hold,
+			runtime: BridgeRuntime.Stopped,
+			start: false,
+		});
+	});
+
+	test("keeps the hold when the server was already stopped", () => {
+		const hold = {
+			reason: BridgeHoldReason.PendingFiles,
+			count: 1,
+		};
+
+		expect(
+			decideInstall(
+				{
+					hold,
+				},
+				BridgeDesired.Stopped,
+			),
+		).toEqual({
+			hold,
+			runtime: BridgeRuntime.Stopped,
+			start: false,
+		});
+	});
+});
+
+describe("recountHold", () => {
+	test("leaves a driver without a hold alone", () => {
+		expect(recountHold(null, 3)).toBeNull();
+	});
+
+	test("moves the count of a pending-files hold to what the driver now lists", () => {
+		expect(
+			recountHold(
+				{
+					reason: BridgeHoldReason.PendingFiles,
+					count: 3,
+				},
+				1,
+			),
+		).toEqual({
+			reason: BridgeHoldReason.PendingFiles,
+			count: 1,
+		});
+	});
+
+	test("keeps the same hold when the count did not move", () => {
+		const hold = {
+			reason: BridgeHoldReason.PendingFiles,
+			count: 2,
+		};
+
+		expect(recountHold(hold, 2)).toBe(hold);
+	});
+
+	test("clears the hold when nothing is pending any more", () => {
+		expect(
+			recountHold(
+				{
+					reason: BridgeHoldReason.PendingFiles,
+					count: 1,
+				},
+				0,
+			),
+		).toBeNull();
+	});
+});

package/src/runtime/bridgeInstall.ts

@@ -0,0 +1,55 @@
+import {
+	BridgeDesired,
+	BridgeHoldReason,
+	type BridgeInstallHold,
+	type BridgeInstallOutcome,
+	BridgeRuntime,
+} from "../core";
+
+export interface BridgeInstallDecision {
+	hold: BridgeInstallHold | null;
+	runtime: BridgeRuntime;
+	start: boolean;
+}
+
+export const decideInstall = (
+	outcome: BridgeInstallOutcome | undefined,
+	desired: BridgeDesired,
+): BridgeInstallDecision => {
+	const hold = outcome ? outcome.hold : null;
+
+	if (hold) {
+		return {
+			hold,
+			runtime: BridgeRuntime.Stopped,
+			start: false,
+		};
+	}
+
+	const running = desired === BridgeDesired.Running;
+
+	return {
+		hold: null,
+		runtime: running ? BridgeRuntime.Starting : BridgeRuntime.Stopped,
+		start: running,
+	};
+};
+
+export const recountHold = (hold: BridgeInstallHold | null, count: number): BridgeInstallHold | null => {
+	if (!hold || hold.reason !== BridgeHoldReason.PendingFiles) {
+		return hold;
+	}
+
+	if (count <= 0) {
+		return null;
+	}
+
+	if (hold.count === count) {
+		return hold;
+	}
+
+	return {
+		reason: hold.reason,
+		count,
+	};
+};

package/src/runtime/bridgeNet.ts

@@ -1,5 +1,6 @@
 import type { BridgeNet, BridgeRequestOptions } from "../context";
 import { BridgeNetError } from "../core";
+import { BridgeHttpMethod } from "../protocol";
 import { type BridgeEgress, BridgeEgressCallError, BridgeEgressUnavailableError } from "./bridgeEgress";
 
 const REQUEST_TIMEOUT_MS = 15_000;
@@ -10,6 +11,10 @@ export const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
 
 const LINE_BREAK = /[\r\n]/;
 
+const hasHeader = (headers: Record<string, string> | undefined, name: string) => {
+	return Object.keys(headers ?? {}).some((key) => key.toLowerCase() === name);
+};
+
 export const safeHeaders = (headers: Record<string, string> = {}) => {
 	const checked: Record<string, string> = {};
 
@@ -54,12 +59,24 @@ const readCapped = async (response: Response, host: string) => {
 };
 
 export const createBridgeNet = (egress: BridgeEgress): BridgeNet => {
-	const direct = async (remote: URL, headers: Record<string, string>, timeoutMs: number) => {
+	const direct = async (
+		remote: URL,
+		headers: Record<string, string>,
+		timeoutMs: number,
+		httpMethod: BridgeHttpMethod,
+		body: string | null,
+	) => {
 		const response = await fetch(remote, {
+			method: httpMethod,
 			headers: {
 				...headers,
 				"user-agent": USER_AGENT,
 			},
+			...(body === null
+				? {}
+				: {
+						body,
+					}),
 			redirect: "error",
 			signal: AbortSignal.timeout(timeoutMs),
 		});
@@ -78,11 +95,23 @@ export const createBridgeNet = (egress: BridgeEgress): BridgeNet => {
 			throw new BridgeNetError(null, `${remote.host} is not https`);
 		}
 
-		const headers = safeHeaders(options.headers);
+		const httpMethod = options.httpMethod ?? BridgeHttpMethod.Get;
+		const body = httpMethod === BridgeHttpMethod.Post ? (options.body ?? null) : null;
+
+		const headers = safeHeaders({
+			...(body !== null && !hasHeader(options.headers, "content-type")
+				? {
+						"content-type": "application/json",
+					}
+				: {}),
+			...options.headers,
+		});
 
 		try {
 			const result = await egress.fetch(url, {
 				...options,
+				httpMethod,
+				body: body ?? undefined,
 				headers,
 			});
 
@@ -97,7 +126,7 @@ export const createBridgeNet = (egress: BridgeEgress): BridgeNet => {
 			}
 		}
 
-		return await direct(remote, headers, options.timeoutMs ?? REQUEST_TIMEOUT_MS);
+		return await direct(remote, headers, options.timeoutMs ?? REQUEST_TIMEOUT_MS, httpMethod, body);
 	};
 
 	return {