akanjs 2.3.0 → 2.3.1-rc.0

package/server/rscWorkerCache.ts

@@ -0,0 +1,180 @@
+import {
+  hasRouteCacheInvalidationScope,
+  type LruTtlCache,
+  type RouteCacheEntry,
+  type RouteCacheInvalidation,
+  type RouteCacheRenderState,
+  shouldInvalidateRouteCacheEntry,
+} from "./cachePolicy";
+import type { AkanRouterStateV1, AkanRscPatchDecision, AkanRscPatchMetadata } from "./routeState";
+
+export interface CachedRscResult {
+  chunks: Uint8Array[];
+  bytes: number;
+  chunksCount: number;
+  pathname: string;
+  routeId?: string;
+  tags?: string[];
+  theme?: string;
+  cacheState: RouteCacheRenderState;
+  patch?: CachedRscPatchMetadata;
+}
+
+export interface CachedRscPatchMetadata {
+  targetRouterState: AkanRouterStateV1;
+  patch: AkanRscPatchMetadata;
+}
+
+export interface RscPatchCacheKeyInput {
+  baseEntry: RouteCacheEntry;
+  targetRouterState: AkanRouterStateV1;
+  patch: AkanRscPatchMetadata;
+}
+
+export function createRscPatchCacheKey({ baseEntry, targetRouterState, patch }: RscPatchCacheKeyInput): string {
+  return [
+    "patch-v1",
+    baseEntry.key,
+    targetRouterState.buildId ?? "",
+    targetRouterState.href,
+    targetRouterState.routeId,
+    JSON.stringify(targetRouterState.segments),
+    patch.patchStartIndex,
+    patch.patchStartSegmentKey,
+    JSON.stringify(patch.segmentPath),
+    patch.headSafe === true ? "head-safe" : "head-unsafe",
+  ].join("\n");
+}
+
+export function createRscPatchCacheEntry(input: RscPatchCacheKeyInput): RouteCacheEntry {
+  return { key: createRscPatchCacheKey(input), ttl: input.baseEntry.ttl };
+}
+
+export function isRscPatchResultCacheEligible(input: {
+  partialCommitEnabled: boolean;
+  patch?: AkanRscPatchMetadata;
+}): boolean {
+  return (
+    input.partialCommitEnabled &&
+    input.patch?.headSafe === true &&
+    input.patch.headSnapshot !== undefined &&
+    !input.patch.headSnapshotFailure
+  );
+}
+
+export function createCachedRscPatchMetadata(input: {
+  targetRouterState: AkanRouterStateV1;
+  patch: AkanRscPatchMetadata;
+}): CachedRscPatchMetadata {
+  return {
+    targetRouterState: input.targetRouterState,
+    patch: input.patch,
+  };
+}
+
+export function isCachedRscPatchMetadataCompatible(input: {
+  cached?: CachedRscPatchMetadata;
+  targetRouterState: AkanRouterStateV1 | null;
+  safePatchDecision: AkanRscPatchDecision;
+}): boolean {
+  if (!input.cached || !input.targetRouterState || input.safePatchDecision.status !== "patch") return false;
+  const currentPatch = input.safePatchDecision.patch;
+  if (!currentPatch) return false;
+  const cachedPatch = input.cached.patch;
+  return (
+    input.cached.targetRouterState.buildId === input.targetRouterState.buildId &&
+    input.cached.targetRouterState.href === input.targetRouterState.href &&
+    input.cached.targetRouterState.routeId === input.targetRouterState.routeId &&
+    JSON.stringify(input.cached.targetRouterState.segments) === JSON.stringify(input.targetRouterState.segments) &&
+    cachedPatch.patchStartIndex === currentPatch.patchStartIndex &&
+    cachedPatch.patchStartSegmentKey === currentPatch.patchStartSegmentKey &&
+    JSON.stringify(cachedPatch.segmentPath) === JSON.stringify(currentPatch.segmentPath) &&
+    cachedPatch.headSafe === true &&
+    cachedPatch.headSnapshot !== undefined &&
+    !cachedPatch.headSnapshotFailure
+  );
+}
+
+export function createRscWorkerCachedPatchReplayDecision(input: {
+  cached: CachedRscPatchMetadata;
+  safePatchDecision: AkanRscPatchDecision;
+}): AkanRscPatchDecision {
+  return {
+    ...input.safePatchDecision,
+    patch: input.cached.patch,
+  };
+}
+
+export function resolveRscWorkerPatchCacheEntry(input: {
+  cacheEntry: RouteCacheEntry | null;
+  targetRouterState: AkanRouterStateV1 | null;
+  safePatchDecision: AkanRscPatchDecision;
+  partialCommitEnabled: boolean;
+}): RouteCacheEntry | null {
+  const patch = input.safePatchDecision.status === "patch" ? input.safePatchDecision.patch : undefined;
+  if (
+    !input.cacheEntry ||
+    !input.targetRouterState ||
+    input.safePatchDecision.status !== "patch" ||
+    !patch ||
+    !isRscPatchResultCacheEligible({ partialCommitEnabled: input.partialCommitEnabled, patch })
+  ) {
+    return null;
+  }
+  return createRscPatchCacheEntry({
+    baseEntry: input.cacheEntry,
+    targetRouterState: input.targetRouterState,
+    patch,
+  });
+}
+
+export function shouldCollectRscWorkerRenderChunks(input: {
+  cacheEntry: RouteCacheEntry | null;
+  effectivePatchDecision: AkanRscPatchDecision;
+  patchCacheEntry: RouteCacheEntry | null;
+}): boolean {
+  return (
+    input.cacheEntry !== null && (input.effectivePatchDecision.status !== "patch" || input.patchCacheEntry !== null)
+  );
+}
+
+export function shouldStoreRscWorkerPatchResult(input: {
+  cacheEntry: RouteCacheEntry | null;
+  patchCacheEntry: RouteCacheEntry | null;
+  effectivePatchDecision: AkanRscPatchDecision;
+  storeTtl: number | null;
+}): boolean {
+  return (
+    input.cacheEntry !== null &&
+    input.patchCacheEntry !== null &&
+    input.storeTtl !== null &&
+    input.effectivePatchDecision.status === "patch"
+  );
+}
+
+export function shouldUseRscWorkerFullResultCache(input: {
+  cacheEntry: RouteCacheEntry | null;
+  patchCacheEntry: RouteCacheEntry | null;
+}): boolean {
+  return input.cacheEntry !== null && input.patchCacheEntry === null;
+}
+
+export function invalidateCachedRscResults(
+  cache: LruTtlCache<CachedRscResult>,
+  invalidation: RouteCacheInvalidation,
+): void {
+  if (!hasRouteCacheInvalidationScope(invalidation)) {
+    cache.clear();
+    return;
+  }
+  cache.invalidate((_key, result) =>
+    shouldInvalidateRouteCacheEntry(
+      {
+        pathname: result.pathname,
+        routeId: result.routeId,
+        tags: result.tags,
+      },
+      invalidation,
+    ),
+  );
+}

