@serverkgg/bridge 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.9",
+	"version": "0.1.10",
 	"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/src/bot/botCauses.test.ts

@@ -109,6 +109,42 @@ const CASES: readonly {
 		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: "GrammyError: Call to 'getUpdates' failed! (409: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first)",
+		cause: BridgeCrashCause.WebhookActive,
+	},
+	{
+		line: "TelegramError: 409: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first",
+		cause: BridgeCrashCause.WebhookActive,
+	},
+	{
+		line: "telegram.error.Conflict: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first",
+		cause: BridgeCrashCause.WebhookActive,
+	},
+	{
+		line: "aiogram.exceptions.TelegramConflictError: Telegram server says - Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first",
+		cause: BridgeCrashCause.WebhookActive,
+	},
+	{
+		line: "Error: listen EADDRINUSE: address already in use :::8080",
+		cause: BridgeCrashCause.PortBusy,
+	},
+	{
+		line: "Error: listen EADDRINUSE: address already in use 0.0.0.0:8080",
+		cause: BridgeCrashCause.PortBusy,
+	},
+	{
+		line: "OSError: [Errno 98] Address already in use",
+		cause: BridgeCrashCause.PortBusy,
+	},
+	{
+		line: "OSError: [Errno 98] error while attempting to bind on address ('0.0.0.0', 8080): address already in use",
+		cause: BridgeCrashCause.PortBusy,
+	},
+	{
+		line: "ERROR:    [Errno 98] error while attempting to bind on address ('0.0.0.0', 8080): address already in use",
+		cause: BridgeCrashCause.PortBusy,
+	},
 	{
 		line: "Error: Cannot find module 'discord.js'",
 		cause: BridgeCrashCause.MissingDependency,
@@ -285,6 +321,26 @@ describe("BOT_CRASH_EVIDENCE", () => {
 		});
 	}
 
