akanjs 2.2.12 → 2.2.13-rc.1

package/server/rscWorker.tsx

@@ -6,13 +6,36 @@ import type {
   RedirectStatus,
 } from "akanjs/client";
 import { type AkanI18nConfig, DEFAULT_AKAN_I18N, getBasePathFromPathname, Logger } from "akanjs/common";
-import { cookies, getRequest, getRequestTheme, requestStorage, updateRequestPolicy } from "akanjs/fetch";
+import {
+  getRequestDynamicUsage,
+  getRequestPolicy,
+  getRequestTheme,
+  requestStorage,
+  untrackedCookies,
+  untrackedRequest,
+  updateRequestPolicy,
+} from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { renderToReadableStream } from "react-server-dom-webpack/server.node";
 import type { ClientManifest } from "./artifact";
+import {
+  createRouteCacheEntry,
+  isPublicRouteCacheableRequest,
+  isRouteCachePathAllowed,
+  LruTtlCache,
+  parsePositiveInt,
+  type RouteCacheEntry,
+  type RouteCacheRenderState,
+  resolveAutoRouteCacheTtl,
+  resolveRouteCacheStoreTtl,
+  shouldStoreRouteCache,
+} from "./cachePolicy";
+import { shouldRenderLocaleAlternates } from "./metadata";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { RouteElementComposer } from "./routeElementComposer";
 import { type PagesContext, RouteTreeBuilder } from "./routeTreeBuilder";
