@serverkgg/bridge 0.0.14 → 0.0.16

package/src/runtime/bridgeDriver.test.ts

@@ -9,8 +9,10 @@ import {
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
+	BridgePlace,
 	type BridgeSectionAction,
 	type BridgeSectionUpload,
+	type BridgeTableSection,
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
@@ -1636,3 +1638,146 @@ describe("field patterns", () => {
 		).toThrow("is a secret control with options — a secret is typed, never chosen from a list");
 	});
 });
+
+describe("section placement", () => {
+	const anyVisibleWhen: BridgeVisibleWhen = {
+		variable: "MODPACK",
+		empty: true,
+	};
+
+	const driverWithRoster = (section: Partial<BridgeTableSection>): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules: {
+			players: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+				actions: {
+					ban: async () => {
+						return;
+					},
+				},
+			},
+		},
+		panel: {
+			tabs: [
+				{
+					id: "roster",
+					title: text("Roster"),
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "online",
+							module: "players",
+							columns: [
+								{
+									key: "name",
+									label: text("Name"),
+								},
+							],
+							...section,
+						},
+					],
+				},
+			],
+		},
+	});
+
+	const placedForm = (place: BridgePlace): BridgeDriver => {
+		const driver = driverWith(anyVisibleWhen);
+
+		Object.assign(formSectionOf(driver), {
+			place,
+		});
+
+		return driver;
+	};
+
+	test("accepts a table placed on the players page", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Players,
+				}),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a form placed on the players page", () => {
+		expect(() => validateDriver(placedForm(BridgePlace.Players))).toThrow(
+			'tab "version" section "version" places a form section on players, which that page cannot render',
+		);
+	});
+
+	test("rejects a form placed on the overview page", () => {
+		expect(() => validateDriver(placedForm(BridgePlace.Overview))).toThrow(
+			"places a form section on overview, which that page cannot render",
+		);
+	});
+
+	test("rejects a table placed on the overview page", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Overview,
+				}),
+			),
+		).toThrow('tab "roster" section "online" places a table section on overview, which that page cannot render');
+	});
+
+	test("accepts an offline row action on a table", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Players,
+					actions: [
+						{
+							id: "ban",
+							label: text("Ban"),
+							offline: true,
+						},
+					],
+				}),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects an offline action on an actions section", () => {
+		expect(() =>
+			validateDriver(
+				driverWithActions([
+					{
+						id: "say",
+						label: text("Say"),
+						offline: true,
+					},
+				]),
+			),
+		).toThrow(
+			'tab "gameplay" section "broadcast" action "say" is offline-only, which only a table or cards row action can be',
+		);
+	});
+
+	test("rejects a form help that is missing a locale", () => {
+		const driver = driverWith(anyVisibleWhen);
+
+		formSectionOf(driver).help = {
+			ar: "",
+			en: "The version the server runs",
+		};
+
+		expect(() => validateDriver(driver)).toThrow(
+			'tab "version" section "version" help needs both arabic and english text',
+		);
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -13,6 +13,7 @@ import {
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
+	BridgePlace,
 	type BridgeSection,
 	type BridgeSectionAction,
 	type BridgeTab,
@@ -333,12 +334,53 @@ const validateActions = (modules: Record<string, BridgePanelModule>, actions: Br
 	}
 };
 
+const PLACE_LAYOUTS: Record<BridgePlace, BridgeLayout[]> = {
+	[BridgePlace.Overview]: [
+		BridgeLayout.Actions,
+		BridgeLayout.Detail,
+	],
+	[BridgePlace.Players]: [
+		BridgeLayout.Actions,
+		BridgeLayout.Cards,
+		BridgeLayout.Table,
+	],
+};
+
+const validatePlace = (section: BridgeSection, where: string) => {
+	const place = "place" in section ? section.place : undefined;
+
+	if (place === undefined) {
+		return;
+	}
+
+	if (!(PLACE_LAYOUTS[place] ?? []).includes(section.layout)) {
+		fail(`${where} places a ${section.layout} section on ${place}, which that page cannot render`);
+	}
+};
+
+const validateOffline = (section: BridgeSection, where: string) => {
+	if (section.layout === BridgeLayout.Table || section.layout === BridgeLayout.Cards) {
+		return;
+	}
+
+	const actions = "actions" in section ? (section.actions ?? []) : [];
+
+	for (const action of actions) {
+		if (action.offline !== undefined) {
+			fail(`${where} action "${action.id}" is offline-only, which only a table or cards row action can be`);
+		}
+	}
+};
+
 const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
 	validateVisibleWhen(section.visibleWhen, where);
 	validateText(section.title, "title", where);
+	validateText(section.help, "help", where);
+	validatePlace(section, where);
+	validateOffline(section, where);
 
-	if (section.layout !== BridgeLayout.Form) {
-		validateText(section.layout === BridgeLayout.Actions ? section.help : section.empty, "text", where);
+	if (section.layout !== BridgeLayout.Form && section.layout !== BridgeLayout.Actions) {
+		validateText(section.empty, "empty text", where);
 	}
 
 	switch (section.layout) {

package/src/runtime/bridgeEvents.test.ts

@@ -4,8 +4,8 @@ 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 { BridgeCrashPhase, type BridgeCrashRecord, BridgeEventName } from "../protocol";
+import { type BridgeEventRing, createEventRing } from "./bridgeEvents";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createSupervisor } from "./bridgeSupervisor";
 
@@ -13,6 +13,10 @@ const RESET = "\u001B[m";
 
 const PLAYER_JOINED = /^\[World\|(?<world>[^\]]+)\] Player '(?<player>[^']+)' joined world (?<target>\S+)$/;
 
