@serverkgg/bridge 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.15",
+	"version": "0.0.17",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

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>;

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/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 {
+	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,12 +120,14 @@ 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[]>;
@@ -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/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/bridgeCrash.ts

@@ -0,0 +1,83 @@
+import { BridgeEventName } from "./bridgeEvents";
+
+export enum BridgeCrashCause {
+	OomKill = "oom-kill",
+	OutOfMemory = "out-of-memory",
+	WrongJavaVersion = "wrong-java",
+	PortBusy = "port-busy",
+	WorldCorrupt = "world-corrupt",
+	MissingDependency = "missing-dependency",
+	ModCrashed = "mod-crashed",
+	Unknown = "unknown",
+}
+
+export enum BridgeCrashPhase {
+	Booting = "booting",
+	Running = "running",
+}
+
+export interface BridgeCrashEvidence {
+	name: BridgeEventName;
+	cause: BridgeCrashCause;
+}
+
+export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
+	{
+		name: BridgeEventName.ServerCrashed,
+		cause: BridgeCrashCause.OutOfMemory,
+	},
+	{
+		name: BridgeEventName.WrongJavaVersion,
+		cause: BridgeCrashCause.WrongJavaVersion,
+	},
+	{
+		name: BridgeEventName.PortBindFailed,
+		cause: BridgeCrashCause.PortBusy,
+	},
+	{
+		name: BridgeEventName.WorldCorrupt,
+		cause: BridgeCrashCause.WorldCorrupt,
+	},
+	{
+		name: BridgeEventName.MissingDependency,
+		cause: BridgeCrashCause.MissingDependency,
+	},
+	{
+		name: BridgeEventName.ModCrashed,
+		cause: BridgeCrashCause.ModCrashed,
+	},
+];
+
+const BRIDGE_CRASH_EVIDENCE_NAMES: ReadonlySet<string> = new Set(BRIDGE_CRASH_EVIDENCE.map((entry) => entry.name));
+
+export const isCrashEvidence = (name: string): boolean => {
+	return BRIDGE_CRASH_EVIDENCE_NAMES.has(name);
+};
+
+export const BRIDGE_CRASH_KEYS = {
+	cause: "cause",
+	phase: "phase",
+	exitCode: "exitCode",
+	restarting: "restarting",
+	looping: "looping",
+	restarts: "restarts",
+	uptimeSeconds: "uptimeSeconds",
+	lastLine: "lastLine",
+} as const;
+
+export const BRIDGE_CRASH_FLAG_YES = "yes";
+
+export const BRIDGE_CRASH_FLAG_NO = "no";
+
+export const BRIDGE_CRASH_LINE_LIMIT = 256;
+
+export interface BridgeCrashRecord {
+	exitCode: number;
+	outOfMemory: boolean;
+	phase: BridgeCrashPhase;
+	uptimeSeconds: number;
+	restarting: boolean;
+	looping: boolean;
+	restarts: number;
+	lastLine: string | null;
+}

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 {
@@ -76,6 +79,7 @@ export interface BridgeStatus {
 	exitCode: number | null;
 	outOfMemory: boolean;
 	restarts: number;
+	crashRecords: boolean;
 	installError: string | null;
 	installErrorText: LocalizedText | null;
 	installHold: BridgeInstallHold | null;
@@ -92,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/protocol/index.ts

@@ -3,6 +3,7 @@ export * from "../panel";
 export * from "../terminal";
 export * from "./bridgeCatalog";
 export * from "./bridgeConfig";
+export * from "./bridgeCrash";
 export * from "./bridgeEgress";
 export * from "./bridgeEvents";
 export * from "./bridgeFrame";

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