@serverkgg/bridge 0.0.10 → 0.0.12

package/src/runtime/bridgeSetup.ts

@@ -1,11 +1,16 @@
-import { BridgeSetupPromptKind, BridgeSetupStepState, type LocalizedText } from "../core";
-import type {
-	BridgeSetupAction,
-	BridgeSetupPrompt,
-	BridgeSetupResult,
-	BridgeSetupRuntime,
-	BridgeSetupSummary,
+import { BRIDGE_ID_PATTERN, BridgeSetupPromptKind, BridgeSetupStepState, type LocalizedText } from "../core";
+import {
+	BRIDGE_SETUP_ACTIONS_LIMIT,
+	BRIDGE_SETUP_CODE_LENGTH_LIMIT,
+	BRIDGE_SETUP_DETAIL_LENGTH_LIMIT,
+	type BridgeSetupAction,
+	type BridgeSetupPrompt,
+	type BridgeSetupResult,
+	type BridgeSetupRuntime,
+	type BridgeSetupStepStatus,
+	type BridgeSetupSummary,
 } from "../protocol";
+import type { BridgeLogger } from "./bridgeLog";
 
 const ATTENTION_KINDS: ReadonlySet<BridgeSetupPromptKind> = new Set([
 	BridgeSetupPromptKind.Link,
@@ -61,3 +66,238 @@ export const failedSetup = (runtime: BridgeSetupRuntime | null, text: LocalizedT
 		},
 	};
 };
+
+const BROKEN_LINK_TEXT: LocalizedText = {
+	ar: "اللعبة رجّعت رابط دخول ما يشتغل. جرّب مرة ثانية.",
+	en: "The game reported a broken sign-in link. Try again.",
+};
+
+const LINK_PROTOCOLS: ReadonlySet<string> = new Set([
+	"http:",
+	"https:",
+]);
+
+export interface SetupNormalizeOptions {
+	declared: ReadonlySet<string>;
+	warn: BridgeLogger;
+}
+
+const httpUrl = (url: string) => {
+	try {
+		return LINK_PROTOCOLS.has(new URL(url).protocol);
+	} catch {
+		return false;
+	}
+};
+
+export const normalizeSetupRuntime = (
+	runtime: BridgeSetupRuntime | null,
+	options: SetupNormalizeOptions,
+): BridgeSetupRuntime | null => {
+	if (!runtime) {
+		return null;
+	}
+
+	const reported = new Set<string>();
+
+	const report = (reason: string) => {
+		if (reported.has(reason)) {
+			return;
+		}
+
+		reported.add(reason);
+
+		options.warn("setup runtime normalized", {
+			reason,
+		});
+	};
+
+	const steps: BridgeSetupStepStatus[] = [];
+	const seen = new Set<string>();
+
+	let active = false;
+
+	for (const step of runtime.steps) {
+		if (!options.declared.has(step.id)) {
+			report("unknown-step");
+
+			continue;
+		}
+
+		if (seen.has(step.id)) {
+			report("duplicate-step");
+
+			continue;
+		}
+
+		seen.add(step.id);
+
+		if (step.state !== BridgeSetupStepState.Active) {
+			steps.push(step);
+
+			continue;
+		}
+
+		if (active) {
+			report("extra-active-step");
+
+			steps.push({
+				id: step.id,
+				state: BridgeSetupStepState.Pending,
+			});
+
+			continue;
+		}
+
+		active = true;
+
+		steps.push(step);
+	}
+
+	return {
+		steps,
+		prompt: normalizePrompt(runtime.prompt, report),
+	};
+};
+
+const normalizeActions = (actions: BridgeSetupAction[], report: (reason: string) => void): BridgeSetupAction[] => {
+	const kept: BridgeSetupAction[] = [];
+	const seen = new Set<string>();
+
+	for (const action of actions) {
+		if (!BRIDGE_ID_PATTERN.test(action.id)) {
+			report("unknown-action-id");
+
+			continue;
+		}
+
+		if (seen.has(action.id)) {
+			report("duplicate-action");
+
+			continue;
+		}
+
+		seen.add(action.id);
+		kept.push(action);
+	}
+
+	if (kept.length <= BRIDGE_SETUP_ACTIONS_LIMIT) {
+		return kept;
+	}
+
+	report("extra-actions");
+
+	return kept.slice(0, BRIDGE_SETUP_ACTIONS_LIMIT);
+};
+
+const normalizePercent = (percent: number | null, report: (reason: string) => void): number | null => {
+	if (percent === null) {
+		return null;
+	}
+
+	if (!Number.isFinite(percent)) {
+		report("unusable-percent");
+
+		return null;
+	}
+
+	if (percent < 0 || percent > 100) {
+		report("percent-out-of-range");
+
+		return Math.min(Math.max(percent, 0), 100);
+	}
+
+	return percent;
+};
+
+const normalizeLine = (
+	value: string | null,
+	limit: number,
+	reason: string,
+	report: (reason: string) => void,
+): string | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const sliced = value.slice(0, limit);
+
+	if (sliced.length === 0) {
+		report(`empty-${reason}`);
+
+		return null;
+	}
+
+	if (sliced.length !== value.length) {
+		report(`long-${reason}`);
+	}
+
+	return sliced;
+};
+
+const normalizeExpiry = (expiresAt: string | null, report: (reason: string) => void): string | null => {
+	if (expiresAt === null) {
+		return null;
+	}
+
+	const stamp = Date.parse(expiresAt);
+
+	if (!Number.isFinite(stamp)) {
+		report("unusable-expiry");
+
+		return null;
+	}
+
+	return new Date(stamp).toISOString();
+};
+
+const normalizePrompt = (
+	prompt: BridgeSetupPrompt | null,
+	report: (reason: string) => void,
+): BridgeSetupPrompt | null => {
+	if (!prompt) {
+		return null;
+	}
+
+	if (prompt.kind === BridgeSetupPromptKind.Wait) {
+		return prompt;
+	}
+
+	if (prompt.kind === BridgeSetupPromptKind.Progress) {
+		return {
+			kind: BridgeSetupPromptKind.Progress,
+			message: prompt.message,
+			percent: normalizePercent(prompt.percent, report),
+			detail: normalizeLine(prompt.detail, BRIDGE_SETUP_DETAIL_LENGTH_LIMIT, "detail", report),
+		};
+	}
+
+	const actions = normalizeActions(prompt.actions, report);
+
+	if (prompt.kind !== BridgeSetupPromptKind.Link) {
+		return {
+			kind: prompt.kind,
+			message: prompt.message,
+			actions,
+		};
+	}
+
+	if (!httpUrl(prompt.url)) {
+		report("unusable-link");
+
+		return {
+			kind: BridgeSetupPromptKind.Failed,
+			message: BROKEN_LINK_TEXT,
+			actions,
+		};
+	}
+
+	return {
+		kind: BridgeSetupPromptKind.Link,
+		message: prompt.message,
+		url: prompt.url,
+		code: normalizeLine(prompt.code, BRIDGE_SETUP_CODE_LENGTH_LIMIT, "code", report),
+		expiresAt: normalizeExpiry(prompt.expiresAt, report),
+		actions,
+	};
+};

