@uniai-fe/uds-templates 0.10.3 → 0.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -67,17 +67,17 @@
     "react-hook-form": "^7.81.0",
     "sass": "^1.101.0",
     "typescript": "6.0.3",
-    "@uniai-fe/eslint-config": "0.4.1",
     "@uniai-fe/next-devkit": "0.4.0",
+    "@uniai-fe/eslint-config": "0.4.1",
     "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/uds-foundation": "0.5.0",
+    "@uniai-fe/util-api": "0.2.1",
     "@uniai-fe/uds-primitives": "0.10.0",
     "@uniai-fe/util-functions": "0.4.3",
-    "@uniai-fe/util-api": "0.2.1",
-    "@uniai-fe/util-next": "0.5.0",
-    "@uniai-fe/util-rtc": "0.2.0",
-    "@uniai-fe/util-jotai": "0.3.0"
+    "@uniai-fe/util-jotai": "0.3.0",
+    "@uniai-fe/util-rtc": "0.2.1",
+    "@uniai-fe/uds-foundation": "0.5.0",
+    "@uniai-fe/util-next": "0.5.0"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/hooks/streamRegistry.ts

@@ -8,6 +8,7 @@ import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
  * @property {boolean} isStreaming WHEP 시작 promise 진행 여부
  * @property {MediaStream | null} stream 현재 수신 중인 MediaStream
  * @property {string | null} streamError 마지막 WHEP 시작 오류 메시지