+import { encodeAkanRedirectDigest } from "./rscHttp";
+import { replayCachedRscResult } from "./rscWorkerReplay";
 import { createSystemPageDocument, getSystemPageHomeHref } from "./systemPages";
 
 interface InitMsg {
@@ -32,6 +55,10 @@ interface RenderMsg {
   headers?: Record<string, string>;
   clientManifest?: ClientManifest;
 }
+interface CancelMsg {
+  type: "cancel";
+  requestId: string;
+}
 interface ReloadMsg {
   type: "reload";
   clientManifest: ClientManifest;
@@ -44,11 +71,23 @@ interface UpdateCssAssetsMsg {
   type: "updateCssAssets";
   cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>;
 }
-type InMsg = InitMsg | RenderMsg | ReloadMsg | UpdateCssAssetsMsg;
+interface InvalidateCacheMsg {
+  type: "invalidate-cache";
+  reason?: string;
+}
+type InMsg = InitMsg | RenderMsg | CancelMsg | ReloadMsg | UpdateCssAssetsMsg | InvalidateCacheMsg;
 type RenderControl =
   | { type: "redirect"; location: string; method: "replace" | "push"; status: RedirectStatus }
   | { type: "not-found" }
   | { type: "error"; error: unknown };
+interface FlightRenderResult {
+  chunks: Uint8Array[];
+  bytes: number;
+  chunksCount: number;
+  control: RenderControl | null;
+  lateControlSent: boolean;
+  cancelled: boolean;
+}
 
 interface RscRendererStats {
   renderCount: number;
@@ -74,11 +113,11 @@ interface RouteRenderStats {
 }
 
 interface CachedRscResult {
-  expiresAt: number;
   chunks: Uint8Array[];
   bytes: number;
   chunksCount: number;
   theme?: string;
+  cacheState: RouteCacheRenderState;
 }
 
 export function isAkanRedirectError(error: unknown): error is AkanRedirectError {
@@ -127,7 +166,11 @@ class RscRenderer {
     pagesBundleBuildId: 0,
   };
   readonly #routeStats = new Map<string, RouteRenderStats>();
-  readonly #resultCache = new Map<string, CachedRscResult>();
+  #resultCache = new LruTtlCache<CachedRscResult>(
+    parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+  );
+  readonly #activeRenderReaders = new Map<string, ReadableStreamDefaultReader<Uint8Array>>();
+  readonly #cancelledRenderRequests = new Set<string>();
   #resultCacheHits = 0;
   #resultCacheMisses = 0;
   #resultCacheBypass = 0;
@@ -158,6 +201,10 @@ class RscRenderer {
         this.#logger.verbose(`received render requestId=${msg.requestId} url=${msg.url} method=${msg.method ?? "GET"}`);
         void this.#handleRender(msg);
         return;
+      case "cancel":
+        this.#logger.verbose(`received cancel requestId=${msg.requestId}`);
+        this.#handleCancel(msg.requestId);
+        return;
       case "reload":
         this.#logger.verbose(`received reload buildId=${msg.buildId}`);
         void this.#handleReload(msg);
@@ -166,9 +213,21 @@ class RscRenderer {
         this.#logger.verbose(`received updateCssAssets count=${Object.keys(msg.cssAssets).length}`);
         this.#cssAssets = msg.cssAssets;
         return;
+      case "invalidate-cache":
+        this.#logger.verbose(`received invalidate-cache reason=${msg.reason ?? "(none)"}`);
+        this.#resultCache.clear();
+        return;
     }
   }
 
+  #handleCancel(requestId: string): void {
+    this.#cancelledRenderRequests.add(requestId);
+    const reader = this.#activeRenderReaders.get(requestId);
+    if (!reader) return;
+    void reader.cancel().catch(() => {
+    });
+  }
+
   async #handleInit(msg: InitMsg): Promise<void> {
     const startedAt = Date.now();
     try {
@@ -289,8 +348,8 @@ class RscRenderer {
           );
         else this.#logger.verbose(`render[${requestId}] no route matched pathname=${urlObj.pathname} — rendering 404`);
         const beforeLoadedKeys = RouteTreeBuilder.getCacheStats().loadedModuleKeys;
-        const cacheKey = match ? await this.#getResultCacheKey(request, urlObj, match.pathRoute) : null;
-        const cached = cacheKey ? this.#getCachedResult(cacheKey) : null;
+        const cacheEntry = match ? this.#getResultCacheEntry(request, urlObj) : null;
+        const cached = cacheEntry ? this.#getCachedResult(cacheEntry.key) : null;
         if (cached) {
           this.#stats.lastRenderDurationMs = Date.now() - startedAt;
           this.#stats.lastRenderLoadedModuleDelta = 0;
@@ -300,27 +359,66 @@ class RscRenderer {
           this.#stats.totalFlightBytes += cached.bytes;
           this.#stats.totalFlightChunks += cached.chunksCount;
           this.#recordRouteStats(routeId, cached.bytes, this.#stats.lastRenderDurationMs);
-          this.#send({ type: "meta", requestId, theme: cached.theme });
-          for (const chunk of cached.chunks) this.#send({ type: "chunk", requestId, data: chunk });
-          this.#send({ type: "end", requestId });
+          await replayCachedRscResult({
+            requestId,
+            chunks: cached.chunks,
+            theme: cached.theme,
+            cacheState: cached.cacheState,
+            send: (message) => this.#send(message),
+            isCancelled: () => this.#cancelledRenderRequests.has(requestId),
+          });
           return;
         }
-        const theme = cookies().get("theme")?.value;
-        const element = match ? await this.#renderMatched(urlObj, match, theme) : await this.#renderNotFound(urlObj);
+        const theme = untrackedCookies().get("theme")?.value;
+        const searchParams = RouteTreeBuilder.parseSearchParams(urlObj.search);
+        let element: ReactNode;
+        if (match) element = await this.#renderMatched(urlObj, match, theme, searchParams);
+        else element = await this.#renderNotFound(urlObj);
         this.#logger.verbose(`render[${requestId}] starting Flight stream`);
-        const result = await this.#renderFlightElement(element, msg.clientManifest ?? this.#clientManifest);
+        const result = await this.#renderFlightElement(element, msg.clientManifest ?? this.#clientManifest, {
+          requestId,
+          collectChunks: cacheEntry !== null,
+          status: match ? undefined : 404,
+          onComplete: ({ chunks, bytes, chunksCount, control, lateControlSent }) => {
+            const cacheState = shouldStoreRouteCache({
+              policy: getRequestPolicy(),
+              dynamicUsage: getRequestDynamicUsage(),
+              renderControlType: control?.type,
+              lateRedirect: control?.type === "redirect" && lateControlSent,
+            });
+            const storeTtl = cacheEntry ? resolveRouteCacheStoreTtl(cacheEntry.ttl, cacheState) : null;
+            if (cacheEntry && storeTtl !== null) {
+              this.#setCachedResult(
+                cacheEntry.key,
+                {
+                  chunks,
+                  bytes,
+                  chunksCount,
+                  theme: getRequestTheme(),
+                  cacheState,
+                },
+                storeTtl,
+              );
+            }
+            return cacheState;
+          },
+        });
+        if (result.cancelled) return;
         const control = result.control;
         if (control) {
           this.#stats.lastRenderKind = control.type;
+          if (result.lateControlSent) {
+            this.#logger.verbose(`render[${requestId}] late ${control.type} delivered after stream start`);
+            return;
+          }
           if (!match && control.type === "error") {
             const systemResult = await this.#renderFlightElement(
               this.#renderSystemNotFound(urlObj),
               msg.clientManifest ?? this.#clientManifest,
+              { requestId, status: 404 },
             );
+            if (systemResult.cancelled) return;
             if (!systemResult.control) {
-              this.#send({ type: "meta", requestId, theme: getRequestTheme(), status: 404 });
-              for (const chunk of systemResult.chunks) this.#send({ type: "chunk", requestId, data: chunk });
-              this.#send({ type: "end", requestId });
               return;
             }
           }
@@ -332,7 +430,7 @@ class RscRenderer {
               kind: control.type,
               route: match.pathRoute,
               params: match.params,
-              searchParams: RouteTreeBuilder.parseSearchParams(urlObj.search),
+              searchParams,
               pathname: urlObj.pathname,
               url: urlObj,
               error: control.type === "error" ? control.error : undefined,
@@ -341,34 +439,34 @@ class RscRenderer {
           ) {
             return;
           }
+          if (
+            control.type === "not-found" &&
+            (await this.#trySendSystemNotFoundRender({
+              requestId,
+              url: urlObj,
+              clientManifest: msg.clientManifest ?? this.#clientManifest,
+            }))
+          ) {
+            return;
+          }
           this.#sendRenderControl(requestId, control);
           return;
         }
         this.#stats.lastFlightBytes = result.bytes;
