@serverkgg/bridge 0.0.1

package/src/runtime/bridgeProbe.ts

@@ -0,0 +1,14 @@
+import type { BridgeProbes } from "../context";
+import { probeA2s } from "../probes";
+
+const PROBE_HOST = "127.0.0.1";
+
+const PROBE_TIMEOUT_MS = 5000;
+
+export const createBridgeProbes = (): BridgeProbes => {
+	return {
+		async a2s(port) {
+			return await probeA2s(PROBE_HOST, port, PROBE_TIMEOUT_MS);
+		},
+	};
+};

package/src/runtime/bridgeRegistry.ts

@@ -0,0 +1,311 @@
+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 { BridgeDriverError } from "./bridgeDriver";
+import type { BridgeEventRing } from "./bridgeEvents";
+import type { BridgeSupervisor } from "./bridgeSupervisor";
+
+interface CacheEntry {
+	value: unknown;
+	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) => {
+	return module.kind === BridgeKind.Collection ? (module.requiresRunning ?? false) : false;
+};
+
+const refreshOf = (module: BridgePanelModule) => {
+	return module.kind === BridgeKind.Collection ? (module.refreshSeconds ?? null) : null;
+};
+
+const dependsOf = (module: BridgePanelModule) => {
+	return module.kind === BridgeKind.Options ? (module.dependsOn ?? []) : [];
+};
+
+const pageSizeOf = (module: BridgePanelModule) => {
+	return module.kind === BridgeKind.Catalog ? (module.pageSize ?? null) : null;
+};
+
+const withVariables = (context: BridgeContext, overlay: Record<string, string>): BridgeContext => {
+	return {
+		get server() {
+			return context.server;
+		},
+		variable(key) {
+			return Object.hasOwn(overlay, key) ? (overlay[key] ?? null) : context.variable(key);
+		},
+		secret(key) {
+			return context.secret(key);
+		},
+		port(key) {
+			return context.port(key);
+		},
+		files: context.files,
+		codec: context.codec,
+		net: context.net,
+		probe: context.probe,
+		command(input, options) {
+			return context.command(input, options);
+		},
+		exec(command, options) {
+			return context.exec(command, options);
+		},
+		logs: context.logs,
+		emit(event, payload) {
+			context.emit(event, payload);
+		},
+		log(message, fields) {
+			context.log(message, fields);
+		},
+	};
+};
+
+const asString = (args: BridgeValues, key: string) => {
+	const value = args[key];
+
+	if (typeof value !== "string" || value.length === 0) {
+		throw new BridgeDriverError(`"${key}" must be a non-empty string`);
+	}
+
+	return value;
+};
+
+const asText = (args: BridgeValues, key: string) => {
+	const value = args[key];
+
+	return typeof value === "string" ? value : "";
+};
+
+const asPage = (args: BridgeValues) => {
+	const value = args.page;
+
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+};
+
+export const createRegistry = (
+	driver: BridgeDriver,
+	context: BridgeContext,
+	supervisor: BridgeSupervisor,
+	ring: BridgeEventRing,
+) => {
+	const cache = new Map<string, CacheEntry>();
+	const inflight = new Map<string, Promise<unknown>>();
+	const modules = driver.modules ?? {};
+
+	const cached = async (key: string, ttlSeconds: number | undefined, run: () => Promise<unknown>) => {
+		if (!ttlSeconds) {
+			return await run();
+		}
+
+		const hit = cache.get(key);
+		const stamp = Math.floor(performance.now());
+
+		if (hit && hit.expiresAt > stamp) {
+			return hit.value;
+		}
+
+		const pending = inflight.get(key);
+
+		if (pending) {
+			return await pending;
+		}
+
+		const promise = run().then((value) => {
+			if (!Array.isArray(value) || value.length > 0) {
+				cache.set(key, {
+					value,
+					expiresAt: stamp + ttlSeconds * 1000,
+				});
+			}
+
+			return value;
+		});
+
+		inflight.set(key, promise);
+
+		try {
+			return await promise;
+		} finally {
+			inflight.delete(key);
+		}
+	};
+
+	const dispatch = async (module: BridgePanelModule, name: string, action: string, args: BridgeValues) => {
+		switch (module.kind) {
+			case BridgeKind.Options: {
+				if (action === BridgeAction.List) {
+					const overlay: Record<string, string> = {};
+
+					for (const variable of dependsOf(module)) {
+						const value = args[variable];
+
+						if (typeof value === "string") {
+							overlay[variable] = value;
+						}
+					}
+
+					const scoped = withVariables(context, overlay);
+
+					const key = [
+						name,
+						...dependsOf(module).map((variable) => `${variable}=${scoped.variable(variable) ?? ""}`),
+					].join("|");
+
+					return await cached(key, module.ttlSeconds, () => module.list(scoped));
+				}
+
+				break;
+			}
+
+			case BridgeKind.Settings: {
+				if (action === BridgeAction.Read) {
+					return await module.read(context);
+				}
+
+				if (action === BridgeAction.Write && module.write) {
+					await module.write(context, args);
+
+					return null;
+				}
+
+				break;
+			}
+
+			case BridgeKind.Collection: {
+				if (action === BridgeAction.List) {
+					return await module.list(context);
+				}
+
+				if (action === BridgeAction.Add && module.add) {
+					await module.add(context, asString(args, "input"));
+
+					return null;
+				}
+
+				const rowAction = module.actions?.[action];
+
+				if (rowAction) {
+					const rows = await module.list(context);
+					const id = asString(args, "id");
+					const row = rows.find((entry) => entry.id === id);
+
+					if (!row) {
+						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);
+					}
+
+					await rowAction(context, row as BridgeRow);
+
+					return null;
+				}
+
+				break;
+			}
+
+			case BridgeKind.Catalog: {
+				if (action === BridgeAction.Search) {
+					return await module.search(context, asText(args, "query"), asPage(args));
+				}
+
+				if (action === BridgeAction.Installed) {
+					return await module.installed(context);
+				}
+
+				if (action === BridgeAction.Install) {
+					return await module.install(context, asString(args, "id"));
+				}
+
+				if (action === BridgeAction.Remove) {
+					await module.remove(context, asString(args, "id"));
+
+					return null;
+				}
+
+				break;
+			}
+		}
+
+		throw new BridgeDriverError(`module "${name}" does not support "${action}"`);
+	};
+
+	return {
+		manifest(): BridgeManifest {
+			const entries: BridgeModuleManifest[] = Object.entries(modules).map(([id, module]) => {
+				return {
+					id,
+					kind: module.kind,
+					requiresRunning: requiresRunning(module),
+					refreshSeconds: refreshOf(module),
+					pageSize: pageSizeOf(module),
+					dependsOn: dependsOf(module),
+					actions: actionsOf(module),
+				};
+			});
+
+			return {
+				version: BRIDGE_VERSION,
+				panel: driver.panel ?? null,
+				modules: entries,
+				events: ring.names(),
+			};
+		},
+
+		async invoke(name: string, action: string, args: BridgeValues = {}) {
+			const module = modules[name];
+
+			if (!module) {
+				throw new BridgeDriverError(`no module named "${name}"`);
+			}
+
+			if (requiresRunning(module) && !supervisor.running) {
+				throw new BridgeDriverError(`module "${name}" needs the game to be running`);
+			}
+
+			return await dispatch(module, name, action, args);
+		},
+	};
+};
+
+export type BridgeRegistry = ReturnType<typeof createRegistry>;