+ * @desc 외부 subscriber에 노출하는 immutable RTC stream 상태 계약
  */
 interface CctvRtcStreamSnapshot {
   /**
@@ -35,7 +36,10 @@ interface CctvRtcStreamSnapshot {
  * @property {WhepStreamHandle | null} handle 연결 완료 뒤 PeerConnection cleanup handle
  * @property {string} identityKey camera와 endpoint 기준 stream family key
  * @property {Set<(snapshot: CctvRtcStreamSnapshot) => void>} listeners snapshot 구독자 집합
+ * @property {MediaStream | null} pendingStream handle 반환 전 수신한 replacement stream
+ * @property {Map<HTMLVideoElement, MediaProvider | null>} previousVideoSources replacement 실패 시 복원할 video source
  * @property {string} streamKey token generation까지 포함한 stream key
+ * @desc Provider scope에서 단일 stream lifecycle과 replacement rollback resource를 소유하는 내부 entry 계약
  */
 interface CctvRtcStreamEntry extends CctvRtcStreamSnapshot {
   /**
@@ -58,6 +62,14 @@ interface CctvRtcStreamEntry extends CctvRtcStreamSnapshot {
    * entry snapshot 구독자 집합
    */
   listeners: Set<(snapshot: CctvRtcStreamSnapshot) => void>;
+  /**
+   * handle 반환 전 수신한 replacement MediaStream
+   */
+  pendingStream: MediaStream | null;
+  /**
+   * replacement 실패 시 복원할 video별 기존 source
+   */
+  previousVideoSources: Map<HTMLVideoElement, MediaProvider | null>;
   /**
    * token generation까지 포함한 stream key
    */
@@ -71,6 +83,7 @@ interface CctvRtcStreamEntry extends CctvRtcStreamSnapshot {
  * @property {string} streamKey token generation까지 포함한 stream key
  * @property {string} token WHEP Bearer token
  * @property {HTMLVideoElement} video 최초 stream attach 대상 video
+ * @desc registry가 token generation별 WHEP lifecycle을 시작하는 입력 계약
  */
 interface CctvRtcStreamStartParams {
   /**
@@ -167,8 +180,11 @@ const closeEntry = (entry: CctvRtcStreamEntry) => {
   entry.isStreaming = false;
 
   entry.attachedVideos.forEach(video => {
-    clearVideoIfAttachedStream(video, entry.stream);
+    // committed 전 replacement도 현재 entry가 video에 붙인 resource로 보고 선택적으로 제거한다.
+    clearVideoIfAttachedStream(video, entry.pendingStream ?? entry.stream);
   });
+  entry.pendingStream = null;
+  entry.previousVideoSources.clear();
 
   // 마지막 closed snapshot을 전달한 뒤 entry가 외부 객체를 붙잡지 않도록 집합을 비운다.
   notifyEntry(entry);
@@ -184,6 +200,7 @@ const closeEntry = (entry: CctvRtcStreamEntry) => {
  * @property {(streamKey: string) => CctvRtcStreamSnapshot} getSnapshot stream snapshot 조회
  * @property {(params: CctvRtcStreamStartParams) => void} start streamKey 단위 WHEP 시작
  * @property {(streamKey: string, listener: (snapshot: CctvRtcStreamSnapshot) => void) => () => void} subscribe stream snapshot 구독
+ * @desc Provider scope에서 WHEP stream 시작, 연결, 구독과 cleanup을 관리하는 공개 registry 계약
  */
 export interface CctvRtcStreamRegistry {
   /**
@@ -228,12 +245,7 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   // Map은 token generation이 포함된 streamKey마다 현재 lifecycle owner를 하나만 유지한다.
   const entries = new Map<string, CctvRtcStreamEntry>();
 
-  /**
-   * CCTV Stream Registry Util; entry resource와 Map owner 제거
-   * @util
-   * @param {CctvRtcStreamEntry} entry 삭제할 registry entry
-   * @desc entry cleanup을 수행한 뒤 streamKey의 Map owner를 제거한다.
-   */
+  // entry resource를 정리한 뒤 streamKey의 Map owner를 제거한다.
   const deleteEntry = (entry: CctvRtcStreamEntry) => {
     closeEntry(entry);
     entries.delete(entry.streamKey);
@@ -253,6 +265,7 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
       if (!entry) {
         // 아직 시작되지 않은 key는 stale srcObject 없이 빈 video 상태로 정규화한다.
         attachVideo(video, null);
+        // 소유할 registry entry가 없으므로 Map mutation 없이 현재 video만 비우는 cleanup을 반환한다.
         return () => {
           if (video.srcObject) video.srcObject = null;
         };
@@ -260,13 +273,21 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
 
       // 기존 MediaStream이 있으면 즉시 reattach하고 pending entry면 현재 화면을 보존한다.
       entry.attachedVideos.add(video);
-      if (entry.stream || !video.srcObject) {
-        attachVideo(video, entry.stream);
+      if (!entry.previousVideoSources.has(video)) {
+        // pending replacement 실패 시 이 attach 직전 source로 돌아갈 수 있게 최초 값만 보관한다.
+        entry.previousVideoSources.set(video, video.srcObject);
+      }
+      // handle 성공 전 track도 새 subscriber video에는 보이되 committed snapshot으로 승격하지 않는다.
+      const attachedStream = entry.stream ?? entry.pendingStream;
+      if (attachedStream || !video.srcObject) {
+        attachVideo(video, attachedStream);
       }
 
       return () => {
+        // detach된 video는 이후 실패 복원과 entry cleanup의 소유 대상에서 제외한다.
         entry.attachedVideos.delete(video);
-        clearVideoIfAttachedStream(video, entry.stream);
+        entry.previousVideoSources.delete(video);
+        clearVideoIfAttachedStream(video, entry.pendingStream ?? entry.stream);
       };
     },
     /**
@@ -311,7 +332,6 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
     /**
      * CCTV Stream Registry Util; streamKey 단위 WHEP 연결 시작
      * @util
-     * @param {CctvRtcStreamStartParams} params WHEP 시작 파라미터
      * @property {string} params.endpoint token-specific WHEP 요청 endpoint
      * @property {string} params.identityKey camera와 endpoint 기준 stream family key
      * @property {string} params.streamKey token generation까지 포함한 stream key
@@ -336,18 +356,16 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         identityKey,
         isStreaming: true,
         listeners: new Set(),
+        pendingStream: null,
+        // 최초 video가 이미 표시하던 connected stream을 replacement 실패 rollback 값으로 보존한다.
+        previousVideoSources: new Map([[video, video.srcObject]]),
         stream: null,
         streamError: null,
         streamKey,
       };
 
       entries.set(streamKey, entry);
-      /**
-       * CCTV Stream Registry Util; 현재 entry의 lifecycle owner 여부 확인
-       * @util
-       * @desc Map owner 일치와 AbortSignal 상태를 함께 확인한다.
-       * @return {boolean} callback과 settlement 반영 가능 여부
-       */
+      // Map owner 일치와 AbortSignal 상태로 현재 entry의 lifecycle 소유권을 확인한다.
       const isCurrentEntry = () =>
         entries.get(streamKey) === entry && !controller.signal.aborted;
 
@@ -365,51 +383,69 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
         video,
         signal: controller.signal,
         onConnectionStateChange: state => {
-          // Provider cleanup 또는 같은 key owner 교체 뒤 늦은 state event는 반영하지 않는다.
-          if (!isCurrentEntry()) return;
+          if (!isCurrentEntry()) {
+            // Provider cleanup 또는 같은 key owner 교체 뒤 늦은 state event는 반영하지 않는다.
+            return;
+          }
 
           entry.connectionState = state;
           notifyEntry(entry);
         },
         onTrack: event => {
-          // 닫힌 entry의 late track이 video와 snapshot을 되살리지 않게 막는다.
-          if (!isCurrentEntry()) return;
+          if (!isCurrentEntry()) {
+            // 닫힌 entry의 late track이 video와 snapshot을 되살리지 않게 막는다.
+            return;
+          }
 
-          entry.stream = event.streams[0] ?? null;
+          // track만으로 성공을 확정하지 않고 handle 반환 전까지 pending resource로 유지한다.
+          entry.pendingStream = event.streams[0] ?? null;
           entry.attachedVideos.forEach(attachedVideo =>
-            attachVideo(attachedVideo, entry.stream),
+            attachVideo(attachedVideo, entry.pendingStream),
           );
-          notifyEntry(entry);
         },
       })
         .then(handle => {
           // pending 중 close된 start가 늦게 resolve되면 새 handle을 즉시 회수한다.
           if (!isCurrentEntry()) {
             handle.close();
+            // 회수한 stale handle을 현재 entry의 성공 상태로 다시 기록하지 않는다.
             return;
           }
 
           entry.handle = handle;
           entry.isStreaming = false;
+          // remote SDP까지 완료된 handle만 committed snapshot으로 승격해 이전 generation을 닫게 한다.
+          entry.stream = entry.pendingStream;
+          entry.pendingStream = null;
           notifyEntry(entry);
+          entry.previousVideoSources.clear();
         })
         .catch(error => {
-          // abort/delete된 이전 owner의 rejection은 현재 entry 상태를 덮어쓰지 않는다.
-          if (entries.get(streamKey) !== entry) return;
+          if (entries.get(streamKey) !== entry) {
+            // abort/delete된 이전 owner의 rejection은 현재 entry 상태를 덮어쓰지 않는다.
+            return;
+          }
 
           // 실패 원인이 어느 negotiation 단계이든 util-rtc 내부 PeerConnection cleanup을 요청한다.
           entry.controller?.abort();
           entry.controller = null;
           entry.handle = null;
           entry.isStreaming = false;
+          const failedStream = entry.pendingStream ?? entry.stream;
+          entry.attachedVideos.forEach(attachedVideo => {
+            // 외부에서 다른 source로 교체한 video는 건드리지 않고 이 entry의 실패 stream만 rollback한다.
+            if (failedStream && attachedVideo.srcObject === failedStream) {
+              attachedVideo.srcObject =
+                entry.previousVideoSources.get(attachedVideo) ?? null;
+            }
+          });
+          entry.pendingStream = null;
           entry.stream = null;
+          entry.previousVideoSources.clear();
           entry.streamError =
             error instanceof Error
               ? error.message
               : "스트림 연결에 실패했습니다.";
-          entry.attachedVideos.forEach(attachedVideo =>
-            clearVideoIfAttachedStream(attachedVideo, entry.stream),
-          );
           // subscriber에는 terminal error를 전달하되 실패 entry는 다음 명시적 start를 막지 않는다.
           notifyEntry(entry);
           entries.delete(streamKey);
@@ -425,7 +461,10 @@ export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
      */
     subscribe(streamKey, listener) {
       const entry = entries.get(streamKey);
-      if (!entry) return () => undefined;
+      if (!entry) {
+        // 구독할 lifecycle owner가 없으므로 listener를 저장하지 않고 no-op cleanup을 반환한다.
+        return () => undefined;
+      }
 
       // 구독 직후 현재 snapshot을 전달해 registry reattach의 첫 render 지연을 줄인다.
       entry.listeners.add(listener);