@serverkgg/bridge 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/rules/package.md

@@ -37,6 +37,11 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 - A settings form targets `BridgeFormTarget.Settings` and module `settings`, with a one-sentence `help` and `restartHint: true`.
 - In a game, the roster and moderation tables go on `place: BridgePlace.Players`, metrics on `BridgePlace.Overview`.
 - A setup `Form` step points at an existing panel form by `tab`, `section` and field keys, never redeclaring a field; `Form` and `Open` steps state `required`. A game's setup ends with the `Open` step `invite` targeting `GuideOpenTab.Access`.
+- A preview module that knows the change cannot install answers `blocked: true`, with the reason in `lines`. The panel then shows the lines with a close button only, and the platform refuses the change before it rebuilds anything.
+- `BridgeConfirm.None` runs on the click: reads, downloads, start, stop and restart.
+- `BridgeConfirm.Normal` asks once, for anything the player can come back from: a settings form, a variable flip, a reinstall, a version or type switch, a modpack or mod install, op and deop, kick, ban, whitelist, rotating a password.
+- `BridgeConfirm.Strong` is only for an action with no way back, where no restore point is taken and nothing in the panel brings the state back: deleting a world, save, map or character data, resetting a dimension, a wipe. A protected action takes no restore point.
+- A `Form` or `Catalog` section, a `Preview` answer and any section with `reinstall` are never `Strong`, because the platform takes a restore point first; `serverk-bridge validate` fails on such a section. The web shows `Strong` as a checkbox acknowledgement.
 - Emit event names from `BridgeEventName`, never strings, and list every event raised from code in `emits` (`patterns: []` when none match the log). A bot matches deployments with `DEPLOYMENT_EVENT_PATTERN`.
 - `install.run` runs on every boot: keep it idempotent with `readStamp` and `writeStamp` (`@serverkgg/bridge/install`), the stamp in `files.protected`. A game protects the default `.serverk-install.json`; a bot writes `.serverk/install.json` (`INSTALL_STAMP`, `shared/botRuntime.ts`) and protects `.serverk/**`.
 

package/src/bot/botCauses.test.ts

