@serverkgg/bridge 0.0.1

package/src/manifest/dimensions.ts

@@ -0,0 +1,106 @@
+export const ASSET_MAX_EDGE = 4096;
+
+export interface AssetDimensions {
+	width: number;
+	height: number;
+}
+
+const readUint16 = (bytes: Uint8Array, offset: number) => {
+	const a = bytes[offset];
+	const b = bytes[offset + 1];
+
+	if (a === undefined || b === undefined) {
+		return null;
+	}
+
+	return (b << 8) + a;
+};
+
+const readUint24 = (bytes: Uint8Array, offset: number) => {
+	const a = bytes[offset];
+	const b = bytes[offset + 1];
+	const c = bytes[offset + 2];
+
+	if (a === undefined || b === undefined || c === undefined) {
+		return null;
+	}
+
+	return (c << 16) + (b << 8) + a;
+};
+
+const readUint32 = (bytes: Uint8Array, offset: number) => {
+	const a = bytes[offset];
+	const b = bytes[offset + 1];
+	const c = bytes[offset + 2];
+	const d = bytes[offset + 3];
+
+	if (a === undefined || b === undefined || c === undefined || d === undefined) {
+		return null;
+	}
+
+	return a + (b << 8) + (c << 16) + d * 0x1_00_00_00;
+};
+
+const lossyDimensions = (bytes: Uint8Array): AssetDimensions | null => {
+	const width = readUint16(bytes, 26);
+	const height = readUint16(bytes, 28);
+
+	if (width === null || height === null) {
+		return null;
+	}
+
+	return {
+		width: width & 0x3f_ff,
+		height: height & 0x3f_ff,
+	};
+};
+
+const losslessDimensions = (bytes: Uint8Array): AssetDimensions | null => {
+	const packed = readUint32(bytes, 21);
+
+	if (packed === null) {
+		return null;
+	}
+
+	return {
+		width: (packed & 0x3f_ff) + 1,
+		height: ((packed >>> 14) & 0x3f_ff) + 1,
+	};
+};
+
+const extendedDimensions = (bytes: Uint8Array): AssetDimensions | null => {
+	const width = readUint24(bytes, 24);
+	const height = readUint24(bytes, 27);
+
+	if (width === null || height === null) {
+		return null;
+	}
+
+	return {
+		width: width + 1,
+		height: height + 1,
+	};
+};
+
+const READERS: Record<string, (bytes: Uint8Array) => AssetDimensions | null> = {
+	"VP8 ": lossyDimensions,
+	VP8L: losslessDimensions,
+	VP8X: extendedDimensions,
+};
+
+export const readDimensions = (bytes: Uint8Array): AssetDimensions | null => {
+	const format = new TextDecoder().decode(bytes.subarray(12, 16));
+	const reader = READERS[format];
+
+	if (!reader) {
+		return null;
+	}
+
+	const dimensions = reader(bytes);
+
+	if (!dimensions || dimensions.width <= 0 || dimensions.height <= 0) {
+		return null;
+	}
+
+	return dimensions;
+};

package/src/manifest/guide.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { localizedTextSchema } from "./localized";
+
+export const zGuideId = z
+	.string()
+	.min(1)
+	.max(64)
+	.regex(/^[a-z0-9][a-z0-9-]*$/);
+
+export const zGuideTag = z
+	.string()
+	.min(1)
+	.max(32)
+	.regex(/^[a-z0-9][a-z0-9._-]*$/);
+
+export const zYoutubeId = z.string().regex(/^[A-Za-z0-9_-]{11}$/);
+
+const zMarkdownPath = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.md$/);
+
+export const guideEntrySchema = z.object({
+	id: zGuideId,
+	title: localizedTextSchema,
+	summary: localizedTextSchema,
+	tags: z.array(zGuideTag).max(8).default([]),
+	video: zYoutubeId.optional(),
+	body: z.object({
+		ar: zMarkdownPath,
+		en: zMarkdownPath,
+	}),
+});
+
+export type GuideEntry = z.infer<typeof guideEntrySchema>;

package/src/manifest/image.ts

