@vibexnpm/talkx 8.5.0 → 8.7.0

package/src/core/ConnectionManager.js

@@ -37,7 +37,8 @@ class ConnectionManager extends EventEmitter {
      * @param {string} options.projectId - 프로젝트 ID
      * @param {boolean} [options.useSockJS=true] - SockJS 사용 여부
      * @param {number} [options.reconnectDelay] - 재연결 지연 시간
-     * @param {number} [options.maxReconnectAttempts] - 최대 재연결 시도 횟수
+     * @param {number} [options.maxReconnectAttempts] - 한 묶음의 최대 재연결 시도 횟수
+     * @param {number} [options.reconnectRecoveryDelay=60000] - 기존 연결의 재시도 소진 후 대기(ms), 0이면 비활성화
      * @param {number} [options.heartbeatIncoming] - 수신 하트비트 간격
      * @param {number} [options.heartbeatOutgoing] - 발신 하트비트 간격
      * @param {number} [options.logLevel] - 로그 레벨
@@ -54,6 +55,7 @@ class ConnectionManager extends EventEmitter {
         this.reconnectDelay = options.reconnectDelay || DefaultConfig.reconnectDelay;
         this.maxReconnectDelay = options.maxReconnectDelay || DefaultConfig.maxReconnectDelay;
         this.maxReconnectAttempts = options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts;
+        this.reconnectRecoveryDelay = options.reconnectRecoveryDelay ?? DefaultConfig.reconnectRecoveryDelay;
         this.heartbeatIncoming = options.heartbeatIncoming || DefaultConfig.heartbeatIncoming;
         this.heartbeatOutgoing = options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing;
         this.resumeOnVisibility = options.resumeOnVisibility !== false;
@@ -77,6 +79,9 @@ class ConnectionManager extends EventEmitter {
         // forceReconnect 단일 실행 보장 (복귀 이벤트 3종이 거의 동시에 들어온다).
         this._forceReconnectPromise = null;
         this._lifecycleHandlers = null;
+        this._recoveryTimer = null;
+        this._terminalAuthError = false;
+        this._recoveryEligible = false;
 
         this._installLifecycleListeners();
     }
@@ -148,7 +153,7 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onResume(reason) {
-        if (!this.resumeOnVisibility || this._intentionalDisconnect) {
+        if (!this.resumeOnVisibility || this._intentionalDisconnect || this._terminalAuthError) {
             return;
         }
 
@@ -209,26 +214,26 @@ class ConnectionManager extends EventEmitter {
      * @returns {Promise<void>}
      */
     async forceReconnect(reason) {
-        if (this._intentionalDisconnect || this.state === ConnectionState.CONNECTING) {
+        if (this._intentionalDisconnect || this._terminalAuthError || this.state === ConnectionState.CONNECTING) {
             return;
         }
 
         // 단일 실행 — 복귀 시 visibilitychange / pageshow / online 이 거의 동시에 들어오는데,
         // deactivate() 를 await 하는 동안 state 는 아직 CONNECTED 라 재진입 가드가 없으면
         // 두 번째 resume 이 그대로 통과해 클라이언트를 이중으로 만든다.
-        if (this._forceReconnectPromise) {
-            this.logger.debug(`Force reconnect already in progress, joining: ${reason}`);
-            return this._forceReconnectPromise;
+        if (!this._forceReconnectPromise) {
+            this._forceReconnectPromise = this._doForceReconnect(reason)
+                .finally(() => { this._forceReconnectPromise = null; });
         }
-
-        this._forceReconnectPromise = this._doForceReconnect(reason)
-            .finally(() => { this._forceReconnectPromise = null; });
-
-        return this._forceReconnectPromise;
+        await this._forceReconnectPromise;
+        // 외부 호출의 완료 의미는 유지하되, 다음 복구 묶음을 막는 실행 잠금은 이미 풀었다.
+        try { await this._connectPromise; }
+        catch { /* connect/error 이벤트가 종료 사유를 전달한다. */ }
     }
 
     /** @private */
     async _doForceReconnect(reason) {
+        this._cancelReconnectRecovery();
         this.logger.info(`Force reconnect: ${reason}`);
 
         if (this.stompClient) {
@@ -243,12 +248,16 @@ class ConnectionManager extends EventEmitter {
             this.stompClient = null;
         }
 
+        if (this._intentionalDisconnect || this._terminalAuthError) return;
+
         // connect() 가 CONNECTED/CONNECTING 이면 조기 반환하므로 상태를 먼저 내려둔다.
         this._setState(ConnectionState.DISCONNECTED);
         this.reconnectAttempts = 0;
 
         try {
-            await this.connect();
+            // 활성화까지만 직렬화한다. connect 대기는 장애 전체에 걸쳐 유지되므로
+            // 여기서 await 하면 다음 저빈도 복구가 이 잠금에 막힌다.
+            this.connect().catch(error => this.logger.warn(`Force reconnect failed (${reason}):`, error));
         } catch (error) {
             this.logger.warn(`Force reconnect failed (${reason}):`, error);
         }
@@ -288,25 +297,35 @@ class ConnectionManager extends EventEmitter {
      */
     _createStompClient() {
         const wsUrl = this._getWebSocketUrl();
+        // 교체된 클라이언트(정지 뒤 새 토큰으로 다시 연결 등)의 늦은 콜백은 현재 연결 상태를 바꾸지 않는다.
+        let stomp = null;
+        const current = () => !this.stompClient || this.stompClient === stomp;
 
         const config = {
             beforeConnect: async (client) => {
-                if (!this.getAccessToken) return;
+                if (!this.getAccessToken) {
+                    this._connectionToken = this.jwtToken;
+                    return;
+                }
                 let attempt = 0;
                 while (!this._intentionalDisconnect && (!client || client.active)) {
                     try {
                         const token = await this.getAccessToken({ forceRefresh: this._authRejected === true });
                         if (this._intentionalDisconnect || (client && !client.active)) return;
+                        if (this._authRejected && (!token || token.replace(/^Bearer\s+/i, '') === this._rejectedToken)) {
+                            this._stopForAuthError(new Error('Authentication rejected without a new access token'), client);
+                            return;
+                        }
                         this.updateToken(token);
+                        this._connectionToken = token;
                         this._authRejected = false;
                         return;
                     } catch (error) {
                         this.emit('error', { type: ErrorTypes.CONNECTION_FAILED, message: error.message, error });
+                        // 거부된 access token과 갱신 요청의 일시 실패는 별개다.
+                        // 새 토큰/동일 토큰 판정은 위에서, 확정된 인증 종료만 여기서 처리한다.
                         if (isTerminalAuthError(error)) {
-                            this._setState(ConnectionState.ERROR);
-                            this._connectReject?.(error);
-                            this._connectResolve = this._connectReject = null;
-                            await (client || this.stompClient)?.deactivate();
+                            this._stopForAuthError(error, client);
                             return;
                         }
                         // beforeConnect의 예외에는 STOMP 소켓 종료 백오프가 적용되지 않는다.
@@ -329,7 +348,8 @@ class ConnectionManager extends EventEmitter {
             },
             heartbeatIncoming: this.heartbeatIncoming,
             heartbeatOutgoing: this.heartbeatOutgoing,
-            reconnectDelay: this.reconnectDelay,
+            // stompjs는 연결 성공 시 다음 지연을 저장한다. close 콜백보다 먼저 지터를 적용한다.
+            reconnectDelay: this.reconnectDelay * (0.8 + Math.random() * 0.4),
             // 지수 백오프 — 고정 간격이면 서버 재시작 시 전 클라이언트가 같은 주기로 몰린다.
             // STOMP 7 내장 기능이라 직접 타이머를 굴리지 않는다.
             reconnectTimeMode: ReconnectionTimeMode.EXPONENTIAL,
@@ -339,11 +359,11 @@ class ConnectionManager extends EventEmitter {
                     this.logger.debug('STOMP:', str);
                 }
             },
-            onConnect: (frame) => this._onConnect(frame),
-            onDisconnect: (frame) => this._onDisconnect(frame),
-            onStompError: (frame) => this._onStompError(frame),
-            onWebSocketClose: (event) => this._onWebSocketClose(event),
-            onWebSocketError: (event) => this._onWebSocketError(event)
+            onConnect: (frame) => { if (current()) this._onConnect(frame); },
+            onDisconnect: (frame) => { if (current()) this._onDisconnect(frame); },
+            onStompError: (frame) => { if (current()) this._onStompError(frame); },
+            onWebSocketClose: (event) => { if (current()) this._onWebSocketClose(event); },
+            onWebSocketError: (event) => { if (current()) this._onWebSocketError(event); }
         };
 
         if (this.useSockJS) {
@@ -357,7 +377,8 @@ class ConnectionManager extends EventEmitter {
         }
 
         const Client = getStompClient();
-        return new Client(config);
+        stomp = new Client(config);
+        return stomp;
     }
 
     /**
@@ -370,29 +391,35 @@ class ConnectionManager extends EventEmitter {
             return;
         }
 
-        if (this.state === ConnectionState.CONNECTING) {
-            this.logger.warn('Connection in progress');
-            return;
+        if (!this._connectPromise) {
+            this._connectPromise = new Promise((resolve, reject) => {
+                const clear = () => {
+                    this._connectPromise = null;
+                    this._connectResolve = this._connectReject = null;
+                };
+                this._connectResolve = () => { clear(); resolve(); };
+                this._connectReject = error => { clear(); reject(error); };
+            });
         }
-
+        const connected = this._connectPromise;
+        if (this.stompClient && (this.state === ConnectionState.CONNECTING || this.state === ConnectionState.RECONNECTING)) {
+            return connected;
+        }
+        this._cancelReconnectRecovery();
+        this._terminalAuthError = false;
         this._setState(ConnectionState.CONNECTING);
         this.reconnectAttempts = 0;
         this._intentionalDisconnect = false;
         this._connectRequested = true;
-
-        return new Promise((resolve, reject) => {
-            this._connectResolve = resolve;
-            this._connectReject = reject;
-
-            try {
-                this.stompClient = this._createStompClient();
-                this.stompClient.activate();
-            } catch (error) {
-                this._setState(ConnectionState.ERROR);
-                this._drainPendingSubscriptions('Connection activation failed');
-                reject(error);
-            }
-        });
+        try {
+            this.stompClient = this._createStompClient();
+            this.stompClient.activate();
+        } catch (error) {
+            this._setState(ConnectionState.ERROR);
+            this._drainPendingSubscriptions('Connection activation failed');
+            this._connectReject?.(error);
+        }
+        return connected;
     }
 
     /**
@@ -408,6 +435,10 @@ class ConnectionManager extends EventEmitter {
         this._setState(ConnectionState.CONNECTED);
         this.reconnectAttempts = 0;
         this._hasConnectedBefore = true;
+        this._recoveryEligible = true;
+        this._authRejected = false;
+        this._rejectedToken = null;
+        this._notifiedRejectedToken = null;
         this.logger.info('Connected to server', frame);
 
         // 기존 구독 재등록 (재연결 시)
@@ -458,12 +489,13 @@ class ConnectionManager extends EventEmitter {
             frame
         };
 
-        // terminal 전이 — 대기 중 구독 Promise 가 영구 hang 되지 않도록 drain.
-        this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
+        if (this._authRejected) this._recordAuthRejection();
+        const terminal = !this._canRecoverConnection();
+        if (terminal) this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
 
         this.emit('error', error);
 
-        if (this._connectReject) {
+        if (terminal && this._connectReject) {
             this._connectReject(new Error(error.message));
             this._connectResolve = null;
             this._connectReject = null;
@@ -475,13 +507,12 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onWebSocketClose(event) {
-        if (this.stompClient && event?.code === 1012) this.stompClient.reconnectDelay = this.reconnectDelay * (0.8 + Math.random() * 0.4);
-        if (event?.code === 4001) this._authRejected = true;
+        if (event?.code === 4001) this._recordAuthRejection();
         this.logger.warn('WebSocket closed:', event);
 
         // forceReconnect 의 의도적 teardown 이면 재연결 시도로 집계하지 않는다 —
         // 카운터가 오염되면 복귀 직후 다시 max 를 소진해버린다.
-        if (this._tearingDown) {
+        if (this._tearingDown || this._intentionalDisconnect || this._terminalAuthError) {
             this.logger.debug('WebSocket closed during intentional teardown — not counting as reconnect');
             return;
         }
@@ -498,11 +529,8 @@ class ConnectionManager extends EventEmitter {
     _onWebSocketError(event) {
         this.logger.error('WebSocket error:', event);
 
-        // 초기 연결 실패 경로 — _connectReject 가 살아있다는 건 아직 한 번도
-        // CONNECTED 된 적이 없다는 뜻. pending 구독도 함께 drain 해서 호출자 hang 방지.
-        // 이미 CONNECTED 후 일시 끊김은 _onWebSocketClose → _handleReconnect 로 흘러
-        // 재연결 성공 시 _processPendingSubscriptions 가 살린다.
-        if (this._connectReject) {
+        // 이전에 연결된 클라이언트의 복구 중에는 원래 호출자의 대기를 유지한다.
+        if (this._connectReject && !this._canRecoverConnection()) {
             this._drainPendingSubscriptions('WebSocket connection failed');
             this._connectReject(new Error('WebSocket connection failed'));
             this._connectResolve = null;
@@ -523,17 +551,26 @@ class ConnectionManager extends EventEmitter {
         this.reconnectAttempts++;
 
         if (this.reconnectAttempts > this.maxReconnectAttempts) {
-            if (this.stompClient) {
-                try {
-                    this.stompClient.deactivate();
-                } catch (error) {
-                    this.logger.warn('Error deactivating stomp client on max reconnect:', error);
-                }
-                this.stompClient = null;
+            const exhaustedClient = this.stompClient;
+            this.stompClient = null;
+            // 같은 STOMP 인스턴스의 타이머를 완전히 끈 뒤 저빈도 복구를 예약한다.
+            // Promise 안에서 호출을 시작하면 stompjs가 close 이후 재시도를 먼저 예약할 수 있다.
+            let deactivated;
+            try {
+                deactivated = exhaustedClient?.deactivate();
+            } catch (error) {
+                this.logger.warn('Error deactivating stomp client on max reconnect:', error);
+            }
+            Promise.resolve(deactivated).catch(error => {
+                this.logger.warn('Error deactivating stomp client on max reconnect:', error);
+            }).then(() => this._scheduleReconnectRecovery());
+
+            // 복구 묶음 사이에서도 같은 connect/subscribe 요청을 유지한다.
+            if (!this._canRecoverConnection()) {
+                this._connectReject?.(new Error('Max reconnection attempts exceeded'));
+                this._connectResolve = this._connectReject = null;
+                this._drainPendingSubscriptions('Max reconnection attempts exceeded');
             }
-
-            // terminal 전이 — 재연결 성공으로 살릴 기회가 사라졌으므로 pending 도 drain.
-            this._drainPendingSubscriptions('Max reconnection attempts exceeded');
 
             this._setState(ConnectionState.ERROR);
             this.emit('error', {
@@ -548,6 +585,61 @@ class ConnectionManager extends EventEmitter {
         this.logger.info(`Reconnecting... attempt ${this.reconnectAttempts}`);
     }
 
+    /** 실제 거부된 자격 증명을 기록한다. 공급 함수가 있어도 정적 토큰일 수 있다. */
+    _recordAuthRejection() {
+        this._authRejected = true;
+        this._rejectedToken = (this._connectionToken || this.jwtToken).replace(/^Bearer\s+/i, '');
+        if (!this.getAccessToken) this._stopForAuthError(new Error('STOMP error: authentication rejected'));
+    }
+
+    _stopForAuthError(error, client = this.stompClient) {
+        // 같은 거부 토큰은 한 번만 알린다. 오류 처리기가 connect() 를 다시 불러도 즉시 정지 → 알림이 반복되지 않는다.
+        const notify = !this._terminalAuthError && this._usesStaticToken() && this._rejectedToken !== this._notifiedRejectedToken;
+        this._terminalAuthError = true;
+        this._recoveryEligible = false;
+        this._cancelReconnectRecovery();
+        this._setState(ConnectionState.ERROR);
+        this._connectReject?.(error);
+        this._drainPendingSubscriptions(error.message);
+        // beforeConnect 안에서도 호출된다. 여기서 deactivate 완료를 기다리지 않는다.
+        Promise.resolve(client?.deactivate()).catch(failure => this.logger.warn('Auth teardown failed:', failure));
+        // 정적 토큰 모드는 정지를 오류 이벤트(FE connectionError)로 알린다. 새 토큰은 updateToken() 으로 온다.
+        // 정지 전이(이 함수와 호출한 _onStompError 의 나머지)를 마친 뒤 알린다. 처리기의 updateToken()·connect() 가 정리 중인 연결과 섞이지 않는다.
+        if (notify) {
+            this._notifiedRejectedToken = this._rejectedToken;
+            Promise.resolve().then(() => this.emit('error', { type: ErrorTypes.CONNECTION_LOST, message: error.message, error }));
+        }
+    }
+
+    /** 갱신 세션이 없는 정적 토큰(레거시) 모드. canRefreshToken 은 TalkFlowClient 가 설치한다. */
+    _usesStaticToken() {
+        return !this.getAccessToken || this.canRefreshToken?.() === false;
+    }
+
+    _canRecoverConnection() {
+        return this._recoveryEligible && !this._intentionalDisconnect && !this._terminalAuthError
+            && this.reconnectRecoveryDelay > 0;
+    }
+
+    /** 기존에 연결됐던 클라이언트만 긴 장애 후 탭 이벤트 없이 다시 시도한다. */
+    _scheduleReconnectRecovery() {
+        if (!this._canRecoverConnection() || this.state !== ConnectionState.ERROR || this.stompClient) return;
+        this._cancelReconnectRecovery();
+        const delay = this.reconnectRecoveryDelay * (0.8 + Math.random() * 0.4);
+        this._recoveryTimer = setTimeout(() => {
+            this._recoveryTimer = null;
+            if (!this._intentionalDisconnect && !this._terminalAuthError && this.state === ConnectionState.ERROR) {
+                this.forceReconnect('retry-cooldown');
+            }
+        }, delay);
+        this._recoveryTimer.unref?.();
+    }
+
+    _cancelReconnectRecovery() {
+        clearTimeout(this._recoveryTimer);
+        this._recoveryTimer = null;
+    }
+
     /**
      * 기존 구독 재등록 (재연결 시)
      * @private
@@ -684,6 +776,13 @@ class ConnectionManager extends EventEmitter {
                 'Authorization': token.startsWith('Bearer ') ? token : `Bearer ${token}`
             };
         }
+
+        // 정적 토큰 모드에서 거부된 토큰으로 정지했다면 새 토큰으로 다시 연결한다. 같은 토큰이면 정지를 유지한다.
+        // connect() 는 진행 중인 연결을 공유한다. connect(jwt) 가 이어서 connect() 를 불러도 클라이언트는 하나다.
+        if (this._terminalAuthError && !this._intentionalDisconnect && this._usesStaticToken()
+                && token.replace(/^Bearer\s+/i, '') !== this._rejectedToken) {
+            this.connect().catch(error => this.logger.warn('Reconnect with updated token failed:', error));
+        }
     }
 
     /**
@@ -695,6 +794,10 @@ class ConnectionManager extends EventEmitter {
     async disconnect() {
         // 명시적 해제 — 포그라운드 복귀가 이걸 되살리면 안 된다.
         this._intentionalDisconnect = true;
+        this._recoveryEligible = false;
+        this._authRejected = false;
+        this._rejectedToken = null;
+        this._cancelReconnectRecovery();
         this._connectRequested = false;
         this._cancelAuthRetry?.();
         this._connectReject?.(Object.assign(new Error('Connection cancelled'), { code: 'AUTH_OPERATION_CANCELLED' }));

package/src/index.js

@@ -14,6 +14,7 @@
  * import TalkFlowClient from '@talkflow/sdk';
  *
  * // 1단계: 로그인. 클라이언트 생성 «전» 에 부른다 — ck/projectId/JWT 를 한 번에 받는다.
+ * //        회사 계정이 둘 이상이면 먼저 { workspaceSelectionRequired, workspaces } 가 온다 → projectId 를 실어 다시 부른다.
  * const { clientKey, projectId, accessToken } = await TalkFlowClient.loginUser({
  *   serverUrl: 'https://chat.apiorbit.net',
  *   email: 'me@example.com',

package/src/talkflow/eventForwarding.js

@@ -68,6 +68,7 @@ const WEBRTC_EVENT_MAP = [
     ['mediaStateChanged', 'mediaStateChanged'],
     ['callStarted', 'callStarted'],
     ['callEnded', 'callEnded'],
+    ['callRecoveryFailed', 'callRecoveryFailed'],
     ['callRequested', 'callRequested'],
     ['callAccepted', 'callAccepted'],
     ['callRejected', 'callRejected'],

package/src/talkflow/session.js

@@ -23,6 +23,7 @@ export function initializeSubClients(client) {
         reconnectDelay: client.options.reconnectDelay,
         maxReconnectDelay: client.options.maxReconnectDelay,
         maxReconnectAttempts: client.options.maxReconnectAttempts,
+        reconnectRecoveryDelay: client.options.reconnectRecoveryDelay,
         heartbeatIncoming: client.options.heartbeatIncoming,
         heartbeatOutgoing: client.options.heartbeatOutgoing,
         resumeOnVisibility: client.options.resumeOnVisibility,
@@ -32,6 +33,8 @@ export function initializeSubClients(client) {
         if (!client.authSession) return client.options.jwtToken;
         return client.authSession.getAccessToken({ forceRefresh, rejectedToken: client.connectionManager?.jwtToken });
     };
+    // 레거시 모드의 공급자는 정적 토큰을 돌려줄 뿐이다. 새 토큰은 updateToken() 으로만 온다.
+    client.connectionManager.canRefreshToken = () => !!client.authSession;
 
     client._chat = new ChatClient({
         connectionManager: client.connectionManager,

package/src/webrtc/PeerConnectionManager.js

@@ -91,6 +91,15 @@ class PeerConnectionManager extends EventEmitter {
         return connection;
     }
 
+    /** 그룹 시작 중 answer를 먼저 보낸 peer에 로컬 트랙을 보낼 협상을 재개한다. */
+    async resumeAutoNegotiation(peerId) {
+        const peer = this.peers.get(peerId);
+        if (!peer || peer.connection.signalingState !== 'stable') return false;
+        peer.skipAutoNegotiation = false;
+        await peer.connection.onnegotiationneeded();
+        return true;
+    }
+
     /**
      * 연결 이벤트 핸들러 설정
      * @private
@@ -146,7 +155,7 @@ class PeerConnectionManager extends EventEmitter {
         // 협상 필요 (Perfect Negotiation)
         connection.onnegotiationneeded = async () => {
             // 1:1 통화에서 수동으로 offer를 생성할 때는 자동 negotiation 건너뛰기
-            if (peerState.skipAutoNegotiation) {
+            if (peerState.skipAutoNegotiation || peerState.makingOffer || connection.signalingState !== 'stable') {
                 this.logger.debug(`Skipping auto negotiation for ${peerId} (manual offer will be sent)`);
                 return;
             }