@serverkgg/bridge 0.0.12 → 0.0.13

package/src/codecs/sourceCfg.ts

@@ -0,0 +1,111 @@
+import type { BridgeValue, BridgeValues } from "../core";
+
+const ENTRY = /^(?<key>[A-Za-z_][A-Za-z0-9_.]*)(?:[ \t]+(?<value>.*))?$/;
+
+const NUMERIC = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+
+const NEWLINES = /[\r\n]+/g;
+
+export interface SourceCfgEntry {
+	key: string;
+	value: string;
+}
+
+export const readSourceCfgEntry = (line: string): SourceCfgEntry | null => {
+	const trimmed = line.trim();
+
+	if (trimmed.length === 0 || trimmed.startsWith("//") || trimmed.startsWith("#")) {
+		return null;
+	}
+
+	const match = trimmed.match(ENTRY);
+
+	if (!match?.groups?.key) {
+		return null;
+	}
+
+	return {
+		key: match.groups.key,
+		value: (match.groups.value ?? "").trim(),
+	};
+};
+
+export const decodeSourceCfgValue = (raw: string): BridgeValue => {
+	if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+		return raw.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\");
+	}
+
+	if (raw === "true" || raw === "false") {
+		return raw === "true";
+	}
+
+	if (NUMERIC.test(raw)) {
+		return Number(raw);
+	}
+
+	return raw;
+};
+
+export const encodeSourceCfgValue = (value: BridgeValue): string => {
+	if (typeof value === "boolean") {
+		return value ? "true" : "false";
+	}
+
+	if (typeof value === "number") {
+		return Number.isFinite(value) ? String(value) : '""';
+	}
+
+	const text = (value ?? "").replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll(NEWLINES, " ");
+
+	return `"${text}"`;
+};
+
+export const parseSourceCfg = (contents: string): BridgeValues => {
+	const values: BridgeValues = {};
+
+	for (const line of contents.split("\n")) {
+		const entry = readSourceCfgEntry(line);
+
+		if (entry) {
+			values[entry.key] = decodeSourceCfgValue(entry.value);
+		}
+	}
+
+	return values;
+};
+
+export const mergeSourceCfg = (contents: string, values: BridgeValues): string => {
+	const pending = new Map(Object.entries(values));
+	const written = new Set<string>();
+	const lines: string[] = [];
+
+	for (const line of contents.split("\n")) {
+		const entry = readSourceCfgEntry(line);
+		const key = entry?.key ?? "";
+
+		if (!entry || !pending.has(key)) {
+			lines.push(line);
+
+			continue;
+		}
+
+		if (written.has(key)) {
+			continue;
+		}
+
+		written.add(key);
+		lines.push(`${key} ${encodeSourceCfgValue(pending.get(key) ?? null)}`);
+	}
+
+	while (lines.length > 0 && (lines.at(-1) ?? "").trim().length === 0) {
+		lines.pop();
+	}
+
+	for (const [key, value] of pending) {
+		if (!written.has(key)) {
+			lines.push(`${key} ${encodeSourceCfgValue(value)}`);
+		}
+	}
+
+	return `${lines.join("\n")}\n`;
+};

