@serverkgg/bridge 0.0.1

package/src/panel/bridgePanel.ts

@@ -0,0 +1,107 @@
+import type { BridgeOption, LocalizedText } from "../core";
+import type { BridgeConfirm } from "./bridgeConfirm";
+import type { BridgeControl } from "./bridgeControl";
+import type { BridgeFormTarget } from "./bridgeFormTarget";
+import type { BridgeIcon } from "./bridgeIcon";
+import type { BridgeLayout } from "./bridgeLayout";
+
+export interface BridgeVisibleWhen {
+	variable: string;
+	values: string[];
+}
+
+export interface BridgeOptionsRef {
+	module: string;
+}
+
+export interface BridgeField {
+	key: string;
+	control: BridgeControl;
+	label: LocalizedText;
+	help?: LocalizedText;
+	warning?: LocalizedText;
+	placeholder?: string;
+	min?: number;
+	max?: number;
+	step?: number;
+	maxLength?: number;
+	options?: BridgeOption[] | BridgeOptionsRef;
+	visibleWhen?: BridgeVisibleWhen;
+}
+
+export interface BridgeSectionAction {
+	id: string;
+	label: LocalizedText;
+	confirm?: BridgeConfirm;
+}
+
+export interface BridgeSectionAdd {
+	label: LocalizedText;
+	placeholder?: string;
+}
+
+export interface BridgeFormSection {
+	layout: BridgeLayout.Form;
+	id: string;
+	title?: LocalizedText;
+	target: BridgeFormTarget;
+	module?: string;
+	reinstall?: boolean;
+	restartHint?: boolean;
+	confirm?: BridgeConfirm;
+	confirmText?: LocalizedText;
+	fields: BridgeField[];
+	visibleWhen?: BridgeVisibleWhen;
+}
+
+export interface BridgeColumn {
+	key: string;
+	label: LocalizedText;
+}
+
+export interface BridgeTableSection {
+	layout: BridgeLayout.Table;
+	id: string;
+	title?: LocalizedText;
+	module: string;
+	columns: BridgeColumn[];
+	add?: BridgeSectionAdd;
+	actions?: BridgeSectionAction[];
+	empty?: LocalizedText;
+	visibleWhen?: BridgeVisibleWhen;
+}
+
+export interface BridgeCardsSection {
+	layout: BridgeLayout.Cards;
+	id: string;
+	title?: LocalizedText;
+	module: string;
+	titleKey: string;
+	subtitleKey?: string;
+	actions?: BridgeSectionAction[];
+	empty?: LocalizedText;
+	visibleWhen?: BridgeVisibleWhen;
+}
+
+export interface BridgeCatalogSection {
+	layout: BridgeLayout.Catalog;
+	id: string;
+	title?: LocalizedText;
+	module: string;
+	restartHint?: boolean;
+	empty?: LocalizedText;
+	visibleWhen?: BridgeVisibleWhen;
+}
+
+export type BridgeSection = BridgeCardsSection | BridgeCatalogSection | BridgeFormSection | BridgeTableSection;
+
+export interface BridgeTab {
+	id: string;
+	title: LocalizedText;
+	icon?: BridgeIcon;
+	sections: BridgeSection[];
+}
+
+export interface BridgePanel {
+	tabs: BridgeTab[];
+}

package/src/panel/index.ts

@@ -0,0 +1,6 @@
+export * from "./bridgeConfirm";
+export * from "./bridgeControl";
+export * from "./bridgeFormTarget";
+export * from "./bridgeIcon";
+export * from "./bridgeLayout";
+export * from "./bridgePanel";

package/src/probes/a2s.ts

