@serverkgg/bridge 0.0.2 → 0.0.4

package/src/runtime/bridgeDriver.ts

@@ -1,6 +1,38 @@
-import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind } from "../core";
+import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind, type LocalizedText } from "../core";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
-import { type BridgeField, BridgeFormTarget, BridgeLayout, type BridgeSection, type BridgeTab } from "../panel";
+import {
+	type BridgeField,
+	BridgeFormTarget,
+	BridgeLayout,
+	type BridgeSection,
+	type BridgeSectionAction,
+	type BridgeTab,
+	type BridgeVisibleWhen,
+} from "../panel";
+import {
+	BRIDGE_ACTION_FIELDS_LIMIT,
+	BRIDGE_DEPENDS_ON_LIMIT,
+	BRIDGE_EVENTS_LIMIT,
+	BRIDGE_EXTENSION_LENGTH_LIMIT,
+	BRIDGE_FIELD_OPTIONS_LIMIT,
+	BRIDGE_FORM_FIELDS_LIMIT,
+	BRIDGE_ID_LENGTH_LIMIT,
+	BRIDGE_KEY_LENGTH_LIMIT,
+	BRIDGE_MODULE_ACTIONS_LIMIT,
+	BRIDGE_MODULES_LIMIT,
+	BRIDGE_OPTION_VALUE_LENGTH_LIMIT,
+	BRIDGE_PANEL_TABS_LIMIT,
+	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
+	BRIDGE_ROW_ACTIONS_LIMIT,
+	BRIDGE_SECTION_ACTIONS_LIMIT,
+	BRIDGE_STAGING_LENGTH_LIMIT,
+	BRIDGE_TAB_SECTIONS_LIMIT,
+	BRIDGE_TABLE_COLUMNS_LIMIT,
+	BRIDGE_TEXT_LENGTH_LIMIT,
+	BRIDGE_UPLOAD_EXTENSIONS_LIMIT,
+	BRIDGE_VISIBLE_VALUES_LIMIT,
+} from "../protocol";
+import { actionsOf } from "./bridgeActions";
 
 const RESERVED_MODULE_IDS = new Set([
 	"announce",
@@ -23,16 +55,45 @@ const fail = (message: string): never => {
 	throw new BridgeDriverError(message);
 };
 
+const countIn = (count: number, limit: number, what: string, where: string) => {
+	if (count > limit) {
+		fail(`${where} declares ${count} ${what} — the platform takes at most ${limit}`);
+	}
+};
+
+const lengthIn = (value: string, limit: number, what: string, where: string) => {
+	if (value.length > limit) {
+		fail(`${where} ${what} is ${value.length} characters — the platform takes at most ${limit}`);
+	}
+};
+
 const validateId = (id: string, where: string) => {
 	if (!BRIDGE_ID_PATTERN.test(id)) {
 		fail(`${where} id "${id}" must be kebab-case — lowercase letters, digits, and dashes, starting with a letter`);
 	}
+
+	lengthIn(id, BRIDGE_ID_LENGTH_LIMIT, `id "${id}"`, where);
 };
 
 const validateModuleId = (id: string, where: string) => {
 	if (!BRIDGE_MODULE_ID_PATTERN.test(id)) {
 		fail(`${where} id "${id}" must be camelCase — letters and digits, starting with a lowercase letter`);
 	}
+
+	lengthIn(id, BRIDGE_ID_LENGTH_LIMIT, `id "${id}"`, where);
+};
+
+const validateText = (text: LocalizedText | undefined, what: string, where: string) => {
+	if (!text) {
+		return;
+	}
+
+	if (text.ar.length === 0 || text.en.length === 0) {
+		fail(`${where} ${what} needs both arabic and english text`);
+	}
+
+	lengthIn(text.ar, BRIDGE_TEXT_LENGTH_LIMIT, `${what} arabic text`, where);
+	lengthIn(text.en, BRIDGE_TEXT_LENGTH_LIMIT, `${what} english text`, where);
 };
 
 const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where: string) => {
@@ -45,6 +106,18 @@ const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where:
 	return module as BridgePanelModule;
 };
 
+const validateVisibleWhen = (visibleWhen: BridgeVisibleWhen | undefined, where: string) => {
+	if (!visibleWhen) {
+		return;
+	}
+
+	if (visibleWhen.empty === undefined && (visibleWhen.values ?? []).length === 0) {
+		fail(`${where} is visible when "${visibleWhen.variable}" matches nothing — declare values, empty, or both`);
+	}
+
+	countIn((visibleWhen.values ?? []).length, BRIDGE_VISIBLE_VALUES_LIMIT, "visible values", where);
+};
+
 const validateFields = (modules: Record<string, BridgePanelModule>, fields: BridgeField[], where: string) => {
 	const keys = new Set<string>();
 
@@ -55,18 +128,98 @@ const validateFields = (modules: Record<string, BridgePanelModule>, fields: Brid
 
 		keys.add(field.key);
 
+		const at = `${where} field "${field.key}"`;
+
+		lengthIn(field.key, BRIDGE_KEY_LENGTH_LIMIT, `key "${field.key}"`, where);
+		validateText(field.label, "label", at);
+		validateText(field.help, "help", at);
+		validateText(field.warning, "warning", at);
+		validateVisibleWhen(field.visibleWhen, at);
+
+		if (field.placeholder) {
+			lengthIn(field.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "placeholder", at);
+		}
+
+		if (Array.isArray(field.options)) {
+			countIn(field.options.length, BRIDGE_FIELD_OPTIONS_LIMIT, "options", at);
+
+			for (const option of field.options) {
+				lengthIn(option.value, BRIDGE_OPTION_VALUE_LENGTH_LIMIT, `option "${option.value}"`, at);
+				validateText(option.label, `option "${option.value}" label`, at);
+				validateText(option.help, `option "${option.value}" help`, at);
+			}
+		}
+
 		if (field.options && !Array.isArray(field.options)) {
-			const options = moduleOf(modules, field.options.module, `${where} field "${field.key}"`);
+			const options = moduleOf(modules, field.options.module, at);
 
 			if (options.kind !== BridgeKind.Options) {
-				fail(`${where} field "${field.key}" references "${field.options.module}", which is not an options module`);
+				fail(`${at} references "${field.options.module}", which is not an options module`);
 			}
 		}
 	}
 };
 
+const validateActions = (modules: Record<string, BridgePanelModule>, actions: BridgeSectionAction[], where: string) => {
+	const ids = new Set<string>();
+
+	for (const action of actions) {
+		if (ids.has(action.id)) {
+			fail(`${where} declares action "${action.id}" more than once`);
+		}
+
+		ids.add(action.id);
+
+		const at = `${where} action "${action.id}"`;
+		const fields = action.fields ?? [];
+
+		lengthIn(action.id, BRIDGE_KEY_LENGTH_LIMIT, `id "${action.id}"`, where);
+		validateText(action.label, "label", at);
+		validateText(action.confirmText, "confirm text", at);
+
+		if (fields.length > BRIDGE_ACTION_FIELDS_LIMIT) {
+			fail(`${at} declares ${fields.length} fields — at most ${BRIDGE_ACTION_FIELDS_LIMIT} fit one prompt`);
+		}
+
+		validateFields(modules, fields, at);
+	}
+};
+
 const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
+	validateVisibleWhen(section.visibleWhen, where);
+	validateText(section.title, "title", where);
+
+	if (section.layout !== BridgeLayout.Form) {
+		validateText(section.layout === BridgeLayout.Actions ? section.help : section.empty, "text", where);
+	}
+
 	switch (section.layout) {
+		case BridgeLayout.Actions: {
+			const module = moduleOf(modules, section.module, where);
+
+			if (module.kind !== BridgeKind.Actions) {
+				fail(`${where} references "${section.module}", which is not an actions module`);
+
+				return;
+			}
+
+			if (section.actions.length === 0) {
+				fail(`${where} declares no actions`);
+			}
+
+			countIn(section.actions.length, BRIDGE_SECTION_ACTIONS_LIMIT, "actions", where);
+
+			validateActions(modules, section.actions, where);
+
+			for (const action of section.actions) {
+				if (!module.actions[action.id]) {
+					fail(`${where} declares action "${action.id}", which module "${section.module}" does not implement`);
+				}
+			}
+
+			return;
+		}
+
 		case BridgeLayout.Form: {
 			if (section.target === BridgeFormTarget.Settings && !section.module) {
 				fail(`${where} targets settings but names no module`);
@@ -84,6 +237,13 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				}
 			}
 
+			validateText(section.confirmText, "confirm text", where);
+
+			if (section.fields.length === 0) {
+				fail(`${where} declares no fields`);
+			}
+
+			countIn(section.fields.length, BRIDGE_FORM_FIELDS_LIMIT, "fields", where);
 			validateFields(modules, section.fields, where);
 
 			return;
@@ -99,11 +259,58 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				return;
 			}
 
-			if (section.layout === BridgeLayout.Table && section.add && !module.add) {
-				fail(`${where} declares an add control but module "${section.module}" has no add handler`);
+			if (section.layout === BridgeLayout.Table) {
+				if (section.add && !module.add) {
+					fail(`${where} declares an add control but module "${section.module}" has no add handler`);
+				}
+
+				if (section.upload && !module.add) {
+					fail(`${where} declares an upload control but module "${section.module}" has no add handler`);
+				}
+
+				if (section.columns.length === 0) {
+					fail(`${where} declares no columns`);
+				}
+
+				countIn(section.columns.length, BRIDGE_TABLE_COLUMNS_LIMIT, "columns", where);
+
+				for (const column of section.columns) {
+					lengthIn(column.key, BRIDGE_KEY_LENGTH_LIMIT, `column key "${column.key}"`, where);
+					validateText(column.label, `column "${column.key}" label`, where);
+				}
+
+				if (section.add) {
+					validateText(section.add.label, "add label", where);
+
+					if (section.add.placeholder) {
+						lengthIn(section.add.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "add placeholder", where);
+					}
+				}
+
+				if (section.upload) {
+					validateText(section.upload.label, "upload label", where);
+					lengthIn(section.upload.staging, BRIDGE_STAGING_LENGTH_LIMIT, "upload staging path", where);
+
+					if (section.upload.extensions.length === 0) {
+						fail(`${where} declares an upload control with no extensions`);
+					}
+
+					countIn(section.upload.extensions.length, BRIDGE_UPLOAD_EXTENSIONS_LIMIT, "upload extensions", where);
+
+					for (const extension of section.upload.extensions) {
+						lengthIn(extension, BRIDGE_EXTENSION_LENGTH_LIMIT, `upload extension "${extension}"`, where);
+					}
+				}
 			}
 
+			countIn((section.actions ?? []).length, BRIDGE_ROW_ACTIONS_LIMIT, "actions", where);
+			validateActions(modules, section.actions ?? [], where);
+
 			for (const action of section.actions ?? []) {
+				if (action.download) {
+					continue;
+				}
+
 				if (!module.actions?.[action.id]) {
 					fail(`${where} declares action "${action.id}", which module "${section.module}" does not implement`);
 				}
@@ -119,6 +326,8 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				fail(`${where} references "${section.module}", which is not a catalog module`);
 			}
 
+			validateText(section.confirmText, "confirm text", where);
+
 			return;
 		}
 	}
