@serverkgg/bridge 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.16",
+	"version": "0.0.18",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -39,6 +39,6 @@
 		"test": "bun test --parallel"
 	},
 	"dependencies": {
-		"zod": "4.5.4"
+		"zod": "4.6.4"
 	}
 }

package/src/codecs/index.ts

@@ -1,4 +1,5 @@
 export * from "./ini";
+export * from "./javaProperties";
 export * from "./json";
 export * from "./properties";
 export * from "./sourceCfg";

package/src/codecs/javaProperties.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { escapeJavaProperty, mergeJavaProperties, parseJavaProperties, unescapeJavaProperty } from "./javaProperties";
+
+const ARABIC = "سيرفرك";
+
+describe("parseJavaProperties", () => {
+	test("decodes the unicode escapes the java server writes", () => {
+		expect(parseJavaProperties("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\n")).toEqual({
+			motd: ARABIC,
+		});
+	});
+
+	test("decodes backslash escapes in values", () => {
+		expect(parseJavaProperties("resource-pack=https\\://example.com/pack.zip\nmotd=a\\tb\\\\c\n")).toEqual({
+			"resource-pack": "https://example.com/pack.zip",
+			motd: "a\tb\\c",
+		});
+	});
+
+	test("repairs a value the server stored as latin-1 bytes of utf-8", () => {
+		expect(parseJavaProperties("motd=ddss \\u00D9\\u008A\\u00D8\\u00AA\n")).toEqual({
+			motd: "ddss يت",
+		});
+	});
+
+	test("keeps plain latin-1 text that is not utf-8", () => {
+		expect(unescapeJavaProperty("caf\\u00E9")).toBe("café");
+	});
+
+	test("keeps comments and plain values", () => {
+		expect(parseJavaProperties("#Minecraft server properties\nmax-players=20\n")).toEqual({
+			"max-players": "20",
+		});
+	});
+});
+
+describe("mergeJavaProperties", () => {
+	test("writes non ascii text as unicode escapes", () => {
+		expect(
+			mergeJavaProperties("motd=A Minecraft Server\nmax-players=20\n", {
+				motd: ARABIC,
+			}),
+		).toBe("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\nmax-players=20\n");
+	});
+
+	test("escapes the characters java treats as separators", () => {
+		expect(escapeJavaProperty("https://a.b#c=d!e")).toBe("https\\://a.b\\#c\\=d\\!e");
+	});
+
+	test("escapes a leading space and control characters", () => {
+		expect(escapeJavaProperty(" a\tb\\c")).toBe("\\ a\\tb\\\\c");
+	});
+
+	test("round trips astral characters", () => {
+		const value = "hi 🎮";
+
+		expect(unescapeJavaProperty(escapeJavaProperty(value))).toBe(value);
+	});
+
+	test("appends a key the file does not have yet", () => {
+		expect(
+			mergeJavaProperties("", {
+				motd: "hello",
+			}),
+		).toBe("motd=hello\n");
+	});
+});

package/src/codecs/javaProperties.ts

@@ -0,0 +1,99 @@
+import { mergeProperties, parseProperties } from "./properties";
+
+const UNICODE_ESCAPE = /\\u([0-9A-Fa-f]{4})/g;
+
+const SIMPLE_ESCAPE = /\\(.)/g;
+
+const SIMPLE_ESCAPES: Record<string, string> = {
+	t: "\t",
+	n: "\n",
+	r: "\r",
+	f: "\f",
+};
+
+const ESCAPED_CHARACTERS: Record<string, string> = {
+	"\\": "\\\\",
+	"\t": "\\t",
+	"\n": "\\n",
+	"\r": "\\r",
+	"\f": "\\f",
+	"=": "\\=",
+	":": "\\:",
+	"#": "\\#",
+	"!": "\\!",
+};
+
+const PRINTABLE_MIN = 0x20;
+
+const PRINTABLE_MAX = 0x7e;
+
+const LATIN1_MAX = 0xff;
+
+const HEX_DIGITS = 4;
+
+const latin1Decoder = new TextDecoder("utf-8", {
+	fatal: true,
+});
+
+const repairLatin1 = (text: string) => {
+	const codes = Array.from(text, (character) => character.charCodeAt(0));
+
+	if (codes.every((code) => code <= PRINTABLE_MAX) || codes.some((code) => code > LATIN1_MAX)) {
+		return text;
+	}
+
+	try {
+		return latin1Decoder.decode(Uint8Array.from(codes));
+	} catch {
+		return text;
+	}
+};
+
+export const unescapeJavaProperty = (text: string) => {
+	const unescaped = text
+		.replace(UNICODE_ESCAPE, (_, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)))
+		.replace(SIMPLE_ESCAPE, (_, character: string) => SIMPLE_ESCAPES[character] ?? character);
+
+	return repairLatin1(unescaped);
+};
+
+export const escapeJavaProperty = (text: string) => {
+	let escaped = "";
+
+	for (const character of text) {
+		const code = character.codePointAt(0) ?? 0;
+		const known = ESCAPED_CHARACTERS[character];
+
+		if (known !== undefined) {
+			escaped += known;
+		} else if (code < PRINTABLE_MIN || code > PRINTABLE_MAX) {
+			for (let index = 0; index < character.length; index += 1) {
+				escaped += `\\u${character.charCodeAt(index).toString(16).toUpperCase().padStart(HEX_DIGITS, "0")}`;
+			}
+		} else {
+			escaped += character;
+		}
+	}
+
+	return escaped.startsWith(" ") ? `\\${escaped}` : escaped;
+};
+
+export const parseJavaProperties = (contents: string) => {
+	const values: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(parseProperties(contents))) {
+		values[unescapeJavaProperty(key)] = unescapeJavaProperty(value);
+	}
+
+	return values;
+};
+
+export const mergeJavaProperties = (contents: string, values: Record<string, string>) => {
+	const escaped: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(values)) {
+		escaped[escapeJavaProperty(key)] = escapeJavaProperty(value);
+	}
+
+	return mergeProperties(contents, escaped);
+};

