@serverkgg/bridge 0.0.11 → 0.0.13

package/src/steam/steamcmd.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+import { steamcmdArgv, steamcmdScript, steamcmdUpdateArgs } from "./steamcmd";
+import { SteamcmdLoginKind, steamcmdLoginArgs } from "./steamcmdLogin";
+import { SteamcmdPlatform } from "./steamcmdPlatform";
+
+const OPTIONS = {
+	appId: "2394010",
+	label: "palworld",
+};
+
+describe("steamcmdLoginArgs", () => {
+	test("logs in anonymously by default", () => {
+		expect(steamcmdLoginArgs()).toEqual([
+			"anonymous",
+		]);
+	});
+
+	test("passes the account credentials through", () => {
+		expect(
+			steamcmdLoginArgs({
+				kind: SteamcmdLoginKind.Account,
+				username: "serverk",
+				password: "hunter2",
+			}),
+		).toEqual([
+			"serverk",
+			"hunter2",
+		]);
+	});
+});
+
+describe("steamcmdScript", () => {
+	test("lives inside the copied steamcmd directory", () => {
+		expect(steamcmdScript()).toBe(".steamcmd/steamcmd.sh");
+		expect(steamcmdScript(".sc")).toBe(".sc/steamcmd.sh");
+	});
+});
+
+describe("steamcmdArgv", () => {
+	test("forces the install directory and logs in before the command", () => {
+		expect(
+			steamcmdArgv(OPTIONS, "/home/container", [
+				"+app_update",
+				"2394010",
+			]),
+		).toEqual([
+			"./.steamcmd/steamcmd.sh",
+			"+force_install_dir",
+			"/home/container",
+			"+login",
+			"anonymous",
+			"+app_update",
+			"2394010",
+			"+quit",
+		]);
+	});
+
+	test("forces the windows platform before the login", () => {
+		const argv = steamcmdArgv(
+			{
+				...OPTIONS,
+				platform: SteamcmdPlatform.Windows,
+			},
+			"/home/container",
+			[],
+		);
+
+		expect(argv.at(1)).toBe("+@sSteamCmdForcePlatformType");
+		expect(argv.at(2)).toBe("windows");
+		expect(argv.indexOf("+@sSteamCmdForcePlatformType")).toBeLessThan(argv.indexOf("+login"));
+	});
+
+	test("leaves the platform alone on linux", () => {
+		expect(
+			steamcmdArgv(
+				{
+					...OPTIONS,
+					platform: SteamcmdPlatform.Linux,
+				},
+				"/home/container",
+				[],
+			),
+		).not.toContain("+@sSteamCmdForcePlatformType");
+	});
+});
+
+describe("steamcmdUpdateArgs", () => {
+	test("updates without validating by default", () => {
+		expect(
+			steamcmdUpdateArgs("258550", {
+				validate: false,
+			}),
+		).toEqual([
+			"+app_update",
+			"258550",
+		]);
+	});
+
+	test("adds validate last of the update flags", () => {
+		expect(
+			steamcmdUpdateArgs("258550", {
+				validate: true,
+			}),
+		).toEqual([
+			"+app_update",
+			"258550",
+			"validate",
+		]);
+	});
+
+	test("passes a branch and its password", () => {
+		expect(
+			steamcmdUpdateArgs("90", {
+				validate: true,
+				branch: "steam_legacy",
+				branchPassword: "shh",
+			}),
+		).toEqual([
+			"+app_update",
+			"90",
+			"-beta",
+			"steam_legacy",
+			"-betapassword",
+			"shh",
+			"validate",
+		]);
+	});
+
+	test("ignores a branch password without a branch", () => {
+		expect(
+			steamcmdUpdateArgs("90", {
+				validate: false,
+				branchPassword: "shh",
+			}),
+		).toEqual([
+			"+app_update",
+			"90",
+		]);
+	});
+
+	test("appends the extra arguments", () => {
+		expect(
+			steamcmdUpdateArgs("376030", {
+				validate: false,
+				extraArgs: [
+					"-language",
+					"english",
+				],
+			}),
+		).toEqual([
+			"+app_update",
+			"376030",
+			"-language",
+			"english",
+		]);
+	});
+});