-        this.#stats.lastFlightChunks = result.chunks.length;
+        this.#stats.lastFlightChunks = result.chunksCount;
         this.#stats.totalFlightBytes += result.bytes;
-        this.#stats.totalFlightChunks += result.chunks.length;
+        this.#stats.totalFlightChunks += result.chunksCount;
         this.#stats.lastRenderDurationMs = Date.now() - startedAt;
         const afterLoadedKeys = RouteTreeBuilder.getCacheStats().loadedModuleKeys;
         this.#stats.lastRenderLoadedModules = afterLoadedKeys.filter((key) => !beforeLoadedKeys.includes(key));
         this.#stats.lastRenderLoadedModuleDelta = this.#stats.lastRenderLoadedModules.length;
         this.#recordRouteStats(routeId, result.bytes, this.#stats.lastRenderDurationMs);
         const responseTheme = getRequestTheme();
-        if (cacheKey)
-          this.#setCachedResult(cacheKey, {
-            chunks: result.chunks,
-            bytes: result.bytes,
-            chunksCount: result.chunks.length,
-            theme: responseTheme,
-          });
-        this.#send({ type: "meta", requestId, theme: responseTheme, status: match ? undefined : 404 });
-        for (const chunk of result.chunks) {
-          this.#send({ type: "chunk", requestId, data: chunk });
-        }
         this.#logger.verbose(
-          `render[${requestId}] done chunks=${result.chunks.length} bytes=${result.bytes} in ${Date.now() - startedAt}ms`,
+          `render[${requestId}] done chunks=${result.chunksCount} bytes=${result.bytes} theme=${responseTheme ?? "(none)"} in ${
+            Date.now() - startedAt
+          }ms`,
         );