@@ -0,0 +1,170 @@
+import type { BridgeA2sInfo } from "../context";
+
+const SIMPLE_PREFIX = 0xff;
+
+const INFO_HEADER = 0x49;
+
+const CHALLENGE_HEADER = 0x41;
+
+const INFO_PAYLOAD = new TextEncoder().encode("Source Engine Query\0");
+
+const DECODER = new TextDecoder();
+
+const infoRequest = (challenge: Uint8Array | null) => {
+	const request = new Uint8Array(5 + INFO_PAYLOAD.length + (challenge?.length ?? 0));
+
+	request.set([
+		SIMPLE_PREFIX,
+		SIMPLE_PREFIX,
+		SIMPLE_PREFIX,
+		SIMPLE_PREFIX,
+		0x54,
+	]);
+	request.set(INFO_PAYLOAD, 5);
+
+	if (challenge) {
+		request.set(challenge, 5 + INFO_PAYLOAD.length);
+	}
+
+	return request;
+};
+
+const readCString = (view: Uint8Array, offset: number) => {
+	let index = offset;
+
+	while (index < view.length && view[index] !== 0) {
+		index += 1;
+	}
+
+	return {
+		value: DECODER.decode(view.subarray(offset, index)),
+		next: index + 1,
+	};
+};
+
+const parseInfo = (view: Uint8Array) => {
+	const name = readCString(view, 6);
+	const map = readCString(view, name.next);
+	const folder = readCString(view, map.next);
+	const game = readCString(view, folder.next);
+
+	const offset = game.next + 2;
+
+	const online = view[offset];
+	const max = view[offset + 1];
+
+	if (online === undefined || max === undefined) {
+		throw new Error("a2s info response is truncated");
+	}
+
+	return {
+		players: {
+			online,
+			max,
+		},
+		name: name.value.length > 0 ? name.value : null,
+		map: map.value.length > 0 ? map.value : null,
+	};
+};
+
+export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
+	return new Promise<BridgeA2sInfo>((resolve, reject) => {
+		const startedAt = performance.now();
+
+		let socket: Awaited<ReturnType<typeof Bun.udpSocket>> | null = null;
+		let challenged = false;
+		let settled = false;
+
+		const finish = (outcome: Omit<BridgeA2sInfo, "latencyMs"> | Error) => {
+			if (settled) {
+				return;
+			}
+
+			settled = true;
+
+			clearTimeout(timer);
+			socket?.close();
+
+			if (outcome instanceof Error) {
+				reject(outcome);
+
+				return;
+			}
+
+			resolve({
+				...outcome,
+				latencyMs: Math.round(performance.now() - startedAt),
+			});
+		};
+
+		const timer = setTimeout(() => {
+			finish(new Error("a2s query timed out"));
+		}, timeoutMs);
+
+		const handle = (view: Uint8Array) => {
+			if (
+				view.length < 5
+				|| view[0] !== SIMPLE_PREFIX
+				|| view[1] !== SIMPLE_PREFIX
+				|| view[2] !== SIMPLE_PREFIX
+				|| view[3] !== SIMPLE_PREFIX
+			) {
+				finish(new Error("a2s response is malformed"));
+
+				return;
+			}
+
+			if (view[4] === CHALLENGE_HEADER) {
+				if (challenged || view.length < 9) {
+					finish(new Error("a2s challenge is malformed"));
+
+					return;
+				}
+
+				challenged = true;
+
+				socket?.send(infoRequest(view.slice(5, 9)));
+
+				return;
+			}
+
+			if (view[4] !== INFO_HEADER) {
+				finish(new Error("a2s response has an unexpected header"));
+
+				return;
+			}
+
+			try {
+				finish(parseInfo(view));
+			} catch (error) {
+				finish(error instanceof Error ? error : new Error(String(error)));
+			}
+		};
+
+		Bun.udpSocket({
+			connect: {
+				hostname: host,
+				port: hostPort,
+			},
+			socket: {
+				data(_socket, data) {
+					handle(data);
+				},
+			},
+		})
+			.then((created) => {
+				if (settled) {
+					created.close();
+
+					return;
+				}
+
+				socket = created;
+
+				created.send(infoRequest(null));
+			})
+			.catch((error) => {
+				finish(error instanceof Error ? error : new Error(String(error)));
+			});
+	});
+};

package/src/probes/index.ts

@@ -0,0 +1 @@
+export * from "./a2s";

package/src/protocol/bridgeConfig.ts

@@ -0,0 +1,13 @@
+export interface BridgeConfig {
+	code: string;
+	token: string;
+	cwd: string;
+	run: string;
+	ports: Record<string, number>;
+	memoryMb: number;
+	cpuPercent: number;
+	gameUid: number;
+	gameGid: number;
+	variables: Record<string, string>;
+	secrets: Record<string, string>;
+}

package/src/protocol/bridgeFrame.ts

