@serverkgg/bridge 0.0.8 → 0.0.10

package/src/runtime/bridgeServer.test.ts

@@ -0,0 +1,598 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	BridgeDesired,
+	BridgeFailureCode,
+	BridgeFailureError,
+	BridgeRuntime,
+	BridgeSetupPromptKind,
+	BridgeSetupStepState,
+	BridgeUserError,
+} from "../core";
+import {
+	BridgeMethod,
+	type BridgePendingResult,
+	type BridgeResponse,
+	type BridgeSetupResult,
+	type BridgeSetupRuntime,
+	type BridgeValues,
+} from "../protocol";
+import { createServer, type ServerOptions } from "./bridgeServer";
+import { failedSetup, unsupportedSetup } from "./bridgeSetup";
+
+const TOKEN = "test-token";
+
+const unreachable = (what: string) => {
+	return () => {
+		throw new Error(`${what} is not part of this test`);
+	};
+};
+
+const baseOptions = (socket: string): ServerOptions => ({
+	socket,
+	token: TOKEN,
+	onStatus: () => ({
+		version: "0.0.0",
+		runtime: BridgeRuntime.Stopped,
+		desired: BridgeDesired.Stopped,
+		exitCode: null,
+		outOfMemory: false,
+		restarts: 0,
+		installError: null,
+		installErrorText: null,
+		installHold: null,
+		setup: null,
+	}),
+	onManifest: unreachable("manifest"),
+	onStart: unreachable("start"),
+	onStop: unreachable("stop"),
+	onCommand: unreachable("command"),
+	onInvoke: unreachable("invoke"),
+	onEvents: unreachable("events"),
+	onSample: unreachable("sample"),
+	onQuiesce: unreachable("quiesce"),
+	onRelease: unreachable("release"),
+	onDescribe: unreachable("describe"),
+	onAnnounce: unreachable("announce"),
+	onPendingList: unreachable("pendingList"),
+	onPendingAdd: unreachable("pendingAdd"),
+	onSetupStatus: unreachable("setupStatus"),
+	onSetupSubmit: unreachable("setupSubmit"),
+	onLog: () => {
+		return;
+	},
+});
+
+const call = async (socket: string, frame: Record<string, unknown>): Promise<BridgeResponse> => {
+	return await new Promise<BridgeResponse>((resolve, reject) => {
+		void Bun.connect<{
+			buffer: string;
+		}>({
+			unix: socket,
+			socket: {
+				open(connection) {
+					connection.data = {
+						buffer: "",
+					};
+
+					connection.write(`${JSON.stringify(frame)}\n`);
+				},
+
+				data(connection, chunk) {
+					connection.data.buffer += chunk.toString();
+
+					const [line] = connection.data.buffer.split("\n");
+
+					if (!line) {
+						return;
+					}
+
+					connection.end();
+
+					resolve(JSON.parse(line) as BridgeResponse);
+				},
+
+				error(_connection, error) {
+					reject(error);
+				},
+			},
+		}).catch(reject);
+	});
+};
+
+describe("pending dispatch", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const listed: BridgePendingResult = {
+		supported: true,
+		staging: ".serverk-staging/pending-upload",
+		extensions: [
+			"jar",
+		],
+		files: [],
+		rejected: null,
+	};
+
+	test("answers pendingList with what the driver lists", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingList: async () => listed,
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.PendingList,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 1,
+			ok: true,
+			result: listed,
+		});
+	});
+
+	test("answers pendingList with the unsupported sentinel when the driver declares no pending module", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingList: async () => ({
+				supported: false,
+				staging: "",
+				extensions: [],
+				files: [],
+				rejected: null,
+			}),
+		});
+
+		const response = await call(socket, {
+			id: 2,
+			token: TOKEN,
+			method: BridgeMethod.PendingList,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 2,
+			ok: true,
+			result: {
+				supported: false,
+				staging: "",
+				extensions: [],
+				files: [],
+				rejected: null,
+			},
+		});
+	});
+
+	test("passes the uploaded path to pendingAdd and answers with the refreshed list", async () => {
+		const received: string[] = [];
+
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async (input) => {
+				received.push(input);
+
+				return listed;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 3,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/patch.jar",
+		});
+
+		server.stop(true);
+
+		expect(received).toEqual([
+			".serverk-staging/pending-upload/patch.jar",
+		]);
+		expect(response).toEqual({
+			id: 3,
+			ok: true,
+			result: listed,
+		});
+	});
+
+	test("refuses a pendingAdd carrying no path", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: unreachable("pendingAdd"),
+		});
+
+		const response = await call(socket, {
+			id: 4,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 4,
+			ok: false,
+			error: "pendingAdd needs an input path",
+		});
+	});
+
+	test("answers pendingAdd with the rejection the driver reported beside the refreshed list", async () => {
+		const rejected: BridgePendingResult = {
+			...listed,
+			rejected: {
+				expected: [
+					"patch.jar",
+				],
+			},
+		};
+
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async () => rejected,
+		});
+
+		const response = await call(socket, {
+			id: 6,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/wrong.jar",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 6,
+			ok: true,
+			result: rejected,
+		});
+	});
+
+	test("names an unknown method so an older agent can degrade", async () => {
+		const server = createServer(baseOptions(socket));
+
+		const response = await call(socket, {
+			id: 5,
+			token: TOKEN,
+			method: "pendingRemove",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 5,
+			ok: false,
+			error: 'unknown method "pendingRemove"',
+		});
+	});
+});
+
+describe("setup dispatch", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const runtime: BridgeSetupRuntime = {
+		steps: [
+			{
+				id: "sign-in",
+				state: BridgeSetupStepState.Active,
+			},
+		],
+		prompt: {
+			kind: BridgeSetupPromptKind.Link,
+			message: {
+				ar: "سجل دخولك",
+				en: "sign in with your account",
+			},
+			url: "https://hytale.com/device",
+			code: "ABCD-EFGH",
+			expiresAt: null,
+			actions: [
+				{
+					id: "renew",
+					label: {
+						ar: "كود جديد",
+						en: "Get a new code",
+					},
+				},
+			],
+		},
+	};
+
+	const reported: BridgeSetupResult = {
+		supported: true,
+		runtime,
+	};
+
+	test("answers setupStatus with what the driver reported", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupStatus: () => reported,
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.SetupStatus,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 1,
+			ok: true,
+			result: reported,
+		});
+	});
+
+	test("answers setupStatus with the unsupported sentinel when the driver declares no setup", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupStatus: () => unsupportedSetup(),
+		});
+
+		const response = await call(socket, {
+			id: 2,
+			token: TOKEN,
+			method: BridgeMethod.SetupStatus,
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 2,
+			ok: true,
+			result: {
+				supported: false,
+				runtime: null,
+			},
+		});
+	});
+
+	test("passes the step, action and args of a setupSubmit to the driver", async () => {
+		const received: {
+			step: string;
+			action: string;
+			args: BridgeValues;
+		}[] = [];
+
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async (step, action, args) => {
+				received.push({
+					step,
+					action,
+					args,
+				});
+
+				return reported;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 3,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+			args: {
+				force: true,
+			},
+		});
+
+		server.stop(true);
+
+		expect(received).toEqual([
+			{
+				step: "sign-in",
+				action: "renew",
+				args: {
+					force: true,
+				},
+			},
+		]);
+		expect(response).toEqual({
+			id: 3,
+			ok: true,
+			result: reported,
+		});
+	});
+
+	test("refuses a setupSubmit carrying no step id", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: unreachable("setupSubmit"),
+		});
+
+		const response = await call(socket, {
+			id: 4,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 4,
+			ok: false,
+			error: "setupSubmit needs a step id",
+		});
+	});
+
+	test("answers a rejected setupSubmit with a failed prompt instead of a failed call", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async () =>
+				failedSetup(runtime, {
+					ar: "الكود ما عاد ينفع",
+					en: "this code cannot be renewed any more",
+				}),
+		});
+
+		const response = await call(socket, {
+			id: 5,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 5,
+			ok: true,
+			result: {
+				supported: true,
+				runtime: {
+					steps: runtime.steps,
+					prompt: {
+						kind: BridgeSetupPromptKind.Failed,
+						message: {
+							ar: "الكود ما عاد ينفع",
+							en: "this code cannot be renewed any more",
+						},
+						actions: [
+							{
+								id: "renew",
+								label: {
+									ar: "كود جديد",
+									en: "Get a new code",
+								},
+							},
+						],
+					},
+				},
+			},
+		});
+	});
+
+	test("answers setupSubmit with the unsupported sentinel when the driver implements no submit", async () => {
+		const server = createServer({
+			...baseOptions(socket),
+			onSetupSubmit: async () => unsupportedSetup(),
+		});
+
+		const response = await call(socket, {
+			id: 6,
+			token: TOKEN,
+			method: BridgeMethod.SetupSubmit,
+			module: "sign-in",
+			action: "renew",
+		});
+
+		server.stop(true);
+
+		expect(response).toEqual({
+			id: 6,
+			ok: true,
+			result: {
+				supported: false,
+				runtime: null,
+			},
+		});
+	});
+});
+
+describe("error serialisation", () => {
+	let dir = "";
+	let socket = "";
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "bridge-server-"));
+		socket = join(dir, "bridge.sock");
+	});
+
+	afterEach(async () => {
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	const thrown = async (error: unknown) => {
+		const server = createServer({
+			...baseOptions(socket),
+			onPendingAdd: async () => {
+				throw error;
+			},
+		});
+
+		const response = await call(socket, {
+			id: 1,
+			token: TOKEN,
+			method: BridgeMethod.PendingAdd,
+			input: ".serverk-staging/pending-upload/patch.jar",
+		});
+
+		server.stop(true);
+
+		return response;
+	};
+
+	test("carries the localized text of a user error beside the message", async () => {
+		expect(
+			await thrown(
+				new BridgeUserError({
+					ar: "هذا مو الملف اللي ننتظره",
+					en: "this is not a file we are waiting for",
+				}),
+			),
+		).toEqual({
+			id: 1,
+			ok: false,
+			error: "this is not a file we are waiting for",
+			text: {
+				ar: "هذا مو الملف اللي ننتظره",
+				en: "this is not a file we are waiting for",
+			},
+		});
+	});
+
+	test("carries the failure code of a failure error and no text", async () => {
+		expect(await thrown(new BridgeFailureError(BridgeFailureCode.CatalogRestricted, "the author blocked it"))).toEqual({
+			id: 1,
+			ok: false,
+			error: "the author blocked it",
+			failure: BridgeFailureCode.CatalogRestricted,
+		});
+	});
+
+	test("carries the message alone for an ordinary error", async () => {
+		expect(await thrown(new Error("the file could not be read"))).toEqual({
+			id: 1,
+			ok: false,
+			error: "the file could not be read",
+		});
+	});
+});

