@serverkgg/bridge 0.0.2 → 0.0.4

package/src/runtime/bridgeFiles.ts

@@ -1,13 +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;
 
@@ -93,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;
@@ -403,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) {
@@ -414,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;
 				}
 
@@ -431,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/bridgeRegistry.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import type { BridgeDriver } from "../modules";
+import { type BridgeConfig, BridgeEventName } from "../protocol";
+import { createContext } from "./bridgeContext";
+import { createEventRing } from "./bridgeEvents";
+import { log } from "./bridgeLog";
+import { createRegistry } from "./bridgeRegistry";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const config = (): BridgeConfig => ({
+	code: "abcdef",
+	token: "token",
+	cwd: `${tmpdir()}/serverk-registry-test`,
+	run: `${tmpdir()}/serverk-registry-test/run`,
+	ports: {},
+	memoryMb: 1024,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {},
+	secrets: {},
+});
+
+const baseDriver = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+});
+
+const registryFor = (driver: BridgeDriver) => {
+	const settings = config();
+
+	const supervisor = createSupervisor({
+		cwd: settings.cwd,
+		uid: settings.gameUid,
+		gid: settings.gameGid,
+		stopTimeoutSeconds: 1,
+		onLog: log,
+		resolveCommand: async () => [
+			"run",
+		],
+	});
+
+	const ring = createEventRing(driver.events, supervisor);
+
+	const context = createContext(settings, supervisor, {
+		onLog: log,
+		onEmit(event, payload) {
+			ring.emit(event, payload);
+		},
+	});
+
+	return createRegistry(driver, context, supervisor, ring);
+};
+
+describe("actions modules", () => {
+	test("lists its action ids in the manifest", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				gameplay: {
+					kind: BridgeKind.Actions,
+					requiresRunning: true,
+					actions: {
+						timeDay: async () => {
+							return;
+						},
+						weatherClear: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules).toEqual([
+			{
+				id: "gameplay",
+				kind: BridgeKind.Actions,
+				requiresRunning: true,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					"timeDay",
+					"weatherClear",
+				],
+			},
+		]);
+	});
+
+	test("hands the whole argument bag to the handler", async () => {
+		const received: BridgeValues[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				broadcast: {
+					kind: BridgeKind.Actions,
+					actions: {
+						say: async (_context, args) => {
+							received.push(args);
+						},
+					},
+				},
+			},
+		});
+
+		await registry.invoke("broadcast", "say", {
+			message: "hello",
+		});
+
+		expect(received).toEqual([
+			{
+				message: "hello",
+			},
+		]);
+	});
+
+	test("refuses to run while the game is stopped", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				broadcast: {
+					kind: BridgeKind.Actions,
+					requiresRunning: true,
+					actions: {
+						say: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		await expect(
+			registry.invoke("broadcast", "say", {
+				message: "hello",
+			}),
+		).rejects.toThrow('module "broadcast" needs the game to be running');
+	});
+
+	test("rejects a driver that reuses a read action id", () => {
+		expect(() =>
+			registryFor({
+				...baseDriver(),
+				modules: {
+					broadcast: {
+						kind: BridgeKind.Actions,
+						actions: {
+							list: async () => {
+								return;
+							},
+						},
+					},
+				},
+			}),
+		).toThrow('module "broadcast" declares action "list", which is reserved for reads');
+	});
+});
+
+describe("manifest events", () => {
+	test("lists the log patterns and the names the driver raises itself", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			events: {
+				kind: BridgeKind.Events,
+				patterns: [
+					{
+						match: /Fatal error/,
+						emit: BridgeEventName.ServerCrashed,
+					},
+					{
+						match: /Fatal error again/,
+						emit: BridgeEventName.ServerCrashed,
+					},
+				],
+				emits: [
+					BridgeEventName.PlayerJoined,
+					BridgeEventName.PlayerLeft,
+					BridgeEventName.ServerCrashed,
+				],
+			},
+		});
+
+		expect(registry.manifest().events).toEqual([
+			BridgeEventName.ServerCrashed,
+			BridgeEventName.PlayerJoined,
+			BridgeEventName.PlayerLeft,
+		]);
+	});
+
+	test("stays on the log patterns when the driver raises nothing itself", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			events: {
+				kind: BridgeKind.Events,
+				patterns: [
+					{
+						match: /Done/,
+						emit: BridgeEventName.ServerStarted,
+					},
+				],
+			},
+		});
+
+		expect(registry.manifest().events).toEqual([
+			BridgeEventName.ServerStarted,
+		]);
+	});
+});
+
+describe("collection row actions", () => {
+	test("passes the row and the arguments without the row id", async () => {
+		const seen: {
+			row: BridgeRow;
+			args: BridgeValues;
+		}[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [
+						{
+							id: "meslzy",
+						},
+					],
+					actions: {
+						xp: async (_context, row, args) => {
+							seen.push({
+								row,
+								args,
+							});
+						},
+					},
+				},
+			},
+		});
+
+		await registry.invoke("players", "xp", {
+			id: "meslzy",
+			amount: 30,
+		});
+
+		expect(seen).toEqual([
+			{
+				row: {
+					id: "meslzy",
+				},
+				args: {
+					amount: 30,
+				},
+			},
+		]);
+	});
+
+	test("keeps listing the built-in actions beside the row actions", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+					actions: {
+						kick: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules[0]?.actions).toEqual([
+			BridgeAction.List,
+			"kick",
+		]);
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -1,5 +1,5 @@
 import type { BridgeContext } from "../context";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
 import type { BridgeDriver, BridgePanelModule, BridgeTerminalModule } from "../modules";
 import {
 	BRIDGE_VERSION,
@@ -7,6 +7,7 @@ import {
 	type BridgeModuleManifest,
 	type BridgeTerminalManifest,
 } from "../protocol";
+import { actionsOf } from "./bridgeActions";
 import { BridgeDriverError } from "./bridgeDriver";
 import type { BridgeEventRing } from "./bridgeEvents";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
@@ -16,55 +17,12 @@ interface CacheEntry {
 	expiresAt: number;
 }
 
-const actionsOf = (module: BridgePanelModule) => {
-	switch (module.kind) {
-		case BridgeKind.Options: {
-			return [
-				BridgeAction.List,
-			];
-		}
-
-		case BridgeKind.Settings: {
-			return [
-				BridgeAction.Read,
-				...(module.write
-					? [
-							BridgeAction.Write,
-						]
-					: []),
-			];
-		}
-
-		case BridgeKind.Collection: {
-			return [
-				BridgeAction.List,
-				...(module.add
-					? [
-							BridgeAction.Add,
-						]
-					: []),
-				...Object.keys(module.actions ?? {}),
-			];
-		}
-
-		case BridgeKind.Catalog: {
-			return [
-				BridgeAction.Install,
-				BridgeAction.Installed,
-				BridgeAction.Remove,
-				BridgeAction.Search,
-				...(module.toggle
-					? [
-							BridgeAction.Toggle,
-						]
-					: []),
-			];
-		}
+const requiresRunning = (module: BridgePanelModule) => {
+	if (module.kind === BridgeKind.Actions || module.kind === BridgeKind.Collection) {
+		return module.requiresRunning ?? false;
 	}
-};
 
-const requiresRunning = (module: BridgePanelModule) => {
-	return module.kind === BridgeKind.Collection ? (module.requiresRunning ?? false) : false;
+	return false;
 };
 
 const refreshOf = (module: BridgePanelModule) => {
@@ -151,6 +109,18 @@ const asOptional = (args: BridgeValues, key: string) => {
 	return typeof value === "string" && value.length > 0 ? value : null;
 };
 
+const withoutId = (args: BridgeValues) => {
+	const rest: BridgeValues = {};
+
+	for (const [key, value] of Object.entries(args)) {
+		if (key !== "id") {
+			rest[key] = value;
+		}
+	}
+
+	return rest;
+};
+
 const asPage = (args: BridgeValues) => {
 	const value = args.page;
 
@@ -167,6 +137,20 @@ export const createRegistry = (
 	const inflight = new Map<string, Promise<unknown>>();
 	const modules = driver.modules ?? {};
 
+	for (const [id, module] of Object.entries(modules)) {
+		if (module.kind !== BridgeKind.Actions) {
+			continue;
+		}
+
+		for (const action of Object.keys(module.actions)) {
+			if (isReadAction(action)) {
+				throw new BridgeDriverError(
+					`module "${id}" declares action "${action}", which is reserved for reads — pick another id`,
+				);
+			}
+		}
+	}
+
 	const cached = async (key: string, ttlSeconds: number | undefined, run: () => Promise<unknown>) => {
 		if (!ttlSeconds) {
 			return await run();
@@ -207,6 +191,18 @@ export const createRegistry = (
 
 	const dispatch = async (module: BridgePanelModule, name: string, action: string, args: BridgeValues) => {
 		switch (module.kind) {
+			case BridgeKind.Actions: {
+				const serverAction = module.actions[action];
+
+				if (serverAction) {
+					await serverAction(context, args);
+
+					return null;
+				}
+
+				break;
+			}
+
 			case BridgeKind.Options: {
 				if (action === BridgeAction.List) {
 					const overlay: Record<string, string> = {};
@@ -268,7 +264,7 @@ export const createRegistry = (
 						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);
 					}
 
-					await rowAction(context, row as BridgeRow);
+					await rowAction(context, row as BridgeRow, withoutId(args));
 
 					return null;
 				}
@@ -352,5 +348,3 @@ export const createRegistry = (
 		},
 	};
 };
-
-export type BridgeRegistry = ReturnType<typeof createRegistry>;

package/src/runtime/bridgeServer.ts

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeFailureError, BridgeSecretError, type BridgeValues, type LocalizedText } from "../core";
+import { BridgeFailureError, BridgeSecretError, type BridgeValues } from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
 	type BridgeAnnounceResult,
@@ -29,7 +29,7 @@ export interface ServerOptions {
 	onQuiesce: () => Promise<BridgeQuiesceResult>;
 	onRelease: () => Promise<void>;
 	onDescribe: () => Promise<BridgeDescribeResult>;
-	onAnnounce: (message: LocalizedText) => Promise<BridgeAnnounceResult>;
+	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
 	onLog: BridgeLogger;
 }
 
@@ -47,21 +47,8 @@ interface IncomingFrame {
 	message?: unknown;
 }
 
-const asMessage = (value: unknown): LocalizedText | null => {
-	if (value === null || typeof value !== "object") {
-		return null;
-	}
-
-	const { ar, en } = value as Record<string, unknown>;
-
-	if (typeof ar !== "string" || typeof en !== "string") {
-		return null;
-	}
-
-	return {
-		ar,
-		en,
-	};
+const asMessage = (value: unknown): string | null => {
+	return typeof value === "string" && value.length > 0 ? value : null;
 };
 
 const matches = (left: string, right: string) => {
@@ -152,7 +139,7 @@ export const createServer = (options: ServerOptions) => {
 				const message = asMessage(request.message);
 
 				if (!message) {
-					throw new Error("announce needs a message with ar and en text");
+					throw new Error("announce needs a message");
 				}
 
 				return await options.onAnnounce(message);
@@ -276,5 +263,3 @@ export const createServer = (options: ServerOptions) => {
 		},
 	});
 };
-
-export type BridgeSocketServer = ReturnType<typeof createServer>;

package/src/runtime/bridgeZip.ts

@@ -18,13 +18,20 @@ const DEFLATED = 8;
 
 const ENCRYPTED_FLAG = 0x1;
 
-const MAX_ENTRIES = 2048;
+export const ZIP_ENTRY_LIMIT = 2048;
+
+export const ZIP_TREE_ENTRY_LIMIT = 8192;
 
 const MAX_ENTRY_BYTES = 128 * 1024 * 1024;
 
+const UNIX_MODE_FORMAT_MASK = 0xf0_00;
+
+const UNIX_MODE_SYMLINK = 0xa0_00;
+
 export interface ZipEntry {
 	name: string;
 	data: Uint8Array;
+	symlink: boolean;
 }
 
 const findEndOfCentralDirectory = (buffer: Buffer) => {
@@ -39,7 +46,7 @@ const findEndOfCentralDirectory = (buffer: Buffer) => {
 	return -1;
 };
 
-export const readZip = (buffer: Buffer): ZipEntry[] => {
+export const readZip = (buffer: Buffer, maxEntries: number = ZIP_ENTRY_LIMIT): ZipEntry[] => {
 	const eocd = findEndOfCentralDirectory(buffer);
 
 	if (eocd === -1) {
@@ -49,7 +56,7 @@ export const readZip = (buffer: Buffer): ZipEntry[] => {
 	const total = buffer.readUInt16LE(eocd + 10);
 	const directoryOffset = buffer.readUInt32LE(eocd + 16);
 
-	if (total > MAX_ENTRIES) {
+	if (total > maxEntries) {
 		throw new Error(`archive has too many entries (${total})`);
 	}
 
@@ -69,8 +76,10 @@ export const readZip = (buffer: Buffer): ZipEntry[] => {
 		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;
 
 		cursor += 46 + nameLength + extraLength + commentLength;
 
@@ -95,6 +104,7 @@ export const readZip = (buffer: Buffer): ZipEntry[] => {
 			entries.push({
 				name,
 				data: compressed,
+				symlink,
 			});
 
 			continue;
@@ -115,6 +125,7 @@ export const readZip = (buffer: Buffer): ZipEntry[] => {
 		entries.push({
 			name,
 			data,
+			symlink,
 		});
 	}