@serverkgg/bridge 0.0.21 → 0.1.2

package/src/runtime/bridgeActivity.ts

@@ -0,0 +1,268 @@
+import type { BridgeActivityReporter } from "../context";
+import { type BridgeActivity, type BridgeValue, type BridgeValues, isLocalizedText } from "../core";
+import {
+	activityPayload,
+	BRIDGE_ACTIVITY_DETAIL_KEY_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_DETAIL_KEY_PATTERN,
+	BRIDGE_ACTIVITY_DETAILS_LIMIT,
+	BRIDGE_ACTIVITY_KEYS,
+	BRIDGE_ACTIVITY_LIMIT,
+	BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT,
+	isBridgeEventName,
+} from "../protocol";
+import { type BridgeLogger, errorText } from "./bridgeLog";
+import type { BridgeRedact } from "./bridgeRedaction";
+
+export interface ActivityNormalizeOptions {
+	secretKeys: ReadonlySet<string>;
+	redact: BridgeRedact;
+	warn: BridgeLogger;
+}
+
+export interface ActivityReporterOptions extends ActivityNormalizeOptions {
+	onEmit: (event: string, payload: BridgeValues) => void;
+}
+
+export interface BridgeActivityAnswer<Result> {
+	result: Result;
+	activity: BridgeActivity[];
+}
+
+export interface BridgeActivityScope {
+	readonly reporter: BridgeActivityReporter;
+	readonly reported: number;
+	close(): BridgeActivity[];
+	drain(): void;
+}
+
+const RESERVED_KEYS: ReadonlySet<string> = new Set(Object.values(BRIDGE_ACTIVITY_KEYS));
+
+const cut = (value: string, limit: number, reason: string, report: (reason: string) => void) => {
+	if (value.length <= limit) {
+		return value;
+	}
+
+	report(`long-${reason}`);
+
+	return value.slice(0, limit);
+};
+
+const isScalar = (value: unknown): value is BridgeValue => {
+	return (
+		value === null
+		|| typeof value === "boolean"
+		|| typeof value === "string"
+		|| (typeof value === "number" && Number.isFinite(value))
+	);
+};
+
+const normalizeDetails = (
+	details: unknown,
+	options: ActivityNormalizeOptions,
+	report: (reason: string) => void,
+): BridgeValues | null => {
+	if (details === undefined || details === null) {
+		return null;
+	}
+
+	if (typeof details !== "object" || Array.isArray(details)) {
+		report("unusable-details");
+
+		return null;
+	}
+
+	const kept: BridgeValues = {};
+
+	let count = 0;
+
+	for (const [key, value] of Object.entries(details)) {
+		if (RESERVED_KEYS.has(key)) {
+			report("reserved-detail");
+
+			continue;
+		}
+
+		if (options.secretKeys.has(key)) {
+			report("secret-detail");
+
+			continue;
+		}
+
+		if (key.length > BRIDGE_ACTIVITY_DETAIL_KEY_LENGTH_LIMIT || !BRIDGE_ACTIVITY_DETAIL_KEY_PATTERN.test(key)) {
+			report("unusable-detail-key");
+
+			continue;
+		}
+
+		if (!isScalar(value)) {
+			report("unusable-detail-value");
+
+			continue;
+		}
+
+		if (count >= BRIDGE_ACTIVITY_DETAILS_LIMIT) {
+			report("extra-details");
+
+			break;
+		}
+
+		kept[key] =
+			typeof value === "string"
+				? cut(options.redact(value), BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT, "detail", report)
+				: value;
+		count += 1;
+	}
+
+	return count > 0 ? kept : null;
+};
+
+export const normalizeActivity = (entry: BridgeActivity, options: ActivityNormalizeOptions): BridgeActivity | null => {
+	const name = String(entry.name);
+	const reported = new Set<string>();
+
+	const report = (reason: string) => {
+		if (reported.has(reason)) {
+			return;
+		}
+
+		reported.add(reason);
+
+		options.warn("activity entry normalized", {
+			name,
+			reason,
+		});
+	};
+
+	if (!isBridgeEventName(name)) {
+		report("unknown-name");
+
+		return null;
+	}
+
+	if (!isLocalizedText(entry.text)) {
+		report("unusable-text");
+
+		return null;
+	}
+
+	const ar = cut(options.redact(entry.text.ar).trim(), BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT, "text", report);
+	const en = cut(options.redact(entry.text.en).trim(), BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT, "text", report);
+
+	if (ar.length === 0 || en.length === 0) {
+		report("empty-text");
+
+		return null;
+	}
+
+	const subject =
+		typeof entry.subject === "string"
+			? cut(options.redact(entry.subject).trim(), BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT, "subject", report)
+			: "";
+
+	if (entry.subject !== undefined && subject.length === 0) {
+		report("empty-subject");
+	}
+
+	const details = normalizeDetails(entry.details, options, report);
+
+	return {
+		name: entry.name,
+		text: {
+			ar,
+			en,
+		},
+		...(subject.length > 0
+			? {
+					subject,
+				}
+			: {}),
+		...(details
+			? {
+					details,
+				}
+			: {}),
+	};
+};
+
+const safely = (options: ActivityNormalizeOptions, run: () => void) => {
+	try {
+		run();
+	} catch (error) {
+		options.warn("activity report failed", {
+			error: errorText(error),
+		});
+	}
+};
+
+export const createActivityReporter = (options: ActivityReporterOptions): BridgeActivityReporter => {
+	return {
+		report(entry) {
+			safely(options, () => {
+				const normalized = normalizeActivity(entry, options);
+
+				if (normalized) {
+					options.onEmit(normalized.name, activityPayload(normalized));
+				}
+			});
+		},
+	};
+};
+
+export const createActivityScope = (
+	fallback: BridgeActivityReporter,
+	options: ActivityNormalizeOptions,
+): BridgeActivityScope => {
+	const entries: BridgeActivity[] = [];
+
+	let open = true;
+
+	return {
+		reporter: {
+			report(entry) {
+				safely(options, () => {
+					if (!open) {
+						fallback.report(entry);
+
+						return;
+					}
+
+					const normalized = normalizeActivity(entry, options);
+
+					if (!normalized) {
+						return;
+					}
+
+					if (entries.length >= BRIDGE_ACTIVITY_LIMIT) {
+						options.warn("activity entry dropped", {
+							name: normalized.name,
+							reason: "extra-entries",
+						});
+
+						return;
+					}
+
+					entries.push(normalized);
+				});
+			},
+		},
+
+		get reported() {
+			return entries.length;
+		},
+
+		close() {
+			open = false;
+
+			return entries.splice(0);
+		},
+
+		drain() {
+			open = false;
+
+			for (const entry of entries.splice(0)) {
+				fallback.report(entry);
+			}
+		},
+	};
+};

