@serverkgg/bridge 0.0.9 → 0.0.10

package/src/runtime/bridgeEvents.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BridgeKind } from "../core";
+import type { BridgeEventsModule } from "../modules";
+import { BridgeEventName } from "../protocol";
+import { createEventRing } from "./bridgeEvents";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const RESET = "\u001B[m";
+
+const PLAYER_JOINED = /^\[World\|(?<world>[^\]]+)\] Player '(?<player>[^']+)' joined world (?<target>\S+)$/;
+
+const silent: BridgeLeveledLogger = Object.assign(() => {}, {
+	warn: () => {},
+	error: () => {},
+});
+
+const events: BridgeEventsModule = {
+	kind: BridgeKind.Events,
+	patterns: [
+		{
+			match: PLAYER_JOINED,
+			emit: BridgeEventName.PlayerJoined,
+		},
+	],
+};
+
+const emittedFor = async (line: string) => {
+	const dir = await mkdtemp(join(tmpdir(), "bridge-events-"));
+	const path = join(dir, "line.txt");
+
+	await Bun.write(path, `${line}\n`);
+
+	const supervisor = createSupervisor({
+		cwd: dir,
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds: 1,
+		onLog: silent,
+		resolveCommand: async () => [
+			"bash",
+			"-c",
+			'cat "$0"; sleep 300',
+			path,
+		],
+	});
+
+	const ring = createEventRing(events, supervisor);
+
+	await supervisor.start();
+
+	try {
+		for (let waited = 0; waited < 5000; waited += 50) {
+			if (ring.drain(0).events.length > 0) {
+				break;
+			}
+
+			await Bun.sleep(50);
+		}
+
+		return ring.drain(0).events;
+	} finally {
+		await supervisor.stop();
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	}
+};
+
+const joined = {
+	seq: 1,
+	event: BridgeEventName.PlayerJoined,
+	payload: {
+		world: "default",
+		player: "Meslzy",
+		target: "default",
+	},
+};
+
+describe("matching a game line against the driver patterns", () => {
+	test("emits on the plain line", async () => {
+		expect(await emittedFor("[World|default] Player 'Meslzy' joined world default")).toEqual([
+			joined,
+		]);
+	});
+
+	test("emits on the line hytale really prints, wrapped in ansi resets at both ends", async () => {
+		expect(await emittedFor(`${RESET}[World|default] Player 'Meslzy' joined world default${RESET}`)).toEqual([
+			joined,
+		]);
+	});
+});

package/src/runtime/bridgeEvents.ts

@@ -1,6 +1,7 @@
 import type { BridgeValues } from "../core";
 import type { BridgeEventsModule } from "../modules";
 import type { BridgeEvent } from "../protocol";
