@serverkgg/bridge 0.0.1

package/src/codecs/ueIni.ts

@@ -0,0 +1,235 @@
+interface TupleEntry {
+	key: string;
+	value: string;
+	quoted: boolean;
+}
+
+const BARE_VALUE = /^-?\d+(?:\.\d+)?$|^(?:True|False)$|^[A-Za-z0-9_.-]+$/;
+
+const isSectionHeader = (line: string) => {
+	const trimmed = line.trim();
+
+	return trimmed.startsWith("[") && trimmed.endsWith("]");
+};
+
+const sectionName = (line: string) => {
+	return line.trim().slice(1, -1);
+};
+
+const splitTuple = (tuple: string) => {
+	const parts: string[] = [];
+
+	let depth = 0;
+	let quoted = false;
+	let current = "";
+
+	for (let index = 0; index < tuple.length; index++) {
+		const character = tuple[index];
+
+		if (character === '"' && tuple[index - 1] !== "\\") {
+			quoted = !quoted;
+		}
+
+		if (!quoted) {
+			if (character === "(") {
+				depth++;
+			}
+
+			if (character === ")") {
+				depth--;
+			}
+
+			if (character === "," && depth === 0) {
+				parts.push(current);
+				current = "";
+
+				continue;
+			}
+		}
+
+		current += character;
+	}
+
+	if (current.trim().length > 0) {
+		parts.push(current);
+	}
+
+	return parts;
+};
+
+const toEntry = (part: string): TupleEntry | null => {
+	const separator = part.indexOf("=");
+
+	if (separator === -1) {
+		return null;
+	}
+
+	const key = part.slice(0, separator).trim();
+	const raw = part.slice(separator + 1).trim();
+
+	if (key.length === 0) {
+		return null;
+	}
+
+	if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+		return {
+			key,
+			value: raw.slice(1, -1).replaceAll('\\"', '"'),
+			quoted: true,
+		};
+	}
+
+	return {
+		key,
+		value: raw,
+		quoted: false,
+	};
+};
+
+const fromEntry = (entry: TupleEntry) => {
+	if (entry.quoted) {
+		return `${entry.key}="${entry.value.replaceAll('"', '\\"')}"`;
+	}
+
+	return `${entry.key}=${entry.value}`;
+};
+
+const normalizeRead = (entry: TupleEntry) => {
+	if (!entry.quoted && (entry.value === "True" || entry.value === "False")) {
+		return entry.value.toLowerCase();
+	}
+
+	return entry.value;
+};
+
+const normalizeWrite = (value: string, quoted: boolean) => {
+	if (!quoted && (value === "true" || value === "false")) {
+		return value === "true" ? "True" : "False";
+	}
+
+	return value;
+};
+
+const parseEntries = (contents: string, section: string, object: string) => {
+	const lines = contents.split("\n");
+	const prefix = `${object}=`;
+
+	let inSection = false;
+
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index] ?? "";
+
+		if (isSectionHeader(line)) {
+			inSection = sectionName(line) === section;
+
+			continue;
+		}
+
+		if (!inSection) {
+			continue;
+		}
+
+		const trimmed = line.trim();
+
+		if (!trimmed.startsWith(prefix)) {
+			continue;
+		}
+
+		const raw = trimmed.slice(prefix.length).trim();
+		const tuple = raw.startsWith("(") && raw.endsWith(")") ? raw.slice(1, -1) : raw;
+
+		const entries: TupleEntry[] = [];
+
+		for (const part of splitTuple(tuple)) {
+			const entry = toEntry(part);
+
+			if (entry) {
+				entries.push(entry);
+			}
+		}
+
+		return {
+			entries,
+			lineIndex: index,
+		};
+	}
+
+	return {
+		entries: [] as TupleEntry[],
+		lineIndex: -1,
+	};
+};
+
+export const parseUeIni = (contents: string, section: string, object: string) => {
+	const values: Record<string, string> = {};
+
+	for (const entry of parseEntries(contents, section, object).entries) {
+		values[entry.key] = normalizeRead(entry);
+	}
+
+	return values;
+};
+
+export const mergeUeIni = (contents: string, section: string, object: string, values: Record<string, string>) => {
+	const pending = new Map(Object.entries(values));
+	const parsed = parseEntries(contents, section, object);
+
+	const entries = parsed.entries.map((entry) => {
+		const value = pending.get(entry.key);
+
+		if (value === undefined) {
+			return entry;
+		}
+
+		pending.delete(entry.key);
+
+		return {
+			...entry,
+			value: normalizeWrite(value, entry.quoted),
+		};
+	});
+
+	for (const [key, value] of pending) {
+		const quoted = !BARE_VALUE.test(value);
+
+		entries.push({
+			key,
+			value: normalizeWrite(value, quoted),
+			quoted,
+		});
+	}
+
+	const objectLine = `${object}=(${entries.map(fromEntry).join(",")})`;
+
+	if (parsed.lineIndex !== -1) {
+		const lines = contents.split("\n");
+
+		lines[parsed.lineIndex] = objectLine;
+
+		return lines.join("\n");
+	}
+
+	const lines = contents.length === 0 ? [] : contents.split("\n");
+
+	while (lines.length > 0 && lines.at(-1)?.length === 0) {
+		lines.pop();
+	}
+
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index] ?? "";
+
+		if (isSectionHeader(line) && sectionName(line) === section) {
+			lines.splice(index + 1, 0, objectLine);
+
+			return `${lines.join("\n")}\n`;
+		}
+	}
+
+	if (lines.length > 0) {
+		lines.push("");
+	}
+
+	lines.push(`[${section}]`, objectLine);
+
+	return `${lines.join("\n")}\n`;
+};

