@serverkgg/bridge 0.0.7 → 0.0.9

package/src/panel/bridgePanel.ts

@@ -5,6 +5,7 @@ import type { BridgeControl } from "./bridgeControl";
 import type { BridgeFormTarget } from "./bridgeFormTarget";
 import type { BridgeIcon } from "./bridgeIcon";
 import type { BridgeLayout } from "./bridgeLayout";
+import type { BridgeUploadMode } from "./bridgeUploadMode";
 
 export interface BridgeVisibleWhen {
 	variable: string;
@@ -44,6 +45,16 @@ export interface BridgeSectionAction {
 	fields?: BridgeField[];
 }
 
+export interface BridgeTabRef {
+	tab: string;
+	label: LocalizedText;
+}
+
+export interface BridgeFormClear {
+	variable: string;
+	warning: LocalizedText;
+}
+
 export interface BridgeSectionAdd {
 	label: LocalizedText;
 	placeholder?: string;
@@ -53,6 +64,7 @@ export interface BridgeSectionUpload {
 	label: LocalizedText;
 	extensions: string[];
 	staging: string;
+	mode?: BridgeUploadMode;
 }
 
 export interface BridgeActionsSection {
@@ -78,6 +90,7 @@ export interface BridgeFormSection {
 	confirm?: BridgeConfirm;
 	confirmText?: LocalizedText;
 	fields: BridgeField[];
+	clears?: BridgeFormClear[];
 	visibleWhen?: BridgeVisibleWhen;
 	access?: BridgeAccess;
 }
@@ -130,10 +143,27 @@ export interface BridgeCatalogSection {
 	access?: BridgeAccess;
 }
 
+export interface BridgeDetailSection {
+	layout: BridgeLayout.Detail;
+	id: string;
+	title?: LocalizedText;
+	module: string;
+	actions?: BridgeSectionAction[];
+	reinstall?: boolean;
+	variable?: string;
+	confirm?: BridgeConfirm;
+	confirmText?: LocalizedText;
+	related?: BridgeTabRef;
+	empty?: LocalizedText;
+	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
+}
+
 export type BridgeSection =
 	| BridgeActionsSection
 	| BridgeCardsSection
 	| BridgeCatalogSection
+	| BridgeDetailSection
 	| BridgeFormSection
 	| BridgeTableSection;
 

package/src/panel/bridgeUploadMode.ts

@@ -0,0 +1,4 @@
+export enum BridgeUploadMode {
+	Archive = "archive",
+	File = "file",
+}

package/src/panel/index.ts

@@ -1,7 +1,9 @@
 export * from "./bridgeAccess";
 export * from "./bridgeConfirm";
 export * from "./bridgeControl";
+export * from "./bridgeDetail";
 export * from "./bridgeFormTarget";
 export * from "./bridgeIcon";
 export * from "./bridgeLayout";
 export * from "./bridgePanel";
+export * from "./bridgeUploadMode";

package/src/protocol/bridgeEgress.ts

@@ -4,18 +4,25 @@ export const BRIDGE_EGRESS_FRAME_LIMIT = 16 * 1024 * 1024;
 
 export const BRIDGE_EGRESS_BODY_LIMIT = 8 * 1024 * 1024;
 
-export const BRIDGE_EGRESS_DOWNLOAD_LIMIT = 512 * 1024 * 1024;
+export const BRIDGE_EGRESS_DOWNLOAD_LIMIT = 2 * 1024 * 1024 * 1024;
 
 export enum BridgeEgressMethod {
 	Fetch = "fetch",
 	Download = "download",
 }
 
+export enum BridgeHttpMethod {
+	Get = "GET",
+	Post = "POST",
+}
+
 export interface BridgeEgressRequest {
 	id: number;
 	token: string;
 	method: BridgeEgressMethod;
 	url: string;
+	httpMethod?: BridgeHttpMethod;
+	body?: string;
 	headers?: Record<string, string>;
 	timeoutMs?: number;
 	cache?: boolean;

package/src/protocol/bridgeEvents.ts

@@ -1,6 +1,10 @@
 export enum BridgeEventName {
 	GameModeChanged = "GameModeChanged",
+	MemoryUndersized = "MemoryUndersized",
 	MissingDependency = "MissingDependency",
+	ModCrashed = "ModCrashed",
+	PlayerAdvanced = "PlayerAdvanced",
+	PlayerDied = "PlayerDied",
 	PlayerJoined = "PlayerJoined",
 	PlayerLeft = "PlayerLeft",
 	PortBindFailed = "PortBindFailed",

package/src/protocol/bridgeFrame.ts

@@ -1,4 +1,4 @@
-import type { BridgeDesired, BridgeRuntime, BridgeValues } from "../core";
+import type { BridgeDesired, BridgeInstallHold, BridgeRuntime, BridgeValues, LocalizedText } from "../core";
 
 export const BRIDGE_SOCKET_NAME = "bridge.sock";
 
@@ -19,6 +19,8 @@ export enum BridgeMethod {
 	Events = "events",
 	Invoke = "invoke",
 	Manifest = "manifest",
+	PendingAdd = "pendingAdd",
+	PendingList = "pendingList",
 	Quiesce = "quiesce",
 	Release = "release",
 	Sample = "sample",
@@ -59,6 +61,7 @@ export interface BridgeFailure {
 	error: string;
 	secret?: string;
 	failure?: string;
+	text?: LocalizedText;
 }
 
 export type BridgeResponse = BridgeFailure | BridgeSuccess;
@@ -68,8 +71,10 @@ export interface BridgeStatus {
 	runtime: BridgeRuntime;
 	desired: BridgeDesired;
 	exitCode: number | null;
+	outOfMemory: boolean;
 	restarts: number;
 	installError: string | null;
+	installHold: BridgeInstallHold | null;
 }
 
 export interface BridgeSampleResult {
@@ -95,6 +100,28 @@ export interface BridgeDescribeResult {
 	build: string | null;
 }
 
+export interface BridgePendingFile {
+	id: string;
+	title: LocalizedText;
+	fileName: string;
+	sizeBytes: number | null;
+	digest: string | null;
+	sourceUrl: string | null;
+	note: LocalizedText | null;
+}
+
+export interface BridgePendingRejection {
+	expected: string[];
+}
+
+export interface BridgePendingResult {
+	supported: boolean;
+	staging: string;
+	extensions: string[];
+	files: BridgePendingFile[];
+	rejected: BridgePendingRejection | null;
+}
+
 export interface BridgeEvent {
 	seq: number;
 	event: string;

package/src/protocol/bridgeLimits.ts

@@ -18,6 +18,14 @@ export const BRIDGE_VISIBLE_VALUES_LIMIT = 16;
 
 export const BRIDGE_PREVIEW_LINES_LIMIT = 8;
 
+export const BRIDGE_DETAIL_STATS_LIMIT = 12;
+
+export const BRIDGE_DETAIL_BADGES_LIMIT = 4;
+
+export const BRIDGE_DETAIL_LINKS_LIMIT = 4;
+
+export const BRIDGE_FORM_CLEARS_LIMIT = 8;
+
 export const BRIDGE_UPLOAD_EXTENSIONS_LIMIT = 8;
 
 export const BRIDGE_MODULES_LIMIT = 32;
@@ -28,6 +36,8 @@ export const BRIDGE_DEPENDS_ON_LIMIT = 8;
 
 export const BRIDGE_EVENTS_LIMIT = 32;
 
+export const BRIDGE_PENDING_FILES_LIMIT = 64;
+
 export const BRIDGE_ID_LENGTH_LIMIT = 32;
 
 export const BRIDGE_KEY_LENGTH_LIMIT = 64;

package/src/runtime/bridgeActions.ts

@@ -42,6 +42,13 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 			];
 		}
 
+		case BridgeKind.Detail: {
+			return [
+				BridgeAction.Read,
+				...Object.keys(module.actions ?? {}),
+			];
+		}
+
 		case BridgeKind.Catalog: {
 			return [
 				BridgeAction.Install,

package/src/runtime/bridgeDriver.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { BridgeKind, PortJoin, PortProtocol } from "../core";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
-import type { BridgeDriver } from "../modules";
+import type { BridgeDriver, BridgePendingModule } from "../modules";
 import {
 	BridgeConfirm,
 	BridgeControl,
@@ -9,6 +9,8 @@ import {
 	BridgeFormTarget,
 	BridgeLayout,
 	type BridgeSectionAction,
+	type BridgeSectionUpload,
+	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
 import { validateDriver, validatePortActivation } from "./bridgeDriver";
@@ -647,6 +649,479 @@ describe("validatePortActivation", () => {
 				],
 				driverWithVariables(),
 			),
-		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form or catalog declares');
+		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form, catalog or detail declares');
+	});
+});
+
+const driverWithDetail = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	modules: {
+		modpackStatus: {
+			kind: BridgeKind.Detail,
+			read: async () => null,
+			actions: {
+				update: async () => null,
+			},
+		},
+	},
+	panel: {
+		tabs: [
+			{
+				id: "version",
+				title: text("Version"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "version",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field("MC_VERSION"),
+						],
+						clears: [
+							{
+								variable: "MODPACK",
+								warning: text("Applying this removes the modpack"),
+							},
+						],
+					},
+					{
+						layout: BridgeLayout.Detail,
+						id: "modpack-status",
+						module: "modpackStatus",
+						variable: "MODPACK",
+						reinstall: true,
+						related: {
+							tab: "modpacks",
+							label: text("Browse modpacks"),
+						},
+						actions: [
+							{
+								id: "update",
+								label: text("Update"),
+							},
+						],
+					},
+				],
+			},
+			{
+				id: "modpacks",
+				title: text("Modpacks"),
+				sections: [
+					{
+						layout: BridgeLayout.Actions,
+						id: "noop",
+						module: "noop",
+						actions: [
+							{
+								id: "ping",
+								label: text("Ping"),
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+});
+
+const withNoop = (driver: BridgeDriver): BridgeDriver => ({
+	...driver,
+	modules: {
+		...driver.modules,
+		noop: {
+			kind: BridgeKind.Actions,
+			actions: {
+				ping: async () => {
+					return;
+				},
+			},
+		},
+	},
+});
+
+const detailSectionOf = (driver: BridgeDriver) => {
+	const section = driver.panel?.tabs[0]?.sections[1];
+
+	if (section?.layout !== BridgeLayout.Detail) {
+		throw new Error("fixture is missing its detail section");
+	}
+
+	return section;
+};
+
+const clearingFormOf = (driver: BridgeDriver) => {
+	const section = driver.panel?.tabs[0]?.sections[0];
+
+	if (section?.layout !== BridgeLayout.Form) {
+		throw new Error("fixture is missing its form section");
+	}
+
+	return section;
+};
+
+describe("detail sections", () => {
+	test("accepts a detail section on a detail module", () => {
+		expect(() => validateDriver(withNoop(driverWithDetail()))).not.toThrow();
+	});
+
+	test("rejects a section pointing at a module that is not a detail module", () => {
+		const driver = withNoop(driverWithDetail());
+
+		driver.modules = {
+			...driver.modules,
+			modpackStatus: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow('references "modpackStatus", which is not a detail module');
+	});
+
+	test("rejects an action the module does not implement", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).actions = [
+			{
+				id: "reinstall",
+				label: text("Reinstall"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow(
+			'declares action "reinstall", which module "modpackStatus" does not implement',
+		);
+	});
+
+	test("rejects a download action, since a detail has no rows to serve", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).actions = [
+			{
+				id: "update",
+				label: text("Update"),
+				download: true,
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow('declares action "update" as a download');
+	});
+
+	test("rejects a related tab the panel does not declare", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).related = {
+			tab: "worlds",
+			label: text("Worlds"),
+		};
+
+		expect(() => validateDriver(driver)).toThrow('relates to tab "worlds", which the panel does not declare');
+	});
+
+	test("counts a detail variable as declared for port activation", () => {
+		expect(() =>
+			validatePortActivation(
+				[
+					port([
+						{
+							variable: "MODPACK",
+							empty: false,
+						},
+					]),
+				],
+				driverWithDetail(),
+			),
+		).not.toThrow();
+	});
+});
+
+describe("form clears", () => {
+	test("accepts a clear of a variable a detail section declares", () => {
+		expect(() => validateDriver(withNoop(driverWithDetail()))).not.toThrow();
+	});
+
+	test("rejects a clear of a variable nothing declares", () => {
+		const driver = withNoop(driverWithDetail());
+
+		clearingFormOf(driver).clears = [
+			{
+				variable: "CROSSPLAY",
+				warning: text("Applying this turns crossplay off"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow(
+			'clears "CROSSPLAY", which no variables form, catalog or detail declares',
+		);
+	});
+
+	test("rejects a clear of one of the form's own fields", () => {
+		const driver = withNoop(driverWithDetail());
+
+		clearingFormOf(driver).clears = [
+			{
+				variable: "MC_VERSION",
+				warning: text("Applying this resets the version"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow('clears "MC_VERSION", which is one of its own fields');
+	});
+
+	test("rejects clears on a form that writes settings", () => {
+		const driver = withNoop(driverWithDetail());
+		const form = clearingFormOf(driver);
+
+		form.target = BridgeFormTarget.Settings;
+		form.module = "config";
+
+		driver.modules = {
+			...driver.modules,
+			config: {
+				kind: BridgeKind.Settings,
+				read: async () => ({}),
+				write: async () => {
+					return;
+				},
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow("clears variables but does not target variables");
+	});
+});
+
+describe("table uploads", () => {
+	const driverWithUpload = (upload: BridgeSectionUpload): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules: {
+			modpackPending: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+				add: async () => {
+					return;
+				},
+			},
+		},
+		panel: {
+			tabs: [
+				{
+					id: "modpacks",
+					title: text("Modpacks"),
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "pending",
+							module: "modpackPending",
+							columns: [
+								{
+									key: "name",
+									label: text("Name"),
+								},
+							],
+							upload,
+						},
+					],
+				},
+			],
+		},
+	});
+
+	const upload = (mode?: BridgeUploadMode): BridgeSectionUpload => ({
+		label: text("Upload"),
+		extensions: [
+			"jar",
+		],
+		staging: ".serverk-staging/pending-upload",
+		mode,
+	});
+
+	test("accepts an upload that declares no mode", () => {
+		expect(() => validateDriver(driverWithUpload(upload()))).not.toThrow();
+	});
+
+	test("accepts both declared upload modes", () => {
+		expect(() => validateDriver(driverWithUpload(upload(BridgeUploadMode.Archive)))).not.toThrow();
+		expect(() => validateDriver(driverWithUpload(upload(BridgeUploadMode.File)))).not.toThrow();
+	});
+
+	test("rejects an upload mode the platform does not know", () => {
+		const section = upload("stream" as BridgeUploadMode);
+
+		expect(() => validateDriver(driverWithUpload(section))).toThrow('declares an unknown upload mode "stream"');
+	});
+});
+
+describe("the pending module", () => {
+	const driverWithPending = (pending: BridgePendingModule): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		pending,
+	});
+
+	const pendingWith = (overrides: Partial<BridgePendingModule>): BridgePendingModule => ({
+		kind: BridgeKind.Pending,
+		staging: ".serverk-staging/pending-upload",
+		extensions: [
+			"jar",
+		],
+		list: async () => [],
+		add: async () => {
+			return;
+		},
+		...overrides,
+	});
+
+	test("accepts a driver that declares no pending module", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+			}),
+		).not.toThrow();
+	});
+
+	test("accepts a pending module declaring a staging path and one extension", () => {
+		expect(() => validateDriver(driverWithPending(pendingWith({})))).not.toThrow();
+	});
+
+	test("rejects a pending module carrying another kind", () => {
+		const pending = pendingWith({
+			kind: BridgeKind.Collection as BridgeKind.Pending,
+		});
+
+		expect(() => validateDriver(driverWithPending(pending))).toThrow(
+			'the pending module declares kind "collection", which is not "pending"',
+		);
+	});
+
+	test("rejects a pending module with no staging path", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						staging: "",
+					}),
+				),
+			),
+		).toThrow("the pending module declares no staging path");
+	});
+
+	test("rejects a staging path longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						staging: "x".repeat(129),
+					}),
+				),
+			),
+		).toThrow("the pending module staging path is 129 characters — the platform takes at most 128");
+	});
+
+	test("rejects a pending module declaring no extensions", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: [],
+					}),
+				),
+			),
+		).toThrow("the pending module declares no extensions");
+	});
+
+	test("rejects more extensions than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: Array.from({
+							length: 9,
+						}).map((_entry, index) => `e${index}`),
+					}),
+				),
+			),
+		).toThrow("the pending module declares 9 extensions — the platform takes at most 8");
+	});
+
+	test("rejects an extension longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: [
+							"x".repeat(17),
+						],
+					}),
+				),
+			),
+		).toThrow('the pending module extension "xxxxxxxxxxxxxxxxx" is 17 characters — the platform takes at most 16');
+	});
+
+	test("reserves the pending module id for the singleton", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+				modules: {
+					pending: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+					},
+				},
+			}),
+		).toThrow('module id "pending" is reserved');
 	});
 });