@@ -128,11 +337,14 @@ const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab)
 	const sections = new Set<string>();
 
 	validateId(tab.id, "tab");
+	validateText(tab.title, "title", `tab "${tab.id}"`);
 
 	if (tab.sections.length === 0) {
 		fail(`tab "${tab.id}" has no sections`);
 	}
 
+	countIn(tab.sections.length, BRIDGE_TAB_SECTIONS_LIMIT, "sections", `tab "${tab.id}"`);
+
 	for (const section of tab.sections) {
 		if (sections.has(section.id)) {
 			fail(`tab "${tab.id}" declares section "${section.id}" more than once`);
@@ -148,6 +360,15 @@ const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab)
 export const validateDriver = (driver: BridgeDriver) => {
 	const modules = driver.modules ?? {};
 
+	countIn(Object.keys(modules).length, BRIDGE_MODULES_LIMIT, "panel modules", "the driver");
+
+	const emitted = new Set([
+		...(driver.events?.patterns ?? []).map((pattern) => pattern.emit),
+		...(driver.events?.emits ?? []),
+	]);
+
+	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
+
 	for (const [id, module] of Object.entries(modules)) {
 		validateModuleId(id, "module");
 
@@ -155,6 +376,18 @@ export const validateDriver = (driver: BridgeDriver) => {
 			fail(`module id "${id}" is reserved`);
 		}
 
+		countIn(actionsOf(module).length, BRIDGE_MODULE_ACTIONS_LIMIT, "actions", `module "${id}"`);
+
+		if (module.kind === BridgeKind.Options) {
+			countIn((module.dependsOn ?? []).length, BRIDGE_DEPENDS_ON_LIMIT, "dependencies", `module "${id}"`);
+		}
+
+		if (module.kind === BridgeKind.Actions) {
+			for (const action of Object.keys(module.actions)) {
+				validateModuleId(action, `module "${id}" action`);
+			}
+		}
+
 		if (module.kind === BridgeKind.Collection) {
 			for (const action of Object.keys(module.actions ?? {})) {
 				validateModuleId(action, `module "${id}" action`);
@@ -166,6 +399,12 @@ export const validateDriver = (driver: BridgeDriver) => {
 		return;
 	}
 
+	if (driver.panel.tabs.length === 0) {
+		fail("the panel declares no tabs");
+	}
+
+	countIn(driver.panel.tabs.length, BRIDGE_PANEL_TABS_LIMIT, "tabs", "the panel");
+
 	const tabs = new Set<string>();
 
 	for (const tab of driver.panel.tabs) {

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/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");
+	});
+});