@serverkgg/bridge 0.0.21 → 0.1.2

package/src/cli/validate.test.ts

@@ -1,9 +1,11 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, spyOn, test } 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 { BridgeKind, BridgeSetupStepKind } from "../core";
 import { GuideOpenTab } from "../guides";
+import { MANIFEST_SCHEMA_VERSION, PackageKind } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
 import {
 	BridgeControl,
@@ -14,7 +16,7 @@ import {
 	type BridgeTab,
 	type BridgeTableSection,
 } from "../panel";
-import { placementReportLines, runValidate, setupReportLines } from "./validate";
+import { availabilityReportLines, placementReportLines, runValidate, setupReportLines } from "./validate";
 
 const text = (value: string) => ({
 	ar: value,
@@ -394,3 +396,281 @@ describe("the placement report", () => {
 		).toEqual([]);
 	});
 });
+
+const webp = (width: number, height: number) => {
+	const bytes = new Uint8Array(30);
+	const view = new DataView(bytes.buffer);
+	const ascii = (offset: number, value: string) => {
+		for (let index = 0; index < value.length; index += 1) {
+			bytes[offset + index] = value.charCodeAt(index);
+		}
+	};
+
+	ascii(0, "RIFF");
+	view.setUint32(4, bytes.byteLength - 8, true);
+	ascii(8, "WEBP");
+	ascii(12, "VP8X");
+	view.setUint32(16, 10, true);
+	view.setUint16(24, (width - 1) & 0xff_ff, true);
+	bytes[26] = ((width - 1) >> 16) & 0xff;
+	view.setUint16(27, (height - 1) & 0xff_ff, true);
+	bytes[29] = ((height - 1) >> 16) & 0xff;
+
+	return bytes;
+};
+
+const BOT_DRIVER = `export const driver = {
+	install: {
+		kind: "install",
+		run: async () => undefined,
+	},
+	lifecycle: {
+		kind: "lifecycle",
+		command: async () => ["node", "/serverk/launcher.mjs"],
+		environment: async () => ({}),
+	},
+};
+`;
+
+const botManifest = (extra: Record<string, unknown> = {}) => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: PackageKind.Bot,
+	metadata: {
+		id: "bot-node",
+		name: text("Node.js Bot"),
+		description: text("Run your own bot"),
+		tagline: text("Your code, always on"),
+		logo: "assets/logo.webp",
+		banner: "assets/banner.webp",
+	},
+	resources: {
+		minMemoryMb: 512,
+		recommendedMemoryMb: 1024,
+		minDiskMb: 2048,
+	},
+	container: {
+		image: "serverkgg/bot-node",
+		ports: [],
+	},
+	...extra,
+});
+
+const WEBHOOK_PORT = {
+	key: "webhook",
+	containerPort: 8080,
+	protocol: "tcp",
+	hostRange: {
+		default: 30_000,
+		min: 30_000,
+		max: 30_099,
+	},
+};
+
+describe("validating a bot package", () => {
+	let root = "";
+	let lines: string[] = [];
+	let restore = () => {};
+
+	const writeBot = (manifest: Record<string, unknown>, detectTable: string | null = renderDetectTable()) => {
+		mkdirSync(join(root, "assets"));
+		mkdirSync(join(root, "src"));
+		mkdirSync(join(root, "image"));
+
+		if (detectTable !== null) {
+			writeFileSync(join(root, "image/detect.json"), detectTable);
+		}
+
+		writeFileSync(
+			join(root, "package.json"),
+			JSON.stringify({
+				name: "@serverkgg/bot-node",
+				dependencies: {
+					"@serverkgg/bridge": "0.1.0",
+				},
+			}),
+		);
+		writeFileSync(join(root, "serverk.yml"), JSON.stringify(manifest));
+		writeFileSync(join(root, "assets/logo.webp"), webp(256, 256));
+		writeFileSync(join(root, "assets/banner.webp"), webp(1280, 720));
+		writeFileSync(join(root, "src/driver.ts"), BOT_DRIVER);
+	};
+
+	const validate = () => {
+		return runValidate([
+			"--dir",
+			root,
+		]);
+	};
+
+	beforeEach(() => {
+		root = mkdtempSync(`${tmpdir()}/serverk-validate-bot-`);
+		lines = [];
+
+		const spy = spyOn(console, "log").mockImplementation((line: unknown) => {
+			lines.push(String(line));
+		});
+
+		restore = () => spy.mockRestore();
+	});
+
+	afterEach(() => {
+		restore();
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("validates a bot with no ports and says which kind it read", async () => {
+		writeBot(botManifest());
+
+		await validate();
+
+		expect(lines).toContain("bot-node is valid");
+		expect(lines).toContain(
+			"  manifest: BotPackage, 0 port(s), 0 conditional, 0 tcp+udp, 0 block(s), 0 secret(s), 0 guide(s)",
+		);
+		expect(lines).toContain("  environment: vault off");
+		expect(lines).toContain("  detect: image/detect.json matches this bridge");
+		expect(lines.some((line) => line.includes("warning"))).toBe(false);
+	});
+
+	test("says when a bot turns the environment vault on", async () => {
+		writeBot(
+			botManifest({
+				environment: {
+					vault: true,
+				},
+			}),
+		);
+
+		await validate();
+
+		expect(lines).toContain("  environment: vault on");
+	});
+
+	test("fails a bot whose detection table is missing", async () => {
+		writeBot(botManifest(), null);
+
+		await expect(validate()).rejects.toThrow(
+			'image/detect.json is missing — run "serverk-bridge detect-table" and commit it',
+		);
+	});
+
+	test("fails a bot whose detection table is stale", async () => {
+		writeBot(botManifest(), "{}\n");
+
+		await expect(validate()).rejects.toThrow(
+			'image/detect.json is out of date — run "serverk-bridge detect-table" and commit it',
+		);
+	});
+
+	test("warns about a port on a bot but still validates it", async () => {
+		writeBot(
+			botManifest({
+				container: {
+					image: "serverkgg/bot-node",
+					ports: [
+						WEBHOOK_PORT,
+					],
+				},
+			}),
+		);
+
+		await validate();
+
+		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",
+		);
+	});
+
+	test("fails a bot that declares platform secrets", async () => {
+		writeBot(
+			botManifest({
+				secrets: [
+					{
+						key: "API_KEY",
+						description: text("A key"),
+					},
+				],
+			}),
+		);
+
+		await expect(validate()).rejects.toThrow(
+			"a bot package declares no platform secrets; per-bot values live in the environment vault",
+		);
+	});
+});
+
+describe("availability report", () => {
+	const driverWithModules = (modules: BridgeDriver["modules"]): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules,
+	});
+
+	test("warns about a protected module that cannot say when its action is unavailable", () => {
+		expect(
+			availabilityReportLines(
+				driverWithModules({
+					worlds: {
+						kind: BridgeKind.Collection,
+						protectedActions: [
+							"delete",
+						],
+						list: async () => [],
+						actions: {
+							delete: async () => {
+								return;
+							},
+						},
+					},
+				}),
+			),
+		).toEqual([
+			'  warning: module "worlds" protects delete but declares no `unavailable` — the panel offers the action everywhere and the platform stops the game before the driver can refuse it',
+		]);
+	});
+
+	test("says nothing when the protected module declares the hook or protects nothing", () => {
+		expect(
+			availabilityReportLines(
+				driverWithModules({
+					worlds: {
+						kind: BridgeKind.Collection,
+						protectedActions: [
+							"delete",
+						],
+						list: async () => [],
+						actions: {
+							delete: async () => {
+								return;
+							},
+						},
+						unavailable: async () => ({}),
+					},
+					players: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+						actions: {
+							kick: async () => {
+								return;
+							},
+						},
+					},
+				}),
+			),
+		).toEqual([]);
+	});
+});