package/server/rscWorkerHost.ts

@@ -5,8 +5,8 @@ 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 { RouteCacheInvalidation, RouteCacheRenderState } from "./cachePolicy";
+import type { RscTraceMetadata, SsrLateRedirect } from "./ssrTypes";
 import type { BaseBuildArtifact, CssAsset } from "./types";
 
 const DEFAULT_RSC_HOST_MAX_PENDING_CHUNKS = 256;
@@ -15,7 +15,7 @@ export interface RscPending {
   onChunk: (data: Uint8Array) => void;
   onEnd: () => void;
   onError: (message: string) => void;
-  onMeta?: (meta: { theme?: AkanTheme; status?: number }) => void;
+  onMeta?: (meta: { theme?: AkanTheme; status?: number; trace?: RscTraceMetadata }) => void;
   onCacheState?: (state: RouteCacheRenderState) => void;
   onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
   onLateRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
@@ -28,6 +28,8 @@ export type RscRedirectStatus = 303 | 307 | 308;
 export interface RscWorkerInvalidateCacheMessage {
   type: "invalidate-cache";
   reason?: string;
+  tags?: string[];
+  paths?: string[];
 }
 
 export type RscRenderResult =
@@ -36,6 +38,7 @@ export type RscRenderResult =
       stream: ReadableStream<Uint8Array>;
       theme?: AkanTheme;
       status?: number;
+      trace?: RscTraceMetadata;
       lateControl: Promise<SsrLateRedirect | null>;
       cacheState: Promise<RouteCacheRenderState>;
       cancel: (reason?: unknown) => void;
@@ -72,8 +75,17 @@ export function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) =>
   };
 }
 
