@serverkgg/bridge 0.1.1 → 0.1.2

package/src/protocol/index.ts

@@ -1,6 +1,7 @@
 export * from "../core";
 export * from "../panel";
 export * from "../terminal";
+export * from "./bridgeActivity";
 export * from "./bridgeCatalog";
 export * from "./bridgeConfig";
 export * from "./bridgeCrash";

package/src/runtime/bridgeActions.ts

@@ -1,10 +1,21 @@
 import { BridgeAction, BridgeKind } from "../core";
 import type { BridgePanelModule } from "../modules";
 
+const advertisedAvailability = (advertised: boolean): string[] => {
+	return advertised
+		? [
+				BridgeAction.Availability,
+			]
+		: [];
+};
+
 export const actionsOf = (module: BridgePanelModule): string[] => {
 	switch (module.kind) {
 		case BridgeKind.Actions: {
-			return Object.keys(module.actions);
+			return [
+				...Object.keys(module.actions),
+				...advertisedAvailability(module.unavailable !== undefined),
+			];
 		}
 
 		case BridgeKind.Options: {
@@ -27,6 +38,7 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 							BridgeAction.Write,
 						]
 					: []),
+				...advertisedAvailability(module.unavailable !== undefined),
 			];
 		}
 
@@ -39,13 +51,17 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 						]
 					: []),
 				...Object.keys(module.actions ?? {}),
+				...advertisedAvailability(module.unavailable !== undefined),
 			];
 		}
 
 		case BridgeKind.Detail: {
+			const actions = Object.keys(module.actions ?? {});
+
 			return [
 				BridgeAction.Read,
-				...Object.keys(module.actions ?? {}),
+				...actions,
+				...advertisedAvailability(actions.length > 0),
 			];
 		}
 
@@ -70,6 +86,7 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 							BridgeAction.Toggle,
 						]
 					: []),
+				...advertisedAvailability(module.unavailable !== undefined),
 			];
 		}
 	}

package/src/runtime/bridgeActivity.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, test } 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", () => {
+	test("keeps a well-formed entry as it is", () => {
+		const { options, warnings } = recorder();
+
+		expect(normalizeActivity(granted(), options)).toEqual(granted());
+		expect(warnings).toEqual([]);
+	});
+
+	test("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",
+				},
+			},
+		]);
+	});
+
+	test("drops an entry whose text is empty in one language", () => {
+		const { options } = recorder();
+
+		expect(
+			normalizeActivity(
+				{
+					...granted(),
+					text: {
+						ar: "  ",
+						en: "Added Steve",
+					},
+				},
+				options,
+			),
+		).toBeNull();
+	});
+
+	test("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",
+		]);
+	});
+
+	test("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);
+	});
+
+	test("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",
+		});
+	});
+
+	test("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", () => {
+	test("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",
+				},
+			},
+		]);
+	});
+
+	test("emits nothing for an entry normalisation drops", () => {
+		const { reporter, emitted } = recorder();
+
+		reporter.report({
+			...granted(),
+			name: "Nope" as BridgeEventName,
+		});
+
+		expect(emitted).toEqual([]);
+	});
+});
+
+describe("createActivityScope", () => {
+	test("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([]);
+	});
+
+	test("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([]);
+	});
+
+	test("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",
+		]);
+	});
+
+	test("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);
+	});
+
+	test("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/bridgeContext.test.ts

@@ -72,6 +72,9 @@ describe("the context's variable maps", () => {
 				onSetup() {
 					return;
 				},
+				onActivity() {
+					return;
+				},
 				async onRestart() {
 					return;
 				},
@@ -158,6 +161,9 @@ describe("the context's ports and address", () => {
 					onSetup() {
 						return;
 					},
+					onActivity() {
+						return;
+					},
 					async onRestart() {
 						return;
 					},

package/src/runtime/bridgeContext.ts

@@ -1,5 +1,5 @@
 import type { BridgeContext } from "../context";
-import type { BridgeValues } from "../core";
+import type { BridgeActivity, BridgeValues } from "../core";
 import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
 import { stripAnsi } from "../utils";
 import { createBridgeCodecs } from "./bridgeCodec";
@@ -18,6 +18,7 @@ export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
 	onSetup: (runtime: BridgeSetupRuntime | null) => void;
+	onActivity: (entry: BridgeActivity) => void;
 	onRestart: () => Promise<void>;
 }
 
@@ -141,6 +142,12 @@ export const createContext = (
 			},
 		},
 
+		activity: {
+			report(entry) {
+				hooks.onActivity(entry);
+			},
+		},
+
 		emit(event, payload) {
 			hooks.onEmit(event, payload);
 		},