package/src/steam/steamcmd.ts

@@ -0,0 +1,273 @@
+import type { BridgeContext } from "../context";
+import { execDetail } from "../utils";
+import { installedBuildId } from "./steamApp";
+import { type SteamcmdLogin, SteamcmdLoginKind, steamcmdLoginArgs } from "./steamcmdLogin";
+import { steamcmdNarrator } from "./steamcmdNarrator";
+import { SteamcmdPlatform } from "./steamcmdPlatform";
+
+export const STEAMCMD_IMAGE_DIRECTORY = "/opt/steamcmd";
+
+export const STEAMCMD_DIRECTORY = ".steamcmd";
+
+export const STEAM_DIRECTORY = ".steam";
+
+const STEAM_CLIENT_DIRECTORY = `${STEAM_DIRECTORY}/sdk64`;
+
+const SENTRY_FILE = ".sentry.b64";
+
+const UPDATE_TIMEOUT_MS = 3_600_000;
+
+const BOOTSTRAP_TIMEOUT_MS = 300_000;
+
+const SENTRY_TIMEOUT_MS = 60_000;
+
+const ATTEMPTS = 3;
+
+const RETRY_DELAY_MS = 5000;
+
+export interface SteamcmdOptions {
+	appId: string;
+	label: string;
+	imageDir?: string;
+	directory?: string;
+	platform?: SteamcmdPlatform;
+	login?: SteamcmdLogin;
+}
+
+export interface SteamcmdRunOptions {
+	timeoutMs?: number;
+	attempts?: number;
+	narrate?: boolean;
+}
+
+export interface SteamcmdUpdateOptions {
+	validate: boolean;
+	branch?: string;
+	branchPassword?: string;
+	extraArgs?: string[];
+}
+
+export interface Steamcmd {
+	directory: string;
+	script: string;
+	prepare(): Promise<void>;
+	run(args: string[], options?: SteamcmdRunOptions): Promise<void>;
+	update(options: SteamcmdUpdateOptions): Promise<void>;
+	buildId(): Promise<string | null>;
+	linkSteamClient(): Promise<void>;
+}
+
+export const steamcmdScript = (directory: string = STEAMCMD_DIRECTORY) => {
+	return `${directory}/steamcmd.sh`;
+};
+
+export const steamcmdArgv = (options: SteamcmdOptions, root: string, args: string[]) => {
+	const argv = [
+		`./${steamcmdScript(options.directory)}`,
+	];
+
+	if (options.platform === SteamcmdPlatform.Windows) {
+		argv.push("+@sSteamCmdForcePlatformType", "windows");
+	}
+
+	argv.push("+force_install_dir", root, "+login", ...steamcmdLoginArgs(options.login), ...args, "+quit");
+
+	return argv;
+};
+
+export const steamcmdUpdateArgs = (appId: string, update: SteamcmdUpdateOptions) => {
+	const args = [
+		"+app_update",
+		appId,
+	];
+
+	if (update.branch) {
+		args.push("-beta", update.branch);
+
+		if (update.branchPassword) {
+			args.push("-betapassword", update.branchPassword);
+		}
+	}
+
+	if (update.validate) {
+		args.push("validate");
+	}
+
+	if (update.extraArgs) {
+		args.push(...update.extraArgs);
+	}
+
+	return args;
+};
+
+const installRoot = async (context: BridgeContext) => {
+	const result = await context.exec([
+		"pwd",
+	]);
+
+	if (result.code !== 0) {
+		throw new Error(`the server directory could not be resolved — ${execDetail(result)}`);
+	}
+
+	return result.stdout.trim();
+};
+
+export const createSteamcmd = (context: BridgeContext, options: SteamcmdOptions): Steamcmd => {
+	const directory = options.directory ?? STEAMCMD_DIRECTORY;
+	const imageDir = options.imageDir ?? STEAMCMD_IMAGE_DIRECTORY;
+	const script = steamcmdScript(directory);
+	const login = options.login;
+
+	const applySentry = async () => {
+		if (login?.kind !== SteamcmdLoginKind.Account || !login.sentry) {
+			return;
+		}
+
+		context.log("restoring the steam sentry");
+
+		const encoded = `${directory}/${SENTRY_FILE}`;
+
+		await context.files.write(encoded, login.sentry);
+
+		const result = await context.exec(
+			[
+				"sh",
+				"-c",
+				'base64 -d < "$1" | tar -x -C "$2"',
+				"steamcmd-sentry",
+				encoded,
+				directory,
+			],
+			{
+				timeoutMs: SENTRY_TIMEOUT_MS,
+			},
+		);
+
+		await context.files.remove(encoded);
+
+		if (result.code !== 0) {
+			throw new Error(`the steam sentry could not be restored — ${execDetail(result)}`);
+		}
+	};
+
+	const run: Steamcmd["run"] = async (args, runOptions = {}) => {
+		const argv = steamcmdArgv(
+			{
+				...options,
+				directory,
+			},
+			await installRoot(context),
+			args,
+		);
+
+		const attempts = runOptions.attempts ?? ATTEMPTS;
+
+		let failure = "";
+
+		for (let attempt = 1; attempt <= attempts; attempt++) {
+			const result = await context.exec(argv, {
+				timeoutMs: runOptions.timeoutMs ?? UPDATE_TIMEOUT_MS,
+				...(runOptions.narrate === false
+					? {}
+					: {
+							onOutput: steamcmdNarrator(context.log, options.label),
+						}),
+			});
+
+			if (result.code === 0) {
+				return;
+			}
+
+			failure = `steamcmd exited with code ${result.code} — ${execDetail(result)}`;
+
+			if (attempt < attempts) {
+				context.log("steamcmd did not finish, trying again", {
+					attempt,
+					of: attempts,
+					code: result.code,
+				});
+
+				await Bun.sleep(RETRY_DELAY_MS);
+			}
+		}
+
+		throw new Error(failure);
+	};
+
+	return {
+		directory,
+		script,
+
+		async prepare() {
+			if (await context.files.exists(script)) {
+				return;
+			}
+
+			context.log("preparing steamcmd");
+
+			await context.files.ensure(directory);
+
+			const copied = await context.exec([
+				"cp",
+				"-a",
+				`${imageDir}/.`,
+				directory,
+			]);
+
+			if (copied.code !== 0) {
+				throw new Error(`steamcmd could not be prepared — ${execDetail(copied)}`);
+			}
+
+			await applySentry();
+
+			context.log("warming up steamcmd");
+
+			const bootstrap = await context.exec(
+				[
+					`./${script}`,
+					"+login",
+					...steamcmdLoginArgs(login),
+					"+app_info_update",
+					"1",
+					"+app_info_print",
+					options.appId,
+					"+quit",
+				],
+				{
+					timeoutMs: BOOTSTRAP_TIMEOUT_MS,
+				},
+			);
+
+			if (bootstrap.code !== 0) {
+				context.log("steamcmd warm-up did not finish cleanly, continuing", {
+					code: bootstrap.code,
+				});
+			}
+		},
+
+		run,
+
+		async update(update) {
+			await run(steamcmdUpdateArgs(options.appId, update));
+		},
+
+		async buildId() {
+			return await installedBuildId(context, options.appId);
+		},
+
+		async linkSteamClient() {
+			await context.files.ensure(STEAM_CLIENT_DIRECTORY);
+
+			const result = await context.exec([
+				"cp",
+				"-f",
+				`${directory}/linux64/steamclient.so`,
+				`${STEAM_CLIENT_DIRECTORY}/steamclient.so`,
+			]);
+
+			if (result.code !== 0) {
+				throw new Error(`steamclient.so could not be linked — ${execDetail(result)}`);
+			}
+		},
+	};
+};