+const MOD_CRASHED = /^Exception in mod (?<mod>\S+) from (?<jar>\S+)$/;
+
+const READY_LINE = /^ready$/;
+
 const silent: BridgeLeveledLogger = Object.assign(() => {}, {
 	warn: () => {},
 	error: () => {},
@@ -25,16 +29,18 @@ const events: BridgeEventsModule = {
 			match: PLAYER_JOINED,
 			emit: BridgeEventName.PlayerJoined,
 		},
+		{
+			match: MOD_CRASHED,
+			emit: BridgeEventName.ModCrashed,
+		},
+	],
+	emits: [
+		BridgeEventName.WorldCorrupt,
 	],
 };
 
-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({
+const lineSupervisor = (dir: string, path: string) => {
+	return createSupervisor({
 		cwd: dir,
 		uid: process.getuid?.() ?? 0,
 		gid: process.getgid?.() ?? 0,
@@ -47,7 +53,15 @@ const emittedFor = async (line: string) => {
 			path,
 		],
 	});
+};
+
+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 = lineSupervisor(dir, path);
 	const ring = createEventRing(events, supervisor);
 
 	await supervisor.start();
@@ -71,6 +85,72 @@ const emittedFor = async (line: string) => {
 	}
 };
 
+const crashAfter = async (line: string, record: BridgeCrashRecord) => {
+	const dir = await mkdtemp(join(tmpdir(), "bridge-events-"));
+	const path = join(dir, "line.txt");
+
+	await Bun.write(path, `${line}\n`);
+
+	const supervisor = lineSupervisor(dir, path);
+	const ring = createEventRing(events, supervisor);
+
+	await supervisor.start();
+
+	try {
+		for (let waited = 0; waited < 5000; waited += 50) {
+			if (supervisor.tail(50).includes(line)) {
+				break;
+			}
+
+			await Bun.sleep(50);
+		}
+
+		const held = ring.drain(0).events;
+
+		ring.crash(record);
+
+		return {
+			held,
+			events: ring.drain(0).events,
+		};
+	} finally {
+		await supervisor.stop();
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	}
+};
+
+const idleRing = () => {
+	const supervisor = createSupervisor({
+		cwd: tmpdir(),
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds: 1,
+		onLog: silent,
+		resolveCommand: async () => [
+			"true",
+		],
+	});
+
+	return createEventRing(events, supervisor);
+};
+
+const crashRecord = (overrides: Partial<BridgeCrashRecord> = {}): BridgeCrashRecord => {
+	return {
+		exitCode: 1,
+		outOfMemory: false,
+		phase: BridgeCrashPhase.Running,
+		uptimeSeconds: 12,
+		restarting: false,
+		looping: false,
+		restarts: 0,
+		lastLine: null,
+		...overrides,
+	};
+};
+
 const joined = {
 	seq: 1,
 	event: BridgeEventName.PlayerJoined,
@@ -93,4 +173,326 @@ describe("matching a game line against the driver patterns", () => {
 			joined,
 		]);
 	});
