akanjs 2.2.13-rc.0 → 2.3.0

package/server/rscWorker.tsx

@@ -6,13 +6,35 @@ 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";
 
@@ -49,7 +71,11 @@ interface UpdateCssAssetsMsg {
   type: "updateCssAssets";
   cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>;
 }
-type InMsg = InitMsg | RenderMsg | CancelMsg | 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" }
@@ -87,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 {
@@ -140,7 +166,9 @@ 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;
@@ -185,6 +213,10 @@ 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;
     }
   }
 
@@ -316,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;
@@ -331,12 +363,13 @@ class RscRenderer {
             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 theme = untrackedCookies().get("theme")?.value;
         const searchParams = RouteTreeBuilder.parseSearchParams(urlObj.search);
         let element: ReactNode;
         if (match) element = await this.#renderMatched(urlObj, match, theme, searchParams);
@@ -344,8 +377,31 @@ class RscRenderer {
         this.#logger.verbose(`render[${requestId}] starting Flight stream`);
         const result = await this.#renderFlightElement(element, msg.clientManifest ?? this.#clientManifest, {
           requestId,
-          collectChunks: cacheKey !== null,
+          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;
@@ -383,6 +439,16 @@ 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;
         }
@@ -396,15 +462,10 @@ class RscRenderer {
         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.chunksCount,
-            theme: responseTheme,
-          });
         this.#logger.verbose(
-          `render[${requestId}] done chunks=${result.chunksCount} 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`,
         );
       });
     } catch (error) {
@@ -441,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;
       }
@@ -527,6 +598,13 @@ class RscRenderer {
       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 };
