@serverkgg/bridge 0.0.21 → 0.1.2

package/src/runtime/serve.ts

@@ -1,14 +1,16 @@
 import { chmod, chown, mkdir, rm } from "node:fs/promises";
 import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError, type LocalizedText } from "../core";
-import type { BridgeDriver } from "../modules";
+import { type BridgeDriver, BridgeLifecycleSubject } from "../modules";
 import {
 	BRIDGE_INSTALL_ERROR_LIMIT,
 	BRIDGE_VERSION,
 	type BridgeConfig,
+	BridgeEventName,
 	type BridgePendingResult,
 	type BridgeSampleResult,
 	type BridgeStatus,
 } from "../protocol";
+import { type ActivityNormalizeOptions, createActivityReporter } from "./bridgeActivity";
 import { createBackupLease } from "./bridgeBackupLease";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
 import { createConsoleHandler } from "./bridgeConsoleHandler";
@@ -16,8 +18,10 @@ import { createContext } from "./bridgeContext";
 import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
 import { decideInstall, recountHold } from "./bridgeInstall";
-import { errorText, log } from "./bridgeLog";
+import { createBridgeLiveConfig } from "./bridgeLiveConfig";
+import { errorDetail, errorText, log as stdoutLog } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
+import { createBridgeRedaction, redactLocalized, redactLogger, secretFieldKeys } from "./bridgeRedaction";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
 import { setupSummaryOf } from "./bridgeSetup";
@@ -35,6 +39,17 @@ const DEFAULT_STOP_TIMEOUT_SECONDS = 30;
 
 const DEFAULT_SAMPLE_REFRESH_SECONDS = 30;
 