package/src/runtime/bridgeSetupHandlers.test.ts

@@ -0,0 +1,303 @@
+import { describe, expect, test } from "bun:test";
+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 { createContext } from "./bridgeContext";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { log } from "./bridgeLog";
+import { createSetupHandlers } from "./bridgeSetupHandlers";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
+
+const config = (): BridgeConfig => ({
+	code: "abcdef",
+	token: "token",
+	cwd: `${tmpdir()}/serverk-setup-handlers-test`,
+	run: `${tmpdir()}/serverk-setup-handlers-test/run`,
+	ports: {},
+	memoryMb: 1024,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {},
+	secrets: {},
+});
+
+const contextOf = (): BridgeContext => {
+	const settings = config();
+
+	const supervisor = createSupervisor({
+		cwd: settings.cwd,
+		uid: settings.gameUid,
+		gid: settings.gameGid,
+		stopTimeoutSeconds: 1,
+		onLog: log,
+		resolveCommand: async () => [
+			"run",
+		],
+	});
+
+	return createContext(settings, supervisor, {
+		onLog: log,
+		onEmit() {
+			return;
+		},
+		onSetup() {
+			return;
+		},
+	});
+};
+
+const recorder = () => {
+	const warnings: {
+		message: string;
+		fields?: Record<string, unknown>;
+	}[] = [];
+
+	const logger: BridgeLeveledLogger = Object.assign(
+		() => {
+			return;
+		},
+		{
+			warn: (message: string, fields?: Record<string, unknown>) => {
+				warnings.push({
+					message,
+					fields,
+				});
+			},
+			error: () => {
+				return;
+			},
+		},
+	);
+
+	return {
+		logger,
+		warnings,
+	};
+};
+
+const driverWith = (setup?: BridgeSetupModule): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	setup,
+});
+
+const signIn = (): BridgeSetupRuntime => ({
+	steps: [
+		{
+			id: "sign-in",
+			state: BridgeSetupStepState.Active,
+		},
+	],
+	prompt: {
+		kind: BridgeSetupPromptKind.Link,
+		message: text("sign in with your account"),
+		url: "https://hytale.com/device",
+		code: "ABCD-EFGH",
+		expiresAt: null,
+		actions: [
+			{
+				id: "renew",
+				label: text("Get a new code"),
+			},
+		],
+	},
+});
+
+const setupWith = (submit?: BridgeSetupModule["submit"]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps: [
+		{
+			kind: BridgeSetupStepKind.Driver,
+			id: "sign-in",
+			title: text("Sign in"),
+		},
+	],
+	submit,
+});
+
+describe("the setup handlers", () => {
+	test("answer unsupported for a driver that declares no setup", async () => {
+		const { logger } = recorder();
+		const handlers = createSetupHandlers(driverWith(), logger);
+
+		expect(handlers.onSetupStatus()).toEqual({
+			supported: false,
+			runtime: null,
+		});
+
+		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+			supported: false,
+			runtime: null,
+		});
+	});
+
+	test("keep nothing for a driver that declares no setup, whatever it reports", () => {
+		const { logger, warnings } = recorder();
+		const handlers = createSetupHandlers(driverWith(), logger);
+
+		handlers.onSetup(signIn());
+
+		expect(handlers.current()).toBeNull();
+		expect(warnings).toEqual([]);
+	});
+
+	test("answer the normalized runtime the driver reported", () => {
+		const { logger, warnings } = recorder();
+		const handlers = createSetupHandlers(driverWith(setupWith()), logger);
+
+		handlers.onSetup({
+			steps: [
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Active,
+				},
+				{
+					id: "invent",
+					state: BridgeSetupStepState.Pending,
+				},
+			],
+			prompt: null,
+		});
+
+		expect(handlers.onSetupStatus()).toEqual({
+			supported: true,
+			runtime: {
+				steps: [
+					{
+						id: "sign-in",
+						state: BridgeSetupStepState.Active,
+					},
+				],
+				prompt: null,
+			},
+		});
+		expect(handlers.current()).toEqual(handlers.onSetupStatus().runtime);
+		expect(warnings).toEqual([
+			{
+				message: "setup runtime normalized",
+				fields: {
+					reason: "unknown-step",
+				},
+			},
+		]);
+	});
+
+	test("answer unsupported for a setup that exports no submit", async () => {
+		const { logger } = recorder();
+		const handlers = createSetupHandlers(driverWith(setupWith()), logger);
+
+		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+			supported: false,
+			runtime: null,
+		});
+	});
+
+	test("turn a user error into a failed prompt that keeps the previous actions", async () => {
+		const { logger, warnings } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					throw new BridgeUserError(text("this code cannot be renewed any more"));
+				}),
+			),
+			logger,
+		);
+
+		handlers.onSetup(signIn());
+
+		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+			supported: true,
+			runtime: {
+				steps: [
+					{
+						id: "sign-in",
+						state: BridgeSetupStepState.Active,
+					},
+				],
+				prompt: {
+					kind: BridgeSetupPromptKind.Failed,
+					message: text("this code cannot be renewed any more"),
+					actions: [
+						{
+							id: "renew",
+							label: text("Get a new code"),
+						},
+					],
+				},
+			},
+		});
+		expect(warnings.at(-1)?.message).toBe("setup submit rejected");
+	});
+
+	test("answer the runtime the driver reported while submitting", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					handlers.onSetup({
+						steps: [
+							{
+								id: "sign-in",
+								state: BridgeSetupStepState.Done,
+							},
+						],
+						prompt: null,
+					});
+				}),
+			),
+			logger,
+		);
+
+		handlers.onSetup(signIn());
+
+		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+			supported: true,
+			runtime: {
+				steps: [
+					{
+						id: "sign-in",
+						state: BridgeSetupStepState.Done,
+					},
+				],
+				prompt: null,
+			},
+		});
+	});
+
+	test("let an error the driver cannot explain out", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					throw new Error("the device endpoint answered 503");
+				}),
+			),
+			logger,
+		);
+
+		await expect(handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).rejects.toThrow(
+			"the device endpoint answered 503",
+		);
+	});
+});