package/src/cli/validate.ts

@@ -4,13 +4,18 @@ 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 { BridgeKind, PortProtocol } from "../core";
 import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
 	declaredFiles,
 	type GuidePackage,
+	isBotManifest,
 	MANIFEST_FILE,
-	type Manifest,
+	type Package,
+	PackageKind,
 	type PackageSource,
+	type RunnableManifest,
 	readAssets,
 	readPackageDocument,
 } from "../manifest";
@@ -31,7 +36,7 @@ const HELP = `serverk-bridge validate [options]
 
 options:
   --dir <path>      package directory (default: current directory)
-  --driver <path>   driver module (default: <dir>/src/driver.ts), game packages only
+  --driver <path>   driver module (default: <dir>/src/driver.ts), runnable packages only
   --help            show this help`;
 
 const BRIDGE_PACKAGE = "@serverkgg/bridge";
@@ -274,6 +279,39 @@ const reportPlacement = (driver: BridgeDriver) => {
 	}
 };
 
+export const availabilityReportLines = (driver: BridgeDriver): string[] => {
+	const lines: string[] = [];
+
+	for (const [id, module] of Object.entries(driver.modules ?? {})) {
+		if (
+			module.kind !== BridgeKind.Actions
+			&& module.kind !== BridgeKind.Catalog
+			&& module.kind !== BridgeKind.Collection
+			&& module.kind !== BridgeKind.Settings
+		) {
+			continue;
+		}
+
+		const protectedActions = module.protectedActions ?? [];
+
+		if (protectedActions.length === 0 || module.unavailable) {
+			continue;
+		}
+
+		lines.push(
+			`  warning: module "${id}" protects ${protectedActions.join(", ")} but declares no \`unavailable\` — the panel offers the action everywhere and the platform stops the game before the driver can refuse it`,
+		);
+	}
+
+	return lines;
+};
+
+const reportAvailability = (driver: BridgeDriver) => {
+	for (const line of availabilityReportLines(driver)) {
+		console.log(line);
+	}
+};
+
 const openTargetOf = (target: GuideOpenTarget) => {
 	if (target.tab === GuideOpenTab.Panel) {
 		return `panel tab "${target.tabId}"`;
@@ -317,7 +355,54 @@ export const setupReportLines = (setup: BridgeSetupModule | undefined): string[]
 	];
 };
 