package/src/steam/steamcmdLogin.ts

@@ -0,0 +1,34 @@
+export enum SteamcmdLoginKind {
+	Account = "account",
+	Anonymous = "anonymous",
+}
+
+export interface SteamcmdAnonymousLogin {
+	kind: SteamcmdLoginKind.Anonymous;
+}
+
+export interface SteamcmdAccountLogin {
+	kind: SteamcmdLoginKind.Account;
+	username: string;
+	password: string;
+	sentry?: string;
+}
+
+export type SteamcmdLogin = SteamcmdAnonymousLogin | SteamcmdAccountLogin;
+
+export const ANONYMOUS_LOGIN: SteamcmdAnonymousLogin = {
+	kind: SteamcmdLoginKind.Anonymous,
+};
+
+export const steamcmdLoginArgs = (login: SteamcmdLogin = ANONYMOUS_LOGIN) => {
+	if (login.kind === SteamcmdLoginKind.Anonymous) {
+		return [
+			"anonymous",
+		];
+	}
+
+	return [
+		login.username,
+		login.password,
+	];
+};

package/src/steam/steamcmdNarrator.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeLog } from "../context";
+import type { BridgeValues } from "../core";
+import { steamcmdNarrator } from "./steamcmdNarrator";
+
+const recorder = () => {
+	const lines: string[] = [];
+	const fields: (BridgeValues | undefined)[] = [];
+
+	const log = ((message: string, values?: BridgeValues) => {
+		lines.push(message);
+		fields.push(values);
+	}) as BridgeLog;
+
+	return {
+		log,
+		lines,
+		fields,
+	};
+};
+
+describe("steamcmdNarrator", () => {
+	test("reports download progress in ten percent steps", () => {
+		const { log, lines, fields } = recorder();
+		const narrate = steamcmdNarrator(log, "palworld");
+
+		for (const percent of [
+			2,
+			9,
+			11,
+			12,
+			25,
+			99,
+		]) {
+			narrate(`Update state (0x61) downloading, progress: ${percent}.44 (1 / 2)`);
+		}
+
+		expect(lines).toEqual([
+			"downloading palworld",
+			"downloading palworld",
+			"downloading palworld",
+			"downloading palworld",
+		]);
+		expect(fields).toEqual([
+			{
+				percent: 0,
+			},
+			{
+				percent: 10,
+			},
+			{
+				percent: 20,
+			},
+			{
+				percent: 90,
+			},
+		]);
+	});
+
+	test("starts counting again when the phase changes", () => {
+		const { log, fields } = recorder();
+		const narrate = steamcmdNarrator(log, "rust");
+
+		narrate("Update state (0x61) downloading, progress: 80.00 (1 / 2)");
+		narrate("Update state (0x81) verifying, progress: 10.00 (1 / 2)");
+
+		expect(fields).toEqual([
+			{
+				percent: 80,
+			},
+			{
+				percent: 10,
+			},
+		]);
+	});
+
+	test("passes notable lines through with the ansi stripped", () => {
+		const { log, lines } = recorder();
+		const narrate = steamcmdNarrator(log, "rust");
+
+		narrate(`${String.fromCharCode(27)}[1mSuccess! App '258550' fully installed.${String.fromCharCode(27)}[0m`);
+		narrate("Logging in user 'serverk' to Steam Public...");
+		narrate("some chatter nobody needs");
+
+		expect(lines).toEqual([
+			"Success! App '258550' fully installed.",
+			"Logging in user 'serverk' to Steam Public...",
+		]);
+	});
+});

