@mandujs/core 0.19.2 → 0.20.1

package/src/runtime/ppr.ts

@@ -0,0 +1,74 @@
+/**
+ * Mandu Partial Prerendering (PPR)
+ *
+ * Caches the static HTML shell (header, sidebar, layout) at build/first-request time,
+ * then injects fresh dynamic data (loader results) per request.
+ *
+ * Result: TTFB of a static page + freshness of a dynamic page.
+ *
+ * The shell is the expensive part (React render tree traversal).
+ * Data injection is cheap (JSON serialization into a script tag).
+ */
+
+import { escapeJsonForInlineScript } from "./escape";
+import { serializeProps } from "../client/serialize";
+
+/**
+ * PPR shell marker injected at the end of cached HTML.
+ * Everything before this marker is the static shell; everything after
+ * (closing tags, data scripts) is regenerated per request.
+ */
+export const PPR_SHELL_MARKER = "<!--mandu:ppr-split-->";
+
+/**
+ * Strip the closing </body></html> and any trailing whitespace from
+ * a full SSR HTML string, then append the shell marker.
+ * The result is safe to cache and later concatenated with fresh data.
+ */
+export function extractShellHtml(fullHtml: string): string {
+  // Remove trailing </body></html> (case-insensitive, whitespace-tolerant)
+  const trimmed = fullHtml.replace(/<\/body>\s*<\/html>\s*$/i, "");
+  return trimmed + PPR_SHELL_MARKER;
+}
+
+/**
+ * Build a streaming Response that:
+ *   1. Sends the cached shell immediately (near-zero TTFB)
+ *   2. Appends a script tag with fresh loader data
+ *   3. Closes with </body></html>
+ */
+export function createPPRResponse(
+  shellHtml: string,
+  routeId: string,
+  loaderData: unknown,
+): Response {
+  const encoder = new TextEncoder();
+
+  // Build the data payload once; avoid doing work inside the stream callback
+  const serialized = serializeProps({ serverData: loaderData });
+  const escaped = escapeJsonForInlineScript(serialized);
+  const dataScript =
+    `<script>window.__MANDU_DATA__=window.__MANDU_DATA__||{};` +
+    `window.__MANDU_DATA__[${JSON.stringify(routeId)}]=${escaped}</script>`;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // (a) Cached shell -- everything up to the split marker (inclusive)
+      controller.enqueue(encoder.encode(shellHtml));
+      // (b) Fresh data script
+      controller.enqueue(encoder.encode(dataScript));
+      // (c) Close the document
+      controller.enqueue(encoder.encode("</body></html>"));
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "X-Content-Type-Options": "nosniff",
+      "X-Mandu-PPR": "shell-hit",
+    },
+  });
+}

package/src/runtime/server.ts

@@ -10,17 +10,17 @@ import React, { type ReactNode } from "react";
 import path from "path";
 import fs from "fs/promises";
 import { PORTS } from "../constants";
