Socket.io + mediasoup SFU 서버 — 코드레벨 동작 흐름 P0코드레벨

개요 · 범위

apps/socket는 하나의 통합(unified) 프로세스로 두 개의 Socket.io 네임스페이스를 동시에 운영한다.

서버 부트스트랩 server.ts:55–174

startServer() 초기화 순서(순서가 중요 — 자원 의존성):

1. Redis 연결(connectRedis). REDIS_URL 비면 memory-only 모드로 skip.
2. mediasoup 워커 초기화(workerManager.initialize) → 녹음 매니저 초기화.
3. Express + http 서버 + Socket.io 생성.
4. Redis 어댑터: isAdapterEnabled()면 pub/sub로 cross-instance broadcast 연결(@socket.io/redis-adapter).
5. HTTP 메트릭 미들웨어 + Prometheus /metrics + REST 라우트 등록.
6. io.on("connection")(레거시) + io.of("/sfu") → setupSignalingHandlers.
7. 메트릭 수집 시작 + Reaper 스케줄러(REAPER_ENABLED!=="false"면 활성, leader-elected).
8. httpServer.listen(PORT) (기본 3001).

자원 계층 (싱글톤 매니저)

핸들러 등록 구조 signalingHandler.ts:107–261

setupSignalingHandlers(io)는 initRouterManagerSync(크로스인스턴스 room 메타 변경 구독)를 1회 init한 뒤, 접속(connection)마다 7개 핸들러군을 등록한다.

io.on("connection", (socket) => {
  setupConnectionHandlers(socket, peers, io);  // JOIN/LEAVE_ROOM, MONITOR_CONNECTED, GET_PEERS
  setupTransportHandlers(socket);            // CREATE/CONNECT_TRANSPORT
  setupMediaHandlers(socket);                // PRODUCE/CONSUME/RESUME/PAUSE/CLOSE/SET_LAYERS
  setupRoomHandlers(socket, peers, io);        // 입장승인·호스트 제어
  setupSessionHandlers(socket, peers, io);     // 세션 상태·릴레이 시그널
  setupAvatarHandlers(socket, peers, io);      // 아바타 상태 동기화
  setupMonitoringHandlers(socket, peers, io);  // 호스트 모니터링 claim
  socket.on("disconnect", ...);                  // 멀티-peer 정리(아래)
});

룸 입장 흐름 — JOIN_ROOM connection-handlers.ts:25–272

roomId 포맷은 {userId}_{lessonIndex}. 역할은 guest(아동) / host / monitor.

1. 1중복 게스트 정리. 같은 userId의 기존 게스트가 있으면 GUEST_DUPLICATE_CONNECTION 통지 후 transport/producer/consumer 정리·peer 삭제·peerCount 감소.
2. 2다중 인스턴스 라우팅(room pin). 모니터 제외. handshake.auth.targetInstance가 다른 인스턴스면 즉시 WRONG_INSTANCE redirect. 첫 도달이면 tryPinRoom; 실패 시 owner 인스턴스로 redirect. (room의 모든 peer를 한 인스턴스에 수렴)
3. 3PeerInfo 저장 + socket.join(roomId). 모니터는 roomId=null(룸 미참여), 호스트는 monitoringRoomId=roomId.
4. 4Router 확보. routerManager.getOrCreateRouter(roomId) (없으면 생성) → incrementPeerCount → joinedRoomId 기록(정확한 감소 추적용).
5. 5게스트면 guestState 초기화 + 재접속 backstop 처리: grace 내 재접속이면 pending 타이머 취소(+이전 세션을 disconnect 시각으로 종료해 누적시간 점프 방지), grace 만료면 LESSON_SESSION_EXPIRED 발송.
6. 6PEER_JOINED 통지 + isTest/groupId 동기화(게스트만).
7. 7기존 producer 목록 수집(자기 것 제외) → callback으로 { success, rtpCapabilities, existingProducers, instanceId } 반환. 클라이언트는 instanceId를 자기 owner로 기록.
8. 8broadcastRoomList(모니터 갱신), 호스트면 broadcastConnectedHosts.

입장 승인 room-handlers.ts

