@serverkgg/bridge 0.0.1 → 0.0.3

package/src/runtime/bridgeDriver.ts

@@ -1,8 +1,41 @@
-import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind } from "../core";
+import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind, type LocalizedText } from "../core";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
-import { type BridgeField, BridgeFormTarget, BridgeLayout, type BridgeSection, type BridgeTab } from "../panel";
+import {
+	type BridgeField,
+	BridgeFormTarget,
+	BridgeLayout,
+	type BridgeSection,
+	type BridgeSectionAction,
+	type BridgeTab,
+	type BridgeVisibleWhen,
+} from "../panel";
+import {
+	BRIDGE_ACTION_FIELDS_LIMIT,
+	BRIDGE_DEPENDS_ON_LIMIT,
+	BRIDGE_EVENTS_LIMIT,
+	BRIDGE_EXTENSION_LENGTH_LIMIT,
+	BRIDGE_FIELD_OPTIONS_LIMIT,
+	BRIDGE_FORM_FIELDS_LIMIT,
+	BRIDGE_ID_LENGTH_LIMIT,
+	BRIDGE_KEY_LENGTH_LIMIT,
+	BRIDGE_MODULE_ACTIONS_LIMIT,
+	BRIDGE_MODULES_LIMIT,
+	BRIDGE_OPTION_VALUE_LENGTH_LIMIT,
+	BRIDGE_PANEL_TABS_LIMIT,
+	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
+	BRIDGE_ROW_ACTIONS_LIMIT,
+	BRIDGE_SECTION_ACTIONS_LIMIT,
+	BRIDGE_STAGING_LENGTH_LIMIT,
+	BRIDGE_TAB_SECTIONS_LIMIT,
+	BRIDGE_TABLE_COLUMNS_LIMIT,
+	BRIDGE_TEXT_LENGTH_LIMIT,
+	BRIDGE_UPLOAD_EXTENSIONS_LIMIT,
+	BRIDGE_VISIBLE_VALUES_LIMIT,
+} from "../protocol";
+import { actionsOf } from "./bridgeActions";
 
 const RESERVED_MODULE_IDS = new Set([
+	"announce",
 	"backup",
 	"events",
 	"install",
@@ -22,16 +55,45 @@ const fail = (message: string): never => {
 	throw new BridgeDriverError(message);
 };
 
+const countIn = (count: number, limit: number, what: string, where: string) => {
+	if (count > limit) {
+		fail(`${where} declares ${count} ${what} — the platform takes at most ${limit}`);
+	}
+};
+
+const lengthIn = (value: string, limit: number, what: string, where: string) => {
+	if (value.length > limit) {
+		fail(`${where} ${what} is ${value.length} characters — the platform takes at most ${limit}`);
+	}
+};
+
 const validateId = (id: string, where: string) => {
 	if (!BRIDGE_ID_PATTERN.test(id)) {
 		fail(`${where} id "${id}" must be kebab-case — lowercase letters, digits, and dashes, starting with a letter`);
 	}
+
+	lengthIn(id, BRIDGE_ID_LENGTH_LIMIT, `id "${id}"`, where);
 };
 
 const validateModuleId = (id: string, where: string) => {
 	if (!BRIDGE_MODULE_ID_PATTERN.test(id)) {
 		fail(`${where} id "${id}" must be camelCase — letters and digits, starting with a lowercase letter`);
 	}
+
+	lengthIn(id, BRIDGE_ID_LENGTH_LIMIT, `id "${id}"`, where);
+};
+
+const validateText = (text: LocalizedText | undefined, what: string, where: string) => {
+	if (!text) {
+		return;
+	}
+
+	if (text.ar.length === 0 || text.en.length === 0) {
+		fail(`${where} ${what} needs both arabic and english text`);
+	}
+
+	lengthIn(text.ar, BRIDGE_TEXT_LENGTH_LIMIT, `${what} arabic text`, where);
+	lengthIn(text.en, BRIDGE_TEXT_LENGTH_LIMIT, `${what} english text`, where);
 };
 
 const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where: string) => {
@@ -44,6 +106,18 @@ const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where:
 	return module as BridgePanelModule;
 };
 
+const validateVisibleWhen = (visibleWhen: BridgeVisibleWhen | undefined, where: string) => {
+	if (!visibleWhen) {
+		return;
+	}
+
+	if (visibleWhen.empty === undefined && (visibleWhen.values ?? []).length === 0) {
+		fail(`${where} is visible when "${visibleWhen.variable}" matches nothing — declare values, empty, or both`);
+	}
+
+	countIn((visibleWhen.values ?? []).length, BRIDGE_VISIBLE_VALUES_LIMIT, "visible values", where);
+};
+
 const validateFields = (modules: Record<string, BridgePanelModule>, fields: BridgeField[], where: string) => {
 	const keys = new Set<string>();
 
@@ -54,18 +128,98 @@ const validateFields = (modules: Record<string, BridgePanelModule>, fields: Brid
 
 		keys.add(field.key);
 
+		const at = `${where} field "${field.key}"`;
+
+		lengthIn(field.key, BRIDGE_KEY_LENGTH_LIMIT, `key "${field.key}"`, where);
+		validateText(field.label, "label", at);
+		validateText(field.help, "help", at);
+		validateText(field.warning, "warning", at);
+		validateVisibleWhen(field.visibleWhen, at);
+
+		if (field.placeholder) {
+			lengthIn(field.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "placeholder", at);
+		}
+
+		if (Array.isArray(field.options)) {
+			countIn(field.options.length, BRIDGE_FIELD_OPTIONS_LIMIT, "options", at);
+
+			for (const option of field.options) {
+				lengthIn(option.value, BRIDGE_OPTION_VALUE_LENGTH_LIMIT, `option "${option.value}"`, at);
+				validateText(option.label, `option "${option.value}" label`, at);
+				validateText(option.help, `option "${option.value}" help`, at);
+			}
+		}
+
 		if (field.options && !Array.isArray(field.options)) {
-			const options = moduleOf(modules, field.options.module, `${where} field "${field.key}"`);
+			const options = moduleOf(modules, field.options.module, at);
 
 			if (options.kind !== BridgeKind.Options) {
-				fail(`${where} field "${field.key}" references "${field.options.module}", which is not an options module`);
+				fail(`${at} references "${field.options.module}", which is not an options module`);
 			}
 		}
 	}
 };
 
+const validateActions = (modules: Record<string, BridgePanelModule>, actions: BridgeSectionAction[], where: string) => {
+	const ids = new Set<string>();
+
+	for (const action of actions) {
+		if (ids.has(action.id)) {
+			fail(`${where} declares action "${action.id}" more than once`);
+		}
+
+		ids.add(action.id);
+
+		const at = `${where} action "${action.id}"`;
+		const fields = action.fields ?? [];
+
+		lengthIn(action.id, BRIDGE_KEY_LENGTH_LIMIT, `id "${action.id}"`, where);
+		validateText(action.label, "label", at);
+		validateText(action.confirmText, "confirm text", at);
+
+		if (fields.length > BRIDGE_ACTION_FIELDS_LIMIT) {
+			fail(`${at} declares ${fields.length} fields — at most ${BRIDGE_ACTION_FIELDS_LIMIT} fit one prompt`);
+		}
+
+		validateFields(modules, fields, at);
+	}
+};
+
 const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
+	validateVisibleWhen(section.visibleWhen, where);
+	validateText(section.title, "title", where);
+
+	if (section.layout !== BridgeLayout.Form) {
+		validateText(section.layout === BridgeLayout.Actions ? section.help : section.empty, "text", where);
+	}
+
 	switch (section.layout) {
+		case BridgeLayout.Actions: {
+			const module = moduleOf(modules, section.module, where);
+
+			if (module.kind !== BridgeKind.Actions) {
+				fail(`${where} references "${section.module}", which is not an actions module`);
+
+				return;
+			}
+
+			if (section.actions.length === 0) {
+				fail(`${where} declares no actions`);
+			}
+
+			countIn(section.actions.length, BRIDGE_SECTION_ACTIONS_LIMIT, "actions", where);
+
+			validateActions(modules, section.actions, where);
+
+			for (const action of section.actions) {
+				if (!module.actions[action.id]) {
+					fail(`${where} declares action "${action.id}", which module "${section.module}" does not implement`);
+				}
+			}
+
+			return;
+		}
+
 		case BridgeLayout.Form: {
 			if (section.target === BridgeFormTarget.Settings && !section.module) {
 				fail(`${where} targets settings but names no module`);
@@ -83,6 +237,13 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				}
 			}
 
+			validateText(section.confirmText, "confirm text", where);
+
+			if (section.fields.length === 0) {
+				fail(`${where} declares no fields`);
+			}
+
+			countIn(section.fields.length, BRIDGE_FORM_FIELDS_LIMIT, "fields", where);
 			validateFields(modules, section.fields, where);
 
 			return;
@@ -98,11 +259,58 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				return;
 			}
 
-			if (section.layout === BridgeLayout.Table && section.add && !module.add) {
-				fail(`${where} declares an add control but module "${section.module}" has no add handler`);
+			if (section.layout === BridgeLayout.Table) {
+				if (section.add && !module.add) {
+					fail(`${where} declares an add control but module "${section.module}" has no add handler`);
+				}
+
+				if (section.upload && !module.add) {
+					fail(`${where} declares an upload control but module "${section.module}" has no add handler`);
+				}
+
+				if (section.columns.length === 0) {
+					fail(`${where} declares no columns`);
+				}
+
+				countIn(section.columns.length, BRIDGE_TABLE_COLUMNS_LIMIT, "columns", where);
+
+				for (const column of section.columns) {
+					lengthIn(column.key, BRIDGE_KEY_LENGTH_LIMIT, `column key "${column.key}"`, where);
+					validateText(column.label, `column "${column.key}" label`, where);
+				}
+
+				if (section.add) {
+					validateText(section.add.label, "add label", where);
+
+					if (section.add.placeholder) {
+						lengthIn(section.add.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "add placeholder", where);
+					}
+				}
+
+				if (section.upload) {
+					validateText(section.upload.label, "upload label", where);
+					lengthIn(section.upload.staging, BRIDGE_STAGING_LENGTH_LIMIT, "upload staging path", where);
+
+					if (section.upload.extensions.length === 0) {
+						fail(`${where} declares an upload control with no extensions`);
+					}
+
+					countIn(section.upload.extensions.length, BRIDGE_UPLOAD_EXTENSIONS_LIMIT, "upload extensions", where);
+
+					for (const extension of section.upload.extensions) {
+						lengthIn(extension, BRIDGE_EXTENSION_LENGTH_LIMIT, `upload extension "${extension}"`, where);
+					}
+				}
 			}
 
+			countIn((section.actions ?? []).length, BRIDGE_ROW_ACTIONS_LIMIT, "actions", where);
+			validateActions(modules, section.actions ?? [], where);
+
 			for (const action of section.actions ?? []) {
+				if (action.download) {
+					continue;
+				}
+
 				if (!module.actions?.[action.id]) {
 					fail(`${where} declares action "${action.id}", which module "${section.module}" does not implement`);
 				}
@@ -118,6 +326,8 @@ const validateSection = (modules: Record<string, BridgePanelModule>, section: Br
 				fail(`${where} references "${section.module}", which is not a catalog module`);
 			}
 
+			validateText(section.confirmText, "confirm text", where);
+
 			return;
 		}
 	}
@@ -127,11 +337,14 @@ const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab)
 	const sections = new Set<string>();
 
 	validateId(tab.id, "tab");
