@mandujs/core 0.9.18 → 0.9.19

package/package.json

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

package/src/runtime/streaming-ssr.ts

@@ -504,16 +504,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 +535,7 @@ export async function renderToStream(
     startTime: Date.now(),
   };
 
-  // criticalData 직렬화 검증
+  // criticalData 직렬화 검증 (dev에서는 throw)
   validateCriticalData(criticalData, isDev);
 
   // 스트리밍 주의사항 경고 (첫 요청 시 1회만)
@@ -548,65 +549,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 +592,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 +605,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 +618,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 +626,7 @@ export async function renderToStream(
 
         console.error("[Mandu Streaming] Pull error:", err);
 
-        // 스트리밍 중 에러 - 에러 스크립트 삽입
+        // Shell 후 에러 - 에러 스크립트 삽입
         const streamingError: StreamingError = {
           error: err,
           isShellError: false,
@@ -665,7 +635,6 @@ export async function renderToStream(
         };
         onStreamError?.(streamingError);
 
-        // 에러 스크립트 삽입
         controller.enqueue(encoder.encode(generateErrorScript(err, routeId)));
 
         if (!tailSent) {
@@ -688,9 +657,15 @@ export async function renderToStream(
  * Streaming SSR Response 생성
  *
  * 헤더 설명:
- * - Transfer-Encoding: chunked - 스트리밍 필수
  * - X-Accel-Buffering: no - nginx 버퍼링 비활성화
  * - Cache-Control: no-transform - 중간 프록시 변환 방지
+ *
+ * 주의: Transfer-Encoding은 설정하지 않음
+ * - WHATWG Response 환경에서 런타임이 자동 처리
+ * - 명시적 설정은 오히려 문제 될 수 있음
+ *
+ * 에러 처리:
+ * - renderToStream에서 throw → 여기서 500 Response 생성 (단일 책임)
  */
 export async function renderStreamingResponse(
   element: ReactElement,
@@ -703,25 +678,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: {
@@ -742,21 +739,32 @@ export async function renderWithDeferredData(
     deferredPromises?: Record<string, Promise<unknown>>;
   }
 ): Promise<Response> {
-  const { deferredPromises = {}, routeId = "default", ...restOptions } = options;
+  const {
+    deferredPromises = {},
+    routeId = "default",
+    onMetrics,
+    isDev = false,
+    ...restOptions
+  } = options;
 
-  // Deferred 데이터 스크립트를 추가할 TransformStream
   const encoder = new TextEncoder();
   const deferredScripts: string[] = [];
+  let deferredChunkCount = 0;
+  const startTime = Date.now();
 
-  // Deferred promises 처리
+  // Deferred promises 처리 (병렬)
   const deferredEntries = Object.entries(deferredPromises);
   if (deferredEntries.length > 0) {
-    // 병렬로 모든 deferred 데이터 대기
-    Promise.all(
+    await Promise.all(
       deferredEntries.map(async ([key, promise]) => {
         try {
           const data = await promise;
           deferredScripts.push(generateDeferredDataScript(routeId, key, data));
+          deferredChunkCount++;
+
+          if (isDev) {
+            console.log(`[Mandu Streaming] Deferred chunk ready: ${key}`);
+          }
         } catch (error) {
           console.error(`[Mandu Streaming] Deferred data error for ${key}:`, error);
         }
@@ -764,8 +772,16 @@ export async function renderWithDeferredData(
     );
   }
 
-  // 기본 스트림 생성
-  const baseStream = await renderToStream(element, { ...restOptions, routeId });
+  // 기본 스트림 생성 (메트릭 수집 포함)
+  let baseMetrics: StreamingMetrics | null = null;
+  const baseStream = await renderToStream(element, {
+    ...restOptions,
+    routeId,
+    isDev,
+    onMetrics: (metrics) => {
+      baseMetrics = metrics;
+    },
+  });
 
   // Deferred 스크립트 주입을 위한 Transform
   const transformStream = new TransformStream<Uint8Array, Uint8Array>({
@@ -777,6 +793,15 @@ export async function renderWithDeferredData(
       for (const script of deferredScripts) {
         controller.enqueue(encoder.encode(script));
       }
+
+      // 최종 메트릭 보고
+      if (onMetrics && baseMetrics) {
+        onMetrics({
+          ...baseMetrics,
+          deferredChunkCount,
+          allReadyTime: Date.now() - startTime,
+        });
+      }
     },
   });
 
@@ -786,9 +811,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",
     },
   });
 }