@coclaw/openclaw-coclaw 0.21.3 → 0.21.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",

package/src/webrtc/webrtc-peer.js

@@ -7,6 +7,7 @@ import { RpcDcSender, DC_LOW_WATER_MARK, MAX_SINGLE_MSG_BYTES } from './rpc-dc-s
 import { createRpcDropMonitor } from './rpc-drop-monitor.js';
 import { isAgentRunResponse } from './agent-run-response.js';
 import { remoteLog } from '../remote-log.js';
+import { createMutex } from '../utils/mutex.js';
 
 // rpc DC 发送队列实现选择（B-stage2 B9b）。
 // - 'fbq'：FileBackedQueue（当前生产默认）—— 长时间后台 / ICE 恢复等慢消化场景溢出到磁盘
@@ -71,6 +72,11 @@ export class WebRtcPeer {
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
 		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, rpcDropMonitor: object|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
+		// per-connId offer mutex：串行化同 connId 的 __handleOffer 调用，防止两条 ICE restart
+		// offer 几乎同时到达时三连 await 中间被并发 offer 重入触发 pion 状态机
+		// InvalidModificationError。lazy 创建，closeByConnId 末尾 delete 释放。
+		/** @type {Map<string, ReturnType<typeof createMutex>>} */
+		this.__offerMutexes = new Map();
 	}
 
 	/** 处理来自 Server 转发的信令消息 */
@@ -142,6 +148,15 @@ export class WebRtcPeer {
 			session.rpcChannel = null;
 		}
 		await session.pc.close();
+		// 清理 per-connId offer mutex 键：mutex 生命期与 session 生命期一一对应，
+		// session 销毁时 mutex 同步销毁（详见 __handleOffer 注释）。
+		// 注意：__handleOffer 内部 mutex 引用是闭包已在 mu.withLock 内拿到；
+		// 此处 delete 只影响 Map 键，不影响排队中的 fn 执行；后续同 connId 新 offer
+		// 走 lazy create 路径建新 mutex（旧 mutex 队列若仍有 fn 也能跑完）。
+		// 已知边界：当 closeByConnId 是从 __handleOfferLocked 内部触发时（restart-failed catch
+		// 或首次 offer 替换旧 session），fn 仍持有 mutex；此期间新 offer 进来会创建 M2
+		// 与 M1 并发——split race 在 TODO.md 追踪，不在本修法范围闭合。
+		this.__offerMutexes.delete(connId);
 		this.__remoteLog(`rtc.closed conn=${connId}`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
 	}