+	it("names an active webhook before the token in use its 409 line also matches", () => {
+		const { ring, print } = botRing();
+
+		print(
+			"GrammyError: Call to 'getUpdates' failed! (409: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first)",
+		);
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.WebhookActive);
+	});
+
+	it("still names a second poller on the token as the token in use", () => {
+		const { ring, print } = botRing();
+
+		print(
+			"GrammyError: Call to 'getUpdates' failed! (409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running)",
+		);
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.TokenInUse);
+	});
+
 	it("names the removed audioop module before any other missing module", () => {
 		const { ring, print } = botRing();
 

package/src/bot/botCauses.ts

@@ -22,10 +22,18 @@ export const BOT_CRASH_EVIDENCE: readonly BridgeEventPattern[] = [
 			/Used disallowed intents|\[DisallowedIntents\]|Privileged intent provided is not enabled or whitelisted|PrivilegedIntentsRequired|close code:? 4014\b/,
 		emit: BridgeEventName.IntentsDisallowed,
 	},
+	{
+		match: /can't use getUpdates method while webhook is active/,
+		emit: BridgeEventName.WebhookActive,
+	},
 	{
 		match: /terminated by other getUpdates request|\b409:? Conflict\b/,
 		emit: BridgeEventName.TokenInUse,
 	},
+	{
+		match: /EADDRINUSE|\[Errno 98\][^\n]*[Aa]ddress already in use|OSError: [^\n]*Address already in use/,
+		emit: BridgeEventName.PortBindFailed,
+	},
 	{
 		match:
 			/Cannot find module|ERR_MODULE_NOT_FOUND|ModuleNotFoundError: No module named|(?:davey|PyNaCl) library needed in order to use voice/,

package/src/bot/botEnvironment.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "bun:test";
 import {
+	BOT_NO_EXPOSURE,
+	type BotExposure,
+	botExposureOf,
 	botProcessEnvironment,
 	customerEnvironment,
 	LAUNCHER_DEPLOYMENT_ID,
@@ -17,7 +20,17 @@ import {
 	platformEnvironment,
 } from "./botEnvironment";
 import { type BotConfig, DEFAULT_REPO_BRANCH } from "./botVariables";
-import { BotPlatform } from "./detect";
+import {
+	BOT_PORT_1_KEY,
+	BOT_PORT_2_KEY,
+	BOT_WEB_PORT_KEY,
+	BotPlatform,
+	PORT,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
+	SERVERK_WEB_HOST,
+	SERVERK_WEB_URL,
+} from "./detect";
 
 const SHA = "0123456789abcdef0123456789abcdef01234567";
 
@@ -32,9 +45,33 @@ const config = (overrides: Partial<BotConfig> = {}): BotConfig => ({
 	deployment: null,
 	snapshot: null,
 	gitToken: null,
+	webUrl: null,
+	...overrides,
+});
+
+const WEB_URL = "https://my-bot.srvk.gg";
+
+const exposureOf = (overrides: Partial<BotExposure> = {}): BotExposure => ({
+	...BOT_NO_EXPOSURE,
 	...overrides,
 });
 
+const contextWith = (ports: Record<string, number>, variables: Record<string, string> = {}) => {
+	return {
+		port: (key: string) => {
+			const value = ports[key];
+
+			if (value === undefined) {
+				throw new Error(`this game declares no port named "${key}"`);
+			}
+
+			return value;
+		},
+		variable: (key: string) => variables[key] ?? null,
+		secret: () => null,
+	};
+};
+
 describe("customerEnvironment", () => {
 	it("hands the process every vault key and nothing the platform or the runtime owns", () => {
 		expect(
@@ -152,6 +189,153 @@ describe("platformEnvironment", () => {
 			SERVERK_SERVER_CODE: "abc",
 		});
 	});
+
+	it("hands the bot PORT, the web address and its host while the web port is active", () => {
+		expect(
+			platformEnvironment(
+				"abc",
+				null,
+				exposureOf({
+					web: 8080,
+					webUrl: WEB_URL,
+				}),
+			),
+		).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			[PORT]: "8080",
+			[SERVERK_WEB_URL]: WEB_URL,
+			[SERVERK_WEB_HOST]: "my-bot.srvk.gg",
+		});
+	});
+
+	it("hands the bot no PORT and no address while the web port is off, even with an address delivered", () => {
+		expect(
+			platformEnvironment(
+				"abc",
+				null,
+				exposureOf({
+					webUrl: WEB_URL,
+				}),
+			),
+		).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+		});
+	});
+
+	it("hands the bot PORT alone while the web port is active before its address is known", () => {
+		expect(
+			platformEnvironment(
+				"abc",
+				null,
+				exposureOf({
+					web: 8080,
+				}),
+			),
+		).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			[PORT]: "8080",
+		});
+	});
+
+	it("drops an address that is not a bare https host", () => {
+		for (const webUrl of [
+			"http://my-bot.srvk.gg",
+			"https://my-bot.srvk.gg/",
+			"https://my-bot.srvk.gg:8443",
+			"https://My-Bot.srvk.gg",
+		]) {
+			expect(
+				platformEnvironment(
+					"abc",
+					null,
+					exposureOf({
+						web: 8080,
+						webUrl,
+					}),
+				),
+				webUrl,
+			).toEqual({
+				SERVERK_BOT: "1",
+				SERVERK_SERVER_CODE: "abc",
+				[PORT]: "8080",
+			});
+		}
+	});
+
+	it("hands the bot each raw port only while it is active", () => {
+		expect(
+			platformEnvironment(
+				"abc",
+				null,
+				exposureOf({
+					port1: 29_004,
+					port2: 30_017,
+				}),
+			),
+		).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			[SERVERK_PORT_1]: "29004",
+			[SERVERK_PORT_2]: "30017",
+		});
+		expect(
+			platformEnvironment(
+				"abc",
+				null,
+				exposureOf({
+					port2: 30_017,
+				}),
+			),
+		).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			[SERVERK_PORT_2]: "30017",
+		});
+	});
+});
+
+describe("botExposureOf", () => {
+	it("reads the active ports and the validated address from the bridge context", () => {
+		expect(
+			botExposureOf(
+				contextWith(
+					{
+						[BOT_WEB_PORT_KEY]: 8080,
+						[BOT_PORT_2_KEY]: 30_017,
+					},
+					{
+						[SERVERK_WEB_URL]: WEB_URL,
+					},
+				),
+			),
+		).toEqual({
+			web: 8080,
+			webUrl: WEB_URL,
+			port1: null,
+			port2: 30_017,
+		});
+	});
+
+	it("answers no exposure for a bundle that declares no port", () => {
+		expect(botExposureOf(contextWith({}))).toEqual(BOT_NO_EXPOSURE);
+	});
+
+	it("reads a raw port without the web port", () => {
+		expect(
+			botExposureOf(
+				contextWith({
+					[BOT_PORT_1_KEY]: 29_004,
+				}),
+			),
+		).toEqual(
+			exposureOf({
+				port1: 29_004,
+			}),
+		);
+	});
 });
 
 describe("botProcessEnvironment", () => {
@@ -186,4 +370,37 @@ describe("botProcessEnvironment", () => {
 			BOT_PLATFORM: BotPlatform.Telegram,
 		});
 	});
+
+	it("lets the platform's PORT win over the customer's while the web port is active", () => {
+		const customer = customerEnvironment(
+			{
+				[PORT]: "3000",
+			},
+			{},
+		);
+
+		expect(
+			botProcessEnvironment({
+				tool: {},
+				customer,
+				launcher: {},
+				platform: platformEnvironment(
+					"abc",
+					null,
+					exposureOf({
+						web: 8080,
+						webUrl: WEB_URL,
+					}),
+				),
+			})[PORT],
+		).toBe("8080");
+		expect(
+			botProcessEnvironment({
+				tool: {},
+				customer,
+				launcher: {},
+				platform: platformEnvironment("abc", null),
+			})[PORT],
+		).toBe("3000");
+	});
 });

package/src/bot/botEnvironment.ts

@@ -1,6 +1,20 @@
-import type { BotConfig } from "./botVariables";
+import type { BridgeContext } from "../context";
+import { type BotConfig, readBotConfig, WEB_URL_PATTERN } from "./botVariables";
 import type { BotPlatform } from "./detect";
-import { BOT_PLATFORM, isReservedBotKey, SERVERK_BOT, SERVERK_SERVER_CODE } from "./detect";
+import {
+	BOT_PLATFORM,
+	BOT_PORT_1_KEY,
+	BOT_PORT_2_KEY,
+	BOT_WEB_PORT_KEY,
+	isReservedBotKey,
+	PORT,
+	SERVERK_BOT,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
+	SERVERK_SERVER_CODE,
+	SERVERK_WEB_HOST,
+	SERVERK_WEB_URL,
+} from "./detect";
 
 export const LAUNCHER_REPO_URL = "SERVERK_REPO_URL";
 
