bosia 1.1.4 → 1.1.6

package/src/core/server.ts

@@ -6,7 +6,7 @@ import { apiRoutes, serverRoutes } from "bosia:routes";
 import { loadPlugins } from "./config.ts";
 import { readArtifact } from "./artifacts.ts";
 import { getPlatform, warmingUp } from "./platform.ts";
-import type { RouteManifest } from "./types.ts";
+import type { RouteManifest, RouteMatch } from "./types.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by renderer.ts via module reference)
 compileRoutes(apiRoutes);
@@ -20,7 +20,18 @@ import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
 import type { CorsConfig } from "./cors.ts";
 import { buildCspHeader, CSP_DIRECTIVES_TEMPLATE, CSP_ENABLED, generateNonce } from "./csp.ts";
-import { isDev, compress, isStaticPath, distManifest, PRECOMPRESSED } from "./html.ts";
+import {
+	isDev,
+	compress,
+	compressBytes,
+	encodeForRequest,
+	isStaticPath,
+	distManifest,
+	PRECOMPRESSED,
+	type Encoded,
+	preloadLinkHeader,
+	compressionOn,
+} from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
 import { stripBase, withBase } from "./basePath.ts";
@@ -28,6 +39,7 @@ import { currentBase } from "./appBase.ts";
 import {
 	buildPrerenderManifest,
 	buildStaticManifest,
+	findOutDirFile,
 	lookupStatic,
 	serveStatic,
 } from "./staticManifest.ts";
@@ -39,6 +51,7 @@ import {
 	cacheGet,
 	cacheSet,
 	coalesceMiss,
+	collectTags,
 	computeCacheKey,
 	deferCacheWrite,
 	serveCached,
@@ -163,7 +176,7 @@ function isValidRoutePath(path: string, origin: string): boolean {
 	}
 }
 
-type DataRequest = { routeUrl: URL; invalidatedBits: string | null };
+type DataRequest = { routeUrl: URL; invalidatedBits: string | null; fresh: boolean };
 
 /**
  * Decode `/__bosia/data/<route>.json` into the page URL it stands for.
@@ -188,14 +201,21 @@ function parseDataRequest(url: URL): DataRequest | "invalid" | null {
 
 	const routeUrl = new URL(routePathStr, url.origin);
 	let invalidatedBits: string | null = null;
+	let fresh = false;
 	for (const [key, val] of url.searchParams.entries()) {
 		if (key === "_invalidated") {
 			invalidatedBits = val;
 			continue;
 		}
+		// Set by the client router when the fetch follows an invalidate():
+		// skip the cached copy, as `?_invalidated` does for page HTML.
+		if (key === "_fresh") {
+			fresh = true;
+			continue;
+		}
 		routeUrl.searchParams.append(key, val);
 	}
-	return { routeUrl, invalidatedBits };
+	return { routeUrl, invalidatedBits, fresh };
 }
 
 /**
@@ -211,9 +231,62 @@ function parseDataRequest(url: URL): DataRequest | "invalid" | null {
  */
 const dataRequests = new WeakMap<Request, DataRequest>();
 