package/src/runtime/bridgeConfigReader.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeConfigError, parseConfig } from "./bridgeConfigReader";
+
+const written = (extra: Record<string, unknown> = {}) => {
+	return JSON.stringify({
+		code: "abcdef",
+		token: "token",
+		cwd: "/home/game",
+		run: "/run/serverk",
+		ports: {
+			game: 19_132,
+			media: 20_000,
+		},
+		memoryMb: 2048,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables: {},
+		secrets: {},
+		...extra,
+	});
+};
+
+describe("parseConfig", () => {
+	test("reads a file an older agent wrote, with no public address and no port counts", () => {
+		const config = parseConfig(written());
+
+		expect(config.publicAddress).toBeUndefined();
+		expect(config.portCounts).toBeUndefined();
+		expect(config.ports).toEqual({
+			game: 19_132,
+			media: 20_000,
+		});
+	});
+
+	test("reads the public address and the port counts when the agent wrote them", () => {
+		const config = parseConfig(
+			written({
+				publicAddress: "203.0.113.7",
+				portCounts: {
+					game: 1,
+					media: 32,
+				},
+			}),
+		);
+
+		expect(config.publicAddress).toBe("203.0.113.7");
+		expect(config.portCounts).toEqual({
+			game: 1,
+			media: 32,
+		});
+	});
+
+	test("ignores a malformed public address and drops non-numeric counts", () => {
+		const config = parseConfig(
+			written({
+				publicAddress: 7,
+				portCounts: {
+					media: "32",
+					game: 1,
+				},
+			}),
+		);
+
+		expect(config.publicAddress).toBeUndefined();
+		expect(config.portCounts).toEqual({
+			game: 1,
+		});
+	});
+
+	test("still refuses a game that would run as root", () => {
+		expect(() =>
+			parseConfig(
+				written({
+					gameUid: 0,
+				}),
+			),
+		).toThrow(BridgeConfigError);
+	});
+});

package/src/runtime/bridgeConfigReader.ts

@@ -70,6 +70,24 @@ const stringRecord = (source: Record<string, unknown>, key: string) => {
 	return out;
 };
 
+const optionalString = (source: Record<string, unknown>, key: string) => {
+	const value = source[key];
+
+	if (typeof value !== "string" || value.length === 0) {
+		return;
+	}
+
+	return value;
+};
+
+const optionalNumberRecord = (source: Record<string, unknown>, key: string) => {
+	if (source[key] === undefined) {
+		return;
+	}
+
+	return numberRecord(source, key);
+};
+
 export const configPath = () => {
 	return `${BRIDGE_RUN_MOUNT}/${BRIDGE_CONFIG_NAME}`;
 };