package/src/runtime/bridgeServer.ts

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeFailureError, BridgeSecretError, type BridgeValues } from "../core";
+import { BridgeFailureError, BridgeSecretError, BridgeUserError, type BridgeValues } from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
 	type BridgeAnnounceResult,
@@ -8,9 +8,11 @@ import {
 	type BridgeEventsResult,
 	type BridgeManifest,
 	BridgeMethod,
+	type BridgePendingResult,
 	type BridgeQuiesceResult,
 	type BridgeResponse,
 	type BridgeSampleResult,
+	type BridgeSetupResult,
 	type BridgeStatus,
 } from "../protocol";
 import { type BridgeLogger, errorText } from "./bridgeLog";
@@ -30,6 +32,10 @@ export interface ServerOptions {
 	onRelease: () => Promise<void>;
 	onDescribe: () => Promise<BridgeDescribeResult>;
 	onAnnounce: (message: string) => Promise<BridgeAnnounceResult>;
+	onPendingList: () => Promise<BridgePendingResult>;
+	onPendingAdd: (input: string) => Promise<BridgePendingResult>;
+	onSetupStatus: () => BridgeSetupResult;
+	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeSetupResult>;
 	onLog: BridgeLogger;
 }
 
@@ -47,7 +53,7 @@ interface IncomingFrame {
 	message?: unknown;
 }
 
