@serverkgg/bridge 0.0.9 → 0.0.11

package/src/probes/a2s.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
+import { probeA2s } from "./a2s";
+
+const HOST = "127.0.0.1";
+
+const CLOSED_PORT = 59_437;
+
+const listen = async (reply: Uint8Array | null) => {
+	return await Bun.udpSocket({
+		hostname: HOST,
+		port: 0,
+		socket: {
+			data(socket, _data, port, address) {
+				if (reply) {
+					socket.send(reply, port, address);
+				}
+			},
+		},
+	});
+};
+
+describe("probeA2s", () => {
+	test("rejects with an unreachable probe error when nothing listens on the port", async () => {
+		const probe = probeA2s(HOST, CLOSED_PORT, 2000);
+
+		await expect(probe).rejects.toBeInstanceOf(BridgeProbeError);
+	});
+
+	test("survives the port-unreachable the game leaves behind before it binds", async () => {
+		for (let attempt = 0; attempt < 3; attempt += 1) {
+			await probeA2s(HOST, CLOSED_PORT, 300).catch(() => null);
+		}
+
+		expect(process.exitCode ?? 0).toBe(0);
+	});
+
+	test("times out against a port that never answers", async () => {
+		const silent = await listen(null);
+
+		try {
+			const error = await probeA2s(HOST, silent.port, 250).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.TimedOut);
+		} finally {
+			silent.close();
+		}
+	});
+
+	test("rejects a reply that is not an a2s frame", async () => {
+		const noisy = await listen(
+			new Uint8Array([
+				1,
+				2,
+				3,
+				4,
+				5,
+			]),
+		);
+
+		try {
+			const error = await probeA2s(HOST, noisy.port, 2000).catch((reason: unknown) => reason);
+
+			expect(error).toBeInstanceOf(BridgeProbeError);
+			expect((error as BridgeProbeError).code).toBe(BridgeProbeCode.Malformed);
+		} finally {
+			noisy.close();
+		}
+	});
+});

package/src/probes/a2s.ts

@@ -1,4 +1,5 @@
 import type { BridgeA2sInfo } from "../context";
+import { BridgeProbeCode, BridgeProbeError } from "../core";
 
 const SIMPLE_PREFIX = 0xff;
 
@@ -67,7 +68,19 @@ const parseInfo = (view: Uint8Array) => {
 	};
 };
 
+const probeError = (code: BridgeProbeCode, message: string, cause: unknown) => {
+	if (cause instanceof BridgeProbeError) {
+		return cause;
+	}
+
+	const detail = cause instanceof Error && cause.message.length > 0 ? `: ${cause.message}` : "";
+
+	return new BridgeProbeError(code, `${message}${detail}`);
+};
+
 export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
+	const target = `${host}:${hostPort}`;
+
 	return new Promise<BridgeA2sInfo>((resolve, reject) => {
 		const startedAt = performance.now();
 
@@ -75,7 +88,7 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 		let challenged = false;
 		let settled = false;
 
-		const finish = (outcome: Omit<BridgeA2sInfo, "latencyMs"> | Error) => {
+		const finish = (outcome: Omit<BridgeA2sInfo, "latencyMs"> | BridgeProbeError) => {
 			if (settled) {
 				return;
 			}
@@ -83,9 +96,12 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 			settled = true;
 
 			clearTimeout(timer);
-			socket?.close();
 
-			if (outcome instanceof Error) {
+			try {
+				socket?.close();
+			} catch {}
+
+			if (outcome instanceof BridgeProbeError) {
 				reject(outcome);
 
 				return;
@@ -98,7 +114,7 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 		};
 
 		const timer = setTimeout(() => {
-			finish(new Error("a2s query timed out"));
+			finish(new BridgeProbeError(BridgeProbeCode.TimedOut, `a2s query to ${target} timed out`));
 		}, timeoutMs);
 
 		const handle = (view: Uint8Array) => {
@@ -109,27 +125,31 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 				|| view[2] !== SIMPLE_PREFIX
 				|| view[3] !== SIMPLE_PREFIX
 			) {
-				finish(new Error("a2s response is malformed"));
+				finish(new BridgeProbeError(BridgeProbeCode.Malformed, "a2s response is malformed"));
 
 				return;
 			}
 
 			if (view[4] === CHALLENGE_HEADER) {
 				if (challenged || view.length < 9) {
-					finish(new Error("a2s challenge is malformed"));
+					finish(new BridgeProbeError(BridgeProbeCode.Malformed, "a2s challenge is malformed"));
 
 					return;
 				}
 
 				challenged = true;
 
-				socket?.send(infoRequest(view.slice(5, 9)));
+				try {
+					socket?.send(infoRequest(view.slice(5, 9)));
+				} catch (error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `a2s challenge to ${target} could not be sent`, error));
+				}
 
 				return;
 			}
 
 			if (view[4] !== INFO_HEADER) {
-				finish(new Error("a2s response has an unexpected header"));
+				finish(new BridgeProbeError(BridgeProbeCode.Malformed, "a2s response has an unexpected header"));
 
 				return;
 			}
@@ -137,7 +157,7 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 			try {
 				finish(parseInfo(view));
 			} catch (error) {
-				finish(error instanceof Error ? error : new Error(String(error)));
+				finish(probeError(BridgeProbeCode.Malformed, `a2s response from ${target} could not be read`, error));
 			}
 		};
 
@@ -150,6 +170,9 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 				data(_socket, data) {
 					handle(data);
 				},
+				error(_socket, error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `a2s query to ${target} failed`, error));
+				},
 			},
 		})
 			.then((created) => {
@@ -161,10 +184,14 @@ export const probeA2s = (host: string, hostPort: number, timeoutMs: number) => {
 
 				socket = created;
 
-				created.send(infoRequest(null));
+				try {
+					created.send(infoRequest(null));
+				} catch (error) {
+					finish(probeError(BridgeProbeCode.Unreachable, `a2s query to ${target} could not be sent`, error));
+				}
 			})
 			.catch((error) => {
-				finish(error instanceof Error ? error : new Error(String(error)));
+				finish(probeError(BridgeProbeCode.Unreachable, `a2s socket for ${target} could not be opened`, error));
 			});
 	});
 };