@@ -0,0 +1,284 @@
+import { describe, expect, it } from "bun:test";
+import { BridgeKind, BridgeStream } from "../core";
+import { BridgeCrashCause, BridgeCrashPhase, type BridgeCrashRecord } from "../protocol";
+import { createEventRing } from "../runtime/bridgeEvents";
+import type { BridgeSupervisor, SupervisorLine } from "../runtime/bridgeSupervisor";
+import { BOT_CRASH_EVIDENCE } from "./botCauses";
+
+const CASES: readonly {
+	line: string;
+	cause: BridgeCrashCause;
+}[] = [
+	{
+		line: "Error [TokenInvalid]: An invalid token was provided.",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "discord.errors.LoginFailure: Improper token has been passed.",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "GrammyError: Call to 'getMe' failed! (401: Unauthorized)",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "telegram.error.InvalidToken: The token `123:abc` was rejected by the server.",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "GrammyError: Call to 'deleteWebhook' failed! (404: Not Found)",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "404: Not Found at https://api.telegram.org/bot***/getMe",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "aiogram.exceptions.TelegramUnauthorizedError: Telegram server says - Unauthorized",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "Error: Used disallowed intents",
+		cause: BridgeCrashCause.IntentsDisallowed,
+	},
+	{
+		line: "Error [DisallowedIntents]: Privileged intent provided is not enabled or whitelisted.",
+		cause: BridgeCrashCause.IntentsDisallowed,
+	},
+	{
+		line: "discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents that have not been explicitly enabled in the developer portal.",
+		cause: BridgeCrashCause.IntentsDisallowed,
+	},
+	{
+		line: "telegram.error.Conflict: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running",
+		cause: BridgeCrashCause.TokenInUse,
+	},
+	{
+		line: "GrammyError: Call to 'getUpdates' failed! (409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running)",
+		cause: BridgeCrashCause.TokenInUse,
+	},
+	{
+		line: "Error: Cannot find module 'discord.js'",
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		line: "Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'telegraf' imported from /home/container/index.js",
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		line: "ModuleNotFoundError: No module named 'discord'",
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		line: "RuntimeError: davey library needed in order to use voice",
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		line: "RuntimeError: PyNaCl library needed in order to use voice",
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		line: "ImportError: cannot import name 'Update' from 'telegram' (/home/container/.venv/lib/python3.12/site-packages/telegram/__init__.py)",
+		cause: BridgeCrashCause.WrongTelegramPackage,
+	},
+	{
+		line: "AttributeError: module 'discord' has no attribute 'Bot'",
+		cause: BridgeCrashCause.WrongDiscordPackage,
+	},
+	{
+		line: "ModuleNotFoundError: No module named 'discord.app_commands'",
+		cause: BridgeCrashCause.WrongDiscordPackage,
+	},
+	{
+		line: "ImportError: cannot import name 'app_commands' from 'discord' (/home/container/.venv/lib/python3.12/site-packages/discord/__init__.py)",
+		cause: BridgeCrashCause.WrongDiscordPackage,
+	},
+	{
+		line: "gyp ERR! stack Error: not found: make",
+		cause: BridgeCrashCause.BuildTools,
+	},
+	{
+		line: "error: command 'gcc' failed: No such file or directory",
+		cause: BridgeCrashCause.BuildTools,
+	},
+	{
+		line: "error: command 'x86_64-linux-gnu-gcc' failed with exit status 1",
+		cause: BridgeCrashCause.BuildTools,
+	},
+	{
+		line: "discord.errors.ClientException: ffmpeg was not found.",
+		cause: BridgeCrashCause.FfmpegMissing,
+	},
+	{
+		line: "Error: spawn ffmpeg ENOENT",
+		cause: BridgeCrashCause.FfmpegMissing,
+	},
+	{
+		line: "ModuleNotFoundError: No module named 'audioop'",
+		cause: BridgeCrashCause.AudioopRemoved,
+	},
+	{
+		line: "discord.errors.HTTPException: 429 Too Many Requests (error code: 0): You are being blocked from accessing our API temporarily due to exceeding our rate limits frequently.",
+		cause: BridgeCrashCause.RateLimited,
+	},
+	{
+		line: "GrammyError: Call to 'sendMessage' failed! (429: Too Many Requests: retry after 5)",
+		cause: BridgeCrashCause.RateLimited,
+	},
+	{
+		line: "error code: 1015",
+		cause: BridgeCrashCause.RateLimited,
+	},
+	{
+		line: "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory",
+		cause: BridgeCrashCause.OutOfMemory,
+	},
+	{
+		line: "FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory",
+		cause: BridgeCrashCause.OutOfMemory,
+	},
+	{
+		line: "MemoryError",
+		cause: BridgeCrashCause.OutOfMemory,
+	},
+];
+
+const recordOf = (overrides: Partial<BridgeCrashRecord> = {}): BridgeCrashRecord => {
+	return {
+		exitCode: 1,
+		outOfMemory: false,
+		phase: BridgeCrashPhase.Booting,
+		uptimeSeconds: 5,
+		restarting: false,
+		looping: false,
+		restarts: 0,
+		lastLine: null,
+		...overrides,
+	};
+};
+
+const botRing = () => {
+	const watchers: ((entry: SupervisorLine) => void)[] = [];
+
+	const supervisor = {
+		subscribe(watcher: (entry: SupervisorLine) => void) {
+			watchers.push(watcher);
+
+			return () => {};
+		},
+	} as unknown as BridgeSupervisor;
+
+	const ring = createEventRing(
+		{
+			kind: BridgeKind.Events,
+			patterns: [
+				...BOT_CRASH_EVIDENCE,
+			],
+		},
+		supervisor,
+	);
+
+	const print = (line: string) => {
+		for (const watcher of watchers) {
+			watcher({
+				stream: BridgeStream.Stderr,
+				line,
+			});
+		}
+	};
+
+	return {
+		ring,
+		print,
+	};
+};
+
+describe("BOT_CRASH_EVIDENCE", () => {
+	for (const item of CASES) {
+		it(`names ${item.cause} from "${item.line}"`, () => {
+			const { ring, print } = botRing();
+
+			print(item.line);
+
+			expect(ring.crash(recordOf())).toBe(item.cause);
+			expect(ring.drain(0).events.at(0)?.payload?.cause).toBe(item.cause);
+		});
+	}
+
+	it("names the removed audioop module before any other missing module", () => {
+		const { ring, print } = botRing();
+
+		print("ModuleNotFoundError: No module named 'audioop'");
+		print("ModuleNotFoundError: No module named 'discord'");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.AudioopRemoved);
+	});
+
+	it("names the wrong discord library before the missing module it shows up as", () => {
+		const { ring, print } = botRing();
+
+		print("ModuleNotFoundError: No module named 'discord.app_commands'");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.WrongDiscordPackage);
+	});
+
+	it("names missing build tools before the missing module they left behind", () => {
+		const { ring, print } = botRing();
+
+		print("gyp ERR! stack Error: not found: make");
+		print("Error: Cannot find module 'better-sqlite3'");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.BuildTools);
+	});
+
+	it("names a missing module before a token the bot never got to use", () => {
+		const { ring, print } = botRing();
+
+		print("GrammyError: Call to 'getMe' failed! (401: Unauthorized)");
+		print("Error: Cannot find module 'grammy'");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.MissingDependency);
+	});
+
+	it("leaves a 404 from a Telegram call that says nothing about the token unexplained", () => {
+		const { ring, print } = botRing();
+
+		print("GrammyError: Call to 'sendMessage' failed! (400: Bad Request: chat not found)");
+		print("GET /assets/logo.png 404: Not Found");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.Unknown);
+	});
+
+	it("leaves a line no library prints unexplained", () => {
+		const { ring, print } = botRing();
+
+		print("TypeError: Cannot read properties of undefined (reading 'send')");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.Unknown);
+	});
+
+	it("calls exit 137 out of memory only when the record carries the flag", () => {
+		const unflagged = botRing();
+
+		expect(
+			unflagged.ring.crash(
+				recordOf({
+					exitCode: 137,
+				}),
+			),
+		).toBe(BridgeCrashCause.Unknown);
+
+		const flagged = botRing();
+
+		flagged.print("Error [TokenInvalid]: An invalid token was provided.");
+
+		expect(
+			flagged.ring.crash(
+				recordOf({
+					exitCode: 137,
+					outOfMemory: true,
+				}),
+			),
+		).toBe(BridgeCrashCause.OomKill);
+	});
+});

