WebRTC 연결 진단 페이지 구현 플랜

마지막 업데이트 2026-07-22

1. 배경 — 무엇을 대체하는가

ovice 진단 사이트는 "수업에 필요한 통신이 성립하는지" 사전에 점검하는 도구다. 표준 WebRTC 진단 도구(webrtc/testrtc, Twilio Network Test)와 동일한 4가지를 본다.

2. 재사용 가능한 기존 자산

코드베이스 탐색 결과, 진단 항목 대부분이 이미 있는 훅에 1:1로 대응된다. 약 80%는 신규 작성이 아니라 재사용이다.

3. 신규로 만들어야 하는 것

4. 진단 항목별 구현 상세

4-1. STUN/TURN 도달성

핵심 진단. ICE 서버로 PC를 만들고 onicecandidate로 수집되는 candidate type을 본다. srflx(서버 reflexive)면 STUN 도달, relay면 TURN 도달이다.

const config = await getIceServers(); // 기존 use-ice-servers 재사용
const pc = new RTCPeerConnection(config);
const found = { host: false, srflx: false, relay: false };
pc.onicecandidate = (e) => {
  if (!e.candidate) return; // gathering 완료
  found[e.candidate.type] = true; // host | srflx | relay
};
pc.createDataChannel("probe");
await pc.setLocalDescription(await pc.createOffer());
// 일정 시간(~5s) 후 found 평가: relay=true 면 TURN OK

4-2. 마이크 / 카메라 / 스피커

디바이스 권한·열거는 use-device-manager를 그대로 쓰고, 마이크는 레벨 미터만 추가한다.

const ctx = new AudioContext();
const src = ctx.createMediaStreamSource(audioStream);
const analyser = ctx.createAnalyser();
src.connect(analyser);
// requestAnimationFrame 루프에서 getByteFrequencyData → 평균 레벨 막대 표시
// 카메라는 track.getSettings()로 width/height/frameRate 표시

4-3. 네트워크 latency / 품질

use-network-quality를 그대로 호출해 외부 + /api/health latency와 navigator.connection.effectiveType를 표시한다. 사용자 네트워크 문제인지 서버 문제인지 구분하는 기존 로직 재사용.

4-4. 루프백 대역폭/RTT

로컬에서 PC 2개를 서로 연결(같은 탭 내 offer/answer 교환)하고 DataChannel로 데이터를 흘려 throughput을, candidate-pair stats로 RTT를 측정한다. 그 후 use-webrtc-monitoring의 stats 파싱·품질 판정 로직을 재활용한다.

5. 단계별 작업 계획

6. 제안 파일 구조

apps/web/
├─ app/main/diagnosis/
│  └─ page.tsx                      # 진단 페이지 진입
├─ hooks/diagnosis/
│  ├─ use-diagnosis-runner.ts       # 단계 오케스트레이션/상태
│  ├─ use-ice-probe.ts              # STUN/TURN + relay-only 도달성
│  └─ use-loopback-probe.ts         # 로컬 PC 루프백 throughput/RTT
└─ components/sections/diagnosis/
   ├─ device-test-section.tsx       # 마이크 레벨/카메라/스피커
   ├─ network-test-section.tsx      # latency + ICE 결과
   └─ diagnosis-result.tsx          # 요약 + 로그 export

재사용(수정 거의 없음):
  hooks/use-ice-servers.ts, use-device-manager.ts,
  use-local-media-stream.ts, shared/lib/use-network-quality.ts
  components/sections/performance-monitor.tsx (품질 판정 로직)

7. 판정 기준(초안)

8. 결론 — 구현 가능성

• 현재 웹앱(apps/web) 내부 구현 가능. 추가 서버/인프라 불필요 — 기존 Metered TURN, /api/ice-servers, /api/health 재활용.
• 핵심 진단 로직(getUserMedia / RTCPeerConnection / getStats)은 전부 클라이언트 사이드라 같은 오리진에서 권한·CORS 이슈 없음.
• 재사용 ~80%, 신규는 진단 UI 조합 + 3~4개 테스트 케이스. 난이도·리스크 모두 낮음.

9. 알려진 한계 / 주의

10. 관련 문서

• 카드뷰 세션 변천사 — WebRTC 통계가 표시되는 모니터링 영역
• architecture — V1(P2P) / V2(mediasoup SFU) 전체 통신 구조