@serverkgg/bridge 0.1.8 → 0.1.10

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

@@ -17,6 +17,8 @@ export enum BridgeCrashCause {
 	FfmpegMissing = "ffmpeg-missing",
 	AudioopRemoved = "audioop-removed",
 	RateLimited = "rate-limited",
+	VariableMissing = "variable-missing",
+	WebhookActive = "webhook-active",
 	Unknown = "unknown",
 }
 
@@ -75,6 +77,10 @@ export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
 		name: BridgeEventName.FfmpegMissing,
 		cause: BridgeCrashCause.FfmpegMissing,
 	},
+	{
+		name: BridgeEventName.VariableMissing,
+		cause: BridgeCrashCause.VariableMissing,
+	},
 	{
 		name: BridgeEventName.IntentsDisallowed,
 		cause: BridgeCrashCause.IntentsDisallowed,
@@ -83,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

@@ -47,6 +47,8 @@ export enum BridgeEventName {
 	TickLagging = "TickLagging",
 	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();