+type RouteMatches = {
+	path: string;
+	pageOnly: boolean;
+	api: RouteMatch<(typeof apiRoutes)[number]> | null;
+	page: RouteMatch<(typeof serverRoutes)[number]> | null;
+	/** handleRequest already looked for a static file at `path` and found none. */
+	staticMiss?: boolean;
+};
+
+/**
+ * Match `path` in resolve()'s order: an API route first (it shadows static
+ * files), then a page unless the path is a static file. A data request only
+ * ever routes to a page.
+ */
+async function matchRoutes(path: string, pageOnly: boolean): Promise<RouteMatches> {
+	if (pageOnly) return { path, pageOnly, api: null, page: findMatch(serverRoutes, path) };
+	const apiMaybe = resolveApiMatch(apiRoutes, path);
+	const api = apiMaybe instanceof Promise ? await apiMaybe : apiMaybe;
+	const page = api || isStaticPath(path) ? null : findMatch(serverRoutes, path);
+	return { path, pageOnly, api, page };
+}
+
+/**
+ * handleRequest matches before the hooks run (so they see `params`) and parks
+ * the result here, keyed like `dataRequests`. resolve() reuses it unless a hook
+ * rewrote the URL, in which case it matches again.
+ */
+const routeMatches = new WeakMap<Request, RouteMatches>();
+
+function routesFor(
+	request: Request,
+	path: string,
+	pageOnly: boolean,
+): RouteMatches | Promise<RouteMatches> {
+	const parked = routeMatches.get(request);
+	if (parked && parked.path === path && parked.pageOnly === pageOnly) return parked;
+	return matchRoutes(path, pageOnly);
+}
+
+const jsonEncoder = new TextEncoder();
+
+/** A page route's `export const cache` flag: the build-time read when it has
+ *  one, otherwise the compiled page module's own export (see renderer.ts). */
+async function pageRouteCacheable(route: (typeof serverRoutes)[number]): Promise<boolean> {
+	const flag = (route as { cache?: boolean | null }).cache;
+	if (flag === true || flag === false) return flag;
+	return (await route.pageModule()).cache !== false;
+}
+
 /**
  * Decode an `_invalidated` bitmask string. Char 0 = page, char i+1 = layout
- * depth i, '1' = run, '0' = skip. Missing/extra chars default to run.
+ * depth i. Only '0' has a meaning; any other char counts as '1'.
+ *   - Page '0': skip the page loader.
+ *   - Layout '0': omit its data from the response. The loader still runs,
+ *     since it may be a guard.
+ * Missing chars count as '1'. Chars past the route's layout count are ignored.
  */
 function buildMaskFromBits(
 	bits: string,
@@ -243,6 +316,56 @@ function parseActionName(url: URL): string {
 const staticManifest = isDev ? null : buildStaticManifest(OUT_DIR);
 const prerenderManifest = isDev ? null : buildPrerenderManifest(OUT_DIR);
 
+/** Serve `path` as a static file, or `null` when there is no such file. */
+async function serveStaticFile(path: string, request: Request): Promise<Response | null> {
+	// Prod fast path: single Map lookup, no per-request stat calls.
+	if (staticManifest) {
+		const hit = lookupStatic(staticManifest, path);
+		return hit ? serveStatic(hit, request) : null;
+	}
+	// Dev: keep the per-request fallthrough so files dropped into `public/`
+	// mid-session are served without a restart. Decode once — filenames on
+	// disk are raw; safePath still runs after so traversal stays blocked.
+	let decodedPath: string;
+	try {
+		decodedPath = decodeURIComponent(path);
+	} catch {
+		return null;
+	}
+	if (decodedPath.startsWith("/dist/client/")) {
+		const resolved = safePath(
+			`${OUT_DIR}/client`,
+			decodedPath.split("?")[0].slice("/dist/client".length),
+		);
+		if (resolved) {
+			const file = Bun.file(resolved);
+			if (await file.exists()) {
+				return new Response(file, { headers: { "Cache-Control": "no-cache" } });
+			}
+		}
+		return null;
+	}
+	const pubPath = safePath("./public", decodedPath);
+	if (pubPath) {
+		const pub = Bun.file(pubPath);
+		if (await pub.exists()) return new Response(pub);
+	}
+	// Same refusals as the prod manifest: never hand out the server bundle,
+	// the user's bundled hooks/config, or build metadata. Matched against the
+	// real directory listing, so no alternative spelling reaches those files.
+	const distPath = findOutDirFile(OUT_DIR, decodedPath);
+	if (distPath) {
+		const dist = Bun.file(distPath);
+		if (await dist.exists()) return new Response(dist);
+	}
+	const staticPath = safePath(`${OUT_DIR}/static`, decodedPath);
+	if (staticPath) {
+		const staticFile = Bun.file(staticPath);
+		if (await staticFile.exists()) return new Response(staticFile);
+	}
+	return null;
+}
+
 async function resolve(event: RequestEvent): Promise<Response> {
 	const { request, url, locals, cookies } = event;
 	const path = url.pathname;
@@ -262,11 +385,15 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// the parse handleRequest parked before the hooks ran is what identifies it.
 	const dataReq = dataRequests.get(request);
 	if (dataReq) {
-		const { routeUrl, invalidatedBits } = dataReq;
+		const { routeUrl, invalidatedBits, fresh } = dataReq;
+		// INVARIANT: once set, releaseDataMiss must fire exactly once — see the
+		// API-route cache below for the same contract.
+		let releaseDataMiss: (() => void) | null = null;
 		try {
-			const pageMatch = findMatch(serverRoutes, routeUrl.pathname);
-			// Build mask from `?_invalidated=<bits>` where char 0 = page,
-			// char i+1 = layout depth i, '1' = run, '0' = skip. Absent → run all.
+			const pageMatch = (await routesFor(request, routeUrl.pathname, true)).page;
+			// Build mask from `?_invalidated=<bits>` — see buildMaskFromBits. A page
+			// '0' skips the page loader; a layout '0' still runs the loader (it may
+			// be a guard) and only leaves its data out. Absent → run and send all.
 			// Mask is sized to the total layout count (matching client `layoutIds`),
 			// not the count of layout servers, so depths without a server loader
 			// still occupy a bit position and stay aligned with the client.
@@ -276,32 +403,8 @@ async function resolve(event: RequestEvent): Promise<Response> {
 						pageMatch?.route ? ((pageMatch.route as any).layoutModules?.length ?? 0) : 0,
 					)
 				: undefined;
-			// Client forwards each skipped layout layer's cached data as
-			// parentSnapshots (depth → data) so downstream loaders see real
-			// parent() data instead of {}. Perf hint only — never authoritative;
-			// authz must read locals. Guarded: undefined for GET / malformed body.
-			let parentSnapshots: Record<number, Record<string, any>> | undefined;
-			if (method !== "GET") {
-				try {
-					const body = await request.json();
-					if (body && typeof body === "object" && body.parentSnapshots) {
-						parentSnapshots = body.parentSnapshots as Record<number, Record<string, any>>;
-					}
-				} catch {
-					parentSnapshots = undefined;
-				}
-			}
 			const runLoad = async () => {
-				const data = await loadRouteData(
-					routeUrl,
-					locals,
-					request,
-					cookies,
-					null,
-					pageMatch,
-					mask,
-					parentSnapshots,
-				);
+				const data = await loadRouteData(routeUrl, locals, request, cookies, null, pageMatch, mask);
 
 				let metadata = null;
 				if (pageMatch) {
@@ -332,6 +435,34 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				return { data, metadata, cookiesAccessed: (cookies as CookieJar).accessed };
 			};
 
+			// ── Response cache for client-navigation data ──
+			// Same contract as page HTML: keyed by URL + identity, plus the mask
+			// (different masks return different slots), tag/path invalidation, and
+			// no CSP. Only GETs use it (the client router only sends GETs); a
+			// `_fresh` fetch after invalidate() skips the read only.
+			const cacheKey =
+				computeCacheKey(routeUrl, request, cookies as CookieJar) +
+				`|data${invalidatedBits ? `|m=${invalidatedBits}` : ""}`;
+			const dataCacheable =
+				CACHE_ENABLED &&
+				!CSP_ENABLED &&
+				!warmingUp &&
+				method === "GET" &&
+				pageMatch !== null &&
+				(await pageRouteCacheable(pageMatch.route));
+			if (dataCacheable && !fresh) {
+				const hit = cacheGet(cacheKey);
+				if (hit) return serveCached(hit, request);
+				const gate = coalesceMiss(cacheKey);
+				if (gate.wait) {
+					await gate.wait;
+					const rehit = cacheGet(cacheKey);
+					if (rehit) return serveCached(rehit, request);
+				} else {
+					releaseDataMiss = gate.release;
+				}
+			}
+
 			// Dedup concurrent identical requests. The key includes the CACHE_KEYS
 			// identity hash, so different users never share a loader result — same
 			// isolation contract as the response cache. The mask is part of the key
@@ -363,13 +494,53 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			// Privacy beats intent: cookie-derived responses stay private even if
 			// a loader set its own cache-control.
 			if (cookiesWereAccessed) extra["cache-control"] = cc;
-			return compress(
-				JSON.stringify({ ...payload, metadata: result.metadata }),
-				"application/json",
-				request,
-				200,
-				extra,
-			);
+			const body = jsonEncoder.encode(JSON.stringify({ ...payload, metadata: result.metadata }));
+
+			// A loader that said not to store its response is taken at its word.
+			const loaderCc = (loaderHeaders["cache-control"] ?? "").toLowerCase();
+			const loaderOptOut = /no-store|no-cache|private/.test(loaderCc);
+			let sent: Encoded | null | undefined;
+			if (
+				dataCacheable &&
+				!loaderOptOut &&
+				(cookies as CookieJar).outgoing.length === 0 &&
+				(CACHE_MAX_BODY_BYTES === 0 || body.length <= CACHE_MAX_BODY_BYTES)
+			) {
+				const tags = collectTags(result.data.layoutDeps ?? null, result.data.pageDeps ?? null);
+				const rel = releaseDataMiss;
+				releaseDataMiss = null;
+				// Encoded once at cache quality and shared by response and entry.
+				const encoded = encodeForRequest(body, request, "cache");
+				sent = encoded;
+				deferCacheWrite(() => {
+					try {
+						const { gzip, brotli } = buildCompressedVariants(
+							body,
+							encoded?.enc === "br"
+								? { brotli: encoded.encoded }
+								: encoded
+									? { gzip: encoded.encoded }
+									: {},
+						);
+						cacheSet(
+							cacheKey,
+							{
+								raw: body,
+								gzip,
+								brotli,
+								contentType: "application/json",
+								status: 200,
+								extraHeaders: extra,
+								tags,
+							},
+							cookies,
+						);
+					} finally {
+						rel?.();
+					}
+				});
+			}
+			return compressBytes(body, "application/json", request, 200, extra, sent);
 		} catch (err) {
 			if (isRedirect(err)) {
 				return compress(
@@ -407,6 +578,8 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				});
 			}
 			return Response.json({ error: "Internal Server Error" }, { status: 500 });
+		} finally {
+			releaseDataMiss?.();
 		}
 	}
 
@@ -423,8 +596,8 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// Matched BEFORE static fallthrough so explicit handlers shadow extension-
 	// based static detection (e.g. `/uploads/[...path]/+server.ts` can serve
 	// `.webp` URLs that would otherwise be intercepted by isStaticPath).
-	const apiMaybe = resolveApiMatch(apiRoutes, path);
-	const apiMatch = apiMaybe instanceof Promise ? await apiMaybe : apiMaybe;
+	const routes = await routesFor(request, path, false);
+	const apiMatch = routes.api;
 	if (apiMatch) {
 		if (warmingUp) return new Response(null, { status: 404 });
 		// INVARIANT: once set, releaseApiMiss must fire exactly once — a missed
@@ -433,15 +606,16 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		let releaseApiMiss: (() => void) | null = null;
 		try {
 			const mod = await apiMatch.route.module();
-			const handler = mod[method];
+			// HEAD falls back to GET (an explicit HEAD export still wins). BosiaApp
+			// strips the body on the way out, for every route kind.
+			const handler = mod[method] ?? (method === "HEAD" ? mod.GET : undefined);
 
 			if (!handler) {
-				const allowed = Object.keys(mod)
-					.filter((k) => /^[A-Z]+$/.test(k))
-					.join(", ");
+				const allowed = Object.keys(mod).filter((k) => /^[A-Z]+$/.test(k));
+				if (allowed.includes("GET") && !allowed.includes("HEAD")) allowed.push("HEAD");
 				return Response.json(
 					{ error: `Method ${method} not allowed` },
-					{ status: 405, headers: { Allow: allowed } },
+					{ status: 405, headers: { Allow: allowed.join(", ") } },
 				);
 			}
 
@@ -450,15 +624,23 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			// ── Response cache for +server.ts GET handlers ──
 			// CSP is skipped because cached responses would ship with a stale
 			// nonce (see renderer.ts for the same gate). The cache key includes
-			// URL + identity so per-user responses stay isolated.
-			const apiCacheable =
-				CACHE_ENABLED && !CSP_ENABLED && (mod as any).cache !== false && method === "GET";
+			// URL + identity so per-user responses stay isolated. HEAD reads the GET
+			// entry but never coalesces or writes: it isn't a leader that fills it.
+			// An explicit HEAD export skips the cache so it always runs.
+			const apiCacheRead =
+				CACHE_ENABLED &&
+				!CSP_ENABLED &&
+				(mod as any).cache !== false &&
+				(method === "GET" || (method === "HEAD" && !mod.HEAD));
+			const apiCacheable = apiCacheRead && method === "GET";
 			let apiCacheKey: string | null = null;
-			if (apiCacheable) {
+			if (apiCacheRead) {
 				apiCacheKey = computeCacheKey(url, request, cookies as CookieJar);
 				if (!url.searchParams.has("_invalidated")) {
 					const hit = cacheGet(apiCacheKey);
 					if (hit) return serveCached(hit, request);
+				}
+				if (apiCacheable && !url.searchParams.has("_invalidated")) {
 					// Miss coalescing: first miss runs the handler; concurrent misses
 					// wait, re-check the cache, and on a still-miss run independently.
 					const gate = coalesceMiss(apiCacheKey);
@@ -475,6 +657,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			const handlerResult = await handler({
 				request,
 				params: apiMatch.params,
+				route: { id: apiMatch.route.id },
 				url,
 				locals,
 				cookies,
@@ -585,51 +768,15 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	}
 
 	// Static files — fallthrough after API routes so explicit handlers win.
+	// handleRequest already served hits before the hooks; this answers a URL a
+	// hook rewrote, and the 404 for a miss (without looking a second time).
 	if (isStaticPath(path)) {
-		// Prod fast path: single Map lookup, no per-request stat calls.
-		if (staticManifest) {
-			const hit = lookupStatic(staticManifest, path);
-			if (hit) return serveStatic(hit, request);
-			return new Response("Not Found", { status: 404 });
-		}
-		// Dev: keep the per-request fallthrough so files dropped into `public/`
-		// mid-session are served without a restart. Decode once — filenames on
-		// disk are raw; safePath still runs after so traversal stays blocked.
-		let decodedPath: string;
-		try {
-			decodedPath = decodeURIComponent(path);
-		} catch {
-			return new Response("Not Found", { status: 404 });
-		}
-		if (decodedPath.startsWith("/dist/client/")) {
-			const resolved = safePath(
-				`${OUT_DIR}/client`,
-				decodedPath.split("?")[0].slice("/dist/client".length),
-			);
-			if (resolved) {
-				const file = Bun.file(resolved);
-				if (await file.exists()) {
-					return new Response(file, { headers: { "Cache-Control": "no-cache" } });
-				}
-			}
-			return new Response("Not Found", { status: 404 });
-		}
-		const pubPath = safePath("./public", decodedPath);
-		if (pubPath) {
-			const pub = Bun.file(pubPath);
-			if (await pub.exists()) return new Response(pub);
-		}
-		const distPath = safePath(OUT_DIR, decodedPath);
-		if (distPath) {
-			const dist = Bun.file(distPath);
-			if (await dist.exists()) return new Response(dist);
-		}
-		const staticPath = safePath(`${OUT_DIR}/static`, decodedPath);
-		if (staticPath) {
-			const staticFile = Bun.file(staticPath);
-			if (await staticFile.exists()) return new Response(staticFile);
-		}
-		return new Response("Not Found", { status: 404 });
+		const parked = routeMatches.get(request);
+		const missed = parked?.staticMiss && parked.path === path;
+		return (
+			(missed ? null : await serveStaticFile(path, request)) ??
+			new Response("Not Found", { status: 404 })
+		);
 	}
 
 	// Prerendered pages — serve static HTML built at build time.
@@ -644,15 +791,19 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		const key = path === "/" ? "/" : path.replace(/\/$/, "");
 		const hit = prerenderManifest.get(key);
 		if (hit) {
+			// Stylesheets only: whether this page hydrates isn't known here, and a
+			// hint for a script it never runs is a wasted download.
+			const link = preloadLinkHeader(undefined, false);
 			return serveStatic(hit, request, {
 				"Content-Type": "text/html; charset=utf-8",
 				"Cache-Control": "public, max-age=3600",
+				...(link ? { Link: link } : {}),
 			});
 		}
 	}
 
-	// Resolve the page route once; reuse for trailing-slash, form-action, and SSR phases.
-	const pageMatch = findMatch(serverRoutes, path);
+	// Matched once before the hooks; reused for trailing-slash, form-action, and SSR phases.
+	const pageMatch = routes.page;
 
 	// Trailing-slash canonicalization — 308 preserves method (form POSTs included)
 	if (pageMatch) {
@@ -677,6 +828,15 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			try {
 				const mod = await pageMatch.route.pageServer();
 				if (mod.actions && typeof mod.actions === "object") {
+					// Layout loaders gate route groups (`(private)/+layout.server.ts`
+					// redirecting anonymous visitors), so they run before any action:
+					// a POST must not reach code the same visitor could not GET.
+					// Their data is discarded; a redirect or error() they throw is
+					// handled by the catch below exactly like one from the action.
+					await loadRouteData(url, locals, request, cookies, null, pageMatch, {
+						page: false,
+						layouts: [],
+					});
 					const actionName = parseActionName(url);
 					const action = mod.actions[actionName];
 					if (!action) {
@@ -704,6 +864,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 					}
 
 					event.params = pageMatch.params;
+					event.route = { id: pageMatch.route.id };
 					let result: any;
 					try {
 						result = await action(event);
@@ -971,11 +1132,38 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 			url: dataReq ? dataReq.routeUrl : url,
 			locals: { nonce },
 			params: {},
+			route: { id: null },
 			cookies: cookieJar,
 			isDataRequest: dataReq !== null,
 			platform: getPlatform(),
 		};
-		let response =
+
+		// Static files are answered before the hooks: a session-lookup hook would
+		// otherwise cost a DB query per chunk. A miss falls through to the hooks
+		// and resolve(), which 404s. Prerendered pages are pages and stay behind
+		// the hooks. Order mirrors resolve(): framework prefixes first (prod only,
+		// unshadowable), then a user `+server.ts` wins over a same-path file.
+		const path = event.url.pathname;
+		let response: Response | null = null;
+		let staticTried = false;
+		if (!dataReq && staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
+			response = await serveStaticFile(path, request);
+			staticTried = true;
+		}
+		if (!response) {
+			const routes = await matchRoutes(path, dataReq !== null);
+			routeMatches.set(request, routes);
+			const matched = routes.api ?? routes.page;
+			if (matched) {
+				event.params = matched.params;
+				event.route = { id: matched.route.id };
+			}
+			if (!dataReq && !routes.api && isStaticPath(path)) {
+				if (!staticTried) response = await serveStaticFile(path, request);
+				routes.staticMiss = !response;
+			}
+		}
+		response ??=
 			userHandle && !warmingUp ? await userHandle({ event, resolve }) : await resolve(event);
 
 		// A hook that short-circuits a data request with a redirect is answering
@@ -1000,7 +1188,24 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 			}
 		}
 
-		const headers = new Headers(response.headers);
+		// Set on the response itself when its headers are mutable, which every
+		// Response the framework builds has. Copying them and rebuilding the
+		// Response cost a Headers copy plus a body re-wrap on every request.
+		// Responses with immutable headers (`fetch()`, `Response.redirect()`)
+		// still get the copy.
+		// On Workers (compressionOn is false only there) an already-encoded body
+		// is rebuilt as before, since the rebuild is what marks it PRECOMPRESSED.
+		let mutable: Headers | null = null;
+		if (compressionOn || !response.headers.has("content-encoding")) {
+			try {
+				response.headers.set("X-Content-Type-Options", SECURITY_HEADERS["X-Content-Type-Options"]!);
+				mutable = response.headers;
+			} catch {
+				// immutable — copied below
+			}
+		}
+		const inPlace = mutable !== null;
+		const headers = mutable ?? new Headers(response.headers);
 		// A handle can mark a response (e.g. a proxied embeddable preview) to opt
 		// out of the frame guard. Strip the internal marker so it never ships, and
 		// skip only X-Frame-Options for that response — other security headers stay.
@@ -1025,6 +1230,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		}
 		// Apply any Set-Cookie headers accumulated during the request
 		for (const cookie of cookieJar.outgoing) headers.append("Set-Cookie", cookie);
+		if (inPlace) return response;
 		return new Response(response.body, {
 			// A Content-Encoding here means the body is already compressed (cache
 			// hit, compress()); rebuilding drops that flag and Workers would
@@ -1209,6 +1415,7 @@ function loadBuiltManifest(): RouteManifest {
 	return {
 		pages: serverRoutes.map((r: any) => ({
 			pattern: r.pattern,
+			id: r.id,
 			page: "",
 			layouts: [],
 			pageServer: r.pageServer ? "" : null,
@@ -1219,7 +1426,7 @@ function loadBuiltManifest(): RouteManifest {
 			cache: r.cache ?? null,
 			prerender: false,
 		})),
-		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, server: "" })),
+		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, id: r.id, server: "" })),
 		errorPage: null,
 	};
 }
@@ -1229,8 +1436,10 @@ export type CreateAppOptions = {
 	handle?: Handle | null;
 };
 
-const frameworkHandler = ({ request }: { request: Request }) =>
-	handleRequest(request, new URL(request.url));
+// `url` is BosiaApp's own parse of `request.url`; handleRequest rewrites it in
+// place (BASE_PATH, X-Forwarded-*), which is safe because routing already ran.
+const frameworkHandler = ({ request, url }: { request: Request; url: URL }) =>
+	handleRequest(request, url);
 
 /** Build the backend app: plugins, the framework's catch-all routes, error handling. */
 export async function createApp(options: CreateAppOptions = {}): Promise<BosiaApp> {