@serverkgg/bridge 0.0.10 → 0.0.11

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);
 		},
 	});
 

package/src/wire/panel.test.ts

@@ -5,6 +5,7 @@ import {
 	BridgeAction,
 	BridgeConfirm,
 	BridgeControl,
+	type BridgeField,
 	BridgeFormTarget,
 	BridgeKind,
 	BridgeLayout,
@@ -457,6 +458,67 @@ describe("the upload mirror", () => {
 	});
 });
 
+const fieldManifest = (field: BridgeField): BridgeManifest => ({
+	version: "1.0.0",
+	panel: {
+		tabs: [
+			{
+				id: "license",
+				title: text("Licence"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "license",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field,
+						],
+					},
+				],
+			},
+		],
+	},
+	terminal: null,
+	setup: null,
+	modules: [],
+	events: [],
+});
+
+describe("secret fields", () => {
+	test("carries a secret control with its pattern and hint through unchanged", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: BridgeControl.Secret,
+			label: text("Licence key"),
+			pattern: "^cfxk_\\w{1,60}_\\w{1,20}$",
+			patternHint: text("A licence key starts with cfxk_"),
+		});
+
+		expect(bridgeManifestSchema.parse(source)).toEqual(source);
+	});
+
+	test("refuses a control the platform does not know", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: "password" as BridgeControl,
+			label: text("Licence key"),
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+
+	test("refuses a pattern longer than the platform takes", () => {
+		const source = fieldManifest({
+			key: "LICENSE_KEY",
+			control: BridgeControl.Secret,
+			label: text("Licence key"),
+			pattern: `^${"a".repeat(256)}$`,
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+});
+
 const setupManifest = (setup: BridgeSetupManifest | null): BridgeManifest => ({
 	version: "1.0.0",
 	panel: null,

package/src/wire/panel.ts

@@ -2,6 +2,7 @@ import { guideOpenTargetSchema } from "@serverkgg/bridge/guides";
 import {
 	BRIDGE_ID_PATTERN,
 	BRIDGE_MODULE_ID_PATTERN,
+	BRIDGE_PATTERN_LENGTH_LIMIT,
 	BridgeAccess,
 	BridgeConfirm,
 	BridgeControl,
@@ -100,6 +101,8 @@ export const bridgeFieldSchema = z.object({
 	max: z.number().optional(),
 	step: z.number().optional(),
 	maxLength: z.int().positive().optional(),
+	pattern: z.string().max(BRIDGE_PATTERN_LENGTH_LIMIT).optional(),
+	patternHint: panelTextSchema.optional(),
 	options: z
 		.union([
 			z.array(bridgeOptionSchema).max(64),