@serverkgg/bridge 0.0.21 → 0.1.1

package/src/panel/bridgeDetail.ts

@@ -1,4 +1,5 @@
 import type { BridgeCopy, BridgeValue, LocalizedText } from "../core";
+import type { BridgeIcon } from "./bridgeIcon";
 
 export enum BridgeDetailTone {
 	Neutral = "neutral",
@@ -38,6 +39,7 @@ export interface BridgeDetail {
 	subtitle: BridgeCopy | null;
 	description: BridgeCopy | null;
 	image: string | null;
+	icon?: BridgeIcon;
 	badges: BridgeDetailBadge[];
 	stats: BridgeDetailStat[];
 	links: BridgeDetailLink[];

package/src/protocol/bridgeConfig.ts

@@ -4,6 +4,8 @@ export interface BridgeConfig {
 	cwd: string;
 	run: string;
 	ports: Record<string, number>;
+	portCounts?: Record<string, number>;
+	publicAddress?: string;
 	memoryMb: number;
 	cpuPercent: number;
 	gameUid: number;

package/src/runtime/bridgeConfigReader.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeConfigError, parseConfig } from "./bridgeConfigReader";
+
+const written = (extra: Record<string, unknown> = {}) => {
+	return JSON.stringify({
+		code: "abcdef",
+		token: "token",
+		cwd: "/home/game",
+		run: "/run/serverk",
+		ports: {
+			game: 19_132,
+			media: 20_000,
+		},
+		memoryMb: 2048,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables: {},
+		secrets: {},
+		...extra,
+	});
+};
+
+describe("parseConfig", () => {
+	test("reads a file an older agent wrote, with no public address and no port counts", () => {
+		const config = parseConfig(written());
+
+		expect(config.publicAddress).toBeUndefined();
+		expect(config.portCounts).toBeUndefined();
+		expect(config.ports).toEqual({
+			game: 19_132,
+			media: 20_000,
+		});
+	});
+
+	test("reads the public address and the port counts when the agent wrote them", () => {
+		const config = parseConfig(
+			written({
+				publicAddress: "203.0.113.7",
+				portCounts: {
+					game: 1,
+					media: 32,
+				},
+			}),
+		);
+
+		expect(config.publicAddress).toBe("203.0.113.7");
+		expect(config.portCounts).toEqual({
+			game: 1,
+			media: 32,
+		});
+	});
+
+	test("ignores a malformed public address and drops non-numeric counts", () => {
+		const config = parseConfig(
+			written({
+				publicAddress: 7,
+				portCounts: {
+					media: "32",
+					game: 1,
+				},
+			}),
+		);
+
+		expect(config.publicAddress).toBeUndefined();
+		expect(config.portCounts).toEqual({
+			game: 1,
+		});
+	});
+
+	test("still refuses a game that would run as root", () => {
+		expect(() =>
+			parseConfig(
+				written({
+					gameUid: 0,
+				}),
+			),
+		).toThrow(BridgeConfigError);
+	});
+});

package/src/runtime/bridgeConfigReader.ts

@@ -70,6 +70,24 @@ const stringRecord = (source: Record<string, unknown>, key: string) => {
 	return out;
 };
 
+const optionalString = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (typeof value !== "string" || value.length === 0) {
+		return;
+	}
+
+	return value;
+};
+
+const optionalNumberRecord = (source: Record<string, unknown>, key: string) => {
+	if (source[key] === undefined) {
+		return;
+	}
+
+	return numberRecord(source, key);
+};
+
 export const configPath = () => {
 	return `${BRIDGE_RUN_MOUNT}/${BRIDGE_CONFIG_NAME}`;
 };
@@ -97,6 +115,8 @@ export const parseConfig = (text: string): BridgeConfig => {
 		cwd: requireString(source, "cwd"),
 		run: requireString(source, "run"),
 		ports: numberRecord(source, "ports"),
+		portCounts: optionalNumberRecord(source, "portCounts"),
+		publicAddress: optionalString(source, "publicAddress"),
 		memoryMb: requireNumber(source, "memoryMb"),
 		cpuPercent: requireNumber(source, "cpuPercent"),
 		gameUid: requireNumber(source, "gameUid"),

package/src/runtime/bridgeContext.test.ts

@@ -0,0 +1,241 @@
+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 { createContext } from "./bridgeContext";
+import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { log } from "./bridgeLog";
+import { createSupervisor } from "./bridgeSupervisor";
+
+describe("the context's variable maps", () => {
+	let directory = "";
+	let path = "";
+
+	const configWith = (variables: Record<string, string>, secrets: Record<string, string>): BridgeConfig => ({
+		code: "abcdef",
+		token: "token",
+		cwd: directory,
+		run: join(directory, "run"),
+		ports: {},
+		memoryMb: 512,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables,
+		secrets,
+	});
+
+	beforeEach(async () => {
+		directory = await mkdtemp(join(tmpdir(), "bridge-context-"));
+		path = join(directory, "config.json");
+	});
+
+	afterEach(async () => {
+		await rm(directory, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("hand a driver every variable and secret the agent wrote, and follow a rewrite", async () => {
+		const boot = configWith(
+			{
+				MY_VAR: "1",
+			},
+			{
+				DISCORD_TOKEN: "sealed",
+			},
+		);
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const live = createBridgeLiveConfig(path, boot, 60_000);
+		const supervisor = createSupervisor({
+			cwd: directory,
+			uid: 1000,
+			gid: 1000,
+			stopTimeoutSeconds: 1,
+			onLog: log,
+			resolveCommand: async () => [
+				"run",
+			],
+		});
+		const context = createContext(
+			boot,
+			supervisor,
+			{
+				onLog: log,
+				onEmit() {
+					return;
+				},
+				onSetup() {
+					return;
+				},
+				async onRestart() {
+					return;
+				},
+			},
+			live,
+		);
+
+		expect(context.variables()).toEqual({
+			MY_VAR: "1",
+		});
+		expect(context.secrets()).toEqual({
+			DISCORD_TOKEN: "sealed",
+		});
+
+		await writeFile(
+			path,
+			JSON.stringify(
+				configWith(
+					{
+						MY_VAR: "2",
+						LOG_LEVEL: "debug",
+					},
+					{},
+				),
+			),
+		);
+
+		live.reload();
+
+		expect(context.variables()).toEqual({
+			MY_VAR: "2",
+			LOG_LEVEL: "debug",
+		});
+		expect(context.secrets()).toEqual({});
+		expect(context.variable("LOG_LEVEL")).toBe("debug");
+	});
+});
+
+describe("the context's ports and address", () => {
+	let directory = "";
+	let path = "";
+
+	const configWith = (extra: Partial<BridgeConfig>): BridgeConfig => ({
+		code: "abcdef",
+		token: "token",
+		cwd: directory,
+		run: join(directory, "run"),
+		ports: {
+			game: 19_140,
+			media: 20_064,
+		},
+		memoryMb: 512,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables: {},
+		secrets: {},
+		...extra,
+	});
+
+	const contextOf = (boot: BridgeConfig) => {
+		const live = createBridgeLiveConfig(path, boot, 60_000);
+		const supervisor = createSupervisor({
+			cwd: directory,
+			uid: 1000,
+			gid: 1000,
+			stopTimeoutSeconds: 1,
+			onLog: log,
+			resolveCommand: async () => [
+				"run",
+			],
+		});
+
+		return {
+			live,
+			context: createContext(
+				boot,
+				supervisor,
+				{
+					onLog: log,
+					onEmit() {
+						return;
+					},
+					onSetup() {
+						return;
+					},
+					async onRestart() {
+						return;
+					},
+				},
+				live,
+			),
+		};
+	};
+
+	beforeEach(async () => {
+		directory = await mkdtemp(join(tmpdir(), "bridge-context-ports-"));
+		path = join(directory, "config.json");
+	});
+
+	afterEach(async () => {
+		await rm(directory, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("hand a driver the block the agent published and its public address", async () => {
+		const boot = configWith({
+			portCounts: {
+				game: 1,
+				media: 32,
+			},
+			publicAddress: "203.0.113.7",
+		});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.portBlock("media")).toEqual({
+			first: 20_064,
+			count: 32,
+		});
+		expect(context.portBlock("game")).toEqual({
+			first: 19_140,
+			count: 1,
+		});
+		expect(context.server.publicAddress).toBe("203.0.113.7");
+	});
+
+	test("treat every port as a single one and the address as unknown for a file an older agent wrote", async () => {
+		const boot = configWith({});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.portBlock("media")).toEqual({
+			first: 20_064,
+			count: 1,
+		});
+		expect(context.server.publicAddress).toBeNull();
+		expect(() => context.portBlock("query")).toThrow('this game declares no port named "query"');
+	});
+
+	test("follow a rewrite of the public address", async () => {
+		const boot = configWith({});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context, live } = contextOf(boot);
+
+		await writeFile(
+			path,
+			JSON.stringify(
+				configWith({
+					publicAddress: "198.51.100.4",
+				}),
+			),
+		);
+
+		live.reload();
+
+		expect(context.server.publicAddress).toBe("198.51.100.4");
+	});
+});

package/src/runtime/bridgeContext.ts

@@ -7,7 +7,7 @@ import { configPath } from "./bridgeConfigReader";
 import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
-import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { type BridgeLiveConfig, createBridgeLiveConfig } from "./bridgeLiveConfig";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
@@ -18,17 +18,17 @@ export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
 	onSetup: (runtime: BridgeSetupRuntime | null) => void;
+	onRestart: () => Promise<void>;
 }
 
 export const createContext = (
 	config: BridgeConfig,
 	supervisor: BridgeSupervisor,
 	hooks: ContextHooks,
+	live: BridgeLiveConfig = createBridgeLiveConfig(configPath(), config),
 ): BridgeContext => {
 	const egress = createBridgeEgress(config);
 
-	const live = createBridgeLiveConfig(configPath(), config);
-
 	const files = createBridgeFiles({
 		root: config.cwd,
 		uid: config.gameUid,
@@ -37,6 +37,16 @@ export const createContext = (
 		onLog: hooks.onLog,
 	});
 
+	const portOf = (key: string) => {
+		const value = config.ports[key];
+
+		if (value === undefined) {
+			throw new Error(`this game declares no port named "${key}"`);
+		}
+
+		return value;
+	};
+
 	return {
 		server: {
 			code: config.code,
@@ -49,24 +59,36 @@ export const createContext = (
 			get running() {
 				return supervisor.running;
 			},
+			get publicAddress() {
+				return live.publicAddress();
+			},
 		},
 
 		variable(key) {
 			return live.variable(key);
 		},
 
+		variables() {
+			return live.variables();
+		},
+
 		secret(key) {
 			return live.secret(key);
 		},
 
-		port(key) {
-			const value = config.ports[key];
+		secrets() {
+			return live.secrets();
+		},
 
-			if (value === undefined) {
-				throw new Error(`this game declares no port named "${key}"`);
-			}
+		port(key) {
+			return portOf(key);
+		},
 
-			return value;
+		portBlock(key) {
+			return {
+				first: portOf(key),
+				count: config.portCounts?.[key] ?? 1,
+			};
 		},
 
 		files,
@@ -123,6 +145,10 @@ export const createContext = (
 			hooks.onEmit(event, payload);
 		},
 
+		async restart() {
+			await hooks.onRestart();
+		},
+
 		log: Object.assign(
 			(message: string, fields?: BridgeValues) => {
 				hooks.onLog(message, {

package/src/runtime/bridgeDriver.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { BridgeKind, BridgeSetupStepKind, PortJoin, PortProtocol } from "../core";
 import { GuideOpenTab } from "../guides";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
-import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
+import {
+	type BridgeDriver,
+	BridgeLifecycleSubject,
+	type BridgePendingModule,
+	type BridgeSetupModule,
+	BridgeStopSignal,
+} from "../modules";
 import {
 	BridgeConfirm,
 	BridgeControl,
@@ -235,6 +241,7 @@ const port = (activeWhen: ManifestPortActivation[]): ManifestPort => ({
 	join: PortJoin.Combined,
 	activeWhen,
 	mirror: false,
+	count: 1,
 });
 
 const driverWithTabs = (tabs: number, sections: number): BridgeDriver => ({
@@ -1781,3 +1788,127 @@ describe("section placement", () => {
 		);
 	});
 });
+
+describe("the lifecycle module", () => {
+	const lifecycleDriver = (lifecycle: Record<string, unknown>): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+			...lifecycle,
+		},
+	});
+
+	test("accepts an environment resolver", () => {
+		expect(() =>
+			validateDriver(
+				lifecycleDriver({
+					environment: async () => ({
+						BOT_TOKEN: "token",
+					}),
+				}),
+			),
+		).not.toThrow();
+	});
+
+	test("accepts a lifecycle that declares no environment", () => {
+		expect(() => validateDriver(lifecycleDriver({}))).not.toThrow();
+	});
+
+	test("accepts each stop signal the bridge sends", () => {
+		for (const stopSignal of Object.values(BridgeStopSignal)) {
+			expect(() =>
+				validateDriver(
+					lifecycleDriver({
+						stopSignal,
+					}),
+				),
+			).not.toThrow();
+		}
+	});
+
+	test("refuses a stop signal the bridge does not send", () => {
+		expect(() =>
+			validateDriver(
+				lifecycleDriver({
+					stopSignal: "SIGHUP",
+				}),
+			),
+		).toThrow('the lifecycle module declares stop signal "SIGHUP" — the bridge sends only SIGTERM or SIGINT');
+	});
+
+	test("accepts a ready timeout from one second to an hour", () => {
+		for (const readyTimeoutSeconds of [
+			1,
+			900,
+			3600,
+		]) {
+			expect(() =>
+				validateDriver(
+					lifecycleDriver({
+						readyTimeoutSeconds,
+					}),
+				),
+			).not.toThrow();
+		}
+	});
+
+	test("refuses a ready timeout outside one second to an hour", () => {
+		for (const readyTimeoutSeconds of [
+			0,
+			3601,
+			1.5,
+		]) {
+			expect(() =>
+				validateDriver(
+					lifecycleDriver({
+						readyTimeoutSeconds,
+					}),
+				),
+			).toThrow(
+				`the lifecycle module declares a ready timeout of ${readyTimeoutSeconds} seconds — it must be a whole number from 1 to 3600`,
+			);
+		}
+	});
+
+	test("accepts each lifecycle subject the bridge names", () => {
+		for (const subject of Object.values(BridgeLifecycleSubject)) {
+			expect(() =>
+				validateDriver(
+					lifecycleDriver({
+						subject,
+					}),
+				),
+			).not.toThrow();
+		}
+	});
+
+	test("refuses a lifecycle subject the bridge does not name", () => {
+		expect(() =>
+			validateDriver(
+				lifecycleDriver({
+					subject: "server",
+				}),
+			),
+		).toThrow('the lifecycle module declares subject "server" — the bridge names only game or bot');
+	});
+
+	test("refuses an environment that is not a function", () => {
+		expect(() =>
+			validateDriver(
+				lifecycleDriver({
+					environment: {
+						BOT_TOKEN: "token",
+					},
+				}),
+			),
+		).toThrow("the lifecycle module declares an environment that is not a function");
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -7,7 +7,14 @@ import {
 } from "../core";
 import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
-import type { BridgeDriver, BridgePanelModule } from "../modules";
+import {
+	type BridgeDriver,
+	BridgeLifecycleSubject,
+	type BridgePanelModule,
+	BridgeStopSignal,
+	isBridgeLifecycleSubject,
+	isBridgeStopSignal,
+} from "../modules";
 import {
 	BridgeControl,
 	type BridgeField,
@@ -50,6 +57,10 @@ import { actionsOf } from "./bridgeActions";
 
 const UPLOAD_MODES = new Set<string>(Object.values(BridgeUploadMode));
 
+const READY_TIMEOUT_MIN_SECONDS = 1;
+
+const READY_TIMEOUT_MAX_SECONDS = 3600;
+
 const RESERVED_MODULE_IDS = new Set([
 	"announce",
 	"backup",
@@ -591,6 +602,47 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 	}
 };
 
+const validateLifecycle = (driver: BridgeDriver) => {
+	const environment: unknown = driver.lifecycle.environment;
+
+	if (environment !== undefined && typeof environment !== "function") {
+		fail(
+			"the lifecycle module declares an environment that is not a function — it must resolve the variables the process starts with",
+		);
+	}
+
+	const stopSignal: unknown = driver.lifecycle.stopSignal;
+
+	if (stopSignal !== undefined && !isBridgeStopSignal(stopSignal)) {
+		fail(
+			`the lifecycle module declares stop signal "${String(stopSignal)}" — the bridge sends only ${Object.values(BridgeStopSignal).join(" or ")}`,
+		);
+	}
+
+	const readyTimeoutSeconds: unknown = driver.lifecycle.readyTimeoutSeconds;
+
+	if (
+		readyTimeoutSeconds !== undefined
+		&& !(
+			Number.isInteger(readyTimeoutSeconds)
+			&& (readyTimeoutSeconds as number) >= READY_TIMEOUT_MIN_SECONDS
+			&& (readyTimeoutSeconds as number) <= READY_TIMEOUT_MAX_SECONDS
+		)
+	) {
+		fail(
+			`the lifecycle module declares a ready timeout of ${String(readyTimeoutSeconds)} seconds — it must be a whole number from ${READY_TIMEOUT_MIN_SECONDS} to ${READY_TIMEOUT_MAX_SECONDS}`,
+		);
+	}
+
+	const subject: unknown = driver.lifecycle.subject;
+
+	if (subject !== undefined && !isBridgeLifecycleSubject(subject)) {
+		fail(
+			`the lifecycle module declares subject "${String(subject)}" — the bridge names only ${Object.values(BridgeLifecycleSubject).join(" or ")}`,
+		);
+	}
+};
+
 const validatePending = (driver: BridgeDriver) => {
 	const pending = driver.pending;
 
@@ -732,6 +784,7 @@ export const validateDriver = (driver: BridgeDriver) => {
 
 	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
 
+	validateLifecycle(driver);
 	validatePending(driver);
 	validateSetup(driver);