@serverkgg/bridge 0.0.1

package/src/runtime/bridgeContext.ts

@@ -0,0 +1,96 @@
+import type { BridgeContext } from "../context";
+import type { BridgeValues } from "../core";
+import type { BridgeConfig } from "../protocol";
+import { createBridgeCodecs } from "./bridgeCodec";
+import { createBridgeExec } from "./bridgeExec";
+import { createBridgeFiles } from "./bridgeFiles";
+import type { BridgeLogger } from "./bridgeLog";
+import { createBridgeNet } from "./bridgeNet";
+import { createBridgeProbes } from "./bridgeProbe";
+import type { BridgeSupervisor } from "./bridgeSupervisor";
+
+export interface ContextHooks {
+	onLog: BridgeLogger;
+	onEmit: (event: string, payload?: BridgeValues) => void;
+}
+
+export const createContext = (
+	config: BridgeConfig,
+	supervisor: BridgeSupervisor,
+	hooks: ContextHooks,
+): BridgeContext => {
+	const files = createBridgeFiles({
+		root: config.cwd,
+		uid: config.gameUid,
+		gid: config.gameGid,
+		onLog: hooks.onLog,
+	});
+
+	return {
+		server: {
+			code: config.code,
+			memoryMb: config.memoryMb,
+			cpuPercent: config.cpuPercent,
+			get running() {
+				return supervisor.running;
+			},
+		},
+
+		variable(key) {
+			return config.variables[key] ?? null;
+		},
+
+		secret(key) {
+			return config.secrets[key] ?? null;
+		},
+
+		port(key) {
+			const value = config.ports[key];
+
+			if (value === undefined) {
+				throw new Error(`this game declares no port named "${key}"`);
+			}
+
+			return value;
+		},
+
+		files,
+
+		codec: createBridgeCodecs(files),
+
+		net: createBridgeNet(),
+
+		probe: createBridgeProbes(),
+
+		async command(input, options) {
+			return await supervisor.command(input, options);
+		},
+
+		exec: createBridgeExec({
+			cwd: config.cwd,
+			uid: config.gameUid,
+			gid: config.gameGid,
+		}),
+
+		logs: {
+			async tail(lines) {
+				return supervisor.tail(lines);
+			},
+
+			async watch(pattern, timeoutMs) {
+				return await supervisor.watch(pattern, timeoutMs);
+			},
+		},
+
+		emit(event, payload) {
+			hooks.onEmit(event, payload);
+		},
+
+		log(message, fields) {
+			hooks.onLog(message, {
+				driver: true,
+				...fields,
+			});
+		},
+	};
+};

package/src/runtime/bridgeDriver.ts