-const asMessage = (value: unknown): string | null => {
+const asText = (value: unknown): string | null => {
 	return typeof value === "string" && value.length > 0 ? value : null;
 };
 
@@ -136,7 +142,7 @@ export const createServer = (options: ServerOptions) => {
 			}
 
 			case BridgeMethod.Announce: {
-				const message = asMessage(request.message);
+				const message = asText(request.message);
 
 				if (!message) {
 					throw new Error("announce needs a message");
@@ -145,6 +151,34 @@ export const createServer = (options: ServerOptions) => {
 				return await options.onAnnounce(message);
 			}
 
+			case BridgeMethod.PendingList: {
+				return await options.onPendingList();
+			}
+
+			case BridgeMethod.PendingAdd: {
+				const input = asText(request.input);
+
+				if (!input) {
+					throw new Error("pendingAdd needs an input path");
+				}
+
+				return await options.onPendingAdd(input);
+			}
+
+			case BridgeMethod.SetupStatus: {
+				return options.onSetupStatus();
+			}
+
+			case BridgeMethod.SetupSubmit: {
+				const step = asText(request.module);
+
+				if (!step) {
+					throw new Error("setupSubmit needs a step id");
+				}
+
+				return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
+			}
+
 			default: {
 				throw new Error(`unknown method "${method}"`);
 			}
@@ -249,6 +283,11 @@ export const createServer = (options: ServerOptions) => {
 												failure: error.code,
 											}
 										: {}),
+									...(error instanceof BridgeUserError
+										? {
+												text: error.text,
+											}
+										: {}),
 								}),
 							);
 						});