@@ -0,0 +1 @@
+export const IMAGE_NAMESPACE = "serverkgg";

package/src/manifest/index.ts

@@ -0,0 +1,9 @@
+export * from "./assets";
+export * from "./category";
+export * from "./checks";
+export * from "./dimensions";
+export * from "./guide";
+export * from "./image";
+export * from "./localized";
+export * from "./manifest";
+export * from "./source";

package/src/manifest/localized.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const localizedTextSchema = z.object({
+	ar: z.string().min(1),
+	en: z.string().min(1),
+});
+
+export type LocalizedText = z.infer<typeof localizedTextSchema>;

package/src/manifest/manifest.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { PortProtocol } from "../core";
+import { ASSET_EXTENSION } from "./assets";
+import { GameCategory } from "./category";
+import { guideEntrySchema } from "./guide";
+import { IMAGE_NAMESPACE } from "./image";
+import { localizedTextSchema } from "./localized";
+
+export const MANIFEST_API_VERSION = "serverk.gg/v1";
+
+export const BACKUP_SETTLE_SECONDS_DEFAULT = 5;
+
+const zRelativePath = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.[a-z0-9]+$/);
+
+const zAssetPath = zRelativePath.refine((value) => {
+	return value.endsWith(`.${ASSET_EXTENSION}`);
+});
+
+export const MANIFEST_HOST_PORT_MIN = 1024;
+
+export const MANIFEST_HOST_PORT_SPAN = 1000;
+
+export const manifestPortHostSchema = z
+	.object({
+		default: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
+		min: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
+		max: z.int().min(MANIFEST_HOST_PORT_MIN).max(65_535),
+	})
+	.refine((host) => host.min <= host.max)
+	.refine((host) => host.min <= host.default && host.default <= host.max)
+	.refine((host) => host.max - host.min + 1 <= MANIFEST_HOST_PORT_SPAN);
+
+export type ManifestPortHost = z.infer<typeof manifestPortHostSchema>;
+
+export const manifestPortSchema = z.object({
+	key: z
+		.string()
+		.min(1)
+		.max(32)
+		.regex(/^[a-z][a-z0-9-]*$/),
+	port: z.int().min(1).max(65_535),
+	protocol: z.enum(PortProtocol).default(PortProtocol.Tcp),
+	host: manifestPortHostSchema,
+});
+
+export type ManifestPort = z.infer<typeof manifestPortSchema>;
+
+const zImageReference = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(new RegExp(`^${IMAGE_NAMESPACE}/[a-z0-9][a-z0-9-]*$`));
+
+export const manifestRuntimeSchema = z.object({
+	image: zImageReference,
+	ports: z.array(manifestPortSchema).min(1).max(8),
+});
+
+export const manifestMetadataSchema = z.object({
+	id: z
+		.string()
+		.min(1)
+		.max(64)
+		.regex(/^[a-z0-9][a-z0-9-]*$/),
+	name: localizedTextSchema,
+	description: localizedTextSchema,
+	tagline: localizedTextSchema,
+	category: z.enum(GameCategory),
+	logo: zAssetPath,
+	banner: zAssetPath,
+});
+
+export const manifestResourcesSchema = z
+	.object({
+		minMemoryMb: z.int().min(128).max(1_048_576),
+		recommendedMemoryMb: z.int().min(128).max(1_048_576),
+		minDiskMb: z.int().min(512),
+		playersPerGb: z.int().min(1).max(1024).optional(),
+		maxPlayers: z.int().min(1).max(100_000).optional(),
+	})
+	.refine((resources) => resources.recommendedMemoryMb >= resources.minMemoryMb);
+
+const zRelativeGlob = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(/^[^/\\][^\\]*$/)
+	.refine((value) => !value.split("/").includes(".."));
+
+export const manifestQuiesceSchema = z.object({
+	before: z.string().max(256).optional(),
+	flush: z.string().max(256).optional(),
+	after: z.string().max(256).optional(),
+	await: z.string().max(256).optional(),
+	settleSeconds: z.int().min(0).max(120).default(BACKUP_SETTLE_SECONDS_DEFAULT),
+});
+
+export const manifestBackupSchema = z.object({
+	include: z.array(zRelativeGlob).max(32).default([]),
+	exclude: z.array(zRelativeGlob).max(64).default([]),
+	quiesce: manifestQuiesceSchema.optional(),
+});
+
+export const manifestResetSchema = z.object({
+	keep: z.array(zRelativeGlob).max(32).default([]),
+});
+
+const zEnvKey = z
+	.string()
+	.min(2)
+	.max(32)
+	.regex(/^[A-Z][A-Z0-9_]*$/);
+
+export const manifestSecretSchema = z.object({
+	key: zEnvKey,
+	description: localizedTextSchema,
+	required: z.boolean().default(true),
+});
+
+export type ManifestSecret = z.infer<typeof manifestSecretSchema>;
+
+export const manifestFilesSchema = z.object({
+	hidden: z
+		.array(
+			z
+				.string()
+				.min(1)
+				.max(128)
+				.regex(/^[^/\\][^\\]*$/)
+				.refine((value) => !value.split("/").includes("..")),
+		)
+		.max(64)
+		.default([]),
+});
+
+export const manifestSchema = z.object({
+	apiVersion: z.literal(MANIFEST_API_VERSION),
+	kind: z.literal("GamePackage"),
+	metadata: manifestMetadataSchema,
+	resources: manifestResourcesSchema,
+	runtime: manifestRuntimeSchema,
+	guides: z.array(guideEntrySchema).max(64).default([]),
+	backup: manifestBackupSchema.optional(),
+	reset: manifestResetSchema.optional(),
+	secrets: z.array(manifestSecretSchema).max(16).default([]),
+	files: manifestFilesSchema.default({
+		hidden: [],
+	}),
+});
+
+export type Manifest = z.infer<typeof manifestSchema>;
+
+export const guidePackageSchema = z.object({
+	apiVersion: z.literal(MANIFEST_API_VERSION),
+	kind: z.literal("GuidePackage"),
+	metadata: z.object({
+		id: z
+			.string()
+			.min(1)
+			.max(64)
+			.regex(/^[a-z0-9][a-z0-9-]*$/),
+	}),
+	guides: z.array(guideEntrySchema).min(1).max(64),
+});
+
+export type GuidePackage = z.infer<typeof guidePackageSchema>;

