@serverkgg/bridge 0.1.1 → 0.1.2

package/src/runtime/bridgeRegistry.ts

@@ -1,17 +1,50 @@
 import type { BridgeContext } from "../context";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
-import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
-import { BridgeLayout } from "../panel";
 import {
+	BRIDGE_AVAILABILITY_KEY_PATTERN,
+	BridgeAction,
+	type BridgeActivity,
+	type BridgeAvailability,
+	BridgeKind,
+	type BridgeRow,
+	type BridgeUnavailable,
+	type BridgeValues,
+	isLocalizedText,
+	isReadAction,
+	type LocalizedText,
+} from "../core";
+import type {
+	BridgeCatalogModule,
+	BridgeCollectionModule,
+	BridgeDriver,
+	BridgePanelModule,
+	BridgeSettingsModule,
+	BridgeSetupModule,
+	BridgeTerminalModule,
+} from "../modules";
+import { type BridgeDetail, BridgeLayout } from "../panel";
+import {
+	BRIDGE_KEY_LENGTH_LIMIT,
+	BRIDGE_TEXT_LENGTH_LIMIT,
 	BRIDGE_VERSION,
+	BridgeEventName,
 	type BridgeManifest,
 	type BridgeModuleManifest,
 	type BridgeSetupManifest,
 	type BridgeTerminalManifest,
 } from "../protocol";
+import { changedSettingKeys } from "../utils";
 import { actionsOf } from "./bridgeActions";
+import {
+	type ActivityNormalizeOptions,
+	type BridgeActivityAnswer,
+	type BridgeActivityScope,
+	createActivityScope,
+} from "./bridgeActivity";
 import { BridgeDriverError } from "./bridgeDriver";
 import type { BridgeEventRing } from "./bridgeEvents";