package/src/protocol/bridgeFrame.ts

@@ -1,4 +1,5 @@
 import type { BridgeDesired, BridgeInstallHold, BridgeRuntime, BridgeValues, LocalizedText } from "../core";
+import type { BridgeSetupSummary } from "./bridgeSetup";
 
 export const BRIDGE_SOCKET_NAME = "bridge.sock";
 
@@ -24,6 +25,8 @@ export enum BridgeMethod {
 	Quiesce = "quiesce",
 	Release = "release",
 	Sample = "sample",
+	SetupStatus = "setupStatus",
+	SetupSubmit = "setupSubmit",
 	Start = "start",
 	Status = "status",
 	Stop = "stop",
@@ -74,7 +77,9 @@ export interface BridgeStatus {
 	outOfMemory: boolean;
 	restarts: number;
 	installError: string | null;
+	installErrorText: LocalizedText | null;
 	installHold: BridgeInstallHold | null;
+	setup: BridgeSetupSummary | null;
 }
 
 export interface BridgeSampleResult {

package/src/protocol/bridgeLimits.ts

@@ -38,6 +38,10 @@ export const BRIDGE_EVENTS_LIMIT = 32;
 
 export const BRIDGE_PENDING_FILES_LIMIT = 64;
 
+export const BRIDGE_SETUP_STEPS_LIMIT = 8;
+
+export const BRIDGE_SETUP_ACTIONS_LIMIT = 4;
+
 export const BRIDGE_ID_LENGTH_LIMIT = 32;
 
 export const BRIDGE_KEY_LENGTH_LIMIT = 64;
@@ -51,3 +55,9 @@ export const BRIDGE_PLACEHOLDER_LENGTH_LIMIT = 256;
 export const BRIDGE_STAGING_LENGTH_LIMIT = 128;
 
 export const BRIDGE_EXTENSION_LENGTH_LIMIT = 16;
+
+export const BRIDGE_PATTERN_LENGTH_LIMIT = 256;
+
+export const BRIDGE_SETUP_CODE_LENGTH_LIMIT = 64;
+
+export const BRIDGE_SETUP_DETAIL_LENGTH_LIMIT = 256;

package/src/protocol/bridgeManifest.ts

@@ -1,6 +1,7 @@
 import type { BridgeKind, BridgeStream } from "../core";
 import type { BridgePanel } from "../panel";
 import type { BridgeTerminalCommand, BridgeTerminalLevel } from "../terminal";
+import type { BridgeSetupManifest } from "./bridgeSetup";
 
 export interface BridgeTerminalRuleManifest {
 	match: string;
@@ -28,6 +29,7 @@ export interface BridgeManifest {
 	version: string;
 	panel: BridgePanel | null;
 	terminal: BridgeTerminalManifest | null;
+	setup: BridgeSetupManifest | null;
 	modules: BridgeModuleManifest[];
 	events: string[];
 }

package/src/protocol/bridgeSetup.ts

@@ -0,0 +1,97 @@
+import type { BridgeSetupPromptKind, BridgeSetupStepKind, BridgeSetupStepState, LocalizedText } from "../core";
+import type { GuideOpenTarget } from "../guides";
+
+interface BridgeSetupStepBase {
+	id: string;
+	title: LocalizedText;
+	help?: LocalizedText;
+	required?: boolean;
+}
+
+export interface BridgeSetupDriverStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Driver;
+	requiresRunning?: boolean;
+}
+
+export interface BridgeSetupFormStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Form;
+	tab: string;
+	section: string;
+	fields?: string[];
+}
+
+export interface BridgeSetupOpenStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Open;
+	target: GuideOpenTarget;
+}
+
+export type BridgeSetupStep = BridgeSetupDriverStep | BridgeSetupFormStep | BridgeSetupOpenStep;
+
+export interface BridgeSetupManifest {
+	steps: BridgeSetupStep[];
+}
+
+export interface BridgeSetupAction {
+	id: string;
+	label: LocalizedText;
+}
+
+export interface BridgeSetupWaitPrompt {
+	kind: BridgeSetupPromptKind.Wait;
+	message: LocalizedText;
+}
+
+export interface BridgeSetupProgressPrompt {
+	kind: BridgeSetupPromptKind.Progress;
+	message: LocalizedText;
+	percent: number | null;
+	detail: string | null;
+}
+
+export interface BridgeSetupLinkPrompt {
+	kind: BridgeSetupPromptKind.Link;
+	message: LocalizedText;
+	url: string;
+	code: string | null;
+	expiresAt: string | null;
+	actions: BridgeSetupAction[];
+}
+
+export interface BridgeSetupActionPrompt {
+	kind: BridgeSetupPromptKind.Action;
+	message: LocalizedText;
+	actions: BridgeSetupAction[];
+}
+
+export interface BridgeSetupFailedPrompt {
+	kind: BridgeSetupPromptKind.Failed;
+	message: LocalizedText;
+	actions: BridgeSetupAction[];
+}
+
+export type BridgeSetupPrompt =
+	| BridgeSetupActionPrompt
+	| BridgeSetupFailedPrompt
+	| BridgeSetupLinkPrompt
+	| BridgeSetupProgressPrompt
+	| BridgeSetupWaitPrompt;
+
+export interface BridgeSetupStepStatus {
+	id: string;
+	state: BridgeSetupStepState;
+}
+
+export interface BridgeSetupRuntime {
+	steps: BridgeSetupStepStatus[];
+	prompt: BridgeSetupPrompt | null;
+}
+
+export interface BridgeSetupSummary {
+	step: string | null;
+	attention: boolean;
+}
+
+export interface BridgeSetupResult {
+	supported: boolean;
+	runtime: BridgeSetupRuntime | null;
+}

