@serverkgg/bridge 0.0.12 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.12",
+	"version": "0.0.14",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -24,6 +24,14 @@
 		"./blog": "./src/blog/index.ts",
 		"./probes": "./src/probes/index.ts",
 		"./wire": "./src/wire/index.ts",
+		"./catalogs": "./src/catalogs/index.ts",
+		"./install": "./src/install/index.ts",
+		"./net": "./src/net/index.ts",
+		"./presence": "./src/presence/index.ts",
+		"./rcon": "./src/rcon/index.ts",
+		"./steam": "./src/steam/index.ts",
+		"./utils": "./src/utils/index.ts",
+		"./wine": "./src/wine/index.ts",
 		"./package.json": "./package.json"
 	},
 	"scripts": {

package/src/catalogs/curseforge.test.ts

@@ -0,0 +1,580 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeContext, BridgeRequestOptions } from "../context";
+import { BridgeFailureCode, BridgeFailureError, BridgeNetError, BridgeSecretError } from "../core";
+import { BridgeHttpMethod } from "../protocol";
+import {
+	CURSEFORGE_API,
+	CURSEFORGE_DOWNLOAD,
+	CURSEFORGE_SECRET,
+	type CurseforgeCatalogOptions,
+	type CurseforgeFile,
+	CurseforgeHash,
+	CurseforgeReleaseType,
+	CurseforgeSort,
+	CurseforgeSortOrder,
+	createCurseforgeCatalog,
+	curseforgeDownloadUrl,
+	curseforgeFallbackUrl,
+	curseforgeSha1,
+	isCurseforgeServerFile,
+	selectCurseforgeFile,
+} from "./curseforge";
+
+const file = (overrides: Partial<CurseforgeFile> = {}): CurseforgeFile => {
+	return {
+		id: 1,
+		modId: 10,
+		fileName: "mod.jar",
+		displayName: "mod",
+		downloadUrl: "https://edge.forgecdn.net/files/4711/12/mod.jar",
+		fileLength: 100,
+		fileDate: null,
+		isAvailable: true,
+		releaseType: CurseforgeReleaseType.Release,
+		gameVersions: [],
+		hashes: [],
+		dependencies: [],
+		...overrides,
+	};
+};
+
+describe("curseforgeSha1", () => {
+	test("finds the sha1 hash and lowercases it", () => {
+		expect(
+			curseforgeSha1(
+				file({
+					hashes: [
+						{
+							value: "AABB",
+							algo: CurseforgeHash.Sha1,
+						},
+						{
+							value: "ccdd",
+							algo: CurseforgeHash.Md5,
+						},
+					],
+				}),
+			),
+		).toBe("aabb");
+	});
+
+	test("returns null when the file carries no sha1", () => {
+		expect(curseforgeSha1(file())).toBeNull();
+	});
+});
+
+describe("curseforgeDownloadUrl", () => {
+	test("re-encodes the path of a curseforge cdn url", () => {
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: "https://edge.forgecdn.net/files/4711/12/my mod.jar",
+				}),
+			),
+		).toBe("https://edge.forgecdn.net/files/4711/12/my%20mod.jar");
+	});
+
+	test("refuses a url that is not on the curseforge cdn", () => {
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: "https://evil.test/files/mod.jar",
+				}),
+			),
+		).toBeNull();
+	});
+
+	test("keeps a name curseforge already escaped escaped once", () => {
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: "https://edge.forgecdn.net/files/1234/567/Some%20Mod%20%5B1.20%5D.jar",
+				}),
+			),
+		).toBe("https://edge.forgecdn.net/files/1234/567/Some%20Mod%20%5B1.20%5D.jar");
+	});
+
+	test("refuses a path carrying a broken escape", () => {
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: "https://edge.forgecdn.net/files/1234/567/100% complete.jar",
+				}),
+			),
+		).toBeNull();
+	});
+
+	test("refuses plain http and a missing url", () => {
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: "http://edge.forgecdn.net/files/1/2/mod.jar",
+				}),
+			),
+		).toBeNull();
+		expect(
+			curseforgeDownloadUrl(
+				file({
+					downloadUrl: null,
+				}),
+			),
+		).toBeNull();
+	});
+});
+
+describe("curseforgeFallbackUrl", () => {
+	test("splits a modern file id into four and the rest", () => {
+		expect(curseforgeFallbackUrl(4_711_123, "mod.jar")).toBe(`${CURSEFORGE_DOWNLOAD}/files/4711/123/mod.jar`);
+	});
+
+	test("divides a legacy file id by a thousand", () => {
+		expect(curseforgeFallbackUrl(123_456, "mod.jar")).toBe(`${CURSEFORGE_DOWNLOAD}/files/123/123456/mod.jar`);
+	});
+
+	test("percent encodes a file name carrying spaces and brackets", () => {
+		expect(curseforgeFallbackUrl(4_711_123, "Butchersdelight beta 1.20.1 2.1.0.jar")).toBe(
+			`${CURSEFORGE_DOWNLOAD}/files/4711/123/Butchersdelight%20beta%201.20.1%202.1.0.jar`,
+		);
+		expect(curseforgeFallbackUrl(4_711_123, "Some Mod [1.20].jar")).toBe(
+			`${CURSEFORGE_DOWNLOAD}/files/4711/123/Some%20Mod%20%5B1.20%5D.jar`,
+		);
+	});
+});
+
+describe("isCurseforgeServerFile", () => {
+	test("accepts a file tagged server", () => {
+		expect(
+			isCurseforgeServerFile(
+				file({
+					gameVersions: [
+						"Client",
+						"Server",
+					],
+				}),
+			),
+		).toBe(true);
+	});
+
+	test("refuses a file tagged client only", () => {
+		expect(
+			isCurseforgeServerFile(
+				file({
+					gameVersions: [
+						"Client",
+					],
+				}),
+			),
+		).toBe(false);
+	});
+
+	test("accepts a file with no side tag", () => {
+		expect(
+			isCurseforgeServerFile(
+				file({
+					gameVersions: [
+						"1.21",
+					],
+				}),
+			),
+		).toBe(true);
+	});
+
+	test("reads the side tags whatever their casing", () => {
+		expect(
+			isCurseforgeServerFile(
+				file({
+					gameVersions: [
+						"client",
+						"server",
+					],
+				}),
+			),
+		).toBe(true);
+		expect(
+			isCurseforgeServerFile(
+				file({
+					gameVersions: [
+						"client",
+					],
+				}),
+			),
+		).toBe(false);
+	});
+});
+
+describe("selectCurseforgeFile", () => {
+	test("returns null when nothing is available", () => {
+		expect(
+			selectCurseforgeFile([
+				file({
+					isAvailable: false,
+				}),
+			]),
+		).toBeNull();
+		expect(selectCurseforgeFile([])).toBeNull();
+	});
+
+	test("prefers the newest file", () => {
+		expect(
+			selectCurseforgeFile([
+				file({
+					id: 1,
+				}),
+				file({
+					id: 9,
+				}),
+				file({
+					id: 5,
+				}),
+			])?.id,
+		).toBe(9);
+	});
+
+	test("prefers a file matching the game version", () => {
+		expect(
+			selectCurseforgeFile(
+				[
+					file({
+						id: 9,
+						gameVersions: [
+							"1.20",
+						],
+					}),
+					file({
+						id: 2,
+						gameVersions: [
+							"1.21",
+						],
+					}),
+				],
+				{
+					gameVersion: "1.21",
+				},
+			)?.id,
+		).toBe(2);
+	});
+
+	test("falls back to the newest when the game version is nowhere", () => {
+		expect(
+			selectCurseforgeFile(
+				[
+					file({
+						id: 9,
+						gameVersions: [
+							"1.20",
+						],
+					}),
+				],
+				{
+					gameVersion: "1.99",
+				},
+			)?.id,
+		).toBe(9);
+	});
+
+	test("keeps stable releases when asked and falls back when there are none", () => {
+		const files = [
+			file({
+				id: 9,
+				releaseType: CurseforgeReleaseType.Alpha,
+			}),
+			file({
+				id: 3,
+				releaseType: CurseforgeReleaseType.Release,
+			}),
+		];
+
+		expect(
+			selectCurseforgeFile(files, {
+				stableOnly: true,
+			})?.id,
+		).toBe(3);
+		expect(
+			selectCurseforgeFile(
+				[
+					files[0] ?? file(),
+				],
+				{
+					stableOnly: true,
+				},
+			)?.id,
+		).toBe(9);
+	});
+
+	test("drops client-only files when asked for a server file", () => {
+		expect(
+			selectCurseforgeFile(
+				[
+					file({
+						id: 9,
+						gameVersions: [
+							"Client",
+						],
+					}),
+					file({
+						id: 3,
+						gameVersions: [
+							"Server",
+						],
+					}),
+				],
+				{
+					serverOnly: true,
+				},
+			)?.id,
+		).toBe(3);
+	});
+});
+
+interface CatalogCall {
+	url: string;
+	cacheSeconds: number | undefined;
+	headers: Record<string, string> | undefined;
+	httpMethod: BridgeHttpMethod | undefined;
+	body: string | undefined;
+}
+
+const catalogContext = (
+	overrides: { key?: string | null; result?: unknown; fail?: Error; options?: Partial<CurseforgeCatalogOptions> } = {},
+) => {
+	const calls: CatalogCall[] = [];
+	const key = overrides.key === undefined ? "test-key" : overrides.key;
+
+	const context = {
+		secret(name: string) {
+			return name === CURSEFORGE_SECRET ? key : null;
+		},
+		net: {
+			async json(url: string, options: BridgeRequestOptions = {}) {
+				calls.push({
+					url,
+					cacheSeconds: options.cacheSeconds,
+					headers: options.headers,
+					httpMethod: options.httpMethod,
+					body: options.body,
+				});
+
+				if (overrides.fail) {
+					throw overrides.fail;
+				}
+
+				return (
+					overrides.result ?? {
+						data: [],
+					}
+				);
+			},
+		},
+	} as unknown as BridgeContext;
+
+	return {
+		calls,
+		catalog: createCurseforgeCatalog(context, {
+			gameId: 432,
+			...overrides.options,
+		}),
+	};
+};
+
+const searchParams = (calls: CatalogCall[], index = 0) => {
+	return new URL(calls[index]?.url ?? "https://curseforge.test").searchParams;
+};
+
+const batchIds = (calls: CatalogCall[], index: number) => {
+	const parsed: unknown = JSON.parse(calls[index]?.body ?? "null");
+
+	if (typeof parsed !== "object" || parsed === null || !("fileIds" in parsed)) {
+		return [];
+	}
+
+	const ids = (parsed as Record<string, unknown>).fileIds;
+
+	return Array.isArray(ids) ? (ids as number[]) : [];
+};
+
+describe("createCurseforgeCatalog", () => {
+	test("sends the key as a header and the search cache window", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search();
+
+		expect(calls[0]?.headers).toEqual({
+			"x-api-key": "test-key",
+		});
+		expect(calls[0]?.cacheSeconds).toBe(60);
+		expect(searchParams(calls).get("gameId")).toBe("432");
+	});
+
+	test("leaves the sort order out when no sort is asked for", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search();
+
+		expect(searchParams(calls).has("sortOrder")).toBe(false);
+	});
+
+	test("sorts a popularity search descending", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search({
+			sort: CurseforgeSort.Popularity,
+		});
+
+		expect(searchParams(calls).get("sortField")).toBe(CurseforgeSort.Popularity);
+		expect(searchParams(calls).get("sortOrder")).toBe(CurseforgeSortOrder.Desc);
+	});
+
+	test("sorts a name search ascending", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search({
+			sort: CurseforgeSort.Name,
+		});
+
+		expect(searchParams(calls).get("sortOrder")).toBe(CurseforgeSortOrder.Asc);
+	});
+
+	test("sorts an author search ascending", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search({
+			sort: CurseforgeSort.Author,
+		});
+
+		expect(searchParams(calls).get("sortOrder")).toBe(CurseforgeSortOrder.Asc);
+	});
+
+	test("keeps an explicit sort order", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search({
+			sort: CurseforgeSort.Name,
+			sortOrder: CurseforgeSortOrder.Desc,
+		});
+
+		expect(searchParams(calls).get("sortOrder")).toBe(CurseforgeSortOrder.Desc);
+	});
+
+	test("drops empty and absent filters but keeps a zero index", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.search({
+			query: "",
+			gameVersion: "",
+			index: 0,
+		});
+
+		const params = searchParams(calls);
+
+		expect(params.has("searchFilter")).toBe(false);
+		expect(params.has("gameVersion")).toBe(false);
+		expect(params.has("classId")).toBe(false);
+		expect(params.get("index")).toBe("0");
+	});
+
+	test("asks for the files of a mod without a query string", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.modFiles(4711);
+
+		expect(calls[0]?.url).toBe(`${CURSEFORGE_API}/mods/4711/files`);
+	});
+
+	test("passes every mod file filter through", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.modFiles(4711, {
+			gameVersion: "1.21",
+			modLoaderType: 4,
+			index: 0,
+			pageSize: 50,
+		});
+
+		const params = searchParams(calls);
+
+		expect(params.get("gameVersion")).toBe("1.21");
+		expect(params.get("modLoaderType")).toBe("4");
+		expect(params.get("index")).toBe("0");
+		expect(params.get("pageSize")).toBe("50");
+	});
+
+	test("caches categories for a day rather than for the project window", async () => {
+		const { catalog, calls } = catalogContext({
+			options: {
+				projectCacheSeconds: 5,
+			},
+		});
+
+		await catalog.categories(6);
+
+		expect(calls[0]?.cacheSeconds).toBe(86_400);
+		expect(searchParams(calls).get("classId")).toBe("6");
+	});
+
+	test("dedupes, sorts and batches file ids into posted bodies", async () => {
+		const { catalog, calls } = catalogContext();
+
+		await catalog.files([
+			...Array.from({
+				length: 150,
+			}).map((_, index) => 150 - index),
+			150,
+		]);
+
+		expect(calls).toHaveLength(2);
+		expect(calls[0]?.httpMethod).toBe(BridgeHttpMethod.Post);
+		expect(calls[0]?.url).toBe(`${CURSEFORGE_API}/mods/files`);
+
+		const first = batchIds(calls, 0);
+		const second = batchIds(calls, 1);
+
+		expect(first).toHaveLength(100);
+		expect(first.at(0)).toBe(1);
+		expect(first.at(-1)).toBe(100);
+		expect(second).toHaveLength(50);
+		expect(second.at(0)).toBe(101);
+		expect(second.at(-1)).toBe(150);
+	});
+
+	test("refuses to work without a key", async () => {
+		const { catalog, calls } = catalogContext({
+			key: null,
+		});
+
+		expect(catalog.ready()).toBe(false);
+		await expect(catalog.search()).rejects.toBeInstanceOf(BridgeSecretError);
+		expect(calls).toHaveLength(0);
+	});
+
+	test("turns a rejected key into a secret error", async () => {
+		for (const status of [
+			401,
+			403,
+		]) {
+			const { catalog } = catalogContext({
+				fail: new BridgeNetError(status, "denied"),
+			});
+
+			await expect(catalog.search()).rejects.toBeInstanceOf(BridgeSecretError);
+		}
+	});
+
+	test("turns throttling into a rate limited failure", async () => {
+		for (const status of [
+			429,
+			503,
+		]) {
+			const { catalog } = catalogContext({
+				fail: new BridgeNetError(status, "slow down"),
+			});
+
+			const failure = await catalog.search().then(
+				() => null,
+				(error: unknown) => error,
+			);
+
+			expect(failure).toBeInstanceOf(BridgeFailureError);
+			expect(failure instanceof BridgeFailureError ? failure.code : null).toBe(BridgeFailureCode.CatalogRateLimited);
+		}
+	});
+});