@@ -112,7 +126,73 @@ export const launcherEnvironment = (config: BotConfig, stateDir: string): Record
 	return environment;
 };
 
-export const platformEnvironment = (code: string, platform: BotPlatform | null): Record<string, string> => {
+export interface BotExposure {
+	web: number | null;
+	webUrl: string | null;
+	port1: number | null;
+	port2: number | null;
+}
+
+export const BOT_NO_EXPOSURE: BotExposure = {
+	web: null,
+	webUrl: null,
+	port1: null,
+	port2: null,
+};
+
+const activePortOf = (context: Pick<BridgeContext, "port">, key: string) => {
+	try {
+		return context.port(key);
+	} catch {
+		return null;
+	}
+};
+
+export const botExposureOf = (context: Pick<BridgeContext, "port" | "variable" | "secret">): BotExposure => {
+	return {
+		web: activePortOf(context, BOT_WEB_PORT_KEY),
+		webUrl: readBotConfig(context).webUrl,
+		port1: activePortOf(context, BOT_PORT_1_KEY),
+		port2: activePortOf(context, BOT_PORT_2_KEY),
+	};
+};
+
+const webEnvironment = (exposure: BotExposure): Record<string, string> => {
+	if (exposure.web === null) {
+		return {};
+	}
+
+	const environment: Record<string, string> = {
+		[PORT]: String(exposure.web),
+	};
+
+	if (exposure.webUrl !== null && WEB_URL_PATTERN.test(exposure.webUrl)) {
+		environment[SERVERK_WEB_URL] = exposure.webUrl;
+		environment[SERVERK_WEB_HOST] = new URL(exposure.webUrl).hostname;
+	}
+
+	return environment;
+};
+
+const rawPortEnvironment = (exposure: BotExposure): Record<string, string> => {
+	const environment: Record<string, string> = {};
+
+	if (exposure.port1 !== null) {
+		environment[SERVERK_PORT_1] = String(exposure.port1);
+	}
+
+	if (exposure.port2 !== null) {
+		environment[SERVERK_PORT_2] = String(exposure.port2);
+	}
+
+	return environment;
+};
+
+export const platformEnvironment = (
+	code: string,
+	platform: BotPlatform | null,
+	exposure: BotExposure = BOT_NO_EXPOSURE,
+): Record<string, string> => {
 	return {
 		[SERVERK_BOT]: "1",
 		[SERVERK_SERVER_CODE]: code,
@@ -121,6 +201,8 @@ export const platformEnvironment = (code: string, platform: BotPlatform | null):
 					[BOT_PLATFORM]: platform,
 				}
 			: {}),
+		...webEnvironment(exposure),
+		...rawPortEnvironment(exposure),
 	};
 };
 

package/src/bot/botVariables.test.ts

@@ -9,6 +9,7 @@ import {
 	ROOT_DIRECTORY_LENGTH_LIMIT,
 	readBotConfig,
 	SNAPSHOT_ID_PATTERN,
+	WEB_URL_PATTERN,
 } from "./botVariables";
 import {
 	BOT_PLATFORM,
@@ -20,6 +21,7 @@ import {
 	REPO_REF,
 	REPO_URL,
 	ROOT_DIRECTORY,
+	SERVERK_WEB_URL,
 	SNAPSHOT_ID,
 	START_COMMAND,
 } from "./detect";
@@ -49,6 +51,7 @@ describe("readBotConfig", () => {
 						[DEPLOYMENT_ID]: "dep_a1b2c3d4",
 						[SNAPSHOT_ID]: "snap_1",
 						[GIT_TOKEN]: "ignored-in-variables",
+						[SERVERK_WEB_URL]: " https://my-bot.srvk.gg ",
 					},
 					{
 						[GIT_TOKEN]: "ghs_installation",
@@ -66,6 +69,7 @@ describe("readBotConfig", () => {
 			deployment: "dep_a1b2c3d4",
 			snapshot: "snap_1",
 			gitToken: "ghs_installation",
+			webUrl: "https://my-bot.srvk.gg",
 		});
 	});
 
@@ -88,8 +92,29 @@ describe("readBotConfig", () => {
 			deployment: null,
 			snapshot: null,
 			gitToken: null,
+			webUrl: null,
 		});
 	});
