@serverkgg/bridge 0.0.1 → 0.0.3

package/src/runtime/bridgeNet.ts

@@ -1,50 +1,103 @@
 import type { BridgeNet, BridgeRequestOptions } from "../context";
+import { BridgeNetError } from "../core";
+import { type BridgeEgress, BridgeEgressCallError, BridgeEgressUnavailableError } from "./bridgeEgress";
 
 const REQUEST_TIMEOUT_MS = 15_000;
 
 const RESPONSE_LIMIT = 8 * 1024 * 1024;
 
-const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
+export const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
 
-export class BridgeNetError extends Error {
-	readonly status: number | null;
+const LINE_BREAK = /[\r\n]/;
 
-	constructor(status: number | null, message: string) {
-		super(message);
+export const safeHeaders = (headers: Record<string, string> = {}) => {
+	const checked: Record<string, string> = {};
 
-		this.name = "BridgeNetError";
-		this.status = status;
+	for (const [key, value] of Object.entries(headers)) {
+		if (LINE_BREAK.test(key) || LINE_BREAK.test(value)) {
+			throw new BridgeNetError(null, "a header contains a line break");
+		}
+
+		checked[key] = value;
 	}
-}
 
-export const createBridgeNet = (): BridgeNet => {
-	const request = async (url: string, options: BridgeRequestOptions = {}) => {
-		const remote = new URL(url);
+	return checked;
+};
 
-		if (remote.protocol !== "https:") {
-			throw new BridgeNetError(null, `"${url}" is not https`);
+const readCapped = async (response: Response, host: string) => {
+	if (!response.body) {
+		return "";
+	}
+
+	const decoder = new TextDecoder();
+	const parts: string[] = [];
+
+	let read = 0;
+
+	for await (const chunk of response.body) {
+		read += chunk.byteLength;
+
+		if (read > RESPONSE_LIMIT) {
+			throw new BridgeNetError(null, `${host} returned more than ${RESPONSE_LIMIT} bytes`);
 		}
 
-		const response = await fetch(url, {
+		parts.push(
+			decoder.decode(chunk, {
+				stream: true,
+			}),
+		);
+	}
+
+	parts.push(decoder.decode());
+
+	return parts.join("");
+};
+
+export const createBridgeNet = (egress: BridgeEgress): BridgeNet => {
+	const direct = async (remote: URL, headers: Record<string, string>, timeoutMs: number) => {
+		const response = await fetch(remote, {
 			headers: {
+				...headers,
 				"user-agent": USER_AGENT,
-				...options.headers,
 			},
-			redirect: "follow",
-			signal: AbortSignal.timeout(options.timeoutMs ?? REQUEST_TIMEOUT_MS),
+			redirect: "error",
+			signal: AbortSignal.timeout(timeoutMs),
 		});
 
 		if (!response.ok) {
-			throw new BridgeNetError(response.status, `${url} answered ${response.status}`);
+			throw new BridgeNetError(response.status, `${remote.host} answered ${response.status}`);
 		}
 
-		const body = await response.text();
+		return await readCapped(response, remote.host);
+	};
+
+	const request = async (url: string, options: BridgeRequestOptions = {}) => {
+		const remote = new URL(url);
+
+		if (remote.protocol !== "https:") {
+			throw new BridgeNetError(null, `${remote.host} is not https`);
+		}
+
+		const headers = safeHeaders(options.headers);
+
+		try {
+			const result = await egress.fetch(url, {
+				...options,
+				headers,
+			});
+
+			return result.body;
+		} catch (error) {
+			if (error instanceof BridgeEgressCallError) {
+				throw new BridgeNetError(error.status, error.message);
+			}
 
-		if (body.length > RESPONSE_LIMIT) {
-			throw new BridgeNetError(null, `${url} returned more than ${RESPONSE_LIMIT} bytes`);
+			if (!(error instanceof BridgeEgressUnavailableError)) {
+				throw error;
+			}
 		}
 
-		return body;
+		return await direct(remote, headers, options.timeoutMs ?? REQUEST_TIMEOUT_MS);
 	};
 
 	return {

package/src/runtime/bridgeRegistry.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import type { BridgeDriver } from "../modules";
+import { type BridgeConfig, BridgeEventName } from "../protocol";
+import { createContext } from "./bridgeContext";
+import { createEventRing } from "./bridgeEvents";
+import { log } from "./bridgeLog";
+import { createRegistry } from "./bridgeRegistry";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const config = (): BridgeConfig => ({
+	code: "abcdef",
+	token: "token",
+	cwd: `${tmpdir()}/serverk-registry-test`,
+	run: `${tmpdir()}/serverk-registry-test/run`,
+	ports: {},
+	memoryMb: 1024,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {},
+	secrets: {},
+});
+
+const baseDriver = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+});
+
+const registryFor = (driver: BridgeDriver) => {
+	const settings = config();
+
+	const supervisor = createSupervisor({
+		cwd: settings.cwd,
+		uid: settings.gameUid,
+		gid: settings.gameGid,
+		stopTimeoutSeconds: 1,
+		onLog: log,
+		resolveCommand: async () => [
+			"run",
+		],
+	});
+
+	const ring = createEventRing(driver.events, supervisor);
+
+	const context = createContext(settings, supervisor, {
+		onLog: log,
+		onEmit(event, payload) {
+			ring.emit(event, payload);
+		},
+	});
+
+	return createRegistry(driver, context, supervisor, ring);
+};
+
+describe("actions modules", () => {
+	test("lists its action ids in the manifest", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				gameplay: {
+					kind: BridgeKind.Actions,
+					requiresRunning: true,
+					actions: {
+						timeDay: async () => {
+							return;
+						},
+						weatherClear: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules).toEqual([
+			{
+				id: "gameplay",
+				kind: BridgeKind.Actions,
+				requiresRunning: true,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					"timeDay",
+					"weatherClear",
+				],
+			},
+		]);
+	});
+
+	test("hands the whole argument bag to the handler", async () => {
+		const received: BridgeValues[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				broadcast: {
+					kind: BridgeKind.Actions,
+					actions: {
+						say: async (_context, args) => {
+							received.push(args);
+						},
+					},
+				},
+			},
+		});
+
+		await registry.invoke("broadcast", "say", {
+			message: "hello",
+		});
+
+		expect(received).toEqual([
+			{
+				message: "hello",
+			},
+		]);
+	});
+
+	test("refuses to run while the game is stopped", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				broadcast: {
+					kind: BridgeKind.Actions,
+					requiresRunning: true,
+					actions: {
+						say: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		await expect(
+			registry.invoke("broadcast", "say", {
+				message: "hello",
+			}),
+		).rejects.toThrow('module "broadcast" needs the game to be running');
+	});
+
+	test("rejects a driver that reuses a read action id", () => {
+		expect(() =>
+			registryFor({
+				...baseDriver(),
+				modules: {
+					broadcast: {
+						kind: BridgeKind.Actions,
+						actions: {
+							list: async () => {
+								return;
+							},
+						},
+					},
+				},
+			}),
+		).toThrow('module "broadcast" declares action "list", which is reserved for reads');
+	});
+});
+
+describe("manifest events", () => {
+	test("lists the log patterns and the names the driver raises itself", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			events: {
+				kind: BridgeKind.Events,
+				patterns: [
+					{
+						match: /Fatal error/,
+						emit: BridgeEventName.ServerCrashed,
+					},
+					{
+						match: /Fatal error again/,
+						emit: BridgeEventName.ServerCrashed,
+					},
+				],
+				emits: [
+					BridgeEventName.PlayerJoined,
+					BridgeEventName.PlayerLeft,
+					BridgeEventName.ServerCrashed,
+				],
+			},
+		});
+
+		expect(registry.manifest().events).toEqual([
+			BridgeEventName.ServerCrashed,
+			BridgeEventName.PlayerJoined,
+			BridgeEventName.PlayerLeft,
+		]);
+	});
+
+	test("stays on the log patterns when the driver raises nothing itself", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			events: {
+				kind: BridgeKind.Events,
+				patterns: [
+					{
+						match: /Done/,
+						emit: BridgeEventName.ServerStarted,
+					},
+				],
+			},
+		});
+
+		expect(registry.manifest().events).toEqual([
+			BridgeEventName.ServerStarted,
+		]);
+	});
+});
+
+describe("collection row actions", () => {
+	test("passes the row and the arguments without the row id", async () => {
+		const seen: {
+			row: BridgeRow;
+			args: BridgeValues;
+		}[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [
+						{
+							id: "meslzy",
+						},
+					],
+					actions: {
+						xp: async (_context, row, args) => {
+							seen.push({
+								row,
+								args,
+							});
+						},
+					},
+				},
+			},
+		});
+
+		await registry.invoke("players", "xp", {
+			id: "meslzy",
+			amount: 30,
+		});
+
+		expect(seen).toEqual([
+			{
+				row: {
+					id: "meslzy",
+				},
+				args: {
+					amount: 30,
+				},
+			},
+		]);
+	});
+
+	test("keeps listing the built-in actions beside the row actions", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				players: {
+					kind: BridgeKind.Collection,
+					list: async () => [],
+					actions: {
+						kick: async () => {
+							return;
+						},
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules[0]?.actions).toEqual([
+			BridgeAction.List,
+			"kick",
+		]);
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -1,7 +1,13 @@
 import type { BridgeContext } from "../context";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
-import type { BridgeDriver, BridgePanelModule } from "../modules";
-import { BRIDGE_VERSION, type BridgeManifest, type BridgeModuleManifest } from "../protocol";
+import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
+import type { BridgeDriver, BridgePanelModule, BridgeTerminalModule } from "../modules";
+import {
+	BRIDGE_VERSION,
+	type BridgeManifest,
+	type BridgeModuleManifest,
+	type BridgeTerminalManifest,
+} from "../protocol";
+import { actionsOf } from "./bridgeActions";
 import { BridgeDriverError } from "./bridgeDriver";
 import type { BridgeEventRing } from "./bridgeEvents";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
@@ -11,50 +17,12 @@ interface CacheEntry {
 	expiresAt: number;
 }
 
-const actionsOf = (module: BridgePanelModule) => {
-	switch (module.kind) {
-		case BridgeKind.Options: {
-			return [
-				BridgeAction.List,
-			];
-		}
-
-		case BridgeKind.Settings: {
-			return [
-				BridgeAction.Read,
-				...(module.write
-					? [
-							BridgeAction.Write,
-						]
-					: []),
-			];
-		}
-
-		case BridgeKind.Collection: {
-			return [
-				BridgeAction.List,
-				...(module.add
-					? [
-							BridgeAction.Add,
-						]
-					: []),
-				...Object.keys(module.actions ?? {}),
-			];
-		}
-
-		case BridgeKind.Catalog: {
-			return [
-				BridgeAction.Install,
-				BridgeAction.Installed,
-				BridgeAction.Remove,
-				BridgeAction.Search,
-			];
-		}
+const requiresRunning = (module: BridgePanelModule) => {
+	if (module.kind === BridgeKind.Actions || module.kind === BridgeKind.Collection) {
+		return module.requiresRunning ?? false;
 	}
-};
 
-const requiresRunning = (module: BridgePanelModule) => {
-	return module.kind === BridgeKind.Collection ? (module.requiresRunning ?? false) : false;
+	return false;
 };
 
 const refreshOf = (module: BridgePanelModule) => {
@@ -69,6 +37,24 @@ const pageSizeOf = (module: BridgePanelModule) => {
 	return module.kind === BridgeKind.Catalog ? (module.pageSize ?? null) : null;
 };
 
+const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTerminalManifest | null => {
+	if (!module) {
+		return null;
+	}
+
+	return {
+		commands: module.commands,
+		rules: (module.rules ?? []).map((rule) => {
+			return {
+				match: rule.match.source,
+				flags: rule.match.flags,
+				level: rule.level,
+				stream: rule.stream,
+			};
+		}),
+	};
+};
+
 const withVariables = (context: BridgeContext, overlay: Record<string, string>): BridgeContext => {
 	return {
 		get server() {
@@ -97,9 +83,7 @@ const withVariables = (context: BridgeContext, overlay: Record<string, string>):
 		emit(event, payload) {
 			context.emit(event, payload);
 		},
-		log(message, fields) {
-			context.log(message, fields);
-		},
+		log: context.log,
 	};
 };
 
@@ -119,6 +103,24 @@ const asText = (args: BridgeValues, key: string) => {
 	return typeof value === "string" ? value : "";
 };
 
+const asOptional = (args: BridgeValues, key: string) => {
+	const value = args[key];
+
+	return typeof value === "string" && value.length > 0 ? value : null;
+};
+
+const withoutId = (args: BridgeValues) => {
+	const rest: BridgeValues = {};
+
+	for (const [key, value] of Object.entries(args)) {
+		if (key !== "id") {
+			rest[key] = value;
+		}
+	}
+
+	return rest;
+};
+
 const asPage = (args: BridgeValues) => {
 	const value = args.page;
 
@@ -135,6 +137,20 @@ export const createRegistry = (
 	const inflight = new Map<string, Promise<unknown>>();
 	const modules = driver.modules ?? {};
 
+	for (const [id, module] of Object.entries(modules)) {
+		if (module.kind !== BridgeKind.Actions) {
+			continue;
+		}
+
+		for (const action of Object.keys(module.actions)) {
+			if (isReadAction(action)) {
+				throw new BridgeDriverError(
+					`module "${id}" declares action "${action}", which is reserved for reads — pick another id`,
+				);
+			}
+		}
+	}
+
 	const cached = async (key: string, ttlSeconds: number | undefined, run: () => Promise<unknown>) => {
 		if (!ttlSeconds) {
 			return await run();
@@ -175,6 +191,18 @@ export const createRegistry = (
 
 	const dispatch = async (module: BridgePanelModule, name: string, action: string, args: BridgeValues) => {
 		switch (module.kind) {
+			case BridgeKind.Actions: {
+				const serverAction = module.actions[action];
+
+				if (serverAction) {
+					await serverAction(context, args);
+
+					return null;
+				}
+
+				break;
+			}
+
 			case BridgeKind.Options: {
 				if (action === BridgeAction.List) {
 					const overlay: Record<string, string> = {};
@@ -236,7 +264,7 @@ export const createRegistry = (
 						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);
 					}
 
-					await rowAction(context, row as BridgeRow);
+					await rowAction(context, row as BridgeRow, withoutId(args));
 
 					return null;
 				}
@@ -246,7 +274,13 @@ export const createRegistry = (
 
 			case BridgeKind.Catalog: {
 				if (action === BridgeAction.Search) {
-					return await module.search(context, asText(args, "query"), asPage(args));
+					return await module.search(context, {
+						query: asText(args, "query"),
+						page: asPage(args),
+						provider: asOptional(args, "provider"),
+						category: asOptional(args, "category"),
+						sort: asOptional(args, "sort"),
+					});
 				}
 
 				if (action === BridgeAction.Installed) {
@@ -263,6 +297,12 @@ export const createRegistry = (
 					return null;
 				}
 
+				if (action === BridgeAction.Toggle && module.toggle) {
+					await module.toggle(context, asString(args, "id"), args.enabled !== false);
+
+					return null;
+				}
+
 				break;
 			}
 		}
@@ -287,6 +327,7 @@ export const createRegistry = (
 			return {
 				version: BRIDGE_VERSION,
 				panel: driver.panel ?? null,
+				terminal: terminalManifestOf(driver.terminal),
 				modules: entries,
 				events: ring.names(),
 			};
@@ -307,5 +348,3 @@ export const createRegistry = (
 		},
 	};
 };
-
-export type BridgeRegistry = ReturnType<typeof createRegistry>;

package/src/runtime/bridgeServer.ts

@@ -1,8 +1,10 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeSecretError, type BridgeValues } from "../core";
+import { BridgeFailureError, BridgeSecretError, type BridgeValues } from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
+	type BridgeAnnounceResult,
 	type BridgeCommandResult,
+	type BridgeDescribeResult,
 	type BridgeEventsResult,
 	type BridgeManifest,
 	BridgeMethod,
@@ -26,6 +28,8 @@ export interface ServerOptions {
 	onSample: () => Promise<BridgeSampleResult>;
 	onQuiesce: () => Promise<BridgeQuiesceResult>;
 	onRelease: () => Promise<void>;
+	onDescribe: () => Promise<BridgeDescribeResult>;
+	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
 	onLog: BridgeLogger;
 }
 
@@ -40,8 +44,13 @@ interface IncomingFrame {
 	action?: unknown;
 	args?: unknown;
 	cursor?: unknown;
+	message?: unknown;
 }
 
+const asMessage = (value: unknown): string | null => {
+	return typeof value === "string" && value.length > 0 ? value : null;
+};
+
 const matches = (left: string, right: string) => {
 	const a = Buffer.from(left);
 	const b = Buffer.from(right);
@@ -122,6 +131,20 @@ export const createServer = (options: ServerOptions) => {
 				return null;
 			}
 
+			case BridgeMethod.Describe: {
+				return await options.onDescribe();
+			}
+
+			case BridgeMethod.Announce: {
+				const message = asMessage(request.message);
+
+				if (!message) {
+					throw new Error("announce needs a message");
+				}
+
+				return await options.onAnnounce(message);
+			}
+
 			default: {
 				throw new Error(`unknown method "${method}"`);
 			}
@@ -205,6 +228,12 @@ export const createServer = (options: ServerOptions) => {
 							);
 						})
 						.catch((error: unknown) => {
+							options.onLog("bridge call failed", {
+								method: String(request.method ?? ""),
+								error: errorText(error),
+								stack: error instanceof Error ? (error.stack ?? null) : null,
+							});
+
 							socket.write(
 								encode({
 									id,
@@ -215,6 +244,11 @@ export const createServer = (options: ServerOptions) => {
 												secret: error.key,
 											}
 										: {}),
+									...(error instanceof BridgeFailureError
+										? {
+												failure: error.code,
+											}
+										: {}),
 								}),
 							);
 						});
@@ -229,5 +263,3 @@ export const createServer = (options: ServerOptions) => {
 		},
 	});
 };
-
-export type BridgeSocketServer = ReturnType<typeof createServer>;