package/src/runtime/bridgeSetupHandlers.ts

@@ -0,0 +1,71 @@
+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 { 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>;
+	current(): BridgeSetupRuntime | null;
+}
+
+export const createSetupHandlers = (driver: BridgeDriver, log: BridgeLeveledLogger): BridgeSetupHandlers => {
+	const declared: ReadonlySet<string> = new Set((driver.setup?.steps ?? []).map((step) => step.id));
+
+	let current: BridgeSetupRuntime | null = null;
+
+	return {
+		onSetup(runtime) {
+			current = driver.setup
+				? normalizeSetupRuntime(runtime, {
+						declared,
+						warn: log.warn,
+					})
+				: null;
+		},
+		current() {
+			return current;
+		},
+		onSetupStatus() {
+			if (!driver.setup) {
+				return unsupportedSetup();
+			}
+
+			return {
+				supported: true,
+				runtime: current,
+			};
+		},
+		async onSetupSubmit(context, step, action, args) {
+			const module = driver.setup;
+
+			if (!module?.submit) {
+				return unsupportedSetup();
+			}
+
+			try {
+				await module.submit(context, step, action, args);
+			} catch (error) {
+				if (!(error instanceof BridgeUserError)) {
+					throw error;
+				}
+
+				log.warn("setup submit rejected", {
+					step,
+					action,
+					error: error.message,
+				});
+
+				return failedSetup(current, error.text);
+			}
+
+			return {
+				supported: true,
+				runtime: current,
+			};
+		},
+	};
+};