package/src/manifest/source.ts

@@ -0,0 +1,89 @@
+import { verifyAsset } from "./assets";
+import { checkManifest } from "./checks";
+import { type Manifest, manifestSchema } from "./manifest";
+
+export const MANIFEST_FILE = "serverk.yml";
+
+export interface PackageSource {
+	list(): string[];
+	read(path: string): Uint8Array | null;
+}
+
+const readText = (source: PackageSource, path: string) => {
+	const bytes = source.read(path);
+
+	if (!bytes) {
+		throw new Error(`missing ${path}`);
+	}
+
+	return new TextDecoder().decode(bytes);
+};
+
+export const readYaml = (source: PackageSource, path: string) => {
+	return Bun.YAML.parse(readText(source, path));
+};
+
+const readAsset = (source: PackageSource, asset: string) => {
+	const bytes = source.read(asset);
+
+	if (!bytes) {
+		throw new Error(`missing asset ${asset}`);
+	}
+
+	const { mediaType, dimensions } = verifyAsset(asset, bytes);
+
+	return {
+		path: asset,
+		bytes,
+		mediaType,
+		dimensions,
+	};
+};
+
+export const readAssets = (source: PackageSource, manifest: Manifest) => {
+	return {
+		logo: readAsset(source, manifest.metadata.logo),
+		banner: readAsset(source, manifest.metadata.banner),
+	};
+};
+
+export const declaredFiles = (manifest: Manifest, guideFiles: string[] = []) => {
+	return [
+		MANIFEST_FILE,
+		manifest.metadata.logo,
+		manifest.metadata.banner,
+		...guideFiles,
+	];
+};
+
+export const computeBundleDigest = (source: PackageSource, paths: string[]) => {
+	const entries = [
+		...new Set(paths),
+	].sort();
+	const bundleHasher = new Bun.CryptoHasher("sha256");
+
+	for (const entry of entries) {
+		const bytes = source.read(entry);
+
+		if (!bytes) {
+			continue;
+		}
+
+		const fileHasher = new Bun.CryptoHasher("sha256");
+
+		fileHasher.update(bytes);
+		bundleHasher.update(`${entry}:${fileHasher.digest("hex")}\n`);
+	}
+
+	return `sha256:${bundleHasher.digest("hex")}`;
+};
+
+export const readPackage = (source: PackageSource) => {
+	const manifest: Manifest = manifestSchema.parse(readYaml(source, MANIFEST_FILE));
+
+	checkManifest(manifest);
+
+	return {
+		manifest,
+	};
+};