+
+	test("holds a matched diagnostic line as evidence and spends it on the crash record", async () => {
+		const { held, events: drained } = await crashAfter(
+			"Exception in mod journeymap from journeymap-5.9.jar",
+			crashRecord({
+				exitCode: 1,
+				phase: BridgeCrashPhase.Booting,
+			}),
+		);
+
+		expect(held, "the diagnostic line reached the ring as a standalone event").toEqual([]);
+		expect(drained).toEqual([
+			{
+				seq: 1,
+				event: BridgeEventName.ServerCrashed,
+				payload: {
+					mod: "journeymap",
+					jar: "journeymap-5.9.jar",
+					cause: "mod-crashed",
+					phase: "booting",
+					exitCode: "1",
+					restarting: "no",
+					looping: "no",
+					restarts: "0",
+					uptimeSeconds: "12",
+				},
+			},
+		]);
+	}, 20_000);
+});
+
+describe("the crash record the ring builds", () => {
+	test("holds evidence out of the ring and lets every other event drain", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			jar: "broken.jar",
+		});
+
+		ring.emit(BridgeEventName.TickLagging, {
+			ms: 900,
+		});
+
+		expect(ring.drain(0).events.map((entry) => entry.event)).toEqual([
+			BridgeEventName.TickLagging,
+		]);
+	});
+
+	test("prefers the oom kill over any evidence it holds", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			jar: "broken.jar",
+		});
+
+		ring.crash(
+			crashRecord({
+				exitCode: 137,
+				outOfMemory: true,
+			}),
+		);
+
+		expect(ring.drain(0).events.at(0)?.payload).toEqual({
+			cause: "oom-kill",
+			phase: "running",
+			exitCode: "137",
+			restarting: "no",
+			looping: "no",
+			restarts: "0",
+			uptimeSeconds: "12",
+		});
+	});
+
+	test("follows the evidence precedence when more than one name is held", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			jar: "broken.jar",
+		});
+
+		ring.emit(BridgeEventName.WrongJavaVersion, {
+			detail: "class file version 65",
+		});
+
+		ring.crash(crashRecord());
+
+		expect(ring.drain(0).events.at(0)?.payload).toEqual({
+			detail: "class file version 65",
+			cause: "wrong-java",
+			phase: "running",
+			exitCode: "1",
+			restarting: "no",
+			looping: "no",
+			restarts: "0",
+			uptimeSeconds: "12",
+		});
+	});
+
+	test("lets the out of memory log pattern outrank the java version", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.WrongJavaVersion, {
+			detail: "class file version 65",
+		});
+
+		ring.emit(BridgeEventName.ServerCrashed, {
+			error: "java.lang.OutOfMemoryError",
+		});
+
+		ring.crash(crashRecord());
+
+		expect(ring.drain(0).events.at(0)?.payload).toMatchObject({
+			cause: "out-of-memory",
+			error: "java.lang.OutOfMemoryError",
+		});
+	});
+
+	test("never lets the evidence overwrite the record keys", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			cause: "not this one",
+			phase: "not this one either",
+		});
+
+		ring.crash(
+			crashRecord({
+				phase: BridgeCrashPhase.Booting,
+			}),
+		);
+
+		expect(ring.drain(0).events.at(0)?.payload).toMatchObject({
+			cause: "mod-crashed",
+			phase: "booting",
+		});
+	});
+
+	test("clears the evidence once it is spent", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			jar: "broken.jar",
+		});
+
+		ring.crash(crashRecord());
+
+		const first = ring.drain(0);
+
+		ring.crash(crashRecord());
+
+		expect(first.events.at(0)?.payload).toMatchObject({
+			cause: "mod-crashed",
+		});
+
+		expect(ring.drain(first.cursor).events.at(0)?.payload).toMatchObject({
+			cause: "unknown",
+		});
+	});
+
+	test("carries the last line only when nothing explains the crash", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.ModCrashed, {
+			jar: "broken.jar",
+		});
+
+		ring.crash(
+			crashRecord({
+				lastLine: "explained, so this line is noise",
+			}),
+		);
+
+		const explained = ring.drain(0);
+
+		ring.crash(
+			crashRecord({
+				lastLine: "Segmentation fault",
+			}),
+		);
+
+		expect(explained.events.at(0)?.payload).not.toHaveProperty("lastLine");
+		expect(ring.drain(explained.cursor).events.at(0)?.payload).toMatchObject({
+			cause: "unknown",
+			lastLine: "Segmentation fault",
+		});
+	});
+
+	test("keeps listing the evidence names the driver declares", () => {
+		expect(idleRing().names()).toEqual([
+			BridgeEventName.PlayerJoined,
+			BridgeEventName.ModCrashed,
+			BridgeEventName.WorldCorrupt,
+		]);
+	});
+});
+
+const EVIDENCE_LINE = "Exception in mod journeymap from journeymap-5.9.jar";
+
+const EVIDENCE_BEFORE_READY = `echo "${EVIDENCE_LINE}"; sleep 0.3; echo ready; sleep 0.5; exit 4`;
+
+const EVIDENCE_AFTER_READY = `echo ready; sleep 0.3; echo "${EVIDENCE_LINE}"; sleep 0.5; exit 4`;
+
+const EVIDENCE_THEN_IDLE = `echo "${EVIDENCE_LINE}"; sleep 300`;
+
+const wired = async (script: string, ready?: RegExp) => {
+	const dir = await mkdtemp(join(tmpdir(), "bridge-events-"));
+
+	const supervisor = createSupervisor({
+		cwd: dir,
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds: 1,
+		ready,
+		onLog: silent,
+		resolveCommand: async () => [
+			"bash",
+			"-c",
+			script,
+		],
+		onStable() {
+			ring.discard();
+		},
+		onStopped() {
+			ring.discard();
+		},
+		onExit(record) {
+			ring.crash(record);
+		},
+	});
+
+	const ring = createEventRing(events, supervisor);
+
+	return {
+		supervisor,
+		ring,
+		async cleanup() {
+			await supervisor.stop();
+			await rm(dir, {
+				force: true,
+				recursive: true,
+			});
+		},
+	};
+};
+
+const crashedEvent = async (ring: BridgeEventRing) => {
+	for (let waited = 0; waited < 10_000; waited += 50) {
+		const found = ring.drain(0).events.find((entry) => entry.event === BridgeEventName.ServerCrashed);
+
+		if (found) {
+			return found;
+		}
+
+		await Bun.sleep(50);
+	}
+
+	return null;
+};
+
+describe("the evidence a run may spend", () => {
+	test("spends nothing printed before the run became stable on a running crash", async () => {
+		const wiring = await wired(EVIDENCE_BEFORE_READY, READY_LINE);
+
+		await wiring.supervisor.start();
+
+		try {
+			const crashed = await crashedEvent(wiring.ring);
+
+			expect(crashed?.payload).toMatchObject({
+				cause: "unknown",
+				phase: "running",
+			});
+
+			expect(crashed?.payload).not.toHaveProperty("jar");
+		} finally {
+			await wiring.cleanup();
+		}
+	}, 20_000);
+
+	test("spends what the run printed after it became stable", async () => {
+		const wiring = await wired(EVIDENCE_AFTER_READY, READY_LINE);
+
+		await wiring.supervisor.start();
+
+		try {
+			const crashed = await crashedEvent(wiring.ring);
+
+			expect(crashed?.payload).toMatchObject({
+				cause: "mod-crashed",
+				phase: "running",
+				jar: "journeymap-5.9.jar",
+			});
+		} finally {
+			await wiring.cleanup();
+		}
+	}, 20_000);
+
+	test("drops what it holds when the stop was requested", async () => {
+		const wiring = await wired(EVIDENCE_THEN_IDLE);
+
+		await wiring.supervisor.start();
+
+		try {
+			for (let waited = 0; waited < 5000; waited += 50) {
+				if (wiring.supervisor.tail(50).includes(EVIDENCE_LINE)) {
+					break;
+				}
+
+				await Bun.sleep(50);
+			}
+
+			await wiring.supervisor.stop();
+
+			wiring.ring.crash(crashRecord());
+
+			expect(wiring.ring.drain(0).events.at(0)?.payload).toMatchObject({
+				cause: "unknown",
+			});
+		} finally {
+			await wiring.cleanup();
+		}
+	}, 20_000);
 });