@serverkgg/bridge 0.1.1 → 0.1.3

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/bridgeSetup.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { BridgeSetupPromptKind, BridgeSetupStepState } from "../core";
 import type { BridgeSetupRuntime } from "../protocol";
 import { failedSetup, normalizeSetupRuntime, setupSummaryOf, unsupportedSetup } from "./bridgeSetup";
@@ -23,11 +23,11 @@ const runtimeWith = (prompt: BridgeSetupRuntime["prompt"]): BridgeSetupRuntime =
 });
 
 describe("the setup summary", () => {
-	test("has nothing to summarise while the driver reported no runtime", () => {
+	it("has nothing to summarise while the driver reported no runtime", () => {
 		expect(setupSummaryOf(null)).toBeNull();
 	});
 
-	test("names the active driver step", () => {
+	it("names the active driver step", () => {
 		expect(
 			setupSummaryOf(
 				runtimeWith({
@@ -41,7 +41,7 @@ describe("the setup summary", () => {
 		});
 	});
 
-	test("names no step once every driver step is done", () => {
+	it("names no step once every driver step is done", () => {
 		expect(
 			setupSummaryOf({
 				steps: [
@@ -58,7 +58,7 @@ describe("the setup summary", () => {
 		});
 	});
 
-	test("asks for attention while a link prompt waits on the customer", () => {
+	it("asks for attention while a link prompt waits on the customer", () => {
 		expect(
 			setupSummaryOf(
 				runtimeWith({
@@ -73,7 +73,7 @@ describe("the setup summary", () => {
 		).toBe(true);
 	});
 
-	test("asks for attention on an action prompt and on a failed one", () => {
+	it("asks for attention on an action prompt and on a failed one", () => {
 		expect(
 			setupSummaryOf(
 				runtimeWith({
@@ -95,7 +95,7 @@ describe("the setup summary", () => {
 		).toBe(true);
 	});
 
-	test("waits quietly while a progress prompt runs", () => {
+	it("waits quietly while a progress prompt runs", () => {
 		expect(
 			setupSummaryOf(
 				runtimeWith({
@@ -110,7 +110,7 @@ describe("the setup summary", () => {
 });
 
 describe("the unsupported sentinel", () => {
-	test("answers a driver that declares no setup", () => {
+	it("answers a driver that declares no setup", () => {
 		expect(unsupportedSetup()).toEqual({
 			supported: false,
 			runtime: null,
@@ -119,7 +119,7 @@ describe("the unsupported sentinel", () => {
 });
 
 describe("a rejected submit", () => {
-	test("turns the user error into a failed prompt keeping the previous actions", () => {
+	it("turns the user error into a failed prompt keeping the previous actions", () => {
 		const result = failedSetup(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Link,
@@ -164,7 +164,7 @@ describe("a rejected submit", () => {
 		});
 	});
 
-	test("carries no actions over from a prompt that had none", () => {
+	it("carries no actions over from a prompt that had none", () => {
 		const result = failedSetup(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Wait,
@@ -180,7 +180,7 @@ describe("a rejected submit", () => {
 		});
 	});
 
-	test("stays empty when the driver never reported a runtime", () => {
+	it("stays empty when the driver never reported a runtime", () => {
 		expect(failedSetup(null, text("nothing to fail"))).toEqual({
 			supported: true,
 			runtime: null,
@@ -236,7 +236,7 @@ const link = (
 };
 
 describe("normalizing a reported runtime", () => {
-	test("has nothing to normalize while the driver reported no runtime", () => {
+	it("has nothing to normalize while the driver reported no runtime", () => {
 		expect(
 			normalizeSetupRuntime(null, {
 				declared,
@@ -247,7 +247,7 @@ describe("normalizing a reported runtime", () => {
 		).toBeNull();
 	});
 
-	test("drops a step the driver never declared", () => {
+	it("drops a step the driver never declared", () => {
 		const { normalized, reasons } = normalizing(
 			withSteps([
 				{
@@ -272,7 +272,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("drops the second report of the same step", () => {
+	it("drops the second report of the same step", () => {
 		const { normalized, reasons } = normalizing(
 			withSteps([
 				{
@@ -297,7 +297,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("keeps the first active step and pends the rest", () => {
+	it("keeps the first active step and pends the rest", () => {
 		const { normalized, reasons } = normalizing(
 			withSteps([
 				{
@@ -326,7 +326,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("clamps a percent that left the scale", () => {
+	it("clamps a percent that left the scale", () => {
 		expect(
 			normalizing(
 				runtimeWith({
@@ -361,7 +361,7 @@ describe("normalizing a reported runtime", () => {
 		});
 	});
 
-	test("drops a percent that is not a number", () => {
+	it("drops a percent that is not a number", () => {
 		const { normalized, reasons } = normalizing(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Progress,
@@ -382,7 +382,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("cuts a detail line to the length the platform takes", () => {
+	it("cuts a detail line to the length the platform takes", () => {
 		const { normalized, reasons } = normalizing(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Progress,
@@ -403,7 +403,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("drops an empty detail line", () => {
+	it("drops an empty detail line", () => {
 		const { normalized, reasons } = normalizing(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Progress,
@@ -421,7 +421,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("drops an action whose id is not kebab-case and the duplicate beside it", () => {
+	it("drops an action whose id is not kebab-case and the duplicate beside it", () => {
 		const { normalized, reasons } = normalizing(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Action,
@@ -459,7 +459,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("keeps only as many actions as the platform renders", () => {
+	it("keeps only as many actions as the platform renders", () => {
 		const { normalized, reasons } = normalizing(
 			runtimeWith({
 				kind: BridgeSetupPromptKind.Failed,
@@ -480,7 +480,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("cuts a long code and drops an empty one", () => {
+	it("cuts a long code and drops an empty one", () => {
 		expect(
 			normalizing(
 				link({
@@ -502,7 +502,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("re-emits an expiry as an iso stamp and drops one it cannot read", () => {
+	it("re-emits an expiry as an iso stamp and drops one it cannot read", () => {
 		expect(
 			normalizing(
 				link({
@@ -524,7 +524,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("turns a link the browser cannot open into a failed prompt keeping its actions", () => {
+	it("turns a link the browser cannot open into a failed prompt keeping its actions", () => {
 		const { normalized, reasons } = normalizing(
 			link({
 				url: "javascript:alert(1)",
@@ -540,7 +540,7 @@ describe("normalizing a reported runtime", () => {
 		expect(normalized?.prompt).toEqual({
 			kind: BridgeSetupPromptKind.Failed,
 			message: {
-				ar: "اللعبة رجّعت رابط دخول ما يشتغل. جرّب مرة ثانية.",
+				ar: "أعادت اللعبة رابط تسجيل دخول غير صالح، جرب مرة ثانية.",
 				en: "The game reported a broken sign-in link. Try again.",
 			},
 			actions: [
@@ -555,7 +555,7 @@ describe("normalizing a reported runtime", () => {
 		]);
 	});
 
-	test("turns a url it cannot parse into a failed prompt", () => {
+	it("turns a url it cannot parse into a failed prompt", () => {
 		expect(
 			normalizing(
 				link({
@@ -565,7 +565,7 @@ describe("normalizing a reported runtime", () => {
 		).toBe(BridgeSetupPromptKind.Failed);
 	});
 
-	test("leaves a healthy runtime exactly as the driver reported it", () => {
+	it("leaves a healthy runtime exactly as the driver reported it", () => {
 		const source = link({});
 		const { normalized, reasons } = normalizing(source);
 

package/src/runtime/bridgeSetup.ts

@@ -68,7 +68,7 @@ export const failedSetup = (runtime: BridgeSetupRuntime | null, text: LocalizedT
 };
 
 const BROKEN_LINK_TEXT: LocalizedText = {
-	ar: "اللعبة رجّعت رابط دخول ما يشتغل. جرّب مرة ثانية.",
+	ar: "أعادت اللعبة رابط تسجيل دخول غير صالح، جرب مرة ثانية.",
 	en: "The game reported a broken sign-in link. Try again.",
 };