@serverkgg/bridge 0.0.10 → 0.0.12

package/src/runtime/bridgeDriver.ts

@@ -9,6 +9,7 @@ import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
 import {
+	BridgeControl,
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
@@ -32,6 +33,7 @@ import {
 	BRIDGE_MODULES_LIMIT,
 	BRIDGE_OPTION_VALUE_LENGTH_LIMIT,
 	BRIDGE_PANEL_TABS_LIMIT,
+	BRIDGE_PATTERN_LENGTH_LIMIT,
 	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
 	BRIDGE_ROW_ACTIONS_LIMIT,
 	BRIDGE_SECTION_ACTIONS_LIMIT,
@@ -121,6 +123,110 @@ const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where:
 	return module as BridgePanelModule;
 };
 
+const compilePattern = (pattern: string): RegExp | null => {
+	try {
+		return new RegExp(pattern);
+	} catch {
+		return null;
+	}
+};
+
+const OPEN_ENDED_REPEAT = /^\{\d+,\}/;
+
+const repeatsWithoutBound = (source: string): boolean => {
+	let index = 0;
+	let inClass = false;
+
+	while (index < source.length) {
+		const char = source[index];
+
+		if (char === "\\") {
+			index += 2;
+
+			continue;
+		}
+
+		if (inClass) {
+			inClass = char !== "]";
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "[") {
+			inClass = true;
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "*" || char === "+" || (char === "{" && OPEN_ENDED_REPEAT.test(source.slice(index)))) {
+			return true;
+		}
+
+		index += 1;
+	}
+
+	return false;
+};
+
+const nestsQuantifiers = (pattern: string): boolean => {
+	const opened: number[] = [];
+
+	let index = 0;
+	let inClass = false;
+
+	while (index < pattern.length) {
+		const char = pattern[index];
+
+		if (char === "\\") {
+			index += 2;
+
+			continue;
+		}
+
+		if (inClass) {
+			inClass = char !== "]";
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "[") {
+			inClass = true;
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "(") {
+			opened.push(index);
+			index += 1;
+
+			continue;
+		}
+
+		if (char === ")") {
+			const start = opened.pop();
+
+			index += 1;
+
+			const quantified =
+				pattern[index] === "*" || pattern[index] === "+" || OPEN_ENDED_REPEAT.test(pattern.slice(index));
+
+			if (start !== undefined && quantified && repeatsWithoutBound(pattern.slice(start + 1, index - 1))) {
+				return true;
+			}
+
+			continue;
+		}
+
+		index += 1;
+	}
+
+	return false;
+};
+
 const validateVisibleWhen = (visibleWhen: BridgeVisibleWhen | undefined, where: string) => {
 	if (!visibleWhen) {
 		return;
@@ -149,12 +255,39 @@ const validateFields = (modules: Record<string, BridgePanelModule>, fields: Brid
 		validateText(field.label, "label", at);
 		validateText(field.help, "help", at);
 		validateText(field.warning, "warning", at);
+		validateText(field.patternHint, "pattern hint", at);
 		validateVisibleWhen(field.visibleWhen, at);
 
 		if (field.placeholder) {
 			lengthIn(field.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "placeholder", at);
 		}
 
+		if (field.pattern !== undefined) {
+			if (field.control !== BridgeControl.Text && field.control !== BridgeControl.Secret) {
+				fail(`${at} declares a pattern on a "${field.control}" control — only text and secret controls match one`);
+			}
+
+			lengthIn(field.pattern, BRIDGE_PATTERN_LENGTH_LIMIT, "pattern", at);
+
+			if (!compilePattern(field.pattern)) {
+				fail(`${at} declares pattern "${field.pattern}", which is not a valid regular expression`);
+			}
+
+			if (nestsQuantifiers(field.pattern)) {
+				fail(
+					`${at} declares pattern "${field.pattern}", which repeats a group that already repeats — a value can make it run for minutes`,
+				);
+			}
+		}
+
+		if (field.patternHint && field.pattern === undefined) {
+			fail(`${at} declares a pattern hint with no pattern to explain`);
+		}
+
+		if (field.control === BridgeControl.Secret && field.options) {
+			fail(`${at} is a secret control with options — a secret is typed, never chosen from a list`);
+		}
+
 		if (Array.isArray(field.options)) {
 			countIn(field.options.length, BRIDGE_FIELD_OPTIONS_LIMIT, "options", at);
 
@@ -515,6 +648,10 @@ const validateSetup = (driver: BridgeDriver) => {
 			}
 		}
 	}
+
+	if (!setup.submit && setup.steps.some((step) => step.kind === BridgeSetupStepKind.Driver)) {
+		fail(`${where} declares a driver step but exports no submit — a driver step is answered through submit`);
+	}
 };
 
 const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab) => {

package/src/runtime/bridgeProbe.ts

@@ -1,5 +1,5 @@
 import type { BridgeProbes } from "../context";
-import { probeA2s } from "../probes";
+import { probeA2s, probeMinecraftPing, probeRaknetPing } from "../probes";
 
 const PROBE_HOST = "127.0.0.1";
 
@@ -10,5 +10,17 @@ export const createBridgeProbes = (): BridgeProbes => {
 		async a2s(port) {
 			return await probeA2s(PROBE_HOST, port, PROBE_TIMEOUT_MS);
 		},
+		async minecraftPing(port) {
+			return await probeMinecraftPing(
+				{
+					address: PROBE_HOST,
+					port,
+				},
+				PROBE_TIMEOUT_MS,
+			);
+		},
+		async raknetPing(port) {
+			return await probeRaknetPing(PROBE_HOST, port, PROBE_TIMEOUT_MS);
+		},
 	};
 };

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([]);
+	});
+});