package/src/codecs/xmlProperties.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { mergeXmlProperties, parseXmlProperties } from "./xmlProperties";
+
+const SAMPLE = [
+	'<?xml version="1.0"?>',
+	"<ServerSettings>",
+	'\t<property name="ServerName" value="serverk"/>',
+	"\t<!-- a note -->",
+	'\t<property name="ServerPort" value="26900"/>',
+	'\t<property value="8" name="ServerMaxPlayerCount"/>',
+	"</ServerSettings>",
+	"",
+].join("\n");
+
+describe("parseXmlProperties", () => {
+	test("reads every property whichever way the attributes are ordered", () => {
+		expect(parseXmlProperties(SAMPLE)).toEqual({
+			ServerName: "serverk",
+			ServerPort: "26900",
+			ServerMaxPlayerCount: "8",
+		});
+	});
+
+	test("decodes entities", () => {
+		expect(parseXmlProperties('<property name="ServerName" value="a &amp; b &lt;c&gt;"/>')).toEqual({
+			ServerName: "a & b <c>",
+		});
+	});
+
+	test("accepts single quoted attributes and an empty value", () => {
+		expect(parseXmlProperties("<property name='ServerPassword' value=''/>")).toEqual({
+			ServerPassword: "",
+		});
+	});
+
+	test("ignores everything that is not a property", () => {
+		expect(parseXmlProperties('<ServerSettings>\n<other name="x" value="1"/>\n</ServerSettings>')).toEqual({});
+	});
+});
+
+describe("mergeXmlProperties", () => {
+	test("rewrites a value in place and keeps order, comments and the header", () => {
+		expect(
+			mergeXmlProperties(SAMPLE, {
+				ServerPort: "26950",
+			}),
+		).toBe(
+			[
+				'<?xml version="1.0"?>',
+				"<ServerSettings>",
+				'\t<property name="ServerName" value="serverk"/>',
+				"\t<!-- a note -->",
+				'\t<property name="ServerPort" value="26950"/>',
+				'\t<property value="8" name="ServerMaxPlayerCount"/>',
+				"</ServerSettings>",
+				"",
+			].join("\n"),
+		);
+	});
+
+	test("rewrites a property whose value attribute comes first", () => {
+		expect(
+			mergeXmlProperties(SAMPLE, {
+				ServerMaxPlayerCount: "16",
+			}),
+		).toContain('<property value="16" name="ServerMaxPlayerCount"/>');
+	});
+
+	test("adds an unknown property before the closing tag with the same indent", () => {
+		expect(
+			mergeXmlProperties(SAMPLE, {
+				ServerPassword: "1234",
+			}),
+		).toBe(
+			[
+				'<?xml version="1.0"?>',
+				"<ServerSettings>",
+				'\t<property name="ServerName" value="serverk"/>',
+				"\t<!-- a note -->",
+				'\t<property name="ServerPort" value="26900"/>',
+				'\t<property value="8" name="ServerMaxPlayerCount"/>',
+				'\t<property name="ServerPassword" value="1234"/>',
+				"</ServerSettings>",
+				"",
+			].join("\n"),
+		);
+	});
+
+	test("escapes a value it writes", () => {
+		expect(
+			mergeXmlProperties(SAMPLE, {
+				ServerName: 'a & b "c"',
+			}),
+		).toContain('<property name="ServerName" value="a &amp; b &quot;c&quot;"/>');
+	});
+
+	test("adds a value attribute to a property that has none", () => {
+		expect(
+			mergeXmlProperties('<property name="ServerName"/>', {
+				ServerName: "x",
+			}),
+		).toBe('<property name="ServerName" value="x"/>');
+	});
+});

package/src/codecs/xmlProperties.ts

@@ -0,0 +1,133 @@
+const PROPERTY_TAG = /<property\b[^>]*>/gi;
+
+const PROPERTY_LINE = /<property\b/i;
+
+const CLOSING_TAG = /<\/[A-Za-z_][\w.:-]*\s*>/g;
+
+const INDENT = /^[ \t]*/;
+
+const DEFAULT_INDENT = "\t";
+
+const ENTITIES: Record<string, string> = {
+	amp: "&",
+	apos: "'",
+	gt: ">",
+	lt: "<",
+	quot: '"',
+};
+
+const ENTITY = /&(amp|apos|gt|lt|quot);/g;
+
+const attributePattern = (name: string) => {
+	return new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i");
+};
+
+const NAME_ATTRIBUTE = attributePattern("name");
+
+const VALUE_ATTRIBUTE = attributePattern("value");
+
+const decodeXml = (raw: string) => {
+	return raw.replace(ENTITY, (_match, entity: string) => ENTITIES[entity] ?? _match);
+};
+
+const encodeXml = (raw: string) => {
+	return raw
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&apos;");
+};
+
+const attributeOf = (tag: string, pattern: RegExp) => {
+	const match = tag.match(pattern);
+
+	if (!match) {
+		return null;
+	}
+
+	return decodeXml(match[1] ?? match[2] ?? "");
+};
+
+const propertyLine = (indent: string, key: string, value: string) => {
+	return `${indent}<property name="${encodeXml(key)}" value="${encodeXml(value)}"/>`;
+};
+
+const existingIndent = (contents: string) => {
+	for (const line of contents.split("\n")) {
+		if (PROPERTY_LINE.test(line)) {
+			return line.match(INDENT)?.at(0) ?? DEFAULT_INDENT;
+		}
+	}
+
+	return DEFAULT_INDENT;
+};
+
+export const parseXmlProperties = (contents: string) => {
+	const values: Record<string, string> = {};
+
+	for (const [tag] of contents.matchAll(PROPERTY_TAG)) {
+		const key = attributeOf(tag, NAME_ATTRIBUTE);
+
+		if (key !== null && key.length > 0) {
+			values[key] = attributeOf(tag, VALUE_ATTRIBUTE) ?? "";
+		}
+	}
+
+	return values;
+};
+
+export const mergeXmlProperties = (contents: string, values: Record<string, string>) => {
+	const pending = new Map(Object.entries(values));
+	const indent = existingIndent(contents);
+
+	const rewritten = contents.replace(PROPERTY_TAG, (tag) => {
+		const key = attributeOf(tag, NAME_ATTRIBUTE);
+
+		if (key === null || !pending.has(key)) {
+			return tag;
+		}
+
+		const value = encodeXml(pending.get(key) ?? "");
+
+		pending.delete(key);
+
+		if (VALUE_ATTRIBUTE.test(tag)) {
+			return tag.replace(VALUE_ATTRIBUTE, `value="${value}"`);
+		}
+
+		return tag.replace(/\s*\/?>$/, ` value="${value}"/>`);
+	});
+
+	if (pending.size === 0) {
+		return rewritten;
+	}
+
+	const added = [
+		...pending,
+	].map(([key, value]) => propertyLine(indent, key, value));
+
+	const closings = [
+		...rewritten.matchAll(CLOSING_TAG),
+	];
+	const last = closings.at(-1);
+
+	if (last?.index === undefined) {
+		const lines = rewritten.split("\n");
+
+		while (lines.length > 0 && (lines.at(-1) ?? "").trim().length === 0) {
+			lines.pop();
+		}
+
+		return `${[
+			...lines,
+			...added,
+		].join("\n")}\n`;
+	}
+
+	const head = rewritten.slice(0, last.index);
+	const tail = rewritten.slice(last.index);
+	const lineStart = head.lastIndexOf("\n") + 1;
+
+	return `${head.slice(0, lineStart)}${added.join("\n")}\n${head.slice(lineStart)}${tail}`;
+};

