@serverkgg/bridge 0.0.21 → 0.1.2

package/src/modules/bridgeModule.ts

@@ -1,5 +1,13 @@
 import type { BridgeContext, BridgeReply } from "../context";
-import type { BridgeInstallOutcome, BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
+import type {
+	BridgeInstallOutcome,
+	BridgeKind,
+	BridgeOption,
+	BridgeRow,
+	BridgeStream,
+	BridgeUnavailable,
+	BridgeValues,
+} from "../core";
 import type { BridgeAddOutcome, BridgeDetail, BridgeDetailOutcome } from "../panel";
 import type {
 	BridgeCatalogEntry,
@@ -11,6 +19,8 @@ import type { BridgeBackupSnapshot, BridgeDescribeResult, BridgePendingFile } fr
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeSetupStep } from "../protocol/bridgeSetup";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
+import type { BridgeLifecycleSubject } from "./bridgeLifecycleSubject";
+import type { BridgeStopSignal } from "./bridgeStopSignal";
 
 export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
 
@@ -25,7 +35,11 @@ export interface BridgeLifecycleModule {
 	ready?: RegExp;
 	failed?: RegExp;
 	stopTimeoutSeconds?: number;
+	readyTimeoutSeconds?: number;
+	stopSignal?: BridgeStopSignal;
+	subject?: BridgeLifecycleSubject;
 	command(context: BridgeContext): Promise<string[]>;
+	environment?(context: BridgeContext): Promise<Record<string, string>>;
 	stop?(context: BridgeContext): Promise<void>;
 	onReady?(context: BridgeContext): Promise<void>;
 }
@@ -109,6 +123,7 @@ export interface BridgeSettingsModule {
 	protectedActions?: string[];
 	read(context: BridgeContext): Promise<BridgeValues>;
 	write?(context: BridgeContext, values: BridgeValues): Promise<void>;
+	unavailable?(context: BridgeContext): Promise<BridgeUnavailable>;
 }
 
 export type BridgeRowAction<Row extends BridgeRow = BridgeRow> = (
@@ -124,6 +139,7 @@ export interface BridgeActionsModule {
 	protectedActions?: string[];
 	requiresRunning?: boolean;
 	actions: Record<string, BridgeServerAction>;
+	unavailable?(context: BridgeContext): Promise<BridgeUnavailable>;
 }
 
 export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
@@ -134,6 +150,7 @@ export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	list(context: BridgeContext): Promise<Row[]>;
 	add?(context: BridgeContext, input: string): Promise<BridgeAddOutcome | undefined>;
 	actions?: Record<string, BridgeRowAction<Row>>;
+	unavailable?(context: BridgeContext, row: Row): Promise<BridgeUnavailable>;
 }
 
 export type BridgeDetailAction = (context: BridgeContext, args: BridgeValues) => Promise<BridgeDetailOutcome | null>;
@@ -158,6 +175,7 @@ export interface BridgeCatalogModule {
 	install(context: BridgeContext, id: string, releaseId?: string): Promise<BridgeCatalogEntry>;
 	remove(context: BridgeContext, id: string): Promise<void>;
 	toggle?(context: BridgeContext, id: string, enabled: boolean): Promise<void>;
+	unavailable?(context: BridgeContext, entry: BridgeCatalogEntry): Promise<BridgeUnavailable>;
 }
 
 export type BridgePanelModule =

package/src/modules/bridgeStopSignal.ts

@@ -0,0 +1,13 @@
+export enum BridgeStopSignal {
+	Term = "SIGTERM",
+	Interrupt = "SIGINT",
+}
+
+export const BRIDGE_STOP_SIGNALS: Record<BridgeStopSignal, NodeJS.Signals> = {
+	[BridgeStopSignal.Term]: "SIGTERM",
+	[BridgeStopSignal.Interrupt]: "SIGINT",
+};
+
+export const isBridgeStopSignal = (value: unknown): value is BridgeStopSignal => {
+	return typeof value === "string" && Object.hasOwn(BRIDGE_STOP_SIGNALS, value);
+};

package/src/modules/index.ts

@@ -1,3 +1,5 @@
 export * from "./bridge";
 export * from "./bridgeDriver";
+export * from "./bridgeLifecycleSubject";
 export * from "./bridgeModule";
+export * from "./bridgeStopSignal";

package/src/panel/bridgeDetail.ts

@@ -1,4 +1,5 @@
-import type { BridgeCopy, BridgeValue, LocalizedText } from "../core";
+import type { BridgeCopy, BridgeUnavailable, BridgeValue, LocalizedText } from "../core";
+import type { BridgeIcon } from "./bridgeIcon";
 
 export enum BridgeDetailTone {
 	Neutral = "neutral",
@@ -38,11 +39,13 @@ export interface BridgeDetail {
 	subtitle: BridgeCopy | null;
 	description: BridgeCopy | null;
 	image: string | null;
+	icon?: BridgeIcon;
 	badges: BridgeDetailBadge[];
 	stats: BridgeDetailStat[];
 	links: BridgeDetailLink[];
 	stale: boolean;
 	actions: string[];
+	unavailable?: BridgeUnavailable;
 }
 
 export interface BridgeDetailOutcome {

package/src/protocol/bridgeActivity.ts

@@ -0,0 +1,54 @@
+import type { BridgeActivity, BridgeValues } from "../core";
+
+export const BRIDGE_ACTIVITY_KEYS = {
+	ar: "activityAr",
+	en: "activityEn",
+	subject: "subject",
+} as const;
+
+export const BRIDGE_ACTIVITY_LIMIT = 8;
+
+export const BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT = 256;
+
+export const BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT = 64;
+
+export const BRIDGE_ACTIVITY_DETAILS_LIMIT = 16;
+
+export const BRIDGE_ACTIVITY_DETAIL_KEY_LENGTH_LIMIT = 64;
+
+export const BRIDGE_ACTIVITY_EXCERPT_LENGTH_LIMIT = 80;
+
+export const BRIDGE_ACTIVITY_NAME_LENGTH_LIMIT = 64;
+
+export const BRIDGE_ACTIVITY_NAME_PATTERN = /^[A-Z][A-Za-z0-9]*$/;
+
+export const BRIDGE_ACTIVITY_DETAIL_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+const ELLIPSIS = "…";
+
+export const isBridgeActivity = (payload: BridgeValues | null): boolean => {
+	return typeof payload?.[BRIDGE_ACTIVITY_KEYS.ar] === "string" && typeof payload[BRIDGE_ACTIVITY_KEYS.en] === "string";
+};
+
+export const activityPayload = (entry: BridgeActivity): BridgeValues => {
+	return {
+		...entry.details,
+		[BRIDGE_ACTIVITY_KEYS.ar]: entry.text.ar,
+		[BRIDGE_ACTIVITY_KEYS.en]: entry.text.en,
+		...(entry.subject === undefined
+			? {}
+			: {
+					[BRIDGE_ACTIVITY_KEYS.subject]: entry.subject,
+				}),
+	};
+};
+
+export const activityExcerpt = (text: string): string => {
+	const line = text.trim();
+
+	if (line.length <= BRIDGE_ACTIVITY_EXCERPT_LENGTH_LIMIT) {
+		return line;
+	}
+
+	return `${line.slice(0, BRIDGE_ACTIVITY_EXCERPT_LENGTH_LIMIT - ELLIPSIS.length).trimEnd()}${ELLIPSIS}`;
+};

package/src/protocol/bridgeConfig.ts

@@ -4,6 +4,8 @@ export interface BridgeConfig {
 	cwd: string;
 	run: string;
 	ports: Record<string, number>;
+	portCounts?: Record<string, number>;
+	publicAddress?: string;
 	memoryMb: number;
 	cpuPercent: number;
 	gameUid: number;

package/src/protocol/bridgeEvents.ts

@@ -1,23 +1,53 @@
 export enum BridgeEventName {
+	AccessGranted = "AccessGranted",
+	AccessRevoked = "AccessRevoked",
+	BroadcastSent = "BroadcastSent",
+	GameInstalled = "GameInstalled",
 	GameModeChanged = "GameModeChanged",
+	GameplayChanged = "GameplayChanged",
+	InstallFailed = "InstallFailed",
 	MemoryUndersized = "MemoryUndersized",
 	MissingDependency = "MissingDependency",
 	ModCrashed = "ModCrashed",
+	ModDisabled = "ModDisabled",
+	ModEnabled = "ModEnabled",
+	ModInstalled = "ModInstalled",
 	ModLoaded = "ModLoaded",
+	ModLoaderInstalled = "ModLoaderInstalled",
+	ModLoaderRemoved = "ModLoaderRemoved",
+	ModRemoved = "ModRemoved",
+	ModpackInstalled = "ModpackInstalled",
+	ModpackRemoved = "ModpackRemoved",
+	ModpackSelected = "ModpackSelected",
 	PlayerAdvanced = "PlayerAdvanced",
 	PlayerBanned = "PlayerBanned",
+	PlayerChanged = "PlayerChanged",
 	PlayerDied = "PlayerDied",
 	PlayerJoined = "PlayerJoined",
 	PlayerKicked = "PlayerKicked",
 	PlayerLeft = "PlayerLeft",
+	PlayerUnbanned = "PlayerUnbanned",
 	PortBindFailed = "PortBindFailed",
+	SecretRotated = "SecretRotated",
 	ServerCrashed = "ServerCrashed",
 	ServerStarted = "ServerStarted",
 	ServerStopping = "ServerStopping",
 	ServerUpdated = "ServerUpdated",
+	SettingsApplied = "SettingsApplied",
+	SettingsChanged = "SettingsChanged",
+	SetupAction = "SetupAction",
+	SetupCompleted = "SetupCompleted",
+	SetupRejected = "SetupRejected",
+	SignInExpired = "SignInExpired",
 	TickLagging = "TickLagging",
+	WorldActivated = "WorldActivated",
+	WorldCloned = "WorldCloned",
 	WorldCorrupt = "WorldCorrupt",
+	WorldCreated = "WorldCreated",
+	WorldDeleted = "WorldDeleted",
+	WorldImported = "WorldImported",
 	WorldSaved = "WorldSaved",
+	WorldWiped = "WorldWiped",
 	WrongJavaVersion = "WrongJavaVersion",
 }
 

package/src/protocol/bridgeFrame.ts

@@ -1,4 +1,11 @@
-import type { BridgeDesired, BridgeInstallHold, BridgeRuntime, BridgeValues, LocalizedText } from "../core";
+import type {
+	BridgeActivity,
+	BridgeDesired,
+	BridgeInstallHold,
+	BridgeRuntime,
+	BridgeValues,
+	LocalizedText,
+} from "../core";
 import type { BridgeSetupSummary } from "./bridgeSetup";
 
 export const BRIDGE_SOCKET_NAME = "bridge.sock";
@@ -59,6 +66,7 @@ export interface BridgeSuccess {
 	id: number | null;
 	ok: true;
 	result: unknown;
+	activity?: BridgeActivity[];
 }
 
 export interface BridgeFailure {
@@ -68,6 +76,7 @@ export interface BridgeFailure {
 	secret?: string;
 	failure?: string;
 	text?: LocalizedText;
+	unchanged?: boolean;
 }
 
 export type BridgeResponse = BridgeFailure | BridgeSuccess;

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);
+	});
+});