+
+	it("drops a web address that is not a bare https host", () => {
+		for (const value of [
+			"http://my-bot.srvk.gg",
+			"https://my-bot.srvk.gg/webhook",
+			"https://my-bot.srvk.gg:443",
+			"https://user@my-bot.srvk.gg",
+			"https://My-Bot.srvk.gg",
+			"https://",
+		]) {
+			expect(
+				readBotConfig(
+					contextWith({
+						[SERVERK_WEB_URL]: value,
+					}),
+				).webUrl,
+				value,
+			).toBeNull();
+		}
+	});
 });
 
 describe("the patterns", () => {
@@ -145,6 +170,13 @@ describe("the patterns", () => {
 		}
 	});
 
+	it("take a web address only as https and a lowercase host", () => {
+		expect(WEB_URL_PATTERN.test("https://my-bot.srvk.gg")).toBe(true);
+		expect(WEB_URL_PATTERN.test("https://abc123.srvk.localhost")).toBe(true);
+		expect(WEB_URL_PATTERN.test("https://my-bot.srvk.gg/")).toBe(false);
+		expect(WEB_URL_PATTERN.test("http://my-bot.srvk.gg")).toBe(false);
+	});
+
 	it("accept https repositories and git branch names", () => {
 		expect(REPO_URL_PATTERN.test("https://github.com/you/bot.git")).toBe(true);
 		expect(REPO_URL_PATTERN.test("https://user:pass@github.com/you/bot")).toBe(false);

package/src/bot/botVariables.ts

@@ -10,6 +10,7 @@ import {
 	REPO_REF,
 	REPO_URL,
 	ROOT_DIRECTORY,
+	SERVERK_WEB_URL,
 	SNAPSHOT_ID,
 	START_COMMAND,
 } from "./detect";
@@ -30,6 +31,8 @@ export const ROOT_DIRECTORY_PATTERN =
 
 export const ROOT_DIRECTORY_LENGTH_LIMIT = 255;
 
+export const WEB_URL_PATTERN = /^https:\/\/[a-z0-9.-]+$/;
+
 export const DEFAULT_REPO_BRANCH = "main";
 
 export const isRootDirectory = (value: string) => {
@@ -47,6 +50,7 @@ export interface BotConfig {
 	deployment: string | null;
 	snapshot: string | null;
 	gitToken: string | null;
+	webUrl: string | null;
 }
 
 const present = (value: string | null) => {
@@ -55,6 +59,10 @@ const present = (value: string | null) => {
 	return trimmed.length === 0 ? null : trimmed;
 };
 
+const webUrlOf = (value: string | null) => {
+	return value !== null && WEB_URL_PATTERN.test(value) ? value : null;
+};
+
 export const readBotConfig = (context: Pick<BridgeContext, "variable" | "secret">): BotConfig => {
 	const platform = present(context.variable(BOT_PLATFORM));
 
@@ -69,5 +77,6 @@ export const readBotConfig = (context: Pick<BridgeContext, "variable" | "secret"
 		deployment: present(context.variable(DEPLOYMENT_ID)),
 		snapshot: present(context.variable(SNAPSHOT_ID)),
 		gitToken: present(context.secret(GIT_TOKEN)),
+		webUrl: webUrlOf(present(context.variable(SERVERK_WEB_URL))),
 	};
 };

package/src/bot/detect/detect.test.ts

@@ -678,6 +678,28 @@ describe("detect warnings", () => {
 
 		expect(quiet.warnings).not.toContain(BotInspectWarning.ReservedEnvKey);
 	});
+
+	it("keeps quiet about the web address and raw port variables an example file lists, and warns about the switches", () => {
+		const quiet = project({
+			...DISCORD_NODE,
+			".env.example": "DISCORD_TOKEN=\nSERVERK_WEB_URL=\nSERVERK_WEB_HOST=\nSERVERK_PORT_1=\nSERVERK_PORT_2=\n",
+		});
+
+		expect(quiet.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+		]);
+		expect(quiet.warnings).not.toContain(BotInspectWarning.ReservedEnvKey);
+
+		const loud = project({
+			...DISCORD_NODE,
+			".env.example": "DISCORD_TOKEN=\nBOT_WEB=on\n",
+		});
+
+		expect(loud.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+		]);
+		expect(loud.warnings).toContain(BotInspectWarning.ReservedEnvKey);
+	});
 });
 
 describe("detect with serverk.json", () => {

package/src/bot/detect/keys.test.ts

@@ -3,9 +3,21 @@ import {
 	BOT_AMBIENT_KEYS,
 	BOT_PLATFORM_KEYS,
 	BOT_PLATFORM_SECRET_KEYS,
+	BOT_PORT_1,
+	BOT_PORT_1_KEY,
+	BOT_PORT_2,
+	BOT_PORT_2_KEY,
 	BOT_PROTECTED_KEYS,
 	BOT_PROVIDED_KEYS,
+	BOT_RAW_PORT_KEYS,
+	BOT_WEB,
+	BOT_WEB_PORT_KEY,
 	isReservedBotKey,
+	PORT,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
+	SERVERK_WEB_HOST,
+	SERVERK_WEB_URL,
 } from "./keys";
 
 describe("isReservedBotKey", () => {
@@ -21,6 +33,21 @@ describe("isReservedBotKey", () => {
 		}
 	});
 
+	it("reserves the web and port switches the platform sets", () => {
+		for (const key of [
+			BOT_WEB,
+			BOT_PORT_1,
+			BOT_PORT_2,
+		]) {
+			expect(BOT_PLATFORM_KEYS).toContain(key);
+			expect(isReservedBotKey(key)).toBe(true);
+		}
+	});
+
+	it("leaves PORT to the customer, so a bot without the web port keeps its own", () => {
+		expect(isReservedBotKey(PORT)).toBe(false);
+	});
+
 	it("leaves the customer's own keys alone, case included", () => {
 		for (const key of [
 			"DISCORD_TOKEN",
@@ -47,6 +74,19 @@ describe("BOT_AMBIENT_KEYS", () => {
 		}
 	});
 
+	it("holds the web address and raw port variables, so detection never asks for them", () => {
+		for (const key of [
+			SERVERK_WEB_URL,
+			SERVERK_WEB_HOST,
+			SERVERK_PORT_1,
+			SERVERK_PORT_2,
+		]) {
+			expect(BOT_PROVIDED_KEYS).toContain(key);
+			expect(BOT_AMBIENT_KEYS).toContain(key);
+			expect(isReservedBotKey(key)).toBe(true);
+		}
+	});
+
 	it("leaves a bot's own keys out", () => {
 		for (const key of [
 			"DISCORD_TOKEN",
@@ -57,3 +97,13 @@ describe("BOT_AMBIENT_KEYS", () => {
 		}
 	});
 });
+
+describe("BOT_RAW_PORT_KEYS", () => {
+	it("names the two raw ports apart from the web port", () => {
+		expect(BOT_RAW_PORT_KEYS).toEqual([
+			BOT_PORT_1_KEY,
+			BOT_PORT_2_KEY,
+		]);
+		expect(BOT_RAW_PORT_KEYS).not.toContain(BOT_WEB_PORT_KEY);
+	});
+});

package/src/bot/detect/keys.ts

@@ -18,12 +18,49 @@ export const SNAPSHOT_ID = "SNAPSHOT_ID";
 
 export const BOT_PLATFORM = "BOT_PLATFORM";
 
+export const BOT_WEB = "BOT_WEB";
+
+export const BOT_PORT_1 = "BOT_PORT_1";
+
+export const BOT_PORT_2 = "BOT_PORT_2";
+
+export const BOT_SWITCH_ON = "on";
+
 export const GIT_TOKEN = "GIT_TOKEN";
 
 export const SERVERK_BOT = "SERVERK_BOT";
 
 export const SERVERK_SERVER_CODE = "SERVERK_SERVER_CODE";
 
+export const SERVERK_WEB_URL = "SERVERK_WEB_URL";
+
+export const SERVERK_WEB_HOST = "SERVERK_WEB_HOST";
+
+export const SERVERK_PORT_1 = "SERVERK_PORT_1";
+
+export const SERVERK_PORT_2 = "SERVERK_PORT_2";
+
+export const PORT = "PORT";
+
+export const BOT_WEB_PORT_KEY = "web";
+
+export const BOT_PORT_1_KEY = "port1";
+
+export const BOT_PORT_2_KEY = "port2";
+
+export const BOT_RAW_PORT_KEYS = [
+	BOT_PORT_1_KEY,
+	BOT_PORT_2_KEY,
+] as const;
+
+export type BotRawPortKey = (typeof BOT_RAW_PORT_KEYS)[number];
+
+export const BOT_PORT_SWITCHES = {
+	[BOT_WEB_PORT_KEY]: BOT_WEB,
+	[BOT_PORT_1_KEY]: BOT_PORT_1,
+	[BOT_PORT_2_KEY]: BOT_PORT_2,
+} as const;
+
 export const BOT_PLATFORM_KEYS: readonly string[] = [
 	REPO_URL,
 	REPO_REF,
@@ -34,6 +71,9 @@ export const BOT_PLATFORM_KEYS: readonly string[] = [
 	DEPLOYMENT_ID,
 	SNAPSHOT_ID,
 	BOT_PLATFORM,
+	BOT_WEB,
+	BOT_PORT_1,
+	BOT_PORT_2,
 ];
 
 export const BOT_PLATFORM_SECRET_KEYS: readonly string[] = [
@@ -52,6 +92,10 @@ export const BOT_PROVIDED_KEYS: readonly string[] = [
 	SERVERK_BOT,
 	SERVERK_SERVER_CODE,
 	BOT_PLATFORM,
+	SERVERK_WEB_URL,
+	SERVERK_WEB_HOST,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
 ];
 
 export const BOT_AMBIENT_KEYS: readonly string[] = [
@@ -59,7 +103,7 @@ export const BOT_AMBIENT_KEYS: readonly string[] = [
 	...BOT_PROVIDED_KEYS,
 	"NODE_ENV",
 	"NODE_OPTIONS",
-	"PORT",
+	PORT,
 	"HOST",
 	"HOSTNAME",
 	"DEBUG",

package/src/cli/validate.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { renderDetectTable } from "../bot/detect";
+import { BOT_SWITCH_ON, BOT_WEB, BOT_WEB_PORT_KEY, renderDetectTable } from "../bot/detect";
 import { BridgeKind, BridgeSetupStepKind } from "../core";
 import { GuideOpenTab, type GuidePack, type ParsedBlock, type ParsedLeafBlock } from "../guides";
 import { MANIFEST_SCHEMA_VERSION, PackageKind, type RunnableManifest } from "../manifest";
@@ -600,7 +600,7 @@ describe("validating a bot package", () => {
 		);
 	});
 
-	it("warns about a port on a bot but still validates it", async () => {
+	it("warns about a bot port with no activeWhen but still validates it", async () => {
 		writeBot(
 			botManifest({
 				container: {
@@ -616,10 +616,40 @@ describe("validating a bot package", () => {
 
 		expect(lines).toContain("bot-node is valid");
 		expect(lines).toContain(
-			"  warning: a bot package declares 1 port(s); bots need none — remove them unless a webhook needs a public port",
+			"  warning: a bot package declares 1 port(s) with no activeWhen; a bot publishes a port only while its author turns it on",
 		);
 	});
 
+	it("validates a bot web port its author turns on without a warning", async () => {
+		writeBot(
+			botManifest({
+				container: {
+					image: "serverkgg/bot-node",
+					ports: [
+						{
+							...WEBHOOK_PORT,
+							key: BOT_WEB_PORT_KEY,
+							web: true,
+							activeWhen: [
+								{
+									variable: BOT_WEB,
+									values: [
+										BOT_SWITCH_ON,
+									],
+								},
+							],
+						},
+					],
+				},
+			}),
+		);
+
+		await validate();
+
+		expect(lines).toContain("bot-node is valid");
+		expect(lines.some((line) => line.includes("warning:"))).toBe(false);
+	});
+
 	it("fails a bot that declares platform secrets", async () => {
 		writeBot(
 			botManifest({

package/src/cli/validate.ts

@@ -4,7 +4,7 @@ import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
 import { type ArticlePack, compileArticles } from "../blog";
-import { DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
+import { BOT_PORT_SWITCHES, DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
 import { BridgeKind, PortProtocol } from "../core";
 import {
 	GuideOpenTab,
@@ -599,14 +599,18 @@ export const setupReportLines = (setup: BridgeSetupModule | undefined): string[]
 };
 
 export const botPortLines = (manifest: RunnableManifest): string[] => {
-	const ports = manifest.container.ports.length;
+	if (!isBotManifest(manifest)) {
+		return [];
+	}
 
-	if (!isBotManifest(manifest) || ports === 0) {
+	const ungated = manifest.container.ports.filter((port) => port.activeWhen.length === 0).length;
+
+	if (ungated === 0) {
 		return [];
 	}
 
 	return [
-		`  warning: a bot package declares ${ports} port(s); bots need none — remove them unless a webhook needs a public port`,
+		`  warning: a bot package declares ${ungated} port(s) with no activeWhen; a bot publishes a port only while its author turns it on`,
 	];
 };
 
@@ -680,7 +684,11 @@ const validateRunnablePackage = async (
 	}
 
 	validateDriver(driver);
-	validatePortActivation(manifest.container.ports, driver);
+	validatePortActivation(
+		manifest.container.ports,
+		driver,
+		isBotManifest(manifest) ? Object.values(BOT_PORT_SWITCHES) : [],
+	);
 
 	const confirmLines = confirmReportLines(driver);
 

package/src/manifest/manifest.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from "bun:test";
 import { z } from "zod";
+import {
+	BOT_PORT_1,
+	BOT_PORT_1_KEY,
+	BOT_PORT_2,
+	BOT_PORT_2_KEY,
+	BOT_SWITCH_ON,
+	BOT_WEB,
+	BOT_WEB_PORT_KEY,
+} from "../bot/detect";
 import { PORT_BLOCK_MAX_COUNT, PortJoin, PortProtocol } from "../core";
 import { GameCategory } from "./category";
 import { ManifestExtensionKind, ManifestExtensionSource } from "./extension";
@@ -1766,6 +1775,146 @@ describe("port pairs and blocks", () => {
 	});
 });
 
+describe("web ports", () => {
+	const gamePort = () => {
+		const [game] = base().container.ports;
+
+		if (!game) {
+			throw new Error("fixture is missing its port");
+		}
+
+		return game;
+	};
+
+	const webPort = (key = "web", min = 31_000) => ({
+		key,
+		containerPort: 8080,
+		protocol: PortProtocol.Tcp,
+		hostRange: {
+			default: min,
+			min,
+			max: min + 99,
+		},
+		web: true,
+	});
+
+	it("reads a port from a bundle published before the web flag as not the web port", () => {
+		expect(manifestSchema.parse(base()).container.ports[0]?.web).toBe(false);
+	});
+
+	it("keeps the one web port a package declares", () => {
+		const manifest = manifestSchema.parse(
+			withPorts([
+				gamePort(),
+				webPort(),
+			]),
+		);
+
+		expect(manifest.container.ports.map((port) => port.web)).toEqual([
+			false,
+			true,
+		]);
+	});
+
+	it("refuses a second web port", () => {
+		expect(
+			failure(
+				withPorts([
+					gamePort(),
+					webPort(),
+					webPort("panel", 31_100),
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.2.web",
+				message: 'port "web" is already the web port — a package declares at most one',
+			},
+		]);
+	});
+
+	for (const protocol of [
+		PortProtocol.Udp,
+		PortProtocol.TcpUdp,
+	]) {
+		it(`refuses a web port carrying ${protocol}`, () => {
+			expect(
+				failure(
+					withPorts([
+						gamePort(),
+						{
+							...webPort(),
+							protocol,
+						},
+					]),
+				),
+			).toEqual([
+				{
+					path: "container.ports.1.protocol",
+					message: `a web port carries tcp only, not ${protocol}`,
+				},
+			]);
+		});
+	}
+
+	it("refuses a web port that is a block", () => {
+		expect(
+			failure(
+				withPorts([
+					gamePort(),
+					{
+						...webPort(),
+						count: 2,
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.count",
+				message: "a web port is a single port, not a block of 2",
+			},
+		]);
+	});
+
+	it("refuses srv, follows and mirror on a web port", () => {
+		expect(
+			failure(
+				withPorts([
+					gamePort(),
+					{
+						...webPort(),
+						srv: {
+							service: "_http",
+						},
+						follows: {
+							key: "game",
+							offset: 1,
+						},
+						mirror: true,
+					},
+				]),
+			),
+		).toEqual([
+			{
+				path: "container.ports.1.srv",
+				message: "a web port is reached only by the server's name and takes no srv",
+			},
+			{
+				path: "container.ports.1.follows",
+				message: "a web port is reached only by the server's name and takes no follows",
+			},
+			{
+				path: "container.ports.1.mirror",
+				message: "a web port is reached only by the server's name and takes no mirror",
+			},
+		]);
+	});
+
+	it("renders its description into the JSON schema", () => {
+		expect(JSON.stringify(buildJsonSchema())).toContain("reached at the server's name over HTTPS");
+	});
+});
+
 const botBase = () => ({
 	schemaVersion: MANIFEST_SCHEMA_VERSION,
 	kind: PackageKind.Bot,
@@ -1928,6 +2077,86 @@ describe("bot packages", () => {
 		expect(manifest.container.ports).toHaveLength(1);
 	});
 
+	it("keep a web port and two raw ports the author turns on", () => {
+		const switched = (variable: string) => [
+			{
+				variable,
+				values: [
+					BOT_SWITCH_ON,
+				],
+			},
+		];
+
+		const manifest = botManifestSchema.parse({
+			...botBase(),
+			container: {
+				...botBase().container,
+				ports: [
+					{
+						key: BOT_WEB_PORT_KEY,
+						containerPort: 8080,
+						protocol: PortProtocol.Tcp,
+						hostRange: {
+							default: 31_000,
+							min: 31_000,
+							max: 31_999,
+						},
+						web: true,
+						activeWhen: switched(BOT_WEB),
+					},
+					{
+						key: BOT_PORT_1_KEY,
+						containerPort: 29_000,
+						protocol: PortProtocol.TcpUdp,
+						hostRange: {
+							default: 29_000,
+							min: 29_000,
+							max: 29_999,
+						},
+						mirror: true,
+						activeWhen: switched(BOT_PORT_1),
+					},
+					{
+						key: BOT_PORT_2_KEY,
+						containerPort: 30_000,
+						protocol: PortProtocol.TcpUdp,
+						hostRange: {
+							default: 30_000,
+							min: 30_000,
+							max: 30_999,
+						},
+						mirror: true,
+						activeWhen: switched(BOT_PORT_2),
+					},
+				],
+			},
+		});
+
+		expect(
+			manifest.container.ports.map((port) => ({
+				key: port.key,
+				web: port.web,
+				variable: port.activeWhen[0]?.variable,
+			})),
+		).toEqual([
+			{
+				key: BOT_WEB_PORT_KEY,
+				web: true,
+				variable: BOT_WEB,
+			},
+			{
+				key: BOT_PORT_1_KEY,
+				web: false,
+				variable: BOT_PORT_1,
+			},
+			{
+				key: BOT_PORT_2_KEY,
+				web: false,
+				variable: BOT_PORT_2,
+			},
+		]);
+	});
+
 	it("reach the runtime reader like a game does", () => {
 		expect(manifestRuntimeOf(botManifestSchema.parse(botBase()))).toEqual({
 			...MANIFEST_RUNTIME_DEFAULTS,

package/src/manifest/manifest.ts

@@ -103,6 +103,10 @@ const manifestPortSchema = z.object({
 		description:
 			"Reserves this many contiguous host ports, bound one to one from containerPort upward. A block is infrastructure, never a player address: it takes no name, hint, join, srv or follows.",
 	}),
+	web: z.boolean().default(false).meta({
+		description:
+			"This port is the server's HTTP surface: bound inside the machine and reached at the server's name over HTTPS.",
+	}),
 });
 
 export type ManifestPort = z.infer<typeof manifestPortSchema>;
@@ -145,7 +149,8 @@ const gameContainerSchema = containerSchemaWith(z.array(manifestPortSchema).min(
 
 const botContainerSchema = containerSchemaWith(
 	z.array(manifestPortSchema).max(MANIFEST_PORTS_LIMIT).default([]).meta({
-		description: "A bot listens on nothing. Declare a port only when a webhook needs a public address.",
+		description:
+			"A bot listens on nothing until its author turns a port on. Gate every port with activeWhen on a variable, and mark the HTTP one web.",
 	}),
 );
 
@@ -543,6 +548,108 @@ const portShapeIssues = (port: ManifestPort, index: number): CheckIssue[] => {
 	return issues;
 };
 
+const WEB_REFUSED_FIELDS = [
+	"srv",
+	"follows",
+] as const;
+
+const webPortIssues = (port: ManifestPort, index: number): CheckIssue[] => {
+	const issues: CheckIssue[] = [];
+	const path = [
+		"container",
+		"ports",
+		index,
+	];
+
+	if (port.protocol !== PortProtocol.Tcp) {
+		issues.push({
+			code: "custom",
+			message: `a web port carries ${PortProtocol.Tcp} only, not ${port.protocol}`,
+			input: port.protocol,
+			path: [
+				...path,
+				"protocol",
+			],
+		});
+	}
+
+	if (port.count !== 1) {
+		issues.push({
+			code: "custom",
+			message: `a web port is a single port, not a block of ${port.count}`,
+			input: port.count,
+			path: [
+				...path,
+				"count",
+			],
+		});
+	}
+
+	for (const field of WEB_REFUSED_FIELDS) {
+		if (port[field] === undefined) {
+			continue;
+		}
+
+		issues.push({
+			code: "custom",
+			message: `a web port is reached only by the server's name and takes no ${field}`,
+			input: port[field],
+			path: [
+				...path,
+				field,
+			],
+		});
+	}
+
+	if (port.mirror) {
+		issues.push({
+			code: "custom",
+			message: "a web port is reached only by the server's name and takes no mirror",
+			input: port.mirror,
+			path: [
+				...path,
+				"mirror",
+			],
+		});
+	}
+
+	return issues;
+};
+
+const webPortsIssues = (ports: ManifestPort[]): CheckIssue[] => {
+	const issues: CheckIssue[] = [];
+
+	let first: ManifestPort | null = null;
+
+	for (const [index, port] of ports.entries()) {
+		if (!port.web) {
+			continue;
+		}
+
+		issues.push(...webPortIssues(port, index));
+
+		if (first === null) {
+			first = port;
+
+			continue;
+		}
+
+		issues.push({
+			code: "custom",
+			message: `port "${first.key}" is already the web port — a package declares at most one`,
+			input: port.web,
+			path: [
+				"container",
+				"ports",
+				index,
+				"web",
+			],
+		});
+	}
+
+	return issues;
+};
+
 const socketBindingIssues = (ports: ManifestPort[]): CheckIssue[] => {
 	const bindings = ports.reduce((total, port) => total + socketProtocolsOf(port.protocol).length, 0);
 
@@ -610,6 +717,7 @@ const portIssues = (ports: ManifestPort[]): CheckIssue[] => {
 		...ports.flatMap(portShapeIssues),
 		...socketBindingIssues(ports),
 		...followIssues(ports),
+		...webPortsIssues(ports),
 	];
 };
 

package/src/protocol/bridgeCrash.ts

@@ -18,6 +18,7 @@ export enum BridgeCrashCause {
 	AudioopRemoved = "audioop-removed",
 	RateLimited = "rate-limited",
 	VariableMissing = "variable-missing",
+	WebhookActive = "webhook-active",
 	Unknown = "unknown",
 }
 
@@ -88,6 +89,10 @@ export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
 		name: BridgeEventName.TokenInvalid,
 		cause: BridgeCrashCause.TokenInvalid,
 	},
+	{
+		name: BridgeEventName.WebhookActive,
+		cause: BridgeCrashCause.WebhookActive,
+	},
 	{
 		name: BridgeEventName.TokenInUse,
 		cause: BridgeCrashCause.TokenInUse,

package/src/protocol/bridgeEvents.ts

@@ -48,6 +48,7 @@ export enum BridgeEventName {
 	TokenInUse = "TokenInUse",
 	TokenInvalid = "TokenInvalid",
 	VariableMissing = "VariableMissing",
+	WebhookActive = "WebhookActive",
 	WorldActivated = "WorldActivated",
 	WorldCloned = "WorldCloned",
 	WorldCorrupt = "WorldCorrupt",

package/src/runtime/bridgeDriver.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { BOT_PORT_SWITCHES, BOT_SWITCH_ON, BOT_WEB } from "../bot/detect";
 import { BridgeKind, BridgeSetupStepKind, PortJoin, PortProtocol } from "../core";
 import { GuideOpenTab } from "../guides";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
@@ -242,6 +243,7 @@ const port = (activeWhen: ManifestPortActivation[]): ManifestPort => ({
 	activeWhen,
 	mirror: false,
 	count: 1,
+	web: false,
 });
 
 const driverWithTabs = (tabs: number, sections: number): BridgeDriver => ({
@@ -663,6 +665,7 @@ describe("validatePortActivation", () => {
 					]),
 				],
 				driverWithVariables(),
+				[],
 			),
 		).not.toThrow();
 	});
@@ -681,9 +684,29 @@ describe("validatePortActivation", () => {
 					]),
 				],
 				driverWithVariables(),
+				[],
 			),
 		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form, catalog or detail declares');
 	});
+
+	it("accepts a variable the platform sets for the package's kind", () => {
+		expect(() =>
+			validatePortActivation(
+				[
+					port([
+						{
+							variable: BOT_WEB,
+							values: [
+								BOT_SWITCH_ON,
+							],
+						},
+					]),
+				],
+				driverWithVariables(),
+				Object.values(BOT_PORT_SWITCHES),
+			),
+		).not.toThrow();
+	});
 });
 
 const driverWithDetail = (): BridgeDriver => ({
@@ -874,6 +897,7 @@ describe("detail sections", () => {
 					]),
 				],
 				driverWithDetail(),
+				[],
 			),
 		).not.toThrow();
 	});

package/src/runtime/bridgeDriver.ts

@@ -905,12 +905,16 @@ const declaredVariables = (driver: BridgeDriver) => {
 	return declared;
 };
 
-export const validatePortActivation = (ports: ManifestPort[], driver: BridgeDriver): void => {
+export const validatePortActivation = (
+	ports: ManifestPort[],
+	driver: BridgeDriver,
+	platformVariables: readonly string[],
+): void => {
 	const declared = declaredVariables(driver);
 
 	for (const port of ports) {
 		for (const [index, rule] of port.activeWhen.entries()) {
-			if (declared.has(rule.variable)) {
+			if (declared.has(rule.variable) || platformVariables.includes(rule.variable)) {
 				continue;
 			}
 

package/src/runtime/bridgeEvents.test.ts

@@ -271,6 +271,19 @@ describe("the crash record the ring builds", () => {
 		});
 	});
 
+	it("names an active webhook before the token in use when both are held", () => {
+		const ring = idleRing();
+
+		ring.emit(BridgeEventName.TokenInUse);
+		ring.emit(BridgeEventName.WebhookActive);
+
+		ring.crash(crashRecord());
+
+		expect(ring.drain(0).events.at(0)?.payload).toMatchObject({
+			cause: "webhook-active",
+		});
+	});
+
 	it("lets the out of memory log pattern outrank the java version", () => {
 		const ring = idleRing();