package/src/steam/steamcmdNarrator.ts

@@ -0,0 +1,43 @@
+import type { BridgeLog } from "../context";
+import { stripAnsi } from "../utils";
+
+const PROGRESS = /Update state \(0x[0-9a-f]+\)\s*(?<phase>[^,]+),\s*progress:\s*(?<percent>\d+)\.\d+/i;
+
+const PROGRESS_STEP = 10;
+
+const NOTABLE = /^(Error|Warning|Failed|Success|Logging in|Connecting|Update state \(0x\d+\) (?!downloading))/i;
+
+export const steamcmdNarrator = (log: BridgeLog, label: string) => {
+	let phase = "";
+	let reported = -1;
+
+	return (raw: string) => {
+		const line = stripAnsi(raw).trim();
+		const progress = line.match(PROGRESS);
+
+		if (progress?.groups) {
+			const current = progress.groups.phase?.trim() ?? "";
+			const percent = Number(progress.groups.percent);
+			const step = Math.floor(percent / PROGRESS_STEP) * PROGRESS_STEP;
+
+			if (current !== phase) {
+				phase = current;
+				reported = -1;
+			}
+
+			if (step > reported) {
+				reported = step;
+
+				log(`${phase} ${label}`, {
+					percent: step,
+				});
+			}
+
+			return;
+		}
+
+		if (NOTABLE.test(line)) {
+			log(line);
+		}
+	};
+};