package/src/bot/botCauses.ts

@@ -0,0 +1,58 @@
+import type { BridgeEventPattern } from "../modules";
+import { BridgeEventName } from "../protocol";
+
+export const BOT_CRASH_EVIDENCE: readonly BridgeEventPattern[] = [
+	{
+		match:
+			/\[TokenInvalid\]|An invalid token was provided|LoginFailure: Improper token|\b401:? Unauthorized\b|\bInvalidToken\b|TelegramUnauthorizedError/,
+		emit: BridgeEventName.TokenInvalid,
+	},
+	{
+		match:
+			/Call to '(?:getMe|deleteWebhook|getUpdates)' failed! \(404: Not Found\)|\/bot[^/\s]*\/(?:getMe|deleteWebhook|getUpdates)\b.*\b404:? Not Found\b|\b404:? Not Found\b.*\/bot[^/\s]*\/(?:getMe|deleteWebhook|getUpdates)\b/,
+		emit: BridgeEventName.TokenInvalid,
+	},
+	{
+		match: /Used disallowed intents|\[DisallowedIntents\]|PrivilegedIntentsRequired|close code:? 4014\b/,
+		emit: BridgeEventName.IntentsDisallowed,
+	},
+	{
+		match: /terminated by other getUpdates request|\b409:? Conflict\b/,
+		emit: BridgeEventName.TokenInUse,
+	},
+	{
+		match:
+			/Cannot find module|ERR_MODULE_NOT_FOUND|ModuleNotFoundError: No module named|(?:davey|PyNaCl) library needed in order to use voice/,
+		emit: BridgeEventName.MissingDependency,
+	},
+	{
+		match: /ImportError: cannot import name .+ from 'telegram'/,
+		emit: BridgeEventName.WrongTelegramPackage,
+	},
+	{
+		match:
+			/AttributeError: module 'discord' has no attribute 'Bot'|No module named 'discord\.app_commands'|ImportError: cannot import name 'app_commands' from 'discord'/,
+		emit: BridgeEventName.WrongDiscordPackage,
+	},
+	{
+		match: /gyp ERR!|error: command '(?:[\w.-]+-)?gcc' failed/,
+		emit: BridgeEventName.BuildToolsMissing,
+	},
+	{
+		match: /ffmpeg was not found|\bENOENT\b.*\bffmpeg\b|\bffmpeg\b.*\bENOENT\b/i,
+		emit: BridgeEventName.FfmpegMissing,
+	},
+	{
+		match: /No module named 'audioop'/,
+		emit: BridgeEventName.AudioopRemoved,
+	},
+	{
+		match: /\b429:? Too Many Requests\b|\berror code:? 1015\b|\bError 1015\b|You are being rate limited/i,
+		emit: BridgeEventName.RateLimited,
+	},
+	{
+		match:
+			/FATAL ERROR: (?:Reached heap limit|Ineffective mark-compacts near heap limit) Allocation failed - JavaScript heap out of memory|^MemoryError\b/,
+		emit: BridgeEventName.ServerCrashed,
+	},
+];

