@serverkgg/bridge 0.0.21 → 0.1.2

package/src/runtime/bridgeContext.ts

@@ -1,5 +1,5 @@
 import type { BridgeContext } from "../context";
-import type { BridgeValues } from "../core";
+import type { BridgeActivity, BridgeValues } from "../core";
 import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
 import { stripAnsi } from "../utils";
 import { createBridgeCodecs } from "./bridgeCodec";
@@ -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,18 @@ export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
 	onSetup: (runtime: BridgeSetupRuntime | null) => void;
+	onActivity: (entry: BridgeActivity) => 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 +38,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 +60,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,
@@ -119,10 +142,20 @@ export const createContext = (
 			},
 		},
 
+		activity: {
+			report(entry) {
+				hooks.onActivity(entry);
+			},
+		},
+
 		emit(event, payload) {
 			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 => ({
@@ -268,6 +275,27 @@ const driverWithTabs = (tabs: number, sections: number): BridgeDriver => ({
 });
 
 describe("panel caps", () => {
+	test("rejects a collection row action named after a read action", () => {
+		const driver = driverWithTabs(1, 1);
+
+		driver.modules = {
+			...driver.modules,
+			worlds: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+				actions: {
+					preview: async () => {
+						return;
+					},
+				},
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow(
+			'module "worlds" declares action "preview", which is reserved for reads',
+		);
+	});
+
 	test("takes the tab and section counts the agent mirror accepts", () => {
 		expect(() => validateDriver(driverWithTabs(8, 8))).not.toThrow();
 	});
@@ -1781,3 +1809,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

@@ -3,11 +3,19 @@ import {
 	BRIDGE_MODULE_ID_PATTERN,
 	BridgeKind,
 	BridgeSetupStepKind,
+	isReadAction,
 	type LocalizedText,
 } 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 +58,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 +603,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 +785,7 @@ export const validateDriver = (driver: BridgeDriver) => {
 
 	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
 
+	validateLifecycle(driver);
 	validatePending(driver);
 	validateSetup(driver);
 
@@ -748,15 +802,17 @@ export const validateDriver = (driver: BridgeDriver) => {
 			countIn((module.dependsOn ?? []).length, BRIDGE_DEPENDS_ON_LIMIT, "dependencies", `module "${id}"`);
 		}
 
-		if (module.kind === BridgeKind.Actions) {
-			for (const action of Object.keys(module.actions)) {
-				validateModuleId(action, `module "${id}" action`);
-			}
-		}
-
-		if (module.kind === BridgeKind.Collection || module.kind === BridgeKind.Detail) {
+		if (
+			module.kind === BridgeKind.Actions
+			|| module.kind === BridgeKind.Collection
+			|| module.kind === BridgeKind.Detail
+		) {
 			for (const action of Object.keys(module.actions ?? {})) {
 				validateModuleId(action, `module "${id}" action`);
+
+				if (isReadAction(action)) {
+					fail(`module "${id}" declares action "${action}", which is reserved for reads — pick another id`);
+				}
 			}
 		}
 	}

package/src/runtime/bridgeFiles.test.ts

@@ -564,6 +564,68 @@ describe("extract", () => {
 		expect(await read("config/beta.json")).toBe("beta");
 	});
 
+	test("keeps dotfiles in a tree when asked and never writes .git or .serverk", async () => {
+		const path = await archive([
+			{
+				name: "bot/.env.example",
+				content: "DISCORD_TOKEN=",
+			},
+			{
+				name: "bot/src/.config/settings.json",
+				content: "{}",
+			},
+			{
+				name: "bot/index.js",
+				content: "run()",
+			},
+			{
+				name: "bot/.git/config",
+				content: "[core]",
+			},
+			{
+				name: "bot/.serverk/deploy-requested",
+				content: "{}",
+			},
+		]);
+
+		const written = await files.extract(path, "", {
+			tree: true,
+			dotfiles: true,
+			select: "bot/",
+		});
+
+		expect(written).toEqual([
+			".env.example",
+			"src/.config/settings.json",
+			"index.js",
+		]);
+
+		expect(await read(".env.example")).toBe("DISCORD_TOKEN=");
+		expect(await files.exists(".git/config")).toBe(false);
+		expect(await files.exists(".serverk/deploy-requested")).toBe(false);
+	});
+
+	test("still skips dotfiles in a tree unless asked", async () => {
+		const path = await archive([
+			{
+				name: ".env.example",
+				content: "DISCORD_TOKEN=",
+			},
+			{
+				name: "index.js",
+				content: "run()",
+			},
+		]);
+
+		const written = await files.extract(path, "", {
+			tree: true,
+		});
+
+		expect(written).toEqual([
+			"index.js",
+		]);
+	});
+
 	test("takes a single named entry when the select carries no trailing slash", async () => {
 		const path = await archive([
 			{

package/src/runtime/bridgeFiles.ts

@@ -152,6 +152,15 @@ const compileSelect = (select: string): ArchiveSelect => {
 	return select.endsWith("/") ? prefixSelect(select) : entrySelect(select);
 };
 
+const ALWAYS_SKIPPED_SEGMENTS: ReadonlySet<string> = new Set([
+	".git",
+	".serverk",
+]);
+
+const hiddenEntry = (segments: string[], dotfiles: boolean) => {
+	return segments.some((segment) => ALWAYS_SKIPPED_SEGMENTS.has(segment) || (!dotfiles && segment.startsWith(".")));
+};
+
 const compileSelects = (select: string | undefined, selects: string[] | undefined) => {
 	const compiled: ArchiveSelect[] = [];
 
@@ -603,6 +612,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			}
 
 			const tree = extractOptions.tree === true;
+			const dotfiles = extractOptions.dotfiles === true;
 			const allowed = extractOptions.extensions?.map((extension) => extension.toLowerCase());
 			const selects = compileSelects(extractOptions.select, extractOptions.selects);
 			const excluded = compileGlobs(extractOptions.exclude ?? []);
@@ -638,7 +648,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 							selected.split("/").at(-1) ?? "",
 						];
 				const name = segments.at(-1) ?? "";
-				if (!name || segments.some((segment) => segment.startsWith("."))) {
+				if (!name || hiddenEntry(segments, dotfiles)) {
 					continue;
 				}
 				if (allowed !== undefined && !allowed.includes(name.split(".").at(-1)?.toLowerCase() ?? "")) {
@@ -677,7 +687,7 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 				const name = segments.at(-1) ?? "";
 				const extension = name.split(".").at(-1)?.toLowerCase() ?? "";
 
-				if (name.length === 0 || segments.some((segment) => segment.startsWith("."))) {
+				if (name.length === 0 || hiddenEntry(segments, dotfiles)) {
 					continue;
 				}
 

package/src/runtime/bridgeLiveConfig.ts

@@ -14,9 +14,13 @@ export const BRIDGE_CONFIG_REFRESH_MS = 2000;
  */
 export interface BridgeLiveConfig {
 	variable: (key: string) => string | null;
+	variables: () => Readonly<Record<string, string>>;
 	secret: (key: string) => string | null;
+	secrets: () => Readonly<Record<string, string>>;
 	memoryMb: () => number;
 	cpuPercent: () => number;
+	publicAddress: () => string | null;
+	reload: () => void;
 }
 
 export const createBridgeLiveConfig = (
@@ -50,14 +54,28 @@ export const createBridgeLiveConfig = (
 		variable(key) {
 			return refresh().variables[key] ?? null;
 		},
+		variables() {
+			return refresh().variables;
+		},
 		secret(key) {
 			return refresh().secrets[key] ?? null;
 		},
+		secrets() {
+			return refresh().secrets;
+		},
 		memoryMb() {
 			return refresh().memoryMb;
 		},
 		cpuPercent() {
 			return refresh().cpuPercent;
 		},
+		publicAddress() {
+			return refresh().publicAddress ?? null;
+		},
+		reload() {
+			checkedAt = null;
+
+			refresh();
+		},
 	};
 };

package/src/runtime/bridgeLog.ts

@@ -36,3 +36,13 @@ export const log: BridgeLeveledLogger = Object.assign(
 export const errorText = (error: unknown) => {
 	return error instanceof Error ? error.message : String(error);
 };
+
+export const errorDetail = (error: unknown) => {
+	const text = errorText(error);
+
+	if (!(error instanceof Error) || error.cause === undefined) {
+		return text;
+	}
+
+	return `${text} — ${errorText(error.cause)}`;
+};