-import {
-  type CacheStore,
-  type CacheStoreStats,
-  type CacheLookupResult,
-  MemoryCacheStore,
-  lookupCache,
-  createCacheEntry,
-  createCachedResponse,
-  getCacheStoreStats,
-  setGlobalCache,
-} from "./cache";
+import {
+  type CacheStore,
+  type CacheStoreStats,
+  type CacheLookupResult,
+  MemoryCacheStore,
+  lookupCache,
+  createCacheEntry,
+  createCachedResponse,
+  getCacheStoreStats,
+  setGlobalCache,
+} from "./cache";
 import {
   createNotFoundResponse,
   createHandlerNotFoundResponse,
@@ -39,7 +39,7 @@ import {
   isCorsRequest,
 } from "./cors";
 import { validateImportPath } from "./security";
-import { KITCHEN_PREFIX, KitchenHandler } from "../kitchen/kitchen-handler";
+import { KITCHEN_PREFIX, KitchenHandler, recordRequest } from "../kitchen/kitchen-handler";
 import {
   type MiddlewareFn,
   type MiddlewareConfig,
@@ -48,6 +48,7 @@ import {
 import { createFetchHandler } from "./handler";
 import { wrapBunWebSocket, type WSUpgradeData } from "../filling/ws";
 import { handleImageRequest } from "./image-handler";
+import { extractShellHtml, createPPRResponse } from "./ppr";
 
 export interface RateLimitOptions {
   windowMs?: number;
@@ -278,7 +279,7 @@ function getMimeType(filePath: string): string {
 }
 
 // ========== Server Options ==========
-export interface ServerOptions {
+export interface ServerOptions {
   port?: number;
   hostname?: string;
   /** 프로젝트 루트 디렉토리 */
@@ -331,13 +332,13 @@ export interface ServerOptions {
    * - CacheStore: 커스텀 캐시 구현체
    * - false/undefined: 캐시 비활성화
    */
-  cache?: boolean | CacheStore;
-  /**
-   * Internal management token for local CLI/runtime control endpoints.
-   * When set, token-protected endpoints such as `/_mandu/cache` become available.
-   */
-  managementToken?: string;
-}
+  cache?: boolean | CacheStore;
+  /**
+   * Internal management token for local CLI/runtime control endpoints.
+   * When set, token-protected endpoints such as `/_mandu/cache` become available.
+   */
+  managementToken?: string;
+}
 
 export interface ManduServer {
   server: Server<undefined>;
@@ -428,11 +429,11 @@ export interface ServerRegistrySettings {
    * - undefined: false로 처리 (404 방지)
    */
   cssPath?: string | false;
-  /** ISR/SWR 캐시 스토어 */
-  cacheStore?: CacheStore;
-  /** Internal management token for local runtime control */
-  managementToken?: string;
-}
+  /** ISR/SWR 캐시 스토어 */
+  cacheStore?: CacheStore;
+  /** Internal management token for local runtime control */
+  managementToken?: string;
+}
 
 export class ServerRegistry {
   readonly apiHandlers: Map<string, ApiHandler> = new Map();
@@ -752,12 +753,12 @@ function createDefaultAppFactory(registry: ServerRegistry) {
 
 // ========== Static File Serving ==========
 
-interface StaticFileResult {
-  handled: boolean;
-  response?: Response;
-}
-
-const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+interface StaticFileResult {
+  handled: boolean;
+  response?: Response;
+}
+
+const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
 
 function createStaticErrorResponse(status: 400 | 403 | 404 | 500): Response {
   const body = {
@@ -811,7 +812,7 @@ async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean
  *
  * 보안: Path traversal 공격 방지를 위해 모든 경로를 검증합니다.
  */
-async function serveStaticFile(pathname: string, settings: ServerRegistrySettings, request?: Request): Promise<StaticFileResult> {
+async function serveStaticFile(pathname: string, settings: ServerRegistrySettings, request?: Request): Promise<StaticFileResult> {
   let filePath: string | null = null;
   let isBundleFile = false;
   let allowedBaseDir: string;
@@ -924,100 +925,124 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
   } catch {
     return { handled: true, response: createStaticErrorResponse(500) };
   }
-}
-
-// ========== Request Handler ==========
-
-function unauthorizedControlResponse(): Response {
-  return Response.json({ error: "Unauthorized runtime control request" }, { status: 401 });
-}
-
-function resolveInternalCacheTarget(payload: Record<string, unknown>): string {
-  if (typeof payload.path === "string" && payload.path.length > 0) {
-    return `path=${payload.path}`;
-  }
-  if (typeof payload.tag === "string" && payload.tag.length > 0) {
-    return `tag=${payload.tag}`;
-  }
-  if (payload.all === true) {
-    return "all";
-  }
-  return "unknown";
-}
-
-async function handleInternalCacheControlRequest(
-  req: Request,
-  settings: ServerRegistrySettings
-): Promise<Response> {
-  const expectedToken = settings.managementToken;
-  const providedToken = req.headers.get("x-mandu-control-token");
-
-  if (!expectedToken || providedToken !== expectedToken) {
-    return unauthorizedControlResponse();
-  }
-
-  const store = settings.cacheStore ?? null;
-  if (!store) {
-    return Response.json({
-      enabled: false,
-      message: "Runtime cache is disabled for this server instance.",
-      stats: null,
-    });
-  }
-
-  if (req.method === "GET") {
-    const stats = getCacheStoreStats(store);
-    return Response.json({
-      enabled: true,
-      message: "Runtime cache is available.",
-      stats,
-    });
-  }
-
-  if (req.method === "POST" || req.method === "DELETE") {
-    let payload: Record<string, unknown> = {};
-    if (req.method === "POST") {
-      try {
-        payload = await req.json() as Record<string, unknown>;
-      } catch {
-        return Response.json({ error: "Invalid JSON body" }, { status: 400 });
-      }
-    } else {
-      payload = { all: true };
-    }
-
-    const before = store.size;
-    if (typeof payload.path === "string" && payload.path.length > 0) {
-      store.deleteByPath(payload.path);
-    } else if (typeof payload.tag === "string" && payload.tag.length > 0) {
-      store.deleteByTag(payload.tag);
-    } else if (payload.all === true) {
-      store.clear();
-    } else {
-      return Response.json({
-        error: "Provide one of: { path }, { tag }, or { all: true }",
-      }, { status: 400 });
-    }
-
-    const after = store.size;
-    const stats: CacheStoreStats | null = getCacheStoreStats(store);
-
-    return Response.json({
-      enabled: true,
-      cleared: Math.max(0, before - after),
-      target: resolveInternalCacheTarget(payload),
-      stats,
-    });
-  }
-
-  return Response.json({ error: "Method not allowed" }, { status: 405 });
-}
-
-async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
+}
+
+// ========== Request Handler ==========
+
+function unauthorizedControlResponse(): Response {
+  return Response.json({ error: "Unauthorized runtime control request" }, { status: 401 });
+}
+
+function resolveInternalCacheTarget(payload: Record<string, unknown>): string {
+  if (typeof payload.path === "string" && payload.path.length > 0) {
+    return `path=${payload.path}`;
+  }
+  if (typeof payload.tag === "string" && payload.tag.length > 0) {
+    return `tag=${payload.tag}`;
+  }
+  if (payload.all === true) {
+    return "all";
+  }
+  return "unknown";
+}
+
+async function handleInternalCacheControlRequest(
+  req: Request,
+  settings: ServerRegistrySettings
+): Promise<Response> {
+  const expectedToken = settings.managementToken;
+  const providedToken = req.headers.get("x-mandu-control-token");
+
+  if (!expectedToken || providedToken !== expectedToken) {
+    return unauthorizedControlResponse();
+  }
+
+  const store = settings.cacheStore ?? null;
+  if (!store) {
+    return Response.json({
+      enabled: false,
+      message: "Runtime cache is disabled for this server instance.",
+      stats: null,
+    });
+  }
+
+  if (req.method === "GET") {
+    const stats = getCacheStoreStats(store);
+    return Response.json({
+      enabled: true,
+      message: "Runtime cache is available.",
+      stats,
+    });
+  }
+
+  if (req.method === "POST" || req.method === "DELETE") {
+    let payload: Record<string, unknown> = {};
+    if (req.method === "POST") {
+      try {
+        payload = await req.json() as Record<string, unknown>;
+      } catch {
+        return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+      }
+    } else {
+      payload = { all: true };
+    }
+
+    const before = store.size;
+    if (typeof payload.path === "string" && payload.path.length > 0) {
+      store.deleteByPath(payload.path);
+    } else if (typeof payload.tag === "string" && payload.tag.length > 0) {
+      store.deleteByTag(payload.tag);
+    } else if (payload.all === true) {
+      store.clear();
+    } else {
+      return Response.json({
+        error: "Provide one of: { path }, { tag }, or { all: true }",
+      }, { status: 400 });
+    }
+
+    const after = store.size;
+    const stats: CacheStoreStats | null = getCacheStoreStats(store);
+
+    return Response.json({
+      enabled: true,
+      cleared: Math.max(0, before - after),
+      target: resolveInternalCacheTarget(payload),
+      stats,
+    });
+  }
+
+  return Response.json({ error: "Method not allowed" }, { status: 405 });
+}
+
+async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
+  const requestStart = Date.now();
   const result = await handleRequestInternal(req, router, registry);
 
   if (!result.ok) {
-    return errorToResponse(result.error, registry.settings.isDev);
+    const errorResponse = errorToResponse(result.error, registry.settings.isDev);
+    if (registry.settings.isDev) {
+      const url = new URL(req.url);
+      const p = url.pathname;
+      if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen")) {
+        const elapsed = Date.now() - requestStart;
+        console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${errorResponse.status} ${elapsed}ms`);
+        recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status: errorResponse.status, duration: elapsed, timestamp: Date.now() });
+      }
+    }
+    return errorResponse;
+  }
+
+  if (registry.settings.isDev) {
+    const url = new URL(req.url);
+    const p = url.pathname;
+    if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen")) {
+      const elapsed = Date.now() - requestStart;
+      const status = result.value.status;
+      const cacheHdr = result.value.headers.get("X-Mandu-Cache") ?? "";
+      const cacheTag = cacheHdr ? ` ${cacheHdr}` : "";
+      console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${status} ${elapsed}ms${cacheTag}`);
+      recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status, duration: elapsed, timestamp: Date.now(), cacheStatus: cacheHdr || undefined });
+    }
   }
 
   return result.value;
@@ -1399,8 +1424,25 @@ async function handlePageRoute(
   // _data 요청 (SPA 네비게이션)은 캐시하지 않음
   const isDataRequest = url.searchParams.has("_data");
 
+  // PPR: cached shell + fresh dynamic data per request
+  if (renderMode === "ppr" && cache && !isDataRequest) {
+    const shellCacheKey = `ppr-shell:${route.id}`;
+    const cachedShell = cache.get(shellCacheKey);
+
+    if (cachedShell) {
+      // Shell HIT: load only the dynamic data (cheap), skip full SSR render
+      const loadResult = await loadPageData(req, route, params, registry);
+      if (!loadResult.ok) return loadResult;
+      const { loaderData, cookies } = loadResult.value;
+      const pprResponse = createPPRResponse(cachedShell.html, route.id, loaderData);
+      return ok(cookies ? cookies.applyToResponse(pprResponse) : pprResponse);
+    }
+
+    // Shell MISS: fall through to full render, then cache the shell below
+  }
+
   // ISR/SWR 캐시 확인 (SSR 렌더링 요청에만 적용)
-  if (cache && !isDataRequest && renderMode !== "dynamic") {
+  if (cache && !isDataRequest && renderMode !== "dynamic" && renderMode !== "ppr") {
     const cacheKey = buildRouteCacheKey(route.id, url);
     const lookup = lookupCache(cache, cacheKey);
 
@@ -1454,8 +1496,22 @@ async function handlePageRoute(
   // 3. SSR 렌더링 (layoutData 전달)
   const ssrResult = await renderPageSSR(route, params, loaderData, req.url, registry, cookies, layoutData);
 
-  // 4. 캐시 저장 (revalidate 설정이 있는 경우 — non-blocking)
-  if (cache && ssrResult.ok && renderMode !== "dynamic") {
+  // 4a. PPR: cache only the shell (HTML structure minus loader data), not the full page
+  if (cache && ssrResult.ok && renderMode === "ppr") {
+    const cacheOptions = getCacheOptionsForRoute(route.id, registry);
+    const revalidate = cacheOptions?.revalidate ?? 3600; // default 1 hour for PPR shells
+    const shellCacheKey = `ppr-shell:${route.id}`;
+    const cloned = ssrResult.value.clone();
+    cloned.text().then((html) => {
+      const shellHtml = extractShellHtml(html);
+      cache.set(shellCacheKey, createCacheEntry(
+        shellHtml, null, revalidate, cacheOptions?.tags ?? []
+      ));
+    }).catch(() => {});
+  }
+
+  // 4b. ISR/SWR 캐시 저장 (revalidate 설정이 있는 경우 — non-blocking)
+  if (cache && ssrResult.ok && renderMode !== "dynamic" && renderMode !== "ppr") {
     const cacheOptions = getCacheOptionsForRoute(route.id, registry);
     if (cacheOptions?.revalidate && cacheOptions.revalidate > 0) {
       const cloned = ssrResult.value.clone();
@@ -1605,18 +1661,18 @@ async function handleRequestInternal(
     return ok(staticResponse);
   }
 
-  // 1.5. Image optimization handler (/_mandu/image)
-  if (pathname === "/_mandu/image") {
-    const imageResponse = await handleImageRequest(req, settings.rootDir, settings.publicDir);
-    if (imageResponse) return ok(imageResponse);
-  }
-
-  // 1.6. Internal runtime cache control endpoint
-  if (pathname === INTERNAL_CACHE_ENDPOINT) {
-    return ok(await handleInternalCacheControlRequest(req, settings));
-  }
-
-  // 2. Kitchen dev dashboard (dev mode only)
+  // 1.5. Image optimization handler (/_mandu/image)
+  if (pathname === "/_mandu/image") {
+    const imageResponse = await handleImageRequest(req, settings.rootDir, settings.publicDir);
+    if (imageResponse) return ok(imageResponse);
+  }
+
+  // 1.6. Internal runtime cache control endpoint
+  if (pathname === INTERNAL_CACHE_ENDPOINT) {
+    return ok(await handleInternalCacheControlRequest(req, settings));
+  }
+
+  // 2. Kitchen dev dashboard (dev mode only)
   if (settings.isDev && pathname.startsWith(KITCHEN_PREFIX) && registry.kitchen) {
     const kitchenResponse = await registry.kitchen.handle(req, pathname);
     if (kitchenResponse) return ok(kitchenResponse);
@@ -1732,10 +1788,10 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     rateLimit = false,
     cssPath: cssPathOption,
     registry = defaultRegistry,
-    guardConfig = null,
-    cache: cacheOption,
-    managementToken,
-  } = options;
+    guardConfig = null,
+    cache: cacheOption,
+    managementToken,
+  } = options;
 
   // cssPath 처리:
   // - string: 해당 경로로 <link> 주입
@@ -1766,11 +1822,11 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     rootDir,
     publicDir,
     cors: corsOptions,
-    streaming,
-    rateLimit: rateLimitOptions,
-    cssPath,
-    managementToken,
-  };
+    streaming,
+    rateLimit: rateLimitOptions,
+    cssPath,
+    managementToken,
+  };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
 

package/src/runtime/ssr.ts

@@ -139,10 +139,23 @@ function generateHydrationScripts(
   }
 
   // Island 번들 modulepreload (성능 최적화 - prefetch only)
-  const bundle = manifest.bundles[routeId];
-  if (bundle) {
-    const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-    scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+  // Per-island bundles take precedence when available
+  const routeIslands = manifest.islands
+    ? Object.values(manifest.islands).filter((ib) => ib.route === routeId)
+    : [];
+
+  if (routeIslands.length > 0) {
+    for (const ib of routeIslands) {
+      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  } else {
+    // Fallback: route-level bundle (backward compat)
+    const bundle = manifest.bundles[routeId];
+    if (bundle) {
+      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
   }
 
   // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)