@torpor/build 0.4.14 → 1.0.0

package/src/site/serverEntry.ts

@@ -1,13 +1,15 @@
 import manifest from "@torpor/build/manifest";
 import { type ServerComponent, type ServerSlotRender } from "@torpor/view/ssr";
+import formDataToRecord from "../form/formDataToRecord.ts";
 import notFound from "../response/notFound.ts";
 import ok from "../response/ok.ts";
 import seeOther from "../response/seeOther.ts";
 import ServerEvent from "../server/ServerEvent.ts";
-import $page from "../state/$page";
+import $page from "../state/$serverPage.ts";
 import type PageEndPoint from "../types/PageEndPoint.ts";
 import type PageServerEndPoint from "../types/PageServerEndPoint.ts";
 import type RouteHandler from "../types/RouteHandler.ts";
+import type ServerRequest from "../types/ServerRequest.ts";
 import {
 	ERROR_ROUTE,
 	HOOK_ROUTE,
@@ -21,6 +23,15 @@ import {
 import type ServerEndPoint from "../types/ServerEndPoint.ts";
 import type ServerHook from "../types/ServerHook.ts";
 import type ServerLoadEvent from "../types/ServerLoadEvent.ts";
+import searchParamsToRecord from "../utils/searchParamsToRecord.ts";
+import validate from "../validation/validate.ts";
+import ValidationError from "../validation/ValidationError.ts";
+import {
+	endpointSchema,
+	validateEndpointParams,
+	validationErrorResponse,
+} from "../validation/endpoint.ts";
+import { findMissingSlotLayout, warnMissingSlotContent } from "./layoutSlots.ts";
 import Router from "./Router.ts";
 
 // Build the router from the Site object created by the user
@@ -29,8 +40,8 @@ router.addPages(manifest.routes);
 
 //console.log(`routes:\n  ${router.routes.map((r) => r.path).join("\n  ")}`);
 
-export async function load(ev: ServerEvent, template: string): Promise<Response> {
-	const url = new URL(ev.request.url);
+export async function load(ev: ServerEvent, template?: string): Promise<Response> {
+	const url = ev.url;
 	const path = url.pathname;
 	const query = url.searchParams;
 
@@ -88,8 +99,8 @@ export async function load(ev: ServerEvent, template: string): Promise<Response>
 			if (ev.request.method === "GET") {
 				return await loadData(ev, url, handler, "load", params);
 			} else if (ev.request.method === "POST") {
-				const serverEndPoint: PageServerEndPoint | undefined =
-					handler.endPoint && (await handler.endPoint()).default;
+				const serverEndPoint: PageServerEndPoint | undefined = (await resolveModule(handler))
+					.default;
 				return handleResponse(
 					await runAction(ev, url, handler, serverEndPoint, params, query, template),
 					true,
@@ -114,6 +125,22 @@ export async function load(ev: ServerEvent, template: string): Promise<Response>
 	return notFound();
 }
 
+/**
+ * Resolves the route's endpoint module, caching it on the handler so warm
+ * requests don't pay for the loader promise.
+ */
+async function resolveModule(handler: RouteHandler): Promise<any> {
+	return (handler.resolvedModule ??= await (handler.modulePromise ??= handler.endPoint()));
+}
+
+async function loadServerHooks(handler: RouteHandler): Promise<ServerHook[]> {
+	if (!handler.serverHooks) return [];
+	// Resolve each hook module once and cache the result on the handler
+	return (handler.resolvedHooks ??= Promise.all(
+		handler.serverHooks.map(async (load) => (await load()).default),
+	));
+}
+
 async function handleResponse(response: Response, fromForm = false): Promise<Response> {
 	$page.status = response.status;
 
@@ -155,151 +182,272 @@ async function loadData(
 	url: URL,
 	handler: RouteHandler,
 	functionName: string,
-	params: Record<string, string>,
+	params: Record<string, any>,
 ) {
-	const serverEndPoint: ServerEndPoint | undefined = (await handler.endPoint()).default;
-	if (serverEndPoint && serverEndPoint[functionName]) {
-		const serverParams = buildServerParams(ev, url, params);
-
-		if (handler.serverHook) {
-			const serverHook: ServerHook | undefined = (await handler.serverHook()).default;
-			if (serverHook?.handle) {
-				await serverHook.handle(serverParams);
-			}
+	// The endpoint module is cached on the handler, so once warm this is a
+	// plain property read
+	const mod = handler.resolvedModule ?? (await resolveModule(handler));
+	const serverEndPoint: ServerEndPoint | undefined = mod?.default;
+	// `functionName` is computed from the request method, so the handlers are
+	// accessed through a loose record
+	const handlerFn = (
+		serverEndPoint as unknown as Record<string, ServerRequest | undefined> | undefined
+	)?.[functionName];
+	if (!serverEndPoint || !handlerFn) {
+		return notFound();
+	}
+
+	// Route params come from the URL, so a failed validation means the
+	// resource doesn't exist. Only endpoints declaring a params schema pay
+	// for validation
+	const paramsSchema = endpointSchema(serverEndPoint, "params");
+	if (paramsSchema) {
+		try {
+			params = (await validate(paramsSchema, params)) as Record<string, any>;
+		} catch (error) {
+			if (error instanceof ValidationError) return notFound();
+			throw error;
 		}
+	}
 
-		const result = await serverEndPoint[functionName](serverParams);
+	try {
+		// If the endpoint declares a schema for this handler, validate its
+		// input up front and reject with 422 if it fails. get/head/load
+		// schemas validate the query string; other schemas validate the json
+		// body. Endpoints without a schema skip straight to the handler
+		const schema = endpointSchema(serverEndPoint, functionName);
+		const values = schema
+			? functionName === "get" || functionName === "head" || functionName === "load"
+				? { query: await validate(schema, searchParamsToRecord(url.searchParams)) }
+				: { json: await validate(schema, await ev.json()) }
+			: {};
+
+		const serverParams = buildServerParams(ev, url, params, values);
+
+		// Hooks are resolved once per handler; routes without hooks don't
+		// await anything here
+		const hooks = handler.serverHooks ? await loadServerHooks(handler) : [];
+
+		let entered = 0;
+		let enterResponse: Response | undefined = undefined;
+		try {
+			// Hooks run from the root down; a hook's enter can return a
+			// Response to short-circuit the request
+			for (; entered < hooks.length && !enterResponse; entered++) {
+				const hookResult = await hooks[entered].enter?.(serverParams);
+				if (hookResult) {
+					enterResponse = hookResult;
+				}
+			}
 
-		// If there was no response returned from load (such as errors or a
-		// redirect), send an ok response
-		return result || ok();
+			// If there was no response returned from load (such as errors or a
+			// redirect), send an ok response
+			return (await handlerFn(serverParams)) || ok();
+		} finally {
+			// Run exit hooks in reverse order for hooks that were entered
+			while (entered > 0) {
+				entered--;
+				await hooks[entered].exit?.(serverParams);
+			}
+		}
+	} catch (error) {
+		const response = validationErrorResponse(error);
+		if (response) return response;
+		throw error;
 	}
-
-	return notFound();
 }
 
 async function loadView(
 	ev: ServerEvent,
 	url: URL,
 	handler: RouteHandler,
-	params: Record<string, string>,
-	template: string,
+	params: Record<string, any>,
+	template: string | undefined,
 	formStatus?: number,
 	form?: Record<string, string | number>,
+	skipHook?: boolean,
 ) {
 	// There must be a client endpoint with a component
-	const clientEndPoint: PageEndPoint | undefined = (await handler.endPoint()).default;
+	const clientEndPoint: PageEndPoint | undefined = (await resolveModule(handler)).default;
 	if (!clientEndPoint?.component) {
 		return notFound();
 	}
 
+	// The template comes from site.html, which endpoints-only sites don't have
+	if (!template) {
+		throw new Error(
+			"Page routes require a src/site.html file, which was not found; add it, or remove page/layout routes to serve endpoints only",
+		);
+	}
+
 	// There may be a server endpoint
 	const serverEndPoint: PageServerEndPoint | undefined =
 		handler.serverEndPoint && (await handler.serverEndPoint())?.default;
 
-	// Maybe hit the server hook
-	const serverParams = buildServerParams(ev, url, params);
-	if (handler.serverHook) {
-		const serverHook: ServerHook | undefined = (await handler.serverHook()).default;
-		if (serverHook?.handle) {
-			await serverHook.handle(serverParams);
+	// Validate the route params and the load query against the server
+	// endpoint's schemas, if it declares any. Params come from the URL, so a
+	// failed validation means the resource doesn't exist; a failed query goes
+	// to the error page like any other load failure
+	let query: unknown;
+	if (serverEndPoint) {
+		try {
+			params = await validateEndpointParams(serverEndPoint, params);
+		} catch (error) {
+			if (error instanceof ValidationError) return notFound();
+			throw error;
+		}
+		const loadSchema = endpointSchema(serverEndPoint, "load");
+		if (loadSchema) {
+			try {
+				query = await validate(loadSchema, searchParamsToRecord(url.searchParams));
+			} catch (error) {
+				const response = validationErrorResponse(error);
+				if (response) return response;
+				throw error;
+			}
 		}
 	}
 
-	// Pass the data into $props
-	// TODO: Promise.all
-	// NOTE: We're loading data from top to bottom, overriding as we go, and I'm
-	// not sure if this is the best way to go
-	let data = {};
-	if (handler.layouts) {
-		for (let layout of handler.layouts) {
-			const layoutEndPoint: PageEndPoint | undefined = (await layout.endPoint())?.default;
-			const layoutServerEndPoint: PageServerEndPoint | undefined =
-				layout.serverEndPoint && (await layout.serverEndPoint())?.default;
-			const layoutResponse = await loadClientAndServerData(
-				url,
-				params,
-				serverParams,
-				data,
-				layoutEndPoint,
-				layoutServerEndPoint,
-			);
-			if (layoutResponse?.ok === false) {
-				return layoutResponse;
+	// Maybe hit the server hooks -- unless they already ran for this request,
+	// which is the case when the view is re-rendered after a form action
+	const serverParams = buildServerParams(ev, url, params, query ? { query } : {});
+	const serverHooks = skipHook ? [] : await loadServerHooks(handler);
+	let entered = 0;
+	let enterResponse: Response | undefined = undefined;
+	try {
+		// Hooks run from the root down; a hook's enter can return a Response
+		// to short-circuit the request
+		for (; entered < serverHooks.length && !enterResponse; entered++) {
+			const hookResult = await serverHooks[entered].enter?.(serverParams);
+			if (hookResult) {
+				enterResponse = hookResult;
 			}
 		}
-	}
-	let endPointResponse = await loadClientAndServerData(
-		url,
-		params,
-		serverParams,
-		data,
-		clientEndPoint,
-		serverEndPoint,
-	);
-	if (endPointResponse?.ok === false) {
-		return endPointResponse;
-	}
-	let $props: Record<string, any> = { data, form };
-
-	let styles = "";
-
-	// If there are layouts, work our way upwards, pushing each component into
-	// the default slot of its parent
-	// TODO: Also handle layout server data
-	// TODO: There's probably a nicer way to do this with reducers or something
-	let component = clientEndPoint.component as ServerComponent;
-	let slots: Record<string, ServerSlotRender> | undefined = undefined;
-	if (handler.layouts) {
-		let slotFunctions: ServerSlotRender[] = [];
-		slotFunctions[handler.layouts.length] = (_, $context) => {
-			let { body, head } = (clientEndPoint.component as ServerComponent)($props, $context);
-			styles += head;
-			return body;
+		if (enterResponse) {
+			return enterResponse;
+		}
+
+		// Pass the data into $props
+		// TODO: Promise.all
+		// NOTE: We're loading data from top to bottom, overriding as we go, and I'm
+		// not sure if this is the best way to go
+		let data = {};
+		if (handler.layouts) {
+			for (let layout of handler.layouts) {
+				const layoutEndPoint: PageEndPoint | undefined = (await layout.endPoint())?.default;
+				const layoutServerEndPoint: PageServerEndPoint | undefined =
+					layout.serverEndPoint && (await layout.serverEndPoint())?.default;
+				const layoutResponse = await loadClientAndServerData(
+					url,
+					params,
+					serverParams,
+					data,
+					layoutEndPoint,
+					layoutServerEndPoint,
+				);
+				if (layoutResponse?.ok === false) {
+					return layoutResponse;
+				}
+			}
+		}
+		let endPointResponse = await loadClientAndServerData(
+			url,
+			params,
+			serverParams,
+			data,
+			clientEndPoint,
+			serverEndPoint,
+		);
+		if (endPointResponse?.ok === false) {
+			return endPointResponse;
+		}
+		let $props: Record<string, any> = { data, form };
+
+		let styles = "";
+
+		// If there are layouts, work our way upwards, pushing each component into
+		// the default slot of its parent
+		// TODO: Also handle layout server data
+		// TODO: There's probably a nicer way to do this with reducers or something
+		let component = clientEndPoint.component as ServerComponent;
+		let slots: Record<string, ServerSlotRender> | undefined = undefined;
+		// Which slot levels actually ran during the render below, so a layout
+		// that never rendered its <slot /> (silently dropping the page
+		// content) can be reported (see findMissingSlotLayout)
+		const invokedLevels = new Set<number>();
+		const trackSlot = (level: number, slot: ServerSlotRender): ServerSlotRender => {
+			return ($slot, $context) => {
+				invokedLevels.add(level);
+				return slot($slot, $context);
+			};
 		};
-		for (let i = handler.layouts.length - 1; i >= 0; i--) {
-			const layoutEndPoint: PageEndPoint | undefined = (await handler.layouts[i].endPoint())
-				?.default;
-			if (layoutEndPoint?.component) {
-				if (i === 0) {
-					component = layoutEndPoint.component as ServerComponent;
-					slots = { _: slotFunctions[i + 1] };
-				} else {
-					slotFunctions[i] = (_, $context) => {
-						let { body, head } = (layoutEndPoint.component as ServerComponent)($props, $context, {
-							_: slotFunctions[i + 1],
+		if (handler.layouts) {
+			let slotFunctions: ServerSlotRender[] = [];
+			// The last slot function will render the client component
+			slotFunctions[handler.layouts.length] = trackSlot(handler.layouts.length, (_, $context) => {
+				let { body, head } = (clientEndPoint.component as ServerComponent)($props, $context);
+				styles += head;
+				return body;
+			});
+			for (let i = handler.layouts.length - 1; i >= 0; i--) {
+				const layoutEndPoint: PageEndPoint | undefined = (await handler.layouts[i].endPoint())
+					?.default;
+				if (layoutEndPoint?.component) {
+					if (i === 0) {
+						component = layoutEndPoint.component as ServerComponent;
+						slots = { _: slotFunctions[i + 1] };
+					} else {
+						slotFunctions[i] = trackSlot(i, (_, $context) => {
+							let { body, head } = (layoutEndPoint.component as ServerComponent)($props, $context, {
+								_: slotFunctions[i + 1],
+							});
+							styles += head;
+							return body;
 						});
-						styles += head;
-						return body;
-					};
+					}
 				}
 			}
 		}
-	}
 
-	let html;
-	try {
-		let { body, head } = component($props, undefined, slots);
+		let html;
+		try {
+			let { body, head } = component($props, undefined, slots);
 
-		// Put the form info in a hidden input so that it can be accessed on the client
-		if (form) {
-			body += `\n<input type="hidden" id="t-form-data" value='${JSON.stringify(form).replaceAll("'", "\\'")}' />`;
+			// Put the form info in a hidden input so that it can be accessed on the client
+			if (form) {
+				body += `\n<input type="hidden" id="t-form-data" value='${JSON.stringify(form).replaceAll("'", "\\'")}' />`;
+			}
+
+			styles += head;
+			html = template.replace("%COMPONENT_BODY%", body).replace("%COMPONENT_HEAD%", styles);
+		} catch (error) {
+			// TODO: Show a proper Error component
+			html = '<span style="color: red">Script syntax error</span><p>' + error + "</p>";
+			console.log(error);
 		}
 
-		styles += head;
-		html = template.replace("%COMPONENT_BODY%", body).replace("%COMPONENT_HEAD%", styles);
-	} catch (error) {
-		// TODO: Show a proper Error component
-		html = '<span style="color: red">Script syntax error</span><p>' + error + "</p>";
-		console.log(error);
-	}
+		// A layout that never rendered <slot /> silently drops the whole page
+		// content from the output; find and report the outermost one
+		if (handler.layouts) {
+			const missingLayout = findMissingSlotLayout(handler.layouts, invokedLevels);
+			if (missingLayout !== undefined) {
+				warnMissingSlotContent(missingLayout);
+			}
+		}
 
-	return new Response(html, {
-		status: formStatus ?? 200,
-		headers: {
-			"Content-Type": "text/html",
-		},
-	});
+		return new Response(html, {
+			status: formStatus ?? 200,
+			headers: {
+				"Content-Type": "text/html",
+			},
+		});
+	} finally {
+		// Run exit hooks in reverse order for hooks that were entered
+		while (entered > 0) {
+			entered--;
+			await serverHooks[entered].exit?.(serverParams);
+		}
+	}
 }
 
 async function runAction(
@@ -307,26 +455,72 @@ async function runAction(
 	url: URL,
 	handler: RouteHandler,
 	serverEndPoint: PageServerEndPoint | undefined,
-	params: Record<string, string>,
+	params: Record<string, any>,
 	query: URLSearchParams,
-	template: string,
+	template: string | undefined,
 ) {
 	const actionName = (Array.from(query.keys())[0] || "default").replace(/^\//, "");
 	if (serverEndPoint?.actions) {
 		const action = serverEndPoint.actions[actionName];
 		if (action) {
-			const serverParams = buildServerParams(ev, url, params);
+			if (actionName === "load" || actionName === "params") {
+				// These names are reserved in the endpoint's schema map: `load`
+				// validates the query string and `params` the route params, so
+				// an action with one of these names would get the wrong schema
+				// applied to its form data
+				throw new Error(
+					`The action name "${actionName}" is reserved. ` +
+						`Rename the action (and its schema key, if any), e.g. to "save".`,
+				);
+			}
+			// Route params come from the URL, so a failed validation means the
+			// resource doesn't exist
+			try {
+				params = await validateEndpointParams(serverEndPoint, params);
+			} catch (error) {
+				if (error instanceof ValidationError) return notFound();
+				throw error;
+			}
 
-			if (handler.serverHook) {
-				const serverHook: ServerHook | undefined = (await handler.serverHook()).default;
-				if (serverHook?.handle) {
-					await serverHook.handle(serverParams);
+			let result: Response | undefined | void;
+			try {
+				// If the endpoint declares a schema for this action, validate the
+				// submitted form data up front and reject with 422 if it fails
+				const schema = endpointSchema(serverEndPoint, actionName);
+				const form = schema
+					? await validate(schema, await formDataToRecord(ev.request))
+					: undefined;
+
+				const serverParams = buildServerParams(ev, url, params, form ? { form } : {});
+
+				const serverHooks = await loadServerHooks(handler);
+				let entered = 0;
+				let enterResponse: Response | undefined = undefined;
+				try {
+					// Hooks run from the root down; a hook's enter can return a
+					// Response to short-circuit the action
+					for (; entered < serverHooks.length && !enterResponse; entered++) {
+						const hookResult = await serverHooks[entered].enter?.(serverParams);
+						if (hookResult) {
+							enterResponse = hookResult;
+						}
+					}
+
+					result = enterResponse || (await action(serverParams));
+				} finally {
+					// Run exit hooks in reverse order for hooks that were entered
+					while (entered > 0) {
+						entered--;
+						await serverHooks[entered].exit?.(serverParams);
+					}
 				}
+			} catch (error) {
+				const response = validationErrorResponse(error);
+				if (response) return response;
+				throw error;
 			}
 
-			let result = await action(serverParams);
-
-			if (ev.request.headers.has("x-torpor-form-submit")) {
+			if (ev.request.headers.has("X-Torpor-Form-Submit")) {
 				// If the form was submitted from javascript, just return the
 				// response and it will be handled on the client
 				// TODO: Should we make the user return a response??
@@ -334,10 +528,10 @@ async function runAction(
 
 				// If it's a redirect, we need to stop the browser handling it
 				if (result.status >= 300 && result.status <= 399) {
-					const location = result.headers.get("location") ?? "";
+					const location = result.headers.get("Location") ?? "";
 					result = ok();
-					result.headers.set("x-torpor-form-redirect", "");
-					result.headers.set("location", location);
+					result.headers.set("X-Torpor-Form-Redirect", "");
+					result.headers.set("Location", location);
 				}
 
 				return result;
@@ -348,9 +542,11 @@ async function runAction(
 			) {
 				// If the form was submitted without javascript, and there was
 				// no result, an ok result, or a 4xx error, re-render the view
-				// with the form result
-				// TODO: do not re-run hooks?
-				const newUrl = new URL(url.pathname, url);
+				// with the form result. The server hook already ran around the
+				// action, so it is not run again here
+				// Keep the query string, so that loads validating the query see
+				// the same values as the original GET
+				const newUrl = new URL(url.pathname + url.search, url);
 				const formStatus = result?.status;
 				let formMessage = await result?.text();
 				if (formMessage && result?.headers.get("Content-Type")?.includes("application/json")) {
@@ -366,7 +562,7 @@ async function runAction(
 				// object with whatever info you need
 				$page.form!.status ??= formStatus ?? 0;
 				$page.form!.message ??= formMessage ?? "";
-				return await loadView(ev, newUrl, handler, params, template, formStatus, $page.form);
+				return await loadView(ev, newUrl, handler, params, template, formStatus, $page.form, true);
 			} else {
 				// If the form was submitted without javascript and there was a
 				// redirect or server error, just return the result to handle it
@@ -381,7 +577,7 @@ async function runAction(
 
 async function loadClientAndServerData(
 	url: URL,
-	params: Record<string, string>,
+	params: Record<string, any>,
 	serverParams: ServerLoadEvent,
 	data: Record<string, any>,
 	clientEndPoint?: PageEndPoint,
@@ -414,7 +610,7 @@ async function loadClientAndServerData(
 	}
 }
 
-function buildClientParams(url: URL, params: Record<string, string>, data: Record<string, any>) {
+function buildClientParams(url: URL, params: Record<string, any>, data: Record<string, any>) {
 	return {
 		url,
 		params,
@@ -425,13 +621,26 @@ function buildClientParams(url: URL, params: Record<string, string>, data: Recor
 function buildServerParams(
 	ev: ServerEvent,
 	url: URL,
-	params: Record<string, string>,
+	params: Record<string, any>,
+	values: { json?: unknown; form?: unknown; query?: unknown } = {},
 ): ServerLoadEvent {
 	return {
 		url,
 		params,
 		appData: {},
 		request: ev.request,
+		// The inputs may have been validated already, in which case the request
+		// body has been consumed and the parsed values are returned instead.
+		// Their types come from the endpoint's schemas, so they are loosely
+		// typed here
+		json: (): Promise<any> =>
+			values.json !== undefined ? Promise.resolve(values.json) : ev.json(),
+		form: (): Promise<any> =>
+			values.form !== undefined ? Promise.resolve(values.form) : formDataToRecord(ev.request),
+		query: (): Promise<any> =>
+			values.query !== undefined
+				? Promise.resolve(values.query)
+				: Promise.resolve(searchParamsToRecord(url.searchParams)),
 		cookies: ev.cookies,
 		headers: ev.headers,
 		adapter: ev.adapter,

package/src/state/$page.ts

@@ -6,7 +6,8 @@ const PAGE_SYMBOL: unique symbol = Symbol.for("torp.Page");
 const $page: PageState =
 	// @ts-ignore
 	(globalThis[PAGE_SYMBOL] ??=
-		// TODO: Should use the SSR $watch if entering via serverEntry
+		// The server request path uses `state/$serverPage`, which stores the
+		// same state (same `globalThis` slot) without a reactive proxy
 		$watch(
 			{
 				status: 404,

package/src/state/$serverPage.ts

@@ -0,0 +1,22 @@
+import { $watch } from "@torpor/view/ssr";
+import type PageState from "../types/PageState";
+
+const PAGE_SYMBOL: unique symbol = Symbol.for("torp.Page");
+
+// The server request path has no reactive subscribers, so the state is
+// stored plainly ($watch from `@torpor/view/ssr` is a no-op that returns
+// the object itself) instead of through a reactive proxy. Shares the same
+// `globalThis` slot as the client `$page`, so both variants always see the
+// same state object whichever loads first.
+const $page: PageState =
+	// @ts-ignore
+	(globalThis[PAGE_SYMBOL] ??= $watch({
+		status: 404,
+		url: new URL("http://localhost"),
+		form: undefined,
+		error: {
+			message: "",
+		},
+	}));
+
+export default $page;