@serverkgg/bridge 0.0.7 → 0.0.9

package/src/runtime/bridgePending.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { BRIDGE_PENDING_FILES_LIMIT, type BridgePendingFile } from "../protocol";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
+
+const file = (id: string): BridgePendingFile => ({
+	id,
+	title: {
+		ar: id,
+		en: id,
+	},
+	fileName: `${id}.jar`,
+	sizeBytes: null,
+	digest: null,
+	sourceUrl: null,
+	note: null,
+});
+
+const files = (count: number) => {
+	return Array.from({
+		length: count,
+	}).map((_entry, index) => file(`file-${index}`));
+};
+
+const recorder = () => {
+	const warnings: string[] = [];
+
+	const onLog: BridgeLeveledLogger = Object.assign(
+		() => {
+			return;
+		},
+		{
+			warn: (message: string) => {
+				warnings.push(message);
+			},
+			error: () => {
+				return;
+			},
+		},
+	);
+
+	return {
+		onLog,
+		warnings,
+	};
+};
+
+describe("unsupportedPending", () => {
+	test("answers the sentinel a driver without a pending module gets", () => {
+		expect(unsupportedPending()).toEqual({
+			supported: false,
+			staging: "",
+			extensions: [],
+			files: [],
+			rejected: null,
+		});
+	});
+});
+
+describe("pendingResult", () => {
+	test("carries the staging path, the extensions and the files the driver listed", () => {
+		const { onLog, warnings } = recorder();
+
+		expect(
+			pendingResult(
+				".serverk-staging/pending-upload",
+				[
+					"jar",
+				],
+				files(2),
+				onLog,
+			),
+		).toEqual({
+			supported: true,
+			staging: ".serverk-staging/pending-upload",
+			extensions: [
+				"jar",
+			],
+			files: files(2),
+			rejected: null,
+		});
+
+		expect(warnings).toEqual([]);
+	});
+
+	test("truncates a list longer than the platform takes and warns instead of throwing", () => {
+		const { onLog, warnings } = recorder();
+
+		const result = pendingResult(
+			".serverk-staging/pending-upload",
+			[
+				"jar",
+			],
+			files(BRIDGE_PENDING_FILES_LIMIT + 5),
+			onLog,
+		);
+
+		expect(result.files).toHaveLength(BRIDGE_PENDING_FILES_LIMIT);
+		expect(result.files.at(0)?.id).toBe("file-0");
+		expect(warnings).toEqual([
+			"pending list truncated",
+		]);
+	});
+});
+
+describe("rejectedPending", () => {
+	test("names every file still pending as what the upload was expected to be", () => {
+		const { onLog } = recorder();
+
+		const result = rejectedPending(
+			pendingResult(
+				".serverk-staging/pending-upload",
+				[
+					"jar",
+				],
+				files(2),
+				onLog,
+			),
+		);
+
+		expect(result.rejected).toEqual({
+			expected: [
+				"file-0.jar",
+				"file-1.jar",
+			],
+		});
+		expect(result.files).toHaveLength(2);
+	});
+
+	test("leaves an empty expectation when the driver has nothing pending left", () => {
+		const { onLog } = recorder();
+
+		expect(
+			rejectedPending(
+				pendingResult(
+					".serverk-staging/pending-upload",
+					[
+						"jar",
+					],
+					[],
+					onLog,
+				),
+			).rejected,
+		).toEqual({
+			expected: [],
+		});
+	});
+});

package/src/runtime/bridgePending.ts

@@ -0,0 +1,43 @@
+import { BRIDGE_PENDING_FILES_LIMIT, type BridgePendingFile, type BridgePendingResult } from "../protocol";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+
+export const unsupportedPending = (): BridgePendingResult => {
+	return {
+		supported: false,
+		staging: "",
+		extensions: [],
+		files: [],
+		rejected: null,
+	};
+};
+
+export const pendingResult = (
+	staging: string,
+	extensions: string[],
+	files: BridgePendingFile[],
+	onLog: BridgeLeveledLogger,
+): BridgePendingResult => {
+	if (files.length > BRIDGE_PENDING_FILES_LIMIT) {
+		onLog.warn("pending list truncated", {
+			files: files.length,
+			limit: BRIDGE_PENDING_FILES_LIMIT,
+		});
+	}
+
+	return {
+		supported: true,
+		staging,
+		extensions,
+		files: files.slice(0, BRIDGE_PENDING_FILES_LIMIT),
+		rejected: null,
+	};
+};
+
+export const rejectedPending = (result: BridgePendingResult): BridgePendingResult => {
+	return {
+		...result,
+		rejected: {
+			expected: result.files.map((file) => file.fileName),
+		},
+	};
+};