-const validateGamePackage = async (source: PackageSource, manifest: Manifest, dir: string, driverArg?: string) => {
+export const botPortLines = (manifest: RunnableManifest): string[] => {
+	const ports = manifest.container.ports.length;
+
+	if (!isBotManifest(manifest) || ports === 0) {
+		return [];
+	}
+
+	return [
+		`  warning: a bot package declares ${ports} port(s); bots need none — remove them unless a webhook needs a public port`,
+	];
+};
+
+export const botEnvironmentLines = (manifest: RunnableManifest): string[] => {
+	if (!isBotManifest(manifest)) {
+		return [];
+	}
+
+	return [
+		`  environment: vault ${manifest.environment.vault ? "on" : "off"}`,
+	];
+};
+
+export const botDetectLines = (source: PackageSource, manifest: RunnableManifest): string[] => {
+	if (!isBotManifest(manifest)) {
+		return [];
+	}
+
+	const bytes = source.read(DETECT_TABLE_FILE);
+
+	if (bytes === null) {
+		throw new Error(`${DETECT_TABLE_FILE} is missing — run "serverk-bridge detect-table" and commit it`);
+	}
+
+	if (new TextDecoder().decode(bytes) !== renderDetectTable()) {
+		throw new Error(`${DETECT_TABLE_FILE} is out of date — run "serverk-bridge detect-table" and commit it`);
+	}
+
+	return [
+		`  detect: ${DETECT_TABLE_FILE} matches this bridge`,
+	];
+};
+
+const validateRunnablePackage = async (
+	source: PackageSource,
+	manifest: RunnableManifest,
+	dir: string,
+	driverArg?: string,
+) => {
 	const assets = readAssets(source, manifest);
 	const guideFiles = manifest.guides.flatMap((guide) => [
 		guide.bodyPath.ar,
@@ -331,6 +416,7 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	}
 
 	const pack = readGuidePack(source, manifest);
+	const detectLines = botDetectLines(source, manifest);
 	const driverPath = driverArg ? resolve(driverArg) : join(dir, "src/driver.ts");
 
 	if (!existsSync(driverPath)) {
@@ -348,11 +434,22 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	validatePortActivation(manifest.container.ports, driver);
 
 	const conditionalPorts = manifest.container.ports.filter((port) => port.activeWhen.length > 0).length;
+	const pairedPorts = manifest.container.ports.filter((port) => port.protocol === PortProtocol.TcpUdp).length;
+	const blockPorts = manifest.container.ports.filter((port) => port.count > 1).length;
 
 	console.log(`${manifest.metadata.id} is valid`);
 	console.log(
-		`  manifest: ${manifest.container.ports.length} port(s), ${conditionalPorts} conditional, ${manifest.secrets.length} secret(s), ${manifest.guides.length} guide(s)`,
+		`  manifest: ${manifest.kind}, ${manifest.container.ports.length} port(s), ${conditionalPorts} conditional, ${pairedPorts} tcp+udp, ${blockPorts} block(s), ${(manifest.secrets ?? []).length} secret(s), ${manifest.guides.length} guide(s)`,
 	);
+
+	for (const line of [
+		...botPortLines(manifest),
+		...botEnvironmentLines(manifest),
+		...detectLines,
+	]) {
+		console.log(line);
+	}
+
 	console.log(
 		`  assets: logo ${assets.logo.dimensions.width}x${assets.logo.dimensions.height}, banner ${assets.banner.dimensions.width}x${assets.banner.dimensions.height}`,
 	);
@@ -368,6 +465,7 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	reportEvents(driver);
 	reportActionTargets(driver);
 	reportPlacement(driver);
+	reportAvailability(driver);
 };
 
 export const runValidate = async (args: string[]) => {
@@ -399,7 +497,7 @@ export const runValidate = async (args: string[]) => {
 
 	assertRegistryBridge(source);
 
-	let document: Manifest | GuidePackage;
+	let document: Package;
 
 	try {
 		document = readPackageDocument(source);
@@ -407,11 +505,11 @@ export const runValidate = async (args: string[]) => {
 		return invalidManifest(error);
 	}
 
-	if (document.kind === "GuidePackage") {
+	if (document.kind === PackageKind.Guide) {
 		validateGuidePackage(source, document);
 
 		return;
 	}
 
-	await validateGamePackage(source, document, dir, values.driver);
+	await validateRunnablePackage(source, document, dir, values.driver);
 };

package/src/context/bridgeContext.ts

@@ -1,4 +1,4 @@
-import type { BridgeStream, BridgeValues } from "../core";
+import type { BridgeActivity, BridgeStream, BridgeValues } from "../core";
 import type { BridgeHttpMethod, BridgeSetupRuntime } from "../protocol";
 
 export interface BridgeServer {
@@ -6,6 +6,12 @@ export interface BridgeServer {
 	memoryMb: number;
 	cpuPercent: number;
 	running: boolean;
+	readonly publicAddress: string | null;
+}
+
+export interface BridgePortBlock {
+	first: number;
+	count: number;
 }
 
 export interface BridgeFileEntry {
@@ -34,6 +40,7 @@ export interface BridgeExtractOptions {
 	select?: string;
 	selects?: string[];
 	exclude?: string[];
+	dotfiles?: boolean;
 }
 
 export interface BridgeListOptions {
@@ -182,6 +189,10 @@ export interface BridgeSetupReporter {
 	clear(): void;
 }
 
+export interface BridgeActivityReporter {
+	report(entry: BridgeActivity): void;
+}
+
 export interface BridgeLog {
 	(message: string, fields?: BridgeValues): void;
 	warn(message: string, fields?: BridgeValues): void;
@@ -191,8 +202,11 @@ export interface BridgeLog {
 export interface BridgeContext {
 	readonly server: BridgeServer;
 	variable(key: string): string | null;
+	variables(): Readonly<Record<string, string>>;
 	secret(key: string): string | null;
+	secrets(): Readonly<Record<string, string>>;
 	port(key: string): number;
+	portBlock(key: string): BridgePortBlock;
 	files: BridgeFiles;
 	codec: BridgeCodecs;
 	net: BridgeNet;
@@ -202,6 +216,8 @@ export interface BridgeContext {
 	exec(command: string[], options?: BridgeExecOptions): Promise<BridgeExecResult>;
 	logs: BridgeLogs;
 	setup: BridgeSetupReporter;
+	activity: BridgeActivityReporter;
 	emit(event: string, payload?: BridgeValues): void;
+	restart(): Promise<void>;
 	log: BridgeLog;
 }

package/src/core/bridgeAction.ts

@@ -1,5 +1,6 @@
 export enum BridgeAction {
 	Add = "add",
+	Availability = "availability",
 	Install = "install",
 	Installed = "installed",
 	List = "list",
@@ -16,6 +17,7 @@ export enum BridgeAction {
 }
 
 export const BRIDGE_READ_ACTIONS: readonly string[] = [
+	BridgeAction.Availability,
 	BridgeAction.Releases,
 	BridgeAction.Installed,
 	BridgeAction.List,

package/src/core/bridgeActivity.ts

@@ -0,0 +1,9 @@
+import type { BridgeEventName } from "../protocol/bridgeEvents";
+import type { BridgeValues, LocalizedText } from "./bridgeValue";
+
+export interface BridgeActivity {
+	name: BridgeEventName;
+	text: LocalizedText;
+	subject?: string;
+	details?: BridgeValues;
+}

package/src/core/bridgeAvailability.ts

@@ -0,0 +1,10 @@
+import type { LocalizedText } from "./bridgeValue";
+
+export const BRIDGE_AVAILABILITY_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+export type BridgeUnavailable = Record<string, LocalizedText>;
+
+export interface BridgeAvailability {
+	module: BridgeUnavailable;
+	subjects: Record<string, BridgeUnavailable>;
+}

package/src/core/bridgePort.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { PortProtocol, portCountOf, SOCKET_PROTOCOLS, socketProtocolsOf } from "./bridgePort";
+
+describe("socketProtocolsOf", () => {
+	test("keeps a single socket protocol as it is", () => {
+		expect(socketProtocolsOf(PortProtocol.Tcp)).toEqual([
+			PortProtocol.Tcp,
+		]);
+		expect(socketProtocolsOf(PortProtocol.Udp)).toEqual([
+			PortProtocol.Udp,
+		]);
+	});
+
+	test("expands a pair into both socket protocols", () => {
+		expect(socketProtocolsOf(PortProtocol.TcpUdp)).toEqual([
+			PortProtocol.Tcp,
+			PortProtocol.Udp,
+		]);
+	});
+
+	test("never hands out the shared list itself", () => {
+		const expanded = socketProtocolsOf(PortProtocol.TcpUdp);
+
+		expanded.pop();
+
+		expect(SOCKET_PROTOCOLS).toEqual([
+			PortProtocol.Tcp,
+			PortProtocol.Udp,
+		]);
+	});
+});
+
+describe("portCountOf", () => {
+	test("reads a port stored before blocks existed as a single port", () => {
+		expect(portCountOf({})).toBe(1);
+	});
+
+	test("reads the count of a block", () => {
+		expect(
+			portCountOf({
+				count: 32,
+			}),
+		).toBe(32);
+	});
+});

package/src/core/bridgePort.ts

@@ -1,8 +1,34 @@
 export enum PortProtocol {
 	Tcp = "tcp",
 	Udp = "udp",
+	TcpUdp = "tcp+udp",
 }
 
+export const PORT_BLOCK_MAX_COUNT = 64;
+
+export type SocketProtocol = PortProtocol.Tcp | PortProtocol.Udp;
+
+export const SOCKET_PROTOCOLS = [
+	PortProtocol.Tcp,
+	PortProtocol.Udp,
+] as const satisfies readonly SocketProtocol[];
+
+export const socketProtocolsOf = (protocol: PortProtocol): SocketProtocol[] => {
+	if (protocol === PortProtocol.TcpUdp) {
+		return [
+			...SOCKET_PROTOCOLS,
+		];
+	}
+
+	return [
+		protocol,
+	];
+};
+
+export const portCountOf = (port: { count?: number | undefined }): number => {
+	return port.count ?? 1;
+};
+
 export enum PortJoin {
 	Combined = "combined",
 	Separate = "separate",

package/src/core/bridgeUserError.test.ts

@@ -17,6 +17,16 @@ describe("BridgeUserError", () => {
 		expect(error.text).toEqual(text);
 	});
 
+	test("keeps the cause a driver attaches for the staff log", () => {
+		const cause = new Error("cdn.modrinth.com answered 404");
+		const error = new BridgeUserError(text, {
+			cause,
+		});
+
+		expect(error.cause).toBe(cause);
+		expect(error.message).toBe(text.en);
+	});
+
 	test("is the class a driver reaches through the published namespace", () => {
 		expect(new Bridge.UserError(text)).toBeInstanceOf(BridgeUserError);
 	});

package/src/core/bridgeUserError.ts

@@ -1,10 +1,14 @@
 import type { LocalizedText } from "./bridgeValue";
 
+export interface BridgeUserErrorOptions {
+	cause?: unknown;
+}
+
 export class BridgeUserError extends Error {
 	readonly text: LocalizedText;
 
-	constructor(text: LocalizedText) {
-		super(text.en);
+	constructor(text: LocalizedText, options: BridgeUserErrorOptions = {}) {
+		super(text.en, options);
 
 		this.name = "BridgeUserError";
 		this.text = text;