@serverkgg/bridge 0.1.1 → 0.1.3

package/src/runtime/bridgeActivity.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from "bun:test";
+import type { BridgeActivity, BridgeValues } from "../core";
+import {
+	BRIDGE_ACTIVITY_DETAILS_LIMIT,
+	BRIDGE_ACTIVITY_KEYS,
+	BRIDGE_ACTIVITY_LIMIT,
+	BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT,
+	BridgeEventName,
+} from "../protocol";
+import {
+	type ActivityNormalizeOptions,
+	createActivityReporter,
+	createActivityScope,
+	normalizeActivity,
+} from "./bridgeActivity";
+
+const SECRET = "tok-1234567890-secret";
+
+const recorder = () => {
+	const warnings: {
+		message: string;
+		fields?: Record<string, unknown>;
+	}[] = [];
+
+	const emitted: {
+		event: string;
+		payload: BridgeValues;
+	}[] = [];
+
+	const options: ActivityNormalizeOptions = {
+		secretKeys: new Set([
+			"RCON_PASSWORD",
+		]),
+		redact: (text) => text.split(SECRET).join("••••"),
+		warn: (message, fields) => {
+			warnings.push({
+				message,
+				fields,
+			});
+		},
+	};
+
+	const reporter = createActivityReporter({
+		...options,
+		onEmit(event, payload) {
+			emitted.push({
+				event,
+				payload,
+			});
+		},
+	});
+
+	return {
+		options,
+		reporter,
+		warnings,
+		emitted,
+	};
+};
+
+const granted = (subject = "Steve"): BridgeActivity => ({
+	name: BridgeEventName.AccessGranted,
+	text: {
+		ar: `أضفت ${subject} للقائمة البيضاء`,
+		en: `Added ${subject} to the whitelist`,
+	},
+	subject,
+});
+
+describe("normalizeActivity", () => {
+	it("keeps a well-formed entry as it is", () => {
+		const { options, warnings } = recorder();
+
+		expect(normalizeActivity(granted(), options)).toEqual(granted());
+		expect(warnings).toEqual([]);
+	});
+
+	it("drops a name the protocol does not know, with a warning", () => {
+		const { options, warnings } = recorder();
+
+		expect(
+			normalizeActivity(
+				{
+					...granted(),
+					name: "WhitelistAdded" as BridgeEventName,
+				},
+				options,
+			),
+		).toBeNull();
+		expect(warnings).toEqual([
+			{
+				message: "activity entry normalized",
+				fields: {
+					name: "WhitelistAdded",
+					reason: "unknown-name",
+				},
+			},
+		]);
+	});
+
+	it("drops an entry whose text is empty in one language", () => {
+		const { options } = recorder();
+
+		expect(
+			normalizeActivity(
+				{
+					...granted(),
+					text: {
+						ar: "  ",
+						en: "Added Steve",
+					},
+				},
+				options,
+			),
+		).toBeNull();
+	});
+
+	it("cuts the text and the subject to their limits", () => {
+		const { options, warnings } = recorder();
+
+		const normalized = normalizeActivity(
+			{
+				...granted(),
+				text: {
+					ar: "ا".repeat(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT + 10),
+					en: "a".repeat(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT + 10),
+				},
+				subject: "s".repeat(BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT + 10),
+			},
+			options,
+		);
+
+		expect(normalized?.text.ar).toHaveLength(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT);
+		expect(normalized?.text.en).toHaveLength(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT);
+		expect(normalized?.subject).toHaveLength(BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT);
+		expect(warnings.map((warning) => warning.fields?.reason)).toEqual([
+			"long-text",
+			"long-subject",
+		]);
+	});
+
+	it("keeps at most sixteen details", () => {
+		const { options } = recorder();
+
+		const details: BridgeValues = {};
+
+		for (let index = 0; index < BRIDGE_ACTIVITY_DETAILS_LIMIT + 4; index++) {
+			details[`key${index}`] = index;
+		}
+
+		const normalized = normalizeActivity(
+			{
+				...granted(),
+				details,
+			},
+			options,
+		);
+
+		expect(Object.keys(normalized?.details ?? {})).toHaveLength(BRIDGE_ACTIVITY_DETAILS_LIMIT);
+	});
+
+	it("removes secret fields, reserved keys and values that are not scalars", () => {
+		const { options } = recorder();
+
+		const normalized = normalizeActivity(
+			{
+				...granted(),
+				details: {
+					RCON_PASSWORD: "hunter22hunter22",
+					[BRIDGE_ACTIVITY_KEYS.ar]: "مزوّر",
+					"bad key": "x",
+					nested: {
+						deep: true,
+					} as unknown as string,
+					count: Number.NaN,
+					from: "1.20.4",
+				},
+			},
+			options,
+		);
+
+		expect(normalized?.details).toEqual({
+			from: "1.20.4",
+		});
+	});
+
+	it("blanks a secret value in the text, the subject and the details", () => {
+		const { options } = recorder();
+
+		const normalized = normalizeActivity(
+			{
+				name: BridgeEventName.BroadcastSent,
+				text: {
+					ar: `أرسلت ${SECRET}`,
+					en: `Sent ${SECRET}`,
+				},
+				subject: SECRET,
+				details: {
+					message: `hello ${SECRET}`,
+				},
+			},
+			options,
+		);
+
+		expect(JSON.stringify(normalized)).not.toContain(SECRET);
+		expect(normalized?.details).toEqual({
+			message: "hello ••••",
+		});
+	});
+});
+
+describe("createActivityReporter", () => {
+	it("emits the entry as an event carrying the text under the reserved keys", () => {
+		const { reporter, emitted } = recorder();
+
+		reporter.report({
+			...granted(),
+			details: {
+				source: "panel",
+			},
+		});
+
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.AccessGranted,
+				payload: {
+					source: "panel",
+					[BRIDGE_ACTIVITY_KEYS.ar]: "أضفت Steve للقائمة البيضاء",
+					[BRIDGE_ACTIVITY_KEYS.en]: "Added Steve to the whitelist",
+					[BRIDGE_ACTIVITY_KEYS.subject]: "Steve",
+				},
+			},
+		]);
+	});
+
+	it("emits nothing for an entry normalisation drops", () => {
+		const { reporter, emitted } = recorder();
+
+		reporter.report({
+			...granted(),
+			name: "Nope" as BridgeEventName,
+		});
+
+		expect(emitted).toEqual([]);
+	});
+});
+
+describe("createActivityScope", () => {
+	it("collects entries for the answer instead of emitting them", () => {
+		const { options, reporter, emitted } = recorder();
+		const scope = createActivityScope(reporter, options);
+
+		scope.reporter.report(granted("Steve"));
+		scope.reporter.report(granted("Alex"));
+
+		expect(scope.reported).toBe(2);
+		expect(scope.close()).toEqual([
+			granted("Steve"),
+			granted("Alex"),
+		]);
+		expect(emitted).toEqual([]);
+	});
+
+	it("drains what it collected to the ring when the handler throws", () => {
+		const { options, reporter, emitted } = recorder();
+		const scope = createActivityScope(reporter, options);
+
+		scope.reporter.report(granted());
+		scope.drain();
+
+		expect(emitted.map((entry) => entry.event)).toEqual([
+			BridgeEventName.AccessGranted,
+		]);
+		expect(scope.close()).toEqual([]);
+	});
+
+	it("sends a report made after the answer to the ring", () => {
+		const { options, reporter, emitted } = recorder();
+		const scope = createActivityScope(reporter, options);
+
+		expect(scope.close()).toEqual([]);
+
+		scope.reporter.report(granted());
+
+		expect(emitted.map((entry) => entry.payload[BRIDGE_ACTIVITY_KEYS.subject])).toEqual([
+			"Steve",
+		]);
+	});
+
+	it("keeps at most eight entries on one answer", () => {
+		const { options, reporter, warnings } = recorder();
+		const scope = createActivityScope(reporter, options);
+
+		for (let index = 0; index < BRIDGE_ACTIVITY_LIMIT + 2; index++) {
+			scope.reporter.report(granted(`player${index}`));
+		}
+
+		expect(scope.close()).toHaveLength(BRIDGE_ACTIVITY_LIMIT);
+		expect(warnings.filter((warning) => warning.fields?.reason === "extra-entries")).toHaveLength(2);
+	});
+
+	it("never throws into the caller, whatever the entry holds", () => {
+		const { options, reporter, warnings } = recorder();
+		const scope = createActivityScope(reporter, options);
+
+		const hostile = {
+			...granted(),
+			get details(): BridgeValues {
+				throw new Error("a getter that throws");
+			},
+		};
+
+		expect(() => scope.reporter.report(hostile)).not.toThrow();
+		expect(() => reporter.report(hostile)).not.toThrow();
+		expect(warnings.filter((warning) => warning.message === "activity report failed")).toHaveLength(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/bridgeBackupLease.test.ts

@@ -1,8 +1,8 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { createBackupLease } from "./bridgeBackupLease";
 
 describe("backup save ownership", () => {
-	test("keeps a long backup frozen while renewed and releases when its owner disappears", async () => {
+	it("keeps a long backup frozen while renewed and releases when its owner disappears", async () => {
 		let now = 0;
 		let releases = 0;
 		const lease = createBackupLease(
@@ -25,7 +25,7 @@ describe("backup save ownership", () => {
 		expect(releases).toBe(1);
 		expect(lease.active).toBe(false);
 	});
-	test("refuses overlapping holds and retains ownership after a failed resume", async () => {
+	it("refuses overlapping holds and retains ownership after a failed resume", async () => {
 		let fail = true;
 		const lease = createBackupLease(async () => {
 			if (fail) {
@@ -43,7 +43,7 @@ describe("backup save ownership", () => {
 	});
 });
 
-test("reserves ownership while the quiesce operation is still awaiting confirmation", async () => {
+it("reserves ownership while the quiesce operation is still awaiting confirmation", async () => {
 	const prepared = Promise.withResolvers<void>();
 	const lease = createBackupLease(async () => {});
 	const owner = lease.begin();
@@ -58,7 +58,7 @@ test("reserves ownership while the quiesce operation is still awaiting confirmat
 	await lease.finish(owner);
 });
 
-test("expiration waits for in-flight preparation before resuming saves", async () => {
+it("expiration waits for in-flight preparation before resuming saves", async () => {
 	let now = 0;
 	let releases = 0;
 	const prepared = Promise.withResolvers<void>();
@@ -83,7 +83,7 @@ test("expiration waits for in-flight preparation before resuming saves", async (
 	expect(lease.active).toBe(false);
 });
 
-test("late releases and tokenless callers cannot release a newer owner", async () => {
+it("late releases and tokenless callers cannot release a newer owner", async () => {
 	let releases = 0;
 	const lease = createBackupLease(async () => {
 		releases++;
@@ -99,7 +99,7 @@ test("late releases and tokenless callers cannot release a newer owner", async (
 	expect(releases).toBe(2);
 });
 
-test("legacy release is accepted only for a legacy hold", async () => {
+it("legacy release is accepted only for a legacy hold", async () => {
 	let releases = 0;
 	const lease = createBackupLease(async () => {
 		releases++;
@@ -111,7 +111,7 @@ test("legacy release is accepted only for a legacy hold", async () => {
 	expect(releases).toBe(1);
 });
 
-test("failed quiesce cleanup keeps the owner until resume succeeds", async () => {
+it("failed quiesce cleanup keeps the owner until resume succeeds", async () => {
 	let releases = 0;
 	const lease = createBackupLease(async () => {
 		releases++;
@@ -127,7 +127,7 @@ test("failed quiesce cleanup keeps the owner until resume succeeds", async () =>
 	expect(lease.active).toBe(false);
 });
 
-test("legacy owners retain the historical hold until explicit release without renewal", async () => {
+it("legacy owners retain the historical hold until explicit release without renewal", async () => {
 	let now = 0;
 	let releases = 0;
 	const lease = createBackupLease(

package/src/runtime/bridgeConfigReader.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { BridgeConfigError, parseConfig } from "./bridgeConfigReader";
 
 const written = (extra: Record<string, unknown> = {}) => {
@@ -22,7 +22,7 @@ const written = (extra: Record<string, unknown> = {}) => {
 };
 
 describe("parseConfig", () => {
-	test("reads a file an older agent wrote, with no public address and no port counts", () => {
+	it("reads a file an older agent wrote, with no public address and no port counts", () => {
 		const config = parseConfig(written());
 
 		expect(config.publicAddress).toBeUndefined();
@@ -33,7 +33,7 @@ describe("parseConfig", () => {
 		});
 	});
 
-	test("reads the public address and the port counts when the agent wrote them", () => {
+	it("reads the public address and the port counts when the agent wrote them", () => {
 		const config = parseConfig(
 			written({
 				publicAddress: "203.0.113.7",
@@ -51,7 +51,7 @@ describe("parseConfig", () => {
 		});
 	});
 
-	test("ignores a malformed public address and drops non-numeric counts", () => {
+	it("ignores a malformed public address and drops non-numeric counts", () => {
 		const config = parseConfig(
 			written({
 				publicAddress: 7,
@@ -68,7 +68,7 @@ describe("parseConfig", () => {
 		});
 	});
 
-	test("still refuses a game that would run as root", () => {
+	it("still refuses a game that would run as root", () => {
 		expect(() =>
 			parseConfig(
 				written({