+import { stripAnsi } from "../utils";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 const EVENT_BUFFER = 500;
@@ -26,12 +27,14 @@ export const createEventRing = (events: BridgeEventsModule | undefined, supervis
 
 	if (events) {
 		supervisor.subscribe((entry) => {
+			const line = stripAnsi(entry.line);
+
 			for (const pattern of events.patterns) {
 				if (pattern.stream && pattern.stream !== entry.stream) {
 					continue;
 				}
 
-				const match = entry.line.match(pattern.match);
+				const match = line.match(pattern.match);
 
 				if (!match) {
 					continue;

package/src/runtime/bridgeRegistry.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
 import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
@@ -62,6 +62,9 @@ const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
+		onSetup() {
+			return;
+		},
 	});
 
 	return createRegistry(driver, context, supervisor, ring);
@@ -560,3 +563,37 @@ describe("detail modules", () => {
 		);
 	});
 });
+
+describe("the setup singleton", () => {
+	test("rides the manifest as its own block and never joins the panel modules", () => {
+		const steps = [
+			{
+				kind: BridgeSetupStepKind.Driver as const,
+				id: "sign-in",
+				title: {
+					ar: "تسجيل الدخول",
+					en: "Sign in",
+				},
+			},
+		];
+
+		const registry = registryFor({
+			...baseDriver(),
+			setup: {
+				kind: BridgeKind.Setup,
+				steps,
+			},
+		});
+
+		const manifest = registry.manifest();
+
+		expect(manifest.setup).toEqual({
+			steps,
+		});
+		expect(manifest.modules.some((module) => module.kind === BridgeKind.Setup)).toBe(false);
+	});
+
+	test("leaves the manifest block empty for a driver that declares no setup", () => {
+		expect(registryFor(baseDriver()).manifest().setup).toBeNull();
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -1,10 +1,11 @@
 import type { BridgeContext } from "../context";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
-import type { BridgeDriver, BridgePanelModule, BridgeTerminalModule } from "../modules";
+import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
 import {
 	BRIDGE_VERSION,
 	type BridgeManifest,
 	type BridgeModuleManifest,
+	type BridgeSetupManifest,
 	type BridgeTerminalManifest,
 } from "../protocol";
 import { actionsOf } from "./bridgeActions";
@@ -63,6 +64,16 @@ const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTer
 	};
 };
 
+const setupManifestOf = (module: BridgeSetupModule | undefined): BridgeSetupManifest | null => {
+	if (!module) {
+		return null;
+	}
+
+	return {
+		steps: module.steps,
+	};
+};
+
 const withVariables = (context: BridgeContext, overlay: Record<string, string>): BridgeContext => {
 	return {
 		get server() {
@@ -88,6 +99,7 @@ const withVariables = (context: BridgeContext, overlay: Record<string, string>):
 			return context.exec(command, options);
 		},
 		logs: context.logs,
+		setup: context.setup,
 		emit(event, payload) {
 			context.emit(event, payload);
 		},
@@ -368,6 +380,7 @@ export const createRegistry = (
 				version: BRIDGE_VERSION,
 				panel: driver.panel ?? null,
 				terminal: terminalManifestOf(driver.terminal),
+				setup: setupManifestOf(driver.setup),
 				modules: entries,
 				events: ring.names(),
 			};

package/src/runtime/bridgeSecrets.test.ts

@@ -0,0 +1,121 @@
+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 { createBridgeSecrets } from "./bridgeSecrets";
+
+const configWith = (secrets: 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",
+	},
+	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-secrets-"));
+	path = join(directory, "config.json");
+});
+
+afterEach(async () => {
+	await rm(directory, {
+		force: true,
+		recursive: true,
+	});
+});
+
+describe("the bridge secrets reader", () => {
+	test("answers from the boot snapshot", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+		expect(secrets.read("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 = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+				MODRINTH_API_KEY: "added",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("rotated");
+		expect(secrets.read("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 = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await writeFile(path, '{"code": "wsvv8fak');
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await rm(path);
+
+		expect(secrets.read("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 = createBridgeSecrets(path, config, 60_000);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+});

package/src/runtime/bridgeSecrets.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import type { BridgeConfig } from "../protocol";
+import { parseConfig } from "./bridgeConfigReader";
+
+export const BRIDGE_SECRET_REFRESH_MS = 2000;
+
+export interface BridgeSecrets {
+	read: (key: string) => string | null;
+}
+
+export const createBridgeSecrets = (
+	path: string,
+	config: BridgeConfig,
+	refreshMs: number = BRIDGE_SECRET_REFRESH_MS,
+): BridgeSecrets => {
+	let values = config.secrets;
+
+	let checkedAt: number | null = null;
+
+	const refresh = () => {
+		const stamp = performance.now();
+
+		if (checkedAt !== null && stamp - checkedAt < refreshMs) {
+			return;
+		}
+
+		checkedAt = stamp;
+
+		try {
+			values = parseConfig(readFileSync(path, "utf8")).secrets;
+		} catch {
+			return;
+		}
+	};
+
+	return {
+		read(key) {
+			refresh();
+
+			return values[key] ?? null;
+		},
+	};
+};

package/src/runtime/bridgeServer.test.ts

@@ -2,9 +2,25 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { BridgeDesired, BridgeFailureCode, BridgeFailureError, BridgeRuntime, BridgeUserError } from "../core";
-import { BridgeMethod, type BridgePendingResult, type BridgeResponse } from "../protocol";
+import {
+	BridgeDesired,
+	BridgeFailureCode,
+	BridgeFailureError,
+	BridgeRuntime,
+	BridgeSetupPromptKind,
+	BridgeSetupStepState,
+	BridgeUserError,
+} from "../core";
+import {
+	BridgeMethod,
+	type BridgePendingResult,
+	type BridgeResponse,
+	type BridgeSetupResult,
+	type BridgeSetupRuntime,
+	type BridgeValues,
+} from "../protocol";
 import { createServer, type ServerOptions } from "./bridgeServer";
+import { failedSetup, unsupportedSetup } from "./bridgeSetup";
 
 const TOKEN = "test-token";
 
@@ -25,7 +41,9 @@ const baseOptions = (socket: string): ServerOptions => ({
 		outOfMemory: false,
 		restarts: 0,
 		installError: null,
+		installErrorText: null,
 		installHold: null,
+		setup: null,
 	}),
 	onManifest: unreachable("manifest"),
 	onStart: unreachable("start"),
@@ -40,6 +58,8 @@ const baseOptions = (socket: string): ServerOptions => ({
 	onAnnounce: unreachable("announce"),
 	onPendingList: unreachable("pendingList"),
 	onPendingAdd: unreachable("pendingAdd"),
+	onSetupStatus: unreachable("setupStatus"),
+	onSetupSubmit: unreachable("setupSubmit"),
 	onLog: () => {
 		return;
 	},
@@ -264,6 +284,246 @@ describe("pending dispatch", () => {
 	});
 });
 
+describe("setup dispatch", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const runtime: BridgeSetupRuntime = {
+		steps: [
+			{
+				id: "sign-in",
+				state: BridgeSetupStepState.Active,
+			},
+		],
+		prompt: {
+			kind: BridgeSetupPromptKind.Link,
+			message: {
+				ar: "سجل دخولك",
+				en: "sign in with your account",
+			},
+			url: "https://hytale.com/device",
+			code: "ABCD-EFGH",
+			expiresAt: null,
+			actions: [
+				{
+					id: "renew",
+					label: {
+						ar: "كود جديد",
+						en: "Get a new code",
+					},
+				},
+			],
+		},
+	};
+
+	const reported: BridgeSetupResult = {
+		supported: true,
+		runtime,
+	};
+
+	test("answers setupStatus with what the driver reported", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupStatus: () => reported,
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.SetupStatus,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 1,
+			ok: true,
+			result: reported,
+		});
+	});
+
+	test("answers setupStatus with the unsupported sentinel when the driver declares no setup", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupStatus: () => unsupportedSetup(),
+		});
+
+		const response = await call(socket, {
+			id: 2,
+			token: TOKEN,
+			method: BridgeMethod.SetupStatus,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 2,
+			ok: true,
+			result: {
+				supported: false,
+				runtime: null,
+			},
+		});
+	});
+
+	test("passes the step, action and args of a setupSubmit to the driver", async () => {
+		const received: {
+			step: string;
+			action: string;
+			args: BridgeValues;
+		}[] = [];
+
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async (step, action, args) => {
+				received.push({
+					step,
+					action,
+					args,
+				});
+
+				return reported;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 3,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+			args: {
+				force: true,
+			},
+		});
+
+		server.stop(true);
+
+		expect(received).toEqual([
+			{
+				step: "sign-in",
+				action: "renew",
+				args: {
+					force: true,
+				},
+			},
+		]);
+		expect(response).toEqual({
+			id: 3,
+			ok: true,
+			result: reported,
+		});
+	});
+
+	test("refuses a setupSubmit carrying no step id", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: unreachable("setupSubmit"),
+		});
+
+		const response = await call(socket, {
+			id: 4,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 4,
+			ok: false,
+			error: "setupSubmit needs a step id",
+		});
+	});
+
+	test("answers a rejected setupSubmit with a failed prompt instead of a failed call", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async () =>
+				failedSetup(runtime, {
+					ar: "الكود ما عاد ينفع",
+					en: "this code cannot be renewed any more",
+				}),
+		});
+
+		const response = await call(socket, {
+			id: 5,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 5,
+			ok: true,
+			result: {
+				supported: true,
+				runtime: {
+					steps: runtime.steps,
+					prompt: {
+						kind: BridgeSetupPromptKind.Failed,
+						message: {
+							ar: "الكود ما عاد ينفع",
+							en: "this code cannot be renewed any more",
+						},
+						actions: [
+							{
+								id: "renew",
+								label: {
+									ar: "كود جديد",
+									en: "Get a new code",
+								},
+							},
+						],
+					},
+				},
+			},
+		});
+	});
+
+	test("answers setupSubmit with the unsupported sentinel when the driver implements no submit", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async () => unsupportedSetup(),
+		});
+
+		const response = await call(socket, {
+			id: 6,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 6,
+			ok: true,
+			result: {
+				supported: false,
+				runtime: null,
+			},
+		});
+	});
+});
+
 describe("error serialisation", () => {
 	let dir = "";
 	let socket = "";

package/src/runtime/bridgeServer.ts

@@ -12,6 +12,7 @@ import {
 	type BridgeQuiesceResult,
 	type BridgeResponse,
 	type BridgeSampleResult,
+	type BridgeSetupResult,
 	type BridgeStatus,
 } from "../protocol";
 import { type BridgeLogger, errorText } from "./bridgeLog";
@@ -33,6 +34,8 @@ export interface ServerOptions {
 	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
 	onPendingList: () => Promise<BridgePendingResult>;
 	onPendingAdd: (input: string) => Promise<BridgePendingResult>;
+	onSetupStatus: () => BridgeSetupResult;
+	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeSetupResult>;
 	onLog: BridgeLogger;
 }
 
@@ -162,6 +165,20 @@ export const createServer = (options: ServerOptions) => {
 				return await options.onPendingAdd(input);
 			}
 
+			case BridgeMethod.SetupStatus: {
+				return options.onSetupStatus();
+			}
+
+			case BridgeMethod.SetupSubmit: {
+				const step = asText(request.module);
+
+				if (!step) {
+					throw new Error("setupSubmit needs a step id");
+				}
+
+				return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
+			}
+
 			default: {
 				throw new Error(`unknown method "${method}"`);
 			}