camox 0.76.0 → 0.76.1

package/dist/features/routes/pageRuntime.js

@@ -36,10 +36,16 @@ function parseMarkdownPath(pathname) {
 	if (pathname === "/index.md") return "/";
 	return pathname.slice(0, -3) || null;
 }
-function createServerApiClient(apiUrl, options) {
-	const headers = localeHeaders(options?.locale);
-	if (options?.lookToken) headers[LOOK_TOKEN_HEADER] = options.lookToken;
-	if (options?.draftId && (options.authCookieHeader || options.lookToken)) headers[DRAFT_HEADER] = options.draftId;
+/**
+* The API's client for one kind of read: with a credential, in a draft or Live, in a locale. Only
+* a credential can read a draft, so a draft is only ever named with one; a Live read names the
+* draft this Worker publishes, if any.
+*/
+function createServerApiClient(apiUrl, { credential, draftId, locale } = {}) {
+	const headers = localeHeaders(locale);
+	const session = credential && "session" in credential ? credential.session : void 0;
+	if (credential && "lookToken" in credential) headers[LOOK_TOKEN_HEADER] = credential.lookToken;
+	if (draftId && credential) headers[DRAFT_HEADER] = draftId;
 	else {
 		const publishing = publishingDraft();
 		if (publishing) headers[PUBLISHING_DRAFT_HEADER] = publishing;
@@ -48,7 +54,7 @@ function createServerApiClient(apiUrl, options) {
 		url: `${apiUrl}/rpc`,
 		headers,
 		fetch: (request, init) => {
-			if (options?.authCookieHeader && request instanceof Request) request.headers.set("Better-Auth-Cookie", options.authCookieHeader);
+			if (session && request instanceof Request) request.headers.set("Better-Auth-Cookie", session);
 			return fetch(request, init);
 		}
 	}));
@@ -92,42 +98,16 @@ function draftRefusalNotice(error, draftId) {
 	if (code === "FORBIDDEN" || status === 403) return { reason: "forbidden" };
 	if (code === "UNAUTHORIZED" || status === 401) return null;
 }
-/**
-* Reads with the draft a URL names, or Live (ADR 0011). Only a member's request names the draft;
-* anyone else reads Live. When the API refuses the draft, the same response reads Live instead.
-*/
-async function readDraftOrLive(draftId, member, read) {
-	if (!draftId) return { value: await read(void 0) };
-	if (!member) return {
-		value: await read(void 0),
-		refusedDraft: { notice: null }
-	};
-	try {
-		return {
-			value: await read(draftId),
-			draftId
-		};
-	} catch (error) {
-		const notice = draftRefusalNotice(error, draftId);
-		if (notice === void 0) throw error;
-		return {
-			value: await read(void 0),
-			refusedDraft: { notice }
-		};
-	}
-}
 /** The URL a render shows: without the draft param when the draft couldn't be read. */
 function renderedHref(url, read) {
 	return read.refusedDraft ? withoutDraft(url) : url;
 }
-async function loadCamoxPage({ apiUrl, authCookieHeader, lookToken, draftId, locale, pathname, projectUuid, queryClient }) {
+async function loadCamoxPage({ reader, draftId, locale, pathname, projectUuid, queryClient }) {
 	const studioCache = createServerStudioCache(queryClient, {
-		apiUrl,
-		authCookieHeader,
-		lookToken,
+		reader,
 		locale
 	});
-	const inDraft = { in: draftId && (authCookieHeader || lookToken) ? draftId : null };
+	const inDraft = { in: draftId ?? null };
 	const fallback = locale && linkFallbackLocale(locale);
 	const [page] = await Promise.all([
 		studioCache.ensure(reads.pageStructure({
@@ -143,16 +123,14 @@ async function loadCamoxPage({ apiUrl, authCookieHeader, lookToken, draftId, loc
 	return page;
 }
 /**
-* The studio's reads for one server request, read with its session. Each operation names the
-* draft it acts in, once the request settled which one it reads.
+* The studio's reads for one server request, read as its reader. Each operation names the draft
+* it acts in, once the request settled which one it reads.
 */
-function createServerStudioCache(queryClient, { apiUrl, authCookieHeader, lookToken, locale }) {
+function createServerStudioCache(queryClient, { reader, locale }) {
 	return createStudioCache({
 		queryClient,
 		scope: createDraftScope({ queryClient }),
-		api: (draft, inLocale) => createServerApiClient(apiUrl, {
-			authCookieHeader,
-			lookToken,
+		api: (draft, inLocale) => reader.api({
 			draftId: draft ?? void 0,
 			locale: inLocale
 		}),
@@ -160,45 +138,6 @@ function createServerStudioCache(queryClient, { apiUrl, authCookieHeader, lookTo
 	});
 }
 /**
-* The locales of the scope a request reads: the URL's draft's for a session naming one, else
-* Live's. A draft the API refuses reads Live's, as the request's other reads then do. Live's read
-* keeps the session: a member's studio routes the locales Live doesn't serve yet, which visitors
-* never see (ADR 0043), and a render with a session is private.
-*/
-async function readScopeLocales({ apiUrl, authCookieHeader, draftId, projectUuid }) {
-	const list = (session, readDraftId) => createServerApiClient(apiUrl, {
-		authCookieHeader: session,
-		draftId: readDraftId
-	}).locales.list({ projectUuid });
-	const { value } = await readDraftOrLive(draftId, !!authCookieHeader, async (readDraftId) => {
-		if (readDraftId || !authCookieHeader) return list(authCookieHeader, readDraftId);
-		try {
-			return await list(authCookieHeader, void 0);
-		} catch (error) {
-			if (!isAuthSessionError(error)) throw error;
-			return list(void 0, void 0);
-		}
-	});
-	return value;
-}
-/**
-* The project, when the auth cookie is a valid session of one of its members. A successful
-* protected project lookup validates both session and project access: cookie presence alone
-* is not proof of authentication. An invalid session asks for the cookie to be cleared.
-*/
-async function resolveMemberProject({ apiUrl, authCookieHeader, projectUuid }) {
-	if (!authCookieHeader) return { clearAuthCookie: false };
-	try {
-		return {
-			project: await createServerApiClient(apiUrl, { authCookieHeader }).projects.getByUuid({ projectUuid }),
-			clearAuthCookie: false
-		};
-	} catch (error) {
-		if (!isAuthSessionError(error)) throw error;
-		return { clearAuthCookie: true };
-	}
-}
-/**
 * The project's favicon, which falls back to the default favicon when none was uploaded.
 * Pass `withDefault: false` to get a 404 instead, to learn whether there is one.
 */
@@ -217,36 +156,13 @@ function buildCamoxPageLoaderData(apiUrl, page, origin) {
 		faviconUrl: buildFaviconUrl(apiUrl, page.project)
 	};
 }
-async function loadCamoxPageForRequest({ apiUrl, authCookieHeader, draftId, locale, origin, pathname, projectUuid, queryClient }) {
-	const member = await resolveMemberProject({
-		apiUrl,
-		authCookieHeader,
-		projectUuid
-	});
-	if (member.clearAuthCookie) console.warn("[camox] Ignoring stale camox_auth_cookie.");
-	const { value: page, ...read } = await readDraftOrLive(draftId, !!member.project, (readDraftId) => loadCamoxPage({
-		apiUrl,
-		authCookieHeader: member.project ? authCookieHeader : void 0,
-		draftId: readDraftId,
-		locale,
-		pathname,
-		projectUuid,
-		queryClient
-	}));
-	return {
-		...read,
-		data: buildCamoxPageLoaderData(apiUrl, page, origin),
-		project: member.project,
-		shouldClearAuthCookie: member.clearAuthCookie
-	};
-}
 /**
 * Reads the Markdown Representation of the page at a runtime path, with its locale's prefix, in
 * one API read: the API finds the locale the prefix names, the page there, its Markdown and what
 * its front matter is built from. Markdown is a public output, so it reads Live whoever asks.
 */
-function readPageMarkdown({ apiUrl, path, projectUuid }) {
-	return createServerApiClient(apiUrl).pages.getMarkdown({
+function readPageMarkdown({ reader, path, projectUuid }) {
+	return reader.api().pages.getMarkdown({
 		path,
 		projectUuid
 	});
@@ -366,4 +282,4 @@ function buildCamoxPageHead(camoxApp, loaderData, locale) {
 }
 
 //#endregion
-export { buildCamoxPageHead, buildCamoxPageLoaderData, buildDefaultFaviconUrl, buildFaviconUrl, buildPageHead, buildPageMeta, createServerApiClient, createServerStudioCache, curatedMarkdownResponse, curatedPageMetaInput, declarePage, getMarkdownPath, isAuthSessionError, isNotFoundError, loadCamoxPage, loadCamoxPageForRequest, parseMarkdownPath, parseQuality, prefersMarkdown, readDraftOrLive, readPageMarkdown, readScopeLocales, renderedHref, resolveMemberProject, withFrontMatter };
+export { buildCamoxPageHead, buildCamoxPageLoaderData, buildDefaultFaviconUrl, buildFaviconUrl, buildPageHead, buildPageMeta, createServerApiClient, createServerStudioCache, curatedMarkdownResponse, curatedPageMetaInput, declarePage, draftRefusalNotice, getMarkdownPath, isAuthSessionError, isNotFoundError, loadCamoxPage, parseMarkdownPath, parseQuality, prefersMarkdown, readPageMarkdown, renderedHref, withFrontMatter };

package/dist/features/runtime/pageApp.js

@@ -2,8 +2,8 @@ import { DraftScopeContext } from "../../lib/draft-scope.js";
 import { useAuthState, useSignInRedirect } from "../../lib/auth.js";
 import { ArtifactCaptureContext } from "../../core/hooks/useArtifactHost.js";
 import { useSignInShortcut } from "../provider/signInShortcut.js";
-import { PreviewActivation } from "../preview/components/PreviewActivation.js";
 import { PreviewDocumentContext } from "./PreviewDocumentContext.js";
+import { PreviewActivation } from "../preview/components/PreviewActivation.js";
 import { Frame } from "../preview/components/Frame.js";
 import { PreviewSignInPage } from "../provider/PreviewSignInPage.js";
 import { CoreCamoxProvider } from "../provider/CoreCamoxProvider.js";

package/dist/features/runtime/pageRead.js

@@ -0,0 +1,105 @@
+import { createRequestContext } from "../../core/requestContext.js";
+import { asCollectionItem } from "../../core/recordItem.js";
+import { matchDerivedLayout } from "../../core/derivedRoutes.js";
+import { layoutPageContext } from "../../core/layoutContext.js";
+import { isNotFoundError } from "../routes/pageRuntime.js";
+
+//#region src/features/runtime/pageRead.ts
+/**
+* What a path shows, in the Locale the path's prefix named: a Singleton Layout's page first, then
+* the curated page at the path, then a Derived Layout's page. Each output reads the curated page
+* and the layout's blocks as it needs them; Page Read decides which it shows and assembles a
+* Layout Page. A Layout Page's loader runs in the Draft its blocks are read in: alongside them
+* when the reader knows the Draft, after them when their read settles it.
+*/
+async function readPage({ app, path, pathname, reader, curated, layout }) {
+	const match = app && matchDerivedLayout(app.getLayouts(), path);
+	const layoutPage = () => readLayoutPage({
+		app,
+		match,
+		pathname,
+		reader,
+		readBlocks: layout
+	});
+	if (!mayShowCuratedPage(app, path)) return layoutPage();
+	try {
+		const { value: page, ...read } = await curated();
+		if (page !== null) return {
+			kind: "curated",
+			page,
+			...read
+		};
+	} catch (error) {
+		if (!isNotFoundError(error)) throw error;
+	}
+	return match ? layoutPage() : { kind: "none" };
+}
+/**
+* Whether a path may show a curated page, so reading one there may be worth starting early: not
+* a Singleton Layout's route.
+*/
+function mayShowCuratedPage(app, path) {
+	return (app && matchDerivedLayout(app.getLayouts(), path))?.layout._internal.kind !== "singleton";
+}
+async function readLayoutPage({ app, match, pathname, reader, readBlocks }) {
+	const layout = match.layout._internal;
+	const blocksInScope = () => reader.inScope((draftId) => readBlocks(draftId, layout.id));
+	const load = (draftId) => loadLayoutResult(app, match, createRequestContext({ records: reader.records(draftId) }), reader.locale);
+	let result;
+	let read;
+	try {
+		if (reader.draft) [result, read] = await Promise.all([load(reader.draft.id), blocksInScope()]);
+		else {
+			read = await blocksInScope();
+			result = await load(read.draftId);
+		}
+	} catch (error) {
+		if (isNotFoundError(error)) return {
+			kind: "none",
+			layout: match.layout
+		};
+		throw error;
+	}
+	const { value: blocks, ...draftRead } = read;
+	return {
+		kind: "layout",
+		layout: match.layout,
+		params: match.params,
+		blocks,
+		result,
+		...layoutPageContext(app, layout, {
+			path: pathname,
+			locale: reader.locale.tag,
+			projectName: blocks.projectName,
+			params: match.params,
+			result
+		}),
+		...draftRead
+	};
+}
+const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An envelope names its record; it doesn't authorize anything, the API does. */
+function isValidCollectionItem(app, result) {
+	const data = result.data;
+	return typeof result.collectionId === "string" && !!app.getCollectionById(result.collectionId) && typeof data?.id === "string" && RECORD_ID.test(data.id) && typeof data.content === "object" && data.content !== null;
+}
+/**
+* Runs a Layout Page's loader in the page's locale. The envelope survives SSR, navigation and
+* hydration, and its data renders as returned: Camox never translates it.
+*/
+async function loadLayoutResult(app, match, context, locale) {
+	const { loader, id } = match.layout._internal;
+	if (!loader) return void 0;
+	const result = await loader({
+		params: match.params,
+		context,
+		locale: locale.tag
+	});
+	const serializedResult = result === void 0 ? void 0 : JSON.parse(JSON.stringify(result));
+	const record = asCollectionItem(serializedResult);
+	if (!(record ? isValidCollectionItem(app, record) : serializedResult?.kind === "data" && Object.hasOwn(serializedResult, "data"))) throw new Error(`Layout "${id}" loader must return { kind: "data", data } with JSON-serializable data, or a collection-item envelope naming a registered collection and a record id`);
+	return serializedResult;
+}
+
+//#endregion
+export { mayShowCuratedPage, readPage };

package/dist/features/runtime/reader.d.ts

@@ -0,0 +1,25 @@
+import { LocaleView } from "../../lib/locale-path.js";
+import "../routes/pageRuntime.js";
+import { Router } from "@camox/api-contract/router";
+import { RouterClient } from "@orpc/server";
+//#region src/features/runtime/reader.d.ts
+/** The API's procedures, as the content port answers them. */
+export type ContentClient = RouterClient<Router>;
+/** What proves a read may see more than Live: a Member's session, or a look token (ADR 0032). */
+export type Credential = {
+  session: string;
+} | {
+  lookToken: string;
+};
+/** Which reads a client makes: with which credential, in which Draft (Live without), in which Locale. */
+export interface ContentAccess {
+  credential?: Credential;
+  draftId?: string;
+  locale?: LocaleView;
+}
+/**
+ * The content port: the API's reads, as one credential sees them, in Live or a Draft, in a
+ * Locale. Production reads the API (`apiContent`); tests read an in-memory one.
+ */
+export type Content = (access: ContentAccess) => ContentClient;
+//#endregion

package/dist/features/runtime/reader.js

@@ -0,0 +1,142 @@
+import { draftNamedBy } from "../../lib/draft-scope.js";
+import { buildClearServerAuthCookieHeader, getLookToken, getServerAuthCookieHeader } from "../../lib/server-auth-cookie.js";
+import { createServerApiClient, draftRefusalNotice, isAuthSessionError } from "../routes/pageRuntime.js";
+import { DRAFT_SEARCH_PARAM } from "@camox/api-contract/drafts";
+
+//#region src/features/runtime/reader.ts
+/** The content port's production adapter: the API at `apiUrl`, over oRPC. */
+function apiContent(apiUrl) {
+	return (access) => createServerApiClient(apiUrl, access);
+}
+function contentOf(options) {
+	return options.content ?? (options.apiUrl ? apiContent(options.apiUrl) : void 0);
+}
+/**
+* Whether a request may see what only it sees, so no shared cache keeps its response (ADR 0022).
+* Known before any read, so a cache can decide before the runtime answers.
+*/
+function isPrivateRequest(request) {
+	return !!getServerAuthCookieHeader(request.headers) || draftNamedBy(request.url) !== null;
+}
+/**
+* The request's Reader: a Member when the API confirms its session for the project, which it
+* asks once, else a Visitor. A session the API refuses is cleared. Without a project or a way to
+* read content, nobody is a Member.
+*/
+async function resolveReader(request, options) {
+	const content = contentOf(options);
+	const session = getServerAuthCookieHeader(request.headers);
+	const named = draftNamedBy(request.url) ?? void 0;
+	const isPrivate = isPrivateRequest(request);
+	if (!content || !options.projectUuid || !session) return visitor(content, options, {
+		named,
+		private: isPrivate
+	});
+	let member;
+	try {
+		member = await content({ credential: { session } }).projects.getByUuid({ projectUuid: options.projectUuid });
+	} catch (error) {
+		if (!isAuthSessionError(error)) throw error;
+		console.warn("[camox] Ignoring stale camox_auth_cookie.");
+		return visitor(content, options, {
+			named,
+			private: isPrivate,
+			setCookie: buildClearServerAuthCookieHeader()
+		});
+	}
+	const credential = { session };
+	const api = ({ draftId, locale } = {}) => content({
+		credential,
+		draftId,
+		locale
+	});
+	return withLocales(options, {
+		member,
+		draftId: named,
+		private: isPrivate,
+		setCookie: void 0,
+		api,
+		read: async (read) => {
+			if (!named) return { value: await read(void 0) };
+			try {
+				return {
+					value: await read(named),
+					draftId: named
+				};
+			} catch (error) {
+				const notice = draftRefusalNotice(error, named);
+				if (notice === void 0) throw error;
+				return {
+					value: await read(void 0),
+					refusedDraft: { notice }
+				};
+			}
+		}
+	});
+}
+/**
+* A Visitor's Reader, for what reads Live whoever asks (sitemaps, llms.txt, Markdown): no
+* session check, no credential.
+*/
+function visitorReader(options) {
+	return visitor(contentOf(options), options, {
+		named: void 0,
+		private: false
+	});
+}
+/**
+* The look document's Reader (ADR 0032): the look token the request's cookie carries, for the
+* Draft the URL names. Null without both.
+*/
+function lookReader(request, options) {
+	const content = contentOf(options);
+	const lookToken = getLookToken(request.headers);
+	const draftId = new URL(request.url).searchParams.get(DRAFT_SEARCH_PARAM) || void 0;
+	if (!content || !lookToken || !draftId) return null;
+	const credential = { lookToken };
+	return withLocales(options, {
+		member: void 0,
+		draftId,
+		private: true,
+		setCookie: void 0,
+		api: ({ locale } = {}) => content({
+			credential,
+			draftId,
+			locale
+		}),
+		read: async (read) => ({
+			value: await read(draftId),
+			draftId
+		})
+	});
+}
+function visitor(content, options, { named, private: isPrivate, setCookie }) {
+	const api = ({ locale } = {}) => {
+		if (!content) throw new Error("Camox has no content to read: the runtime names no API.");
+		return content({ locale });
+	};
+	return withLocales(options, {
+		member: void 0,
+		draftId: void 0,
+		private: isPrivate,
+		setCookie,
+		api,
+		read: async (read) => ({
+			value: await read(void 0),
+			...named && { refusedDraft: { notice: null } }
+		})
+	});
+}
+function withLocales(options, reader) {
+	return {
+		...reader,
+		locales: async () => {
+			const projectUuid = options.projectUuid;
+			const { value } = await reader.read((draftId) => reader.api({ draftId }).locales.list({ projectUuid }));
+			return value;
+		}
+	};
+}
+
+//#endregion
+export { apiContent, isPrivateRequest, lookReader, resolveReader, visitorReader };

package/dist/features/runtime/runtime.d.ts

@@ -3,9 +3,10 @@ import { AlternatePath, LocaleView } from "../../lib/locale-path.js";
 import { AnyLayoutLoaderResult } from "../../core/createLayout.js";
 import { CamoxApp } from "../../core/createApp.js";
 import { AnalyticsProviders } from "./analytics.js";
+import { Content, ContentClient } from "./reader.js";
 import { RuntimeOwnedRouteKind } from "./runtimeRoutes.js";
 import { StudioRenderInput } from "./studioApp.js";
-import { DraftRead, MemberProject, PageHead, createServerApiClient } from "../routes/pageRuntime.js";
+import { DraftRead, MemberProject, PageHead } from "../routes/pageRuntime.js";
 import { LookPlaceholderHeight } from "@camox/api-contract/drafts";
 import { UseHeadInput } from "unhead/types";
 //#region src/features/runtime/runtime.d.ts
@@ -47,7 +48,7 @@ export interface PageRenderInput extends DraftRead {
    */
   lookLayout?: {
     layoutId: string;
-    layout: Awaited<ReturnType<ReturnType<typeof createServerApiClient>["layouts"]["getUnplaced"]>>["layout"];
+    layout: Awaited<ReturnType<ContentClient["layouts"]["getUnplaced"]>>["layout"];
     placeholder: LookPlaceholderHeight;
     path: string;
     projectName: string;
@@ -74,7 +75,7 @@ export interface PageRenderInput extends DraftRead {
       projectName: string;
     };
     result?: AnyLayoutLoaderResult;
-    layout: Awaited<ReturnType<ReturnType<typeof createServerApiClient>["layouts"]["get"]>>["layout"];
+    layout: Awaited<ReturnType<ContentClient["layouts"]["get"]>>["layout"];
   };
   apiUrl: string;
   authenticationUrl: string;
@@ -97,6 +98,11 @@ export interface PageRenderInput extends DraftRead {
 }
 export interface RuntimeOptions {
   apiUrl?: string;
+  /**
+   * Where the runtime reads content, as each request's Reader sees it. Without it, the API at
+   * `apiUrl`. Tests read an in-memory one.
+   */
+  content?: Content;
   authenticationUrl?: string;
   /** Where the browser loads each block from, so a page can preload the blocks it renders. */
   blockPreloads?: {