-        this.#send({ type: "end", requestId });
       });
     } catch (error) {
       if (isAkanRedirectError(error)) {
@@ -404,6 +502,16 @@ class RscRenderer {
         ) {
           return;
         }
+        if (
+          fallbackUrl &&
+          (await this.#trySendSystemNotFoundRender({
+            requestId,
+            url: fallbackUrl,
+            clientManifest: msg.clientManifest ?? this.#clientManifest,
+          }))
+        ) {
+          return;
+        }
         this.#send({ type: "not-found", requestId });
         return;
       }
@@ -435,6 +543,8 @@ class RscRenderer {
         message: error instanceof Error ? error.message : String(error),
       });
     } finally {
+      this.#activeRenderReaders.delete(requestId);
+      this.#cancelledRenderRequests.delete(requestId);
       this.#stats.inFlightRenderCount = Math.max(0, this.#stats.inFlightRenderCount - 1);
     }
   }
@@ -484,7 +594,19 @@ class RscRenderer {
   async #renderFlightElement(
     element: ReactNode,
     clientManifest: ClientManifest,
-  ): Promise<{ chunks: Uint8Array[]; bytes: number; control: RenderControl | null }> {
+    options: {
+      requestId?: string;
+      collectChunks?: boolean;
+      status?: number;
+      onComplete?: (result: {
+        chunks: Uint8Array[];
+        bytes: number;
+        chunksCount: number;
+        control: RenderControl | null;
+        lateControlSent: boolean;
+      }) => Promise<RouteCacheRenderState> | RouteCacheRenderState;
+    } = {},
+  ): Promise<FlightRenderResult> {
     const controlRef: { current: RenderControl | null } = { current: null };
     const stream = await renderToReadableStream(element, clientManifest, {
       onError: (error) => {
@@ -495,7 +617,11 @@ class RscRenderer {
             method: error.method,
             status: error.status,
           };
-          return error.digest;
+          return encodeAkanRedirectDigest({
+            location: error.location,
+            method: error.method,
+            status: error.status,
+          });
         }
         if (isAkanNotFoundError(error)) {
           controlRef.current = { type: "not-found" };
@@ -506,20 +632,85 @@ class RscRenderer {
       },
     });
     const reader = stream.getReader();
+    if (options.requestId) this.#activeRenderReaders.set(options.requestId, reader);
     let bytes = 0;
+    let chunksCount = 0;
+    let sentMeta = false;
+    let sentChunk = false;
+    let lateControlSent = false;
     const chunks: Uint8Array[] = [];
-    while (true) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      if (controlRef.current) {
-        await reader.cancel();
-        break;
+    const sendMeta = () => {
+      if (!options.requestId || sentMeta) return;
+      sentMeta = true;
+      this.#send({ type: "meta", requestId: options.requestId, theme: getRequestTheme(), status: options.status });
+    };
+    const sendLateRedirect = () => {
+      if (!options.requestId || lateControlSent || controlRef.current?.type !== "redirect") return;
+
+      lateControlSent = true;
+      this.#send({
+        type: "late-redirect",
+        requestId: options.requestId,
+        location: controlRef.current.location,
+        method: controlRef.current.method,
+        status: controlRef.current.status,
+      });
+    };
+    try {
+      while (true) {
+        if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
+          await reader.cancel();
+          return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
+        }
+        const { value, done } = await reader.read();
+        if (controlRef.current && !sentChunk) {
+          await reader.cancel();
+          return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
+        }
+        if (controlRef.current && sentChunk) sendLateRedirect();
+        if (done) break;
+        const chunk = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
+        bytes += chunk.byteLength;
+        chunksCount += 1;
+        if (options.collectChunks) chunks.push(chunk);
+        if (options.requestId) {
+          sendMeta();
+          this.#send({ type: "chunk", requestId: options.requestId, data: chunk });
+          sentChunk = true;
+        }
       }
-      const chunk = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
-      bytes += chunk.byteLength;
-      chunks.push(chunk);
+    } catch (error) {
+      if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
+        return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
+      }
+      throw error;
+    } finally {
+      if (options.requestId) this.#activeRenderReaders.delete(options.requestId);
+      reader.releaseLock();
+    }
+    if (controlRef.current && sentChunk) sendLateRedirect();
+    if (controlRef.current && !sentChunk)
+      return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
+    if (options.requestId) {
+      sendMeta();
+      const cacheState = (await options.onComplete?.({
+        chunks,
+        bytes,
+        chunksCount,
+        control: controlRef.current,
+        lateControlSent,
+      })) ?? { cacheable: false, reason: "uncacheable-render" };
+      this.#send({ type: "cache-state", requestId: options.requestId, state: cacheState });
+      this.#send({ type: "end", requestId: options.requestId });
     }