package/src/steam/steamcmdPlatform.ts

@@ -0,0 +1,4 @@
+export enum SteamcmdPlatform {
+	Linux = "linux",
+	Windows = "windows",
+}

package/src/steam/webApi.ts

@@ -0,0 +1,70 @@
+import type { BridgeContext } from "../context";
+import { BridgeSecretError } from "../core";
+
+export const STEAM_WEB_API = "https://api.steampowered.com";
+
+export const STEAM_WEB_API_SECRET = "STEAM_WEB_API_KEY";
+
+const SUMMARY_BATCH = 100;
+
+const SUMMARY_CACHE_SECONDS = 600;
+
+export interface SteamPlayerSummary {
+	steamid: string;
+	personaname: string;
+	profileurl: string;
+	avatar: string;
+	avatarmedium: string;
+	avatarfull: string;
+}
+
+interface PlayerSummaryResponse {
+	response?: {
+		players?: SteamPlayerSummary[];
+	};
+}
+
+export const steamWebApiReady = (context: BridgeContext) => {
+	return context.secret(STEAM_WEB_API_SECRET) !== null;
+};
+
+const webApiKey = (context: BridgeContext) => {
+	const key = context.secret(STEAM_WEB_API_SECRET);
+
+	if (!key) {
+		throw new BridgeSecretError(STEAM_WEB_API_SECRET, "the steam web api needs a key before it can be asked");
+	}
+
+	return key;
+};
+
+export const playerSummaries = async (context: BridgeContext, ids: string[]): Promise<SteamPlayerSummary[]> => {
+	const wanted = [
+		...new Set(ids.filter((id) => id.length > 0)),
+	];
+
+	if (wanted.length === 0) {
+		return [];
+	}
+
+	const key = webApiKey(context);
+	const summaries: SteamPlayerSummary[] = [];
+
+	for (let cursor = 0; cursor < wanted.length; cursor += SUMMARY_BATCH) {
+		const query = new URLSearchParams({
+			key,
+			steamids: wanted.slice(cursor, cursor + SUMMARY_BATCH).join(","),
+		});
+
+		const page = await context.net.json<PlayerSummaryResponse>(
+			`${STEAM_WEB_API}/ISteamUser/GetPlayerSummaries/v2/?${query.toString()}`,
+			{
+				cacheSeconds: SUMMARY_CACHE_SECONDS,
+			},
+		);
+
+		summaries.push(...(page.response?.players ?? []));
+	}
+
+	return summaries;
+};

package/src/steam/workshop.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { workshopContentPath, workshopDownloadArgs, workshopFormBody } from "./workshop";
+
+describe("workshopFormBody", () => {
+	test("writes the count and the indexed ids", () => {
+		expect(
+			workshopFormBody("itemcount", [
+				"450814997",
+				"1234",
+			]),
+		).toBe("itemcount=2&publishedfileids%5B0%5D=450814997&publishedfileids%5B1%5D=1234");
+	});
+
+	test("names the count field the collection api expects", () => {
+		expect(
+			workshopFormBody("collectioncount", [
+				"1",
+			]),
+		).toBe("collectioncount=1&publishedfileids%5B0%5D=1");
+	});
+});
+
+describe("workshopDownloadArgs", () => {
+	test("asks steamcmd for every item", () => {
+		expect(
+			workshopDownloadArgs("440900", [
+				"1",
+				"2",
+			]),
+		).toEqual([
+			"+workshop_download_item",
+			"440900",
+			"1",
+			"+workshop_download_item",
+			"440900",
+			"2",
+		]);
+	});
+});
+
+describe("workshopContentPath", () => {
+	test("points at where steamcmd unpacks an item", () => {
+		expect(workshopContentPath("440900", "12345")).toBe("steamapps/workshop/content/440900/12345");
+	});
+});