package/src/context/bridgeContext.ts

@@ -59,9 +59,12 @@ export interface BridgeCodec {
 }
 
 export interface BridgeCodecs {
+	ini: BridgeCodec;
 	json: BridgeCodec;
 	properties: BridgeCodec;
+	sourceCfg: BridgeCodec;
 	ueIni: BridgeCodec;
+	xmlProperties: BridgeCodec;
 }
 
 export interface BridgeRequestOptions {
@@ -115,6 +118,22 @@ export interface BridgeProbes {
 	raknetPing(port: number): Promise<BridgeRaknetPingStatus>;
 }
 
+export interface BridgeRconOptions {
+	port: number;
+	password: string;
+	timeoutMs?: number;
+	multiPacket?: boolean;
+}
+
+export interface BridgeRconClient {
+	command(text: string): Promise<string>;
+	close(): void;
+}
+
+export interface BridgeRcons {
+	source(options: BridgeRconOptions): Promise<BridgeRconClient>;
+}
+
 export interface BridgeCommandOptions {
 	expect?: RegExp;
 	timeoutMs?: number;
@@ -164,6 +183,7 @@ export interface BridgeContext {
 	codec: BridgeCodecs;
 	net: BridgeNet;
 	probe: BridgeProbes;
+	rcon: BridgeRcons;
 	command(input: string, options?: BridgeCommandOptions): Promise<BridgeReply>;
 	exec(command: string[], options?: BridgeExecOptions): Promise<BridgeExecResult>;
 	logs: BridgeLogs;

package/src/core/bridgeRconError.ts

@@ -0,0 +1,19 @@
+export enum BridgeRconCode {
+	AuthFailed = "auth-failed",
+	Closed = "closed",
+	Malformed = "malformed",
+	Oversized = "oversized",
+	TimedOut = "timed-out",
+	Unreachable = "unreachable",
+}
+
+export class BridgeRconError extends Error {
+	readonly code: BridgeRconCode;
+
+	constructor(code: BridgeRconCode, message: string) {
+		super(message);
+
+		this.name = "BridgeRconError";
+		this.code = code;
+	}
+}

package/src/core/index.ts

@@ -7,6 +7,7 @@ export * from "./bridgeKind";
 export * from "./bridgeNetError";
 export * from "./bridgePort";
 export * from "./bridgeProbeError";
+export * from "./bridgeRconError";
 export * from "./bridgeRuntime";
 export * from "./bridgeSecretError";
 export * from "./bridgeSetup";

package/src/install/index.ts

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

package/src/install/installStamp.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import { INSTALL_STAMP_FILE, parseStamp, readStamp, writeStamp } from "./installStamp";
+
+interface TestStamp {
+	buildId: string | null;
+	rconPassword?: string;
+}
+
+const testContext = (seed: Record<string, string> = {}) => {
+	const stored = new Map(Object.entries(seed));
+
+	const context = {
+		files: {
+			async exists(path: string) {
+				return stored.has(path);
+			},
+			async read(path: string) {
+				return stored.get(path) ?? "";
+			},
+			async write(path: string, content: string) {
+				stored.set(path, content);
+			},
+		},
+	} as unknown as BridgeContext;
+
+	return {
+		context,
+		stored,
+	};
+};
+
+describe("parseStamp", () => {
+	test("reads a json object", () => {
+		expect(
+			parseStamp<TestStamp>(
+				JSON.stringify({
+					buildId: "123",
+				}),
+			),
+		).toEqual({
+			buildId: "123",
+		});
+	});
+
+	test("returns null for anything that is not a json object", () => {
+		expect(parseStamp("")).toBeNull();
+		expect(parseStamp("{")).toBeNull();
+		expect(parseStamp("null")).toBeNull();
+		expect(parseStamp("[1,2]")).toBeNull();
+		expect(parseStamp('"text"')).toBeNull();
+	});
+});
+
+describe("readStamp", () => {
+	test("returns null when the stamp file is absent", async () => {
+		const { context } = testContext();
+
+		expect(await readStamp(context)).toBeNull();
+	});
+
+	test("reads the stamp the writer left behind", async () => {
+		const { context } = testContext();
+
+		await writeStamp<TestStamp>(context, {
+			buildId: "4711",
+			rconPassword: "secret",
+		});
+
+		expect(await readStamp<TestStamp>(context)).toEqual({
+			buildId: "4711",
+			rconPassword: "secret",
+		});
+	});
+
+	test("writes pretty json ending in a newline", async () => {
+		const { context, stored } = testContext();
+
+		await writeStamp(context, {
+			buildId: "1",
+		});
+
+		expect(stored.get(INSTALL_STAMP_FILE)).toBe('{\n  "buildId": "1"\n}\n');
+	});
+
+	test("honours a custom stamp path", async () => {
+		const { context, stored } = testContext();
+
+		await writeStamp(
+			context,
+			{
+				ready: true,
+			},
+			".serverk-wine.json",
+		);
+
+		expect(stored.has(INSTALL_STAMP_FILE)).toBe(false);
+		expect(await readStamp(context, ".serverk-wine.json")).toEqual({
+			ready: true,
+		});
+	});
+
+	test("returns null when the read fails after the file was seen", async () => {
+		const context = {
+			files: {
+				async exists() {
+					return true;
+				},
+				async read() {
+					throw new Error("vanished");
+				},
+			},
+		} as unknown as BridgeContext;
+
+		expect(await readStamp(context)).toBeNull();
+	});
+
+	test("returns null when the stamp file is corrupt", async () => {
+		const { context } = testContext({
+			[INSTALL_STAMP_FILE]: "not json",
+		});
+
+		expect(await readStamp(context)).toBeNull();
+	});
+});

package/src/install/installStamp.ts

@@ -0,0 +1,40 @@
+import type { BridgeContext } from "../context";
+
+export const INSTALL_STAMP_FILE = ".serverk-install.json";
+
+export const parseStamp = <Stamp extends object = Record<string, unknown>>(raw: string): Stamp | null => {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+			return null;
+		}
+
+		return parsed as Stamp;
+	} catch {
+		return null;
+	}
+};
+
+export const readStamp = async <Stamp extends object = Record<string, unknown>>(
+	context: BridgeContext,
+	path: string = INSTALL_STAMP_FILE,
+): Promise<Stamp | null> => {
+	if (!(await context.files.exists(path))) {
+		return null;
+	}
+
+	try {
+		return parseStamp<Stamp>(await context.files.read(path));
+	} catch {
+		return null;
+	}
+};
+
+export const writeStamp = async <Stamp extends object>(
+	context: BridgeContext,
+	stamp: Stamp,
+	path: string = INSTALL_STAMP_FILE,
+): Promise<void> => {
+	await context.files.write(path, `${JSON.stringify(stamp, null, 2)}\n`);
+};

package/src/main.ts

@@ -1,5 +1,6 @@
 export * from "./context";
 export * from "./core";
+export * from "./install";
 export * from "./modules";
 export * from "./panel";
 export * from "./runtime";

package/src/manifest/index.ts

@@ -8,4 +8,5 @@ export * from "./localized";
 export * from "./manifest";
 export * from "./presence";
 export * from "./primitives";
+export * from "./runtime";
 export * from "./source";