@vibexnpm/talkx 2.3.1

package/src/webrtc/WebRTCClient.js

@@ -0,0 +1,1041 @@
+/**
+ * WebRTCClient
+ * WebRTC 통화 기능 클라이언트
+ */
+
+import EventEmitter from '../utils/EventEmitter.js';
+import Logger from '../utils/Logger.js';
+import MediaStreamManager from './MediaStreamManager.js';
+import PeerConnectionManager from './PeerConnectionManager.js';
+import { WebSocketPaths, SignalTypes, ErrorTypes, DefaultConfig, LogLevel } from '../constants.js';
+
+class WebRTCClient extends EventEmitter {
+    /**
+     * @param {Object} options
+     * @param {Object} options.connectionManager - ConnectionManager 인스턴스
+     * @param {Object} options.apiClient - ApiClient 인스턴스
+     * @param {string} options.userId - 사용자 ID
+     * @param {Object[]} [options.iceServers] - ICE 서버 설정
+     * @param {number} [options.logLevel] - 로그 레벨
+     */
+    constructor(options) {
+        super();
+
+        this.connectionManager = options.connectionManager;
+        this.apiClient = options.apiClient;
+        this.userId = options.userId;
+        this.logLevel = options.logLevel || LogLevel.WARN;
+
+        this.logger = new Logger(this.logLevel, 'WebRTCClient');
+
+        // 미디어 및 피어 연결 매니저
+        this.mediaManager = new MediaStreamManager({ logLevel: this.logLevel });
+        this.peerManager = new PeerConnectionManager({
+            iceServers: options.iceServers || DefaultConfig.iceServers,
+            logLevel: this.logLevel
+        });
+
+        // 현재 통화 상태
+        this.currentRoom = null;
+        this.isGroupCall = false;
+        this.participants = new Map();
+
+        // ICE 서버 초기화 상태
+        this._iceServersFetched = false;
+
+        // 1:1 통화 대기 상태 (CALL_REQUEST 전송 후 CALL_ACCEPT 대기)
+        this._waitingForCallAccept = false;
+        this._pendingCallTarget = null;
+
+        // ICE candidate 큐 (peer connection 생성 전에 도착한 candidate 저장)
+        this._pendingIceCandidates = new Map();
+
+        // 이벤트 연결
+        this._setupEventHandlers();
+    }
+
+    /**
+     * ICE 서버 설정 초기화 (TURN credentials 가져오기)
+     * 통화 시작 전 호출하면 더 빠른 연결 가능
+     * @returns {Promise<void>}
+     */
+    async initializeIceServers() {
+        if (this._iceServersFetched) {
+            return;
+        }
+
+        try {
+            const data = await this.getTurnCredentials();
+            if (data && data.iceServers) {
+                this.peerManager.setIceServers(data.iceServers);
+                this._iceServersFetched = true;
+                this.logger.info('ICE servers fetched successfully');
+            }
+        } catch (error) {
+            this.logger.warn('Failed to fetch TURN credentials, using fallback ICE servers:', error.message);
+            this._setFallbackIceServers();
+        }
+    }
+
+    /**
+     * 기본 ICE 서버 설정 (Fallback)
+     * @private
+     */
+    _setFallbackIceServers() {
+        this.peerManager.setIceServers([
+            { urls: 'stun:stun.l.google.com:19302' },
+            { urls: 'stun:stun1.l.google.com:19302' }
+        ]);
+    }
+
+    /**
+     * 이벤트 핸들러 설정
+     * @private
+     */
+    _setupEventHandlers() {
+        // 미디어 이벤트
+        this.mediaManager.on('streamStarted', (data) => this.emit('localStreamStarted', data));
+        this.mediaManager.on('streamStopped', (data) => this.emit('localStreamStopped', data));
+        this.mediaManager.on('videoToggled', () => this._sendMediaState());
+        this.mediaManager.on('audioToggled', () => this._sendMediaState());
+        this.mediaManager.on('screenShareStarted', (data) => this.emit('screenShareStarted', data));
+        this.mediaManager.on('screenShareEnded', (data) => this.emit('screenShareEnded', data));
+        this.mediaManager.on('error', (error) => this.emit('error', error));
+
+        // 피어 연결 이벤트
+        this.peerManager.on('remoteTrack', (data) => this.emit('remoteTrack', data));
+        this.peerManager.on('peerConnected', (data) => this.emit('peerConnected', data));
+        this.peerManager.on('peerDisconnected', (data) => this.emit('peerDisconnected', data));
+        this.peerManager.on('peerClosed', (data) => this.emit('peerClosed', data));
+        this.peerManager.on('error', (error) => this.emit('error', error));
+
+        // ICE Candidate 전송
+        this.peerManager.on('iceCandidate', ({ peerId, candidate }) => {
+            this._sendSignal({
+                type: SignalTypes.ICE_CANDIDATE,
+                receiverId: peerId,
+                data: { candidate }
+            });
+        });
+
+        // Negotiation (Offer 전송)
+        this.peerManager.on('negotiationNeeded', ({ peerId, description }) => {
+            this._sendSignal({
+                type: SignalTypes.CALL_OFFER,
+                receiverId: peerId,
+                data: { sdp: description }
+            });
+        });
+
+        // Answer 전송
+        this.peerManager.on('answerCreated', ({ peerId, answer }) => {
+            this._sendSignal({
+                type: SignalTypes.CALL_ANSWER,
+                receiverId: peerId,
+                data: { sdp: answer }
+            });
+        });
+    }
+
+    // ==================== REST API ====================
+
+    /**
+     * TURN 서버 인증 정보 가져오기
+     * @returns {Promise<Object>}
+     */
+    async getTurnCredentials() {
+        const response = await this.apiClient.get('/api/v1/webrtc/turn-credentials');
+        return response.data;
+    }
+
+    /**
+     * 통화방 생성
+     * @public
+     * @param {Object} data
+     * @param {string} data.roomName - 방 이름
+     * @param {boolean} data.isGroup - 그룹 통화 여부
+     * @param {string} [data.chatRoomId] - 연결할 채팅방 ID
+     * @returns {Promise<Object>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async createCallRoom(data) {
+        return this.apiClient.post('/api/v1/webrtc/rooms', data);
+    }
+
+    /**
+     * 통화방 정보 조회
+     * @public
+     * @param {string} roomId - 통화방 ID
+     * @returns {Promise<Object>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async getCallRoom(roomId) {
+        return this.apiClient.get(`/api/v1/webrtc/rooms/${roomId}`);
+    }
+
+    /**
+     * 통화방 참여
+     * @public
+     * @param {string} roomId - 통화방 ID
+     * @returns {Promise<Object>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async joinCallRoomApi(roomId) {
+        return this.apiClient.post(`/api/v1/webrtc/rooms/${roomId}/join`);
+    }
+
+    /**
+     * 통화방 나가기
+     * @public
+     * @param {string} roomId - 통화방 ID
+     * @returns {Promise<Object>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async leaveCallRoomApi(roomId) {
+        return this.apiClient.delete(`/api/v1/webrtc/rooms/${roomId}/leave`);
+    }
+
+    // ==================== 통화 수신 대기 ====================
+
+    /**
+     * 통화 수신 대기 활성화
+     * connect() 후 자동 호출되지만, 수동으로도 호출 가능
+     * 개인 WebRTC 채널(/user/queue/webrtc)을 구독하여 초대 알림 수신
+     * @public
+     * @returns {Promise<void>}
+     */
+    async enableIncomingCalls() {
+        if (this._incomingCallsEnabled) {
+            this.logger.debug('Incoming calls already enabled');
+            return;
+        }
+
+        await this._subscribeToDirectSignaling();
+        this._incomingCallsEnabled = true;
+        this.logger.info('Incoming calls enabled - now listening for call invitations');
+    }
+
+    /**
+     * 통화 수신 대기 비활성화
+     * @public
+     */
+    disableIncomingCalls() {
+        if (!this._incomingCallsEnabled) {
+            return;
+        }
+
+        const directDestination = WebSocketPaths.getWebRTCUserDestination();
+        this.connectionManager.unsubscribe(directDestination);
+        this._incomingCallsEnabled = false;
+        this.logger.info('Incoming calls disabled');
+    }
+
+    /**
+     * 통화 수신 대기 상태 확인
+     * @public
+     * @returns {boolean}
+     */
+    isIncomingCallsEnabled() {
+        return this._incomingCallsEnabled || false;
+    }
+
+    // ==================== 통화 기능 ====================
+
+    /**
+     * 통화 시작 (미디어 및 구독)
+     * @param {Object} options
+     * @param {string} options.roomId - 통화방 ID
+     * @param {boolean} [options.isGroup=false] - 그룹 통화 여부
+     * @param {Object} [options.mediaConstraints] - 미디어 제약조건
+     * @returns {Promise<MediaStream>}
+     */
+    async startCall(options) {
+        const { roomId, isGroup = false, mediaConstraints = { video: true, audio: true } } = options;
+
+        try {
+            // TURN 서버 설정 초기화
+            await this.initializeIceServers();
+
+            // 로컬 미디어 획득
+            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
+            this.peerManager.setLocalStream(localStream);
+
+            // 현재 방 설정
+            this.currentRoom = roomId;
+            this.isGroupCall = isGroup;
+
+            // WebSocket 구독
+            await this._subscribeToSignaling(roomId, isGroup);
+
+            // 입장 시그널 전송
+            this._sendSignal({
+                type: SignalTypes.JOIN_ROOM,
+                roomId
+            });
+
+            this.logger.info(`Call started in room: ${roomId}`);
+            this.emit('callStarted', { roomId, isGroup, localStream });
+
+            return localStream;
+
+        } catch (error) {
+            this.logger.error('Failed to start call:', error);
+            this.emit('error', {
+                type: ErrorTypes.PEER_CONNECTION_FAILED,
+                message: error.message,
+                error
+            });
+            throw error;
+        }
+    }
+
+    /**
+     * 1:1 통화 요청
+     * @param {string} targetUserId - 상대방 사용자 ID
+     * @param {Object} [mediaConstraints] - 미디어 제약조건
+     */
+    async callUser(targetUserId, mediaConstraints = { video: true, audio: true }) {
+        try {
+            // TURN 서버 설정 초기화
+            await this.initializeIceServers();
+
+            // 로컬 미디어 획득
+            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
+            this.peerManager.setLocalStream(localStream);
+
+            // 1:1 통화 구독
+            await this._subscribeToDirectSignaling();
+
+            // CALL_ACCEPT 대기 상태 설정
+            // PeerConnection은 CALL_ACCEPT를 받은 후에 생성하여 자동 negotiation 방지
+            this._waitingForCallAccept = true;
+            this._pendingCallTarget = targetUserId;
+
+            // 통화 요청 시그널
+            this._sendSignal({
+                type: SignalTypes.CALL_REQUEST,
+                receiverId: targetUserId
+            });
+
+            this.currentRoom = null;
+            this.isGroupCall = false;
+
+            this.emit('callRequested', { targetUserId, localStream });
+
+        } catch (error) {
+            this.logger.error('Failed to call user:', error);
+            this._waitingForCallAccept = false;
+            this._pendingCallTarget = null;
+            throw error;
+        }
+    }
+
+    /**
+     * 통화 수락
+     * @param {string} callerId - 발신자 ID
+     * @param {Object} [mediaConstraints] - 미디어 제약조건
+     */
+    async acceptCall(callerId, mediaConstraints = { video: true, audio: true }) {
+        try {
+            // TURN 서버 설정 초기화
+            await this.initializeIceServers();
+
+            // 로컬 미디어 획득 (수신자도 미디어 필요)
+            const localStream = await this.mediaManager.getUserMedia(mediaConstraints);
+            this.peerManager.setLocalStream(localStream);
+
+            // 피어 연결 생성 (Polite - 수신자)
+            // skipAutoNegotiation: true - 수신자는 offer를 받아서 answer를 보내므로 자동 negotiation 불필요
+            this.peerManager.createPeerConnection(callerId, true, { skipAutoNegotiation: true });
+
+            // 수락 시그널
+            this._sendSignal({
+                type: SignalTypes.CALL_ACCEPT,
+                receiverId: callerId
+            });
+
+            this.emit('callAccepted', { callerId });
+
+        } catch (error) {
+            this.logger.error('Failed to accept call:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * 통화 거절
+     * @param {string} callerId - 발신자 ID
+     */
+    rejectCall(callerId) {
+        this._sendSignal({
+            type: SignalTypes.CALL_REJECT,
+            receiverId: callerId
+        });
+
+        this.emit('callRejected', { callerId });
+    }
+
+    /**
+     * 통화 취소 (발신자가 수신자 응답 전 취소)
+     */
+    cancelCall() {
+        if (this._waitingForCallAccept && this._pendingCallTarget) {
+            this._sendSignal({
+                type: SignalTypes.CALL_CANCEL,
+                receiverId: this._pendingCallTarget
+            });
+
+            this.emit('callCancelled', { targetUserId: this._pendingCallTarget });
+
+            // 대기 상태 초기화
+            this._waitingForCallAccept = false;
+            this._pendingCallTarget = null;
+
+            // 미디어 정리
+            this.mediaManager.stopAll();
+        }
+    }
+
+    /**
+     * 통화 종료
+     */
+    endCall() {
+        // 대기 중인 통화가 있으면 취소 처리
+        if (this._waitingForCallAccept && this._pendingCallTarget) {
+            this._sendSignal({
+                type: SignalTypes.CALL_CANCEL,
+                receiverId: this._pendingCallTarget
+            });
+        }
+
+        // 대기 상태 초기화
+        this._waitingForCallAccept = false;
+        this._pendingCallTarget = null;
+
+        if (this.currentRoom) {
+            // 퇴장 시그널 전송
+            this._sendSignal({
+                type: SignalTypes.LEAVE_ROOM,
+                roomId: this.currentRoom
+            });
+
+            // 구독 해제
+            this._unsubscribeFromSignaling();
+        }
+
+        // 모든 피어에게 종료 시그널
+        this.peerManager.getPeerIds().forEach(peerId => {
+            this._sendSignal({
+                type: SignalTypes.CALL_END,
+                receiverId: peerId
+            });
+        });
+
+        // 정리
+        this.peerManager.closeAllPeerConnections();
+        this.mediaManager.stopAll();
+        this.participants.clear();
+        this._pendingIceCandidates.clear();
+
+        const roomId = this.currentRoom;
+        this.currentRoom = null;
+        this.isGroupCall = false;
+
+        this.emit('callEnded', { roomId });
+        this.logger.info('Call ended');
+    }
+
+    // ==================== 미디어 제어 ====================
+
+    /**
+     * 비디오 토글
+     * @returns {boolean}
+     */
+    toggleVideo() {
+        return this.mediaManager.toggleVideo();
+    }
+
+    /**
+     * 오디오 토글
+     * @returns {boolean}
+     */
+    toggleAudio() {
+        return this.mediaManager.toggleAudio();
+    }
+
+    /**
+     * 화면 공유 시작
+     * @returns {Promise<MediaStream>}
+     */
+    async startScreenShare() {
+        const screenStream = await this.mediaManager.getDisplayMedia();
+
+        // 피어들에게 화면 공유 트랙 전송
+        const videoTrack = screenStream.getVideoTracks()[0];
+        const localVideoTrack = this.mediaManager.getTrack('video');
+
+        if (localVideoTrack && videoTrack) {
+            await this.peerManager.replaceTrack(localVideoTrack, videoTrack);
+        }
+
+        // 화면 공유 종료 시 원복 — 복원 시점의 현재 카메라 트랙 사용 (공유 중 switchDevice 대응)
+        videoTrack.onended = async () => {
+            const currentVideoTrack = this.mediaManager.getTrack('video');
+            if (currentVideoTrack) {
+                await this.peerManager.replaceTrack(videoTrack, currentVideoTrack);
+            }
+            this.emit('screenShareEnded', {});
+        };
+
+        return screenStream;
+    }
+
+    /**
+     * 화면 공유 중지
+     */
+    stopScreenShare() {
+        const screenStream = this.mediaManager.getScreenStream();
+        if (screenStream) {
+            screenStream.getTracks().forEach(track => track.stop());
+        }
+    }
+
+    /**
+     * 로컬 스트림 가져오기
+     * @public
+     * @returns {MediaStream|null}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    getLocalStream() {
+        return this.mediaManager.getLocalStream();
+    }
+
+    /**
+     * 디바이스 목록 가져오기
+     * @returns {Promise<Object>}
+     */
+    async getDevices() {
+        return this.mediaManager.getDevices();
+    }
+
+    /**
+     * 디바이스 전환
+     * @param {string} deviceId
+     * @param {string} kind - 'video' or 'audio'
+     */
+    async switchDevice(deviceId, kind) {
+        // switchDevice가 localStream을 교체하므로, 교체 전 기존 트랙을 먼저 저장
+        const oldTrack = this.mediaManager.getTrack(kind);
+        const newTrack = await this.mediaManager.switchDevice(deviceId, kind);
+
+        // 피어들에게 트랙 교체
+        if (oldTrack) {
+            await this.peerManager.replaceTrack(oldTrack, newTrack);
+        }
+
+        return newTrack;
+    }
+
+    /**
+     * 비디오 상태 직접 설정
+     * @public
+     * @param {boolean} enabled
+     */
+    // noinspection JSUnusedGlobalSymbols
+    setVideoEnabled(enabled) {
+        this.mediaManager.setVideoEnabled(enabled);
+        this._sendMediaState();
+    }
+
+    /**
+     * 오디오 상태 직접 설정
+     * @public
+     * @param {boolean} enabled
+     */
+    // noinspection JSUnusedGlobalSymbols
+    setAudioEnabled(enabled) {
+        this.mediaManager.setAudioEnabled(enabled);
+        this._sendMediaState();
+    }
+
+    /**
+     * 디바이스 변경 감지 시작
+     * @public
+     */
+    // noinspection JSUnusedGlobalSymbols
+    startDeviceChangeDetection() {
+        this.mediaManager.startDeviceChangeDetection();
+        this.mediaManager.on('deviceChange', (devices) => {
+            this.emit('deviceChange', devices);
+        });
+    }
+
+    /**
+     * 디바이스 변경 감지 중지
+     * @public
+     */
+    // noinspection JSUnusedGlobalSymbols
+    stopDeviceChangeDetection() {
+        this.mediaManager.stopDeviceChangeDetection();
+    }
+
+    /**
+     * 비디오 해상도/프레임레이트 변경
+     * @public
+     * @param {Object} constraints - { width, height, frameRate }
+     * @returns {Promise<void>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async applyVideoConstraints(constraints) {
+        return this.mediaManager.applyVideoConstraints(constraints);
+    }
+
+    /**
+     * 현재 비디오 설정 가져오기
+     * @public
+     * @returns {MediaTrackSettings|null}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    getVideoSettings() {
+        return this.mediaManager.getVideoSettings();
+    }
+
+    /**
+     * 현재 오디오 설정 가져오기
+     * @public
+     * @returns {MediaTrackSettings|null}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    getAudioSettings() {
+        return this.mediaManager.getAudioSettings();
+    }
+
+    // ==================== 시그널링 ====================
+
+    /**
+     * 시그널링 구독
+     * @private
+     */
+    async _subscribeToSignaling(roomId, isGroup) {
+        if (isGroup) {
+            // 그룹 통화: /topic/webrtc/{roomId}
+            const destination = WebSocketPaths.getWebRTCDestination(roomId);
+            await this.connectionManager.subscribe(destination, (message) => {
+                this._handleSignal(message);
+            });
+        }
+
+        // 1:1 또는 그룹 모두에서 개인 큐 구독
+        await this._subscribeToDirectSignaling();
+    }
+
+    /**
+     * 1:1 시그널링 구독
+     * @private
+     */
+    async _subscribeToDirectSignaling() {
+        const destination = WebSocketPaths.getWebRTCUserDestination();
+        await this.connectionManager.subscribe(destination, (message) => {
+            this._handleSignal(message);
+        });
+    }
+
+    /**
+     * 시그널링 구독 해제
+     * @private
+     */
+    _unsubscribeFromSignaling() {
+        if (this.currentRoom && this.isGroupCall) {
+            const destination = WebSocketPaths.getWebRTCDestination(this.currentRoom);
+            this.connectionManager.unsubscribe(destination);
+        }
+
+        // 수신 대기가 활성화된 경우 direct 채널 구독 유지 (그룹 통화 종료 후에도 수신 가능)
+        if (!this._incomingCallsEnabled) {
+            const directDestination = WebSocketPaths.getWebRTCUserDestination();
+            this.connectionManager.unsubscribe(directDestination);
+        }
+    }
+
+    /**
+     * 시그널 전송
+     * @private
+     */
+    _sendSignal(signal) {
+        const payload = {
+            type: signal.type,
+            roomId: signal.roomId || this.currentRoom,
+            receiverId: signal.receiverId,
+            data: signal.data
+        };
+
+        this.connectionManager.send(WebSocketPaths.WEBRTC_SIGNAL, payload);
+        this.logger.debug('Signal sent:', payload);
+    }
+
+    /**
+     * 미디어 상태 전송
+     * @private
+     */
+    _sendMediaState() {
+        if (!this.currentRoom && this.peerManager.getPeerIds().length === 0) {
+            return;
+        }
+
+        const mediaState = {
+            videoEnabled: this.mediaManager.isVideoEnabled(),
+            audioEnabled: this.mediaManager.isAudioEnabled()
+        };
+
+        this._sendSignal({
+            type: SignalTypes.VIDEO_STATE_CHANGED,
+            data: mediaState
+        });
+
+        this.emit('mediaStateChanged', mediaState);
+    }
+
+    /**
+     * 시그널 처리
+     * @private
+     */
+    async _handleSignal(message) {
+        const { type, senderId, data } = message;
+
+        // 자신의 시그널 무시
+        if (senderId === this.userId) {
+            return;
+        }
+
+        this.logger.debug(`Signal received: ${type} from ${senderId}`);
+
+        switch (type) {
+            case SignalTypes.JOIN_ROOM:
+            case SignalTypes.PEER_JOINED:
+                await this._handleUserJoined(senderId);
+                break;
+
+            case SignalTypes.LEAVE_ROOM:
+            case SignalTypes.PEER_LEFT:
+                this._handleUserLeft(senderId);
+                break;
+
+            case SignalTypes.CALL_OFFER:
+                await this._handleOffer(senderId, data.sdp);
+                break;
+
+            case SignalTypes.CALL_ANSWER:
+                await this._handleAnswer(senderId, data.sdp);
+                break;
+
+            case SignalTypes.ICE_CANDIDATE:
+                await this._handleIceCandidate(senderId, data.candidate);
+                break;
+
+            case SignalTypes.VIDEO_STATE_CHANGED:
+            case SignalTypes.AUDIO_STATE_CHANGED:
+                this._handleMediaState(senderId, data);
+                break;
+
+            case SignalTypes.CALL_REQUEST:
+                // 통화 중이거나 통화 요청 대기 중이면 BUSY 응답
+                if (this.isInCall() || this._waitingForCallAccept) {
+                    this._sendSignal({
+                        type: SignalTypes.CALL_BUSY,
+                        receiverId: senderId
+                    });
+                    this.emit('incomingCallWhileBusy', { callerId: senderId });
+                } else {
+                    this.emit('incomingCall', { callerId: senderId });
+                }
+                break;
+
+            case SignalTypes.CALL_BUSY:
+                // 상대방이 통화 중
+                this._waitingForCallAccept = false;
+                this._pendingCallTarget = null;
+                this.mediaManager.stopAll();
+                this.emit('callBusy', { userId: senderId });
+                break;
+
+            case SignalTypes.CALL_INVITATION:
+                // 그룹 통화 초대 (createCallRoom으로 초대받은 경우)
+                this.emit('callInvitation', {
+                    callRoomId: data?.callRoomId || message.roomId,
+                    title: data?.title,
+                    hostUserId: data?.hostUserId || senderId,
+                    maxParticipants: data?.maxParticipants,
+                    createdAt: data?.createdAt
+                });
+                break;
+
+            case SignalTypes.CALL_ACCEPT:
+                await this._handleCallAccepted(senderId);
+                break;
+
+            case SignalTypes.CALL_REJECT:
+                // 대기 상태 초기화
+                this._waitingForCallAccept = false;
+                this._pendingCallTarget = null;
+                // 발신자 미디어 정리 (거절당했으므로 통화 불가)
+                this.mediaManager.stopAll();
+                this.emit('callRejected', { userId: senderId });
+                break;
+
+            case SignalTypes.CALL_CANCEL:
+                // 대기 상태 초기화
+                this._waitingForCallAccept = false;
+                this._pendingCallTarget = null;
+                this.emit('callCancelled', { userId: senderId });
+                break;
+
+            case SignalTypes.CALL_END:
+                this._handleCallEnded(senderId);
+                break;
+
+            default:
+                this.logger.warn(`Unknown signal type: ${type}`);
+        }
+    }
+
+    /**
+     * 사용자 입장 처리
+     * @private
+     */
+    async _handleUserJoined(userId) {
+        this.participants.set(userId, { joinedAt: new Date() });
+
+        // userId 비교로 Polite/Impolite 결정 (작은 쪽이 Polite)
+        // Perfect Negotiation에서 충돌 시 한 쪽만 양보하도록 보장
+        const polite = this.userId < userId;
+        this.peerManager.createPeerConnection(userId, polite);
+
+        this.emit('userJoined', { userId });
+        this.logger.info(`User joined: ${userId} (I am ${polite ? 'polite' : 'impolite'})`);
+    }
+
+    /**
+     * 사용자 퇴장 처리
+     * @private
+     */
+    _handleUserLeft(userId) {
+        this.participants.delete(userId);
+        this.peerManager.closePeerConnection(userId);
+
+        this.emit('userLeft', { userId });
+        this.logger.info(`User left: ${userId}`);
+    }
+
+    /**
+     * Offer 처리
+     * @private
+     */
+    async _handleOffer(senderId, sdp) {
+        // 피어 연결이 없으면 생성
+        if (!this.peerManager.getPeerConnection(senderId)) {
+            // userId 비교로 Polite/Impolite 결정
+            const polite = this.userId < senderId;
+            // skipAutoNegotiation: true - offer를 먼저 처리한 후 answer 전송
+            // 트랙 추가 시 자동 negotiation이 발생하면 offer 충돌 발생
+            this.peerManager.createPeerConnection(senderId, polite, { skipAutoNegotiation: true });
+        }
+
+        await this.peerManager.handleRemoteDescription(senderId, sdp);
+
+        // remoteDescription 설정 후 대기 중인 ICE candidates 처리
+        await this._processPendingIceCandidates(senderId);
+    }
+
+    /**
+     * Answer 처리
+     * @private
+     */
+    async _handleAnswer(senderId, sdp) {
+        await this.peerManager.handleRemoteDescription(senderId, sdp);
+        // remoteDescription 설정 후 대기 중인 ICE candidates 처리
+        await this._processPendingIceCandidates(senderId);
+    }
+
+    /**
+     * ICE Candidate 처리
+     * @private
+     */
+    async _handleIceCandidate(senderId, candidate) {
+        // peer connection이 아직 없으면 큐에 저장
+        if (!this.peerManager.getPeerConnection(senderId)) {
+            this._queueIceCandidate(senderId, candidate);
+            return;
+        }
+
+        // addIceCandidate가 false 반환하면 (remoteDescription 미설정) 큐에 저장
+        const added = await this.peerManager.addIceCandidate(senderId, new RTCIceCandidate(candidate));
+        if (!added) {
+            this._queueIceCandidate(senderId, candidate);
+        }
+    }
+
+    /**
+     * ICE candidate를 큐에 저장
+     * @private
+     */
+    _queueIceCandidate(peerId, candidate) {
+        if (!this._pendingIceCandidates.has(peerId)) {
+            this._pendingIceCandidates.set(peerId, []);
+        }
+        this._pendingIceCandidates.get(peerId).push(candidate);
+        this.logger.debug(`ICE candidate queued for ${peerId}`);
+    }
+
+    /**
+     * 대기 중인 ICE candidate 처리
+     * @private
+     */
+    async _processPendingIceCandidates(peerId) {
+        const candidates = this._pendingIceCandidates.get(peerId);
+        if (!candidates || candidates.length === 0) {
+            return;
+        }
+
+        this.logger.debug(`Processing ${candidates.length} pending ICE candidates for ${peerId}`);
+
+        for (const candidate of candidates) {
+            await this.peerManager.addIceCandidate(peerId, new RTCIceCandidate(candidate));
+        }
+
+        this._pendingIceCandidates.delete(peerId);
+    }
+
+    /**
+     * 미디어 상태 처리
+     * @private
+     */
+    _handleMediaState(userId, state) {
+        this.emit('participantMediaState', {
+            userId,
+            videoEnabled: state.videoEnabled,
+            audioEnabled: state.audioEnabled
+        });
+    }
+
+    /**
+     * 통화 수락 처리 (발신자 측에서 CALL_ACCEPT 수신 시)
+     * @private
+     */
+    async _handleCallAccepted(userId) {
+        // 대기 상태 초기화
+        this._waitingForCallAccept = false;
+        this._pendingCallTarget = null;
+
+        // 이제 PeerConnection 생성 (Impolite - 발신자)
+        // skipAutoNegotiation: true - 트랙 추가 시 자동 negotiation 건너뛰고 수동으로 offer 전송
+        this.peerManager.createPeerConnection(userId, false, { skipAutoNegotiation: true });
+
+        // Offer 생성 및 전송
+        const offer = await this.peerManager.createOffer(userId);
+        this._sendSignal({
+            type: SignalTypes.CALL_OFFER,
+            receiverId: userId,
+            data: { sdp: offer }
+        });
+
+        this.emit('callAccepted', { userId });
+    }
+
+    /**
+     * 통화 종료 처리
+     * @private
+     */
+    _handleCallEnded(userId) {
+        this.peerManager.closePeerConnection(userId);
+        this.participants.delete(userId);
+
+        this.emit('participantLeft', { userId });
+
+        // 모든 참여자가 나갔으면 통화 종료
+        if (this.peerManager.getPeerIds().length === 0) {
+            this.endCall();
+        }
+    }
+
+    // ==================== 유틸리티 ====================
+
+    /**
+     * 현재 통화 중인지 확인
+     * @returns {boolean}
+     */
+    isInCall() {
+        return this.currentRoom !== null || this.peerManager.getPeerIds().length > 0;
+    }
+
+    /**
+     * 현재 통화방 ID
+     * @returns {string|null}
+     */
+    getCurrentRoom() {
+        return this.currentRoom;
+    }
+
+    /**
+     * 참여자 목록
+     * @returns {string[]}
+     */
+    getParticipants() {
+        return Array.from(this.participants.keys());
+    }
+
+    /**
+     * 연결 상태 요약
+     * @public
+     * @returns {Object}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    getConnectionSummary() {
+        return this.peerManager.getConnectionSummary();
+    }
+
+    /**
+     * 특정 피어의 연결 통계 가져오기 (디버깅/모니터링용)
+     * @public
+     * @param {string} peerId - 피어 ID
+     * @returns {Promise<RTCStatsReport|null>}
+     */
+    // noinspection JSUnusedGlobalSymbols
+    async getStats(peerId) {
+        return this.peerManager.getStats(peerId);
+    }
+
+    /**
+     * 미디어 상태
+     * @returns {Object}
+     */
+    getMediaState() {
+        return {
+            videoEnabled: this.mediaManager.isVideoEnabled(),
+            audioEnabled: this.mediaManager.isAudioEnabled(),
+            streamInfo: this.mediaManager.getStreamInfo()
+        };
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level
+     */
+    setLogLevel(level) {
+        this.logger.setLevel(level);
+        this.mediaManager.setLogLevel(level);
+        this.peerManager.setLogLevel(level);
+    }
+
+    /**
+     * 리소스 정리
+     */
+    destroy() {
+        this.endCall();
+        this.mediaManager.destroy();
+        this.peerManager.destroy();
+        this.removeAllListeners();
+        this.logger.info('WebRTCClient destroyed');
+    }
+}
+
+export default WebRTCClient;