@@ -97,6 +115,8 @@ export const parseConfig = (text: string): BridgeConfig => {
 		cwd: requireString(source, "cwd"),
 		run: requireString(source, "run"),
 		ports: numberRecord(source, "ports"),
+		portCounts: optionalNumberRecord(source, "portCounts"),
+		publicAddress: optionalString(source, "publicAddress"),
 		memoryMb: requireNumber(source, "memoryMb"),
 		cpuPercent: requireNumber(source, "cpuPercent"),
 		gameUid: requireNumber(source, "gameUid"),

package/src/runtime/bridgeContext.test.ts

@@ -0,0 +1,247 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BridgeConfig } from "../protocol";
+import { createContext } from "./bridgeContext";
+import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { log } from "./bridgeLog";
+import { createSupervisor } from "./bridgeSupervisor";
+
+describe("the context's variable maps", () => {
+	let directory = "";
+	let path = "";
+
+	const configWith = (variables: Record<string, string>, secrets: Record<string, string>): BridgeConfig => ({
+		code: "abcdef",
+		token: "token",
+		cwd: directory,
+		run: join(directory, "run"),
+		ports: {},
+		memoryMb: 512,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables,
+		secrets,
+	});
+
+	beforeEach(async () => {
+		directory = await mkdtemp(join(tmpdir(), "bridge-context-"));
+		path = join(directory, "config.json");
+	});
+
+	afterEach(async () => {
+		await rm(directory, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("hand a driver every variable and secret the agent wrote, and follow a rewrite", async () => {
+		const boot = configWith(
+			{
+				MY_VAR: "1",
+			},
+			{
+				DISCORD_TOKEN: "sealed",
+			},
+		);
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const live = createBridgeLiveConfig(path, boot, 60_000);
+		const supervisor = createSupervisor({
+			cwd: directory,
+			uid: 1000,
+			gid: 1000,
+			stopTimeoutSeconds: 1,
+			onLog: log,
+			resolveCommand: async () => [
+				"run",
+			],
+		});
+		const context = createContext(
+			boot,
+			supervisor,
+			{
+				onLog: log,
+				onEmit() {
+					return;
+				},
+				onSetup() {
+					return;
+				},
+				onActivity() {
+					return;
+				},
+				async onRestart() {
+					return;
+				},
+			},
+			live,
+		);
+
+		expect(context.variables()).toEqual({
+			MY_VAR: "1",
+		});
+		expect(context.secrets()).toEqual({
+			DISCORD_TOKEN: "sealed",
+		});
+
+		await writeFile(
+			path,
+			JSON.stringify(
+				configWith(
+					{
+						MY_VAR: "2",
+						LOG_LEVEL: "debug",
+					},
+					{},
+				),
+			),
+		);
+
+		live.reload();
+
+		expect(context.variables()).toEqual({
+			MY_VAR: "2",
+			LOG_LEVEL: "debug",
+		});
+		expect(context.secrets()).toEqual({});
+		expect(context.variable("LOG_LEVEL")).toBe("debug");
+	});
+});
+
+describe("the context's ports and address", () => {
+	let directory = "";
+	let path = "";
+
+	const configWith = (extra: Partial<BridgeConfig>): BridgeConfig => ({
+		code: "abcdef",
+		token: "token",
+		cwd: directory,
+		run: join(directory, "run"),
+		ports: {
+			game: 19_140,
+			media: 20_064,
+		},
+		memoryMb: 512,
+		cpuPercent: 100,
+		gameUid: 1000,
+		gameGid: 1000,
+		variables: {},
+		secrets: {},
+		...extra,
+	});
+
+	const contextOf = (boot: BridgeConfig) => {
+		const live = createBridgeLiveConfig(path, boot, 60_000);
+		const supervisor = createSupervisor({
+			cwd: directory,
+			uid: 1000,
+			gid: 1000,
+			stopTimeoutSeconds: 1,
+			onLog: log,
+			resolveCommand: async () => [
+				"run",
+			],
+		});
+
+		return {
+			live,
+			context: createContext(
+				boot,
+				supervisor,
+				{
+					onLog: log,
+					onEmit() {
+						return;
+					},
+					onSetup() {
+						return;
+					},
+					onActivity() {
+						return;
+					},
+					async onRestart() {
+						return;
+					},
+				},
+				live,
+			),
+		};
+	};
+
+	beforeEach(async () => {
+		directory = await mkdtemp(join(tmpdir(), "bridge-context-ports-"));
+		path = join(directory, "config.json");
+	});
+
+	afterEach(async () => {
+		await rm(directory, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("hand a driver the block the agent published and its public address", async () => {
+		const boot = configWith({
+			portCounts: {
+				game: 1,
+				media: 32,
+			},
+			publicAddress: "203.0.113.7",
+		});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.portBlock("media")).toEqual({
+			first: 20_064,
+			count: 32,
+		});
+		expect(context.portBlock("game")).toEqual({
+			first: 19_140,
+			count: 1,
+		});
+		expect(context.server.publicAddress).toBe("203.0.113.7");
+	});
+
+	test("treat every port as a single one and the address as unknown for a file an older agent wrote", async () => {
+		const boot = configWith({});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.portBlock("media")).toEqual({
+			first: 20_064,
+			count: 1,
+		});
+		expect(context.server.publicAddress).toBeNull();
+		expect(() => context.portBlock("query")).toThrow('this game declares no port named "query"');
+	});
+
+	test("follow a rewrite of the public address", async () => {
+		const boot = configWith({});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context, live } = contextOf(boot);
+
+		await writeFile(
+			path,
+			JSON.stringify(
+				configWith({
+					publicAddress: "198.51.100.4",
+				}),
+			),
+		);
+
+		live.reload();
+
+		expect(context.server.publicAddress).toBe("198.51.100.4");
+	});
+});