@serverkgg/bridge 0.1.1 → 0.1.2

package/src/runtime/bridgeServer.ts

@@ -1,5 +1,12 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeFailureError, BridgeSecretError, BridgeUserError, type BridgeValues } from "../core";
+import type { Socket } from "bun";
+import {
+	type BridgeActivity,
+	BridgeFailureError,
+	BridgeSecretError,
+	BridgeUserError,
+	type BridgeValues,
+} from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
 	type BridgeAnnounceResult,
@@ -15,8 +22,10 @@ import {
 	type BridgeSetupResult,
 	type BridgeStatus,
 } from "../protocol";
-import { type BridgeLogger, errorText } from "./bridgeLog";
+import type { BridgeActivityAnswer } from "./bridgeActivity";
+import { type BridgeLogger, errorDetail } from "./bridgeLog";
 import { redactLocalized } from "./bridgeRedaction";
+import { BridgeRefusalError } from "./bridgeRefusalError";
 
 export interface ServerOptions {
 	socket: string;
@@ -26,7 +35,12 @@ export interface ServerOptions {
 	onStart: () => Promise<void>;
 	onStop: () => Promise<void>;
 	onCommand: (input: string, expect: string | undefined, timeoutMs: number | undefined) => Promise<BridgeCommandResult>;
-	onInvoke: (module: string, action: string, args: BridgeValues, recoveryOperationId?: string) => Promise<unknown>;
+	onInvoke: (
+		module: string,
+		action: string,
+		args: BridgeValues,
+		recoveryOperationId?: string,
+	) => Promise<BridgeActivityAnswer<unknown>>;
 	onEvents: (cursor: number) => BridgeEventsResult;
 	onSample: () => Promise<BridgeSampleResult>;
 	onQuiesce: (supportsSnapshot: boolean, leaseId?: string) => Promise<BridgeQuiesceResult>;
@@ -36,11 +50,17 @@ export interface ServerOptions {
 	onPendingList: () => Promise<BridgePendingResult>;
 	onPendingAdd: (input: string) => Promise<BridgePendingResult>;
 	onSetupStatus: () => BridgeSetupResult;
-	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeSetupResult>;
+	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeActivityAnswer<BridgeSetupResult>>;
+	onUndelivered: (activity: BridgeActivity[]) => void;
 	onLog: BridgeLogger;
 	redact?: (text: string) => string;
 }
 
+interface SocketState {
+	buffer: string;
+	closed: boolean;
+}
+
 interface IncomingFrame {
 	leaseId?: unknown;
 	supportsSnapshot?: unknown;
@@ -73,6 +93,23 @@ const encode = (response: BridgeResponse) => {
 	return `${JSON.stringify(response)}\n`;
 };
 
+interface PlainAnswer {
+	result: unknown;
+	activity: null;
+}
+
+const deliver = (socket: Socket<SocketState>, frame: string): boolean => {
+	if (socket.data.closed) {
+		return false;
+	}
+
+	try {
+		return socket.write(frame) === Buffer.byteLength(frame);
+	} catch {
+		return false;
+	}
+};
+
 const asArgs = (value: unknown): BridgeValues => {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) {
 		return {};
@@ -90,10 +127,10 @@ const asArgs = (value: unknown): BridgeValues => {
 };
 
 const logFailure = (onLog: BridgeLogger, method: string, error: unknown) => {
-	if (error instanceof BridgeUserError) {
+	if (error instanceof BridgeUserError || error instanceof BridgeRefusalError) {
 		onLog("bridge call refused", {
 			method,
-			error: error.message,
+			error: errorDetail(error),
 		});
 
 		return;
@@ -101,7 +138,7 @@ const logFailure = (onLog: BridgeLogger, method: string, error: unknown) => {
 
 	onLog("bridge call failed", {
 		method,
-		error: errorText(error),
+		error: errorDetail(error),
 		stack: error instanceof Error ? (error.stack ?? null) : null,
 	});
 };
@@ -137,15 +174,6 @@ export const createServer = (options: ServerOptions) => {
 				);
 			}
 
-			case BridgeMethod.Invoke: {
-				return await options.onInvoke(
-					String(request.module ?? ""),
-					String(request.action ?? ""),
-					asArgs(request.args),
-					asText(request.recoveryOperationId) ?? undefined,
-				);
-			}
-
 			case BridgeMethod.Events: {
 				return options.onEvents(typeof request.cursor === "number" ? request.cursor : 0);
 			}
@@ -196,33 +224,68 @@ export const createServer = (options: ServerOptions) => {
 				return options.onSetupStatus();
 			}
 
-			case BridgeMethod.SetupSubmit: {
-				const step = asText(request.module);
+			default: {
+				throw new Error(`unknown method "${method}"`);
+			}
+		}
+	};
 
-				if (!step) {
-					throw new Error("setupSubmit needs a step id");
-				}
+	const answer = async (
+		method: string,
+		request: IncomingFrame,
+	): Promise<BridgeActivityAnswer<unknown> | PlainAnswer> => {
+		if (method === BridgeMethod.Invoke) {
+			return await options.onInvoke(
+				String(request.module ?? ""),
+				String(request.action ?? ""),
+				asArgs(request.args),
+				asText(request.recoveryOperationId) ?? undefined,
+			);
+		}
 
-				return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
-			}
+		if (method === BridgeMethod.SetupSubmit) {
+			const step = asText(request.module);
 
-			default: {
-				throw new Error(`unknown method "${method}"`);
+			if (!step) {
+				throw new Error("setupSubmit needs a step id");
 			}
+
+			return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
 		}
+
+		return {
+			result: await handle(method, request),
+			activity: null,
+		};
 	};
 
-	return Bun.listen<{
-		buffer: string;
-	}>({
+	const undelivered = (method: string, activity: BridgeActivity[]) => {
+		if (activity.length === 0) {
+			return;
+		}
+
+		options.onLog("answer not delivered, its activity goes to the events ring", {
+			method,
+			entries: activity.length,
+		});
+
+		options.onUndelivered(activity);
+	};
+
+	return Bun.listen<SocketState>({
 		unix: options.socket,
 		socket: {
 			open(socket) {
 				socket.data = {
 					buffer: "",
+					closed: false,
 				};
 			},
 
+			close(socket) {
+				socket.data.closed = true;
+			},
+
 			data(socket, chunk) {
 				socket.data.buffer += chunk.toString();
 
@@ -278,15 +341,32 @@ export const createServer = (options: ServerOptions) => {
 						continue;
 					}
 
-					void handle(String(request.method ?? ""), request)
-						.then((result) => {
-							socket.write(
-								encode({
+					void answer(String(request.method ?? ""), request)
+						.then(({ result, activity }) => {
+							const method = String(request.method ?? "");
+
+							let frame: string;
+
+							try {
+								frame = encode({
 									id,
 									ok: true,
 									result,
-								}),
-							);
+									...(activity === null
+										? {}
+										: {
+												activity,
+											}),
+								});
+							} catch (error) {
+								undelivered(method, activity ?? []);
+
+								throw error;
+							}
+
+							if (!deliver(socket, frame)) {
+								undelivered(method, activity ?? []);
+							}
 						})
 						.catch((error: unknown) => {
 							logFailure(options.onLog, String(request.method ?? ""), error);
@@ -297,7 +377,7 @@ export const createServer = (options: ServerOptions) => {
 								encode({
 									id,
 									ok: false,
-									error: redact(errorText(error)),
+									error: redact(errorDetail(error)),
 									...(error instanceof BridgeSecretError
 										? {
 												secret: error.key,
@@ -313,6 +393,16 @@ export const createServer = (options: ServerOptions) => {
 												text: redactLocalized(error.text, redact),
 											}
 										: {}),
+									...(error instanceof BridgeRefusalError
+										? {
+												unchanged: true,
+												...(error.text
+													? {
+															text: redactLocalized(error.text, redact),
+														}
+													: {}),
+											}
+										: {}),
 								}),
 							);
 						});

package/src/runtime/bridgeSetupHandlers.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import type { BridgeContext } from "../context";
 import { BridgeKind, BridgeSetupPromptKind, BridgeSetupStepKind, BridgeSetupStepState, BridgeUserError } from "../core";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
-import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
+import { type BridgeConfig, BridgeEventName, type BridgeSetupRuntime } from "../protocol";
 import { createContext } from "./bridgeContext";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { log } from "./bridgeLog";
@@ -51,6 +51,9 @@ const contextOf = (): BridgeContext => {
 		onSetup() {
 			return;
 		},
+		onActivity() {
+			return;
+		},
 		async onRestart() {
 			return;
 		},
@@ -146,7 +149,7 @@ describe("the setup handlers", () => {
 			runtime: null,
 		});
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: false,
 			runtime: null,
 		});
@@ -207,7 +210,7 @@ describe("the setup handlers", () => {
 		const { logger } = recorder();
 		const handlers = createSetupHandlers(driverWith(setupWith()), logger);
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: false,
 			runtime: null,
 		});
@@ -227,7 +230,7 @@ describe("the setup handlers", () => {
 
 		handlers.onSetup(signIn());
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: true,
 			runtime: {
 				steps: [
@@ -251,6 +254,65 @@ describe("the setup handlers", () => {
 		expect(warnings.at(-1)?.message).toBe("setup submit rejected");
 	});
 
+	test("add one rejected entry built from the user error", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					throw new BridgeUserError({
+						ar: "الكود ما عاد ينفع",
+						en: "this code cannot be renewed any more",
+					});
+				}),
+			),
+			logger,
+		);
+
+		handlers.onSetup(signIn());
+
+		const { activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+
+		expect(activity).toEqual([
+			{
+				name: BridgeEventName.SetupRejected,
+				text: {
+					ar: "الكود ما عاد ينفع",
+					en: "this code cannot be renewed any more",
+				},
+				details: {
+					step: "sign-in",
+					action: "renew",
+				},
+			},
+		]);
+	});
+
+	test("answer what the driver reported while submitting", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async (context) => {
+					context.activity.report({
+						name: BridgeEventName.SetupCompleted,
+						text: text("signed in"),
+					});
+				}),
+			),
+			logger,
+		);
+
+		const { activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+
+		expect(activity).toEqual([
+			{
+				name: BridgeEventName.SetupCompleted,
+				text: text("signed in"),
+			},
+		]);
+	});
+
 	test("answer the runtime the driver reported while submitting", async () => {
 		const { logger } = recorder();
 
@@ -273,7 +335,7 @@ describe("the setup handlers", () => {
 
 		handlers.onSetup(signIn());
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: true,
 			runtime: {
 				steps: [
@@ -381,11 +443,12 @@ describe("the setup handlers redaction", () => {
 
 		handlers.onSetup(signIn());
 
-		const result = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+		const { result, activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
 
 		expect(result.runtime?.prompt).toMatchObject({
 			kind: BridgeSetupPromptKind.Failed,
 			message: text("telegram refused ••••"),
 		});
+		expect(JSON.stringify(activity)).not.toContain(SECRET);
 	});
 });

package/src/runtime/bridgeSetupHandlers.ts

@@ -1,15 +1,22 @@
 import type { BridgeContext } from "../context";
 import { BridgeUserError, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
-import type { BridgeSetupResult, BridgeSetupRuntime } from "../protocol";
-import type { BridgeLeveledLogger } from "./bridgeLog";
-import { type BridgeRedact, redactLocalized, redactSetupRuntime } from "./bridgeRedaction";
+import { BridgeEventName, type BridgeSetupResult, type BridgeSetupRuntime } from "../protocol";
+import { type ActivityNormalizeOptions, type BridgeActivityAnswer, createActivityScope } from "./bridgeActivity";
+import { type BridgeLeveledLogger, errorDetail } from "./bridgeLog";
+import { type BridgeRedact, redactLocalized, redactSetupRuntime, secretFieldKeys } from "./bridgeRedaction";
+import { scopedContext } from "./bridgeScopedContext";
 import { failedSetup, normalizeSetupRuntime, unsupportedSetup } from "./bridgeSetup";
 
 export interface BridgeSetupHandlers {
 	onSetup(runtime: BridgeSetupRuntime | null): void;
 	onSetupStatus(): BridgeSetupResult;
-	onSetupSubmit(context: BridgeContext, step: string, action: string, args: BridgeValues): Promise<BridgeSetupResult>;
+	onSetupSubmit(
+		context: BridgeContext,
+		step: string,
+		action: string,
+		args: BridgeValues,
+	): Promise<BridgeActivityAnswer<BridgeSetupResult>>;
 	current(): BridgeSetupRuntime | null;
 }
 
@@ -22,6 +29,12 @@ export const createSetupHandlers = (
 ): BridgeSetupHandlers => {
 	const declared: ReadonlySet<string> = new Set((driver.setup?.steps ?? []).map((step) => step.id));
 
+	const activity: ActivityNormalizeOptions = {
+		secretKeys: new Set(secretFieldKeys(driver)),
+		redact,
+		warn: log.warn,
+	};
+
 	let current: BridgeSetupRuntime | null = null;
 
 	return {
@@ -53,28 +66,50 @@ export const createSetupHandlers = (
 			const module = driver.setup;
 
 			if (!module?.submit) {
-				return unsupportedSetup();
+				return {
+					result: unsupportedSetup(),
+					activity: [],
+				};
 			}
 
+			const scope = createActivityScope(context.activity, activity);
+
 			try {
-				await module.submit(context, step, action, args);
+				await module.submit(scopedContext(context, scope.reporter), step, action, args);
 			} catch (error) {
 				if (!(error instanceof BridgeUserError)) {
+					scope.drain();
+
 					throw error;
 				}
 
 				log.warn("setup submit rejected", {
 					step,
 					action,
-					error: error.message,
+					error: errorDetail(error),
 				});
 
-				return failedSetup(current, redactLocalized(error.text, redact));
+				scope.reporter.report({
+					name: BridgeEventName.SetupRejected,
+					text: error.text,
+					details: {
+						step,
+						action,
+					},
+				});
+
+				return {
+					result: failedSetup(current, redactLocalized(error.text, redact)),
+					activity: scope.close(),
+				};
 			}
 
 			return {
-				supported: true,
-				runtime: current,
+				result: {
+					supported: true,
+					runtime: current,
+				},
+				activity: scope.close(),
 			};
 		},
 	};

package/src/runtime/serve.ts

@@ -5,10 +5,12 @@ 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";
@@ -17,7 +19,7 @@ import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
 import { decideInstall, recountHold } from "./bridgeInstall";
 import { createBridgeLiveConfig } from "./bridgeLiveConfig";
-import { errorText, log as stdoutLog } from "./bridgeLog";
+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";
@@ -37,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,
@@ -130,6 +143,19 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const ring = createEventRing(driver.events, supervisor);
 
+	const activity: ActivityNormalizeOptions = {
+		secretKeys: new Set(secretFieldKeys(driver)),
+		redact,
+		warn: log.warn,
+	};
+
+	const reporter = createActivityReporter({
+		...activity,
+		onEmit(event, payload) {
+			ring.emit(event, payload);
+		},
+	});
+
 	const context = createContext(
 		config,
 		supervisor,
@@ -141,6 +167,9 @@ export const serve = async (driver: BridgeDriver) => {
 			onSetup(runtime) {
 				setup.onSetup(runtime);
 			},
+			onActivity(entry) {
+				reporter.report(entry);
+			},
 			async onRestart() {
 				if (current !== BridgeDesired.Running) {
 					throw new Error(
@@ -154,7 +183,7 @@ export const serve = async (driver: BridgeDriver) => {
 		live,
 	);
 
-	const registry = createRegistry(driver, context, supervisor, ring);
+	const registry = createRegistry(driver, context, supervisor, ring, activity);
 	const backupLease = createBackupLease(async () => {
 		if (supervisor.running) {
 			await driver.backup?.release?.(context);
@@ -409,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);
 		},
@@ -462,7 +496,7 @@ export const serve = async (driver: BridgeDriver) => {
 
 		log("install complete");
 	} catch (error) {
-		installError = redact(errorText(error)).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
+		installError = redact(errorDetail(error)).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
 		installErrorText = error instanceof BridgeUserError ? redactLocalized(error.text, redact) : null;
 
 		supervisor.setRuntime(BridgeRuntime.Crashed);
@@ -471,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.",
+		});
+	});
+});