@mandujs/core 0.9.18 → 0.9.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/runtime/streaming-ssr.ts

@@ -22,12 +22,35 @@ import { serializeProps } from "../client/serialize";
 
 /**
  * Streaming SSR 에러 타입
+ *
+ * 에러 정책 (Error Policy):
+ * 1. Stream 생성 실패 (renderToReadableStream throws)
+ *    → renderStreamingResponse에서 catch → 500 Response 반환
+ *    → 이 경우 StreamingError는 생성되지 않음
+ *
+ * 2. Shell 전 React 렌더링 에러 (onError called, shellSent=false)
+ *    → isShellError: true, recoverable: false
+ *    → onShellError 콜백 호출
+ *    → 스트림은 계속 진행 (빈 컨텐츠 or 부분 렌더링)
+ *
+ * 3. Shell 후 스트리밍 에러 (onError called, shellSent=true)
+ *    → isShellError: false, recoverable: true
+ *    → onStreamError 콜백 호출
+ *    → 에러 스크립트가 HTML에 삽입됨
  */
 export interface StreamingError {
   error: Error;
-  /** Shell 전송 전 에러인지 여부 */
+  /**
+   * Shell 전송 전 에러인지 여부
+   * - true: React 초기 렌더링 중 에러 (Shell 전송 전)
+   * - false: 스트리밍 중 에러 (Shell 이미 전송됨)
+   */
   isShellError: boolean;
-  /** 복구 가능 여부 */
+  /**
+   * 복구 가능 여부
+   * - true: Shell 이후 에러 - 에러 스크립트 삽입으로 클라이언트 알림
+   * - false: Shell 전 에러 - 사용자에게 불완전한 UI 표시될 수 있음
+   */
   recoverable: boolean;
   /** 타임스탬프 */
   timestamp: number;
@@ -76,13 +99,23 @@ export interface StreamingSSROptions {
   enableClientRouter?: boolean;
   /** Streaming 타임아웃 (ms) */
   streamTimeout?: number;
-  /** Shell 렌더링 후 콜백 */
+  /** Shell 렌더링 후 콜백 (TTFB 측정 시점) */
   onShellReady?: () => void;
   /** 모든 컨텐츠 렌더링 후 콜백 */
   onAllReady?: () => void;
-  /** Shell 전 에러 콜백 (500 반환 가능) */
+  /**
+   * Shell 전 에러 콜백
+   * - React 초기 렌더링 중 에러 발생 시 호출
+   * - 이 시점에서는 이미 스트림이 시작됨 (500 반환 불가)
+   * - 로깅/모니터링 용도
+   */
   onShellError?: (error: StreamingError) => void;
-  /** 스트리밍 중 에러 콜백 (이미 응답 시작됨 - fallback UI 삽입) */
+  /**
+   * 스트리밍 중 에러 콜백
+   * - Shell 전송 후 에러 발생 시 호출
+   * - 에러 스크립트가 HTML에 자동 삽입됨
+   * - 클라이언트에서 mandu:streaming-error 이벤트로 감지 가능
+   */
   onStreamError?: (error: StreamingError) => void;
   /** 에러 콜백 (deprecated - onShellError/onStreamError 사용 권장) */
   onError?: (error: Error) => void;
@@ -504,16 +537,17 @@ function generateHMRScript(port: number): string {
  * React 컴포넌트를 ReadableStream으로 렌더링
  * Bun/Web Streams API 기반
  *
- * 에러 처리:
- * - Shell 전 에러: onShellError 호출 → 500 응답 가능
- * - Shell 후 에러: onStreamError 호출 → 에러 스크립트 삽입
+ * 핵심 원칙:
+ * - Shell은 즉시 전송 (TTFB 최소화)
+ * - allReady는 메트릭용으로만 사용 (대기 안 함)
+ * - Shell 전 에러는 throw → Response 레이어에서 500 처리
+ * - Shell 후 에러는 에러 스크립트 삽입
  */
 export async function renderToStream(
   element: ReactElement,
   options: StreamingSSROptions = {}
 ): Promise<ReadableStream<Uint8Array>> {
   const {
-    streamTimeout = 10000,
     onShellReady,
     onAllReady,
     onShellError,
@@ -534,7 +568,7 @@ export async function renderToStream(
     startTime: Date.now(),
   };
 
-  // criticalData 직렬화 검증
+  // criticalData 직렬화 검증 (dev에서는 throw)
   validateCriticalData(criticalData, isDev);
 
   // 스트리밍 주의사항 경고 (첫 요청 시 1회만)
@@ -548,65 +582,42 @@ export async function renderToStream(
   const htmlTail = generateHTMLTail(options);
 
   let shellSent = false;
-  let hasShellError = false;
 
   // React renderToReadableStream 호출
-  let reactStream: ReadableStream<Uint8Array>;
-  try {
-    reactStream = await renderToReadableStream(element, {
-      onError: (error: Error) => {
-        metrics.hasError = true;
-        const streamingError: StreamingError = {
-          error,
-          isShellError: !shellSent,
-          recoverable: shellSent, // Shell 후면 복구 가능 (에러 스크립트 삽입)
-          timestamp: Date.now(),
-        };
-
-        console.error("[Mandu Streaming] React render error:", error);
-
-        if (!shellSent) {
-          hasShellError = true;
-          onShellError?.(streamingError);
-        } else {
-          onStreamError?.(streamingError);
-        }
-
-        // deprecated 콜백 호환
-        onError?.(error);
-      },
-    });
-  } catch (error) {
-    // renderToReadableStream 자체 실패 (Shell 전 에러)
-    metrics.hasError = true;
-    const err = error instanceof Error ? error : new Error(String(error));
-    const streamingError: StreamingError = {
-      error: err,
-      isShellError: true,
-      recoverable: false,
-      timestamp: Date.now(),
-    };
+  // 실패 시 throw → renderStreamingResponse에서 500 처리
+  const reactStream = await renderToReadableStream(element, {
+    onError: (error: Error) => {
+      metrics.hasError = true;
+      const streamingError: StreamingError = {
+        error,
+        isShellError: !shellSent,
+        recoverable: shellSent,
+        timestamp: Date.now(),
+      };
 
-    onShellError?.(streamingError);
-    onError?.(err);
+      console.error("[Mandu Streaming] React render error:", error);
 
-    // 에러 응답을 위한 빈 스트림 반환
-    throw err;
-  }
+      if (!shellSent) {
+        // Shell 전 에러 - 콜백만 호출 (throw는 하지 않음, 이미 스트림 시작됨)
+        onShellError?.(streamingError);
+      } else {
+        // Shell 후 에러 - 스트림에 에러 스크립트 삽입됨
+        onStreamError?.(streamingError);
+      }
 
-  // Shell 준비 완료 대기 (타임아웃 포함)
-  const timeoutPromise = new Promise<void>((_, reject) =>
-    setTimeout(() => reject(new Error("Shell render timeout")), streamTimeout)
-  );
+      onError?.(error);
+    },
+  });
 
-  try {
-    await Promise.race([reactStream.allReady, timeoutPromise]);
-  } catch {
-    // Timeout이나 에러 시에도 계속 진행 (이미 일부 렌더링된 경우)
+  // allReady는 백그라운드에서 메트릭용으로만 사용 (대기 안 함!)
+  reactStream.allReady.then(() => {
+    metrics.allReadyTime = Date.now() - metrics.startTime;
     if (isDev) {
-      console.warn("[Mandu Streaming] Shell render timed out or errored, continuing with partial content");
+      console.log(`[Mandu Streaming] All ready: ${routeId} (${metrics.allReadyTime}ms)`);
     }
-  }
+  }).catch(() => {
+    // 에러는 onError에서 이미 처리됨
+  });
 
   // Custom stream으로 래핑 (Shell + React Content + Tail)
   let tailSent = false;
@@ -614,17 +625,7 @@ export async function renderToStream(
 
   return new ReadableStream<Uint8Array>({
     async start(controller) {
-      // Shell 전 에러면 에러 HTML 반환
-      if (hasShellError) {
-        const errorHtml = `<!DOCTYPE html>
-<html><head><title>Error</title></head>
-<body><h1>500 Server Error</h1><p>렌더링 중 오류가 발생했습니다.</p></body></html>`;
-        controller.enqueue(encoder.encode(errorHtml));
-        controller.close();
-        return;
-      }
-
-      // 1. HTML Shell 전송 (즉시 TTFB)
+      // Shell 즉시 전송 (TTFB 최소화의 핵심!)
       controller.enqueue(encoder.encode(htmlShell));
       shellSent = true;
       metrics.shellReadyTime = Date.now() - metrics.startTime;
@@ -637,10 +638,12 @@ export async function renderToStream(
 
         if (done) {
           if (!tailSent) {
-            // 2. HTML Tail 전송 (스크립트, 데이터)
             controller.enqueue(encoder.encode(htmlTail));
             tailSent = true;
-            metrics.allReadyTime = Date.now() - metrics.startTime;
+            // allReady가 아직 안 끝났을 수 있으므로 현재 시점으로 기록
+            if (metrics.allReadyTime === 0) {
+              metrics.allReadyTime = Date.now() - metrics.startTime;
+            }
             onAllReady?.();
             onMetrics?.(metrics);
           }
@@ -648,7 +651,7 @@ export async function renderToStream(
           return;
         }
 
-        // 3. React 컨텐츠 스트리밍
+        // React 컨텐츠를 그대로 스트리밍
         controller.enqueue(value);
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -656,7 +659,7 @@ export async function renderToStream(
 
         console.error("[Mandu Streaming] Pull error:", err);
 
-        // 스트리밍 중 에러 - 에러 스크립트 삽입
+        // Shell 후 에러 - 에러 스크립트 삽입
         const streamingError: StreamingError = {
           error: err,
           isShellError: false,
@@ -665,7 +668,6 @@ export async function renderToStream(
         };
         onStreamError?.(streamingError);
 
-        // 에러 스크립트 삽입
         controller.enqueue(encoder.encode(generateErrorScript(err, routeId)));
 
         if (!tailSent) {
@@ -688,9 +690,19 @@ export async function renderToStream(
  * Streaming SSR Response 생성
  *
  * 헤더 설명:
- * - Transfer-Encoding: chunked - 스트리밍 필수
  * - X-Accel-Buffering: no - nginx 버퍼링 비활성화
  * - Cache-Control: no-transform - 중간 프록시 변환 방지
+ *
+ * 주의: Transfer-Encoding은 설정하지 않음
+ * - WHATWG Response 환경에서 런타임이 자동 처리
+ * - 명시적 설정은 오히려 문제 될 수 있음
+ *
+ * 에러 정책:
+ * - renderToReadableStream 자체가 throw (stream 생성 실패)
+ *   → 여기서 catch → 500 Response 반환 (유일한 500 케이스)
+ * - React onError 콜백 호출 (렌더링 중 에러)
+ *   → StreamingError로 래핑 → 콜백 호출
+ *   → 스트림은 계속 진행 (부분 렌더링 or 에러 스크립트 삽입)
  */
 export async function renderStreamingResponse(
   element: ReactElement,
@@ -703,25 +715,47 @@ export async function renderStreamingResponse(
       status: 200,
       headers: {
         "Content-Type": "text/html; charset=utf-8",
-        "Transfer-Encoding": "chunked",
-        // Streaming 관련 헤더
+        // Transfer-Encoding은 런타임이 자동 처리 (명시 안 함)
         "X-Content-Type-Options": "nosniff",
         // nginx 버퍼링 비활성화 힌트
         "X-Accel-Buffering": "no",
         // 캐시 및 변환 방지 (Streaming은 동적)
-        "Cache-Control": "no-cache, no-store, must-revalidate, no-transform",
-        // Cloudflare 등 CDN 힌트
+        "Cache-Control": "no-store, no-transform",
+        // CDN 힌트
         "CDN-Cache-Control": "no-store",
       },
     });
   } catch (error) {
-    // Shell 전 에러 시 500 응답
+    // renderToStream에서 throw된 에러 → 500 응답 (단일 책임)
     const err = error instanceof Error ? error : new Error(String(error));
-    console.error("[Mandu Streaming] Response generation failed:", err);
+    console.error("[Mandu Streaming] Render failed:", err);
+
+    // XSS 방지
+    const safeMessage = err.message
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
 
     return new Response(
-      `<!DOCTYPE html><html><head><title>500 Error</title></head>
-<body><h1>500 Server Error</h1><p>${err.message}</p></body></html>`,
+      `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <title>500 Server Error</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 40px; background: #f5f5f5; }
+    .error { background: white; padding: 24px; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+    h1 { color: #e53935; margin: 0 0 16px 0; }
+    pre { background: #f5f5f5; padding: 12px; overflow-x: auto; }
+  </style>
+</head>
+<body>
+  <div class="error">
+    <h1>500 Server Error</h1>
+    <p>렌더링 중 오류가 발생했습니다.</p>
+    ${options.isDev ? `<pre>${safeMessage}</pre>` : ""}
+  </div>
+</body>
+</html>`,
       {
         status: 500,
         headers: {
@@ -734,48 +768,114 @@ export async function renderStreamingResponse(
 
 /**
  * Deferred 데이터와 함께 Streaming SSR 렌더링
- * Critical 데이터는 즉시, Deferred 데이터는 준비되면 스트리밍
+ *
+ * 핵심 원칙:
+ * - base stream은 즉시 시작 (TTFB 최소화)
+ * - deferred는 병렬로 처리하되 스트림을 막지 않음
+ * - 준비된 deferred만 tail 이후에 스크립트로 주입
  */
 export async function renderWithDeferredData(
   element: ReactElement,
   options: StreamingSSROptions & {
     deferredPromises?: Record<string, Promise<unknown>>;
+    /** Deferred 타임아웃 (ms) - 이 시간 안에 resolve되지 않으면 포기 */
+    deferredTimeout?: number;
   }
 ): Promise<Response> {
-  const { deferredPromises = {}, routeId = "default", ...restOptions } = options;
+  const {
+    deferredPromises = {},
+    deferredTimeout = 5000,
+    routeId = "default",
+    onMetrics,
+    isDev = false,
+    ...restOptions
+  } = options;
 
-  // Deferred 데이터 스크립트를 추가할 TransformStream
   const encoder = new TextEncoder();
-  const deferredScripts: string[] = [];
+  const startTime = Date.now();
+
+  // 준비된 deferred 스크립트를 담을 배열 (mutable)
+  const readyScripts: string[] = [];
+  let deferredChunkCount = 0;
+  let allDeferredSettled = false;
 
-  // Deferred promises 처리
+  // 1. Deferred promises 병렬 시작 (막지 않음!)
   const deferredEntries = Object.entries(deferredPromises);
-  if (deferredEntries.length > 0) {
-    // 병렬로 모든 deferred 데이터 대기
-    Promise.all(
-      deferredEntries.map(async ([key, promise]) => {
-        try {
-          const data = await promise;
-          deferredScripts.push(generateDeferredDataScript(routeId, key, data));
-        } catch (error) {
-          console.error(`[Mandu Streaming] Deferred data error for ${key}:`, error);
-        }
+  const deferredSettledPromise = deferredEntries.length > 0
+    ? Promise.allSettled(
+        deferredEntries.map(async ([key, promise]) => {
+          try {
+            // 타임아웃 적용
+            const timeoutPromise = new Promise<never>((_, reject) =>
+              setTimeout(() => reject(new Error(`Deferred timeout: ${key}`)), deferredTimeout)
+            );
+            const data = await Promise.race([promise, timeoutPromise]);
+
+            // 스크립트 생성 및 추가
+            const script = generateDeferredDataScript(routeId, key, data);
+            readyScripts.push(script);
+            deferredChunkCount++;
+
+            if (isDev) {
+              console.log(`[Mandu Streaming] Deferred ready: ${key} (${Date.now() - startTime}ms)`);
+            }
+          } catch (error) {
+            console.error(`[Mandu Streaming] Deferred error for ${key}:`, error);
+          }
+        })
+      ).then(() => {
+        allDeferredSettled = true;
       })
-    );
-  }
+    : Promise.resolve().then(() => { allDeferredSettled = true; });
 
-  // 기본 스트림 생성
-  const baseStream = await renderToStream(element, { ...restOptions, routeId });
+  // 2. Base stream 즉시 시작 (TTFB 최소화의 핵심!)
+  let baseMetrics: StreamingMetrics | null = null;
+  const baseStream = await renderToStream(element, {
+    ...restOptions,
+    routeId,
+    isDev,
+    onMetrics: (metrics) => {
+      baseMetrics = metrics;
+    },
+  });
 
-  // Deferred 스크립트 주입을 위한 Transform
+  // 3. TransformStream: base stream 통과 + tail 이후 deferred 스크립트 주입
   const transformStream = new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
+      // base stream chunk 그대로 전달
       controller.enqueue(chunk);
     },
-    flush(controller) {
-      // 모든 deferred 스크립트 추가
-      for (const script of deferredScripts) {
+    async flush(controller) {
+      // base stream 완료 후, deferred가 아직 안 끝났으면 잠시 대기
+      // (단, deferredTimeout 내에서만)
+      if (!allDeferredSettled) {
+        const remainingTime = Math.max(0, deferredTimeout - (Date.now() - startTime));
+        if (remainingTime > 0) {
+          await Promise.race([
+            deferredSettledPromise,
+            new Promise(resolve => setTimeout(resolve, remainingTime)),
+          ]);
+        }
+      }
+
+      // 준비된 deferred 스크립트만 주입 (실제 enqueue 기준 카운트)
+      let injectedCount = 0;
+      for (const script of readyScripts) {
         controller.enqueue(encoder.encode(script));
+        injectedCount++;
+      }
+
+      if (isDev && injectedCount > 0) {
+        console.log(`[Mandu Streaming] Injected ${injectedCount} deferred scripts`);
+      }
+
+      // 최종 메트릭 보고 (injectedCount가 실제 메트릭)
+      if (onMetrics && baseMetrics) {
+        onMetrics({
+          ...baseMetrics,
+          deferredChunkCount: injectedCount,
+          allReadyTime: Date.now() - startTime,
+        });
       }
     },
   });
@@ -786,9 +886,10 @@ export async function renderWithDeferredData(
     status: 200,
     headers: {
       "Content-Type": "text/html; charset=utf-8",
-      "Transfer-Encoding": "chunked",
       "X-Content-Type-Options": "nosniff",
-      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "X-Accel-Buffering": "no",
+      "Cache-Control": "no-store, no-transform",
+      "CDN-Cache-Control": "no-store",
     },
   });
 }