@serverkgg/bridge 0.0.8 → 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/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, {

package/src/runtime/bridgeServer.test.ts

@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BridgeDesired, BridgeFailureCode, BridgeFailureError, BridgeRuntime, BridgeUserError } from "../core";
+import { BridgeMethod, type BridgePendingResult, type BridgeResponse } from "../protocol";
+import { createServer, type ServerOptions } from "./bridgeServer";
+
+const TOKEN = "test-token";
+
+const unreachable = (what: string) => {
+	return () => {
+		throw new Error(`${what} is not part of this test`);
+	};
+};
+
+const baseOptions = (socket: string): ServerOptions => ({
+	socket,
+	token: TOKEN,
+	onStatus: () => ({
+		version: "0.0.0",
+		runtime: BridgeRuntime.Stopped,
+		desired: BridgeDesired.Stopped,
+		exitCode: null,
+		outOfMemory: false,
+		restarts: 0,
+		installError: null,
+		installHold: null,
+	}),
+	onManifest: unreachable("manifest"),
+	onStart: unreachable("start"),
+	onStop: unreachable("stop"),
+	onCommand: unreachable("command"),
+	onInvoke: unreachable("invoke"),
+	onEvents: unreachable("events"),
+	onSample: unreachable("sample"),
+	onQuiesce: unreachable("quiesce"),
+	onRelease: unreachable("release"),
+	onDescribe: unreachable("describe"),
+	onAnnounce: unreachable("announce"),
+	onPendingList: unreachable("pendingList"),
+	onPendingAdd: unreachable("pendingAdd"),
+	onLog: () => {
+		return;
+	},
+});
+
+const call = async (socket: string, frame: Record<string, unknown>): Promise<BridgeResponse> => {
+	return await new Promise<BridgeResponse>((resolve, reject) => {
+		void Bun.connect<{
+			buffer: string;
+		}>({
+			unix: socket,
+			socket: {
+				open(connection) {
+					connection.data = {
+						buffer: "",
+					};
+
+					connection.write(`${JSON.stringify(frame)}\n`);
+				},
+
+				data(connection, chunk) {
+					connection.data.buffer += chunk.toString();
+
+					const [line] = connection.data.buffer.split("\n");
+
+					if (!line) {
+						return;
+					}
+
+					connection.end();
+
+					resolve(JSON.parse(line) as BridgeResponse);
+				},
+
+				error(_connection, error) {
+					reject(error);
+				},
+			},
+		}).catch(reject);
+	});
+};
+
+describe("pending dispatch", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const listed: BridgePendingResult = {
+		supported: true,
+		staging: ".serverk-staging/pending-upload",
+		extensions: [
+			"jar",
+		],
+		files: [],
+		rejected: null,
+	};
+
+	test("answers pendingList with what the driver lists", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingList: async () => listed,
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.PendingList,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 1,
+			ok: true,
+			result: listed,
+		});
+	});
+
+	test("answers pendingList with the unsupported sentinel when the driver declares no pending module", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingList: async () => ({
+				supported: false,
+				staging: "",
+				extensions: [],
+				files: [],
+				rejected: null,
+			}),
+		});
+
+		const response = await call(socket, {
+			id: 2,
+			token: TOKEN,
+			method: BridgeMethod.PendingList,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 2,
+			ok: true,
+			result: {
+				supported: false,
+				staging: "",
+				extensions: [],
+				files: [],
+				rejected: null,
+			},
+		});
+	});
+
+	test("passes the uploaded path to pendingAdd and answers with the refreshed list", async () => {
+		const received: string[] = [];
+
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async (input) => {
+				received.push(input);
+
+				return listed;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 3,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/patch.jar",
+		});
+
+		server.stop(true);
+
+		expect(received).toEqual([
+			".serverk-staging/pending-upload/patch.jar",
+		]);
+		expect(response).toEqual({
+			id: 3,
+			ok: true,
+			result: listed,
+		});
+	});
+
+	test("refuses a pendingAdd carrying no path", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: unreachable("pendingAdd"),
+		});
+
+		const response = await call(socket, {
+			id: 4,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 4,
+			ok: false,
+			error: "pendingAdd needs an input path",
+		});
+	});
+
+	test("answers pendingAdd with the rejection the driver reported beside the refreshed list", async () => {
+		const rejected: BridgePendingResult = {
+			...listed,
+			rejected: {
+				expected: [
+					"patch.jar",
+				],
+			},
+		};
+
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async () => rejected,
+		});
+
+		const response = await call(socket, {
+			id: 6,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/wrong.jar",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 6,
+			ok: true,
+			result: rejected,
+		});
+	});
+
+	test("names an unknown method so an older agent can degrade", async () => {
+		const server = createServer(baseOptions(socket));
+
+		const response = await call(socket, {
+			id: 5,
+			token: TOKEN,
+			method: "pendingRemove",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 5,
+			ok: false,
+			error: 'unknown method "pendingRemove"',
+		});
+	});
+});
+
+describe("error serialisation", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const thrown = async (error: unknown) => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async () => {
+				throw error;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/patch.jar",
+		});
+
+		server.stop(true);
+
+		return response;
+	};
+
+	test("carries the localized text of a user error beside the message", async () => {
+		expect(
+			await thrown(
+				new BridgeUserError({
+					ar: "هذا مو الملف اللي ننتظره",
+					en: "this is not a file we are waiting for",
+				}),
+			),
+		).toEqual({
+			id: 1,
+			ok: false,
+			error: "this is not a file we are waiting for",
+			text: {
+				ar: "هذا مو الملف اللي ننتظره",
+				en: "this is not a file we are waiting for",
+			},
+		});
+	});
+
+	test("carries the failure code of a failure error and no text", async () => {
+		expect(await thrown(new BridgeFailureError(BridgeFailureCode.CatalogRestricted, "the author blocked it"))).toEqual({
+			id: 1,
+			ok: false,
+			error: "the author blocked it",
+			failure: BridgeFailureCode.CatalogRestricted,
+		});
+	});
+
+	test("carries the message alone for an ordinary error", async () => {
+		expect(await thrown(new Error("the file could not be read"))).toEqual({
+			id: 1,
+			ok: false,
+			error: "the file could not be read",
+		});
+	});
+});