@@ -0,0 +1,91 @@
+import type { BridgeDesired, BridgeRuntime, BridgeValues } from "../core";
+
+export const BRIDGE_SOCKET_NAME = "bridge.sock";
+
+export const BRIDGE_CONFIG_NAME = "config.json";
+
+export const BRIDGE_STATE_NAME = "state.json";
+
+export const BRIDGE_RUN_MOUNT = "/serverk/run";
+
+export const BRIDGE_FRAME_LIMIT = 1024 * 1024;
+
+export const BRIDGE_INSTALL_ERROR_LIMIT = 2048;
+
+export enum BridgeMethod {
+	Command = "command",
+	Events = "events",
+	Invoke = "invoke",
+	Manifest = "manifest",
+	Quiesce = "quiesce",
+	Release = "release",
+	Sample = "sample",
+	Start = "start",
+	Status = "status",
+	Stop = "stop",
+}
+
+export interface BridgeRequest {
+	id: number;
+	token: string;
+	method: BridgeMethod;
+	input?: string;
+	expect?: string;
+	timeoutMs?: number;
+	module?: string;
+	action?: string;
+	args?: BridgeValues;
+	cursor?: number;
+}
+
+export interface BridgeCommandResult {
+	sent: string;
+	line: string | null;
+	groups: Record<string, string>;
+}
+
+export interface BridgeSuccess {
+	id: number | null;
+	ok: true;
+	result: unknown;
+}
+
+export interface BridgeFailure {
+	id: number | null;
+	ok: false;
+	error: string;
+	secret?: string;
+}
+
+export type BridgeResponse = BridgeFailure | BridgeSuccess;
+
+export interface BridgeStatus {
+	version: string;
+	runtime: BridgeRuntime;
+	desired: BridgeDesired;
+	exitCode: number | null;
+	restarts: number;
+	installError: string | null;
+}
+
+export interface BridgeSampleResult {
+	online: number | null;
+	max: number | null;
+}
+
+export interface BridgeQuiesceResult {
+	supported: boolean;
+	quiesced: boolean;
+	settleSeconds: number;
+}
+
+export interface BridgeEvent {
+	seq: number;
+	event: string;
+	payload: BridgeValues | null;
+}
+
+export interface BridgeEventsResult {
+	events: BridgeEvent[];
+	cursor: number;
+}

package/src/protocol/bridgeLine.ts

@@ -0,0 +1,40 @@
+export const BRIDGE_LOG_SOURCE = "bridge";
+
+export interface BridgeLogLine {
+	message: string;
+	text: string;
+}
+
+export const parseBridgeLine = (line: string): BridgeLogLine | null => {
+	if (!line.startsWith("{") || !line.endsWith("}")) {
+		return null;
+	}
+
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return null;
+	}
+
+	if (typeof parsed !== "object" || parsed === null) {
+		return null;
+	}
+
+	const entry = parsed as Record<string, unknown>;
+
+	if (entry.source !== BRIDGE_LOG_SOURCE || typeof entry.message !== "string") {
+		return null;
+	}
+
+	const fields = Object.entries(entry)
+		.filter(([key]) => key !== "source" && key !== "message")
+		.map(([key, value]) => `${key}=${typeof value === "object" ? JSON.stringify(value) : String(value)}`)
+		.join(" ");
+
+	return {
+		message: entry.message,
+		text: fields.length > 0 ? `${entry.message} ${fields}` : entry.message,
+	};
+};

package/src/protocol/bridgeManifest.ts

@@ -0,0 +1,19 @@
+import type { BridgeKind } from "../core";
+import type { BridgePanel } from "../panel";
+
+export interface BridgeModuleManifest {
+	id: string;
+	kind: BridgeKind;
+	requiresRunning: boolean;
+	refreshSeconds: number | null;
+	pageSize: number | null;
+	dependsOn: string[];
+	actions: string[];
+}
+
+export interface BridgeManifest {
+	version: string;
+	panel: BridgePanel | null;
+	modules: BridgeModuleManifest[];
+	events: string[];
+}

package/src/protocol/bridgeVersion.ts

@@ -0,0 +1,11 @@
+import pkg from "../../package.json";
+
+export const BRIDGE_VERSION: string = pkg.version;
+
+export const BRIDGE_MAJOR: number = Number(BRIDGE_VERSION.split(".").at(0));
+
+if (!Number.isInteger(BRIDGE_MAJOR) || BRIDGE_MAJOR < 0) {
+	throw new Error(`the bridge version "${BRIDGE_VERSION}" has no valid major`);
+}
+
+export const BRIDGE_VERSION_LABEL = "gg.serverk.bridge.version";

package/src/protocol/index.ts

@@ -0,0 +1,7 @@
+export * from "../core";
+export * from "../panel";
+export * from "./bridgeConfig";
+export * from "./bridgeFrame";
+export * from "./bridgeLine";
+export * from "./bridgeManifest";
+export * from "./bridgeVersion";

package/src/runtime/bridgeCodec.ts

