@mandujs/core 0.9.19 → 0.9.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.19",
+  "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;
@@ -664,8 +697,12 @@ export async function renderToStream(
  * - WHATWG Response 환경에서 런타임이 자동 처리
  * - 명시적 설정은 오히려 문제 될 수 있음
  *
- * 에러 처리:
- * - renderToStream에서 throw → 여기서 500 Response 생성 (단일 책임)
+ * 에러 정책:
+ * - renderToReadableStream 자체가 throw (stream 생성 실패)
+ *   → 여기서 catch → 500 Response 반환 (유일한 500 케이스)
+ * - React onError 콜백 호출 (렌더링 중 에러)
+ *   → StreamingError로 래핑 → 콜백 호출
+ *   → 스트림은 계속 진행 (부분 렌더링 or 에러 스크립트 삽입)
  */
 export async function renderStreamingResponse(
   element: ReactElement,
@@ -731,16 +768,23 @@ 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 = {},
+    deferredTimeout = 5000,
     routeId = "default",
     onMetrics,
     isDev = false,
@@ -748,31 +792,43 @@ export async function renderWithDeferredData(
   } = options;
 
   const encoder = new TextEncoder();
-  const deferredScripts: string[] = [];
-  let deferredChunkCount = 0;
   const startTime = Date.now();
 
-  // Deferred promises 처리 (병렬)
-  const deferredEntries = Object.entries(deferredPromises);
-  if (deferredEntries.length > 0) {
-    await Promise.all(
-      deferredEntries.map(async ([key, promise]) => {
-        try {
-          const data = await promise;
-          deferredScripts.push(generateDeferredDataScript(routeId, key, data));
-          deferredChunkCount++;
+  // 준비된 deferred 스크립트를 담을 배열 (mutable)
+  const readyScripts: string[] = [];
+  let deferredChunkCount = 0;
+  let allDeferredSettled = false;
 
-          if (isDev) {
-            console.log(`[Mandu Streaming] Deferred chunk ready: ${key}`);
+  // 1. Deferred promises 병렬 시작 (막지 않음!)
+  const deferredEntries = Object.entries(deferredPromises);
+  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);
           }
-        } catch (error) {
-          console.error(`[Mandu Streaming] Deferred data error for ${key}:`, error);
-        }
+        })
+      ).then(() => {
+        allDeferredSettled = true;
       })
-    );
-  }
+    : Promise.resolve().then(() => { allDeferredSettled = true; });
 
-  // 기본 스트림 생성 (메트릭 수집 포함)
+  // 2. Base stream 즉시 시작 (TTFB 최소화의 핵심!)
   let baseMetrics: StreamingMetrics | null = null;
   const baseStream = await renderToStream(element, {
     ...restOptions,
@@ -783,22 +839,41 @@ export async function renderWithDeferredData(
     },
   });
 
-  // 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,
+          deferredChunkCount: injectedCount,
           allReadyTime: Date.now() - startTime,
         });
       }