package/src/context/bridgeContext.ts

@@ -27,6 +27,8 @@ export interface BridgeDownloadOptions {
 }
 
 export interface BridgeExtractOptions {
+	maxBytes?: number;
+	maxEntryBytes?: number;
 	extensions?: string[];
 	tree?: boolean;
 	select?: string;
@@ -34,10 +36,14 @@ export interface BridgeExtractOptions {
 	exclude?: string[];
 }
 
+export interface BridgeListOptions {
+	directory?: string;
+}
+
 export interface BridgeFiles {
 	read(path: string): Promise<string>;
 	write(path: string, content: string): Promise<void>;
-	list(glob: string): Promise<BridgeFileEntry[]>;
+	list(glob: string, options?: BridgeListOptions): Promise<BridgeFileEntry[]>;
 	remove(path: string): Promise<void>;
 	move(from: string, to: string): Promise<void>;
 	ensure(...paths: string[]): Promise<void>;
@@ -60,6 +66,7 @@ export interface BridgeCodec {
 
 export interface BridgeCodecs {
 	ini: BridgeCodec;
+	javaProperties: BridgeCodec;
 	json: BridgeCodec;
 	properties: BridgeCodec;
 	sourceCfg: BridgeCodec;

package/src/core/bridgeAction.ts

@@ -7,6 +7,7 @@ export enum BridgeAction {
 	Quiesce = "quiesce",
 	Read = "read",
 	Release = "release",
+	Releases = "releases",
 	Remove = "remove",
 	Sample = "sample",
 	Search = "search",
@@ -15,6 +16,7 @@ export enum BridgeAction {
 }
 
 export const BRIDGE_READ_ACTIONS: readonly string[] = [
+	BridgeAction.Releases,
 	BridgeAction.Installed,
 	BridgeAction.List,
 	BridgeAction.Preview,

package/src/modules/bridge.ts

@@ -11,6 +11,7 @@ import type {
 } from "../core";
 import { BridgeUserError } from "../core";
 import type {
+	BridgeAddOutcome,
 	BridgeDetail,
 	BridgeDetailBadge,
 	BridgeDetailLink,
@@ -72,6 +73,7 @@ import type {
 
 export namespace Bridge {
 	export type Actions = BridgeActionsModule;
+	export type AddOutcome = BridgeAddOutcome;
 	export type Announce = BridgeAnnounceModule;
 	export type Backup = BridgeBackupModule;
 	export type Catalog = BridgeCatalogModule;

package/src/modules/bridgeModule.ts

@@ -1,8 +1,13 @@
 import type { BridgeContext, BridgeReply } from "../context";
 import type { BridgeInstallOutcome, BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
-import type { BridgeDetail, BridgeDetailOutcome } from "../panel";
-import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
-import type { BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
+import type { BridgeAddOutcome, BridgeDetail, BridgeDetailOutcome } from "../panel";
+import type {
+	BridgeCatalogEntry,
+	BridgeCatalogPage,
+	BridgeCatalogQuery,
+	BridgeCatalogRelease,
+} from "../protocol/bridgeCatalog";
+import type { BridgeBackupSnapshot, BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeSetupStep } from "../protocol/bridgeSetup";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
@@ -32,7 +37,12 @@ export interface BridgeAnnounceModule {
 export interface BridgeBackupModule {
 	kind: BridgeKind.Backup;
 	settleSeconds?: number;
-	quiesce?(context: BridgeContext): Promise<void>;
+	quiesce?(context: BridgeContext): Promise<
+		| undefined
+		| {
+				snapshot?: BridgeBackupSnapshot;
+		  }
+	>;
 	release?(context: BridgeContext): Promise<void>;
 }
 
@@ -95,6 +105,7 @@ export interface BridgePreviewModule {
 
 export interface BridgeSettingsModule {
 	kind: BridgeKind.Settings;
+	protectedActions?: string[];
 	read(context: BridgeContext): Promise<BridgeValues>;
 	write?(context: BridgeContext, values: BridgeValues): Promise<void>;
 }
@@ -109,16 +120,18 @@ export type BridgeServerAction = (context: BridgeContext, args: BridgeValues) =>
 
 export interface BridgeActionsModule {
 	kind: BridgeKind.Actions;
+	protectedActions?: string[];
 	requiresRunning?: boolean;
 	actions: Record<string, BridgeServerAction>;
 }
 
 export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	kind: BridgeKind.Collection;
+	protectedActions?: string[];
 	requiresRunning?: boolean;
 	refreshSeconds?: number;
 	list(context: BridgeContext): Promise<Row[]>;
-	add?(context: BridgeContext, input: string): Promise<void>;
+	add?(context: BridgeContext, input: string): Promise<BridgeAddOutcome | undefined>;
 	actions?: Record<string, BridgeRowAction<Row>>;
 }
 
@@ -126,6 +139,7 @@ export type BridgeDetailAction = (context: BridgeContext, args: BridgeValues) =>
 
 export interface BridgeDetailModule {
 	kind: BridgeKind.Detail;
+	protectedActions?: string[];
 	requiresRunning?: boolean;
 	refreshSeconds?: number;
 	read(context: BridgeContext): Promise<BridgeDetail | null>;
@@ -134,10 +148,13 @@ export interface BridgeDetailModule {
 
 export interface BridgeCatalogModule {
 	kind: BridgeKind.Catalog;
+	protectedActions?: string[];
 	pageSize?: number;
 	search(context: BridgeContext, query: BridgeCatalogQuery): Promise<BridgeCatalogPage>;
 	installed(context: BridgeContext): Promise<BridgeCatalogEntry[]>;
-	install(context: BridgeContext, id: string): Promise<BridgeCatalogEntry>;
+	releases?(context: BridgeContext, id: string): Promise<BridgeCatalogRelease[]>;
+	preview?(context: BridgeContext, id: string, releaseId?: string): Promise<BridgePreview>;
+	install(context: BridgeContext, id: string, releaseId?: string): Promise<BridgeCatalogEntry>;
 	remove(context: BridgeContext, id: string): Promise<void>;
 	toggle?(context: BridgeContext, id: string, enabled: boolean): Promise<void>;
 }

package/src/panel/bridgeCollection.ts

@@ -0,0 +1,5 @@
+import type { LocalizedText } from "../core";
+
+export interface BridgeAddOutcome {
+	notice: LocalizedText;
+}

package/src/panel/index.ts

@@ -1,4 +1,5 @@
 export * from "./bridgeAccess";
+export * from "./bridgeCollection";
 export * from "./bridgeConfirm";
 export * from "./bridgeControl";
 export * from "./bridgeDetail";

package/src/protocol/bridgeCatalog.ts

@@ -1,5 +1,11 @@
 import type { LocalizedText } from "../core";
 
+export interface BridgeCatalogRelease {
+	id: string;
+	label: string;
+	gameVersion?: string;
+}
+
 export interface BridgeCatalogProvider {
 	id: string;
 	label: LocalizedText;

package/src/protocol/bridgeFrame.ts

@@ -44,6 +44,9 @@ export interface BridgeRequest {
 	args?: BridgeValues;
 	cursor?: number;
 	message?: string;
+	supportsSnapshot?: boolean;
+	leaseId?: string;
+	recoveryOperationId?: string;
 }
 
 export interface BridgeCommandResult {
@@ -93,10 +96,20 @@ export interface BridgeAnnounceResult {
 	delivered: boolean;
 }
 
+export interface BridgeBackupSnapshot {
+	roots: string[];
+	files: Array<{
+		path: string;
+		size: number;
+	}>;
+}
+
 export interface BridgeQuiesceResult {
+	leaseId?: string;
 	supported: boolean;
 	quiesced: boolean;
 	settleSeconds: number;
+	snapshot?: BridgeBackupSnapshot;
 }
 
 export interface BridgeDescribeResult {

package/src/protocol/bridgeManifest.ts

@@ -23,6 +23,7 @@ export interface BridgeModuleManifest {
 	pageSize: number | null;
 	dependsOn: string[];
 	actions: string[];
+	protectedActions?: string[];
 }
 
 export interface BridgeManifest {

package/src/protocol/bridgePreview.ts

@@ -2,6 +2,7 @@ import type { LocalizedText } from "../core";
 import type { BridgeConfirm } from "../panel";
 
 export interface BridgePreview {
+	variables?: Record<string, string>;
 	confirm: BridgeConfirm;
 	lines: LocalizedText[];
 }

package/src/runtime/bridgeActions.ts

@@ -51,6 +51,16 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 
 		case BridgeKind.Catalog: {
 			return [
+				...(module.releases
+					? [
+							BridgeAction.Releases,
+						]
+					: []),
+				...(module.preview
+					? [
+							BridgeAction.Preview,
+						]
+					: []),
 				BridgeAction.Install,
 				BridgeAction.Installed,
 				BridgeAction.Remove,

package/src/runtime/bridgeBackupLease.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { createBackupLease } from "./bridgeBackupLease";
+
+describe("backup save ownership", () => {
+	test("keeps a long backup frozen while renewed and releases when its owner disappears", async () => {
+		let now = 0;
+		let releases = 0;
+		const lease = createBackupLease(
+			async () => {
+				releases++;
+			},
+			() => now,
+			120,
+		);
+		const id = lease.begin();
+		for (let index = 0; index < 10; index++) {
+			now += 100;
+			lease.renew(id);
+			await lease.expire();
+		}
+		expect(releases).toBe(0);
+		now += 121;
+		expect(() => lease.renew(id)).toThrow("expired");
+		await lease.expire();
+		expect(releases).toBe(1);
+		expect(lease.active).toBe(false);
+	});
+	test("refuses overlapping holds and retains ownership after a failed resume", async () => {
+		let fail = true;
+		const lease = createBackupLease(async () => {
+			if (fail) {
+				throw new Error("resume failed");
+			}
+		});
+		const owner = lease.begin();
+		expect(() => lease.begin()).toThrow("already owns");
+		expect(() => lease.renew("another-owner")).toThrow();
+		await expect(lease.finish(owner)).rejects.toThrow("resume failed");
+		expect(lease.active).toBe(true);
+		fail = false;
+		await lease.finish(owner);
+		expect(lease.active).toBe(false);
+	});
+});
+
+test("reserves ownership while the quiesce operation is still awaiting confirmation", async () => {
+	const prepared = Promise.withResolvers<void>();
+	const lease = createBackupLease(async () => {});
+	const owner = lease.begin();
+	const operation = lease.prepare(owner, () => prepared.promise);
+	expect(() => lease.begin()).toThrow("already owns");
+	expect(() => lease.renew(owner)).toThrow("not ready");
+	await expect(lease.finish("competitor")).rejects.toThrow("owner");
+	await expect(lease.finish()).rejects.toThrow("owner");
+	prepared.resolve();
+	await operation;
+	expect(lease.renew(owner)).toBe(owner);
+	await lease.finish(owner);
+});
+
+test("expiration waits for in-flight preparation before resuming saves", async () => {
+	let now = 0;
+	let releases = 0;
+	const prepared = Promise.withResolvers<void>();
+	const lease = createBackupLease(
+		async () => {
+			releases++;
+		},
+		() => now,
+		10,
+	);
+	const owner = lease.begin();
+	const operation = lease.prepare(owner, () => prepared.promise);
+	now = 11;
+	const expired = lease.expire();
+	await Promise.resolve();
+	expect(releases).toBe(0);
+	expect(() => lease.begin()).toThrow();
+	prepared.resolve();
+	await operation;
+	await expired;
+	expect(releases).toBe(1);
+	expect(lease.active).toBe(false);
+});
+
+test("late releases and tokenless callers cannot release a newer owner", async () => {
+	let releases = 0;
+	const lease = createBackupLease(async () => {
+		releases++;
+	});
+	const first = lease.begin();
+	await lease.finish(first);
+	const second = lease.begin();
+	await expect(lease.finish(first)).rejects.toThrow("owner");
+	await expect(lease.finish()).rejects.toThrow("owner");
+	expect(releases).toBe(1);
+	expect(lease.active).toBe(true);
+	await lease.finish(second);
+	expect(releases).toBe(2);
+});
+
+test("legacy release is accepted only for a legacy hold", async () => {
+	let releases = 0;
+	const lease = createBackupLease(async () => {
+		releases++;
+	});
+	lease.begin(true);
+	await lease.finish();
+	expect(releases).toBe(1);
+	await lease.finish();
+	expect(releases).toBe(1);
+});
+
+test("failed quiesce cleanup keeps the owner until resume succeeds", async () => {
+	let releases = 0;
+	const lease = createBackupLease(async () => {
+		releases++;
+	});
+	const owner = lease.begin();
+	await expect(
+		lease.prepare(owner, async () => {
+			throw new Error("quiesce failed");
+		}),
+	).rejects.toThrow();
+	await lease.finish(owner);
+	expect(releases).toBe(1);
+	expect(lease.active).toBe(false);
+});
+
+test("legacy owners retain the historical hold until explicit release without renewal", async () => {
+	let now = 0;
+	let releases = 0;
+	const lease = createBackupLease(
+		async () => {
+			releases++;
+		},
+		() => now,
+		120,
+	);
+	lease.begin(true);
+	now = 120_000;
+	await lease.expire();
+	expect(lease.active).toBe(true);
+	expect(releases).toBe(0);
+	await lease.finish();
+	expect(releases).toBe(1);
+	expect(lease.active).toBe(false);
+});

package/src/runtime/bridgeBackupLease.ts

@@ -0,0 +1,74 @@
+export const createBackupLease = (
+	release: () => Promise<void>,
+	now: () => number = () => performance.now(),
+	ttlMs = 120_000,
+) => {
+	let id: string | null = null;
+	let legacy = false;
+	let deadline = 0;
+	let preparing: Promise<unknown> | null = null;
+	let releasing: Promise<void> | null = null;
+	const finish = async (token?: string) => {
+		if (id === null) {
+			return;
+		}
+		if (token !== id && !(token === undefined && legacy)) {
+			throw new Error("only the backup save lease owner can release it");
+		}
+		if (releasing) {
+			return await releasing;
+		}
+		releasing = Promise.resolve()
+			.then(async () => {
+				await preparing?.catch(() => undefined);
+				await release();
+				id = null;
+				legacy = false;
+			})
+			.finally(() => {
+				releasing = null;
+			});
+		await releasing;
+	};
+	return {
+		get active() {
+			return id !== null;
+		},
+		begin(legacyOwner = false) {
+			if (id !== null) {
+				throw new Error("a backup already owns the save hold");
+			}
+			id = crypto.randomUUID();
+			legacy = legacyOwner;
+			deadline = now() + ttlMs;
+			return id;
+		},
+		async prepare<Result>(token: string, run: () => Promise<Result>): Promise<Result> {
+			if (id !== token || releasing || preparing) {
+				throw new Error("the backup save lease is not available for preparation");
+			}
+			const operation = Promise.resolve().then(run);
+			preparing = operation;
+			try {
+				return await operation;
+			} finally {
+				if (preparing === operation) {
+					preparing = null;
+				}
+			}
+		},
+		renew(token: string) {
+			if (id !== token || now() >= deadline || releasing || preparing) {
+				throw new Error("the backup save lease expired or is not ready");
+			}
+			deadline = now() + ttlMs;
+			return token;
+		},
+		finish,
+		async expire() {
+			if (id !== null && !legacy && now() >= deadline) {
+				await finish(id);
+			}
+		},
+	};
+};

package/src/runtime/bridgeCodec.ts

@@ -1,11 +1,13 @@
 import {
 	mergeIni,
+	mergeJavaProperties,
 	mergeJson,
 	mergeProperties,
 	mergeSourceCfg,
 	mergeUeIni,
 	mergeXmlProperties,
 	parseIni,
+	parseJavaProperties,
 	parseJson,
 	parseProperties,
 	parseSourceCfg,
@@ -61,6 +63,15 @@ export const createBridgeCodecs = (files: BridgeFiles): BridgeCodecs => {
 		},
 	};
 
+	const javaProperties: BridgeCodec = {
+		async read(path) {
+			return widen(parseJavaProperties(await readOr(files, path)));
+		},
+		async merge(path, values) {
+			await files.write(path, mergeJavaProperties(await readOr(files, path), toStrings(values)));
+		},
+	};
+
 	const json: BridgeCodec = {
 		async read(path) {
 			return parseJson(await readOr(files, path));
@@ -112,6 +123,7 @@ export const createBridgeCodecs = (files: BridgeFiles): BridgeCodecs => {
 
 	return {
 		ini,
+		javaProperties,
 		json,
 		properties,
 		sourceCfg,