@uniai-fe/uds-templates 0.6.26 → 0.6.28

package/src/cctv/hooks/streamScheduler.ts

@@ -0,0 +1,276 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type {
+  CctvRtcStreamOptions,
+  CctvRtcStreamScheduleStatus,
+} from "../types";
+
+const DEFAULT_STREAM_SCHEDULER_OPTIONS = {
+  batchSize: 4,
+  batchIntervalMs: 1200,
+} satisfies Required<CctvRtcStreamOptions>;
+
+type StreamSchedulerListener = () => void;
+
+/**
+ * CCTV; RTC stream scheduler contract
+ * @property {(identityKey: string) => () => void} request stream 시작 순번 요청 함수
+ * @property {(identityKey: string) => CctvRtcStreamScheduleStatus} getStatus stream 시작 순번 상태 조회 함수
+ * @property {(listener: StreamSchedulerListener) => () => void} subscribe scheduler 변경 구독 함수
+ * @property {() => void} clear scheduler 내부 상태 정리 함수
+ */
+export interface CctvRtcStreamScheduler {
+  /**
+   * stream 시작 순번 요청 함수
+   */
+  request: (identityKey: string) => () => void;
+  /**
+   * stream 시작 순번 상태 조회 함수
+   */
+  getStatus: (identityKey: string) => CctvRtcStreamScheduleStatus;
+  /**
+   * scheduler 변경 구독 함수
+   */
+  subscribe: (listener: StreamSchedulerListener) => () => void;
+  /**
+   * scheduler 내부 상태 정리 함수
+   */
+  clear: () => void;
+}
+
+/**
+ * CCTV; RTC stream scheduler 옵션 정규화
+ * @param {CctvRtcStreamOptions} [options] Provider에서 전달한 stream lazy loading 옵션
+ * @returns {Required<CctvRtcStreamOptions>} scheduler 내부에서 사용할 확정 옵션
+ * @desc
+ * service가 잘못된 수치를 넘겨도 기본값과 최소 clamp만 적용해 scheduler가 멈추지 않게 한다.
+ */
+const getNormalizedSchedulerOptions = (
+  options?: CctvRtcStreamOptions,
+): Required<CctvRtcStreamOptions> => {
+  // optional 값을 먼저 지역 변수로 좁혀 TypeScript가 number 판정을 안정적으로 추론하게 한다.
+  const batchSizeCandidate = options?.batchSize;
+  const batchIntervalCandidate = options?.batchIntervalMs;
+
+  // batchSize는 한 번에 grant할 stream 수라 1보다 작으면 scheduler가 진행되지 않는다.
+  const batchSize =
+    typeof batchSizeCandidate === "number" &&
+    Number.isFinite(batchSizeCandidate)
+      ? Math.max(1, Math.floor(batchSizeCandidate))
+      : DEFAULT_STREAM_SCHEDULER_OPTIONS.batchSize;
+
+  // batchIntervalMs는 batch 사이 대기시간이며 0은 연속 flush 허용값으로 둔다.
+  const batchIntervalMs =
+    typeof batchIntervalCandidate === "number" &&
+    Number.isFinite(batchIntervalCandidate)
+      ? Math.max(0, Math.floor(batchIntervalCandidate))
+      : DEFAULT_STREAM_SCHEDULER_OPTIONS.batchIntervalMs;
+
+  return {
+    batchSize,
+    batchIntervalMs,
+  };
+};
+
+/**
+ * CCTV; RTC stream scheduler 생성
+ * @param {CctvRtcStreamOptions} [options] stream lazy loading 옵션
+ * @returns {CctvRtcStreamScheduler} stream 시작 순번 scheduler
+ * @desc
+ * item UI는 즉시 렌더하되 token/WHEP 시작만 batch 단위로 열어 초기 요청 burst를 줄인다.
+ */
+export function createCctvRtcStreamScheduler(
+  options?: CctvRtcStreamOptions,
+): CctvRtcStreamScheduler {
+  // Provider option은 scheduler 생성 시점에 확정해 queue 처리 중 정책 drift를 막는다.
+  const { batchSize, batchIntervalMs } = getNormalizedSchedulerOptions(options);
+
+  // queue는 아직 token/WHEP 시작 권한을 받지 못한 stream identity 순서를 보관한다.
+  const queue: string[] = [];
+
+  // granted는 token query를 열 수 있는 stream identity 집합이다.
+  const granted = new Set<string>();
+
+  // requestCounts는 같은 stream identity를 여러 component가 동시에 쓰는 경우 premature release를 막는다.
+  const requestCounts = new Map<string, number>();
+
+  // listeners는 hook state와 scheduler 내부 상태를 동기화하는 구독자 집합이다.
+  const listeners = new Set<StreamSchedulerListener>();
+
+  // timer는 다음 batch flush 예약을 단일화해 중복 setTimeout을 방지한다.
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const notify = () => {
+    // queue/grant 상태가 바뀌면 모든 hook subscriber가 status를 다시 읽는다.
+    listeners.forEach(listener => listener());
+  };
+
+  const clearTimer = () => {
+    // 예약된 flush가 없으면 timer cleanup은 no-op으로 둔다.
+    if (!timer) return;
+
+    clearTimeout(timer);
+    timer = null;
+  };
+
+  const flush = () => {
+    // 현재 timer callback이 실행됐으므로 다음 예약이 가능하도록 비운다.
+    timer = null;
+
+    // FIFO 순서대로 이번 batch 크기만큼 grant한다.
+    const nextBatch = queue.splice(0, batchSize);
+    nextBatch.forEach(identityKey => {
+      granted.add(identityKey);
+    });
+
+    // 실제 grant 변화가 있을 때만 subscriber를 깨운다.
+    if (nextBatch.length > 0) {
+      notify();
+    }
+
+    // 아직 대기열이 남아 있으면 다음 batch를 interval 뒤에 예약한다.
+    if (queue.length > 0) {
+      timer = setTimeout(flush, batchIntervalMs);
+    }
+  };
+
+  const scheduleFlush = () => {
+    // 이미 예약된 flush가 있으면 같은 queue에 중복 timer를 만들지 않는다.
+    if (timer) return;
+
+    // 첫 batch는 즉시 열고, 이후 batch만 interval을 적용한다.
+    timer = setTimeout(flush, granted.size === 0 ? 0 : batchIntervalMs);
+  };
+
+  return {
+    request(identityKey) {
+      // 같은 stream identity를 여러 video가 요청하면 reference count만 증가시킨다.
+      const currentCount = requestCounts.get(identityKey) ?? 0;
+      requestCounts.set(identityKey, currentCount + 1);
+
+      // 이미 grant됐거나 queue에 있으면 중복 등록하지 않는다.
+      if (!granted.has(identityKey) && !queue.includes(identityKey)) {
+        queue.push(identityKey);
+        notify();
+        scheduleFlush();
+      }
+
+      return () => {
+        // cleanup은 hook unmount 또는 identity 변경 때 호출되며 reference count를 먼저 낮춘다.
+        const nextCount = (requestCounts.get(identityKey) ?? 1) - 1;
+
+        // 아직 같은 identity를 쓰는 component가 남아 있으면 grant/queue 상태를 유지한다.
+        if (nextCount > 0) {
+          requestCounts.set(identityKey, nextCount);
+          return;
+        }
+
+        // 마지막 subscriber가 사라지면 scheduler 상태에서 identity를 제거한다.
+        requestCounts.delete(identityKey);
+        granted.delete(identityKey);
+
+        // 아직 grant 전 queue에 남아 있던 identity라면 대기열에서도 제거한다.
+        const queuedIndex = queue.indexOf(identityKey);
+        if (queuedIndex > -1) {
+          queue.splice(queuedIndex, 1);
+        }
+
+        // 더 이상 처리할 queue가 없으면 다음 flush 예약도 취소한다.
+        if (queue.length === 0) {
+          clearTimer();
+        }
+
+        // release 결과를 subscriber에게 알려 `queued -> idle` 또는 `granted -> idle` 전환을 반영한다.
+        notify();
+      };
+    },
+    getStatus(identityKey) {
+      // token query를 열 수 있는 상태를 최우선으로 반환한다.
+      if (granted.has(identityKey)) return "granted";
+
+      // queue에 들어갔지만 아직 grant되지 않은 상태는 overlay에서 대기 상태로 표시된다.
+      if (queue.includes(identityKey)) return "queued";
+
+      // 요청 전이거나 release 이후면 idle이다.
+      return "idle";
+    },
+    subscribe(listener) {
+      // hook이 scheduler 상태 변경을 React state로 동기화할 수 있게 listener를 등록한다.
+      listeners.add(listener);
+
+      return () => {
+        // hook cleanup 시 listener 누수를 막는다.
+        listeners.delete(listener);
+      };
+    },
+    clear() {
+      // Provider unmount 시 timer와 모든 mutable scheduler 상태를 비운다.
+      clearTimer();
+      queue.splice(0, queue.length);
+      granted.clear();
+      requestCounts.clear();
+
+      // 마지막 상태 변화를 알린 뒤 listener 집합도 비운다.
+      notify();
+      listeners.clear();
+    },
+  };
+}
+
+/**
+ * CCTV; RTC stream scheduler 상태 구독
+ * @hook
+ * @param {CctvRtcStreamScheduler} scheduler stream 시작 순번 scheduler
+ * @param {string} identityKey stream identity key
+ * @param {boolean} enabled scheduler 요청 활성화 여부
+ * @returns {CctvRtcStreamScheduleStatus} stream 시작 순번 상태
+ */
+export function useCctvRtcStreamScheduleStatus({
+  enabled,
+  identityKey,
+  scheduler,
+}: {
+  /**
+   * scheduler 요청 활성화 여부
+   */
+  enabled: boolean;
+  /**
+   * stream identity key
+   */
+  identityKey: string;
+  /**
+   * stream 시작 순번 scheduler
+   */
+  scheduler: CctvRtcStreamScheduler;
+}): CctvRtcStreamScheduleStatus {
+  const [status, setStatus] = useState<CctvRtcStreamScheduleStatus>("idle");
+
+  useEffect(() => {
+    // 필수 identity가 없거나 offline이면 scheduler에 등록하지 않고 idle로 되돌린다.
+    if (!enabled || !identityKey) {
+      setStatus("idle");
+      return;
+    }
+
+    // scheduler mutable state를 React state로 복사해 render가 status 변화를 감지하게 한다.
+    const syncStatus = () => {
+      setStatus(scheduler.getStatus(identityKey));
+    };
+
+    // subscribe 이후 request해야 request 직후 notify도 놓치지 않는다.
+    const unsubscribe = scheduler.subscribe(syncStatus);
+    const release = scheduler.request(identityKey);
+
+    // request 직후 현재 상태를 즉시 반영해 queued/granted 표시 지연을 줄인다.
+    syncStatus();
+
+    return () => {
+      // cleanup 순서는 scheduler reference release 후 listener 제거로 둬 release notify를 받을 수 있게 한다.
+      release();
+      unsubscribe();
+    };
+  }, [enabled, identityKey, scheduler]);
+
+  return status;
+}