@@ -212,6 +227,46 @@ export class WebRtcPeer {
 	async __handleOffer(msg) {
 		const connId = msg.fromConnId;
 		const isIceRestart = !!msg.payload?.iceRestart;
+
+		// no-session ICE restart 不需要串行化：直接 reject，不进 mutex。
+		// 设计意图：mutex 生命期严格对齐 session（仅在有 session 时存在），
+		// 短命路径不为它建/拆 mutex。同时该路径本身就是"无 session 立即 reject"的语义，
+		// 没有任何可序列化的状态。
+		if (isIceRestart && !this.__sessions.has(connId)) {
+			const credRemain = this.__credRemainSec(msg.turnCreds);
+			const credRemainStr = credRemain ?? 'none';
+			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId} credRemain=${credRemainStr}`);
+			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
+			this.__onSend({
+				type: 'rtc:restart-rejected',
+				toConnId: connId,
+				payload: { reason: 'no_session' },
+			});
+			return;
+		}
+
+		// per-connId mutex 串行化：同 connId 几乎同时到达多条 offer（典型场景：UI 多入口
+		// nudgeRestart 在数百毫秒内连发两条 ICE restart）时，把整段三连 await + sendSignaling
+		// 串成 N 轮，最后一条胜出（plugin PC 凭据 = 最后一条 offer 凭据 = UI 当前凭据）。
+		// 不串行化时三连 await 中间被并发 offer 重入会触发 pion InvalidModificationError。
+		// 包**整个** __handleOfferLocked：既覆盖 ICE restart 路径（复用现有 PC）也覆盖首次
+		// offer 路径（创建新 PC + 触发 closeByConnId 清场），后者若不在锁内会与紧随的 ICE
+		// restart 踩。
+		// mutex 生命期 = session 生命期：与 session 一一成对管理。删除点在两处（且仅两处）：
+		// 1) closeByConnId（覆盖所有正常 close 路径：rtc:closed / state-change / TTL / closeAll）
+		// 2) __handleOfferLocked 首次 offer 的 catch（catch 手工删 session 时同步删 mutex）
+		// 任何新增 session 删除点必须配套删除 mutex 键，否则会泄漏。
+		let mu = this.__offerMutexes.get(connId);
+		if (!mu) {
+			mu = createMutex();
+			this.__offerMutexes.set(connId, mu);
+		}
+		return mu.withLock(() => this.__handleOfferLocked(msg));
+	}
+
+	async __handleOfferLocked(msg) {
+		const connId = msg.fromConnId;
+		const isIceRestart = !!msg.payload?.iceRestart;
 		const credRemain = this.__credRemainSec(msg.turnCreds);
 		const credRemainStr = credRemain ?? 'none';
 
@@ -239,6 +294,14 @@ export class WebRtcPeer {
 				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
+					// 身份重核：close-during-lock 路径（rtc:closed / connectionState=closed|failed-TTL /
+					// closeAll）不走 offer mutex，可能在三连 await 中间删掉 session。命中即丢弃后续动作，
+					// 不发 stale rtc:answer。logger.info 仅本地诊断，不上 remoteLog（closeByConnId 触发方
+					// 自带 rtc.closed / rtc.state 等远程日志，server 端能从那侧还原"PC 哪一刻死了"）。
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setRemoteDescription`);
+						return;
+					}
 					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 sender 分片阈值；
 					// queue 存的是完整字符串（buildChunks 在 sender.send 内同步完成），
 					// 已开始分片的当前消息用旧 size，下一条消息用新 size
@@ -248,7 +311,15 @@ export class WebRtcPeer {
 						if (existing.rpcDcSender) existing.rpcDcSender.maxMessageSize = newMMS;
 					}
 					const answer = await existing.pc.createAnswer();
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after createAnswer`);
+						return;
+					}
 					await existing.pc.setLocalDescription(answer);
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setLocalDescription`);
+						return;
+					}
 					this.__onSend({
 						type: 'rtc:answer',
 						toConnId: connId,
@@ -258,6 +329,13 @@ export class WebRtcPeer {
 					this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
 					return;
 				} catch (err) {
+					// 身份重核：session 已被中途关掉时 catch 收到的 err 是"PC 已 close"残响，
+					// 不应再发 stale restart-rejected（用户会看到误报失败），也不重复调 closeByConnId
+					// （session 已删，再调是 no-op 但徒增 rtc.closed 日志噪声）。
+					if (this.__sessions.get(connId) !== existing) {
+						this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart error after session change (suppressed): ${err?.message}`);
+						return;
+					}
 					// ICE restart 协商失败 → reject，不 fall through
 					this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
 					this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
@@ -546,7 +624,7 @@ export class WebRtcPeer {
 			this.__remoteLog(`rtc.answer conn=${connId}`);
 			this.logger.info?.(`${this.__rtcTag} answer sent to ${connId}`);
 		} catch (err) {
-			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
+			// SDP 协商失败 → 清理已入 Map 的 session + mutex，避免泄漏
 			const cur = this.__sessions.get(connId);
 			if (cur && cur.pc === pc) {
 				if (cur.__failedTimer) {
@@ -555,6 +633,10 @@ export class WebRtcPeer {
 				}
 				this.__sessions.delete(connId);
 			}
+			// 同步清 mutex 键，保持 mutex 与 session 生命期一致。本 fn 即将 throw 退出，
+			// fn 仍持有的 mutex 实例引用会自然 GC；删 map 键防后续 offer 误用残留键
+			// （split race 边界仍在 TODO 中追踪，不在此修法范围）。
+			this.__offerMutexes.delete(connId);
 			await pc.close().catch(() => {});
 			throw err;
 		}