@serverkgg/bridge 0.0.1 → 0.0.3

package/src/runtime/bridgeEvents.ts

@@ -51,7 +51,10 @@ export const createEventRing = (events: BridgeEventsModule | undefined, supervis
 	return {
 		names() {
 			return [
-				...new Set((events?.patterns ?? []).map((pattern) => pattern.emit)),
+				...new Set([
+					...(events?.patterns ?? []).map((pattern) => pattern.emit),
+					...(events?.emits ?? []),
+				]),
 			];
 		},
 

package/src/runtime/bridgeExec.ts

@@ -8,10 +8,20 @@ const OUTPUT_LIMIT = 256 * 1024;
 
 const EXIT_GRACE_MS = 3000;
 
-const BASE_ENVIRONMENT = {
-	HOME: "/home/container",
-	LANG: "C.UTF-8",
-	PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+const FALLBACK_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+
+const inheritedPath = () => {
+	const declared = process.env.PATH ?? "";
+
+	return declared.length > 0 ? declared : FALLBACK_PATH;
+};
+
+const baseEnvironment = () => {
+	return {
+		HOME: "/home/container",
+		LANG: "C.UTF-8",
+		PATH: inheritedPath(),
+	};
 };
 
 export class BridgeExecError extends Error {
@@ -92,7 +102,7 @@ export const createBridgeExec = (target: BridgeExecTarget) => {
 		const child = Bun.spawn(argv, {
 			cwd: target.cwd,
 			env: {
-				...BASE_ENVIRONMENT,
+				...baseEnvironment(),
 				HOME: target.cwd,
 				...environment,
 			},

package/src/runtime/bridgeFiles.test.ts

@@ -0,0 +1,334 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import type { BridgeFiles } from "../context";
+import type { BridgeEgress } from "./bridgeEgress";
+import { createBridgeFiles } from "./bridgeFiles";
+
+const LOCAL_SIGNATURE = 0x04_03_4b_50;
+
+const CENTRAL_SIGNATURE = 0x02_01_4b_50;
+
+const EOCD_SIGNATURE = 0x06_05_4b_50;
+
+const FILE_ATTRIBUTES = 0x81_a4_00_00;
+
+const SYMLINK_ATTRIBUTES = 0xa1_ff_00_00;
+
+interface ArchiveEntry {
+	name: string;
+	content: string;
+	symlink?: boolean;
+}
+
+const buildZip = (entries: ArchiveEntry[]) => {
+	const locals: Buffer[] = [];
+	const centrals: Buffer[] = [];
+
+	let offset = 0;
+
+	for (const entry of entries) {
+		const name = Buffer.from(entry.name, "utf8");
+		const data = Buffer.from(entry.content, "utf8");
+
+		const local = Buffer.alloc(30);
+
+		local.writeUInt32LE(LOCAL_SIGNATURE, 0);
+		local.writeUInt16LE(20, 4);
+		local.writeUInt32LE(data.length, 18);
+		local.writeUInt32LE(data.length, 22);
+		local.writeUInt16LE(name.length, 26);
+
+		const central = Buffer.alloc(46);
+
+		central.writeUInt32LE(CENTRAL_SIGNATURE, 0);
+		central.writeUInt16LE(20, 6);
+		central.writeUInt32LE(data.length, 20);
+		central.writeUInt32LE(data.length, 24);
+		central.writeUInt16LE(name.length, 28);
+		central.writeUInt32LE(entry.symlink === true ? SYMLINK_ATTRIBUTES : FILE_ATTRIBUTES, 38);
+		central.writeUInt32LE(offset, 42);
+
+		locals.push(local, name, data);
+		centrals.push(central, name);
+
+		offset += 30 + name.length + data.length;
+	}
+
+	const body = Buffer.concat(locals);
+	const directory = Buffer.concat(centrals);
+	const end = Buffer.alloc(22);
+
+	end.writeUInt32LE(EOCD_SIGNATURE, 0);
+	end.writeUInt16LE(entries.length, 8);
+	end.writeUInt16LE(entries.length, 10);
+	end.writeUInt32LE(directory.length, 12);
+	end.writeUInt32LE(body.length, 16);
+
+	return Buffer.concat([
+		body,
+		directory,
+		end,
+	]);
+};
+
+const egress: BridgeEgress = {
+	fetch() {
+		throw new Error("the egress channel is not part of this test");
+	},
+
+	download() {
+		throw new Error("the egress channel is not part of this test");
+	},
+};
+
+describe("extract", () => {
+	let root = "";
+	let files: BridgeFiles;
+
+	const archive = async (entries: ArchiveEntry[]) => {
+		await Bun.write(`${root}/pack.zip`, buildZip(entries));
+
+		return "pack.zip";
+	};
+
+	const read = async (path: string) => {
+		return await Bun.file(`${root}/${path}`).text();
+	};
+
+	beforeEach(async () => {
+		root = await mkdtemp(`${tmpdir()}/serverk-bridge-`);
+
+		files = createBridgeFiles({
+			root,
+			uid: 0,
+			gid: 0,
+			egress,
+			onLog: () => undefined,
+		});
+	});
+
+	afterEach(async () => {
+		await rm(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("flattens paths, skips dotfiles and filters extensions by default", async () => {
+		const path = await archive([
+			{
+				name: "overrides/mods/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "overrides/config/beta.json",
+				content: "beta",
+			},
+			{
+				name: ".hidden.jar",
+				content: "hidden",
+			},
+		]);
+
+		const written = await files.extract(path, "mods", {
+			extensions: [
+				"jar",
+			],
+		});
+
+		expect(written).toEqual([
+			"mods/alpha.jar",
+		]);
+
+		expect(await read("mods/alpha.jar")).toBe("alpha");
+	});
+
+	test("flattens paths with no options at all", async () => {
+		const path = await archive([
+			{
+				name: "nested/deep/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "beta.txt",
+				content: "beta",
+			},
+		]);
+
+		const written = await files.extract(path, "plugins");
+
+		expect(written).toEqual([
+			"plugins/alpha.jar",
+			"plugins/beta.txt",
+		]);
+	});
+
+	test("keeps relative paths and creates intermediate directories in tree mode", async () => {
+		const path = await archive([
+			{
+				name: "mods/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "config/deep/beta.json",
+				content: "beta",
+			},
+		]);
+
+		const written = await files.extract(path, "staging", {
+			tree: true,
+		});
+
+		expect(written).toEqual([
+			"staging/mods/alpha.jar",
+			"staging/config/deep/beta.json",
+		]);
+
+		expect(await read("staging/mods/alpha.jar")).toBe("alpha");
+		expect(await read("staging/config/deep/beta.json")).toBe("beta");
+	});
+
+	test("keeps the dotfile skip in tree mode", async () => {
+		const path = await archive([
+			{
+				name: "mods/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "mods/.secret.jar",
+				content: "secret",
+			},
+			{
+				name: ".git/config.json",
+				content: "git",
+			},
+		]);
+
+		const written = await files.extract(path, "staging", {
+			tree: true,
+		});
+
+		expect(written).toEqual([
+			"staging/mods/alpha.jar",
+		]);
+	});
+
+	test("rejects absolute entries in tree mode", async () => {
+		const path = await archive([
+			{
+				name: "/etc/passwd",
+				content: "root",
+			},
+		]);
+
+		await expect(
+			files.extract(path, "staging", {
+				tree: true,
+			}),
+		).rejects.toThrow("absolute path");
+	});
+
+	test("rejects escaping entries in tree mode", async () => {
+		const path = await archive([
+			{
+				name: "overrides/../../escape.json",
+				content: "escape",
+			},
+		]);
+
+		await expect(
+			files.extract(path, "staging", {
+				tree: true,
+			}),
+		).rejects.toThrow("is not allowed");
+	});
+
+	test("rejects symlink entries in tree mode", async () => {
+		const path = await archive([
+			{
+				name: "mods/link.jar",
+				content: "/etc/passwd",
+				symlink: true,
+			},
+		]);
+
+		await expect(
+			files.extract(path, "staging", {
+				tree: true,
+			}),
+		).rejects.toThrow("symlink");
+	});
+
+	test("extracts only the selected prefix and strips it", async () => {
+		const path = await archive([
+			{
+				name: "overrides/mods/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "server-overrides/mods/beta.jar",
+				content: "beta",
+			},
+			{
+				name: "modrinth.index.json",
+				content: "{}",
+			},
+		]);
+
+		const written = await files.extract(path, "", {
+			select: "overrides",
+		});
+
+		expect(written).toEqual([
+			"alpha.jar",
+		]);
+
+		expect(await read("alpha.jar")).toBe("alpha");
+	});
+
+	test("composes select with tree", async () => {
+		const path = await archive([
+			{
+				name: "overrides/mods/alpha.jar",
+				content: "alpha",
+			},
+			{
+				name: "overrides/config/deep/beta.json",
+				content: "beta",
+			},
+			{
+				name: "modrinth.index.json",
+				content: "{}",
+			},
+		]);
+
+		const written = await files.extract(path, "", {
+			select: "overrides/",
+			tree: true,
+		});
+
+		expect(written).toEqual([
+			"mods/alpha.jar",
+			"config/deep/beta.json",
+		]);
+
+		expect(await read("config/deep/beta.json")).toBe("beta");
+	});
+
+	test("fails when nothing matches", async () => {
+		const path = await archive([
+			{
+				name: "overrides/mods/alpha.jar",
+				content: "alpha",
+			},
+		]);
+
+		await expect(
+			files.extract(path, "staging", {
+				select: "server-overrides",
+				tree: true,
+			}),
+		).rejects.toThrow("contained no matching files");
+	});
+});

package/src/runtime/bridgeFiles.ts

@@ -1,11 +1,13 @@
 import type { Dirent } from "node:fs";
 import { chown, mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
-import type { BridgeDownloadOptions, BridgeFileEntry, BridgeFiles } from "../context";
+import type { BridgeDownloadOptions, BridgeExtractOptions, BridgeFileEntry, BridgeFiles } from "../context";
 import { compileGlob } from "../utils";
+import { type BridgeEgress, BridgeEgressCallError, BridgeEgressUnavailableError } from "./bridgeEgress";
 import type { BridgeLogger } from "./bridgeLog";
+import { USER_AGENT } from "./bridgeNet";
 import { BridgePathError, resolveWithin, toSegments } from "./bridgePath";
 import { isPrivileged } from "./bridgePrivilege";
-import { readZip } from "./bridgeZip";
+import { readZip, ZIP_ENTRY_LIMIT, ZIP_TREE_ENTRY_LIMIT } from "./bridgeZip";
 
 const READ_LIMIT = 4 * 1024 * 1024;
 
@@ -21,8 +23,6 @@ const WALK_LIMIT = 4096;
 
 const MILESTONE_STEP = 25;
 
-const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
-
 const DIGEST_LENGTHS: Record<string, number> = {
 	sha1: 40,
 	sha256: 64,
@@ -33,9 +33,15 @@ export interface BridgeFilesOptions {
 	root: string;
 	uid: number;
 	gid: number;
+	egress: BridgeEgress;
 	onLog: BridgeLogger;
 }
 
+interface DownloadSource {
+	body: AsyncIterable<Uint8Array>;
+	totalBytes: number | null;
+}
+
 const parseDigest = (digest: string) => {
 	const [algo, expected] = digest.split(":");
 
@@ -87,6 +93,32 @@ const directorySize = async (path: string, depth: number): Promise<number> => {
 	return total;
 };
 
+const selectPrefix = (select: string | undefined) => {
+	if (select === undefined) {
+		return null;
+	}
+
+	const segments = toSegments(select);
+
+	return segments.length === 0 ? null : `${segments.join("/")}/`;
+};
+
+const selectedName = (name: string, prefix: string | null) => {
+	if (prefix === null) {
+		return name;
+	}
+
+	return name.startsWith(prefix) ? name.slice(prefix.length) : null;
+};
+
+const treeSegments = (name: string) => {
+	if (name.startsWith("/") || /^[A-Za-z]:/.test(name)) {
+		throw new BridgePathError("invalid", `archive entry "${name}" is an absolute path`);
+	}
+
+	return toSegments(name);
+};
+
 const walk = async (directory: string, prefix: string, depth: number, out: BridgeFileEntry[]) => {
 	if (depth > WALK_DEPTH || out.length >= WALK_LIMIT) {
 		return;
@@ -169,6 +201,49 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 		await ensureDirectory(segments.slice(0, -1).join("/"));
 	};
 
+	const openSource = async (remote: URL, downloadOptions: BridgeDownloadOptions): Promise<DownloadSource> => {
+		if (downloadOptions.cache !== false) {
+			try {
+				const shared = await options.egress.download(remote.href, {
+					digest: downloadOptions.digest,
+					sizeBytes: downloadOptions.sizeBytes,
+				});
+
+				return {
+					body: shared.body,
+					totalBytes: shared.sizeBytes > 0 ? shared.sizeBytes : (downloadOptions.sizeBytes ?? null),
+				};
+			} catch (error) {
+				if (error instanceof BridgeEgressCallError) {
+					throw new BridgePathError("missing", `${remote.host} answered ${error.status ?? error.message}`);
+				}
+
+				if (!(error instanceof BridgeEgressUnavailableError)) {
+					throw error;
+				}
+			}
+		}
+
+		const response = await fetch(remote, {
+			headers: {
+				"user-agent": USER_AGENT,
+			},
+			redirect: "error",
+			signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+		});
+
+		if (!response.ok || !response.body) {
+			throw new BridgePathError("missing", `${remote.host} answered ${response.status}`);
+		}
+
+		const declared = Number(response.headers.get("content-length"));
+
+		return {
+			body: response.body,
+			totalBytes: Number.isSafeInteger(declared) && declared > 0 ? declared : (downloadOptions.sizeBytes ?? null),
+		};
+	};
+
 	return {
 		async read(path) {
 			const resolved = await resolveWithin(options.root, path);
@@ -262,7 +337,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			const remote = new URL(url);
 
 			if (remote.protocol !== "https:") {
-				throw new BridgePathError("invalid", `url "${url}" is not https`);
+				throw new BridgePathError("invalid", `${remote.host} is not https`);
 			}
 
 			const limit = downloadOptions.sizeBytes ?? DOWNLOAD_LIMIT;
@@ -271,26 +346,14 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				throw new BridgePathError("invalid", `download of ${limit} bytes exceeds the limit`);
 			}
 
-			const response = await fetch(url, {
-				headers: {
-					"user-agent": USER_AGENT,
-				},
-				redirect: "follow",
-				signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-			});
-
-			if (!response.ok || !response.body) {
-				throw new BridgePathError("missing", `${url} answered ${response.status}`);
-			}
+			const source = await openSource(remote, downloadOptions);
 
 			await ensureParent(path);
 
 			const resolved = await resolveWithin(options.root, path);
 			const staging = `${resolved.target}.download`;
 
-			const declared = Number(response.headers.get("content-length"));
-			const totalBytes =
-				Number.isSafeInteger(declared) && declared > 0 ? declared : (downloadOptions.sizeBytes ?? null);
+			const totalBytes = source.totalBytes;
 
 			const hasher = downloadOptions.digest ? new Bun.CryptoHasher(parseDigest(downloadOptions.digest).algo) : null;
 			const writer = Bun.file(staging).writer();
@@ -305,11 +368,11 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			let milestone = 0;
 
 			try {
-				for await (const chunk of response.body) {
+				for await (const chunk of source.body) {
 					readBytes += chunk.byteLength;
 
 					if (readBytes > limit) {
-						throw new BridgePathError("invalid", `${url} returned more than ${limit} bytes`);
+						throw new BridgePathError("invalid", `${remote.host} returned more than ${limit} bytes`);
 					}
 
 					hasher?.update(chunk);
@@ -336,7 +399,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				if (downloadOptions.sizeBytes !== undefined && readBytes !== downloadOptions.sizeBytes) {
 					throw new BridgePathError(
 						"invalid",
-						`${url} returned ${readBytes} bytes, expected ${downloadOptions.sizeBytes}`,
+						`${remote.host} returned ${readBytes} bytes, expected ${downloadOptions.sizeBytes}`,
 					);
 				}
 
@@ -344,7 +407,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 					const { expected } = parseDigest(downloadOptions.digest);
 
 					if (hasher.digest("hex") !== expected) {
-						throw new BridgePathError("invalid", `${url} failed digest verification`);
+						throw new BridgePathError("invalid", `${remote.host} failed digest verification`);
 					}
 				}
 			} catch (error) {
@@ -366,7 +429,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			});
 		},
 
-		async extract(path, destination, extensions) {
+		async extract(path, destination, extractOptions: BridgeExtractOptions = {}) {
 			const resolved = await resolveWithin(options.root, path);
 
 			if (!resolved.exists || resolved.isDirectory) {
@@ -377,16 +440,32 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				throw new BridgePathError("invalid", `archive "${path}" is larger than the extract limit`);
 			}
 
-			const allowed = extensions?.map((extension) => extension.toLowerCase());
+			const tree = extractOptions.tree === true;
+			const allowed = extractOptions.extensions?.map((extension) => extension.toLowerCase());
+			const prefix = selectPrefix(extractOptions.select);
+			const base = toSegments(destination);
 			const target = await ensureDirectory(destination);
 			const buffer = Buffer.from(await Bun.file(resolved.target).arrayBuffer());
+			const directories = new Set<string>();
 			const written: string[] = [];
 
-			for (const entry of readZip(buffer)) {
-				const name = entry.name.split("/").at(-1) ?? "";
+			for (const entry of readZip(buffer, tree ? ZIP_TREE_ENTRY_LIMIT : ZIP_ENTRY_LIMIT)) {
+				const selected = selectedName(entry.name, prefix);
+
+				if (selected === null) {
+					continue;
+				}
+
+				const segments = tree
+					? treeSegments(selected)
+					: [
+							selected.split("/").at(-1) ?? "",
+						];
+
+				const name = segments.at(-1) ?? "";
 				const extension = name.split(".").at(-1)?.toLowerCase() ?? "";
 
-				if (name.length === 0 || name.startsWith(".")) {
+				if (name.length === 0 || segments.some((segment) => segment.startsWith("."))) {
 					continue;
 				}
 
@@ -394,10 +473,30 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 					continue;
 				}
 
-				const relative = toSegments(destination).length === 0 ? name : `${toSegments(destination).join("/")}/${name}`;
+				if (tree && entry.symlink) {
+					throw new BridgePathError("invalid", `archive entry "${entry.name}" is a symlink`);
+				}
+
+				const parent = segments.slice(0, -1);
+
+				if (parent.length > 0 && !directories.has(parent.join("/"))) {
+					await ensureDirectory(
+						[
+							...base,
+							...parent,
+						].join("/"),
+					);
+
+					directories.add(parent.join("/"));
+				}
+
+				const relative = [
+					...base,
+					...segments,
+				].join("/");
 
-				await Bun.write(`${target}/${name}`, entry.data);
-				await own(`${target}/${name}`);
+				await Bun.write(`${target}/${segments.join("/")}`, entry.data);
+				await own(`${target}/${segments.join("/")}`);
 
 				written.push(relative);
 			}

package/src/runtime/bridgeLog.ts

@@ -1,15 +1,38 @@
+import { BRIDGE_LOG_SOURCE } from "../protocol/bridgeLine";
+import { BridgeTerminalLevel } from "../terminal";
+
 export type BridgeLogger = (message: string, fields?: Record<string, unknown>) => void;
 
-export const log: BridgeLogger = (message, fields = {}) => {
+export interface BridgeLeveledLogger extends BridgeLogger {
+	warn: BridgeLogger;
+	error: BridgeLogger;
+}
+
+const write = (level: BridgeTerminalLevel, message: string, fields: Record<string, unknown>) => {
 	process.stdout.write(
 		`${JSON.stringify({
-			source: "bridge",
-			message,
 			...fields,
+			source: BRIDGE_LOG_SOURCE,
+			level,
+			message,
 		})}\n`,
 	);
 };
 
+export const log: BridgeLeveledLogger = Object.assign(
+	(message: string, fields: Record<string, unknown> = {}) => {
+		write(BridgeTerminalLevel.Info, message, fields);
+	},
+	{
+		warn: (message: string, fields: Record<string, unknown> = {}) => {
+			write(BridgeTerminalLevel.Warn, message, fields);
+		},
+		error: (message: string, fields: Record<string, unknown> = {}) => {
+			write(BridgeTerminalLevel.Error, message, fields);
+		},
+	},
+);
+
 export const errorText = (error: unknown) => {
 	return error instanceof Error ? error.message : String(error);
 };