@serverkgg/bridge 0.0.21 → 0.1.1

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,
@@ -394,3 +396,209 @@ 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",
+		);
+	});
+});

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 { 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";
@@ -317,7 +322,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 +383,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 +401,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}`,
 	);
@@ -399,7 +463,7 @@ export const runValidate = async (args: string[]) => {
 
 	assertRegistryBridge(source);
 
-	let document: Manifest | GuidePackage;
+	let document: Package;
 
 	try {
 		document = readPackageDocument(source);
@@ -407,11 +471,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

@@ -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 {
@@ -191,8 +198,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;
@@ -203,5 +213,6 @@ export interface BridgeContext {
 	logs: BridgeLogs;
 	setup: BridgeSetupReporter;
 	emit(event: string, payload?: BridgeValues): void;
+	restart(): Promise<void>;
 	log: BridgeLog;
 }

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/guides/compile.ts

@@ -1,7 +1,7 @@
 import { verifyAsset } from "../manifest/assets";
 import type { GuideEntry, GuideSurface, GuideTag } from "../manifest/guide";
 import type { LocalizedText } from "../manifest/localized";
-import type { GuidePackage, Manifest } from "../manifest/manifest";
+import type { GuidePackage, RunnableManifest } from "../manifest/manifest";
 import type { PackageSource } from "../manifest/source";
 import type { GuideBlock, GuideLeafBlock } from "./blocks";
 import { type CompiledGuide, type CompiledGuideTag, compiledGuideSchema } from "./compiled";
@@ -140,7 +140,7 @@ export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entr
 	};
 };
 
-export const readGuidePack = (source: PackageSource, manifest: Manifest): GuidePack | null => {
+export const readGuidePack = (source: PackageSource, manifest: RunnableManifest): GuidePack | null => {
 	if (manifest.guides.length === 0) {
 		return null;
 	}

package/src/manifest/index.ts

@@ -4,6 +4,7 @@ export * from "./category";
 export * from "./guide";
 export * from "./image";
 export * from "./jsonSchema";
+export * from "./kind";
 export * from "./localized";
 export * from "./manifest";
 export * from "./presence";

package/src/manifest/kind.ts

@@ -0,0 +1,5 @@
+export enum PackageKind {
+	Game = "GamePackage",
+	Bot = "BotPackage",
+	Guide = "GuidePackage",
+}