@@ -0,0 +1,179 @@
+import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind } from "../core";
+import type { BridgeDriver, BridgePanelModule } from "../modules";
+import { type BridgeField, BridgeFormTarget, BridgeLayout, type BridgeSection, type BridgeTab } from "../panel";
+
+const RESERVED_MODULE_IDS = new Set([
+	"backup",
+	"events",
+	"install",
+	"lifecycle",
+	"query",
+]);
+
+export class BridgeDriverError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = "BridgeDriverError";
+	}
+}
+
+const fail = (message: string): never => {
+	throw new BridgeDriverError(message);
+};
+
+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`);
+	}
+};
+
+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`);
+	}
+};
+
+const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where: string) => {
+	const module = modules[id];
+
+	if (!module) {
+		fail(`${where} references module "${id}", which the driver does not export`);
+	}
+
+	return module as BridgePanelModule;
+};
+
+const validateFields = (modules: Record<string, BridgePanelModule>, fields: BridgeField[], where: string) => {
+	const keys = new Set<string>();
+
+	for (const field of fields) {
+		if (keys.has(field.key)) {
+			fail(`${where} declares field "${field.key}" more than once`);
+		}
+
+		keys.add(field.key);
+
+		if (field.options && !Array.isArray(field.options)) {
+			const options = moduleOf(modules, field.options.module, `${where} field "${field.key}"`);
+
+			if (options.kind !== BridgeKind.Options) {
+				fail(`${where} field "${field.key}" references "${field.options.module}", which is not an options module`);
+			}
+		}
+	}
+};
+
+const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
+	switch (section.layout) {
+		case BridgeLayout.Form: {
+			if (section.target === BridgeFormTarget.Settings && !section.module) {
+				fail(`${where} targets settings but names no module`);
+
+				return;
+			}
+
+			if (section.module) {
+				const module = moduleOf(modules, section.module, where);
+
+				if (module.kind !== BridgeKind.Settings) {
+					fail(`${where} references "${section.module}", which is not a settings module`);
+				} else if (section.target === BridgeFormTarget.Settings && !module.write) {
+					fail(`${where} targets settings but module "${section.module}" has no write handler`);
+				}
+			}
+
+			validateFields(modules, section.fields, where);
+
+			return;
+		}
+
+		case BridgeLayout.Table:
+		case BridgeLayout.Cards: {
+			const module = moduleOf(modules, section.module, where);
+
+			if (module.kind !== BridgeKind.Collection) {
+				fail(`${where} references "${section.module}", which is not a collection module`);
+
+				return;
+			}
+
+			if (section.layout === BridgeLayout.Table && section.add && !module.add) {
+				fail(`${where} declares an add control but module "${section.module}" has no add handler`);
+			}
+
+			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.Catalog: {
+			const module = moduleOf(modules, section.module, where);
+
+			if (module.kind !== BridgeKind.Catalog) {
+				fail(`${where} references "${section.module}", which is not a catalog module`);
+			}
+
+			return;
+		}
+	}
+};
+
+const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab) => {
+	const sections = new Set<string>();
+
+	validateId(tab.id, "tab");
+
+	if (tab.sections.length === 0) {
+		fail(`tab "${tab.id}" has no sections`);
+	}
+
+	for (const section of tab.sections) {
+		if (sections.has(section.id)) {
+			fail(`tab "${tab.id}" declares section "${section.id}" more than once`);
+		}
+
+		sections.add(section.id);
+
+		validateId(section.id, `tab "${tab.id}" section`);
+		validateSection(modules, section, `tab "${tab.id}" section "${section.id}"`);
+	}
+};
+
+export const validateDriver = (driver: BridgeDriver) => {
+	const modules = driver.modules ?? {};
+
+	for (const [id, module] of Object.entries(modules)) {
+		validateModuleId(id, "module");
+
+		if (RESERVED_MODULE_IDS.has(id)) {
+			fail(`module id "${id}" is reserved`);
+		}
+
+		if (module.kind === BridgeKind.Collection) {
+			for (const action of Object.keys(module.actions ?? {})) {
+				validateModuleId(action, `module "${id}" action`);
+			}
+		}
+	}
+
+	if (!driver.panel) {
+		return;
+	}
+
+	const tabs = new Set<string>();
+
+	for (const tab of driver.panel.tabs) {
+		if (tabs.has(tab.id)) {
+			fail(`the panel declares tab "${tab.id}" more than once`);
+		}
+
+		tabs.add(tab.id);
+
+		validateTab(modules, tab);
+	}
+};

package/src/runtime/bridgeEvents.ts

@@ -0,0 +1,71 @@
+import type { BridgeValues } from "../core";
+import type { BridgeEventsModule } from "../modules";
+import type { BridgeEvent } from "../protocol";
+import type { BridgeSupervisor } from "./bridgeSupervisor";
+
+const EVENT_BUFFER = 500;
+
+export const createEventRing = (events: BridgeEventsModule | undefined, supervisor: BridgeSupervisor) => {
+	const ring: BridgeEvent[] = [];
+
+	let sequence = 0;
+
+	const push = (event: string, payload: BridgeValues | null) => {
+		sequence += 1;
+
+		ring.push({
+			seq: sequence,
+			event,
+			payload,
+		});
+
+		while (ring.length > EVENT_BUFFER) {
+			ring.shift();
+		}
+	};
+
+	if (events) {
+		supervisor.subscribe((entry) => {
+			for (const pattern of events.patterns) {
+				if (pattern.stream && pattern.stream !== entry.stream) {
+					continue;
+				}
+
+				const match = entry.line.match(pattern.match);
+
+				if (!match) {
+					continue;
+				}
+
+				const groups = match.groups
+					? {
+							...match.groups,
+						}
+					: null;
+
+				push(pattern.emit, groups);
+			}
+		});
+	}
+
+	return {
+		names() {
+			return [
+				...new Set((events?.patterns ?? []).map((pattern) => pattern.emit)),
+			];
+		},
+
+		emit(event: string, payload?: BridgeValues) {
+			push(event, payload ?? null);
+		},
+
+		drain(cursor: number) {
+			return {
+				events: ring.filter((entry) => entry.seq > cursor),
+				cursor: sequence,
+			};
+		},
+	};
+};
+
+export type BridgeEventRing = ReturnType<typeof createEventRing>;