package/src/bot/botDeploy.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from "bun:test";
 import type { BridgeValues } from "../core";
-import { BridgeEventName } from "../protocol";
+import { BridgeCrashCause, BridgeCrashPhase, type BridgeCrashReport, BridgeEventName } from "../protocol";
 import {
+	BOT_READY_GRACE_SECONDS,
+	createBotReadiness,
 	DEPLOY_MARKER,
 	DEPLOY_MARKER_DRAFT,
 	DEPLOYMENT_EVENT_PATTERN,
@@ -9,6 +11,7 @@ import {
 	type DeployMarker,
 	deploymentLine,
 	deployPending,
+	pendingDeploymentOf,
 	requestDeploy,
 } from "./botDeploy";
 import { BotDeploymentOutcome, BotDeploymentSource, BotDeploymentStage, DEPLOYMENT_STATE_FILE } from "./botState";
@@ -361,3 +364,259 @@ describe("deployPending", () => {
 		expect(await deployPending(stopped.context)).toBe(false);
 	});
 });
+
+const LIVE_AT = Date.parse("2026-09-27T10:00:00.000Z");
+
+const LAUNCHED_BEFORE = LIVE_AT - 60_000;
+
+const LAUNCHED_AFTER = LIVE_AT + 60_000;
+
+const reportOf = (overrides: Partial<BridgeCrashReport> = {}): BridgeCrashReport => {
+	return {
+		cause: BridgeCrashCause.TokenInvalid,
+		exitCode: 1,
+		outOfMemory: false,
+		phase: BridgeCrashPhase.Booting,
+		uptimeSeconds: 5,
+		restarting: false,
+		looping: false,
+		restarts: 0,
+		lastLine: null,
+		...overrides,
+	};
+};
+
+const readyBot = async (launchedAt: number) => {
+	const deploy = deployContext(true, liveState("dep_a1b2c3d4"));
+	const readiness = createBotReadiness();
+
+	readiness.launching(launchedAt);
+
+	await readiness.ready(deploy.context);
+
+	return {
+		...deploy,
+		readiness,
+	};
+};
+
+describe("createBotReadiness", () => {
+	it("waits twenty seconds for a bot to prove it is ready", () => {
+		expect(BOT_READY_GRACE_SECONDS).toBe(20);
+	});
+
+	it("reports the deployment ready once the bot is stable, never when the launcher hands over", async () => {
+		const { context, emitted, stored, readiness } = await readyBot(LAUNCHED_BEFORE);
+
+		expect(emitted).toEqual([]);
+
+		await readiness.stable(context);
+
+		expect(JSON.parse(stored.get(DEPLOYMENT_STATE_FILE) ?? "null").settled).toBe(true);
+
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.ServerUpdated,
+				payload: {
+					kind: "deployment",
+					deployment: "dep_a1b2c3d4",
+					outcome: "ready",
+					commit: "0123456789ab",
+				},
+			},
+		]);
+	});
+
+	it("fails the deployment at the start stage with the cause when the bot exits inside the grace", async () => {
+		const { context, stored, emitted, readiness } = await readyBot(LAUNCHED_BEFORE);
+
+		await readiness.exit(context, reportOf());
+
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.ServerUpdated,
+				payload: {
+					kind: "deployment",
+					deployment: "dep_a1b2c3d4",
+					outcome: "failed",
+					stage: "start",
+					detail: "token-invalid",
+				},
+			},
+		]);
+
+		const state = JSON.parse(stored.get(DEPLOYMENT_STATE_FILE) ?? "null");
+
+		expect({
+			...state,
+			finishedAt: null,
+		}).toEqual({
+			...JSON.parse(liveState("dep_a1b2c3d4")[DEPLOYMENT_STATE_FILE]),
+			outcome: BotDeploymentOutcome.Failed,
+			stage: BotDeploymentStage.Start,
+			detail: "token-invalid",
+			finishedAt: null,
+			settled: true,
+		});
+	});
+
+	it("names the failure unknown when nothing the bot printed explains it", async () => {
+		const { context, emitted, readiness } = await readyBot(LAUNCHED_BEFORE);
+
+		await readiness.exit(
+			context,
+			reportOf({
+				cause: BridgeCrashCause.Unknown,
+			}),
+		);
+
+		expect(emitted.at(0)?.payload?.detail).toBe("unknown");
+	});
+
+	it("leaves a deployment that went live before this launch alone on a plain restart", async () => {
+		const { context, emitted, stored, readiness } = await readyBot(LAUNCHED_AFTER);
+		const before = stored.get(DEPLOYMENT_STATE_FILE);
+
+		await readiness.exit(context, reportOf());
+		await readiness.stable(context);
+
+		expect(emitted).toEqual([]);
+		expect(stored.get(DEPLOYMENT_STATE_FILE)).toBe(before);
+	});
+
+	it("spends the deployment once, so a crash after the bot became stable fails nothing", async () => {
+		const { context, emitted, readiness } = await readyBot(LAUNCHED_BEFORE);
+
+		await readiness.stable(context);
+		await readiness.exit(
+			context,
+			reportOf({
+				phase: BridgeCrashPhase.Running,
+			}),
+		);
+
+		expect(emitted.map((entry) => entry.payload?.outcome)).toEqual([
+			"ready",
+		]);
+	});
+});
+
+describe("the deployment a bot is still proving", () => {
+	it("waits for the state read still in flight before it reports ready", async () => {
+		const deploy = deployContext(true, liveState("dep_a1b2c3d4"));
+		const readiness = createBotReadiness();
+
+		readiness.launching(LAUNCHED_BEFORE);
+
+		const reading = readiness.ready(deploy.context);
+
+		await readiness.stable(deploy.context);
+		await reading;
+
+		expect(deploy.emitted.map((entry) => entry.payload?.outcome)).toEqual([
+			"ready",
+		]);
+	});
+
+	it("keeps proving a deployment the launcher left unsettled when the bot starts again", async () => {
+		const unsettled = JSON.parse(liveState("dep_a1b2c3d4")[DEPLOYMENT_STATE_FILE]);
+		const deploy = deployContext(true, {
+			[DEPLOYMENT_STATE_FILE]: JSON.stringify({
+				...unsettled,
+				settled: false,
+			}),
+		});
+		const readiness = createBotReadiness();
+
+		readiness.launching(LAUNCHED_AFTER);
+
+		await readiness.ready(deploy.context);
+		await readiness.exit(deploy.context, reportOf());
+
+		expect(deploy.emitted.map((entry) => entry.payload?.outcome)).toEqual([
+			"failed",
+		]);
+	});
+
+	it("does not call a deployment live while the bot is still proving it, and restarts nothing", async () => {
+		const unsettled = JSON.parse(liveState("dep_a1b2c3d4")[DEPLOYMENT_STATE_FILE]);
+		const { context, stored, events, emitted } = deployContext(true, {
+			[DEPLOYMENT_STATE_FILE]: JSON.stringify({
+				...unsettled,
+				settled: false,
+			}),
+		});
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+
+		expect(emitted).toEqual([]);
+		expect(stored.has(DEPLOY_MARKER)).toBe(false);
+		expect(events).toEqual([
+			"log the deployment is running but has not proven itself yet, its outcome follows",
+		]);
+	});
+});
+
+describe("pendingDeploymentOf", () => {
+	it("takes a ready deployment the launcher wrote during this launch or left unsettled, never a settled one", () => {
+		const state = {
+			deployment: "dep_a1b2c3d4",
+			source: BotDeploymentSource.Snapshot,
+			ref: null,
+			commit: null,
+			snapshot: "snap_1",
+			outcome: BotDeploymentOutcome.Ready,
+			stage: null,
+			detail: null,
+			finishedAt: "2026-09-27T10:00:00.000Z",
+		};
+
+		expect(pendingDeploymentOf(state, LAUNCHED_BEFORE)).toEqual(state);
+		expect(pendingDeploymentOf(state, LAUNCHED_AFTER)).toBeNull();
+		expect(
+			pendingDeploymentOf(
+				{
+					...state,
+					outcome: BotDeploymentOutcome.Failed,
+				},
+				LAUNCHED_BEFORE,
+			),
+		).toBeNull();
+		expect(
+			pendingDeploymentOf(
+				{
+					...state,
+					deployment: null,
+				},
+				LAUNCHED_BEFORE,
+			),
+		).toBeNull();
+		expect(pendingDeploymentOf(null, LAUNCHED_BEFORE)).toBeNull();
+		expect(
+			pendingDeploymentOf(
+				{
+					...state,
+					settled: false,
+				},
+				LAUNCHED_AFTER,
+			),
+		).toEqual({
+			...state,
+			settled: false,
+		});
+		expect(
+			pendingDeploymentOf(
+				{
+					...state,
+					settled: true,
+				},
+				LAUNCHED_BEFORE,
+			),
+		).toBeNull();
+	});
+});