@serverkgg/bridge 0.0.12 → 0.0.14

package/src/runtime/bridgeConsoleHandler.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeCommandOptions, BridgeContext, BridgeReply } from "../context";
+import { BridgeKind, BridgeUserError } from "../core";
+import type { BridgeDriver, BridgeTerminalModule } from "../modules";
+import { createConsoleHandler } from "./bridgeConsoleHandler";
+
+const context = {} as unknown as BridgeContext;
+
+const driverWith = (terminal: BridgeTerminalModule | undefined): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	terminal,
+});
+
+const terminalWith = (run: BridgeTerminalModule["run"]): BridgeTerminalModule => ({
+	kind: BridgeKind.Terminal,
+	commands: [
+		{
+			name: "Save",
+			summary: {
+				ar: "يحفظ العالم.",
+				en: "Save the world.",
+			},
+		},
+	],
+	run,
+});
+
+const handlerFor = (driver: BridgeDriver) => {
+	const written: string[] = [];
+
+	const handler = createConsoleHandler({
+		driver,
+		context,
+		async onStdin(input: string, options: BridgeCommandOptions): Promise<BridgeReply> {
+			written.push(input);
+
+			return {
+				sent: input,
+				line: options.expect ? "matched" : null,
+				groups: {},
+			};
+		},
+	});
+
+	return {
+		handler,
+		written,
+	};
+};
+
+describe("routing a console line to the driver before the game's stdin", () => {
+	test("answers with the driver's reply when the driver handles the line", async () => {
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async (_context, input) => {
+					return {
+						sent: input,
+						line: "Save requested",
+						groups: {},
+					};
+				}),
+			),
+		);
+
+		expect(await handler("Save", {})).toEqual({
+			sent: "Save",
+			line: "Save requested",
+			groups: {},
+		});
+		expect(written).toEqual([]);
+	});
+
+	test("hands the driver the same line the caller typed", async () => {
+		const seen: string[] = [];
+
+		const { handler } = handlerFor(
+			driverWith(
+				terminalWith(async (_context, input) => {
+					seen.push(input);
+
+					return {
+						sent: input,
+						line: null,
+						groups: {},
+					};
+				}),
+			),
+		);
+
+		await handler("Broadcast hello world", {});
+
+		expect(seen).toEqual([
+			"Broadcast hello world",
+		]);
+	});
+
+	test("writes the line to stdin when the driver answers null", async () => {
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					return null;
+				}),
+			),
+		);
+
+		expect(await handler("save-all", {})).toEqual({
+			sent: "save-all",
+			line: null,
+			groups: {},
+		});
+		expect(written).toEqual([
+			"save-all",
+		]);
+	});
+
+	test("keeps the expect and timeout of a line the driver leaves alone", async () => {
+		const { handler } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					return null;
+				}),
+			),
+		);
+
+		expect(
+			(
+				await handler("list", {
+					expect: /players online/,
+					timeoutMs: 1000,
+				})
+			).line,
+		).toBe("matched");
+	});
+
+	test("writes the line to stdin when the driver declares no handler", async () => {
+		const { handler, written } = handlerFor(
+			driverWith({
+				kind: BridgeKind.Terminal,
+				commands: [],
+			}),
+		);
+
+		await handler("list", {});
+
+		expect(written).toEqual([
+			"list",
+		]);
+	});
+
+	test("writes the line to stdin when the game declares no terminal at all", async () => {
+		const { handler, written } = handlerFor(driverWith(undefined));
+
+		await handler("list", {});
+
+		expect(written).toEqual([
+			"list",
+		]);
+	});
+
+	test("refuses the line with the driver's own text when the driver rejects it", async () => {
+		const refusal = {
+			ar: "هذا الأمر يشتغل داخل اللعبة بس.",
+			en: "That command only works inside the game.",
+		};
+
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					throw new BridgeUserError(refusal);
+				}),
+			),
+		);
+
+		try {
+			await handler("TeleportToPlayer meslzy", {});
+
+			expect.unreachable();
+		} catch (error) {
+			expect(error).toBeInstanceOf(BridgeUserError);
+			expect((error as BridgeUserError).text).toEqual(refusal);
+		}
+
+		expect(written).toEqual([]);
+	});
+});

