@serverkgg/bridge 0.0.1 → 0.0.2

package/src/modules/bridgeModule.ts

@@ -1,9 +1,15 @@
 import type { BridgeContext } from "../context";
-import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
+import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues, LocalizedText } from "../core";
+import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
+import type { BridgeDescribeResult } from "../protocol/bridgeFrame";
+import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
+
+export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
 
 export interface BridgeInstallModule {
 	kind: BridgeKind.Install;
 	run(context: BridgeContext): Promise<void>;
+	describe?(context: BridgeContext): Promise<BridgeDescription>;
 }
 
 export interface BridgeLifecycleModule {
@@ -15,6 +21,11 @@ export interface BridgeLifecycleModule {
 	onReady?(context: BridgeContext): Promise<void>;
 }
 
+export interface BridgeAnnounceModule {
+	kind: BridgeKind.Announce;
+	announce(context: BridgeContext, message: LocalizedText): Promise<void>;
+}
+
 export interface BridgeBackupModule {
 	kind: BridgeKind.Backup;
 	settleSeconds?: number;
@@ -44,6 +55,12 @@ export interface BridgeEventsModule {
 	patterns: BridgeEventPattern[];
 }
 
+export interface BridgeTerminalModule {
+	kind: BridgeKind.Terminal;
+	commands: BridgeTerminalCommand[];
+	rules?: BridgeTerminalRule[];
+}
+
 export interface BridgeOptionsModule {
 	kind: BridgeKind.Options;
 	dependsOn?: string[];
@@ -68,35 +85,14 @@ export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	actions?: Record<string, BridgeRowAction<Row>>;
 }
 
-export interface BridgeCatalogHit {
-	id: string;
-	title: string;
-	description: string;
-	icon: string | null;
-	downloads: number;
-	pageUrl?: string | null;
-}
-
-export interface BridgeCatalogPage {
-	hits: BridgeCatalogHit[];
-	total: number;
-}
-
-export interface BridgeCatalogEntry {
-	id: string;
-	path: string;
-	title: string;
-	version: string | null;
-	sizeBytes: number;
-}
-
 export interface BridgeCatalogModule {
 	kind: BridgeKind.Catalog;
 	pageSize?: number;
-	search(context: BridgeContext, query: string, page: number): Promise<BridgeCatalogPage>;
+	search(context: BridgeContext, query: BridgeCatalogQuery): Promise<BridgeCatalogPage>;
 	installed(context: BridgeContext): Promise<BridgeCatalogEntry[]>;
 	install(context: BridgeContext, id: string): Promise<BridgeCatalogEntry>;
 	remove(context: BridgeContext, id: string): Promise<void>;
+	toggle?(context: BridgeContext, id: string, enabled: boolean): Promise<void>;
 }
 
 export type BridgePanelModule =
@@ -106,7 +102,9 @@ export type BridgePanelModule =
 	| BridgeSettingsModule;
 
 export type BridgeModule =
+	| BridgeAnnounceModule
 	| BridgeBackupModule
+	| BridgeTerminalModule
 	| BridgeEventsModule
 	| BridgeInstallModule
 	| BridgeLifecycleModule

package/src/panel/bridgeAccess.ts

@@ -0,0 +1,3 @@
+export enum BridgeAccess {
+	Invoke = "invoke",
+}

package/src/panel/bridgePanel.ts

@@ -1,4 +1,5 @@
 import type { BridgeOption, LocalizedText } from "../core";
+import type { BridgeAccess } from "./bridgeAccess";
 import type { BridgeConfirm } from "./bridgeConfirm";
 import type { BridgeControl } from "./bridgeControl";
 import type { BridgeFormTarget } from "./bridgeFormTarget";
@@ -52,6 +53,7 @@ export interface BridgeFormSection {
 	confirmText?: LocalizedText;
 	fields: BridgeField[];
 	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
 }
 
 export interface BridgeColumn {
@@ -69,6 +71,7 @@ export interface BridgeTableSection {
 	actions?: BridgeSectionAction[];
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
 }
 
 export interface BridgeCardsSection {
@@ -81,6 +84,7 @@ export interface BridgeCardsSection {
 	actions?: BridgeSectionAction[];
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
 }
 
 export interface BridgeCatalogSection {
@@ -91,6 +95,7 @@ export interface BridgeCatalogSection {
 	restartHint?: boolean;
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
 }
 
 export type BridgeSection = BridgeCardsSection | BridgeCatalogSection | BridgeFormSection | BridgeTableSection;
@@ -100,6 +105,7 @@ export interface BridgeTab {
 	title: LocalizedText;
 	icon?: BridgeIcon;
 	sections: BridgeSection[];
+	access?: BridgeAccess;
 }
 
 export interface BridgePanel {

package/src/panel/index.ts

@@ -1,3 +1,4 @@
+export * from "./bridgeAccess";
 export * from "./bridgeConfirm";
 export * from "./bridgeControl";
 export * from "./bridgeFormTarget";

package/src/protocol/bridgeCatalog.ts

@@ -0,0 +1,56 @@
+import type { LocalizedText } from "../core";
+
+export interface BridgeCatalogProvider {
+	id: string;
+	label: LocalizedText;
+	ready: boolean;
+	note?: LocalizedText;
+}
+
+export interface BridgeCatalogFacet {
+	value: string;
+	label: LocalizedText;
+}
+
+export interface BridgeCatalogHit {
+	id: string;
+	provider: string;
+	title: string;
+	description: string;
+	icon: string | null;
+	downloads: number;
+	author: string | null;
+	categories: string[];
+	updatedAt: string | null;
+	pageUrl: string | null;
+}
+
+export interface BridgeCatalogPage {
+	hits: BridgeCatalogHit[];
+	total: number;
+	providers: BridgeCatalogProvider[];
+	categories: BridgeCatalogFacet[];
+	sorts: BridgeCatalogFacet[];
+}
+
+export interface BridgeCatalogEntry {
+	id: string;
+	provider: string | null;
+	path: string;
+	title: string;
+	version: string | null;
+	sizeBytes: number;
+	enabled: boolean;
+	gameVersion: string | null;
+	stale: boolean;
+	pageUrl: string | null;
+	icon: string | null;
+}
+
+export interface BridgeCatalogQuery {
+	query: string;
+	page: number;
+	provider: string | null;
+	category: string | null;
+	sort: string | null;
+}

package/src/protocol/bridgeEgress.ts

@@ -0,0 +1,53 @@
+export const BRIDGE_EGRESS_SOCKET_NAME = "egress.sock";
+
+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 enum BridgeEgressMethod {
+	Fetch = "fetch",
+	Download = "download",
+}
+
+export interface BridgeEgressRequest {
+	id: number;
+	token: string;
+	method: BridgeEgressMethod;
+	url: string;
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	cache?: boolean;
+	cacheSeconds?: number;
+	refresh?: boolean;
+	digest?: string;
+	sizeBytes?: number;
+}
+
+export interface BridgeEgressFetchResult {
+	status: number;
+	body: string;
+	fromCache: boolean;
+}
+
+export interface BridgeEgressDownloadResult {
+	status: number;
+	sizeBytes: number;
+	fromCache: boolean;
+}
+
+export interface BridgeEgressSuccess<Result> {
+	id: number | null;
+	ok: true;
+	result: Result;
+}
+
+export interface BridgeEgressFailure {
+	id: number | null;
+	ok: false;
+	error: string;
+	status: number | null;
+}
+
+export type BridgeEgressResponse<Result> = BridgeEgressFailure | BridgeEgressSuccess<Result>;

package/src/protocol/bridgeFrame.ts

@@ -1,4 +1,4 @@
-import type { BridgeDesired, BridgeRuntime, BridgeValues } from "../core";
+import type { BridgeDesired, BridgeRuntime, BridgeValues, LocalizedText } from "../core";
 
 export const BRIDGE_SOCKET_NAME = "bridge.sock";
 
@@ -13,7 +13,9 @@ export const BRIDGE_FRAME_LIMIT = 1024 * 1024;
 export const BRIDGE_INSTALL_ERROR_LIMIT = 2048;
 
 export enum BridgeMethod {
+	Announce = "announce",
 	Command = "command",
+	Describe = "describe",
 	Events = "events",
 	Invoke = "invoke",
 	Manifest = "manifest",
@@ -36,6 +38,7 @@ export interface BridgeRequest {
 	action?: string;
 	args?: BridgeValues;
 	cursor?: number;
+	message?: LocalizedText;
 }
 
 export interface BridgeCommandResult {
@@ -55,6 +58,7 @@ export interface BridgeFailure {
 	ok: false;
 	error: string;
 	secret?: string;
+	failure?: string;
 }
 
 export type BridgeResponse = BridgeFailure | BridgeSuccess;
@@ -73,12 +77,24 @@ export interface BridgeSampleResult {
 	max: number | null;
 }
 
+export interface BridgeAnnounceResult {
+	supported: boolean;
+	delivered: boolean;
+}
+
 export interface BridgeQuiesceResult {
 	supported: boolean;
 	quiesced: boolean;
 	settleSeconds: number;
 }
 
+export interface BridgeDescribeResult {
+	supported: boolean;
+	version: string | null;
+	variant: string | null;
+	build: string | null;
+}
+
 export interface BridgeEvent {
 	seq: number;
 	event: string;

package/src/protocol/bridgeLine.ts

@@ -1,10 +1,31 @@
+import { BridgeTerminalLevel } from "../terminal";
+
 export const BRIDGE_LOG_SOURCE = "bridge";
 
+const FIELD_LIMIT = 16;
+
+const FIELD_KEY_LIMIT = 64;
+
+const FIELD_VALUE_LIMIT = 512;
+
 export interface BridgeLogLine {
+	level: BridgeTerminalLevel;
 	message: string;
-	text: string;
+	fields: Record<string, string>;
 }
 
+const LEVELS = new Set<string>(Object.values(BridgeTerminalLevel));
+
+const levelOf = (value: unknown): BridgeTerminalLevel => {
+	return typeof value === "string" && LEVELS.has(value) ? (value as BridgeTerminalLevel) : BridgeTerminalLevel.Info;
+};
+
+const textOf = (value: unknown) => {
+	const text = typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+
+	return text.slice(0, FIELD_VALUE_LIMIT);
+};
+
 export const parseBridgeLine = (line: string): BridgeLogLine | null => {
 	if (!line.startsWith("{") || !line.endsWith("}")) {
 		return null;
@@ -28,13 +49,27 @@ export const parseBridgeLine = (line: string): BridgeLogLine | null => {
 		return null;
 	}
 
-	const fields = Object.entries(entry)
-		.filter(([key]) => key !== "source" && key !== "message")
-		.map(([key, value]) => `${key}=${typeof value === "object" ? JSON.stringify(value) : String(value)}`)
-		.join(" ");
+	const fields: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(entry)) {
+		if (key === "source" || key === "message" || key === "level" || key === "driver") {
+			continue;
+		}
+
+		if (key.length > FIELD_KEY_LIMIT) {
+			continue;
+		}
+
+		if (Object.keys(fields).length >= FIELD_LIMIT) {
+			break;
+		}
+
+		fields[key] = textOf(value);
+	}
 
 	return {
+		level: levelOf(entry.level),
 		message: entry.message,
-		text: fields.length > 0 ? `${entry.message} ${fields}` : entry.message,
+		fields,
 	};
 };

package/src/protocol/bridgeManifest.ts

@@ -1,5 +1,18 @@
-import type { BridgeKind } from "../core";
+import type { BridgeKind, BridgeStream } from "../core";
 import type { BridgePanel } from "../panel";
+import type { BridgeTerminalCommand, BridgeTerminalLevel } from "../terminal";
+
+export interface BridgeTerminalRuleManifest {
+	match: string;
+	flags: string;
+	level: BridgeTerminalLevel;
+	stream?: BridgeStream;
+}
+
+export interface BridgeTerminalManifest {
+	commands: BridgeTerminalCommand[];
+	rules: BridgeTerminalRuleManifest[];
+}
 
 export interface BridgeModuleManifest {
 	id: string;
@@ -14,6 +27,7 @@ export interface BridgeModuleManifest {
 export interface BridgeManifest {
 	version: string;
 	panel: BridgePanel | null;
+	terminal: BridgeTerminalManifest | null;
 	modules: BridgeModuleManifest[];
 	events: string[];
 }

package/src/protocol/bridgeVersion.ts

@@ -1,4 +1,4 @@
-import pkg from "../../package.json";
+import pkg from "../../package.json" with { type: "json" };
 
 export const BRIDGE_VERSION: string = pkg.version;
 

package/src/protocol/index.ts

@@ -1,6 +1,9 @@
 export * from "../core";
 export * from "../panel";
+export * from "../terminal";
+export * from "./bridgeCatalog";
 export * from "./bridgeConfig";
+export * from "./bridgeEgress";
 export * from "./bridgeFrame";
 export * from "./bridgeLine";
 export * from "./bridgeManifest";

package/src/runtime/bridgeContext.ts

@@ -2,15 +2,16 @@ import type { BridgeContext } from "../context";
 import type { BridgeValues } from "../core";
 import type { BridgeConfig } from "../protocol";
 import { createBridgeCodecs } from "./bridgeCodec";
+import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
-import type { BridgeLogger } from "./bridgeLog";
+import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 export interface ContextHooks {
-	onLog: BridgeLogger;
+	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
 }
 
@@ -19,10 +20,13 @@ export const createContext = (
 	supervisor: BridgeSupervisor,
 	hooks: ContextHooks,
 ): BridgeContext => {
+	const egress = createBridgeEgress(config);
+
 	const files = createBridgeFiles({
 		root: config.cwd,
 		uid: config.gameUid,
 		gid: config.gameGid,
+		egress,
 		onLog: hooks.onLog,
 	});
 
@@ -58,7 +62,7 @@ export const createContext = (
 
 		codec: createBridgeCodecs(files),
 
-		net: createBridgeNet(),
+		net: createBridgeNet(egress),
 
 		probe: createBridgeProbes(),
 
@@ -86,11 +90,27 @@ export const createContext = (
 			hooks.onEmit(event, payload);
 		},
 
-		log(message, fields) {
-			hooks.onLog(message, {
-				driver: true,
-				...fields,
-			});
-		},
+		log: Object.assign(
+			(message: string, fields?: BridgeValues) => {
+				hooks.onLog(message, {
+					...fields,
+					driver: true,
+				});
+			},
+			{
+				warn(message: string, fields?: BridgeValues) {
+					hooks.onLog.warn(message, {
+						...fields,
+						driver: true,
+					});
+				},
+				error(message: string, fields?: BridgeValues) {
+					hooks.onLog.error(message, {
+						...fields,
+						driver: true,
+					});
+				},
+			},
+		),
 	};
 };

package/src/runtime/bridgeDriver.ts

@@ -3,6 +3,7 @@ import type { BridgeDriver, BridgePanelModule } from "../modules";
 import { type BridgeField, BridgeFormTarget, BridgeLayout, type BridgeSection, type BridgeTab } from "../panel";
 
 const RESERVED_MODULE_IDS = new Set([
+	"announce",
 	"backup",
 	"events",
 	"install",