package/src/modules/bridge.ts

@@ -0,0 +1,53 @@
+import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
+import type { BridgeOption, BridgeRow, BridgeValue, BridgeValues, LocalizedText } from "../core";
+import type { BridgeField, BridgePanel, BridgeSection, BridgeTab } from "../panel";
+import type { BridgeDriver } from "./bridgeDriver";
+import type {
+	BridgeBackupModule,
+	BridgeCatalogEntry,
+	BridgeCatalogHit,
+	BridgeCatalogModule,
+	BridgeCatalogPage,
+	BridgeCollectionModule,
+	BridgeEventPattern,
+	BridgeEventsModule,
+	BridgeInstallModule,
+	BridgeLifecycleModule,
+	BridgeOptionsModule,
+	BridgeQueryModule,
+	BridgeRowAction,
+	BridgeSample,
+	BridgeSettingsModule,
+} from "./bridgeModule";
+
+export namespace Bridge {
+	export type Backup = BridgeBackupModule;
+	export type Catalog = BridgeCatalogModule;
+	export type CatalogEntry = BridgeCatalogEntry;
+	export type CatalogHit = BridgeCatalogHit;
+	export type CatalogPage = BridgeCatalogPage;
+	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
+	export type Context = BridgeContext;
+	export type Driver = BridgeDriver;
+	export type EventPattern = BridgeEventPattern;
+	export type Events = BridgeEventsModule;
+	export type ExecResult = BridgeExecResult;
+	export type Field = BridgeField;
+	export type FileEntry = BridgeFileEntry;
+	export type Install = BridgeInstallModule;
+	export type Lifecycle = BridgeLifecycleModule;
+	export type Option = BridgeOption;
+	export type Options = BridgeOptionsModule;
+	export type Panel = BridgePanel;
+	export type Query = BridgeQueryModule;
+	export type Reply = BridgeReply;
+	export type Row = BridgeRow;
+	export type RowAction<Row extends BridgeRow = BridgeRow> = BridgeRowAction<Row>;
+	export type Sample = BridgeSample;
+	export type Section = BridgeSection;
+	export type Settings = BridgeSettingsModule;
+	export type Tab = BridgeTab;
+	export type Text = LocalizedText;
+	export type Value = BridgeValue;
+	export type Values = BridgeValues;
+}

package/src/modules/bridgeDriver.ts

@@ -0,0 +1,19 @@
+import type { BridgePanel } from "../panel";
+import type {
+	BridgeBackupModule,
+	BridgeEventsModule,
+	BridgeInstallModule,
+	BridgeLifecycleModule,
+	BridgePanelModule,
+	BridgeQueryModule,
+} from "./bridgeModule";
+
+export interface BridgeDriver {
+	install: BridgeInstallModule;
+	lifecycle: BridgeLifecycleModule;
+	events?: BridgeEventsModule;
+	query?: BridgeQueryModule;
+	backup?: BridgeBackupModule;
+	panel?: BridgePanel;
+	modules?: Record<string, BridgePanelModule>;
+}

package/src/modules/bridgeModule.ts