package/src/runtime/serve.ts

@@ -7,8 +7,6 @@ import {
 	type BridgeConfig,
 	type BridgePendingResult,
 	type BridgeSampleResult,
-	type BridgeSetupResult,
-	type BridgeSetupRuntime,
 	type BridgeStatus,
 } from "../protocol";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
@@ -20,7 +18,8 @@ import { errorText, log } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
-import { failedSetup, setupSummaryOf, unsupportedSetup } from "./bridgeSetup";
+import { setupSummaryOf } from "./bridgeSetup";
+import { createSetupHandlers } from "./bridgeSetupHandlers";
 import { readDesired, writeDesired } from "./bridgeState";
 import { createSupervisor } from "./bridgeSupervisor";
 
@@ -74,7 +73,7 @@ export const serve = async (driver: BridgeDriver) => {
 
 	let installHold: BridgeInstallHold | null = null;
 
-	let setupRuntime: BridgeSetupRuntime | null = null;
+	const setup = createSetupHandlers(driver, log);
 
 	const supervisor = createSupervisor({
 		cwd: config.cwd,
@@ -106,7 +105,7 @@ export const serve = async (driver: BridgeDriver) => {
 			ring.emit(event, payload);
 		},
 		onSetup(runtime) {
-			setupRuntime = runtime;
+			setup.onSetup(runtime);
 		},
 	});
 
@@ -125,7 +124,7 @@ export const serve = async (driver: BridgeDriver) => {
 			installError,
 			installErrorText,
 			installHold,
-			setup: setupSummaryOf(setupRuntime),
+			setup: setupSummaryOf(setup.current()),
 		};
 	};
 
@@ -320,42 +319,10 @@ export const serve = async (driver: BridgeDriver) => {
 			return await pending();
 		},
 		onSetupStatus() {
-			if (!driver.setup) {
-				return unsupportedSetup();
-			}
-
-			return {
-				supported: true,
-				runtime: setupRuntime,
-			};
+			return setup.onSetupStatus();
 		},
-		async onSetupSubmit(step, action, args): Promise<BridgeSetupResult> {
-			const module = driver.setup;
-
-			if (!module?.submit) {
-				return unsupportedSetup();
-			}
-
-			try {
-				await module.submit(context, step, action, args);
-			} catch (error) {
-				if (!(error instanceof BridgeUserError)) {
-					throw error;
-				}
-
-				log.warn("setup submit rejected", {
-					step,
-					action,
-					error: error.message,
-				});
-
-				return failedSetup(setupRuntime, error.text);
-			}
-
-			return {
-				supported: true,
-				runtime: setupRuntime,
-			};
+		async onSetupSubmit(step, action, args) {
+			return await setup.onSetupSubmit(context, step, action, args);
 		},
 	});