-    return { chunks, bytes, control: controlRef.current };
+    return {
+      chunks,
+      bytes,
+      chunksCount,
+      control: lateControlSent ? controlRef.current : null,
+      lateControlSent,
+      cancelled: false,
+    };
   }
 
   async #trySendFallbackRender({
@@ -555,15 +746,16 @@ class RscRenderer {
         digest: kind === "error" ? "AKAN_RENDER_ERROR" : undefined,
       });
       if (!element) return false;
-      const result = await this.#renderFlightElement(element, clientManifest);
+      const result = await this.#renderFlightElement(element, clientManifest, {
+        requestId,
+        status: kind === "not-found" ? 404 : 500,
+      });
+      if (result.cancelled) return true;
       if (result.control) return false;
-      this.#send({ type: "meta", requestId, theme: getRequestTheme(), status: kind === "not-found" ? 404 : 500 });
-      for (const chunk of result.chunks) this.#send({ type: "chunk", requestId, data: chunk });
-      this.#send({ type: "end", requestId });
       this.#stats.lastFlightBytes = result.bytes;
-      this.#stats.lastFlightChunks = result.chunks.length;
+      this.#stats.lastFlightChunks = result.chunksCount;
       this.#stats.totalFlightBytes += result.bytes;
-      this.#stats.totalFlightChunks += result.chunks.length;
+      this.#stats.totalFlightChunks += result.chunksCount;
       return true;
     } catch (fallbackError) {
       this.#logger.error(
@@ -575,6 +767,37 @@ class RscRenderer {
     }
   }
 
+  async #trySendSystemNotFoundRender({
+    requestId,
+    url,
+    clientManifest,
+  }: {
+    requestId: string;
+    url: URL;
+    clientManifest: ClientManifest;
+  }): Promise<boolean> {
+    try {
+      const result = await this.#renderFlightElement(this.#renderSystemNotFound(url), clientManifest, {
+        requestId,
+        status: 404,
+      });
+      if (result.cancelled) return true;
+      if (result.control) return false;
+      this.#stats.lastFlightBytes = result.bytes;
+      this.#stats.lastFlightChunks = result.chunksCount;
+      this.#stats.totalFlightBytes += result.bytes;
+      this.#stats.totalFlightChunks += result.chunksCount;
+      return true;
+    } catch (error) {
+      this.#logger.error(
+        `render[${requestId}] system not-found fallback failed: ${
+          error instanceof Error ? (error.stack ?? error.message) : String(error)
+        }`,
+      );
+      return false;
+    }
+  }
+
   #sendRenderControl(requestId: string, control: RenderControl): void {
     if (control.type === "redirect") {
       this.#logger.verbose(`render[${requestId}] redirect ${control.location}`);
@@ -617,35 +840,29 @@ class RscRenderer {
       }));
   }
 