@@ -539,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" };
@@ -611,6 +693,14 @@ class RscRenderer {
       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 {
@@ -677,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}`);
@@ -719,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 {
@@ -756,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> {
@@ -813,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)}
@@ -824,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>
@@ -842,11 +952,15 @@ class RscRenderer {
     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,
@@ -860,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>
@@ -900,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),
     });
@@ -938,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;
   }
@@ -948,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;
@@ -978,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");

package/server/rscWorkerHost.ts

@@ -5,6 +5,7 @@ import { type AkanI18nConfig, DEFAULT_AKAN_I18N, Logger } from "akanjs/common";
 import type { AkanTheme } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { ClientManifest } from "./artifact";
+import type { RouteCacheRenderState } from "./cachePolicy";
 import type { SsrLateRedirect } from "./ssrTypes";
 import type { BaseBuildArtifact, CssAsset } from "./types";
 
@@ -15,6 +16,7 @@ export interface RscPending {
   onEnd: () => void;
   onError: (message: string) => void;
   onMeta?: (meta: { theme?: AkanTheme; status?: number }) => void;
+  onCacheState?: (state: RouteCacheRenderState) => void;
   onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
   onLateRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
   onNotFound?: () => void;
@@ -23,6 +25,11 @@ export interface RscPending {
 export type RscRedirectMethod = "replace" | "push";
 export type RscRedirectStatus = 303 | 307 | 308;
 
+export interface RscWorkerInvalidateCacheMessage {
+  type: "invalidate-cache";
+  reason?: string;
+}
+
 export type RscRenderResult =
   | {
       type: "stream";
@@ -30,6 +37,7 @@ export type RscRenderResult =
       theme?: AkanTheme;
       status?: number;
       lateControl: Promise<SsrLateRedirect | null>;
+      cacheState: Promise<RouteCacheRenderState>;
       cancel: (reason?: unknown) => void;
     }
   | { type: "redirect"; location: string; method: RscRedirectMethod; status: RscRedirectStatus }
@@ -64,6 +72,10 @@ export function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) =>
   };
 }
 
+export function createRscWorkerInvalidateCacheMessage(reason?: string): RscWorkerInvalidateCacheMessage {
+  return reason ? { type: "invalidate-cache", reason } : { type: "invalidate-cache" };
+}
+
 export function createRscHostRenderStream(input: {
   setPending: (pending: RscPending) => void;
   deletePending: () => void;
@@ -78,15 +90,25 @@ export function createRscHostRenderStream(input: {
   let theme: AkanTheme | undefined;
   let status: number | undefined;
   let resolveLateControl!: (control: SsrLateRedirect | null) => void;
+  let resolveCacheState!: (state: RouteCacheRenderState) => void;
   const lateControl = new Promise<SsrLateRedirect | null>((resolve) => {
     resolveLateControl = resolve;
   });
+  const cacheState = new Promise<RouteCacheRenderState>((resolve) => {
+    resolveCacheState = resolve;
+  });
   let lateControlSettled = false;
+  let cacheStateSettled = false;
   const settleLateControl = (control: SsrLateRedirect | null) => {
     if (lateControlSettled) return;
     lateControlSettled = true;
     resolveLateControl(control);
   };
+  const settleCacheState = (state: RouteCacheRenderState) => {
+    if (cacheStateSettled) return;
+    cacheStateSettled = true;
+    resolveCacheState(state);
+  };
   const maxPendingChunks = input.maxPendingChunks ?? getRscHostMaxPendingChunks();
   let pendingChunks = 0;
   let removeAbortListener: (() => void) | undefined;
@@ -97,6 +119,7 @@ export function createRscHostRenderStream(input: {
   const cancelRender = createIdempotentRscRenderCancel((reason) => {
     input.deletePending();
     settleLateControl(null);
+    settleCacheState({ cacheable: false, reason: "cancelled" });
     input.cancelRender(reason);
     cleanupAbortListener();
   });
@@ -117,7 +140,7 @@ export function createRscHostRenderStream(input: {
         const settleStream = () => {
           if (settled) return;
           settled = true;
-          resolve({ type: "stream", stream, theme, status, lateControl, cancel: cancelRender });
+          resolve({ type: "stream", stream, theme, status, lateControl, cacheState, cancel: cancelRender });
         };
         input.setPending({
           onMeta: (meta) => {
@@ -140,12 +163,14 @@ export function createRscHostRenderStream(input: {
           },
           onEnd: () => {
             settleLateControl(null);
+            settleCacheState({ cacheable: false, reason: "missing-cache-state" });
             cleanupAbortListener();
             settleStream();
             controller.close();
           },
           onError: (msg) => {
             settleLateControl(null);
+            settleCacheState({ cacheable: false, reason: "error" });
             cleanupAbortListener();
             if (!settled) {
               settled = true;
@@ -156,6 +181,7 @@ export function createRscHostRenderStream(input: {
           },
           onRedirect: (location, method, status) => {
             settleLateControl(null);
+            settleCacheState({ cacheable: false, reason: "redirect" });
             cleanupAbortListener();
             if (!settled) {
               settled = true;
@@ -168,8 +194,12 @@ export function createRscHostRenderStream(input: {
           onLateRedirect: (location, method, status) => {
             settleLateControl({ type: "redirect", location, method, status });
           },
+          onCacheState: (state) => {
+            settleCacheState(state);
+          },
           onNotFound: () => {
             settleLateControl(null);
+            settleCacheState({ cacheable: false, reason: "not-found" });
             cleanupAbortListener();
             if (!settled) {
               settled = true;
@@ -205,6 +235,7 @@ type RscInMsg =
   | { type: "ready" }
   | { type: "reloaded"; buildId: number }
   | { type: "meta"; requestId: string; theme?: AkanTheme; status?: number }
+  | { type: "cache-state"; requestId: string; state: RouteCacheRenderState }
   | { type: "chunk"; requestId: string; data: Uint8Array }
   | { type: "end"; requestId: string }
   | { type: "redirect"; requestId: string; location: string; method?: RscRedirectMethod; status?: RscRedirectStatus }
@@ -386,6 +417,17 @@ export class RscWorker {
     });
   }
 
+  invalidateRouteResultCache(reason?: string): void {
+    if (this.#status !== "ready") return;
+    try {
+      this.#proc.send(createRscWorkerInvalidateCacheMessage(reason));
+    } catch (error) {
+      this.#logger.warn(
+        `rsc worker cache invalidate send failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
   kill(): void {
     this.#killed = true;
     this.#status = "stopped";
@@ -527,6 +569,10 @@ export class RscWorker {
 
   #handleMessage(message: RscInMsg, proc: Bun.Subprocess<"ignore", "inherit", "inherit">): void {
     if (proc !== this.#proc) return;
+    if (message.type === "cache-state") {
+      this.#pending.get(message.requestId)?.onCacheState?.(message.state);
+      return;
+    }
     switch (message.type) {
       case "hello":
 

package/server/rscWorkerReplay.ts

@@ -1,5 +1,8 @@
+import type { RouteCacheRenderState } from "./cachePolicy";
+
 export type CachedRscReplayMessage =
   | { type: "meta"; requestId: string; theme?: string; status?: number }
+  | { type: "cache-state"; requestId: string; state: RouteCacheRenderState }
   | { type: "chunk"; requestId: string; data: Uint8Array }
   | { type: "end"; requestId: string };
 
@@ -12,6 +15,7 @@ export async function replayCachedRscResult(input: {
   chunks: readonly Uint8Array[];
   theme?: string;
   status?: number;
+  cacheState?: RouteCacheRenderState;
   send: (message: CachedRscReplayMessage) => void;
   isCancelled: () => boolean;
   yieldEveryChunks?: number;
@@ -24,6 +28,7 @@ export async function replayCachedRscResult(input: {
   const yieldToHost = input.yieldToHost ?? yieldToHostEventLoop;
   if (input.isCancelled()) return false;
   input.send({ type: "meta", requestId: input.requestId, theme: input.theme, status: input.status });
+  input.send({ type: "cache-state", requestId: input.requestId, state: input.cacheState ?? { cacheable: true } });
   for (let index = 0; index < input.chunks.length; index += 1) {
     if (input.isCancelled()) return false;
     input.send({ type: "chunk", requestId: input.requestId, data: input.chunks[index] });