package/src/runtime/bridgeServer.ts

@@ -0,0 +1,233 @@
+import { timingSafeEqual } from "node:crypto";
+import { BridgeSecretError, type BridgeValues } from "../core";
+import {
+	BRIDGE_FRAME_LIMIT,
+	type BridgeCommandResult,
+	type BridgeEventsResult,
+	type BridgeManifest,
+	BridgeMethod,
+	type BridgeQuiesceResult,
+	type BridgeResponse,
+	type BridgeSampleResult,
+	type BridgeStatus,
+} from "../protocol";
+import { type BridgeLogger, errorText } from "./bridgeLog";
+
+export interface ServerOptions {
+	socket: string;
+	token: string;
+	onStatus: () => BridgeStatus;
+	onManifest: () => BridgeManifest;
+	onStart: () => Promise<void>;
+	onStop: () => Promise<void>;
+	onCommand: (input: string, expect: string | undefined, timeoutMs: number | undefined) => Promise<BridgeCommandResult>;
+	onInvoke: (module: string, action: string, args: BridgeValues) => Promise<unknown>;
+	onEvents: (cursor: number) => BridgeEventsResult;
+	onSample: () => Promise<BridgeSampleResult>;
+	onQuiesce: () => Promise<BridgeQuiesceResult>;
+	onRelease: () => Promise<void>;
+	onLog: BridgeLogger;
+}
+
+interface IncomingFrame {
+	id?: unknown;
+	token?: unknown;
+	method?: unknown;
+	input?: unknown;
+	expect?: unknown;
+	timeoutMs?: unknown;
+	module?: unknown;
+	action?: unknown;
+	args?: unknown;
+	cursor?: unknown;
+}
+
+const matches = (left: string, right: string) => {
+	const a = Buffer.from(left);
+	const b = Buffer.from(right);
+
+	return a.length === b.length && timingSafeEqual(a, b);
+};
+
+const encode = (response: BridgeResponse) => {
+	return `${JSON.stringify(response)}\n`;
+};
+
+const asArgs = (value: unknown): BridgeValues => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return {};
+	}
+
+	const out: BridgeValues = {};
+
+	for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+		if (entry === null || typeof entry === "boolean" || typeof entry === "number" || typeof entry === "string") {
+			out[key] = entry;
+		}
+	}
+
+	return out;
+};
+
+export const createServer = (options: ServerOptions) => {
+	const handle = async (method: string, request: IncomingFrame): Promise<unknown> => {
+		switch (method) {
+			case BridgeMethod.Status: {
+				return options.onStatus();
+			}
+
+			case BridgeMethod.Manifest: {
+				return options.onManifest();
+			}
+
+			case BridgeMethod.Start: {
+				await options.onStart();
+
+				return options.onStatus();
+			}
+
+			case BridgeMethod.Stop: {
+				await options.onStop();
+
+				return options.onStatus();
+			}
+
+			case BridgeMethod.Command: {
+				return await options.onCommand(
+					String(request.input ?? ""),
+					typeof request.expect === "string" ? request.expect : undefined,
+					typeof request.timeoutMs === "number" ? request.timeoutMs : undefined,
+				);
+			}
+
+			case BridgeMethod.Invoke: {
+				return await options.onInvoke(String(request.module ?? ""), String(request.action ?? ""), asArgs(request.args));
+			}
+
+			case BridgeMethod.Events: {
+				return options.onEvents(typeof request.cursor === "number" ? request.cursor : 0);
+			}
+
+			case BridgeMethod.Sample: {
+				return await options.onSample();
+			}
+
+			case BridgeMethod.Quiesce: {
+				return await options.onQuiesce();
+			}
+
+			case BridgeMethod.Release: {
+				await options.onRelease();
+
+				return null;
+			}
+
+			default: {
+				throw new Error(`unknown method "${method}"`);
+			}
+		}
+	};
+
+	return Bun.listen<{
+		buffer: string;
+	}>({
+		unix: options.socket,
+		socket: {
+			open(socket) {
+				socket.data = {
+					buffer: "",
+				};
+			},
+
+			data(socket, chunk) {
+				socket.data.buffer += chunk.toString();
+
+				if (socket.data.buffer.length > BRIDGE_FRAME_LIMIT) {
+					socket.data.buffer = "";
+					socket.write(
+						encode({
+							id: null,
+							ok: false,
+							error: "request is too large",
+						}),
+					);
+
+					return;
+				}
+
+				const frames = socket.data.buffer.split("\n");
+
+				socket.data.buffer = frames.pop() ?? "";
+
+				for (const frame of frames) {
+					if (frame.trim().length === 0) {
+						continue;
+					}
+
+					let request: IncomingFrame;
+
+					try {
+						request = JSON.parse(frame) as IncomingFrame;
+					} catch {
+						socket.write(
+							encode({
+								id: null,
+								ok: false,
+								error: "request is not valid json",
+							}),
+						);
+
+						continue;
+					}
+
+					const id = typeof request.id === "number" ? request.id : null;
+
+					if (typeof request.token !== "string" || !matches(request.token, options.token)) {
+						socket.write(
+							encode({
+								id,
+								ok: false,
+								error: "unauthorized",
+							}),
+						);
+
+						continue;
+					}
+
+					void handle(String(request.method ?? ""), request)
+						.then((result) => {
+							socket.write(
+								encode({
+									id,
+									ok: true,
+									result,
+								}),
+							);
+						})
+						.catch((error: unknown) => {
+							socket.write(
+								encode({
+									id,
+									ok: false,
+									error: errorText(error),
+									...(error instanceof BridgeSecretError
+										? {
+												secret: error.key,
+											}
+										: {}),
+								}),
+							);
+						});
+				}
+			},
+
+			error(_socket, error) {
+				options.onLog("bridge socket error", {
+					error: error.message,
+				});
+			},
+		},
+	});
+};
+
+export type BridgeSocketServer = ReturnType<typeof createServer>;

package/src/runtime/bridgeState.ts

@@ -0,0 +1,40 @@
+import { BridgeDesired } from "../core";
+
+const isDesired = (value: unknown): value is BridgeDesired => {
+	return value === BridgeDesired.Running || value === BridgeDesired.Stopped;
+};
+
+export const readDesired = async (path: string): Promise<BridgeDesired> => {
+	const file = Bun.file(path);
+
+	if (!(await file.exists())) {
+		return BridgeDesired.Running;
+	}
+
+	try {
+		const parsed: unknown = JSON.parse(await file.text());
+
+		if (parsed === null || typeof parsed !== "object") {
+			return BridgeDesired.Running;
+		}
+
+		const desired = (
+			parsed as {
+				desired?: unknown;
+			}
+		).desired;
+
+		return isDesired(desired) ? desired : BridgeDesired.Running;
+	} catch {
+		return BridgeDesired.Running;
+	}
+};
+
+export const writeDesired = async (path: string, desired: BridgeDesired) => {
+	await Bun.write(
+		path,
+		`${JSON.stringify({
+			desired,
+		})}\n`,
+	);
+};