-  async #getResultCacheKey(request: Request, url: URL, pathRoute: PathRoute): Promise<string | null> {
-    const config = await pathRoute.renderPage.getPageConfig?.();
-    const ttl = RscRenderer.#normalizeCacheTtl(config?.rscCacheTtl);
-    updateRequestPolicy({
-      rscCache: config?.rscCache,
-      rscCacheTtl: config?.rscCacheTtl,
-      cacheable: config?.rscCache === "public" || ttl !== null,
+  #getResultCacheEntry(request: Request, url: URL): RouteCacheEntry | null {
+    const ttl = resolveAutoRouteCacheTtl({
+      enabled: process.env.AKAN_RSC_RESULT_CACHE,
+      ttl: process.env.AKAN_RSC_RESULT_CACHE_TTL,
     });
-    if (config?.rscCache !== "public" && ttl === null) {
+    if (ttl === null) {
       this.#resultCacheBypass += 1;
       return null;
     }
-    if (ttl === 0) {
+    if (
+      !isRouteCachePathAllowed(url.pathname, {
+        allow: process.env.AKAN_RSC_RESULT_CACHE_PATHS,
+        deny: process.env.AKAN_RSC_RESULT_CACHE_EXCLUDE_PATHS,
+      })
+    ) {
       this.#resultCacheBypass += 1;
       return null;
     }
-    if (!RscRenderer.#isPublicCacheableRequest(request)) {
+    if (!isPublicRouteCacheableRequest(request)) {
       this.#resultCacheBypass += 1;
       return null;
     }
-    return [
-      request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? url.host,
-      request.headers.get("x-base-path") ?? "",
-      url.pathname,
-      url.search,
-      request.headers.get("accept-language") ?? "",
-      cookies().get("theme")?.value ?? "",
-      ttl ?? 30,
-    ].join("\n");
+    return createRouteCacheEntry({ request, url, theme: untrackedCookies().get("theme")?.value, ttl });
   }
 
   #getCachedResult(cacheKey: string): CachedRscResult | null {
@@ -654,27 +871,12 @@ class RscRenderer {
       this.#resultCacheMisses += 1;
       return null;
     }
-    if (cached.expiresAt <= Date.now()) {
-      this.#resultCache.delete(cacheKey);
-      this.#resultCacheMisses += 1;
-      return null;
-    }
     this.#resultCacheHits += 1;
     return cached;
   }
 
-  #setCachedResult(
-    cacheKey: string,
-    result: { chunks: Uint8Array[]; bytes: number; chunksCount: number; theme?: string },
-  ): void {
-    const ttl = Number.parseInt(cacheKey.split("\n").at(-1) ?? "30", 10);
-    const maxEntries = RscRenderer.#parsePositiveIntEnv("AKAN_RSC_RESULT_CACHE_MAX_ENTRIES") ?? 100;
-    while (this.#resultCache.size >= maxEntries) {
-      const firstKey = this.#resultCache.keys().next().value;
-      if (!firstKey) break;
-      this.#resultCache.delete(firstKey);
-    }
-    this.#resultCache.set(cacheKey, { ...result, expiresAt: Date.now() + ttl * 1000 });
+  #setCachedResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
+    this.#resultCache.set(cacheKey, result, ttl);
   }
 
   #runWithRequest<T>(request: Request, fn: () => Promise<T>): Promise<T> {
@@ -711,8 +913,18 @@ class RscRenderer {
       digest,
     });
     if (!body) return null;
-    const routeHead = "resolveHead" in route ? await route.resolveHead?.({ params, searchParams }) : undefined;
-    const theme = cookies().get("theme")?.value;
+    const routeHead =
+      "resolveHead" in route
+        ? await RouteElementComposer.resolveHeadWithMetadata({
+            pathRoute: route,
+            params,
+            searchParams,
+          })
+        : { node: undefined, hasExplicitLanguageAlternates: false };
+    const renderLocaleAlternates = shouldRenderLocaleAlternates({
+      hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
+    });
+    const theme = untrackedCookies().get("theme")?.value;
     return (
       <html
         lang={params.lang ?? RscRenderer.#getLocale(pathname, this.#i18n)}
@@ -722,8 +934,8 @@ class RscRenderer {
           <meta key="charset" charSet="utf-8" />
           <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1" />
           <meta key="robots" name="robots" content="noindex" />
-          {routeHead ?? this.#renderDefaultHead()}
-          {this.#renderLocaleAlternates(url)}
+          {routeHead.node ?? this.#renderDefaultHead()}
+          {renderLocaleAlternates ? this.#renderLocaleAlternates(url) : null}
           {this.#renderStylesheet(pathname)}
         </head>
         <body key="body">{body}</body>
@@ -735,17 +947,25 @@ class RscRenderer {
     url: URL,
     match: { pathRoute: PathRoute; params: Record<string, string> },
     theme?: string,
+    searchParams = RouteTreeBuilder.parseSearchParams(url.search),
   ): Promise<ReactNode> {
-    const searchParams = RouteTreeBuilder.parseSearchParams(url.search);
     this.#logger.verbose(
       `composing route element pathname=${url.pathname} search=${url.search || "(none)"} params=${JSON.stringify(match.params)}`,
     );
-    const routeHead = await RouteElementComposer.resolveHead({
+    const routeHead = await RouteElementComposer.resolveHeadWithMetadata({
+      pathRoute: match.pathRoute,
+      params: match.params,
+      searchParams,
+    });
+    const renderLocaleAlternates = shouldRenderLocaleAlternates({
+      isSpecialRoute: match.pathRoute.isSpecialRoute,
+      hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
+    });
+    const body = RouteElementComposer.compose({
       pathRoute: match.pathRoute,
       params: match.params,
       searchParams,
     });
-    const body = RouteElementComposer.compose({ pathRoute: match.pathRoute, params: match.params, searchParams });
     return (
       <html
         lang={match.params.lang ?? this.#i18n.defaultLocale}
@@ -754,8 +974,8 @@ class RscRenderer {
         <head key="head">
           <meta key="charset" charSet="utf-8" />
           <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1" />
-          {routeHead ?? this.#renderDefaultHead()}
-          {match.pathRoute.isSpecialRoute ? null : this.#renderLocaleAlternates(url)}
+          {routeHead.node ?? this.#renderDefaultHead()}
+          {renderLocaleAlternates ? this.#renderLocaleAlternates(url) : null}
           {this.#renderStylesheet(url.pathname)}
         </head>
         <body key="body">{body}</body>
@@ -794,7 +1014,7 @@ class RscRenderer {
         pathname: url.pathname,
         i18n: this.#i18n,
         basePaths: this.#basePaths,
-        headerBasePath: getRequest()?.headers.get("x-base-path"),
+        headerBasePath: untrackedRequest()?.headers.get("x-base-path"),
       }),
       stylesheetHref: this.#getStylesheetHref(url.pathname),
     });
@@ -832,7 +1052,7 @@ class RscRenderer {
     const basePath = getBasePathFromPathname(pathname, {
       basePaths: Object.keys(this.#cssAssets),
       i18n: this.#i18n,
-      headerBasePath: getRequest()?.headers.get("x-base-path"),
+      headerBasePath: untrackedRequest()?.headers.get("x-base-path"),
     });
     return this.#cssAssets[basePath ?? ""]?.cssUrl ?? null;
   }
@@ -842,29 +1062,6 @@ class RscRenderer {
     return segment && i18n.locales.includes(segment) ? segment : i18n.defaultLocale;
   }
 
-  static #parsePositiveIntEnv(name: string): number | null {
-    const parsed = Number.parseInt(process.env[name] ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-  }
-
-  static #normalizeCacheTtl(value: unknown): number | null {
-    if (value === undefined || value === null) return null;
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
-    return Math.floor(value);
-  }
-
-  static #isPublicCacheableRequest(request: Request): boolean {
-    if (request.method !== "GET") return false;
-    if (request.headers.has("authorization")) return false;
-    const cookie = request.headers.get("cookie");
-    if (!cookie) return true;
-    return cookie
-      .split(";")
-      .map((part) => part.trim().split("=")[0])
-      .filter(Boolean)
-      .every((name) => name === "theme" || name.startsWith("akan_public_"));
-  }
-
   static #errorForFallback(error: unknown): unknown {
     if (process.env.NODE_ENV !== "production") return error;
     return undefined;
@@ -872,7 +1069,7 @@ class RscRenderer {
 
   static #getPublicRequestUrl(url: URL): URL {
     const publicUrl = new URL(url);
-    const req = getRequest();
+    const req = untrackedRequest();
     const headers = req?.headers;
     const host = headers?.get("x-forwarded-host") ?? headers?.get("host");
     const proto = headers?.get("x-forwarded-proto");
@@ -895,4 +1092,4 @@ class RscRenderer {
   }
 }
 
-new RscRenderer().start();
+if (import.meta.main) new RscRenderer().start();