-export function createRscWorkerInvalidateCacheMessage(reason?: string): RscWorkerInvalidateCacheMessage {
-  return reason ? { type: "invalidate-cache", reason } : { type: "invalidate-cache" };
+export function createRscWorkerInvalidateCacheMessage(
+  invalidation?: string | RouteCacheInvalidation,
+): RscWorkerInvalidateCacheMessage {
+  if (!invalidation) return { type: "invalidate-cache" };
+  if (typeof invalidation === "string") return { type: "invalidate-cache", reason: invalidation };
+  return {
+    type: "invalidate-cache",
+    reason: invalidation.reason,
+    tags: invalidation.tags,
+    paths: invalidation.paths,
+  };
 }
 
 export function createRscHostRenderStream(input: {
@@ -89,6 +101,7 @@ export function createRscHostRenderStream(input: {
   let stream!: ReadableStream<Uint8Array>;
   let theme: AkanTheme | undefined;
   let status: number | undefined;
+  let trace: RscTraceMetadata | undefined;
   let resolveLateControl!: (control: SsrLateRedirect | null) => void;
   let resolveCacheState!: (state: RouteCacheRenderState) => void;
   const lateControl = new Promise<SsrLateRedirect | null>((resolve) => {
@@ -140,12 +153,13 @@ export function createRscHostRenderStream(input: {
         const settleStream = () => {
           if (settled) return;
           settled = true;
-          resolve({ type: "stream", stream, theme, status, lateControl, cacheState, cancel: cancelRender });
+          resolve({ type: "stream", stream, theme, status, trace, lateControl, cacheState, cancel: cancelRender });
         };
         input.setPending({
           onMeta: (meta) => {
             theme = meta.theme;
             status = meta.status;
+            trace = meta.trace;
             settleStream();
           },
           onChunk: (data) => {
@@ -234,7 +248,7 @@ type RscInMsg =
   | { type: "hello" }
   | { type: "ready" }
   | { type: "reloaded"; buildId: number }
-  | { type: "meta"; requestId: string; theme?: AkanTheme; status?: number }
+  | { type: "meta"; requestId: string; theme?: AkanTheme; status?: number; trace?: RscTraceMetadata }
   | { type: "cache-state"; requestId: string; state: RouteCacheRenderState }
   | { type: "chunk"; requestId: string; data: Uint8Array }
   | { type: "end"; requestId: string }
@@ -329,7 +343,7 @@ export class RscWorker {
   };
 
   constructor(artifact: BaseBuildArtifact) {
-    this.#clientManifest = {};
+    this.#clientManifest = artifact.rscRuntimeClientManifest ?? {};
     this.#pagesBundlePath = artifact.pagesBundlePath;
     this.#pagesBundleBuildId = artifact.pagesBundleBuildId;
     this.#cssAssets = artifact.cssAssets ?? {};
@@ -417,10 +431,10 @@ export class RscWorker {
     });
   }
 
-  invalidateRouteResultCache(reason?: string): void {
+  invalidateRouteResultCache(invalidation?: string | RouteCacheInvalidation): void {
     if (this.#status !== "ready") return;
     try {
-      this.#proc.send(createRscWorkerInvalidateCacheMessage(reason));
+      this.#proc.send(createRscWorkerInvalidateCacheMessage(invalidation));
     } catch (error) {
       this.#logger.warn(
         `rsc worker cache invalidate send failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -544,12 +558,24 @@ export class RscWorker {
     this.#status = "starting";
     const workerPath = this.#resolveWorkerPath();
     let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
+    const earlyMessages: RscInMsg[] = [];
     proc = Bun.spawn(["bun", "--conditions", "react-server", workerPath], {
-      ipc: (message: RscInMsg) => this.#handleMessage(message, proc),
+      ipc: (message: RscInMsg) => {
+        if (!proc) {
+          earlyMessages.push(message);
+          return;
+        }
+        this.#handleMessage(message, proc);
+      },
       stdio: ["ignore", "inherit", "inherit"],
       serialization: "advanced",
       env: { ...process.env },
     });
+    if (earlyMessages.length > 0) {
+      setTimeout(() => {
+        for (const message of earlyMessages.splice(0)) this.#handleMessage(message, proc);
+      }, 0);
+    }
     proc.exited.then((code) => this.#handleExit(proc, code));
     return proc;
   }
@@ -603,7 +629,9 @@ export class RscWorker {
         this.#pending.get(message.requestId)?.onChunk(message.data);
         return;
       case "meta":
-        this.#pending.get(message.requestId)?.onMeta?.({ theme: message.theme, status: message.status });
+        this.#pending
+          .get(message.requestId)
+          ?.onMeta?.({ theme: message.theme, status: message.status, trace: message.trace });
         return;
       case "end":
         this.#resolvePending(message.requestId, (p) => p.onEnd());

package/server/rscWorkerReplay.ts

@@ -1,7 +1,8 @@
 import type { RouteCacheRenderState } from "./cachePolicy";
+import type { RscTraceMetadata } from "./ssrTypes";
 
 export type CachedRscReplayMessage =
-  | { type: "meta"; requestId: string; theme?: string; status?: number }
+  | { type: "meta"; requestId: string; theme?: string; status?: number; trace?: RscTraceMetadata }
   | { type: "cache-state"; requestId: string; state: RouteCacheRenderState }
   | { type: "chunk"; requestId: string; data: Uint8Array }
   | { type: "end"; requestId: string };
@@ -15,6 +16,7 @@ export async function replayCachedRscResult(input: {
   chunks: readonly Uint8Array[];
   theme?: string;
   status?: number;
+  trace?: RscTraceMetadata;
   cacheState?: RouteCacheRenderState;
   send: (message: CachedRscReplayMessage) => void;
   isCancelled: () => boolean;
@@ -27,7 +29,14 @@ export async function replayCachedRscResult(input: {
       : 1;
   const yieldToHost = input.yieldToHost ?? yieldToHostEventLoop;
   if (input.isCancelled()) return false;
-  input.send({ type: "meta", requestId: input.requestId, theme: input.theme, status: input.status });
+  const metaMessage: CachedRscReplayMessage = {
+    type: "meta",
+    requestId: input.requestId,
+    theme: input.theme,
+    status: input.status,
+  };
+  if (input.trace) metaMessage.trace = input.trace;
+  input.send(metaMessage);
   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;

package/server/ssrFromRscRenderer.tsx

@@ -1,6 +1,6 @@
 import { Readable } from "node:stream";
 import { type AkanRequestStore, type AkanTheme, pushRequestFallback, requestStorage } from "akanjs/fetch";
-import { type ReactNode, use } from "react";
+import type { ReactNode } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
 import { createFromNodeStream } from "react-server-dom-webpack/client.node";
 import type { SsrChunkRegistryStats, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes";
@@ -121,12 +121,13 @@ export function createSoftRedirectScript(redirect: SsrLateRedirect): string {
 
 function sanitizeFlightRows(
   stream: ReadableStream<Uint8Array>,
-  options: { rewriteStylesheetHints?: boolean } = {},
+  options: { rewriteStylesheetHints?: boolean; dropDebugInfoRows?: boolean } = {},
 ): ReadableStream<Uint8Array> {
   const decoder = new TextDecoder("utf-8", { fatal: true });
   const encoder = new TextEncoder();
   const hlStylesheetRe = /(:HL\["[^"\\]*(?:\\.[^"\\]*)*",)"stylesheet"(\])/g;
   const redirectErrorRowRe = /^([0-9a-z]+):E(\{[^\n]*"digest":"AKAN_REDIRECT(?:;[^"]*)?"[^\n]*\})(\n?)$/;
+  const debugInfoRowRe = /^[0-9a-z]+:D/;
   let buffered: Uint8Array<ArrayBuffer> = new Uint8Array(0);
 
   const concatBytes = (left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer> => {
@@ -143,6 +144,7 @@ function sanitizeFlightRows(
     } catch {
       return row;
     }
+    if (options.dropDebugInfoRows && debugInfoRowRe.test(text)) return new Uint8Array(0);
     const sanitized = (options.rewriteStylesheetHints ? text.replace(hlStylesheetRe, `$1"style"$2`) : text).replace(
       redirectErrorRowRe,
       "$1:null$3",
@@ -180,6 +182,10 @@ export function sanitizeFlightForClientStream(stream: ReadableStream<Uint8Array>
   return sanitizeFlightRows(stream, { rewriteStylesheetHints: true });
 }
 
+export function sanitizeFlightForSsrStream(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  return sanitizeFlightRows(stream, { dropDebugInfoRows: true });
+}
+
 type StderrWrite = typeof process.stderr.write;
 
 export class ExpectedLateRedirectStderrSuppressor {
@@ -445,7 +451,6 @@ export function interleaveRscScriptsWithHtml(
             if (done || errored) break;
             controller.enqueue(value);
             bootstrapDetector.observe(value);
-            flushPendingRscScripts();
           }
         } finally {
           htmlReader.releaseLock();
@@ -578,25 +583,25 @@ export class SsrFromRscRenderer {
 
     const [rscForSsr, rscForClient] = input.rscStream.tee();
 
-    const ssrNodeStream = Readable.fromWeb(sanitizeFlightRows(rscForSsr) as never);
+    const ssrNodeStream = Readable.fromWeb(sanitizeFlightForSsrStream(rscForSsr) as never);
     const stderrSuppressor = ExpectedLateRedirectStderrSuppressor.start(input.lateControl);
     const thenable = SsrFromRscRenderer.#suppressExpectedLateRedirectError(
       createFromNodeStream(ssrNodeStream, input.ssrManifest),
       input.lateControl,
     );
 
-    function Root(): ReactNode {
-      return use(thenable);
-    }
-
     const bootstrap = input.extraBootstrapInline
       ? `${SsrFromRscRenderer.#clientBootstrap}\n${input.extraBootstrapInline}`
       : SsrFromRscRenderer.#clientBootstrap;
 
-    const renderHtml = () =>
-      renderToReadableStream(<Root />, {
+    const renderHtml = async () => {
+      const root = await thenable;
+      const stream = await renderToReadableStream(root, {
         bootstrapScriptContent: bootstrap,
       });
+      await stream.allReady;
+      return stream;
+    };
     const requestContext = input.requestStore ?? input.request;
     const htmlStream =
       requestContext && requestStorage ? await requestStorage.run(requestContext, renderHtml) : await renderHtml();

package/server/ssrTypes.ts

@@ -26,6 +26,24 @@ export interface SsrLateRedirect {
   status: 303 | 307 | 308;
 }
 
+export interface RscTraceMetadata {
+  navId?: string;
+  pathname: string;
+  routeId: string;
+  cache: "hit" | "miss" | "bypass";
+  cacheReason?: string;
+  cacheKeyHash?: string;
+  partial?: "full" | "candidate" | "patch" | "fallback";
+  partialReason?: string;
+  partialCommonPrefixLength?: number;
+  patchStartIndex?: number;
+  patchSegmentPath?: string;
+  patchStartSegment?: string;
+  patchHeadSafe?: boolean;
+  patchHeadSnapshot?: string;
+  routeState?: string;
+}
+
 export interface SsrFromRscInput {
   request?: Request;
   requestStore?: AkanRequestStore;

package/server/types.tsx

@@ -1,5 +1,7 @@
 import type { PromiseOrObject } from "akanjs/base";
 import type { AkanI18nConfig } from "akanjs/common";
+import type { ClientManifest } from "./artifact";
+import type { SsrManifest } from "./ssrTypes";
 
 export type WebsocketRoute = (
   ws: Bun.ServerWebSocket<unknown>,
@@ -85,6 +87,8 @@ export function getAkanImageWidths(config: Pick<AkanImageConfig, "deviceSizes" |
 
 export type BaseBuildArtifact = {
   rscClientUrl: string;
+  rscRuntimeClientManifest?: ClientManifest;
+  rscRuntimeSsrManifest?: SsrManifest;
   vendorMap: Record<string, string>;
   pagesBundlePath: string;
   pagesBundleBuildId: number;