package/src/runtime/bridgeExec.ts

@@ -0,0 +1,143 @@
+import type { BridgeExecOptions, BridgeExecResult } from "../context";
+import { BridgeStream } from "../core";
+import { settleUid, unprivilegedArgv } from "./bridgePrivilege";
+
+const DEFAULT_EXEC_TIMEOUT_MS = 900_000;
+
+const OUTPUT_LIMIT = 256 * 1024;
+
+const EXIT_GRACE_MS = 3000;
+
+const BASE_ENVIRONMENT = {
+	HOME: "/home/container",
+	LANG: "C.UTF-8",
+	PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+};
+
+export class BridgeExecError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = "BridgeExecError";
+	}
+}
+
+export interface BridgeExecTarget {
+	cwd: string;
+	uid: number;
+	gid: number;
+}
+
+const capped = (text: string) => {
+	return text.length > OUTPUT_LIMIT ? text.slice(0, OUTPUT_LIMIT) : text;
+};
+
+const drain = async (
+	stream: ReadableStream<Uint8Array>,
+	report: ((line: string) => void) | undefined,
+): Promise<string> => {
+	const decoder = new TextDecoder();
+
+	let collected = "";
+	let pending = "";
+
+	const emit = (line: string) => {
+		const trimmed = line.trimEnd();
+
+		if (report && trimmed.trim().length > 0) {
+			report(trimmed);
+		}
+	};
+
+	for await (const chunk of stream) {
+		const text = decoder.decode(chunk, {
+			stream: true,
+		});
+
+		if (collected.length < OUTPUT_LIMIT) {
+			collected += text;
+		}
+
+		if (!report) {
+			continue;
+		}
+
+		pending += text;
+
+		const lines = pending.split("\n");
+
+		pending = lines.pop() ?? "";
+
+		for (const line of lines) {
+			emit(line);
+		}
+	}
+
+	emit(pending);
+
+	return collected;
+};
+
+export const createBridgeExec = (target: BridgeExecTarget) => {
+	return async (command: string[], options: BridgeExecOptions = {}): Promise<BridgeExecResult> => {
+		const [executable] = command;
+		const { timeoutMs, environment, onOutput } = options;
+
+		if (!executable) {
+			throw new BridgeExecError("the exec command is empty");
+		}
+
+		const { argv } = await unprivilegedArgv(command, target.uid, target.gid);
+
+		const child = Bun.spawn(argv, {
+			cwd: target.cwd,
+			env: {
+				...BASE_ENVIRONMENT,
+				HOME: target.cwd,
+				...environment,
+			},
+			stderr: "pipe",
+			stdin: "ignore",
+			stdout: "pipe",
+		});
+
+		const observed = await settleUid(child.pid, target.uid);
+
+		if (observed !== target.uid) {
+			const finished = await Promise.race([
+				child.exited.then(() => true),
+				Bun.sleep(EXIT_GRACE_MS).then(() => false),
+			]);
+
+			if (observed !== null || !finished) {
+				child.kill("SIGKILL");
+
+				await child.exited;
+
+				const reason = observed === null ? "could not be verified" : `runs as uid ${observed}`;
+
+				throw new BridgeExecError(`the exec process ${reason}, expected uid ${target.uid} — refusing to run it`);
+			}
+		}
+
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS);
+
+		try {
+			const [stdout, stderr, code] = await Promise.all([
+				drain(child.stdout, onOutput && ((line) => onOutput(line, BridgeStream.Stdout))),
+				drain(child.stderr, onOutput && ((line) => onOutput(line, BridgeStream.Stderr))),
+				child.exited,
+			]);
+
+			return {
+				stdout: capped(stdout),
+				stderr: capped(stderr),
+				code,
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+};