package/src/protocol/index.ts

@@ -10,4 +10,5 @@ export * from "./bridgeLimits";
 export * from "./bridgeLine";
 export * from "./bridgeManifest";
 export * from "./bridgePreview";
+export * from "./bridgeSetup";
 export * from "./bridgeVersion";

package/src/runtime/bridgeConfigReader.ts

@@ -82,14 +82,8 @@ export const statePath = (config: BridgeConfig) => {
 	return `${config.run}/${BRIDGE_STATE_NAME}`;
 };
 
-export const readConfig = async (path: string): Promise<BridgeConfig> => {
-	const file = Bun.file(path);
-
-	if (!(await file.exists())) {
-		throw new BridgeConfigError(`no bridge config at "${path}"`);
-	}
-
-	const parsed: unknown = JSON.parse(await file.text());
+export const parseConfig = (text: string): BridgeConfig => {
+	const parsed: unknown = JSON.parse(text);
 
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 		throw new BridgeConfigError("bridge config must be an object");
@@ -117,3 +111,13 @@ export const readConfig = async (path: string): Promise<BridgeConfig> => {
 
 	return config;
 };
+
+export const readConfig = async (path: string): Promise<BridgeConfig> => {
+	const file = Bun.file(path);
+
+	if (!(await file.exists())) {
+		throw new BridgeConfigError(`no bridge config at "${path}"`);
+	}
+
+	return parseConfig(await file.text());
+};

package/src/runtime/bridgeContext.ts

@@ -1,18 +1,22 @@
 import type { BridgeContext } from "../context";
 import type { BridgeValues } from "../core";
-import type { BridgeConfig } from "../protocol";
+import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
+import { stripAnsi } from "../utils";
 import { createBridgeCodecs } from "./bridgeCodec";
+import { configPath } from "./bridgeConfigReader";
 import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
+import { createBridgeSecrets } from "./bridgeSecrets";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
+	onSetup: (runtime: BridgeSetupRuntime | null) => void;
 }
 
 export const createContext = (
@@ -22,6 +26,8 @@ export const createContext = (
 ): BridgeContext => {
 	const egress = createBridgeEgress(config);
 
+	const secrets = createBridgeSecrets(configPath(), config);
+
 	const files = createBridgeFiles({
 		root: config.cwd,
 		uid: config.gameUid,
@@ -45,7 +51,7 @@ export const createContext = (
 		},
 
 		secret(key) {
-			return config.secrets[key] ?? null;
+			return secrets.read(key);
 		},
 
 		port(key) {
@@ -84,6 +90,26 @@ export const createContext = (
 			async watch(pattern, timeoutMs) {
 				return await supervisor.watch(pattern, timeoutMs);
 			},
+
+			follow(pattern, onMatch) {
+				return supervisor.subscribe((entry) => {
+					const match = stripAnsi(entry.line).match(pattern);
+
+					if (match) {
+						onMatch(match);
+					}
+				});
+			},
+		},
+
+		setup: {
+			report(runtime) {
+				hooks.onSetup(runtime);
+			},
+
+			clear() {
+				hooks.onSetup(null);
+			},
 		},
 
 		emit(event, payload) {