package/src/runtime/bridgeConsoleHandler.ts

@@ -0,0 +1,26 @@
+import type { BridgeCommandOptions, BridgeContext, BridgeReply } from "../context";
+import type { BridgeDriver } from "../modules";
+
+export type BridgeConsoleHandler = (input: string, options: BridgeCommandOptions) => Promise<BridgeReply>;
+
+export interface BridgeConsoleOptions {
+	driver: BridgeDriver;
+	context: BridgeContext;
+	onStdin: BridgeConsoleHandler;
+}
+
+export const createConsoleHandler = (options: BridgeConsoleOptions): BridgeConsoleHandler => {
+	return async (input, commandOptions) => {
+		const run = options.driver.terminal?.run;
+
+		if (run) {
+			const reply = await run(options.context, input);
+
+			if (reply) {
+				return reply;
+			}
+		}
+
+		return await options.onStdin(input, commandOptions);
+	};
+};

package/src/runtime/bridgeContext.ts

@@ -7,10 +7,11 @@ import { configPath } from "./bridgeConfigReader";
 import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
+import { createBridgeLiveConfig } from "./bridgeLiveConfig";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
-import { createBridgeSecrets } from "./bridgeSecrets";
+import { createBridgeRcons } from "./bridgeRcon";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 export interface ContextHooks {
@@ -26,7 +27,7 @@ export const createContext = (
 ): BridgeContext => {
 	const egress = createBridgeEgress(config);
 
-	const secrets = createBridgeSecrets(configPath(), config);
+	const live = createBridgeLiveConfig(configPath(), config);
 
 	const files = createBridgeFiles({
 		root: config.cwd,
@@ -39,19 +40,23 @@ export const createContext = (
 	return {
 		server: {
 			code: config.code,
-			memoryMb: config.memoryMb,
-			cpuPercent: config.cpuPercent,
+			get memoryMb() {
+				return live.memoryMb();
+			},
+			get cpuPercent() {
+				return live.cpuPercent();
+			},
 			get running() {
 				return supervisor.running;
 			},
 		},
 
 		variable(key) {
-			return config.variables[key] ?? null;
+			return live.variable(key);
 		},
 
 		secret(key) {
-			return secrets.read(key);
+			return live.secret(key);
 		},
 
 		port(key) {
@@ -72,6 +77,8 @@ export const createContext = (
 
 		probe: createBridgeProbes(),
 
+		rcon: createBridgeRcons(),
+
 		async command(input, options) {
 			return await supervisor.command(input, options);
 		},

package/src/runtime/bridgeDriver.test.ts

@@ -232,6 +232,7 @@ const port = (activeWhen: ManifestPortActivation[]): ManifestPort => ({
 	},
 	join: PortJoin.Combined,
 	activeWhen,
+	mirror: false,
 });
 
 const driverWithTabs = (tabs: number, sections: number): BridgeDriver => ({

package/src/runtime/bridgeLiveConfig.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BridgeConfig } from "../protocol";
+import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+
+const configWith = (secrets: Record<string, string>, variables: Record<string, string> = {}): BridgeConfig => ({
+	code: "wsvv8fakxm",
+	token: "token",
+	cwd: "/data",
+	run: "/run/bridge",
+	ports: {
+		game: 25_565,
+	},
+	memoryMb: 2048,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {
+		VERSION: "1.21",
+		...variables,
+	},
+	secrets,
+});
+
+let directory: string;
+
+let path: string;
+
+const write = async (config: BridgeConfig) => {
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+};
+
+beforeEach(async () => {
+	directory = await mkdtemp(join(tmpdir(), "bridge-live-config-"));
+	path = join(directory, "config.json");
+});
+
+afterEach(async () => {
+	await rm(directory, {
+		force: true,
+		recursive: true,
+	});
+});
+
+describe("the bridge live config reader", () => {
+	test("answers from the boot snapshot", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeLiveConfig(path, config, 0);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+		expect(secrets.secret("MODRINTH_API_KEY")).toBeNull();
+	});
+
+	test("sees a value the agent rewrote into the config", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeLiveConfig(path, config, 0);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+				MODRINTH_API_KEY: "added",
+			}),
+		);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("rotated");
+		expect(secrets.secret("MODRINTH_API_KEY")).toBe("added");
+	});
+
+	test("keeps the last good values while the config is mid-write", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeLiveConfig(path, config, 0);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await writeFile(path, '{"code": "wsvv8fak');
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await rm(path);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+
+	test("re-reads the file at most once per refresh window", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeLiveConfig(path, config, 60_000);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+			}),
+		);
+
+		expect(secrets.secret("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+
+	test("sees a variable the customer changed after boot, and the new plan resources", async () => {
+		const config = configWith({});
+
+		await write(config);
+
+		const live = createBridgeLiveConfig(path, config, 0);
+
+		expect(live.variable("CROSSPLAY")).toBeNull();
+		expect(live.memoryMb()).toBe(2048);
+
+		await write({
+			...configWith(
+				{},
+				{
+					CROSSPLAY: "true",
+				},
+			),
+			memoryMb: 4096,
+			cpuPercent: 200,
+		});
+
+		expect(live.variable("CROSSPLAY")).toBe("true");
+		expect(live.variable("VERSION")).toBe("1.21");
+		expect(live.memoryMb()).toBe(4096);
+		expect(live.cpuPercent()).toBe(200);
+	});
+});

package/src/runtime/bridgeLiveConfig.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import type { BridgeConfig } from "../protocol";
+import { parseConfig } from "./bridgeConfigReader";
+
+export const BRIDGE_CONFIG_REFRESH_MS = 2000;
+
+/**
+ * The agent rewrites the bridge config in place when the customer changes a
+ * variable, a secret or the plan, and then restarts the game rather than the
+ * container. The bridge process outlives that rewrite, so anything answered
+ * from the boot snapshot would be stale. Every read here re-checks the file,
+ * throttled to one read per refresh window, and keeps the last good values
+ * while the agent is mid-write.
+ */
+export interface BridgeLiveConfig {
+	variable: (key: string) => string | null;
+	secret: (key: string) => string | null;
+	memoryMb: () => number;
+	cpuPercent: () => number;
+}
+
+export const createBridgeLiveConfig = (
+	path: string,
+	config: BridgeConfig,
+	refreshMs: number = BRIDGE_CONFIG_REFRESH_MS,
+): BridgeLiveConfig => {
+	let current = config;
+
+	let checkedAt: number | null = null;
+
+	const refresh = () => {
+		const stamp = performance.now();
+
+		if (checkedAt !== null && stamp - checkedAt < refreshMs) {
+			return current;
+		}
+
+		checkedAt = stamp;
+
+		try {
+			current = parseConfig(readFileSync(path, "utf8"));
+		} catch {
+			return current;
+		}
+
+		return current;
+	};
+
+	return {
+		variable(key) {
+			return refresh().variables[key] ?? null;
+		},
+		secret(key) {
+			return refresh().secrets[key] ?? null;
+		},
+		memoryMb() {
+			return refresh().memoryMb;
+		},
+		cpuPercent() {
+			return refresh().cpuPercent;
+		},
+	};
+};

package/src/runtime/bridgeRcon.ts

@@ -0,0 +1,19 @@
+import type { BridgeRcons } from "../context";
+import { RconClient } from "../rcon";
+
+const RCON_HOST = "127.0.0.1";
+
+export const createBridgeRcons = (): BridgeRcons => {
+	return {
+		async source(options) {
+			const client = new RconClient({
+				...options,
+				host: RCON_HOST,
+			});
+
+			await client.connect();
+
+			return client;
+		},
+	};
+};

package/src/runtime/bridgeRegistry.ts

@@ -92,6 +92,7 @@ const withVariables = (context: BridgeContext, overlay: Record<string, string>):
 		codec: context.codec,
 		net: context.net,
 		probe: context.probe,
+		rcon: context.rcon,
 		command(input, options) {
 			return context.command(input, options);
 		},

package/src/runtime/serve.ts

@@ -10,6 +10,7 @@ import {
 	type BridgeStatus,
 } from "../protocol";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
+import { createConsoleHandler } from "./bridgeConsoleHandler";
 import { createContext } from "./bridgeContext";
 import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
@@ -111,6 +112,14 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const registry = createRegistry(driver, context, supervisor, ring);
 
+	const runConsole = createConsoleHandler({
+		driver,
+		context,
+		async onStdin(input, commandOptions) {
+			return await supervisor.command(input, commandOptions);
+		},
+	});
+
 	let current = desired;
 
 	const status = (): BridgeStatus => {
@@ -205,7 +214,7 @@ export const serve = async (driver: BridgeDriver) => {
 			await supervisor.stop();
 		},
 		async onCommand(input, expect, timeoutMs) {
-			return await supervisor.command(input, {
+			return await runConsole(input, {
 				expect: expect === undefined ? undefined : new RegExp(expect),
 				timeoutMs,
 			});

package/src/steam/index.ts

@@ -0,0 +1,7 @@
+export * from "./steamApp";
+export * from "./steamcmd";
+export * from "./steamcmdLogin";
+export * from "./steamcmdNarrator";
+export * from "./steamcmdPlatform";
+export * from "./webApi";
+export * from "./workshop";

package/src/steam/steamApp.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import { appManifestPath, buildIdOf, installedBuildId, missingGameRoots } from "./steamApp";
+
+const MANIFEST = [
+	'"AppState"',
+	"{",
+	'\t"appid"\t\t"2394010"',
+	'\t"buildid"\t\t"19582821"',
+	"}",
+].join("\n");
+
+const testContext = (files: Record<string, string>) => {
+	return {
+		files: {
+			async exists(path: string) {
+				return path in files;
+			},
+			async read(path: string) {
+				return files[path] ?? "";
+			},
+		},
+	} as unknown as BridgeContext;
+};
+
+describe("appManifestPath", () => {
+	test("points at the steamapps manifest", () => {
+		expect(appManifestPath("2394010")).toBe("steamapps/appmanifest_2394010.acf");
+	});
+
+	test("accepts another steamapps directory", () => {
+		expect(appManifestPath("90", ".steam/steamapps")).toBe(".steam/steamapps/appmanifest_90.acf");
+	});
+});
+
+describe("buildIdOf", () => {
+	test("reads the build id out of an acf manifest", () => {
+		expect(buildIdOf(MANIFEST)).toBe("19582821");
+	});
+
+	test("returns null when there is no build id", () => {
+		expect(buildIdOf('"AppState"\n{\n}\n')).toBeNull();
+		expect(buildIdOf("")).toBeNull();
+	});
+});
+
+describe("installedBuildId", () => {
+	test("returns null when the app was never installed", async () => {
+		expect(await installedBuildId(testContext({}), "2394010")).toBeNull();
+	});
+
+	test("reads the installed build id", async () => {
+		const context = testContext({
+			"steamapps/appmanifest_2394010.acf": MANIFEST,
+		});
+
+		expect(await installedBuildId(context, "2394010")).toBe("19582821");
+	});
+});
+
+describe("missingGameRoots", () => {
+	test("names only the paths that are absent", async () => {
+		const context = testContext({
+			"PalServer.sh": "",
+			Engine: "",
+		});
+
+		expect(
+			await missingGameRoots(context, [
+				"PalServer.sh",
+				"Pal/Content",
+				"Engine",
+			]),
+		).toEqual([
+			"Pal/Content",
+		]);
+	});
+});

package/src/steam/steamApp.ts

@@ -0,0 +1,35 @@
+import type { BridgeContext } from "../context";
+
+export const STEAMAPPS_DIRECTORY = "steamapps";
+
+const BUILD_ID = /"buildid"\s+"(?<buildId>\d+)"/;
+
+export const appManifestPath = (appId: string, directory: string = STEAMAPPS_DIRECTORY) => {
+	return `${directory}/appmanifest_${appId}.acf`;
+};
+
+export const buildIdOf = (manifest: string) => {
+	return manifest.match(BUILD_ID)?.groups?.buildId ?? null;
+};
+
+export const installedBuildId = async (context: BridgeContext, appId: string, directory?: string) => {
+	const path = appManifestPath(appId, directory);
+
+	if (!(await context.files.exists(path))) {
+		return null;
+	}
+
+	return buildIdOf(await context.files.read(path));
+};
+
+export const missingGameRoots = async (context: BridgeContext, roots: string[]) => {
+	const missing: string[] = [];
+
+	for (const path of roots) {
+		if (!(await context.files.exists(path))) {
+			missing.push(path);
+		}
+	}
+
+	return missing;
+};