+const INSTALL_FAILED_TEXT: Record<BridgeLifecycleSubject, LocalizedText> = {
+	[BridgeLifecycleSubject.Game]: {
+		ar: "ما قدرنا نثبّت اللعبة. جرّب مرة ثانية.",
+		en: "We could not install the game. Try again.",
+	},
+	[BridgeLifecycleSubject.Bot]: {
+		ar: "ما قدرنا نثبّت كود بوتك. جرّب مرة ثانية.",
+		en: "We could not install your bot's code. Try again.",
+	},
+};
+
 const prepare = async (config: BridgeConfig) => {
 	await mkdir(config.cwd, {
 		recursive: true,
@@ -69,25 +84,42 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const desired = await readDesired(statePath(config));
 
+	const live = createBridgeLiveConfig(configPath(), config);
+
+	const redact = createBridgeRedaction(secretFieldKeys(driver), live);
+
+	const log = redactLogger(stdoutLog, redact);
+
 	let installError: string | null = null;
 
 	let installErrorText: LocalizedText | null = null;
 
 	let installHold: BridgeInstallHold | null = null;
 
-	const setup = createSetupHandlers(driver, log);
+	const setup = createSetupHandlers(driver, log, redact);
 
 	const supervisor = createSupervisor({
 		cwd: config.cwd,
 		uid: config.gameUid,
 		gid: config.gameGid,
 		stopTimeoutSeconds: driver.lifecycle.stopTimeoutSeconds ?? DEFAULT_STOP_TIMEOUT_SECONDS,
+		readyTimeoutSeconds: driver.lifecycle.readyTimeoutSeconds,
+		stopSignal: driver.lifecycle.stopSignal,
+		subject: driver.lifecycle.subject,
 		ready: driver.lifecycle.ready,
 		failed: driver.lifecycle.failed,
+		redact,
 		onLog: log,
 		async resolveCommand() {
+			live.reload();
+
 			return await driver.lifecycle.command(context);
 		},
+		resolveEnvironment: driver.lifecycle.environment
+			? async () => {
+					return (await driver.lifecycle.environment?.(context)) ?? {};
+				}
+			: undefined,
 		async gracefulStop() {
 			await driver.lifecycle.stop?.(context);
 		},
@@ -111,17 +143,47 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const ring = createEventRing(driver.events, supervisor);
 
-	const context = createContext(config, supervisor, {
-		onLog: log,
+	const activity: ActivityNormalizeOptions = {
+		secretKeys: new Set(secretFieldKeys(driver)),
+		redact,
+		warn: log.warn,
+	};
+
+	const reporter = createActivityReporter({
+		...activity,
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
-		onSetup(runtime) {
-			setup.onSetup(runtime);
-		},
 	});
 
-	const registry = createRegistry(driver, context, supervisor, ring);
+	const context = createContext(
+		config,
+		supervisor,
+		{
+			onLog: log,
+			onEmit(event, payload) {
+				ring.emit(event, payload);
+			},
+			onSetup(runtime) {
+				setup.onSetup(runtime);
+			},
+			onActivity(entry) {
+				reporter.report(entry);
+			},
+			async onRestart() {
+				if (current !== BridgeDesired.Running) {
+					throw new Error(
+						`the ${driver.lifecycle.subject ?? BridgeLifecycleSubject.Game} is not meant to be running, so there is nothing to restart`,
+					);
+				}
+
+				await supervisor.restart();
+			},
+		},
+		live,
+	);
+
+	const registry = createRegistry(driver, context, supervisor, ring, activity);
 	const backupLease = createBackupLease(async () => {
 		if (supervisor.running) {
 			await driver.backup?.release?.(context);
@@ -220,6 +282,7 @@ export const serve = async (driver: BridgeDriver) => {
 	const server = createServer({
 		socket: socketPath(config),
 		token: config.token,
+		redact,
 		onLog: log,
 		onStatus: status,
 		onManifest() {
@@ -375,6 +438,11 @@ export const serve = async (driver: BridgeDriver) => {
 		onSetupStatus() {
 			return setup.onSetupStatus();
 		},
+		onUndelivered(activity) {
+			for (const entry of activity) {
+				reporter.report(entry);
+			}
+		},
 		async onSetupSubmit(step, action, args) {
 			return await setup.onSetupSubmit(context, step, action, args);
 		},
@@ -428,8 +496,8 @@ export const serve = async (driver: BridgeDriver) => {
 
 		log("install complete");
 	} catch (error) {
-		installError = errorText(error).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
-		installErrorText = error instanceof BridgeUserError ? error.text : null;
+		installError = redact(errorDetail(error)).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
+		installErrorText = error instanceof BridgeUserError ? redactLocalized(error.text, redact) : null;
 
 		supervisor.setRuntime(BridgeRuntime.Crashed);
 
@@ -437,6 +505,14 @@ export const serve = async (driver: BridgeDriver) => {
 			error: installError,
 		});
 
+		context.activity.report({
+			name: BridgeEventName.InstallFailed,
+			text:
+				error instanceof BridgeUserError
+					? error.text
+					: INSTALL_FAILED_TEXT[driver.lifecycle.subject ?? BridgeLifecycleSubject.Game],
+		});
+
 		return;
 	}
 

package/src/steam/steamcmd.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { steamcmdArgv, steamcmdScript, steamcmdUpdateArgs } from "./steamcmd";
+import { steamcmdArgv, steamcmdFailureText, steamcmdScript, steamcmdUpdateArgs } from "./steamcmd";
 import { SteamcmdLoginKind, steamcmdLoginArgs } from "./steamcmdLogin";
 import { SteamcmdPlatform } from "./steamcmdPlatform";
 
@@ -155,3 +155,34 @@ describe("steamcmdUpdateArgs", () => {
 		]);
 	});
 });
+
+describe("steamcmdFailureText", () => {
+	test("says the download account does not own the app when steam answers no subscription", () => {
+		expect(
+			steamcmdFailureText(
+				{
+					stdout: "No subscription",
+					stderr: "",
+					code: 8,
+				},
+				"assetto",
+			).en,
+		).toBe("Steam refused to download assetto because the download account does not own it. Contact support.");
+	});
+
+	test("says the download failed for any other exit", () => {
+		expect(
+			steamcmdFailureText(
+				{
+					stdout: "",
+					stderr: "",
+					code: 8,
+				},
+				"palworld",
+			),
+		).toEqual({
+			ar: "ما قدرنا ننزّل palworld من Steam. جرّب مرة ثانية.",
+			en: "We could not download palworld from Steam. Try again.",
+		});
+	});
+});

package/src/steam/steamcmd.ts

@@ -1,4 +1,5 @@
-import type { BridgeContext } from "../context";
+import type { BridgeContext, BridgeExecResult } from "../context";
+import { BridgeUserError, type LocalizedText } from "../core";
 import { execDetail } from "../utils";
 import { installedBuildId } from "./steamApp";
 import { type SteamcmdLogin, SteamcmdLoginKind, steamcmdLoginArgs } from "./steamcmdLogin";
@@ -25,6 +26,8 @@ const ATTEMPTS = 3;
 
 const RETRY_DELAY_MS = 5000;
 
+const NO_SUBSCRIPTION = "No subscription";
+
 export interface SteamcmdOptions {
 	appId: string;
 	label: string;
@@ -100,6 +103,20 @@ export const steamcmdUpdateArgs = (appId: string, update: SteamcmdUpdateOptions)
 	return args;
 };
 
+export const steamcmdFailureText = (result: BridgeExecResult, label: string): LocalizedText => {
+	if (`${result.stdout}\n${result.stderr}`.includes(NO_SUBSCRIPTION)) {
+		return {
+			ar: `Steam رفض تنزيل ${label} لأن حساب التنزيل ما يملكه. راسل الدعم.`,
+			en: `Steam refused to download ${label} because the download account does not own it. Contact support.`,
+		};
+	}
+
+	return {
+		ar: `ما قدرنا ننزّل ${label} من Steam. جرّب مرة ثانية.`,
+		en: `We could not download ${label} from Steam. Try again.`,
+	};
+};
+
 const installRoot = async (context: BridgeContext) => {
 	const result = await context.exec([
 		"pwd",
@@ -162,7 +179,7 @@ export const createSteamcmd = (context: BridgeContext, options: SteamcmdOptions)
 
 		const attempts = runOptions.attempts ?? ATTEMPTS;
 
-		let failure = "";
+		let failure: BridgeExecResult | null = null;
 
 		for (let attempt = 1; attempt <= attempts; attempt++) {
 			const result = await context.exec(argv, {
@@ -178,7 +195,7 @@ export const createSteamcmd = (context: BridgeContext, options: SteamcmdOptions)
 				return;
 			}
 
-			failure = `steamcmd exited with code ${result.code} — ${execDetail(result)}`;
+			failure = result;
 
 			if (attempt < attempts) {
 				context.log("steamcmd did not finish, trying again", {
@@ -191,7 +208,13 @@ export const createSteamcmd = (context: BridgeContext, options: SteamcmdOptions)
 			}
 		}
 
-		throw new Error(failure);
+		if (!failure) {
+			throw new Error("steamcmd was not run");
+		}
+
+		throw new BridgeUserError(steamcmdFailureText(failure, options.label), {
+			cause: new Error(`steamcmd exited with code ${failure.code} — ${execDetail(failure)}`),
+		});
 	};
 
 	return {

package/src/utils/changedSettingKeys.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { changedSettingKeys } from "./changedSettingKeys";
+
+describe("changedSettingKeys", () => {
+	test("keeps only the keys whose value really changed", () => {
+		expect(
+			changedSettingKeys(
+				{
+					difficulty: "easy",
+					expRate: "1.000000",
+					pvp: "True",
+					name: "My server",
+				},
+				{
+					difficulty: "hard",
+					expRate: 1,
+					pvp: true,
+					name: "My server",
+				},
+			),
+		).toEqual([
+			"difficulty",
+		]);
+	});
+
+	test("counts a key the stored values do not hold as changed", () => {
+		expect(
+			changedSettingKeys(
+				{},
+				{
+					seed: "42",
+				},
+			),
+		).toEqual([
+			"seed",
+		]);
+	});
+
+	test("counts every written key as changed when nothing could be read first", () => {
+		const written = {
+			difficulty: "hard",
+			pvp: false,
+		};
+
+		expect(changedSettingKeys(null, written)).toEqual([
+			"difficulty",
+			"pvp",
+		]);
+		expect(changedSettingKeys(undefined, written)).toEqual([
+			"difficulty",
+			"pvp",
+		]);
+	});
+
+	test("answers nothing for an empty write", () => {
+		expect(
+			changedSettingKeys(
+				{
+					difficulty: "easy",
+				},
+				{},
+			),
+		).toEqual([]);
+	});
+});

package/src/utils/changedSettingKeys.ts

@@ -0,0 +1,6 @@
+import type { BridgeValues } from "../core";
+import { sameSettingValue } from "./sameSettingValue";
+
+export const changedSettingKeys = (before: BridgeValues | null | undefined, written: BridgeValues): string[] => {
+	return Object.keys(written).filter((key) => !before || !sameSettingValue(before[key], written[key]));
+};

package/src/utils/describeExecFailure.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { describeExecFailure } from "./describeExecFailure";
+
+describe("describeExecFailure", () => {
+	test("names the subject and the exit code in both languages", () => {
+		const text = describeExecFailure(
+			{
+				stdout: "",
+				stderr: "java.lang.RuntimeException",
+				code: 1,
+			},
+			"Forge installer",
+		);
+
+		expect(text).toEqual({
+			ar: "Forge installer فشل وطلع بكود 1.",
+			en: "Forge installer failed with exit code 1.",
+		});
+	});
+
+	test("keeps the process output out of the customer text", () => {
+		const text = describeExecFailure(
+			{
+				stdout: "token=abc",
+				stderr: "at /home/game/secret",
+				code: 2,
+			},
+			"unzip",
+		);
+
+		expect(JSON.stringify(text)).not.toContain("secret");
+		expect(JSON.stringify(text)).not.toContain("token");
+	});
+});

package/src/utils/describeExecFailure.ts

@@ -0,0 +1,9 @@
+import type { BridgeExecResult } from "../context";
+import type { LocalizedText } from "../core";
+
+export const describeExecFailure = (result: BridgeExecResult, subject: string): LocalizedText => {
+	return {
+		ar: `${subject} فشل وطلع بكود ${result.code}.`,
+		en: `${subject} failed with exit code ${result.code}.`,
+	};
+};

package/src/utils/index.ts

@@ -1,4 +1,7 @@
+export * from "./changedSettingKeys";
+export * from "./describeExecFailure";
 export * from "./execDetail";
 export * from "./glob";
+export * from "./sameSettingValue";
 export * from "./stripAnsi";
 export * from "./token";

package/src/utils/sameSettingValue.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { sameSettingValue } from "./sameSettingValue";
+
+describe("sameSettingValue", () => {
+	test("treats a float the ini codec wrote as equal to the integer the form sends", () => {
+		expect(sameSettingValue("1.000000", 1)).toBe(true);
+		expect(sameSettingValue("1", "1.000000")).toBe(true);
+	});
+
+	test("treats decimals that differ only in trailing zeros as equal", () => {
+		expect(sameSettingValue("0.5", "0.50")).toBe(true);
+	});
+
+	test("treats boolean text as equal whatever its case", () => {
+		expect(sameSettingValue("True", "true")).toBe(true);
+		expect(sameSettingValue("False", false)).toBe(true);
+		expect(sameSettingValue(true, "FALSE")).toBe(false);
+	});
+
+	test("never treats an empty value as zero", () => {
+		expect(sameSettingValue("", "0")).toBe(false);
+		expect(sameSettingValue(null, 0)).toBe(false);
+	});
+
+	test("keeps a leading-zero string different from its number, since it may be an id", () => {
+		expect(sameSettingValue("01", "1")).toBe(false);
+	});
+
+	test("compares the trimmed text of anything else", () => {
+		expect(sameSettingValue(" easy ", "easy")).toBe(true);
+		expect(sameSettingValue("easy", "hard")).toBe(false);
+		expect(sameSettingValue("2", "3")).toBe(false);
+		expect(sameSettingValue(undefined, "")).toBe(true);
+	});
+});

package/src/utils/sameSettingValue.ts

@@ -0,0 +1,40 @@
+import type { BridgeValue } from "../core";
+
+const PLAIN_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?$/;
+
+const BOOLEAN_TEXT: Readonly<Record<string, boolean>> = {
+	true: true,
+	false: false,
+};
+
+const settingText = (value: BridgeValue | undefined) => {
+	return value === undefined || value === null ? "" : String(value).trim();
+};
+
+const numberOf = (text: string) => {
+	return PLAIN_NUMBER.test(text) ? Number(text) : null;
+};
+
+const booleanOf = (text: string) => {
+	return BOOLEAN_TEXT[text.toLowerCase()] ?? null;
+};
+
+export const sameSettingValue = (left: BridgeValue | undefined, right: BridgeValue | undefined): boolean => {
+	const a = settingText(left);
+	const b = settingText(right);
+
+	if (a === b) {
+		return true;
+	}
+
+	const leftNumber = numberOf(a);
+	const rightNumber = numberOf(b);
+
+	if (leftNumber !== null && rightNumber !== null) {
+		return leftNumber === rightNumber;
+	}
+
+	const leftBoolean = booleanOf(a);
+
+	return leftBoolean !== null && leftBoolean === booleanOf(b);
+};

package/src/wire/activity.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { BRIDGE_ACTIVITY_DETAILS_LIMIT, BRIDGE_ACTIVITY_LIMIT, BridgeEventName } from "@serverkgg/bridge/protocol";
+import { bridgeActivitiesSchema, bridgeActivitySchema } from "./activity";
+
+const entry = {
+	name: BridgeEventName.ModpackInstalled,
+	text: {
+		ar: "ثبّتنا مودباك All the Mods 9",
+		en: "Installed modpack All the Mods 9",
+	},
+	subject: "All the Mods 9",
+	details: {
+		version: "0.3.2",
+		files: 312,
+	},
+};
+
+describe("bridgeActivitySchema", () => {
+	test("accepts a well-formed entry", () => {
+		expect(bridgeActivitySchema.parse(entry)).toEqual(entry);
+	});
+
+	test("accepts a name this reader does not know yet, so a newer game still reaches it", () => {
+		expect(
+			bridgeActivitySchema.safeParse({
+				...entry,
+				name: "PortalOpened",
+			}).success,
+		).toBe(true);
+	});
+
+	test("refuses a name that is not an event name", () => {
+		expect(
+			bridgeActivitySchema.safeParse({
+				...entry,
+				name: "portal opened",
+			}).success,
+		).toBe(false);
+	});
+
+	test("refuses an entry missing one language", () => {
+		expect(
+			bridgeActivitySchema.safeParse({
+				...entry,
+				text: {
+					ar: "",
+					en: "Installed",
+				},
+			}).success,
+		).toBe(false);
+	});
+
+	test("refuses more details than an entry carries", () => {
+		const details: Record<string, number> = {};
+
+		for (let index = 0; index <= BRIDGE_ACTIVITY_DETAILS_LIMIT; index++) {
+			details[`key${index}`] = index;
+		}
+
+		expect(
+			bridgeActivitySchema.safeParse({
+				...entry,
+				details,
+			}).success,
+		).toBe(false);
+	});
+
+	test("refuses a detail that is not a scalar", () => {
+		expect(
+			bridgeActivitySchema.safeParse({
+				...entry,
+				details: {
+					nested: {
+						deep: true,
+					},
+				},
+			}).success,
+		).toBe(false);
+	});
+});
+
+describe("bridgeActivitiesSchema", () => {
+	test("refuses more entries than one answer carries", () => {
+		expect(
+			bridgeActivitiesSchema.safeParse(
+				Array.from(
+					{
+						length: BRIDGE_ACTIVITY_LIMIT + 1,
+					},
+					() => entry,
+				),
+			).success,
+		).toBe(false);
+	});
+});

package/src/wire/activity.ts

@@ -0,0 +1,41 @@
+import {
+	BRIDGE_ACTIVITY_DETAIL_KEY_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_DETAIL_KEY_PATTERN,
+	BRIDGE_ACTIVITY_DETAILS_LIMIT,
+	BRIDGE_ACTIVITY_LIMIT,
+	BRIDGE_ACTIVITY_NAME_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_NAME_PATTERN,
+	BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT,
+	BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT,
+} from "@serverkgg/bridge/protocol";
+import { z } from "zod";
+
+const activityTextSchema = z.object({
+	ar: z.string().min(1).max(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT),
+	en: z.string().min(1).max(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT),
+});
+
+const activityDetailsSchema = z
+	.record(
+		z.string().min(1).max(BRIDGE_ACTIVITY_DETAIL_KEY_LENGTH_LIMIT).regex(BRIDGE_ACTIVITY_DETAIL_KEY_PATTERN),
+		z.union([
+			z.boolean(),
+			z.number(),
+			z.string().max(BRIDGE_ACTIVITY_TEXT_LENGTH_LIMIT),
+			z.null(),
+		]),
+	)
+	.refine((details) => Object.keys(details).length <= BRIDGE_ACTIVITY_DETAILS_LIMIT);
+
+export const bridgeActivitySchema = z.object({
+	name: z.string().min(1).max(BRIDGE_ACTIVITY_NAME_LENGTH_LIMIT).regex(BRIDGE_ACTIVITY_NAME_PATTERN),
+	text: activityTextSchema,
+	subject: z.string().min(1).max(BRIDGE_ACTIVITY_SUBJECT_LENGTH_LIMIT).optional(),
+	details: activityDetailsSchema.optional(),
+});
+
+export type BridgeActivityInput = z.infer<typeof bridgeActivitySchema>;
+
+export const bridgeActivitiesSchema = z.array(bridgeActivitySchema).max(BRIDGE_ACTIVITY_LIMIT);
+
+export type BridgeActivitiesInput = z.infer<typeof bridgeActivitiesSchema>;

package/src/wire/index.ts

@@ -1,2 +1,3 @@
+export * from "./activity";
 export * from "./panel";
 export * from "./zEnvKey";