+	validateText(tab.title, "title", `tab "${tab.id}"`);
 
 	if (tab.sections.length === 0) {
 		fail(`tab "${tab.id}" has no sections`);
 	}
 
+	countIn(tab.sections.length, BRIDGE_TAB_SECTIONS_LIMIT, "sections", `tab "${tab.id}"`);
+
 	for (const section of tab.sections) {
 		if (sections.has(section.id)) {
 			fail(`tab "${tab.id}" declares section "${section.id}" more than once`);
@@ -147,6 +360,15 @@ const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab)
 export const validateDriver = (driver: BridgeDriver) => {
 	const modules = driver.modules ?? {};
 
+	countIn(Object.keys(modules).length, BRIDGE_MODULES_LIMIT, "panel modules", "the driver");
+
+	const emitted = new Set([
+		...(driver.events?.patterns ?? []).map((pattern) => pattern.emit),
+		...(driver.events?.emits ?? []),
+	]);
+
+	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
+
 	for (const [id, module] of Object.entries(modules)) {
 		validateModuleId(id, "module");
 
@@ -154,6 +376,18 @@ export const validateDriver = (driver: BridgeDriver) => {
 			fail(`module id "${id}" is reserved`);
 		}
 
+		countIn(actionsOf(module).length, BRIDGE_MODULE_ACTIONS_LIMIT, "actions", `module "${id}"`);
+
+		if (module.kind === BridgeKind.Options) {
+			countIn((module.dependsOn ?? []).length, BRIDGE_DEPENDS_ON_LIMIT, "dependencies", `module "${id}"`);
+		}
+
+		if (module.kind === BridgeKind.Actions) {
+			for (const action of Object.keys(module.actions)) {
+				validateModuleId(action, `module "${id}" action`);
+			}
+		}
+
 		if (module.kind === BridgeKind.Collection) {
 			for (const action of Object.keys(module.actions ?? {})) {
 				validateModuleId(action, `module "${id}" action`);
@@ -165,6 +399,12 @@ export const validateDriver = (driver: BridgeDriver) => {
 		return;
 	}
 
+	if (driver.panel.tabs.length === 0) {
+		fail("the panel declares no tabs");
+	}
+
+	countIn(driver.panel.tabs.length, BRIDGE_PANEL_TABS_LIMIT, "tabs", "the panel");
+
 	const tabs = new Set<string>();
 
 	for (const tab of driver.panel.tabs) {

package/src/runtime/bridgeEgress.ts

@@ -0,0 +1,360 @@
+import {
+	BRIDGE_EGRESS_FRAME_LIMIT,
+	BRIDGE_EGRESS_SOCKET_NAME,
+	type BridgeConfig,
+	type BridgeEgressDownloadResult,
+	type BridgeEgressFetchResult,
+	BridgeEgressMethod,
+	type BridgeEgressRequest,
+	type BridgeEgressResponse,
+} from "../protocol";
+
+const CONNECT_RETRY_MS = 10_000;
+
+const CALL_TIMEOUT_MS = 20_000;
+
+const DOWNLOAD_TIMEOUT_MS = 300_000;
+
+const QUEUE_HIGH_WATER_BYTES = 8 * 1024 * 1024;
+
+const NEWLINE = 0x0a;
+
+export class BridgeEgressUnavailableError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = "BridgeEgressUnavailableError";
+	}
+}
+
+export class BridgeEgressCallError extends Error {
+	readonly status: number | null;
+
+	constructor(status: number | null, message: string) {
+		super(message);
+
+		this.name = "BridgeEgressCallError";
+		this.status = status;
+	}
+}
+
+export interface BridgeEgressCallOptions {
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	cache?: boolean;
+	cacheSeconds?: number;
+	refresh?: boolean;
+}
+
+export interface BridgeEgressDownloadOptions extends BridgeEgressCallOptions {
+	digest?: string;
+	sizeBytes?: number;
+}
+
+export interface BridgeEgressDownload extends BridgeEgressDownloadResult {
+	body: AsyncIterable<Uint8Array>;
+}
+
+export interface BridgeEgress {
+	fetch(url: string, options?: BridgeEgressCallOptions): Promise<BridgeEgressFetchResult>;
+	download(url: string, options?: BridgeEgressDownloadOptions): Promise<BridgeEgressDownload>;
+}
+
+const createByteStream = () => {
+	const chunks: Uint8Array[] = [];
+
+	let queued = 0;
+	let done = false;
+	let failure: unknown = null;
+	let wake: (() => void) | null = null;
+	let drain: (() => void) | null = null;
+
+	const signal = () => {
+		const resume = wake;
+
+		wake = null;
+		resume?.();
+	};
+
+	return {
+		get queued() {
+			return queued;
+		},
+
+		push(chunk: Uint8Array) {
+			chunks.push(chunk);
+			queued += chunk.byteLength;
+			signal();
+		},
+
+		finish() {
+			done = true;
+			signal();
+		},
+
+		fail(error: unknown) {
+			failure = error;
+			done = true;
+			signal();
+		},
+
+		onDrain(listener: () => void) {
+			drain = listener;
+		},
+
+		async *stream(): AsyncGenerator<Uint8Array> {
+			while (true) {
+				const chunk = chunks.shift();
+
+				if (chunk) {
+					queued -= chunk.byteLength;
+
+					if (queued < QUEUE_HIGH_WATER_BYTES) {
+						drain?.();
+					}
+
+					yield chunk;
+
+					continue;
+				}
+
+				if (failure) {
+					throw failure;
+				}
+
+				if (done) {
+					return;
+				}
+
+				await new Promise<void>((resolve) => {
+					wake = resolve;
+				});
+			}
+		},
+	};
+};
+
+export const createBridgeEgress = (config: BridgeConfig): BridgeEgress => {
+	const path = `${config.run}/${BRIDGE_EGRESS_SOCKET_NAME}`;
+
+	let blockedUntil = 0;
+
+	const frameOf = (method: BridgeEgressMethod, url: string, options: BridgeEgressDownloadOptions) => {
+		const request: BridgeEgressRequest = {
+			id: 1,
+			token: config.token,
+			method,
+			url,
+			...options,
+		};
+
+		return `${JSON.stringify(request)}\n`;
+	};
+
+	const connect = async <Data>(handlers: Bun.SocketHandler<Data>) => {
+		if (performance.now() < blockedUntil) {
+			throw new BridgeEgressUnavailableError("the egress channel is not available");
+		}
+
+		try {
+			return await Bun.connect<Data>({
+				unix: path,
+				socket: handlers,
+			});
+		} catch {
+			blockedUntil = performance.now() + CONNECT_RETRY_MS;
+
+			throw new BridgeEgressUnavailableError("the egress channel is not available");
+		}
+	};
+
+	return {
+		async fetch(url, options = {}) {
+			let settle: (response: BridgeEgressResponse<BridgeEgressFetchResult>) => void = () => undefined;
+			let fail: (error: Error) => void = () => undefined;
+
+			const pending = new Promise<BridgeEgressResponse<BridgeEgressFetchResult>>((resolve, reject) => {
+				settle = resolve;
+				fail = reject;
+			});
+
+			let buffer = "";
+
+			const socket = await connect<undefined>({
+				data(_connection, chunk) {
+					buffer += chunk.toString();
+
+					if (buffer.length > BRIDGE_EGRESS_FRAME_LIMIT) {
+						fail(new BridgeEgressUnavailableError("the egress reply is too large"));
+
+						return;
+					}
+
+					const frame = buffer.split("\n").at(0) ?? "";
+
+					if (buffer.includes("\n") && frame.trim().length > 0) {
+						try {
+							settle(JSON.parse(frame) as BridgeEgressResponse<BridgeEgressFetchResult>);
+						} catch {
+							fail(new BridgeEgressUnavailableError("the egress channel sent a malformed reply"));
+						}
+					}
+				},
+
+				error(_connection, error) {
+					fail(new BridgeEgressUnavailableError(error.message));
+				},
+
+				close() {
+					fail(new BridgeEgressUnavailableError("the egress channel closed the connection"));
+				},
+			});
+
+			try {
+				socket.write(frameOf(BridgeEgressMethod.Fetch, url, options));
+
+				const response = await Promise.race([
+					pending,
+					Bun.sleep(options.timeoutMs ?? CALL_TIMEOUT_MS).then(() => {
+						throw new BridgeEgressUnavailableError("the egress channel timed out");
+					}),
+				]);
+
+				if (!response.ok) {
+					throw new BridgeEgressCallError(response.status, response.error);
+				}
+
+				return response.result;
+			} finally {
+				socket.end();
+			}
+		},
+
+		async download(url, options = {}) {
+			let settle: (response: BridgeEgressResponse<BridgeEgressDownloadResult>) => void = () => undefined;
+			let fail: (error: Error) => void = () => undefined;
+
+			const pending = new Promise<BridgeEgressResponse<BridgeEgressDownloadResult>>((resolve, reject) => {
+				settle = resolve;
+				fail = reject;
+			});
+
+			const stream = createByteStream();
+
+			let header: string | null = null;
+			let headerBuffer = "";
+			let received = 0;
+			let expected: number | null = null;
+
+			const socket = await connect<undefined>({
+				data(connection, chunk) {
+					let body = chunk;
+
+					if (header === null) {
+						const boundary = chunk.indexOf(NEWLINE);
+
+						if (boundary === -1) {
+							headerBuffer += chunk.toString();
+
+							if (headerBuffer.length > BRIDGE_EGRESS_FRAME_LIMIT) {
+								fail(new BridgeEgressUnavailableError("the egress reply is too large"));
+							}
+
+							return;
+						}
+
+						header = headerBuffer + chunk.subarray(0, boundary).toString();
+
+						try {
+							const response = JSON.parse(header) as BridgeEgressResponse<BridgeEgressDownloadResult>;
+
+							settle(response);
+
+							if (!response.ok) {
+								return;
+							}
+
+							expected = response.result.sizeBytes;
+						} catch {
+							fail(new BridgeEgressUnavailableError("the egress channel sent a malformed reply"));
+
+							return;
+						}
+
+						body = chunk.subarray(boundary + 1);
+					}
+
+					if (body.byteLength === 0) {
+						return;
+					}
+
+					received += body.byteLength;
+					stream.push(new Uint8Array(body));
+
+					if (stream.queued >= QUEUE_HIGH_WATER_BYTES) {
+						connection.pause();
+					}
+
+					if (expected !== null && expected > 0 && received >= expected) {
+						stream.finish();
+					}
+				},
+
+				error(_connection, error) {
+					fail(new BridgeEgressUnavailableError(error.message));
+					stream.fail(new BridgeEgressUnavailableError(error.message));
+				},
+
+				close() {
+					fail(new BridgeEgressUnavailableError("the egress channel closed the connection"));
+
+					if (expected !== null && expected > 0 && received < expected) {
+						stream.fail(new BridgeEgressUnavailableError("the egress channel closed mid-transfer"));
+
+						return;
+					}
+
+					stream.finish();
+				},
+			});
+
+			stream.onDrain(() => {
+				socket.resume();
+			});
+
+			try {
+				socket.write(frameOf(BridgeEgressMethod.Download, url, options));
+
+				const response = await Promise.race([
+					pending,
+					Bun.sleep(options.timeoutMs ?? DOWNLOAD_TIMEOUT_MS).then(() => {
+						throw new BridgeEgressUnavailableError("the egress channel timed out");
+					}),
+				]);
+
+				if (!response.ok) {
+					socket.end();
+
+					throw new BridgeEgressCallError(response.status, response.error);
+				}
+
+				const body = async function* () {
+					try {
+						yield* stream.stream();
+					} finally {
+						socket.end();
+					}
+				};
+
+				return {
+					...response.result,
+					body: body(),
+				};
+			} catch (error) {
+				socket.end();
+
+				throw error;
+			}
+		},
+	};
+};