package/src/context/bridgeContext.ts

@@ -0,0 +1,120 @@
+import type { BridgeStream, BridgeValues } from "../core";
+
+export interface BridgeServer {
+	code: string;
+	memoryMb: number;
+	cpuPercent: number;
+	running: boolean;
+}
+
+export interface BridgeFileEntry {
+	path: string;
+	name: string;
+	directory: boolean;
+	sizeBytes: number;
+	modifiedAt: string;
+}
+
+export interface BridgeDownloadOptions {
+	digest?: string;
+	sizeBytes?: number;
+}
+
+export interface BridgeFiles {
+	read(path: string): Promise<string>;
+	write(path: string, content: string): Promise<void>;
+	list(glob: string): Promise<BridgeFileEntry[]>;
+	remove(path: string): Promise<void>;
+	move(from: string, to: string): Promise<void>;
+	ensure(...paths: string[]): Promise<void>;
+	exists(path: string): Promise<boolean>;
+	size(path: string): Promise<number>;
+	download(path: string, url: string, options?: BridgeDownloadOptions): Promise<void>;
+	extract(path: string, destination: string, extensions?: string[]): Promise<string[]>;
+}
+
+export interface BridgeCodecOptions {
+	section?: string;
+	object?: string;
+}
+
+export interface BridgeCodec {
+	read(path: string, options?: BridgeCodecOptions): Promise<BridgeValues>;
+	merge(path: string, values: BridgeValues, options?: BridgeCodecOptions): Promise<void>;
+}
+
+export interface BridgeCodecs {
+	json: BridgeCodec;
+	properties: BridgeCodec;
+	ueIni: BridgeCodec;
+}
+
+export interface BridgeRequestOptions {
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+}
+
+export interface BridgeNet {
+	json<Result>(url: string, options?: BridgeRequestOptions): Promise<Result>;
+	text(url: string, options?: BridgeRequestOptions): Promise<string>;
+}
+
+export interface BridgePingPlayers {
+	online: number;
+	max: number;
+}
+
+export interface BridgeA2sInfo {
+	players: BridgePingPlayers;
+	name: string | null;
+	map: string | null;
+	latencyMs: number;
+}
+
+export interface BridgeProbes {
+	a2s(port: number): Promise<BridgeA2sInfo>;
+}
+
+export interface BridgeCommandOptions {
+	expect?: RegExp;
+	timeoutMs?: number;
+}
+
+export interface BridgeReply {
+	sent: string;
+	line: string | null;
+	groups: Record<string, string>;
+}
+
+export interface BridgeExecOptions {
+	timeoutMs?: number;
+	environment?: Record<string, string>;
+	onOutput?(line: string, stream: BridgeStream): void;
+}
+
+export interface BridgeExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+}
+
+export interface BridgeLogs {
+	tail(lines: number): Promise<string[]>;
+	watch(pattern: RegExp, timeoutMs: number): Promise<RegExpMatchArray | null>;
+}
+
+export interface BridgeContext {
+	readonly server: BridgeServer;
+	variable(key: string): string | null;
+	secret(key: string): string | null;
+	port(key: string): number;
+	files: BridgeFiles;
+	codec: BridgeCodecs;
+	net: BridgeNet;
+	probe: BridgeProbes;
+	command(input: string, options?: BridgeCommandOptions): Promise<BridgeReply>;
+	exec(command: string[], options?: BridgeExecOptions): Promise<BridgeExecResult>;
+	logs: BridgeLogs;
+	emit(event: string, payload?: BridgeValues): void;
+	log(message: string, fields?: BridgeValues): void;
+}

