@serverkgg/bridge 0.0.13 → 0.0.15

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

package/src/wire/panel.ts

@@ -12,6 +12,7 @@ import {
 	BridgeLayout,
 	type BridgeManifest,
 	type BridgePanel,
+	BridgePlace,
 	type BridgeSection,
 	type BridgeSetupManifest,
 	type BridgeSetupStep,
@@ -118,6 +119,7 @@ export const bridgeSectionActionSchema = z.object({
 	confirm: z.enum(BridgeConfirm).optional(),
 	confirmText: panelTextSchema.optional(),
 	download: z.boolean().optional(),
+	offline: z.boolean().optional(),
 	fields: z.array(bridgeFieldSchema).max(ACTION_FIELDS_LIMIT).optional(),
 });
 
@@ -148,6 +150,7 @@ export const bridgeActionsSectionSchema = z.object({
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
 	help: panelTextSchema.optional(),
+	place: z.enum(BridgePlace).optional(),
 	module: zBridgeModuleId,
 	actions: z.array(bridgeSectionActionSchema).min(1).max(SECTION_ACTIONS_LIMIT),
 	visibleWhen: bridgeVisibleWhenSchema.optional(),
@@ -158,6 +161,7 @@ export const bridgeFormSectionSchema = z.object({
 	layout: z.literal(BridgeLayout.Form),
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
 	target: z.enum(BridgeFormTarget),
 	module: zBridgeModuleId.optional(),
 	preview: bridgePreviewRefSchema.optional(),
@@ -175,6 +179,8 @@ export const bridgeDetailSectionSchema = z.object({
 	layout: z.literal(BridgeLayout.Detail),
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
+	place: z.enum(BridgePlace).optional(),
 	module: zBridgeModuleId,
 	actions: z.array(bridgeSectionActionSchema).max(SECTION_ACTIONS_LIMIT).optional(),
 	reinstall: z.boolean().optional(),
@@ -196,6 +202,8 @@ export const bridgeTableSectionSchema = z.object({
 	layout: z.literal(BridgeLayout.Table),
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
+	place: z.enum(BridgePlace).optional(),
 	module: zBridgeModuleId,
 	restartHint: z.boolean().optional(),
 	columns: z.array(bridgeColumnSchema).min(1).max(8),
@@ -211,6 +219,8 @@ export const bridgeCardsSectionSchema = z.object({
 	layout: z.literal(BridgeLayout.Cards),
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
+	place: z.enum(BridgePlace).optional(),
 	module: zBridgeModuleId,
 	titleKey: zKey,
 	subtitleKey: zKey.optional(),
@@ -224,6 +234,7 @@ export const bridgeCatalogSectionSchema = z.object({
 	layout: z.literal(BridgeLayout.Catalog),
 	id: zBridgeId,
 	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
 	module: zBridgeModuleId,
 	restartHint: z.boolean().optional(),
 	reinstall: z.boolean().optional(),