package/src/runtime/bridgePrivilege.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, spyOn } from "bun:test";
+import { privilegePlan, readEffectiveUid, setprivArgv, spawnCredentials } from "./bridgePrivilege";
+
+const COMMAND = [
+	"java",
+	"-jar",
+	"server.jar",
+];
+
+describe("spawnCredentials", () => {
+	it("carries the uid and gid for the spawn options", () => {
+		expect(spawnCredentials(1000, 1000)).toEqual({
+			uid: 1000,
+			gid: 1000,
+		});
+	});
+});
+
+describe("setprivArgv", () => {
+	afterEach(() => {
+		spyOn(Bun, "which").mockRestore();
+	});
+
+	it("wraps the command with a full privilege drop", () => {
+		spyOn(Bun, "which").mockReturnValue("/usr/bin/setpriv");
+
+		expect(setprivArgv(COMMAND, 1000, 1000)).toEqual([
+			"setpriv",
+			"--reuid=1000",
+			"--regid=1000",
+			"--clear-groups",
+			"--",
+			...COMMAND,
+		]);
+	});
+
+	it("refuses to build a wrapper the image cannot run", () => {
+		spyOn(Bun, "which").mockReturnValue(null);
+
+		expect(() => setprivArgv(COMMAND, 1000, 1000)).toThrow("setpriv is missing");
+	});
+});
+
+describe("privilegePlan", () => {
+	afterEach(() => {
+		spyOn(Bun, "which").mockRestore();
+	});
+
+	it("passes credentials to the runtime when the spawn uid option is honoured", () => {
+		const plan = privilegePlan(true, COMMAND, 1000, 1000);
+
+		expect(plan.argv, "a native runtime must run the bare command").toEqual(COMMAND);
+		expect(plan.credentials, "the drop must ride the spawn options or the game runs as root").toEqual({
+			uid: 1000,
+			gid: 1000,
+		});
+	});
+
+	it("falls back to setpriv with no spawn credentials otherwise", () => {
+		spyOn(Bun, "which").mockReturnValue("/usr/bin/setpriv");
+
+		const plan = privilegePlan(false, COMMAND, 1000, 1000);
+
+		expect(plan.argv.at(0), "the wrapper must lead the argv").toBe("setpriv");
+		expect(plan.credentials, "credentials on a setpriv wrapper would fail the spawn").toEqual({});
+	});
+});
+
+describe("readEffectiveUid", () => {
+	it("reads this process's own effective uid", async () => {
+		expect(await readEffectiveUid(process.pid)).toBe(process.getuid?.() ?? 0);
+	});
+
+	it("answers null for a pid that does not exist", async () => {
+		expect(await readEffectiveUid(2 ** 22 - 1)).toBeNull();
+	});
+});

package/src/runtime/bridgePrivilege.ts

@@ -91,11 +91,13 @@ export const setprivArgv = (command: string[], uid: number, gid: number) => {
 	];
 };
 
-export const unprivilegedArgv = async (command: string[], uid: number, gid: number) => {
-	const native = await probeNativeUid(uid, gid);
-
+export const privilegePlan = (native: boolean, command: string[], uid: number, gid: number) => {
 	return {
 		argv: native ? command : setprivArgv(command, uid, gid),
 		credentials: native ? spawnCredentials(uid, gid) : {},
 	};
 };
+
+export const unprivilegedArgv = async (command: string[], uid: number, gid: number) => {
+	return privilegePlan(await probeNativeUid(uid, gid), command, uid, gid);
+};

package/src/runtime/bridgeRegistry.test.ts

@@ -426,3 +426,137 @@ describe("preview modules", () => {
 		);
 	});
 });
