@uniai-fe/uds-templates 0.5.6 → 0.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/cctv/apis/client.ts

@@ -51,4 +51,10 @@ export const useQueryCctvRtcToken = ({
   useQuery({
     queryKey: ["cctv_rtc_token", username, company_id, cam_id, url],
     queryFn: () => postCctvRtcToken({ company_id, cam_id, username, url }),
+    enabled: Boolean(username && company_id && cam_id),
+    staleTime: Infinity,
+    gcTime: Infinity,
+    refetchOnMount: false,
+    refetchOnReconnect: false,
+    refetchOnWindowFocus: false,
   });

package/src/cctv/components/Provider.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { createContext, useContext } from "react";
+import { createContext, useContext, useEffect, useMemo } from "react";
 import { Form } from "@uniai-fe/uds-primitives";
+import type { DefaultValues } from "react-hook-form";
 
 import type {
   CctvApiUrlContext,
@@ -9,6 +10,10 @@ import type {
   CctvProviderProps,
 } from "../types";
 import { CCTV_CONTEXT_DEFAULT_VALUES } from "../data";
+import {
+  createCctvRtcStreamRegistry,
+  type CctvRtcStreamRegistry,
+} from "../hooks/streamRegistry";
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -20,6 +25,10 @@ const ApiUrlContext = createContext<CctvApiUrlContext>({
   tokenUrl: undefined,
 });
 
+const RtcStreamRegistryContext = createContext<CctvRtcStreamRegistry | null>(
+  null,
+);
+
 /**
  * CCTV; API 경로 컨텍스트
  * @return {CctvApiUrlContext}
@@ -31,6 +40,16 @@ export function useCctvApiUrl(): CctvApiUrlContext {
   return useContext(ApiUrlContext);
 }
 
+export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
+  const registry = useContext(RtcStreamRegistryContext);
+  if (!registry) {
+    throw new Error(
+      "CCTV.Provider 내부에서 useCctvRtcStreamRegistry를 사용해야 합니다.",
+    );
+  }
+  return registry;
+}
+
 /**
  * CCTV; Provider props
  * @component
@@ -39,30 +58,46 @@ export function useCctvApiUrl(): CctvApiUrlContext {
  * @property {string} [listUrl] company-list API 요청 경로
  * @property {string} [tokenUrl] token API 요청 경로
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
+ * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
  * @property {React.ReactNode} children
  */
-export default function CCTVProvider({
+export default function CCTVProvider<ContextExtension extends object = object>({
   username,
   company_id,
   cam_id,
   listUrl,
   tokenUrl,
+  defaultValues,
   children,
-}: CctvProviderProps) {
+}: CctvProviderProps<ContextExtension>) {
+  const streamRegistry = useMemo(() => createCctvRtcStreamRegistry(), []);
+
+  useEffect(() => {
+    return () => {
+      streamRegistry.closeAll();
+    };
+  }, [streamRegistry]);
+
+  const mergedDefaultValues = {
+    // 변경 설명: service 확장 context 기본값을 core CCTV form context와 한 RHF scope에서 병합한다.
+    ...defaultValues,
+    ...CCTV_CONTEXT_DEFAULT_VALUES,
+    username,
+    company_id,
+    cam_id,
+  } as DefaultValues<CctvContext<ContextExtension>>;
+
   return (
     <ApiUrlContext.Provider value={{ listUrl, tokenUrl }}>
-      <Form.Provider<CctvContext>
-        options={{
-          defaultValues: {
-            ...CCTV_CONTEXT_DEFAULT_VALUES,
-            username,
-            company_id,
-            cam_id,
-          },
-        }}
-      >
-        {children}
-      </Form.Provider>
+      <RtcStreamRegistryContext.Provider value={streamRegistry}>
+        <Form.Provider<CctvContext<ContextExtension>>
+          options={{
+            defaultValues: mergedDefaultValues,
+          }}
+        >
+          {children}
+        </Form.Provider>
+      </RtcStreamRegistryContext.Provider>
     </ApiUrlContext.Provider>
   );
 }

package/src/cctv/hooks/streamRegistry.ts

@@ -0,0 +1,195 @@
+"use client";
+
+import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
+
+interface CctvRtcStreamSnapshot {
+  connectionState: RTCPeerConnectionState;
+  isStreaming: boolean;
+  stream: MediaStream | null;
+  streamError: string | null;
+}
+
+interface CctvRtcStreamEntry extends CctvRtcStreamSnapshot {
+  attachedVideos: Set<HTMLVideoElement>;
+  controller: AbortController | null;
+  handle: WhepStreamHandle | null;
+  identityKey: string;
+  listeners: Set<(snapshot: CctvRtcStreamSnapshot) => void>;
+  streamKey: string;
+}
+
+interface CctvRtcStreamStartParams {
+  endpoint: string;
+  identityKey: string;
+  streamKey: string;
+  token: string;
+  video: HTMLVideoElement;
+}
+
+const getEntrySnapshot = (
+  entry?: CctvRtcStreamEntry,
+): CctvRtcStreamSnapshot => ({
+  connectionState: entry?.connectionState ?? "new",
+  isStreaming: entry?.isStreaming ?? false,
+  stream: entry?.stream ?? null,
+  streamError: entry?.streamError ?? null,
+});
+
+const attachVideo = (video: HTMLVideoElement, stream: MediaStream | null) => {
+  video.playsInline = true;
+  video.autoplay = true;
+  video.srcObject = stream;
+};
+
+const notifyEntry = (entry: CctvRtcStreamEntry) => {
+  const snapshot = getEntrySnapshot(entry);
+  entry.listeners.forEach(listener => listener(snapshot));
+};
+
+const closeEntry = (entry: CctvRtcStreamEntry) => {
+  entry.controller?.abort();
+  entry.controller = null;
+  entry.handle?.close();
+  entry.handle = null;
+  entry.connectionState = "closed";
+  entry.isStreaming = false;
+
+  entry.attachedVideos.forEach(video => {
+    if (!entry.stream || video.srcObject === entry.stream) {
+      video.srcObject = null;
+    }
+  });
+
+  notifyEntry(entry);
+  entry.attachedVideos.clear();
+  entry.listeners.clear();
+};
+
+export interface CctvRtcStreamRegistry {
+  attach: (streamKey: string, video: HTMLVideoElement) => () => void;
+  closeAll: () => void;
+  closeByIdentity: (identityKey: string, exceptStreamKey?: string) => void;
+  getSnapshot: (streamKey: string) => CctvRtcStreamSnapshot;
+  start: (params: CctvRtcStreamStartParams) => void;
+  subscribe: (
+    streamKey: string,
+    listener: (snapshot: CctvRtcStreamSnapshot) => void,
+  ) => () => void;
+}
+
+export function createCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
+  const entries = new Map<string, CctvRtcStreamEntry>();
+
+  const deleteEntry = (entry: CctvRtcStreamEntry) => {
+    closeEntry(entry);
+    entries.delete(entry.streamKey);
+  };
+
+  return {
+    attach(streamKey, video) {
+      const entry = entries.get(streamKey);
+      if (!entry) {
+        attachVideo(video, null);
+        return () => {
+          if (video.srcObject) video.srcObject = null;
+        };
+      }
+
+      entry.attachedVideos.add(video);
+      attachVideo(video, entry.stream);
+
+      return () => {
+        entry.attachedVideos.delete(video);
+        if (!entry.stream || video.srcObject === entry.stream) {
+          video.srcObject = null;
+        }
+      };
+    },
+    closeAll() {
+      entries.forEach(entry => closeEntry(entry));
+      entries.clear();
+    },
+    closeByIdentity(identityKey, exceptStreamKey) {
+      entries.forEach(entry => {
+        if (
+          entry.identityKey === identityKey &&
+          entry.streamKey !== exceptStreamKey
+        ) {
+          deleteEntry(entry);
+        }
+      });
+    },
+    getSnapshot(streamKey) {
+      return getEntrySnapshot(entries.get(streamKey));
+    },
+    start({ endpoint, identityKey, streamKey, token, video }) {
+      const existingEntry = entries.get(streamKey);
+      if (existingEntry) return;
+
+      const controller = new AbortController();
+      const entry: CctvRtcStreamEntry = {
+        attachedVideos: new Set([video]),
+        connectionState: "connecting",
+        controller,
+        handle: null,
+        identityKey,
+        isStreaming: true,
+        listeners: new Set(),
+        stream: null,
+        streamError: null,
+        streamKey,
+      };
+
+      entries.set(streamKey, entry);
+      attachVideo(video, null);
+
+      startWhepStream({
+        endpoint,
+        token,
+        video,
+        signal: controller.signal,
+        onConnectionStateChange: state => {
+          entry.connectionState = state;
+          notifyEntry(entry);
+        },
+        onTrack: event => {
+          entry.stream = event.streams[0] ?? null;
+          entry.attachedVideos.forEach(attachedVideo =>
+            attachVideo(attachedVideo, entry.stream),
+          );
+          notifyEntry(entry);
+        },
+      })
+        .then(handle => {
+          entry.handle = handle;
+          entry.isStreaming = false;
+          notifyEntry(entry);
+        })
+        .catch(error => {
+          entry.controller = null;
+          entry.handle = null;
+          entry.isStreaming = false;
+          entry.stream = null;
+          entry.streamError =
+            error instanceof Error
+              ? error.message
+              : "스트림 연결에 실패했습니다.";
+          entry.attachedVideos.forEach(attachedVideo =>
+            attachVideo(attachedVideo, null),
+          );
+          notifyEntry(entry);
+        });
+    },
+    subscribe(streamKey, listener) {
+      const entry = entries.get(streamKey);
+      if (!entry) return () => undefined;
+
+      entry.listeners.add(listener);
+      listener(getEntrySnapshot(entry));
+
+      return () => {
+        entry.listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/cctv/hooks/useContext.ts

@@ -11,7 +11,7 @@ import type {
   CctvCompanyCameraList,
   CctvCompanyGroup,
   CctvCompanyGroupItems,
-  CctvContext,
+  CctvBaseContext,
   UseCctvContextReturn,
 } from "../types";
 import { initCompanyList } from "../utils/data";
@@ -49,7 +49,7 @@ export default function useCctvContext(): UseCctvContextReturn {
   const setCtx = useSetAtom(cctvSelectedContext);
   const liveRegistry = useAtomValue(cctvRtcLiveRegistryAtom);
   // react-hook-form context에서 control/setValue 등을 꺼낸다.
-  const { control, setValue, ...context } = useFormContext<CctvContext>();
+  const { control, setValue, ...context } = useFormContext<CctvBaseContext>();
 
   // 폼 상태를 watch 하여 실시간 컨텍스트 값을 얻는다.
   const username = useWatch({ control, name: "username" });

package/src/cctv/hooks/useRtcStream.ts

@@ -1,14 +1,15 @@
 "use client";
 
 // React 훅들을 활용해 WebRTC 스트림 라이프사이클을 제어한다.
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useSetAtom } from "jotai";
-// util-rtc 모듈에서 제공하는 WHEP(WebRTC-HTTP Egress Protocol) 헬퍼와 핸들 타입.
-import { startWhepStream, type WhepStreamHandle } from "@uniai-fe/util-rtc";
 
 // 토큰 발급 쿼리와 API URL 컨텍스트 훅, 타입, react-hook-form 유틸.
 import { useQueryCctvRtcToken } from "../apis/client";
-import { useCctvApiUrl } from "../components/Provider";
+import {
+  useCctvApiUrl,
+  useCctvRtcStreamRegistry,
+} from "../components/Provider";
 import type { UseCctvRtcStreamParams, UseCctvRtcStreamReturn } from "../types";
 import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
 import { getIsLive } from "../utils/video-state";
@@ -39,6 +40,7 @@ export function useCctvRtcStream({
 }: UseCctvRtcStreamParams): UseCctvRtcStreamReturn {
   // Provider를 통해 주입된 기본 토큰 발급 URL을 확보한다.
   const { tokenUrl: contextTokenUrl } = useCctvApiUrl();
+  const streamRegistry = useCctvRtcStreamRegistry();
   const setLiveRegistry = useSetAtom(cctvRtcLiveRegistryAtom);
   const instanceKeyRef = useRef<string | null>(null);
   if (!instanceKeyRef.current) {
@@ -47,6 +49,8 @@ export function useCctvRtcStream({
 
   // WebRTC MediaStream을 연결할 video 요소 ref.
   const videoRef = useRef<HTMLVideoElement | null>(null);
+  const activeStreamKeyRef = useRef<string | null>(null);
+  const activeStreamIdentityKeyRef = useRef<string | null>(null);
 
   // RTCPeerConnectionState를 관찰해 UI에 노출하기 위한 상태값.
   const [connectionState, setConnectionState] =
@@ -80,71 +84,115 @@ export function useCctvRtcStream({
     return `${cam.cam_rtc.replace(/\/$/, "")}/whep${query}`;
   }, [cam?.cam_rtc, username]);
 
+  const streamKey = useMemo(() => {
+    if (!cam?.cam_id || !cam.cam_online || !endpoint || !tokenQuery.data?.token)
+      return "";
+
+    return [
+      username,
+      cam.company_id,
+      cam.cam_id,
+      endpoint,
+      tokenQuery.dataUpdatedAt,
+    ].join("|");
+  }, [
+    cam?.cam_id,
+    cam?.cam_online,
+    cam?.company_id,
+    endpoint,
+    tokenQuery.data?.token,
+    tokenQuery.dataUpdatedAt,
+    username,
+  ]);
+
+  const streamIdentityKey = useMemo(() => {
+    if (!cam?.cam_id || !endpoint) return "";
+
+    return [username, cam.company_id, cam.cam_id, endpoint].join("|");
+  }, [cam?.cam_id, cam?.company_id, endpoint, username]);
+
   // 토큰과 endpoint가 준비되면 WebRTC 스트림을 연결한다.
   useEffect(() => {
     const currentVideo = videoRef.current;
 
     // 토큰/카메라 에러로 전환되면 직전 MediaStream이 화면에 남지 않도록 비운다.
     if (tokenQuery.isError || !cam?.cam_online) {
+      if (streamIdentityKey) {
+        streamRegistry.closeByIdentity(streamIdentityKey);
+      }
       if (currentVideo) currentVideo.srcObject = null;
+      setConnectionState("new");
+      setStreamError(null);
+      setStreaming(false);
       return;
     }
 
     // 필수 값이 없으면 스트림을 시작하지 않는다.
-    if (!tokenQuery.data?.token || !endpoint || !currentVideo) return;
-
-    let handle: WhepStreamHandle | null = null;
+    if (!streamKey || !tokenQuery.data?.token || !endpoint || !currentVideo)
+      return;
 
-    // fetch / PeerConnection을 취소하기 위한 AbortController.
-    const controller = new AbortController();
+    if (
+      activeStreamIdentityKeyRef.current === streamIdentityKey &&
+      activeStreamKeyRef.current !== streamKey
+    ) {
+      streamRegistry.closeByIdentity(streamIdentityKey, streamKey);
+    }
 
-    // 기존 오류를 초기화하고 스트리밍 상태를 true로 설정한다.
-    setStreamError(null);
-    setStreaming(true);
-    setConnectionState("connecting");
+    activeStreamKeyRef.current = streamKey;
+    activeStreamIdentityKeyRef.current = streamIdentityKey;
 
-    // util-rtc의 startWhepStream으로 SDP 교환과 스트림 연결을 수행한다.
-    startWhepStream({
+    streamRegistry.start({
+      streamKey,
+      identityKey: streamIdentityKey,
       endpoint,
       token: tokenQuery.data.token,
       video: currentVideo,
-      signal: controller.signal,
-      onConnectionStateChange: state => setConnectionState(state),
-    })
-      .then(streamHandle => {
-        // cleanup 시 close를 호출하기 위해 핸들을 저장한다.
-        handle = streamHandle;
-      })
-      .catch(error => {
-        // 스트림 실패 시에도 이전 프레임이 에러 오버레이 뒤에 남지 않도록 정리한다.
-        currentVideo.srcObject = null;
-        // Error 객체 여부에 따라 메시지를 정규화한다.
-        setStreamError(
-          error instanceof Error
-            ? error.message
-            : "스트림 연결에 실패했습니다.",
-        );
-      })
-      .finally(() => {
-        // 성공/실패에 관계없이 스트리밍 상태를 false로 되돌린다.
-        setStreaming(false);
-      });
+    });
+
+    const detachVideo = streamRegistry.attach(streamKey, currentVideo);
+    const unsubscribe = streamRegistry.subscribe(streamKey, snapshot => {
+      setConnectionState(snapshot.connectionState);
+      setStreamError(snapshot.streamError);
+      setStreaming(snapshot.isStreaming);
+      if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
+        currentVideo.srcObject = snapshot.stream;
+      }
+    });
+    const snapshot = streamRegistry.getSnapshot(streamKey);
+    setConnectionState(snapshot.connectionState);
+    setStreamError(snapshot.streamError);
+    setStreaming(snapshot.isStreaming);
+
+    if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
+      currentVideo.srcObject = snapshot.stream;
+    }
 
-    // effect cleanup: AbortSignal 취소 및 peer 리소스 정리.
+    // effect cleanup: current video attach만 해제하고 registry stream은 유지한다.
     return () => {
-      controller.abort();
-      handle?.close();
-      handle = null;
-      currentVideo.srcObject = null;
+      unsubscribe();
+      detachVideo();
     };
   }, [
     endpoint,
+    streamIdentityKey,
+    streamKey,
+    streamRegistry,
     tokenQuery.data?.token,
     tokenQuery.isError,
-    cam?.cam_id,
     cam?.cam_online,
   ]);
 
+  const refetchToken = useCallback<typeof tokenQuery.refetch>(
+    async options => {
+      const result = await tokenQuery.refetch(options);
+      if (result.isSuccess && streamIdentityKey) {
+        streamRegistry.closeByIdentity(streamIdentityKey);
+      }
+      return result;
+    },
+    [streamIdentityKey, streamRegistry, tokenQuery],
+  );
+
   const liveState = useMemo(
     () =>
       cam
@@ -202,6 +250,6 @@ export function useCctvRtcStream({
     isStreaming,
     isTokenLoading,
     isTokenError,
-    refetchToken: tokenQuery.refetch,
+    refetchToken,
   };
 }

package/src/cctv/types/context.ts

@@ -59,13 +59,17 @@ export interface CctvApiUrlContext {
  * CCTV; 실시간 영상보기 컨텍스트
  * @property {string} [company_id] 선택된 업체 id코드
  * @property {string} [cam_id] 선택된 카메라 id코드
+ * @property {string} username CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [search] 검색 키워드 (입력값)
  * @property {string} [filter] 검색 키워드 (필터값)
  * @property {API_Res_CctvCompanyGroup[]} rawData 원본 데이터 배열
  * @property {boolean} isFetching 데이터 로딩 상태
  * @property {boolean} isError 데이터 에러 상태
  */
-export interface CctvContext extends CctvSelectedContext {
+export interface CctvBaseContext extends CctvSelectedContext {
+  /**
+   * CCTV 조회시 권한 확인을 위한 계정명
+   */
   username: string;
   /**
    * 검색 키워드 (입력값)
@@ -79,21 +83,56 @@ export interface CctvContext extends CctvSelectedContext {
    * 원본 데이터 배열
    */
   rawData: API_Res_CctvCompanyGroup[];
+  /**
+   * 데이터 로딩 상태
+   */
   isFetching: boolean;
+  /**
+   * 데이터 에러 상태
+   */
   isError: boolean;
 }
 
+/**
+ * CCTV; Provider form context
+ * @template ContextExtension
+ * @typedef {CctvBaseContext & ContextExtension} CctvContext
+ * @property {string} [company_id] 선택된 업체 id코드
+ * @property {string} [cam_id] 선택된 카메라 id코드
+ * @property {string} username CCTV 조회시 권한 확인을 위한 계정명
+ * @property {string} search 검색 키워드 입력값
+ * @property {string} filter 검색 키워드 필터값
+ * @property {API_Res_CctvCompanyGroup[]} rawData 원본 데이터 배열
+ * @property {boolean} isFetching 데이터 로딩 상태
+ * @property {boolean} isError 데이터 에러 상태
+ */
+export type CctvContext<ContextExtension extends object = object> =
+  CctvBaseContext & ContextExtension;
+
 /**
  * CCTV; Provider props
+ * @template ContextExtension
  * @property {string} [company_id] 선택된 업체 id코드
  * @property {string} [cam_id] 선택된 카메라 id코드
  * @property {string} [listUrl] company-list API 요청 경로
  * @property {string} [tokenUrl] token API 요청 경로
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
+ * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
  * @property {React.ReactNode} children
  */
-export type CctvProviderProps = CctvSelectedContext &
-  CctvApiUrlContext & {
-    username?: string;
-    children: React.ReactNode;
-  };
+export type CctvProviderProps<ContextExtension extends object = object> =
+  CctvSelectedContext &
+    CctvApiUrlContext & {
+      /**
+       * CCTV 조회시 권한 확인을 위한 계정명
+       */
+      username?: string;
+      /**
+       * 서비스 확장 context 기본값
+       */
+      defaultValues?: ContextExtension;
+      /**
+       * Provider 하위 콘텐츠
+       */
+      children: React.ReactNode;
+    };

package/src/cctv/types/hook.ts

@@ -7,7 +7,7 @@ import type {
   CctvCompanyGroupItems,
 } from "./list";
 import type { UseFormReturn } from "react-hook-form";
-import type { CctvContext } from "./context";
+import type { CctvBaseContext } from "./context";
 
 /**
  * CCTV; useCctvRtcStream params
@@ -135,7 +135,7 @@ export interface UseCctvCompanyDataReturn extends Omit<
  * @property {(cam_id: string) => void} onOpenCamera 카메라 선택 함수
  * @property {() => void} onCloseCamera 카메라 선택 해제 함수
  */
-export interface UseCctvContextReturn extends UseFormReturn<CctvContext> {
+export interface UseCctvContextReturn extends UseFormReturn<CctvBaseContext> {
   /**
    * 데이터 로딩 중 상태
    */