@serverkgg/bridge 0.1.7 → 0.1.8

package/src/manifest/index.ts

@@ -12,3 +12,4 @@ export * from "./presence";
 export * from "./primitives";
 export * from "./runtime";
 export * from "./source";
+export * from "./steam";

package/src/manifest/manifest.test.ts

@@ -931,6 +931,85 @@ describe("presence", () => {
 	});
 });
 
+describe("steam", () => {
+	it("is optional, so a game that declares none parses", () => {
+		const result = gameManifestSchema.safeParse(base());
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toBeUndefined();
+	});
+
+	it("accepts the server app id", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toEqual({
+			appId: 896_660,
+		});
+	});
+
+	it("accepts the variable that holds the Steam branch", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+				branchVariable: "VALHEIM_BRANCH",
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toEqual({
+			appId: 896_660,
+			branchVariable: "VALHEIM_BRANCH",
+		});
+	});
+
+	it("refuses a branch variable that is not an environment key", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+				branchVariable: "valheim-branch",
+			},
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain("must be SCREAMING_SNAKE_CASE");
+	});
+
+	for (const appId of [
+		0,
+		-1,
+		2.5,
+		"258550",
+	]) {
+		it(`refuses ${JSON.stringify(appId)} as an app id`, () => {
+			const result = gameManifestSchema.safeParse({
+				...base(),
+				steam: {
+					appId,
+				},
+			});
+
+			expect(result.success).toBe(false);
+		});
+	}
+
+	it("refuses a block with no app id", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {},
+		});
+
+		expect(result.success).toBe(false);
+	});
+});
+
 describe("container runtime", () => {
 	it("materializes the defaults when the manifest declares no runtime", () => {
 		const manifest = manifestSchema.parse(base());

package/src/manifest/manifest.ts

@@ -22,6 +22,7 @@ import {
 	zSlug,
 } from "./primitives";
 import { ManifestPlatform, manifestRuntimeSchema, WINE_MIN_SHM_MB } from "./runtime";
+import { manifestSteamSchema } from "./steam";
 
 export const MANIFEST_SCHEMA_VERSION = "serverk.gg/v1";
 
@@ -825,6 +826,10 @@ export const gameManifestSchema = z
 		secrets: z.array(manifestSecretSchema).max(16).default([]),
 		files: manifestFilesSchema.prefault({}),
 		presence: manifestPresenceSchema.optional(),
+		steam: manifestSteamSchema.optional().meta({
+			description:
+				"The Steam app behind this game. Declare it when steamcmd installs the server, so the platform sees when a newer game version is out.",
+		}),
 	})
 	.check((ctx) => {
 		if (ctx.issues.length > 0) {

package/src/manifest/steam.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { zEnvKey } from "./primitives";
+
+export const manifestSteamSchema = z.object({
+	appId: z.int().positive().meta({
+		description: "Steam app id of the dedicated server, the one steamcmd installs with app_update.",
+	}),
+	branchVariable: zEnvKey.optional().meta({
+		description:
+			"The server variable that holds the Steam branch the customer picked. Omit it when the package installs the public branch only.",
+	}),
+});
+
+export type ManifestSteam = z.infer<typeof manifestSteamSchema>;

package/src/steam/steamcmd.test.ts

@@ -1,5 +1,16 @@
 import { describe, expect, it } from "bun:test";
-import { steamcmdArgv, steamcmdFailureText, steamcmdScript, steamcmdUpdateArgs } from "./steamcmd";
+import type { BridgeContext, BridgeExecResult } from "../context";
+import type { BridgeValues } from "../core";
+import {
+	createSteamcmd,
+	SteamcmdFailure,
+	steamcmdArgv,
+	steamcmdFailureOf,
+	steamcmdFailureText,
+	steamcmdRetryable,
+	steamcmdScript,
+	steamcmdUpdateArgs,
+} from "./steamcmd";
 import { SteamcmdLoginKind, steamcmdLoginArgs } from "./steamcmdLogin";
 import { SteamcmdPlatform } from "./steamcmdPlatform";
 
@@ -8,6 +19,86 @@ const OPTIONS = {
 	label: "palworld",
 };
 
+const MANIFEST = [
+	'"AppState"',
+	"{",
+	'\t"appid"\t\t"2394010"',
+	'\t"buildid"\t\t"19582821"',
+	"}",
+].join("\n");
+
+const SUCCESS: BridgeExecResult = {
+	stdout: "Success! App '2394010' fully installed.",
+	stderr: "",
+	code: 0,
+};
+
+interface Logged {
+	message: string;
+	fields?: BridgeValues;
+}
+
+const resultOf = (stdout: string): BridgeExecResult => {
+	return {
+		stdout,
+		stderr: "",
+		code: 8,
+	};
+};
+
+const contextWith = (answers: BridgeExecResult[], files: Record<string, string>) => {
+	const commands: string[][] = [];
+	const logs: Logged[] = [];
+
+	const log = Object.assign(
+		(message: string, fields?: BridgeValues) => {
+			logs.push({
+				message,
+				fields,
+			});
+		},
+		{
+			warn(message: string, fields?: BridgeValues) {
+				logs.push({
+					message,
+					fields,
+				});
+			},
+		},
+	);
+
+	const context = {
+		async exec(command: string[]) {
+			commands.push(command);
+
+			if (command[0] === "pwd") {
+				return {
+					stdout: "/home/container\n",
+					stderr: "",
+					code: 0,
+				};
+			}
+
+			return answers.shift() ?? SUCCESS;
+		},
+		files: {
+			async exists(path: string) {
+				return path in files;
+			},
+			async read(path: string) {
+				return files[path] ?? "";
+			},
+		},
+		log,
+	} as unknown as BridgeContext;
+
+	return {
+		context,
+		commands,
+		logs,
+	};
+};
+
 describe("steamcmdLoginArgs", () => {
 	it("logs in anonymously by default", () => {
 		expect(steamcmdLoginArgs()).toEqual([
@@ -85,12 +176,26 @@ describe("steamcmdArgv", () => {
 });
 
 describe("steamcmdUpdateArgs", () => {
+	it("refreshes the app info before the update", () => {
+		const args = steamcmdUpdateArgs("258550", {
+			validate: false,
+		});
+
+		expect(args.slice(0, 2)).toEqual([
+			"+app_info_update",
+			"1",
+		]);
+		expect(args.indexOf("+app_info_update")).toBeLessThan(args.indexOf("+app_update"));
+	});
+
 	it("updates without validating by default", () => {
 		expect(
 			steamcmdUpdateArgs("258550", {
 				validate: false,
 			}),
 		).toEqual([
+			"+app_info_update",
+			"1",
 			"+app_update",
 			"258550",
 		]);
@@ -102,6 +207,8 @@ describe("steamcmdUpdateArgs", () => {
 				validate: true,
 			}),
 		).toEqual([
+			"+app_info_update",
+			"1",
 			"+app_update",
 			"258550",
 			"validate",
@@ -116,6 +223,8 @@ describe("steamcmdUpdateArgs", () => {
 				branchPassword: "shh",
 			}),
 		).toEqual([
+			"+app_info_update",
+			"1",
 			"+app_update",
 			"90",
 			"-beta",
@@ -133,6 +242,8 @@ describe("steamcmdUpdateArgs", () => {
 				branchPassword: "shh",
 			}),
 		).toEqual([
+			"+app_info_update",
+			"1",
 			"+app_update",
 			"90",
 		]);
@@ -148,6 +259,8 @@ describe("steamcmdUpdateArgs", () => {
 				],
 			}),
 		).toEqual([
+			"+app_info_update",
+			"1",
 			"+app_update",
 			"376030",
 			"-language",
@@ -156,7 +269,142 @@ describe("steamcmdUpdateArgs", () => {
 	});
 });
 
+const FAILURE_CASES = [
+	{
+		output: "Error! App '2394010' state is 0x202 after update job.",
+		failure: SteamcmdFailure.DiskFull,
+	},
+	{
+		output: "Error! App '2394010' state is 0x212 after update job.",
+		failure: SteamcmdFailure.DiskFull,
+	},
+	{
+		output: "Invalid platform",
+		failure: SteamcmdFailure.InvalidPlatform,
+	},
+	{
+		output: "No subscription",
+		failure: SteamcmdFailure.NoSubscription,
+	},
+	{
+		output: "Password check for AppId 896660",
+		failure: SteamcmdFailure.BranchPassword,
+	},
+	{
+		output: "Error! State is 0x402 after update job.",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Error! State is 0x602 after update job.",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Error! App '2394010' state is 0x606 after update job.",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Error! App '232250' state is 0x626 after update job.",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Error! App '317670' state is 0x6A6 after update job.",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Missing configuration",
+		failure: SteamcmdFailure.Transient,
+	},
+	{
+		output: "Update state (0x61) downloading, progress: 1.11 (127644881 / 11530459441)",
+		failure: SteamcmdFailure.Unknown,
+	},
+	{
+		output: "",
+		failure: SteamcmdFailure.Unknown,
+	},
+];
+
+describe("steamcmdFailureOf", () => {
+	for (const item of FAILURE_CASES) {
+		it(`reads ${JSON.stringify(item.output)} as ${item.failure}`, () => {
+			expect(steamcmdFailureOf(resultOf(item.output))).toBe(item.failure);
+		});
+	}
+
+	it("reads the code from stderr too", () => {
+		expect(
+			steamcmdFailureOf({
+				stdout: "",
+				stderr: "Error! App '2394010' state is 0x212 after update job.",
+				code: 8,
+			}),
+		).toBe(SteamcmdFailure.DiskFull);
+	});
+
+	it("puts a full disk ahead of a transient code in the same output", () => {
+		expect(
+			steamcmdFailureOf(
+				resultOf(
+					[
+						"Error! State is 0x602 after update job.",
+						"Error! App '2394010' state is 0x202 after update job.",
+					].join("\n"),
+				),
+			),
+		).toBe(SteamcmdFailure.DiskFull);
+	});
+});
+
+const RETRY_CASES = [
+	{
+		failure: SteamcmdFailure.DiskFull,
+		retryable: false,
+	},
+	{
+		failure: SteamcmdFailure.InvalidPlatform,
+		retryable: false,
+	},
+	{
+		failure: SteamcmdFailure.NoSubscription,
+		retryable: false,
+	},
+	{
+		failure: SteamcmdFailure.BranchPassword,
+		retryable: false,
+	},
+	{
+		failure: SteamcmdFailure.Transient,
+		retryable: true,
+	},
+	{
+		failure: SteamcmdFailure.Unknown,
+		retryable: true,
+	},
+];
+
+describe("steamcmdRetryable", () => {
+	for (const item of RETRY_CASES) {
+		it(`${item.retryable ? "retries" : "does not retry"} a ${item.failure} failure`, () => {
+			expect(steamcmdRetryable(item.failure)).toBe(item.retryable);
+		});
+	}
+});
+
 describe("steamcmdFailureText", () => {
+	it("tells the owner to free space or move up a plan when the disk is full", () => {
+		expect(steamcmdFailureText(resultOf("Error! App '258550' state is 0x202 after update job."), "rust")).toEqual({
+			ar: "امتلأت مساحة سيرفرك، فتعذّر تنزيل rust من Steam. احذف الملفات التي لا تحتاجها من صفحة الملفات أو انتقل إلى باقة أكبر، ثم جرب مرة ثانية.",
+			en: "Your server is out of space, so we couldn't download rust from Steam. Delete files you don't need on the Files page or move to a larger plan, then try again.",
+		});
+	});
+
+	it("says the branch password is wrong and where to fix it", () => {
+		expect(steamcmdFailureText(resultOf("Password check for AppId 896660"), "valheim")).toEqual({
+			ar: "كلمة مرور الفرع على Steam غير صحيحة، فتعذّر تنزيل valheim. صحّحها من الإعدادات.",
+			en: "The Steam branch password is wrong, so we couldn't download valheim. Fix it in the settings.",
+		});
+	});
+
 	it("says the download account does not own the app when steam answers no subscription", () => {
 		expect(
 			steamcmdFailureText(
@@ -186,3 +434,121 @@ describe("steamcmdFailureText", () => {
 		});
 	});
 });
+
+describe("createSteamcmd", () => {
+	it("stops at the first failure a retry cannot fix", async () => {
+		const { context, commands } = contextWith(
+			[
+				resultOf("Error! App '2394010' state is 0x202 after update job."),
+			],
+			{},
+		);
+		const steamcmd = createSteamcmd(context, OPTIONS);
+
+		await expect(
+			steamcmd.run([
+				"+app_update",
+				"2394010",
+			]),
+		).rejects.toThrow(
+			"Your server is out of space, so we couldn't download palworld from Steam. Delete files you don't need on the Files page or move to a larger plan, then try again.",
+		);
+		expect(commands.filter((command) => command[0] !== "pwd")).toHaveLength(1);
+	});
+
+	it("clears the cached app info, updates, then logs the installed build", async () => {
+		const { context, commands, logs } = contextWith([], {
+			".steamcmd": "",
+			".steam": "",
+			"steamapps/appmanifest_2394010.acf": MANIFEST,
+		});
+
+		await createSteamcmd(context, OPTIONS).update({
+			validate: false,
+		});
+
+		expect(commands).toEqual([
+			[
+				"find",
+				".steamcmd",
+				".steam",
+				"-type",
+				"f",
+				"-name",
+				"appinfo.vdf",
+				"-delete",
+			],
+			[
+				"pwd",
+			],
+			[
+				"./.steamcmd/steamcmd.sh",
+				"+force_install_dir",
+				"/home/container",
+				"+login",
+				"anonymous",
+				"+app_info_update",
+				"1",
+				"+app_update",
+				"2394010",
+				"+quit",
+			],
+		]);
+		expect(logs).toEqual([
+			{
+				message: "steamcmd finished the update",
+				fields: {
+					app: "2394010",
+					build: "19582821",
+				},
+			},
+		]);
+	});
+
+	it("skips clearing the app info when no steam directory is there yet", async () => {
+		const { context, commands, logs } = contextWith([], {});
+
+		await createSteamcmd(context, OPTIONS).update({
+			validate: false,
+		});
+
+		expect(commands.map((command) => command[0])).toEqual([
+			"pwd",
+			"./.steamcmd/steamcmd.sh",
+		]);
+		expect(logs).toEqual([
+			{
+				message: "steamcmd finished the update",
+				fields: {
+					app: "2394010",
+					build: null,
+				},
+			},
+		]);
+	});
+
+	it("updates anyway when the app info cannot be cleared", async () => {
+		const { context, commands, logs } = contextWith(
+			[
+				resultOf("find: permission denied"),
+			],
+			{
+				".steamcmd": "",
+			},
+		);
+
+		await createSteamcmd(context, OPTIONS).update({
+			validate: false,
+		});
+
+		expect(commands.map((command) => command[0])).toEqual([
+			"find",
+			"pwd",
+			"./.steamcmd/steamcmd.sh",
+		]);
+		expect(logs.map((entry) => entry.message)).toEqual([
+			"the cached steam app info could not be cleared, updating anyway",
+			"steamcmd finished the update",
+		]);
+	});
+});