+
+describe("detail modules", () => {
+	test("lists read and its own action ids in the manifest", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+					actions: {
+						update: async () => null,
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules).toEqual([
+			{
+				id: "modpackStatus",
+				kind: BridgeKind.Detail,
+				requiresRunning: false,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					BridgeAction.Read,
+					"update",
+				],
+			},
+		]);
+	});
+
+	test("returns what read answers", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => ({
+						id: "modrinth:abc",
+						title: "Better MC",
+						subtitle: "1.21.1 · NeoForge",
+						description: null,
+						image: null,
+						badges: [],
+						stats: [],
+						links: [],
+						stale: false,
+						actions: [],
+					}),
+				},
+			},
+		});
+
+		expect(await registry.invoke("modpackStatus", BridgeAction.Read)).toMatchObject({
+			id: "modrinth:abc",
+			title: "Better MC",
+		});
+	});
+
+	test("hands the argument bag to an action and returns its outcome", async () => {
+		const received: BridgeValues[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+					actions: {
+						update: async (_context, args) => {
+							received.push(args);
+
+							return {
+								variables: {
+									MODPACK: "modrinth:abc:v2",
+								},
+							};
+						},
+					},
+				},
+			},
+		});
+
+		expect(
+			await registry.invoke("modpackStatus", "update", {
+				id: "modrinth:abc",
+			}),
+		).toEqual({
+			variables: {
+				MODPACK: "modrinth:abc:v2",
+			},
+		});
+
+		expect(received).toEqual([
+			{
+				id: "modrinth:abc",
+			},
+		]);
+	});
+
+	test("refuses an action named after a read", () => {
+		expect(() =>
+			registryFor({
+				...baseDriver(),
+				modules: {
+					modpackStatus: {
+						kind: BridgeKind.Detail,
+						read: async () => null,
+						actions: {
+							read: async () => null,
+						},
+					},
+				},
+			}),
+		).toThrow('module "modpackStatus" declares action "read", which is reserved for reads');
+	});
+
+	test("refuses an action the module does not answer", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+				},
+			},
+		});
+
+		await expect(registry.invoke("modpackStatus", "update")).rejects.toThrow(
+			'module "modpackStatus" does not support "update"',
+		);
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -18,7 +18,11 @@ interface CacheEntry {
 }
 
 const requiresRunning = (module: BridgePanelModule) => {
-	if (module.kind === BridgeKind.Actions || module.kind === BridgeKind.Collection) {
+	if (
+		module.kind === BridgeKind.Actions
+		|| module.kind === BridgeKind.Collection
+		|| module.kind === BridgeKind.Detail
+	) {
 		return module.requiresRunning ?? false;
 	}
 
@@ -26,7 +30,11 @@ const requiresRunning = (module: BridgePanelModule) => {
 };
 
 const refreshOf = (module: BridgePanelModule) => {
-	return module.kind === BridgeKind.Collection ? (module.refreshSeconds ?? null) : null;
+	if (module.kind === BridgeKind.Collection || module.kind === BridgeKind.Detail) {
+		return module.refreshSeconds ?? null;
+	}
+
+	return null;
 };
 
 const dependsOf = (module: BridgePanelModule) => {
@@ -138,11 +146,11 @@ export const createRegistry = (
 	const modules = driver.modules ?? {};
 
 	for (const [id, module] of Object.entries(modules)) {
-		if (module.kind !== BridgeKind.Actions) {
+		if (module.kind !== BridgeKind.Actions && module.kind !== BridgeKind.Detail) {
 			continue;
 		}
 
-		for (const action of Object.keys(module.actions)) {
+		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`,
@@ -290,6 +298,20 @@ export const createRegistry = (
 				break;
 			}
 
+			case BridgeKind.Detail: {
+				if (action === BridgeAction.Read) {
+					return await module.read(context);
+				}
+
+				const detailAction = module.actions?.[action];
+
+				if (detailAction) {
+					return await detailAction(context, args);
+				}
+
+				break;
+			}
+
 			case BridgeKind.Catalog: {
 				if (action === BridgeAction.Search) {
 					return await module.search(context, {