승인 전까지 게스트는 룸에 join은 되어 있으나 세션은 시작하지 않는다. 호스트 제어 이벤트(마이크/아바타/스텝 등)도 이 핸들러군에서 처리된다(세션 릴레이 #6 참고).

미디어 협상 — transport / produce / consume

① 트랜스포트 transport-handlers.ts

• CREATE_TRANSPORT {direction} → transportManager.createTransport → { id, iceParameters, iceCandidates, dtlsParameters } 반환. send/recv 각각 생성. recv는 setMaxIncomingBitrate 적용.
• CONNECT_TRANSPORT {transportId, dtlsParameters} → DTLS 핸드셰이크. transport DTLS가 closed/failed면 자동 close.

② 송출(produce) media-handlers.ts:12–114

PRODUCE { transportId, kind, rtpParameters, appData, roomId, peerId }
  └─ producerManager.createProducer(...)
  └─ socket.to(roomId).emit(NEW_PRODUCER, { producerId, kind, peerId })  // 같은 룸의 다른 peer가 consume하도록

③ 수신(consume) media-handlers.ts:117–319

• CONSUME {producerId, rtpCapabilities} → createConsumer(paused 상태로 생성 — 선택적 구독). producer의 appData.type을 consumer로 전달. consumer close 시 consumer-closed 통지(카드뷰 정확한 cleanup).
• RESUME_CONSUMER로 실제 수신 시작 / PAUSE_CONSUMER로 일시중지.
• SET_CONSUMER_LAYERS {spatialLayer, temporalLayer} → simulcast 레이어 선택(모니터 썸네일 180p ↔ 확대 720p). consumer not found는 disconnect 정상 케이스라 warn 처리.

접속 종료 정리 signalingHandler.ts:128–257

싱글톤 소켓이 여러 peer(모니터 카드뷰)를 가질 수 있어, 해당 socket.id를 가진 모든 peer를 모아 정리한다.

1. replaced 가드: 같은 peerId를 새 소켓이 이미 점유(게스트 새로고침 재진입)했으면 stale cleanup을 skip(새 owner 세션 보호).
2. 게스트면 guest-disconnected 통지 + guestState/manualReady 정리. pendingMetadata는 보존(재접속 녹음 재개용).
3. DB backstop: pendingDisconnectTracker.schedule로 grace 후 미종료 lesson session 일괄 종료 예약.
4. 녹음 중이면 stopRecording → RECORDING_STOPPED(성공/실패) 통지.
5. peer 삭제 + transport/producer/consumer 정리 + joinedRoomId 기준 peerCount 감소 + PEER_LEFT 통지.
6. 필요 시 broadcastRoomList / broadcastConnectedHosts.

다중 인스턴스 라우팅 (요약)

• room pin: tryPinRoom(Redis)으로 room을 한 인스턴스에 고정. 다른 인스턴스 도달 시 WRONG_INSTANCE + redirectInstance로 클라이언트가 owner에 재접속.
• router-sync: initRouterManagerSync가 Redis pub/sub로 room 메타 변경을 구독 → owner 메모리 refresh + broadcastRoomList 재전송.
• Socket.io Redis adapter: room-scoped broadcast가 인스턴스 경계를 넘도록.
• reaper: leader-elected로 죽은 인스턴스의 room/peer 메타를 원자적으로 정리.

상세는 → 로드맵 #5(Router 매니저/소유권), #16(Redis 인프라/reaper). 설계 의도는 Redis 트러블슈팅 가이드 및 handover 문서.

mediasoup 설정 sfu-config.ts, packages/shared MEDIASOUP_CONFIG

REST · 디버그 API server.ts:131–158, sfu-api/

함정 · 주의

• 인메모리 자원: peers Map·router·transport는 인스턴스 로컬. 인스턴스가 죽으면 복구 불가 → room pin + reaper로 일관성 유지. 직접 broadcast 시 cross-instance 누락 주의(adapter 경유).
• stale 이벤트 가드: JOIN/LEAVE/disconnect 모두 socketId 일치 검사로 새로고침 race에서 새 owner를 보호한다. 이 가드를 제거하면 유령 정리로 정상 세션이 끊긴다.
• peerCount는 joinedRoomId 기준: 모니터는 roomId=null이라 increment 대상이 아님. 감소 시 joinedRoomId를 써야 정확.
• consumer는 항상 paused로 생성: resume를 빼먹으면 "소리/영상 안 나옴" 버그. layer not-found는 정상(disconnect).
• 녹음 트리거는 produce 시점에 appData.type으로: mic-audio/ai-audio 순서·isAiSessionActive 상태에 의존. 트랙 메타(type) 누락 시 녹음이 안 걸린다.

파일 · 라인 레퍼런스

관련 문서

• 코드레벨 문서화 로드맵 (#2 본 문서)
• PPI 아키텍처 문서 (전체 개요)
• Redis 트러블슈팅 가이드 (다중 인스턴스)
• PPI-879 Redis 이관 회고
• OpenAI Realtime 세션 매니저 (#1, 클라이언트측)