package/src/context/index.ts

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

package/src/core/bridgeAction.ts

@@ -0,0 +1,13 @@
+export enum BridgeAction {
+	Add = "add",
+	Install = "install",
+	Installed = "installed",
+	List = "list",
+	Quiesce = "quiesce",
+	Read = "read",
+	Release = "release",
+	Remove = "remove",
+	Sample = "sample",
+	Search = "search",
+	Write = "write",
+}

package/src/core/bridgeId.ts

@@ -0,0 +1,3 @@
+export const BRIDGE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export const BRIDGE_MODULE_ID_PATTERN = /^[a-z][a-zA-Z0-9]*$/;

package/src/core/bridgeKind.ts

@@ -0,0 +1,11 @@
+export enum BridgeKind {
+	Backup = "backup",
+	Catalog = "catalog",
+	Collection = "collection",
+	Events = "events",
+	Install = "install",
+	Lifecycle = "lifecycle",
+	Options = "options",
+	Query = "query",
+	Settings = "settings",
+}

package/src/core/bridgePort.ts

@@ -0,0 +1,4 @@
+export enum PortProtocol {
+	Tcp = "tcp",
+	Udp = "udp",
+}

package/src/core/bridgeRuntime.ts

@@ -0,0 +1,13 @@
+export enum BridgeRuntime {
+	Crashed = "crashed",
+	Installing = "installing",
+	Running = "running",
+	Starting = "starting",
+	Stopped = "stopped",
+	Stopping = "stopping",
+}
+
+export enum BridgeDesired {
+	Running = "running",
+	Stopped = "stopped",
+}

package/src/core/bridgeSecretError.ts

@@ -0,0 +1,10 @@
+export class BridgeSecretError extends Error {
+	readonly key: string;
+
+	constructor(key: string, message: string) {
+		super(message);
+
+		this.name = "BridgeSecretError";
+		this.key = key;
+	}
+}

package/src/core/bridgeStream.ts

@@ -0,0 +1,4 @@
+export enum BridgeStream {
+	Stderr = "stderr",
+	Stdout = "stdout",
+}

package/src/core/bridgeValue.ts

