Router 매니저 — 크로스인스턴스 소유권·router-sync 코드레벨 동작 흐름 P0코드레벨

개요 · 범위

PPI-879 이후 SFU 소켓 서버는 다중 인스턴스 + Redis(Valkey) SoT 구조다. mediasoup Router는 인스턴스 메모리에만 존재(복구 불가)하므로, 한 room의 모든 peer를 한 인스턴스(owner)에 고정(pin)하고, 메모리는 캐시+owner 표지로만 쓰며 진실은 Redis에 둔다. 이 문서는 그 핵심인 routerManager(657L)와 room-store를 다룬다.

5분 핵심 출처: redis-infra.md#5분-안에-알아야-할-것

메모리 vs Redis 역할

Invariants 출처: redis-infra.md#invariants

Router 생성 createRouter L137 / getOrCreateRouter L184

• 이미 메모리에 있으면 그 router 반환. 없으면 workerManager.getWorker()(라운드로빈)로 worker.createRouter({mediaCodecs}).
• 메모리 먼저, Redis 나중 패턴(L161–164): rooms.set 후 awaitRedis(setRoomMeta). 같은 인스턴스 후속 로직(broadcastRoomList)이 즉시 fresh를 보게 하고, cross-instance read는 어차피 Redis adapter로 처리되므로 순서 무관.
• 신규 room 기본값: autoTransitionEnabled=true, realtimeModelVersion=v1.0, guestState=null.

Room Pin — 원자적 소유권 획득 room-store.ts: tryPinRoom L124 / PIN_ROOM_LUA L94

JOIN_ROOM(게스트/호스트) 시 tryPinRoom(roomId)을 호출해 owner를 정한다(모니터는 제외). 단일 Lua 스크립트로 완전 원자 처리:

-- KEYS[1]=room:{id}:instance, ARGV: newInstanceId, ttl, keyPrefix, roomId
owner = GET roomInstanceKey
if owner == false       → SET owner=new(EX ttl) + SADD instance:new:rooms → {1,new}
if owner == newInstance  → EXPIRE 갱신 + SADD(멱등)         → {1,new}
if owner heartbeat 없음  → SREM old:rooms, SET new, SADD     → {1,new}  (stale 인계)
else                     → {0, owner}  (살아있는 다른 owner → 실패)

• TTL = heartbeatTtlSeconds * 3 (기본 90s).
• 실패 시({0,owner}) connection-handler가 WRONG_INSTANCE + redirectInstance=ownerInstanceId로 응답 → 클라이언트가 owner 인스턴스로 재접속(#2 JOIN_ROOM 참고).
• stale owner(heartbeat 만료) 자동 인계가 Lua 안에 포함 → owner가 죽으면 다음 pin이 자연스럽게 takeover.

Owner 권한 모델 — setter 분기

모든 상태 setter(setAutoTransitionEnabled, setVadSettings, setNoiseReduction, updateGuestState 등)는 동일한 owner/non-owner 분기를 쓴다.

updateGuestState 예시 L527–561

• owner: guestState null이면 initGuestState 후, applyGuestStateUpdates로 merge → room.guestState=merged(메모리 먼저) → Redis await.
• 비-owner: redisGetRoomMeta로 현재 상태 읽어 merge → Redis write → publishRoomSync. (호스트가 비-owner 인스턴스에 붙은 카드뷰에서 토글한 경우)

router-sync — cross-instance 메모리 정합 publishRoomSync L115 / initRouterManagerSync L628

비-owner가 Redis를 바꾸면 owner의 메모리 캐시는 모른다. 이를 pub/sub로 해소한다.

• 채널: ROOM_SYNC_CHANNEL = redisKey("router-sync") (STAGE prefix 격리, #640).
• publishRoomSync는 cross-instance write 경로(비-owner setter, peerCount cross-instance 등)에서만 호출. owner 자기 write는 메모리가 이미 fresh라 불필요.
• owner가 사라진 room의 인계도 이 채널 기반(id-041).

peerCount · router 종료 increment/decrementPeerCount L216/234

• owner: 메모리 peerCount++/-- + Redis Lua(INCREMENT/DECREMENT_PEER_COUNT_LUA). 비-owner: Redis Lua만 + publishRoomSync.
• increment 시 예약된 router close 타이머 취소. decrement로 0 도달 시 router 종료 스케줄(단, Redis await 중 재입장 가능성 때문에 재확인).

router 종료 race / pin 폴백 회귀: id-028

reaper 연계 (요약)

인스턴스는 heartbeat를 Redis ZSET에 주기 발행한다. leader로 뽑힌 인스턴스의 reaper가 heartbeat 끊긴 인스턴스의 instance:{id}:rooms / peer 매핑을 원자적으로 정리한다. room pin의 stale takeover(PIN_ROOM_LUA의 heartbeat 체크)와 짝을 이룬다. 상세는 → 로드맵 #16(Redis 인프라/reaper).

함정 · 회귀 패턴 출처: redis-infra.md#failure-modes

• 비-owner setter 호출: 가드 누락 시 잘못된 인스턴스가 메모리를 덮음(id-021). setter 추가 시 owner 분기 필수.
• async race: 비동기 처리 중 owner가 바뀌어 갱신이 잘못 적용(id-043).
• owner 메모리/Redis 불일치: cross-instance 변경 시 메모리만 갱신 → router-sync로 해결(id-041). publishRoomSync 누락 주의.
• cross-instance hydration 누락: 새 인스턴스가 default로 시작(예: getNoiseReduction Redis fallback 없으면, id-006). 새 상태엔 Redis fallback 경로 필수.
• 저장 vs broadcast 순서: Redis 저장 전 broadcast하면 일부 인스턴스 stale(id-019).
• 채널 prefix 미적용: dev/prod 또는 브랜치 간 이벤트 누설(#640, id-009). 채널/키 추가 시 key-prefix.ts 정책 준수.
• stale peer 매핑: upsertPeer가 이전 인덱스 미정리(id-032).

파일 · 라인 레퍼런스

관련 문서

• 코드레벨 문서화 로드맵 (#5 본 문서 — P0 완료)
• Socket.io + mediasoup SFU 서버 (#2, JOIN_ROOM/pin 진입)
• Redis 트러블슈팅 가이드
• PPI-879 Redis 이관 회고
• (예정) Redis 인프라/reaper #16