@serverkgg/bridge 0.0.14 → 0.0.15

package/src/runtime/bridgeRegistry.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
 import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
+import { BridgeLayout } from "../panel";
 import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
 import { createEventRing } from "./bridgeEvents";
@@ -296,6 +297,101 @@ describe("collection row actions", () => {
 	});
 });
 
+describe("offline row actions", () => {
+	const rosterDriver = (
+		offline: boolean,
+		list: () => Promise<BridgeRow[]>,
+		ban: (row: BridgeRow) => void,
+	): BridgeDriver => ({
+		...baseDriver(),
+		panel: {
+			tabs: [
+				{
+					id: "players",
+					title: {
+						ar: "اللاعبين",
+						en: "Players",
+					},
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "online",
+							module: "players",
+							columns: [
+								{
+									key: "name",
+									label: {
+										ar: "الاسم",
+										en: "Name",
+									},
+								},
+							],
+							actions: [
+								{
+									id: "ban",
+									label: {
+										ar: "حظر",
+										en: "Ban",
+									},
+									offline,
+								},
+							],
+						},
+					],
+				},
+			],
+		},
+		modules: {
+			players: {
+				kind: BridgeKind.Collection,
+				list,
+				actions: {
+					ban: async (_context, row) => {
+						ban(row);
+					},
+				},
+			},
+		},
+	});
+
+	test("hands an offline action the id alone when the row is not listed", async () => {
+		const seen: BridgeRow[] = [];
+		const registry = registryFor(
+			rosterDriver(
+				true,
+				async () => [],
+				(row) => seen.push(row),
+			),
+		);
+
+		await registry.invoke("players", "ban", {
+			id: "steam_1",
+		});
+
+		expect(seen).toEqual([
+			{
+				id: "steam_1",
+			},
+		]);
+	});
+
+	test("still refuses an unlisted row for an action that is not offline", async () => {
+		const registry = registryFor(
+			rosterDriver(
+				false,
+				async () => [],
+				() => undefined,
+			),
+		);
+
+		await expect(
+			registry.invoke("players", "ban", {
+				id: "steam_1",
+			}),
+		).rejects.toThrow('module "players" has no row "steam_1"');
+	});
+});
+
 describe("preview modules", () => {
 	test("lists the preview action in the manifest", () => {
 		const registry = registryFor({

package/src/runtime/bridgeRegistry.ts

@@ -1,6 +1,7 @@
 import type { BridgeContext } from "../context";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
 import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
+import { BridgeLayout } from "../panel";
 import {
 	BRIDGE_VERSION,
 	type BridgeManifest,
@@ -148,6 +149,29 @@ const asPage = (args: BridgeValues) => {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 };
 
+const offlineActionsOf = (driver: BridgeDriver): Map<string, Set<string>> => {
+	const offline = new Map<string, Set<string>>();
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (section.layout !== BridgeLayout.Table && section.layout !== BridgeLayout.Cards) {
+				continue;
+			}
+
+			for (const action of section.actions ?? []) {
+				if (action.offline === true) {
+					const actions = offline.get(section.module) ?? new Set<string>();
+
+					actions.add(action.id);
+					offline.set(section.module, actions);
+				}
+			}
+		}
+	}
+
+	return offline;
+};
+
 export const createRegistry = (
 	driver: BridgeDriver,
 	context: BridgeContext,
@@ -157,6 +181,7 @@ export const createRegistry = (
 	const cache = new Map<string, CacheEntry>();
 	const inflight = new Map<string, Promise<unknown>>();
 	const modules = driver.modules ?? {};
+	const offlineActions = offlineActionsOf(driver);
 
 	for (const [id, module] of Object.entries(modules)) {
 		if (module.kind !== BridgeKind.Actions && module.kind !== BridgeKind.Detail) {
@@ -297,7 +322,14 @@ export const createRegistry = (
 				if (rowAction) {
 					const rows = await module.list(context);
 					const id = asString(args, "id");
-					const row = rows.find((entry) => entry.id === id);
+					const listed = rows.find((entry) => entry.id === id);
+					const row =
+						listed
+						?? (offlineActions.get(name)?.has(action)
+							? {
+									id,
+								}
+							: undefined);
 
 					if (!row) {
 						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);

package/src/steam/avatars.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, describe, expect, setSystemTime, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import type { BridgeValues } from "../core";
+import { createSteamAvatars, STEAM_AVATAR_CACHE_TTL_MS, steamAvatarHashOf } from "./avatars";
+
+const ALICE_HASH = "a".repeat(40);
+
+const BOB_HASH = "b".repeat(40);
+
+const ALICE = "76561198000000001";
+
+const BOB = "76561198000000002";
+
+const identity = (id: string) => (id.startsWith("7656") ? id : null);
+
+interface Warning {
+	message: string;
+	fields: BridgeValues | undefined;
+}
+
+interface Summary {
+	steamid: string;
+	avatarfull: string;
+}
+
+interface FakeSteam {
+	context: BridgeContext;
+	calls: string[][];
+	warnings: Warning[];
+}
+
+const summaryOf = (steamId: string, hash: string): Summary => {
+	return {
+		steamid: steamId,
+		avatarfull: `https://avatars.steamstatic.com/${hash}_full.jpg`,
+	};
+};
+
+const fakeSteam = (options: { key?: string | null; answer?: (steamIds: string[]) => Summary[] }): FakeSteam => {
+	const calls: string[][] = [];
+	const warnings: Warning[] = [];
+
+	const context = {
+		secret(key: string) {
+			return key === "STEAM_WEB_API_KEY" ? (options.key === undefined ? "secret-key" : options.key) : null;
+		},
+		net: {
+			async json(url: string) {
+				const steamIds = (new URL(url).searchParams.get("steamids") ?? "").split(",").filter((id) => id.length > 0);
+
+				calls.push(steamIds);
+
+				return {
+					response: {
+						players: options.answer?.(steamIds) ?? [],
+					},
+				};
+			},
+		},
+		log: {
+			warn(message: string, fields?: BridgeValues) {
+				warnings.push({
+					message,
+					fields,
+				});
+			},
+		},
+	} as unknown as BridgeContext;
+
+	return {
+		context,
+		calls,
+		warnings,
+	};
+};
+
+afterEach(() => {
+	setSystemTime();
+});
+
+describe("reading the avatar hash out of a steam profile picture", () => {
+	test("takes the hash out of the full-size url steam answers with", () => {
+		expect(steamAvatarHashOf(`https://avatars.steamstatic.com/${ALICE_HASH}_full.jpg`)).toBe(ALICE_HASH);
+	});
+
+	test("takes the hash out of a url that carries no size suffix", () => {
+		expect(steamAvatarHashOf(`https://avatars.steamstatic.com/${BOB_HASH}.jpg`)).toBe(BOB_HASH);
+	});
+
+	test("reports no hash for a url that is not a steam avatar", () => {
+		expect(steamAvatarHashOf("https://example.com/avatar.png")).toBeNull();
+		expect(steamAvatarHashOf("")).toBeNull();
+	});
+});
+
+describe("keeping the steam avatars a roster shows", () => {
+	test("asks steam for a hash it has never seen, and answers with it", async () => {
+		const steam = fakeSteam({
+			answer: () => [
+				summaryOf(ALICE, ALICE_HASH),
+			],
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		expect(
+			await avatars.resolve(steam.context, [
+				ALICE,
+			]),
+		).toEqual(
+			new Map([
+				[
+					ALICE,
+					ALICE_HASH,
+				],
+			]),
+		);
+		expect(steam.calls).toEqual([
+			[
+				ALICE,
+			],
+		]);
+	});
+
+	test("answers the second time without asking steam again", async () => {
+		const steam = fakeSteam({
+			answer: () => [
+				summaryOf(ALICE, ALICE_HASH),
+			],
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		expect(
+			(
+				await avatars.resolve(steam.context, [
+					ALICE,
+				])
+			).get(ALICE),
+		).toBe(ALICE_HASH);
+		expect(steam.calls.length).toBe(1);
+	});
+
+	test("asks only for the ids it is missing, and still answers for the cached one", async () => {
+		const steam = fakeSteam({
+			answer: (steamIds) => {
+				return steamIds.map((steamId) => {
+					return summaryOf(steamId, steamId.endsWith("1") ? ALICE_HASH : BOB_HASH);
+				});
+			},
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		const hashes = await avatars.resolve(steam.context, [
+			ALICE,
+			BOB,
+		]);
+
+		expect(steam.calls.at(1)).toEqual([
+			BOB,
+		]);
+		expect(hashes.get(ALICE)).toBe(ALICE_HASH);
+		expect(hashes.get(BOB)).toBe(BOB_HASH);
+	});
+
+	test("asks steam again once the cached hash is six hours old", async () => {
+		setSystemTime(new Date(0));
+
+		const steam = fakeSteam({
+			answer: () => [
+				summaryOf(ALICE, ALICE_HASH),
+			],
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		setSystemTime(new Date(STEAM_AVATAR_CACHE_TTL_MS - 1));
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		expect(steam.calls.length).toBe(1);
+
+		setSystemTime(new Date(STEAM_AVATAR_CACHE_TTL_MS));
+
+		expect(
+			(
+				await avatars.resolve(steam.context, [
+					ALICE,
+				])
+			).get(ALICE),
+		).toBe(ALICE_HASH);
+		expect(steam.calls.length).toBe(2);
+	});
+
+	test("never asks steam about a player the game does not map to a steam id", async () => {
+		const steam = fakeSteam({});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		expect(
+			await avatars.resolve(steam.context, [
+				"gdk_2535000000000001",
+			]),
+		).toEqual(new Map());
+		expect(steam.calls).toEqual([]);
+	});
+
+	test("answers with nothing while the platform has no steam key", async () => {
+		const steam = fakeSteam({
+			key: null,
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		expect(
+			await avatars.resolve(steam.context, [
+				ALICE,
+			]),
+		).toEqual(new Map());
+		expect(steam.calls).toEqual([]);
+		expect(steam.warnings).toEqual([]);
+	});
+
+	test("answers with nothing and warns once when steam refuses", async () => {
+		const steam = fakeSteam({
+			answer: () => {
+				throw new Error("429 too many requests");
+			},
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		expect(
+			await avatars.resolve(steam.context, [
+				ALICE,
+			]),
+		).toEqual(new Map());
+		expect(steam.warnings.length).toBe(1);
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		expect(steam.warnings.length).toBe(1);
+	});
+
+	test("never writes the api key into the warning it logs", async () => {
+		const steam = fakeSteam({
+			key: "top-secret-key",
+			answer: () => {
+				throw new Error("steam said no");
+			},
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		await avatars.resolve(steam.context, [
+			ALICE,
+		]);
+
+		expect(JSON.stringify(steam.warnings)).not.toContain("top-secret-key");
+	});
+
+	test("keeps the roster moving when steam sends a profile with no usable picture", async () => {
+		const steam = fakeSteam({
+			answer: () => [
+				{
+					steamid: ALICE,
+					avatarfull: "https://example.com/none.png",
+				},
+			],
+		});
+		const avatars = createSteamAvatars({
+			steamIdOf: identity,
+		});
+
+		expect(
+			await avatars.resolve(steam.context, [
+				ALICE,
+			]),
+		).toEqual(new Map());
+	});
+});

package/src/steam/avatars.ts

@@ -0,0 +1,107 @@
+import type { BridgeContext } from "../context";
+import { playerSummaries, steamWebApiReady } from "./webApi";
+
+export const STEAM_AVATAR_CACHE_TTL_MS = 21_600_000;
+
+const STEAM_AVATAR = /\/([0-9a-f]{40})(?:_[a-z]+)?\.jpg/;
+
+export const steamAvatarHashOf = (url: string): string | null => {
+	return url.match(STEAM_AVATAR)?.at(1) ?? null;
+};
+
+export interface SteamAvatars {
+	resolve(context: BridgeContext, ids: string[]): Promise<Map<string, string>>;
+}
+
+export interface SteamAvatarsOptions {
+	steamIdOf: (id: string) => string | null;
+}
+
+interface CachedAvatar {
+	hash: string;
+	storedAt: number;
+}
+
+export const createSteamAvatars = (options: SteamAvatarsOptions): SteamAvatars => {
+	const { steamIdOf } = options;
+	const cached = new Map<string, CachedAvatar>();
+
+	let warned = false;
+
+	const hashOf = (steamId: string, now: number) => {
+		const entry = cached.get(steamId);
+
+		if (!entry) {
+			return null;
+		}
+
+		if (now - entry.storedAt >= STEAM_AVATAR_CACHE_TTL_MS) {
+			cached.delete(steamId);
+
+			return null;
+		}
+
+		return entry.hash;
+	};
+
+	const known = (ids: string[], now: number) => {
+		const hashes = new Map<string, string>();
+
+		for (const id of ids) {
+			const steamId = steamIdOf(id);
+			const hash = steamId === null ? null : hashOf(steamId, now);
+
+			if (hash !== null) {
+				hashes.set(id, hash);
+			}
+		}
+
+		return hashes;
+	};
+
+	return {
+		async resolve(context, ids) {
+			const now = Date.now();
+			const missing = new Set(
+				ids.flatMap((id) => {
+					const steamId = steamIdOf(id);
+
+					return steamId === null || hashOf(steamId, now) !== null
+						? []
+						: [
+								steamId,
+							];
+				}),
+			);
+
+			if (missing.size === 0 || !steamWebApiReady(context)) {
+				return known(ids, now);
+			}
+
+			try {
+				for (const summary of await playerSummaries(context, [
+					...missing,
+				])) {
+					const hash = steamAvatarHashOf(summary.avatarfull);
+
+					if (hash !== null) {
+						cached.set(summary.steamid, {
+							hash,
+							storedAt: now,
+						});
+					}
+				}
+			} catch (error) {
+				if (!warned) {
+					warned = true;
+
+					context.log.warn("the steam web api did not answer for the roster", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}
+
+			return known(ids, now);
+		},
+	};
+};

package/src/steam/index.ts

@@ -1,3 +1,4 @@
+export * from "./avatars";
 export * from "./steamApp";
 export * from "./steamcmd";
 export * from "./steamcmdLogin";

package/src/wire/panel.test.ts

@@ -10,6 +10,7 @@ import {
 	BridgeKind,
 	BridgeLayout,
 	type BridgeManifest,
+	BridgePlace,
 	type BridgeSetupManifest,
 	BridgeSetupStepKind,
 	BridgeUploadMode,
@@ -604,3 +605,81 @@ describe("the setup mirror", () => {
 		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
 	});
 });
+
+const placedManifest = (): BridgeManifest => ({
+	version: "1.0.0",
+	panel: {
+		tabs: [
+			{
+				id: "roster",
+				title: text("Roster"),
+				sections: [
+					{
+						layout: BridgeLayout.Table,
+						id: "online",
+						module: "players",
+						place: BridgePlace.Players,
+						columns: [
+							{
+								key: "name",
+								label: text("Name"),
+							},
+						],
+						actions: [
+							{
+								id: "ban",
+								label: text("Ban"),
+								confirm: BridgeConfirm.Strong,
+								offline: true,
+							},
+						],
+					},
+				],
+			},
+			{
+				id: "settings",
+				title: text("Settings"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "world",
+						title: text("World"),
+						help: text("These settings apply the next time the server starts"),
+						target: BridgeFormTarget.Variables,
+						fields: [
+							{
+								key: "WORLD_NAME",
+								control: BridgeControl.Text,
+								label: text("World name"),
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+	terminal: null,
+	setup: null,
+	modules: [
+		{
+			id: "players",
+			kind: BridgeKind.Collection,
+			requiresRunning: true,
+			refreshSeconds: 20,
+			pageSize: null,
+			dependsOn: [],
+			actions: [
+				"ban",
+			],
+		},
+	],
+	events: [],
+});
+
+describe("the placement mirror", () => {
+	test("carries place, an offline row action and a form help through unchanged", () => {
+		const source = placedManifest();
+
+		expect(bridgeManifestSchema.parse(source)).toEqual(source);
+	});
+});