@@ -0,0 +1,114 @@
+import type { BridgeContext } from "../context";
+import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
+
+export interface BridgeInstallModule {
+	kind: BridgeKind.Install;
+	run(context: BridgeContext): Promise<void>;
+}
+
+export interface BridgeLifecycleModule {
+	kind: BridgeKind.Lifecycle;
+	ready?: RegExp;
+	stopTimeoutSeconds?: number;
+	command(context: BridgeContext): Promise<string[]>;
+	stop?(context: BridgeContext): Promise<void>;
+	onReady?(context: BridgeContext): Promise<void>;
+}
+
+export interface BridgeBackupModule {
+	kind: BridgeKind.Backup;
+	settleSeconds?: number;
+	quiesce?(context: BridgeContext): Promise<void>;
+	release?(context: BridgeContext): Promise<void>;
+}
+
+export interface BridgeSample {
+	online: number | null;
+	max: number | null;
+}
+
+export interface BridgeQueryModule {
+	kind: BridgeKind.Query;
+	refreshSeconds?: number;
+	sample(context: BridgeContext): Promise<BridgeSample>;
+}
+
+export interface BridgeEventPattern {
+	match: RegExp;
+	emit: string;
+	stream?: BridgeStream;
+}
+
+export interface BridgeEventsModule {
+	kind: BridgeKind.Events;
+	patterns: BridgeEventPattern[];
+}
+
+export interface BridgeOptionsModule {
+	kind: BridgeKind.Options;
+	dependsOn?: string[];
+	ttlSeconds?: number;
+	list(context: BridgeContext): Promise<BridgeOption[]>;
+}
+
+export interface BridgeSettingsModule {
+	kind: BridgeKind.Settings;
+	read(context: BridgeContext): Promise<BridgeValues>;
+	write?(context: BridgeContext, values: BridgeValues): Promise<void>;
+}
+
+export type BridgeRowAction<Row extends BridgeRow = BridgeRow> = (context: BridgeContext, row: Row) => Promise<void>;
+
+export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
+	kind: BridgeKind.Collection;
+	requiresRunning?: boolean;
+	refreshSeconds?: number;
+	list(context: BridgeContext): Promise<Row[]>;
+	add?(context: BridgeContext, input: string): Promise<void>;
+	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>;
+	installed(context: BridgeContext): Promise<BridgeCatalogEntry[]>;
+	install(context: BridgeContext, id: string): Promise<BridgeCatalogEntry>;
+	remove(context: BridgeContext, id: string): Promise<void>;
+}
+
+export type BridgePanelModule =
+	| BridgeCatalogModule
+	| BridgeCollectionModule
+	| BridgeOptionsModule
+	| BridgeSettingsModule;
+
+export type BridgeModule =
+	| BridgeBackupModule
+	| BridgeEventsModule
+	| BridgeInstallModule
+	| BridgeLifecycleModule
+	| BridgePanelModule
+	| BridgeQueryModule;

package/src/modules/index.ts

@@ -0,0 +1,3 @@
+export * from "./bridge";
+export * from "./bridgeDriver";
+export * from "./bridgeModule";

package/src/panel/bridgeConfirm.ts

@@ -0,0 +1,5 @@
+export enum BridgeConfirm {
+	None = "none",
+	Normal = "normal",
+	Strong = "strong",
+}

package/src/panel/bridgeControl.ts

@@ -0,0 +1,7 @@
+export enum BridgeControl {
+	Boolean = "boolean",
+	Number = "number",
+	Select = "select",
+	Slider = "slider",
+	Text = "text",
+}

package/src/panel/bridgeFormTarget.ts

@@ -0,0 +1,4 @@
+export enum BridgeFormTarget {
+	Settings = "settings",
+	Variables = "variables",
+}

package/src/panel/bridgeIcon.ts

@@ -0,0 +1,17 @@
+export enum BridgeIcon {
+	Box = "box",
+	Chart = "chart",
+	Command = "command",
+	Download = "download",
+	Gamepad = "gamepad",
+	Globe = "globe",
+	Map = "map",
+	Puzzle = "puzzle",
+	Rocket = "rocket",
+	Settings = "settings",
+	Shield = "shield",
+	Sword = "sword",
+	Tag = "tag",
+	Users = "users",
+	Wrench = "wrench",
+}

package/src/panel/bridgeLayout.ts

@@ -0,0 +1,6 @@
+export enum BridgeLayout {
+	Cards = "cards",
+	Catalog = "catalog",
+	Form = "form",
+	Table = "table",
+}