@serverkgg/bridge 0.0.10 → 0.0.11

package/src/runtime/bridgeSetup.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { BridgeSetupPromptKind, BridgeSetupStepState } from "../core";
 import type { BridgeSetupRuntime } from "../protocol";
-import { failedSetup, setupSummaryOf, unsupportedSetup } from "./bridgeSetup";
+import { failedSetup, normalizeSetupRuntime, setupSummaryOf, unsupportedSetup } from "./bridgeSetup";
 
 const text = (value: string) => ({
 	ar: value,
@@ -187,3 +187,389 @@ describe("a rejected submit", () => {
 		});
 	});
 });
+
+const declared: ReadonlySet<string> = new Set([
+	"sign-in",
+	"download",
+]);
+
+const normalizing = (runtime: BridgeSetupRuntime | null) => {
+	const reasons: string[] = [];
+
+	const normalized = normalizeSetupRuntime(runtime, {
+		declared,
+		warn: (_message, fields) => {
+			reasons.push(String(fields?.reason));
+		},
+	});
+
+	return {
+		normalized,
+		reasons,
+	};
+};
+
+const withSteps = (steps: BridgeSetupRuntime["steps"]): BridgeSetupRuntime => ({
+	steps,
+	prompt: null,
+});
+
+const link = (
+	prompt: Partial<
+		Extract<
+			BridgeSetupRuntime["prompt"],
+			{
+				kind: BridgeSetupPromptKind.Link;
+			}
+		>
+	>,
+) => {
+	return runtimeWith({
+		kind: BridgeSetupPromptKind.Link,
+		message: text("sign in with your account"),
+		url: "https://hytale.com/device",
+		code: "ABCD-EFGH",
+		expiresAt: null,
+		actions: [],
+		...prompt,
+	});
+};
+
+describe("normalizing a reported runtime", () => {
+	test("has nothing to normalize while the driver reported no runtime", () => {
+		expect(
+			normalizeSetupRuntime(null, {
+				declared,
+				warn: () => {
+					return;
+				},
+			}),
+		).toBeNull();
+	});
+
+	test("drops a step the driver never declared", () => {
+		const { normalized, reasons } = normalizing(
+			withSteps([
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Active,
+				},
+				{
+					id: "invent",
+					state: BridgeSetupStepState.Pending,
+				},
+			]),
+		);
+
+		expect(normalized?.steps).toEqual([
+			{
+				id: "sign-in",
+				state: BridgeSetupStepState.Active,
+			},
+		]);
+		expect(reasons).toEqual([
+			"unknown-step",
+		]);
+	});
+
+	test("drops the second report of the same step", () => {
+		const { normalized, reasons } = normalizing(
+			withSteps([
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Done,
+				},
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Failed,
+				},
+			]),
+		);
+
+		expect(normalized?.steps).toEqual([
+			{
+				id: "sign-in",
+				state: BridgeSetupStepState.Done,
+			},
+		]);
+		expect(reasons).toEqual([
+			"duplicate-step",
+		]);
+	});
+
+	test("keeps the first active step and pends the rest", () => {
+		const { normalized, reasons } = normalizing(
+			withSteps([
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Active,
+				},
+				{
+					id: "download",
+					state: BridgeSetupStepState.Active,
+				},
+			]),
+		);
+
+		expect(normalized?.steps).toEqual([
+			{
+				id: "sign-in",
+				state: BridgeSetupStepState.Active,
+			},
+			{
+				id: "download",
+				state: BridgeSetupStepState.Pending,
+			},
+		]);
+		expect(reasons).toEqual([
+			"extra-active-step",
+		]);
+	});
+
+	test("clamps a percent that left the scale", () => {
+		expect(
+			normalizing(
+				runtimeWith({
+					kind: BridgeSetupPromptKind.Progress,
+					message: text("downloading the game"),
+					percent: 140,
+					detail: null,
+				}),
+			),
+		).toEqual({
+			normalized: {
+				steps: [
+					{
+						id: "sign-in",
+						state: BridgeSetupStepState.Active,
+					},
+					{
+						id: "download",
+						state: BridgeSetupStepState.Pending,
+					},
+				],
+				prompt: {
+					kind: BridgeSetupPromptKind.Progress,
+					message: text("downloading the game"),
+					percent: 100,
+					detail: null,
+				},
+			},
+			reasons: [
+				"percent-out-of-range",
+			],
+		});
+	});
+
+	test("drops a percent that is not a number", () => {
+		const { normalized, reasons } = normalizing(
+			runtimeWith({
+				kind: BridgeSetupPromptKind.Progress,
+				message: text("downloading the game"),
+				percent: Number.NaN,
+				detail: null,
+			}),
+		);
+
+		expect(normalized?.prompt).toEqual({
+			kind: BridgeSetupPromptKind.Progress,
+			message: text("downloading the game"),
+			percent: null,
+			detail: null,
+		});
+		expect(reasons).toEqual([
+			"unusable-percent",
+		]);
+	});
+
+	test("cuts a detail line to the length the platform takes", () => {
+		const { normalized, reasons } = normalizing(
+			runtimeWith({
+				kind: BridgeSetupPromptKind.Progress,
+				message: text("downloading the game"),
+				percent: null,
+				detail: "d".repeat(300),
+			}),
+		);
+
+		expect(normalized?.prompt).toEqual({
+			kind: BridgeSetupPromptKind.Progress,
+			message: text("downloading the game"),
+			percent: null,
+			detail: "d".repeat(256),
+		});
+		expect(reasons).toEqual([
+			"long-detail",
+		]);
+	});
+
+	test("drops an empty detail line", () => {
+		const { normalized, reasons } = normalizing(
+			runtimeWith({
+				kind: BridgeSetupPromptKind.Progress,
+				message: text("downloading the game"),
+				percent: null,
+				detail: "",
+			}),
+		);
+
+		expect(normalized?.prompt).toMatchObject({
+			detail: null,
+		});
+		expect(reasons).toEqual([
+			"empty-detail",
+		]);
+	});
+
+	test("drops an action whose id is not kebab-case and the duplicate beside it", () => {
+		const { normalized, reasons } = normalizing(
+			runtimeWith({
+				kind: BridgeSetupPromptKind.Action,
+				message: text("get a new code"),
+				actions: [
+					{
+						id: "renew",
+						label: text("Get a new code"),
+					},
+					{
+						id: "Renew Now",
+						label: text("Get a new code"),
+					},
+					{
+						id: "renew",
+						label: text("Get a new code"),
+					},
+				],
+			}),
+		);
+
+		expect(normalized?.prompt).toEqual({
+			kind: BridgeSetupPromptKind.Action,
+			message: text("get a new code"),
+			actions: [
+				{
+					id: "renew",
+					label: text("Get a new code"),
+				},
+			],
+		});
+		expect(reasons).toEqual([
+			"unknown-action-id",
+			"duplicate-action",
+		]);
+	});
+
+	test("keeps only as many actions as the platform renders", () => {
+		const { normalized, reasons } = normalizing(
+			runtimeWith({
+				kind: BridgeSetupPromptKind.Failed,
+				message: text("the sign-in expired"),
+				actions: Array.from({
+					length: 6,
+				}).map((_entry, index) => ({
+					id: `action-${index}`,
+					label: text(`Action ${index}`),
+				})),
+			}),
+		);
+
+		expect(normalized?.prompt?.kind).toBe(BridgeSetupPromptKind.Failed);
+		expect(normalized?.prompt && "actions" in normalized.prompt ? normalized.prompt.actions.length : 0).toBe(4);
+		expect(reasons).toEqual([
+			"extra-actions",
+		]);
+	});
+
+	test("cuts a long code and drops an empty one", () => {
+		expect(
+			normalizing(
+				link({
+					code: "c".repeat(80),
+				}),
+			).normalized?.prompt,
+		).toMatchObject({
+			code: "c".repeat(64),
+		});
+
+		expect(
+			normalizing(
+				link({
+					code: "",
+				}),
+			).reasons,
+		).toEqual([
+			"empty-code",
+		]);
+	});
+
+	test("re-emits an expiry as an iso stamp and drops one it cannot read", () => {
+		expect(
+			normalizing(
+				link({
+					expiresAt: "2026-09-04T10:00:00+03:00",
+				}),
+			).normalized?.prompt,
+		).toMatchObject({
+			expiresAt: "2026-09-04T07:00:00.000Z",
+		});
+
+		expect(
+			normalizing(
+				link({
+					expiresAt: "soon",
+				}),
+			).reasons,
+		).toEqual([
+			"unusable-expiry",
+		]);
+	});
+
+	test("turns a link the browser cannot open into a failed prompt keeping its actions", () => {
+		const { normalized, reasons } = normalizing(
+			link({
+				url: "javascript:alert(1)",
+				actions: [
+					{
+						id: "renew",
+						label: text("Get a new code"),
+					},
+				],
+			}),
+		);
+
+		expect(normalized?.prompt).toEqual({
+			kind: BridgeSetupPromptKind.Failed,
+			message: {
+				ar: "اللعبة رجّعت رابط دخول ما يشتغل. جرّب مرة ثانية.",
+				en: "The game reported a broken sign-in link. Try again.",
+			},
+			actions: [
+				{
+					id: "renew",
+					label: text("Get a new code"),
+				},
+			],
+		});
+		expect(reasons).toEqual([
+			"unusable-link",
+		]);
+	});
+
+	test("turns a url it cannot parse into a failed prompt", () => {
+		expect(
+			normalizing(
+				link({
+					url: "not a url",
+				}),
+			).normalized?.prompt?.kind,
+		).toBe(BridgeSetupPromptKind.Failed);
+	});
+
+	test("leaves a healthy runtime exactly as the driver reported it", () => {
+		const source = link({});
+		const { normalized, reasons } = normalizing(source);
+
+		expect(normalized).toEqual(source);
+		expect(reasons).toEqual([]);
+	});
+});

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