@riducms/admin 0.2.2 → 0.3.0

package/src/core/bootstrap/admin-bootstrap.ts

@@ -0,0 +1,396 @@
+import {
+	isRecord,
+	ADMIN_PREPARED_ROUTE_STATE_MEDIA_TYPE,
+	ADMIN_PREPARED_ROUTE_STATE_VERSION,
+	type AdminPreparedRouteDataV1,
+	type AdminCreateDataV1,
+	type AdminPreparedRouteStateV1,
+} from "@riducms/protocol";
+import { RiduError, type AdminLoader } from "@riducms/sdk";
+import { createContext } from "svelte";
+
+import type { AdminRuntime } from "@admin/core/runtime/admin-runtime.svelte";
+import { peekFormDraft } from "@admin/core/forms/form-draft-recovery";
+import { recoverFormDraft } from "@admin/core/forms/form-schema";
+import { preparedCustomView } from "@admin/core/routing/admin-view-selection";
+
+import {
+	readEmbeddedAdminState,
+	validateAdminPreparedState,
+	normalizedURLIdentity,
+} from "@admin/core/bootstrap/admin-prepared-state";
+import {
+	moduleGroupsForRelativeURL,
+	preloadAdminModuleGroups,
+} from "@admin/core/bootstrap/admin-route-modules";
+
+export class AdminBootstrapCoordinator {
+	#initialState = readEmbeddedAdminState();
+	#contextKey = "";
+	#routeKey = "";
+	#routeData?: {
+		identity: string;
+		data: AdminPreparedRouteDataV1;
+		loaders: AdminPreparedRouteStateV1["loaders"];
+	};
+	#runtime?: AdminRuntime;
+	#basePath = "/admin";
+
+	get initialState() {
+		return this.#initialState;
+	}
+
+	configure(runtime: AdminRuntime) {
+		this.#runtime = runtime;
+		this.#basePath = normalizeAdminBasePath(runtime.adminBasePath);
+	}
+
+	get contextKey() {
+		return this.#contextKey;
+	}
+
+	async prepareInitial(options: { stageRoute?: boolean } = {}) {
+		const state = this.initialState;
+		if (state === undefined) return;
+
+		if (state.outcome === "redirect") {
+			window.location.replace(state.location);
+			return neverSettles();
+		}
+		if (state.outcome === "reload") {
+			window.location.reload();
+			return neverSettles();
+		}
+
+		if (options.stageRoute === false) {
+			this.clear();
+			this.#initialState = undefined;
+			this.#clearContext();
+			return;
+		}
+
+		this.#adoptContext(state);
+		const preparedState = await this.#prepareRestoredCreateDraft(state);
+		await preloadAdminModuleGroups(preparedState.moduleGroups);
+		if (preparedState.outcome === "prepared") this.stage(preparedState);
+	}
+
+	loader = async ({ request }: { request: Request }) => {
+		const url = new URL(request.url);
+
+		try {
+			// Go marks its HTML even when the initial snapshot is missing or invalid.
+			// Browser-only hosts such as Vite have neither that marker nor the endpoint.
+			if (
+				this.#contextKey === "" &&
+				document.querySelector('meta[name="ridu-admin-build-id"]') === null
+			) {
+				await preloadAdminModuleGroups(
+					moduleGroupsForRelativeURL(this.#relativePath(url.pathname))
+				);
+				return null;
+			}
+
+			// Start URL-known chunks while Go reads the data. The response may name
+			// additional chunks (such as an upload preview), which we await below.
+			const [state] = await Promise.all([
+				this.#fetchRouteState(url, request.signal),
+				preloadAdminModuleGroups(moduleGroupsForRelativeURL(this.#relativePath(url.pathname))),
+			]);
+			if (request.signal.aborted) return null;
+
+			// Recover a missing or invalidated Go context through a fresh document;
+			// navigation data cannot establish an authoritative runtime on its own.
+			if (state.outcome === "reload" || this.#contextKey === "") {
+				window.location.assign(url.href);
+				return neverSettles();
+			}
+			if (state.outcome === "redirect") {
+				window.location.assign(state.location);
+				return neverSettles();
+			}
+
+			const preparedState = await this.#prepareRestoredCreateDraft(state, request.signal);
+			await preloadAdminModuleGroups(preparedState.moduleGroups);
+			if (request.signal.aborted) return null;
+
+			// Returning data does not publish it. Only commit() may give it to the
+			// destination; a newer navigation can still supersede this loader.
+			return preparedState;
+		} catch {
+			if (request.signal.aborted) return null;
+
+			// Preparation is an optimization. Any fetch, validation, or decode failure leaves the
+			// destination's existing controller loader as the authoritative fallback.
+			this.clear();
+			return null;
+		}
+	};
+
+	shouldRevalidate = ({ currentUrl, nextUrl }: { currentUrl: URL; nextUrl: URL }) =>
+		normalizedURLIdentity(currentUrl) !== normalizedURLIdentity(nextUrl);
+
+	stage(
+		state: AdminPreparedRouteStateV1,
+		expectedIdentity = normalizedURLIdentity(new URL(window.location.href))
+	) {
+		const identity = `${state.pathname}${state.search}`;
+		if (
+			state.version !== ADMIN_PREPARED_ROUTE_STATE_VERSION ||
+			expectedIdentity !== identity ||
+			state.fingerprint === "" ||
+			(this.#contextKey !== "" && state.contextKey !== this.#contextKey) ||
+			state.route === undefined ||
+			!this.#canSeedRoute(state)
+		) {
+			this.clear();
+			return false;
+		}
+
+		this.#routeData = { identity, data: state.route, loaders: state.loaders };
+		this.#routeKey = routeStateKey(state);
+		this.#adoptContext(state);
+		return true;
+	}
+
+	commit(state: AdminPreparedRouteStateV1 | null | undefined, url: URL) {
+		if (state == null) {
+			this.clear();
+			return false;
+		}
+
+		const identity = normalizedURLIdentity(url);
+		if (`${state.pathname}${state.search}` !== identity) return false;
+		if (this.#contextKey !== "" && state.contextKey !== this.#contextKey) return false;
+
+		const navigation = state.navigation ?? state.runtime;
+		if (navigation !== undefined) this.#runtime?.adoptPreparedNavigation(navigation);
+		this.#adoptContext(state);
+		if (state.outcome === "prepared") {
+			return this.#routeKey === routeStateKey(state) || this.stage(state, identity);
+		}
+
+		this.clear();
+		return false;
+	}
+
+	clear() {
+		this.#routeKey = "";
+		this.#routeData = undefined;
+	}
+
+	routeData(pathname: string, search = "") {
+		const base = this.#basePath === "/" ? "" : this.#basePath;
+		const url = new URL(`${base}${pathname}${search}`, window.location.origin);
+		return this.#routeData?.identity === normalizedURLIdentity(url)
+			? this.#routeData.data
+			: undefined;
+	}
+
+	discardRouteData(state: AdminPreparedRouteStateV1) {
+		if (this.#routeKey === routeStateKey(state)) this.clear();
+	}
+
+	loaderData(key: string, pathname: string, search = "") {
+		return this.routeData(pathname, search) === undefined
+			? undefined
+			: this.#routeData?.loaders?.[key];
+	}
+
+	isRouteStaged(state: AdminPreparedRouteStateV1) {
+		return this.#routeKey === routeStateKey(state);
+	}
+
+	async #fetchRouteState(url: URL, signal: AbortSignal) {
+		const response = await fetch(url, {
+			headers: {
+				Accept: ADMIN_PREPARED_ROUTE_STATE_MEDIA_TYPE,
+				"Ridu-Admin-Context": this.#contextKey,
+			},
+			credentials: "include",
+			signal,
+		});
+		if (!response.ok) throw new Error(`Admin route preparation failed with ${response.status}.`);
+
+		return validateAdminPreparedState(await response.json(), url, this.#contextKey);
+	}
+
+	async #prepareRestoredCreateDraft(state: AdminPreparedRouteStateV1, signal?: AbortSignal) {
+		if (state.outcome !== "prepared" || state.route?.kind !== "collection-create") return state;
+
+		const match = /^\/collections\/([^/]+)\/create(?:\/api)?$/.exec(
+			this.#relativePath(state.pathname)
+		);
+		const manifest = state.runtime?.manifest ?? this.#runtime?.manifest;
+		const navigation = state.navigation ?? state.runtime;
+		const client = this.#runtime?.client;
+		if (match === null || manifest === undefined || client === undefined) return state;
+
+		const slug = decodeURIComponent(match[1]);
+		const collection = manifest.collections.find((candidate) => candidate.slug === slug);
+		if (collection === undefined) return state;
+		const checkpoint = peekFormDraft(collection.id, undefined);
+		if (checkpoint === undefined) return state;
+
+		const defaults = state.route.create.values;
+		const recovered = recoverFormDraft(
+			{ values: defaults, original: defaults },
+			{ values: checkpoint.values, original: checkpoint.original },
+			checkpoint.collection.fields,
+			collection.fields
+		);
+		if (samePreparedCreateValues(recovered.values, defaults)) {
+			return state;
+		}
+
+		// Go checked access against its defaults. A local draft can change a
+		// data-dependent rule, so settle access for the recovered values before reveal.
+		let access: AdminCreateDataV1["access"];
+		try {
+			const value = await client.collectionAccess(slug, {
+				data: recovered.values,
+				locale: navigation.contentLocale,
+				signal,
+			});
+			access = { value };
+		} catch (cause) {
+			if (!(cause instanceof RiduError)) throw cause;
+			access = {
+				error: {
+					code: cause.code,
+					status: cause.status,
+					message: cause.message,
+					issues: [...cause.issues],
+					...(cause.requestId === undefined ? {} : { requestId: cause.requestId }),
+					...(cause.details === undefined ? {} : { details: cause.details }),
+				},
+			};
+		}
+
+		return {
+			...state,
+			route: {
+				...state.route,
+				create: { values: recovered.values, access },
+			},
+		};
+	}
+
+	#adoptContext(state: AdminPreparedRouteStateV1) {
+		if (state.contextKey === "") return;
+		if (this.#contextKey !== "" && this.#contextKey !== state.contextKey) return;
+		this.#contextKey = state.contextKey;
+		document.documentElement.dataset.riduContext = state.contextKey;
+	}
+
+	#clearContext() {
+		this.#contextKey = "";
+		delete document.documentElement.dataset.riduContext;
+	}
+
+	#canSeedRoute(state: AdminPreparedRouteStateV1) {
+		const config = this.#runtime?.config;
+		const route = state.route;
+		if (config === undefined || route === undefined) return route !== undefined;
+
+		const selected = preparedCustomView(
+			config,
+			this.#relativePath(state.pathname),
+			this.#runtime?.manifest
+		);
+
+		if (route.kind === "custom") {
+			const loader = selected?.loader;
+			return loader !== undefined && validLoaderSeed(loader, state.loaders);
+		}
+
+		// A core seed belongs to the core view, never to its custom replacement.
+		if (selected !== undefined) return false;
+
+		switch (route.kind) {
+			case "dashboard": {
+				const panels = config.extensions.dashboardPanels;
+				const replacement = panels.find((panel) => panel.position === "replace");
+				if (replacement !== undefined) {
+					return (
+						replacement.loader !== undefined && validLoaderSeed(replacement.loader, state.loaders)
+					);
+				}
+
+				return panels.every(
+					(panel) => panel.loader === undefined || validLoaderSeed(panel.loader, state.loaders)
+				);
+			}
+			case "account":
+			case "security":
+				return !config.extensions.account.some((panel) => panel.position === "replace");
+			case "login":
+				return !config.extensions.login.some((panel) => panel.position === "replace");
+			default:
+				return true;
+		}
+	}
+
+	#relativePath(pathname: string) {
+		if (this.#basePath === "/") return pathname;
+		if (pathname === this.#basePath) return "/";
+		return pathname.startsWith(`${this.#basePath}/`)
+			? pathname.slice(this.#basePath.length)
+			: pathname;
+	}
+}
+
+function validLoaderSeed(
+	loader: AdminLoader<never, unknown>,
+	results: AdminPreparedRouteStateV1["loaders"]
+) {
+	const result = results?.[loader.key];
+	if (result === undefined) return false;
+	// A structured read failure is complete data too: the view renders its error state.
+	if (result.error !== undefined) return true;
+
+	try {
+		loader.decode(result.value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function routeStateKey(state: AdminPreparedRouteStateV1) {
+	return `${state.pathname}${state.search}:${state.fingerprint}`;
+}
+
+// Create access depends on values, including a recovered local draft. Object
+// key order is not data identity, and authored fields named "signal" are data.
+export function samePreparedCreateValues(left: unknown, right: unknown): boolean {
+	if (left === right) return true;
+	if (Array.isArray(left) && Array.isArray(right))
+		return (
+			left.length === right.length &&
+			left.every((value, index) => samePreparedCreateValues(value, right[index]))
+		);
+	if (!isRecord(left) || !isRecord(right)) return false;
+	const keys = Object.keys(left);
+	return (
+		keys.length === Object.keys(right).length &&
+		keys.every(
+			(key) => Object.hasOwn(right, key) && samePreparedCreateValues(left[key], right[key])
+		)
+	);
+}
+
+function normalizeAdminBasePath(basePath: string) {
+	return `/${basePath.split("/").filter(Boolean).join("/")}`;
+}
+
+function neverSettles(): Promise<never> {
+	// A hard navigation transfers ownership to a new document, so the initiating handler must not
+	// resume and mutate the outgoing application while that document is loading.
+	return new Promise(() => {});
+}
+
+const [getAdminBootstrapCoordinator, setAdminBootstrapCoordinator] =
+	createContext<AdminBootstrapCoordinator>();
+
+export { getAdminBootstrapCoordinator, setAdminBootstrapCoordinator };

package/src/core/bootstrap/admin-prepared-state.ts

@@ -0,0 +1,213 @@
+import {
+	isRecord,
+	ADMIN_PREPARED_ROUTE_STATE_VERSION,
+	isAdminPreparedRouteData,
+	isAdminLoaderResults,
+	type AdminPreparedRouteStateV1,
+	type AdminPreparedRouteDataV1,
+} from "@riducms/protocol";
+
+const templateID = "ridu-admin-initial-state";
+
+// Cold HTML and navigation JSON cross the same wire boundary. Validate them
+// here, before the coordinator exposes anything to the runtime or controllers.
+export function readEmbeddedAdminState(): AdminPreparedRouteStateV1 | undefined {
+	const template = document.getElementById(templateID);
+	if (!(template instanceof HTMLTemplateElement)) return undefined;
+
+	try {
+		return validateAdminPreparedState(
+			JSON.parse(template.content.textContent ?? ""),
+			new URL(location.href)
+		);
+	} catch {
+		// Embedded state is optional; malformed or stale data falls back to the SDK bootstrap.
+		return undefined;
+	} finally {
+		template.remove();
+	}
+}
+
+export function validateAdminPreparedState(
+	value: unknown,
+	url: URL,
+	contextKey?: string
+): AdminPreparedRouteStateV1 {
+	if (!isRecord(value)) throw new Error("Admin prepared state must be an object.");
+	if (value.version !== ADMIN_PREPARED_ROUTE_STATE_VERSION)
+		throw new Error("Admin prepared state version is incompatible.");
+
+	if (typeof value.pathname !== "string" || typeof value.search !== "string")
+		throw new Error("Admin prepared route identity is invalid.");
+	if (`${value.pathname}${value.search}` !== normalizedURLIdentity(url))
+		throw new Error("Admin prepared route identity is stale.");
+
+	if (
+		typeof value.contextKey !== "string" ||
+		(value.contextKey !== "" && !/^[0-9a-f]{32}$/.test(value.contextKey))
+	)
+		throw new Error("Admin prepared context key is invalid.");
+	if (
+		typeof value.fingerprint !== "string" ||
+		(value.fingerprint !== "" && !/^[0-9a-f]{64}$/.test(value.fingerprint))
+	)
+		throw new Error("Admin prepared fingerprint is invalid.");
+	if (
+		typeof value.buildId !== "string" ||
+		(value.buildId !== "" && !/^[0-9a-f]{24}$/.test(value.buildId))
+	)
+		throw new Error("Admin prepared build ID is invalid.");
+	if (
+		!Array.isArray(value.moduleGroups) ||
+		!value.moduleGroups.every((group) => typeof group === "string")
+	)
+		throw new Error("Admin prepared module groups are invalid.");
+
+	const expectedBuildID = document
+		.querySelector<HTMLMetaElement>('meta[name="ridu-admin-build-id"]')
+		?.getAttribute("content");
+	if (
+		value.outcome !== "reload" &&
+		// An empty navigation context requires a fresh document, including its build.
+		contextKey !== "" &&
+		expectedBuildID != null &&
+		value.buildId !== expectedBuildID
+	)
+		throw new Error("Admin prepared state build is stale.");
+
+	if (
+		value.loaders !== undefined &&
+		(value.outcome !== "prepared" || !isAdminLoaderResults(value.loaders))
+	)
+		throw new Error("Admin loader results are invalid.");
+
+	// Each outcome has a different payload. Keep those requirements separate so
+	// adding a field to one outcome cannot silently relax another's validation.
+	switch (value.outcome) {
+		case "prepared":
+			if (
+				!isAdminPreparedRouteData(value.route) ||
+				(value.runtime === undefined && value.navigation === undefined) ||
+				!validPreparedModuleGroups(value.moduleGroups, value.route)
+			)
+				throw new Error("Admin prepared route data is invalid.");
+			break;
+		case "redirect":
+			if (typeof value.location !== "string")
+				throw new Error("Admin prepared redirect location is invalid.");
+			break;
+		case "reload":
+			if (
+				value.runtime !== undefined ||
+				value.navigation !== undefined ||
+				value.route !== undefined
+			)
+				throw new Error("Admin reload must not carry runtime or route data.");
+			break;
+		case "fallback":
+			if (value.location !== undefined || !validDiagnostic(value.diagnostic))
+				throw new Error("Admin fallback requires a diagnostic and no redirect.");
+			break;
+		default:
+			throw new Error("Admin prepared state outcome is invalid.");
+	}
+
+	if (value.runtime !== undefined && !validPreparedRuntime(value.runtime))
+		throw new Error("Admin prepared runtime is invalid.");
+
+	// Compact navigation can reuse a runtime, but can never establish one.
+	if (
+		value.navigation !== undefined &&
+		(value.runtime !== undefined ||
+			!contextKey ||
+			value.contextKey !== contextKey ||
+			!validPreparedNavigation(value.navigation))
+	)
+		throw new Error("Admin prepared navigation requires the matching runtime context.");
+
+	return value as unknown as AdminPreparedRouteStateV1;
+}
+
+function validPreparedModuleGroups(groups: string[], route: AdminPreparedRouteDataV1) {
+	const allowed = new Set([
+		"entry",
+		"document",
+		"date",
+		"upload-preview",
+		"bulk-upload",
+		"document-api",
+		"versions",
+	]);
+	if (
+		groups.some((group) => !allowed.has(group)) ||
+		new Set(groups).size !== groups.length ||
+		!groups.includes("entry")
+	)
+		return false;
+
+	switch (route.kind) {
+		case "collection-create":
+		case "collection-document":
+		case "global-document":
+			return groups.includes("document");
+		case "collection-api":
+		case "global-api":
+			return groups.includes("document") && groups.includes("document-api");
+		case "collection-versions":
+		case "global-versions":
+			return groups.includes("versions");
+		case "upload":
+			return groups.includes("bulk-upload");
+		case "security":
+			return groups.includes("date");
+		default:
+			return true;
+	}
+}
+
+function validPreparedNavigation(value: unknown) {
+	return (
+		isRecord(value) &&
+		isRecord(value.collectionOperations) &&
+		isRecord(value.globalOperations) &&
+		(value.contentLocale === undefined || typeof value.contentLocale === "string")
+	);
+}
+
+function validPreparedRuntime(value: unknown) {
+	if (!isRecord(value) || !isRecord(value.manifest) || !isRecord(value.manifest.application))
+		return false;
+
+	if (
+		!Array.isArray(value.manifest.collections) ||
+		(value.manifest.globals !== undefined && !Array.isArray(value.manifest.globals)) ||
+		!Array.isArray(value.manifest.plugins) ||
+		typeof value.authBootstrapAvailable !== "boolean" ||
+		!validPreparedNavigation(value) ||
+		!isRecord(value.preferences) ||
+		!["system", "light", "dark"].includes(String(value.theme))
+	)
+		return false;
+
+	if (value.session === undefined) return true;
+	return (
+		isRecord(value.session) &&
+		typeof value.session.id === "string" &&
+		typeof value.session.collection === "string" &&
+		isRecord(value.session.user)
+	);
+}
+
+function validDiagnostic(value: unknown) {
+	return isRecord(value) && typeof value.code === "string" && typeof value.message === "string";
+}
+
+export function normalizedURLIdentity(url: Pick<URL, "pathname" | "search">) {
+	const parameters = new URLSearchParams(url.search);
+	// Stable key sorting matches Go's identity and preserves repeated-value order.
+	parameters.sort();
+
+	const search = parameters.size === 0 ? "" : `?${parameters}`;
+	const pathname = url.pathname.length > 1 ? url.pathname.replace(/\/$/, "") : url.pathname;
+	return pathname + search;
+}

package/src/core/bootstrap/admin-route-modules.ts

@@ -0,0 +1,66 @@
+// Keep the exports, not a second import-promise cache: the browser already
+// deduplicates imports. Route wrappers need these synchronously on first render
+// so an already-loaded component does not briefly enter an {#await} placeholder.
+const preparedModules = new Map<string, unknown>();
+
+export function preparedAdminModule<Module>(group: string): Module | undefined {
+	return preparedModules.get(group) as Module | undefined;
+}
+
+export function moduleGroupsForRelativeURL(pathname: string) {
+	const segments = pathname.split("/").filter(Boolean);
+	if (segments[0] === "collections") {
+		if (segments.length === 3 && segments[2] === "upload") return ["bulk-upload"];
+		if ((segments.length === 4 || segments.length === 5) && segments[3] === "versions") {
+			return ["versions"];
+		}
+		if (segments.length === 3 && segments[2] !== "trash" && segments[2] !== "upload") {
+			return ["document"];
+		}
+		if (segments.length === 4 && segments[3] === "api") return ["document", "document-api"];
+	}
+	if (segments[0] === "globals") {
+		if ((segments.length === 3 || segments.length === 4) && segments[2] === "versions") {
+			return ["versions"];
+		}
+		if (segments.length === 2) return ["document"];
+		if (segments.length === 3 && segments[2] === "api") return ["document", "document-api"];
+	}
+	if (segments.length === 2 && segments[0] === "account" && segments[1] === "security") {
+		return ["date"];
+	}
+	return [];
+}
+
+export async function preloadAdminModuleGroups(groups: readonly string[]) {
+	await Promise.all(
+		[...new Set(groups)].map(async (group) => {
+			if (preparedModules.has(group)) return;
+			let module: unknown;
+			switch (group) {
+				case "bulk-upload":
+					module = await import("@admin/features/uploads/bulk-upload-route.svelte");
+					break;
+				case "document":
+					module = await import("@admin/features/documents/document-route.svelte");
+					break;
+				case "versions":
+					module = await import("@admin/features/versions/version-history-route.svelte");
+					break;
+				case "date":
+					module =
+						await import("@admin/components/ui/date-value-control/date-value-control.svelte");
+					break;
+				case "upload-preview":
+					module = await import("@admin/features/uploads/upload-control.svelte");
+					break;
+				case "document-api":
+					module = await import("@admin/features/documents/document-api-view.svelte");
+					break;
+				default:
+					return;
+			}
+			preparedModules.set(group, module);
+		})
+	);
+}