@@ -0,0 +1,19 @@
+export type BridgeValue = boolean | number | string | null;
+
+export type BridgeValues = Record<string, BridgeValue>;
+
+export type BridgeRow = BridgeValues & {
+	id: string;
+};
+
+export interface LocalizedText {
+	ar: string;
+	en: string;
+}
+
+export interface BridgeOption {
+	value: string;
+	label: LocalizedText;
+	help?: LocalizedText;
+	latest?: boolean;
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export * from "./bridgeAction";
+export * from "./bridgeId";
+export * from "./bridgeKind";
+export * from "./bridgePort";
+export * from "./bridgeRuntime";
+export * from "./bridgeSecretError";
+export * from "./bridgeStream";
+export * from "./bridgeValue";

package/src/main.ts

@@ -0,0 +1,5 @@
+export * from "./context";
+export * from "./core";
+export * from "./modules";
+export * from "./panel";
+export { BridgeNetError, serve } from "./runtime";

package/src/manifest/assets.ts

@@ -0,0 +1,102 @@
+import { ASSET_MAX_EDGE, type AssetDimensions, readDimensions } from "./dimensions";
+
+export const ASSET_MAX_BYTES = 512 * 1024;
+
+export const ASSET_EXTENSION = "webp";
+
+export const ASSET_MEDIA_TYPE = "image/webp";
+
+const RIFF_HEADER_BYTES = 12;
+
+const startsWith = (bytes: Uint8Array, signature: number[]) => {
+	return signature.every((byte, index) => bytes[index] === byte);
+};
+
+const isWebp = (bytes: Uint8Array) => {
+	if (bytes.byteLength < RIFF_HEADER_BYTES) {
+		return false;
+	}
+
+	const riff = startsWith(
+		bytes,
+		[
+			0x52,
+			0x49,
+			0x46,
+			0x46,
+		],
+	);
+
+	const webp = startsWith(
+		bytes.subarray(8),
+		[
+			0x57,
+			0x45,
+			0x42,
+			0x50,
+		],
+	);
+
+	if (!riff || !webp) {
+		return false;
+	}
+
+	const first = bytes[4];
+	const second = bytes[5];
+	const third = bytes[6];
+	const fourth = bytes[7];
+
+	if (first === undefined || second === undefined || third === undefined || fourth === undefined) {
+		return false;
+	}
+
+	const declared = first + (second << 8) + (third << 16) + fourth * 0x1_00_00_00;
+
+	return declared + 8 === bytes.byteLength;
+};
+
+export const assetMediaType = (path: string) => {
+	const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+
+	if (extension !== ASSET_EXTENSION) {
+		throw new Error(`asset "${path}" must be a .${ASSET_EXTENSION} file`);
+	}
+
+	return ASSET_MEDIA_TYPE;
+};
+
+export interface VerifiedAsset {
+	mediaType: string;
+	dimensions: AssetDimensions;
+}
+
+export const verifyAsset = (path: string, bytes: Uint8Array): VerifiedAsset => {
+	if (bytes.byteLength === 0) {
+		throw new Error(`asset "${path}" is empty`);
+	}
+
+	if (bytes.byteLength > ASSET_MAX_BYTES) {
+		throw new Error(`asset "${path}" exceeds ${ASSET_MAX_BYTES} bytes`);
+	}
+
+	const mediaType = assetMediaType(path);
+
+	if (!isWebp(bytes)) {
+		throw new Error(`asset "${path}" is not a well-formed webp file`);
+	}
+
+	const dimensions = readDimensions(bytes);
+
+	if (!dimensions) {
+		throw new Error(`asset "${path}" has unreadable dimensions`);
+	}
+
+	if (dimensions.width > ASSET_MAX_EDGE || dimensions.height > ASSET_MAX_EDGE) {
+		throw new Error(`asset "${path}" exceeds ${ASSET_MAX_EDGE}px on an edge`);
+	}
+
+	return {
+		mediaType,
+		dimensions,
+	};
+};

package/src/manifest/category.ts

@@ -0,0 +1,10 @@
+export enum GameCategory {
+	Sandbox = "sandbox",
+	Survival = "survival",
+	Shooter = "shooter",
+	Racing = "racing",
+	Roleplay = "roleplay",
+	Strategy = "strategy",
+	Simulation = "simulation",
+	Other = "other",
+}

package/src/manifest/checks.ts

@@ -0,0 +1,50 @@
+import type { Manifest, ManifestPort } from "./manifest";
+
+const overlaps = (a: ManifestPort, b: ManifestPort) => {
+	return a.host.min <= b.host.max && b.host.min <= a.host.max;
+};
+
+export const checkManifest = (manifest: Manifest) => {
+	const portKeys = manifest.runtime.ports.map((port) => port.key);
+
+	if (new Set(portKeys).size !== portKeys.length) {
+		throw new Error("runtime declares duplicate port keys");
+	}
+
+	const ports = manifest.runtime.ports;
+
+	for (let index = 0; index < ports.length; index += 1) {
+		for (let other = index + 1; other < ports.length; other += 1) {
+			const a = ports[index];
+			const b = ports[other];
+
+			if (!a || !b || a.protocol !== b.protocol) {
+				continue;
+			}
+
+			if (overlaps(a, b)) {
+				throw new Error(`ports "${a.key}" and "${b.key}" declare overlapping ${a.protocol} host ranges`);
+			}
+		}
+	}
+
+	const guideIds = manifest.guides.map((guide) => guide.id);
+
+	if (new Set(guideIds).size !== guideIds.length) {
+		throw new Error("guides declare duplicate ids");
+	}
+
+	const bodies: string[] = [];
+
+	for (const guide of manifest.guides) {
+		if (guide.body.ar === guide.body.en) {
+			throw new Error(`guide "${guide.id}" reuses one body file for both locales`);
+		}
+
+		bodies.push(guide.body.ar, guide.body.en);
+	}
+
+	if (new Set(bodies).size !== bodies.length) {
+		throw new Error("guides declare duplicate body paths");
+	}
+};