+import { errorText } from "./bridgeLog";
+import { BridgeRefusalError } from "./bridgeRefusalError";
+import { scopedContext } from "./bridgeScopedContext";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 interface CacheEntry {
@@ -19,6 +52,11 @@ interface CacheEntry {
 	expiresAt: number;
 }
 
+const UNAVAILABLE_TEXT: LocalizedText = {
+	ar: "هذا الإجراء مو متاح الحين",
+	en: "This action is not available right now",
+};
+
 const requiresRunning = (module: BridgePanelModule) => {
 	if (
 		module.kind === BridgeKind.Actions
@@ -87,53 +125,9 @@ const setupManifestOf = (module: BridgeSetupModule | undefined): BridgeSetupMani
 	};
 };
 
-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);
-		},
-		variables() {
-			return {
-				...context.variables(),
-				...overlay,
-			};
-		},
-		secret(key) {
-			return context.secret(key);
-		},
-		secrets() {
-			return context.secrets();
-		},
-		port(key) {
-			return context.port(key);
-		},
-		portBlock(key) {
-			return context.portBlock(key);
-		},
-		files: context.files,
-		codec: context.codec,
-		net: context.net,
-		probe: context.probe,
-		rcon: context.rcon,
-		command(input, options) {
-			return context.command(input, options);
-		},
-		exec(command, options) {
-			return context.exec(command, options);
-		},
-		logs: context.logs,
-		setup: context.setup,
-		emit(event, payload) {
-			context.emit(event, payload);
-		},
-		restart() {
-			return context.restart();
-		},
-		log: context.log,
-	};
+const SETTINGS_CHANGED_TEXT: LocalizedText = {
+	ar: "تم تغيير الإعدادات",
+	en: "Changed the settings",
 };
 
 const asString = (args: BridgeValues, key: string) => {
@@ -176,6 +170,65 @@ const asPage = (args: BridgeValues) => {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 };
 
+const guardedActionsOf = (module: BridgePanelModule): string[] => {
+	switch (module.kind) {
+		case BridgeKind.Actions: {
+			return Object.keys(module.actions);
+		}
+
+		case BridgeKind.Collection:
+		case BridgeKind.Detail: {
+			return Object.keys(module.actions ?? {});
+		}
+
+		case BridgeKind.Settings: {
+			return module.write
+				? [
+						BridgeAction.Write,
+					]
+				: [];
+		}
+
+		case BridgeKind.Catalog: {
+			return [
+				BridgeAction.Remove,
+				...(module.toggle
+					? [
+							BridgeAction.Toggle,
+						]
+					: []),
+			];
+		}
+
+		default: {
+			return [];
+		}
+	}
+};
+
+const isAvailabilityKey = (key: string) => {
+	return key.length <= BRIDGE_KEY_LENGTH_LIMIT && BRIDGE_AVAILABILITY_KEY_PATTERN.test(key);
+};
+
+const refuse = (name: string, action: string, reasons: BridgeUnavailable) => {
+	const text = reasons[action];
+
+	if (text) {
+		throw new BridgeRefusalError(`module "${name}" cannot run "${action}" right now`, text);
+	}
+};
+
+const settingsChanged = (keys: string[]): BridgeActivity => {
+	return {
+		name: BridgeEventName.SettingsChanged,
+		text: SETTINGS_CHANGED_TEXT,
+		details: {
+			keys: keys.join(","),
+			count: keys.length,
+		},
+	};
+};
+
 const offlineActionsOf = (driver: BridgeDriver): Map<string, Set<string>> => {
 	const offline = new Map<string, Set<string>>();
 
@@ -201,9 +254,10 @@ const offlineActionsOf = (driver: BridgeDriver): Map<string, Set<string>> => {
 
 export const createRegistry = (
 	driver: BridgeDriver,
-	context: BridgeContext,
+	base: BridgeContext,
 	supervisor: BridgeSupervisor,
 	ring: BridgeEventRing,
+	activity: ActivityNormalizeOptions,
 ) => {
 	const cache = new Map<string, CacheEntry>();
 	const inflight = new Map<string, Promise<unknown>>();
@@ -211,7 +265,11 @@ export const createRegistry = (
 	const offlineActions = offlineActionsOf(driver);
 
 	for (const [id, module] of Object.entries(modules)) {
-		if (module.kind !== BridgeKind.Actions && module.kind !== BridgeKind.Detail) {
+		if (
+			module.kind !== BridgeKind.Actions
+			&& module.kind !== BridgeKind.Collection
+			&& module.kind !== BridgeKind.Detail
+		) {
 			continue;
 		}
 
@@ -262,12 +320,286 @@ export const createRegistry = (
 		}
 	};
 
-	const dispatch = async (module: BridgePanelModule, name: string, action: string, args: BridgeValues) => {
+	const listings = new Map<string, Promise<BridgeRow[]>>();
+
+	const listFresh = (module: BridgeCollectionModule, name: string, context: BridgeContext) => {
+		const rows = Promise.resolve().then(() => module.list(context));
+
+		listings.set(name, rows);
+
+		const settle = () => {
+			if (listings.get(name) === rows) {
+				listings.delete(name);
+			}
+		};
+
+		rows.then(settle, settle);
+
+		return rows;
+	};
+
+	const listForAvailability = (module: BridgeCollectionModule, name: string, context: BridgeContext) => {
+		return listings.get(name) ?? listFresh(module, name, context);
+	};
+
+	const reasonOf = (text: LocalizedText): LocalizedText => {
+		const ar = activity.redact(text.ar.trim()).slice(0, BRIDGE_TEXT_LENGTH_LIMIT);
+		const en = activity.redact(text.en.trim()).slice(0, BRIDGE_TEXT_LENGTH_LIMIT);
+
+		return ar.length > 0 && en.length > 0
+			? {
+					ar,
+					en,
+				}
+			: UNAVAILABLE_TEXT;
+	};
+
+	const unavailableOf = (name: string, raw: unknown, guarded: readonly string[]): BridgeUnavailable => {
+		const kept: BridgeUnavailable = {};
+
+		if (raw === undefined || raw === null) {
+			return kept;
+		}
+
+		if (typeof raw !== "object" || Array.isArray(raw)) {
+			activity.warn("availability answer is not an object, it is ignored", {
+				module: name,
+			});
+
+			return kept;
+		}
+
+		const dropped: string[] = [];
+
+		for (const [action, text] of Object.entries(raw)) {
+			if (!guarded.includes(action) || !isAvailabilityKey(action) || !isLocalizedText(text)) {
+				dropped.push(action);
+
+				continue;
+			}
+
+			kept[action] = reasonOf(text);
+		}
+
+		if (dropped.length > 0) {
+			activity.warn("availability names actions the module cannot refuse, they are ignored", {
+				module: name,
+				actions: dropped.join(","),
+			});
+		}
+
+		return kept;
+	};
+
+	const isSubjectId = (name: string, id: unknown): id is string => {
+		if (typeof id === "string" && id.length > 0) {
+			return true;
+		}
+
+		activity.warn("availability skipped a subject without an id", {
+			module: name,
+		});
+
+		return false;
+	};
+
+	const askUnavailable = async (
+		name: string,
+		guarded: readonly string[],
+		ask: () => Promise<unknown> | undefined,
+	): Promise<BridgeUnavailable> => {
+		try {
+			return unavailableOf(name, await ask(), guarded);
+		} catch (error) {
+			activity.warn("availability could not be read, the actions count as available", {
+				module: name,
+				error: errorText(error),
+			});
+
+			return {};
+		}
+	};
+
+	const detailUnavailable = (name: string, detail: BridgeDetail, guarded: readonly string[]): BridgeUnavailable => {
+		const reasons = unavailableOf(name, detail.unavailable, guarded);
+		const pressable = Array.isArray(detail.actions) ? detail.actions : [];
+		const closed: BridgeUnavailable = {};
+
+		for (const action of guarded) {
+			if (!pressable.includes(action) && isAvailabilityKey(action)) {
+				closed[action] = reasons[action] ?? UNAVAILABLE_TEXT;
+			}
+		}
+
+		return closed;
+	};
+
+	const availabilityOf = async (
+		module: BridgePanelModule,
+		name: string,
+		args: BridgeValues,
+		context: BridgeContext,
+	): Promise<BridgeAvailability> => {
+		const guarded = guardedActionsOf(module);
+		const id = asOptional(args, "id");
+		const availability: BridgeAvailability = {
+			module: {},
+			subjects: {},
+		};
+
+		switch (module.kind) {
+			case BridgeKind.Collection: {
+				if (!module.unavailable) {
+					break;
+				}
+
+				for (const row of await listForAvailability(module, name, context)) {
+					if (!isSubjectId(name, row.id)) {
+						continue;
+					}
+
+					if (id !== null && row.id !== id) {
+						continue;
+					}
+
+					const reasons = await askUnavailable(name, guarded, () => module.unavailable?.(context, row));
+
+					if (Object.keys(reasons).length > 0) {
+						availability.subjects[row.id] = reasons;
+					}
+				}
+
+				break;
+			}
+
+			case BridgeKind.Catalog: {
+				if (!module.unavailable) {
+					break;
+				}
+
+				for (const entry of await module.installed(context)) {
+					if (!isSubjectId(name, entry.id)) {
+						continue;
+					}
+
+					if (id !== null && entry.id !== id) {
+						continue;
+					}
+
+					const reasons = await askUnavailable(name, guarded, () => module.unavailable?.(context, entry));
+
+					if (Object.keys(reasons).length > 0) {
+						availability.subjects[entry.id] = reasons;
+					}
+				}
+
+				break;
+			}
+
+			case BridgeKind.Actions:
+			case BridgeKind.Settings: {
+				availability.module = await askUnavailable(name, guarded, () => module.unavailable?.(context));
+
+				break;
+			}
+
+			case BridgeKind.Detail: {
+				const detail = await module.read(context);
+
+				if (detail) {
+					availability.module = detailUnavailable(name, detail, guarded);
+				}
+
+				break;
+			}
+		}
+
+		return availability;
+	};
+
+	const refuseEntry = async (
+		module: BridgeCatalogModule,
+		name: string,
+		action: string,
+		id: string,
+		context: BridgeContext,
+	) => {
+		if (!module.unavailable) {
+			return;
+		}
+
+		refuse(
+			name,
+			action,
+			await askUnavailable(name, guardedActionsOf(module), async () => {
+				const entry = (await module.installed(context)).find((installed) => installed.id === id);
+
+				return entry ? await module.unavailable?.(context, entry) : undefined;
+			}),
+		);
+	};
+
+	const readBefore = async (module: BridgeSettingsModule, scoped: BridgeContext, name: string) => {
+		try {
+			return {
+				...(await module.read(scoped)),
+			};
+		} catch (error) {
+			activity.warn("settings could not be read before the write", {
+				module: name,
+				error: errorText(error),
+			});
+
+			return null;
+		}
+	};
+
+	const reportSettingsDefault = (
+		scope: BridgeActivityScope,
+		before: BridgeValues | null,
+		written: BridgeValues,
+		name: string,
+	) => {
+		try {
+			const keys = changedSettingKeys(before, written);
+
+			if (scope.reported === 0 && keys.length > 0) {
+				scope.reporter.report(settingsChanged(keys));
+			}
+		} catch (error) {
+			activity.warn("settings change could not be reported", {
+				module: name,
+				error: errorText(error),
+			});
+		}
+	};
+
+	const dispatch = async (
+		module: BridgePanelModule,
+		name: string,
+		action: string,
+		args: BridgeValues,
+		scope: BridgeActivityScope,
+	) => {
+		const context = scopedContext(base, scope.reporter);
+
+		if (action === BridgeAction.Availability && actionsOf(module).includes(BridgeAction.Availability)) {
+			return await availabilityOf(module, name, args, context);
+		}
+
 		switch (module.kind) {
 			case BridgeKind.Actions: {
 				const serverAction = module.actions[action];
 
 				if (serverAction) {
+					if (module.unavailable) {
+						refuse(
+							name,
+							action,
+							await askUnavailable(name, guardedActionsOf(module), () => module.unavailable?.(context)),
+						);
+					}
+
 					await serverAction(context, args);
 
 					return null;
@@ -288,7 +620,7 @@ export const createRegistry = (
 						}
 					}
 
-					const scoped = withVariables(context, overlay);
+					const scoped = scopedContext(base, scope.reporter, overlay);
 
 					const key = [
 						name,
@@ -311,7 +643,7 @@ export const createRegistry = (
 						}
 					}
 
-					const scoped = withVariables(context, overlay);
+					const scoped = scopedContext(base, scope.reporter, overlay);
 
 					return await module.preview(scoped, args);
 				}
@@ -325,8 +657,20 @@ export const createRegistry = (
 				}
 
 				if (action === BridgeAction.Write && module.write) {
+					if (module.unavailable) {
+						refuse(
+							name,
+							action,
+							await askUnavailable(name, guardedActionsOf(module), () => module.unavailable?.(context)),
+						);
+					}
+
+					const before = await readBefore(module, context, name);
+
 					await module.write(context, args);
 
+					reportSettingsDefault(scope, before, args, name);
+
 					return null;
 				}
 
@@ -335,7 +679,7 @@ export const createRegistry = (
 
 			case BridgeKind.Collection: {
 				if (action === BridgeAction.List) {
-					return await module.list(context);
+					return await listFresh(module, name, context);
 				}
 
 				if (action === BridgeAction.Add && module.add) {
@@ -357,7 +701,17 @@ export const createRegistry = (
 							: undefined);
 
 					if (!row) {
-						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);
+						throw new BridgeRefusalError(`module "${name}" has no row "${id}"`);
+					}
+
+					if (module.unavailable) {
+						refuse(
+							name,
+							action,
+							await askUnavailable(name, guardedActionsOf(module), () =>
+								module.unavailable?.(context, row as BridgeRow),
+							),
+						);
 					}
 
 					await rowAction(context, row as BridgeRow, withoutId(args));
@@ -376,6 +730,18 @@ export const createRegistry = (
 				const detailAction = module.actions?.[action];
 
 				if (detailAction) {
+					const guarded = guardedActionsOf(module);
+
+					refuse(
+						name,
+						action,
+						await askUnavailable(name, guarded, async () => {
+							const detail = await module.read(context);
+
+							return detail ? detailUnavailable(name, detail, guarded) : undefined;
+						}),
+					);
+
 					return await detailAction(context, args);
 				}
 
@@ -408,13 +774,19 @@ export const createRegistry = (
 				}
 
 				if (action === BridgeAction.Remove) {
-					await module.remove(context, asString(args, "id"));
+					const id = asString(args, "id");
+
+					await refuseEntry(module, name, action, id, context);
+					await module.remove(context, id);
 
 					return null;
 				}
 
 				if (action === BridgeAction.Toggle && module.toggle) {
-					await module.toggle(context, asString(args, "id"), args.enabled !== false);
+					const id = asString(args, "id");
+
+					await refuseEntry(module, name, action, id, context);
+					await module.toggle(context, id, args.enabled !== false);
 
 					return null;
 				}
@@ -423,7 +795,7 @@ export const createRegistry = (
 			}
 		}
 
-		throw new BridgeDriverError(`module "${name}" does not support "${action}"`);
+		throw new BridgeRefusalError(`module "${name}" does not support "${action}"`);
 	};
 
 	return {
@@ -456,22 +828,49 @@ export const createRegistry = (
 			};
 		},
 
-		async invoke(name: string, action: string, args: BridgeValues = {}, recoveryOperationId?: string) {
+		async invoke(
+			name: string,
+			action: string,
+			args: BridgeValues = {},
+			recoveryOperationId?: string,
+		): Promise<BridgeActivityAnswer<unknown>> {
 			const module = modules[name];
 
 			if (!module) {
-				throw new BridgeDriverError(`no module named "${name}"`);
+				throw new BridgeRefusalError(`no module named "${name}"`);
 			}
 
 			if (protectedActionsOf(module).includes(action) && (!recoveryOperationId || supervisor.running)) {
-				throw new BridgeDriverError("this action needs a recovery operation with the game stopped");
+				throw new BridgeRefusalError("this action needs a recovery operation with the game stopped");
 			}
 
 			if (requiresRunning(module) && !supervisor.running) {
-				throw new BridgeDriverError(`module "${name}" needs the game to be running`);
+				throw new BridgeRefusalError(`module "${name}" needs the game to be running`);
+			}
+
+			const scope = createActivityScope(base.activity, activity);
+			const mutation = !isReadAction(action);
+
+			if (mutation) {
+				listings.clear();
 			}
 
-			return await dispatch(module, name, action, args);
+			try {
+				const result = await dispatch(module, name, action, args, scope);
+
+				return {
+					result,
+					activity: scope.close(),
+				};
+			} catch (error) {
+				scope.drain();
+
+				throw error;
+			} finally {
+				if (mutation) {
+					listings.clear();
+				}
+			}
 		},
 	};
 };

package/src/runtime/bridgeScopedContext.ts

@@ -0,0 +1,55 @@
+import type { BridgeActivityReporter, BridgeContext } from "../context";
+
+export const scopedContext = (
+	context: BridgeContext,
+	activity: BridgeActivityReporter,
+	overlay: Record<string, string> = {},
+): BridgeContext => {
+	return {
+		get server() {
+			return context.server;
+		},
+		variable(key) {
+			return Object.hasOwn(overlay, key) ? (overlay[key] ?? null) : context.variable(key);
+		},
+		variables() {
+			return {
+				...context.variables(),
+				...overlay,
+			};
+		},
+		secret(key) {
+			return context.secret(key);
+		},
+		secrets() {
+			return context.secrets();
+		},
+		port(key) {
+			return context.port(key);
+		},
+		portBlock(key) {
+			return context.portBlock(key);
+		},
+		files: context.files,
+		codec: context.codec,
+		net: context.net,
+		probe: context.probe,
+		rcon: context.rcon,
+		command(input, options) {
+			return context.command(input, options);
+		},
+		exec(command, options) {
+			return context.exec(command, options);
+		},
+		logs: context.logs,
+		setup: context.setup,
+		activity,
+		emit(event, payload) {
+			context.emit(event, payload);
+		},
+		restart() {
+			return context.restart();
+		},
+		log: context.log,
+	};
+};