@@ -0,0 +1,78 @@
+import { mergeJson, mergeProperties, mergeUeIni, parseJson, parseProperties, parseUeIni } from "../codecs";
+import type { BridgeCodec, BridgeCodecOptions, BridgeCodecs, BridgeFiles } from "../context";
+import type { BridgeValue, BridgeValues } from "../core";
+
+const toText = (value: BridgeValue) => {
+	return value === null ? "" : String(value);
+};
+
+const toStrings = (values: BridgeValues) => {
+	const out: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(values)) {
+		out[key] = toText(value);
+	}
+
+	return out;
+};
+
+const widen = (values: Record<string, string>): BridgeValues => {
+	return values;
+};
+
+const readOr = async (files: BridgeFiles, path: string) => {
+	return (await files.exists(path)) ? await files.read(path) : "";
+};
+
+const requireTarget = (options: BridgeCodecOptions | undefined, path: string) => {
+	const section = options?.section;
+	const object = options?.object;
+
+	if (!section || !object) {
+		throw new Error(`the ue-ini codec needs "section" and "object" options to edit "${path}"`);
+	}
+
+	return {
+		section,
+		object,
+	};
+};
+
+export const createBridgeCodecs = (files: BridgeFiles): BridgeCodecs => {
+	const properties: BridgeCodec = {
+		async read(path) {
+			return widen(parseProperties(await readOr(files, path)));
+		},
+		async merge(path, values) {
+			await files.write(path, mergeProperties(await readOr(files, path), toStrings(values)));
+		},
+	};
+
+	const json: BridgeCodec = {
+		async read(path) {
+			return parseJson(await readOr(files, path));
+		},
+		async merge(path, values) {
+			await files.write(path, mergeJson(await readOr(files, path), values));
+		},
+	};
+
+	const ueIni: BridgeCodec = {
+		async read(path, options) {
+			const target = requireTarget(options, path);
+
+			return widen(parseUeIni(await readOr(files, path), target.section, target.object));
+		},
+		async merge(path, values, options) {
+			const target = requireTarget(options, path);
+
+			await files.write(path, mergeUeIni(await readOr(files, path), target.section, target.object, toStrings(values)));
+		},
+	};
+
+	return {
+		properties,
+		json,
+		ueIni,
+	};
+};

package/src/runtime/bridgeConfigReader.ts

@@ -0,0 +1,119 @@
+import {
+	BRIDGE_CONFIG_NAME,
+	BRIDGE_RUN_MOUNT,
+	BRIDGE_SOCKET_NAME,
+	BRIDGE_STATE_NAME,
+	type BridgeConfig,
+} from "../protocol";
+
+export class BridgeConfigError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = "BridgeConfigError";
+	}
+}
+
+const requireString = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (typeof value !== "string" || value.length === 0) {
+		throw new BridgeConfigError(`config field "${key}" must be a non-empty string`);
+	}
+
+	return value;
+};
+
+const requireNumber = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		throw new BridgeConfigError(`config field "${key}" must be a number`);
+	}
+
+	return value;
+};
+
+const numberRecord = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return {};
+	}
+
+	const out: Record<string, number> = {};
+
+	for (const [entryKey, entryValue] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof entryValue === "number") {
+			out[entryKey] = entryValue;
+		}
+	}
+
+	return out;
+};
+
+const stringRecord = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return {};
+	}
+
+	const out: Record<string, string> = {};
+
+	for (const [entryKey, entryValue] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof entryValue === "string") {
+			out[entryKey] = entryValue;
+		}
+	}
+
+	return out;
+};
+
+export const configPath = () => {
+	return `${BRIDGE_RUN_MOUNT}/${BRIDGE_CONFIG_NAME}`;
+};
+
+export const socketPath = (config: BridgeConfig) => {
+	return `${config.run}/${BRIDGE_SOCKET_NAME}`;
+};
+
+export const statePath = (config: BridgeConfig) => {
+	return `${config.run}/${BRIDGE_STATE_NAME}`;
+};
+
+export const readConfig = async (path: string): Promise<BridgeConfig> => {
+	const file = Bun.file(path);
+
+	if (!(await file.exists())) {
+		throw new BridgeConfigError(`no bridge config at "${path}"`);
+	}
+
+	const parsed: unknown = JSON.parse(await file.text());
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new BridgeConfigError("bridge config must be an object");
+	}
+
+	const source = parsed as Record<string, unknown>;
+
+	const config: BridgeConfig = {
+		code: requireString(source, "code"),
+		token: requireString(source, "token"),
+		cwd: requireString(source, "cwd"),
+		run: requireString(source, "run"),
+		ports: numberRecord(source, "ports"),
+		memoryMb: requireNumber(source, "memoryMb"),
+		cpuPercent: requireNumber(source, "cpuPercent"),
+		gameUid: requireNumber(source, "gameUid"),
+		gameGid: requireNumber(source, "gameGid"),
+		variables: stringRecord(source, "variables"),
+		secrets: stringRecord(source, "secrets"),
+	};
+
+	if (config.gameUid === 0 || config.gameGid === 0) {
+		throw new BridgeConfigError("the game must not run as root");
+	}
+
+	return config;
+};