@steve02081504/fount-p2p 0.0.19 → 0.0.21

package/README.md

@@ -107,8 +107,9 @@ Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harnes
 
 ## Optional dependencies
 
-- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is subprocess-only; see [docs/runtime.md](./docs/runtime.md).
-- `node-datachannel` — WebRTC DataChannels (dependency).
+- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is in-process; see [docs/runtime.md](./docs/runtime.md).
+- `node-datachannel` — native WebRTC DataChannels (optionalDependencies). Preferred when the addon loads.
+- `node-rtc-connection` — pure-JS WebRTC DataChannel fallback (dependency; used on Termux/Android or when native is missing).
 - `ws` — Nostr discovery / signaling / last-resort link WebSockets (dependency).
 
 Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.

package/core/entity_id.mjs

@@ -11,7 +11,7 @@ import {
 import { isHex64, normalizeHex64 } from './hexIds.mjs'
 
 /**
- *
+ * entityHash 编解码与校验（re-export）。
  */
 export {
 	encodeEntityHash,

package/dag/index.mjs

@@ -252,10 +252,10 @@ export function eventsToMetas(events) {
 }
 
 /**
- *
+ * DAG 行内容/签名 canonicalize（re-export）。
  */
 export { canonicalizeRowContent, canonicalizeSignedRow } from './canonicalize_row.mjs'
 /**
- *
+ * 剥离 DAG 事件本地扩展字段（re-export）。
  */
 export { stripDagEventLocalExtensions } from './strip_extensions.mjs'

package/dag/storage.mjs

@@ -6,9 +6,12 @@ import { createInterface } from 'node:readline'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 
-import { atomicTemporaryPath, finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 import { withAsyncMutex } from '../utils/async_mutex.mjs'
+import { atomicTemporaryPath, finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 
+/**
+ * 原子重命名 finalize（re-export）。
+ */
 export { finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 
 /** 流式重写 JSONL 时分块写入的行数上限 */

package/federation/chunk_fetch_pending.mjs

@@ -20,7 +20,7 @@ export function registerChunkFetchWait(key, expectedHash, timeoutMs, options = {
 		return {
 			done: Promise.resolve(null),
 			/**
-			 *
+			 * 槽位已满时的空操作取消。
 			 */
 			cancel: () => { },
 		}

package/federation/entity_key_chain.mjs

@@ -8,7 +8,7 @@ import { hashFromPubKeyHex } from '../core/entity_id.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 
 /**
- *
+ * entity 密钥撤销签名的域分隔前缀。
  */
 export const ENTITY_KEY_REVOKE_DOMAIN = 'fount-entity-key-revoke'
 

package/federation/manifest_fetch_pending.mjs

@@ -26,7 +26,7 @@ export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
 		return {
 			done: Promise.resolve(null),
 			/**
-			 *
+			 * 槽位已满时的空操作取消。
 			 */
 			cancel: () => { },
 		}
@@ -57,7 +57,7 @@ export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
 	return {
 		done,
 		/**
-		 *
+		 * 取消等待并以 null 结算。
 		 */
 		cancel: () => {
 			clearTimeout(timer)

package/files/assemble_stream.mjs

@@ -76,7 +76,7 @@ function readStreamChunk(stream) {
 	if (stream.readableEnded) return Promise.resolve(null)
 	return new Promise((resolve, reject) => {
 		/**
-		 *
+		 * readable 时读取下一块密文。
 		 */
 		const onReadable = () => {
 			cleanup()
@@ -84,7 +84,7 @@ function readStreamChunk(stream) {
 			resolve(next ? Buffer.from(next) : Buffer.alloc(0))
 		}
 		/**
-		 *
+		 * 流结束时 resolve null。
 		 */
 		const onEnd = () => {
 			cleanup()
@@ -98,7 +98,7 @@ function readStreamChunk(stream) {
 			reject(error)
 		}
 		/**
-		 *
+		 * 注销流事件监听。
 		 */
 		const cleanup = () => {
 			stream.off('readable', onReadable)
@@ -130,7 +130,7 @@ export function createManifestPlaintextStream(manifest, partStreams, contentKey)
 
 	return new Readable({
 		/**
-		 *
+		 * 按 manifest part 顺序解密密文块并推送明文。
 		 */
 		async read() {
 			if (finished) return

package/files/chunk_fetch.mjs

@@ -3,15 +3,24 @@ import { randomUUID } from 'node:crypto'
 import { bytesToBase64 } from '../core/bytes_codec.mjs'
 import {
 	MAX_PENDING_CHUNK_FETCHES,
-	pendingChunkFetches,
 	registerChunkFetchWait,
 } from '../federation/chunk_fetch_pending.mjs'
+import { ms } from '../utils/duration.mjs'
+import { createInflightTable } from '../utils/inflight_table.mjs'
 
 import { verifiedChunkBytes } from './chunk_fetch_verify.mjs'
 import { fetchFederationChunk, resolveNodeHash } from './chunk_provider_registry.mjs'
 import { getChunk, hasChunk, putChunk } from './chunk_store.mjs'
 import { fanoutFedFetch } from './fetch_fanout.mjs'
 
+const DEFAULT_CHUNK_FETCH_TIMEOUT_MS = ms('8s')
+
+/** 同 username+hash 共享一次 fanout；队满只丢已超基础超时的队首。 */
+const chunkInflight = createInflightTable({
+	maxSize: MAX_PENDING_CHUNK_FETCHES,
+	baseTimeoutMs: DEFAULT_CHUNK_FETCH_TIMEOUT_MS,
+})
+
 /**
  * @typedef {{
  *   username: string,
@@ -42,19 +51,27 @@ export async function fetchChunk(context) {
 		}
 	}
 
-	if (pendingChunkFetches.size >= MAX_PENDING_CHUNK_FETCHES) return null
+	const inflightKey = `${username}\0${hash}`
+	const shared = chunkInflight.acquire(inflightKey, () => {
+		const requestId = randomUUID()
+		const wait = registerChunkFetchWait(requestId, hash, DEFAULT_CHUNK_FETCH_TIMEOUT_MS)
+		void (async () => {
+			try {
+				const { nodeHash } = await resolveNodeHash(username)
+				await fanoutFedFetch(username, 'fed_chunk_get', {
+					requestId,
+					nodeHash,
+					chunkHash: hash,
+					ownerEntityHash: context.ownerEntityHash,
+				})
+			}
+			catch { /* pending wait 超时/cancel 负责 settle */ }
+		})()
+		return { done: wait.done, cancel: wait.cancel }
+	})
+	if (!shared) return null
 
-	const requestId = randomUUID()
-	const { done } = registerChunkFetchWait(requestId, hash, 8000)
-	const { nodeHash } = await resolveNodeHash(username)
-	const payload = {
-		requestId,
-		nodeHash,
-		chunkHash: hash,
-		ownerEntityHash: context.ownerEntityHash,
-	}
-	await fanoutFedFetch(username, 'fed_chunk_get', payload)
-	const result = await done
+	const result = await shared
 	const verified = verifiedChunkBytes(hash, result)
 	if (verified) {
 		await putChunk(hash, verified)

package/files/chunk_responder.mjs

@@ -99,7 +99,7 @@ export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardG
 			if (!String(data.requestId || '')) return
 			await handleFedChunkGetIngress(username, data, peerId, (resp, pid) => {
 				/**
-				 *
+				 * 发送 fed_chunk_data 响应（可经 fedOut 限速队列）。
 				 */
 				const send = () => {
 					try { sendChunkData(resp, pid) }
@@ -123,7 +123,7 @@ export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardG
 			if (!String(data.requestId || '')) return
 			await handleFedManifestGetIngress(username, data, peerId, (resp, pid) => {
 				/**
-				 *
+				 * 发送 fed_manifest_data 响应（可经 fedOut 限速队列）。
 				 */
 				const send = () => {
 					try { sendManifestData(resp, pid) }

package/files/manifest_fetch.mjs

@@ -3,11 +3,12 @@ import { randomUUID } from 'node:crypto'
 import {
 	manifestFetchExpectedKey,
 	MAX_PENDING_MANIFEST_FETCHES,
-	pendingManifestFetches,
 	registerManifestFetchWait,
 } from '../federation/manifest_fetch_pending.mjs'
 import { isWritableLocalEntity } from '../node/identity.mjs'
 import { getEntityStore } from '../node/instance.mjs'
+import { ms } from '../utils/duration.mjs'
+import { createInflightTable } from '../utils/inflight_table.mjs'
 
 import { resolveNodeHash } from './chunk_provider_registry.mjs'
 import { loadFileManifest, saveFileManifest } from './evfs.mjs'
@@ -15,11 +16,18 @@ import { fanoutFedFetch } from './fetch_fanout.mjs'
 import { normalizeFileManifest } from './manifest.mjs'
 import { shouldPreferIncomingPublicManifest } from './public_manifest.mjs'
 
-const DEFAULT_MANIFEST_FETCH_TIMEOUT_MS = 8000
+const DEFAULT_MANIFEST_FETCH_TIMEOUT_MS = ms('8s')
+
+/** 同 username+owner+path 共享一次 fanout；队满只丢已超基础超时的队首。 */
+const manifestInflight = createInflightTable({
+	maxSize: MAX_PENDING_MANIFEST_FETCHES,
+	baseTimeoutMs: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS,
+})
 
 /**
  * 拉取公开 manifest；默认不写盘。`cache: true` 或 `cachePublicManifest` 才缓存。
  * 本地已有 publicSig 时仍会 fanout 再校验，按 publishedAt 择新；超时则回退本地。
+ * 同 key in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
  * @param {{ username: string, ownerEntityHash: string, logicalPath: string, cache?: boolean, timeoutMs?: number }} context - 拉取上下文
  * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
  */
@@ -29,30 +37,37 @@ export async function fetchPublicManifest(context) {
 	const { username } = context
 	if (!ownerEntityHash || !logicalPath || !username) return null
 
-	const local = await loadFileManifest(ownerEntityHash, logicalPath)
-	const hasLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
-
-	if (pendingManifestFetches.size >= MAX_PENDING_MANIFEST_FETCHES)
-		return hasLocalPublic ? local : null
-
 	const timeoutMs = Number(context.timeoutMs) > 0
 		? Number(context.timeoutMs)
 		: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS
-	const requestId = randomUUID()
-	const { done } = registerManifestFetchWait(
-		requestId,
-		manifestFetchExpectedKey(ownerEntityHash, logicalPath),
-		timeoutMs,
-	)
-	const { nodeHash } = await resolveNodeHash(username)
-	const payload = {
-		requestId,
-		nodeHash,
-		ownerEntityHash,
-		logicalPath,
-	}
-	await fanoutFedFetch(username, 'fed_manifest_get', payload)
-	const result = await done
+	const expectedKey = manifestFetchExpectedKey(ownerEntityHash, logicalPath)
+	const inflightKey = `${username}\0${expectedKey}`
+
+	// 先挂 in-flight（同步），再读本地 — 避免并发调用在 await 间隙各自 start
+	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
+	const shared = manifestInflight.acquire(inflightKey, () => {
+		const requestId = randomUUID()
+		const wait = registerManifestFetchWait(requestId, expectedKey, timeoutMs)
+		void (async () => {
+			try {
+				const { nodeHash } = await resolveNodeHash(username)
+				await fanoutFedFetch(username, 'fed_manifest_get', {
+					requestId,
+					nodeHash,
+					ownerEntityHash,
+					logicalPath,
+				})
+			}
+			catch { /* pending wait 超时/cancel 负责 settle */ }
+		})()
+		return { done: wait.done, cancel: wait.cancel }
+	})
+
+	const local = await localPromise
+	const hasLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
+	if (!shared) return hasLocalPublic ? local : null
+
+	const result = await shared
 
 	if (result && (!hasLocalPublic || shouldPreferIncomingPublicManifest(local, result))) {
 		if (context.cache === true)

package/link/channel_mux.mjs

@@ -75,35 +75,23 @@ export function pickChannel(action, byteLength) {
 }
 
 /**
- * 读取 RTC 数据通道当前 bufferedAmount，失败时返回 0。
+ * 读取 RTC 数据通道当前 bufferedAmount。
  * @param {RTCDataChannel} channel RTC 数据通道
  * @returns {number} 缓冲区待发送字节数
  */
 export function readBufferedAmount(channel) {
-	try {
-		return Number.isFinite(channel?.bufferedAmount) ? Number(channel.bufferedAmount) : 0
-	}
-	catch {
-		return 0
-	}
+	return channel.bufferedAmount
 }
 
 /**
  * 配置数据通道的 bufferedAmountLowThreshold。
  * @param {RTCDataChannel} channel RTC 数据通道
  * @param {number} [thresholdBytes=CHANNEL_LOW_THRESHOLD_BYTES] 低水位阈值（字节）
- * @returns {number | null} 实际生效的阈值，不支持时返回 null
+ * @returns {number} 实际生效的阈值
  */
 export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CHANNEL_LOW_THRESHOLD_BYTES) {
-	try {
-		channel.bufferedAmountLowThreshold = thresholdBytes
-		return Number.isFinite(channel.bufferedAmountLowThreshold)
-			? Number(channel.bufferedAmountLowThreshold)
-			: null
-	}
-	catch {
-		return null
-	}
+	channel.bufferedAmountLowThreshold = thresholdBytes
+	return channel.bufferedAmountLowThreshold
 }
 
 /**
@@ -113,18 +101,9 @@ export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CH
  * @returns {() => void} 取消订阅函数
  */
 export function onBufferedAmountLow(channel, callback) {
-	/**
-	 * bufferedamountlow 事件处理函数。
-	 * @returns {void}
-	 */
-	const handler = () => callback()
-	channel.addEventListener?.('bufferedamountlow', handler)
-	channel.onbufferedamountlow = handler
-	if (channel.bufferedAmountLow?.subscribe)
-		channel.bufferedAmountLow.subscribe(handler)
+	channel.onbufferedamountlow = callback
 	return () => {
-		channel.removeEventListener?.('bufferedamountlow', handler)
-		if (channel.onbufferedamountlow === handler) channel.onbufferedamountlow = null
+		if (channel.onbufferedamountlow === callback) channel.onbufferedamountlow = null
 	}
 }
 
@@ -163,12 +142,12 @@ export function createChannelSendQueues(options) {
 		const channel = getChannel(channelName)
 		if (channel?.readyState !== 'open') return
 		const queue = queues[channelName]
-		let i = 0
-		while (i < queue.length) {
+		let sent = 0
+		while (sent < queue.length) {
 			if (readBufferedAmount(channel) > highWatermarkBytes) break
-			channel.send(queue[i++].bytes)
+			channel.send(queue[sent++].bytes)
 		}
-		if (i > 0) queue.splice(0, i)
+		if (sent > 0) queue.splice(0, sent)
 	}
 
 	return {

package/link/providers/webrtc.mjs

@@ -1,3 +1,4 @@
+import { toBytes } from '../../core/bytes_codec.mjs'
 import { getSignalingRuntimeConfig } from '../../node/instance.mjs'
 import { nodeDebug } from '../../node/log.mjs'
 import { ms } from '../../utils/duration.mjs'
@@ -11,20 +12,12 @@ import {
 	onBufferedAmountLow,
 } from '../channel_mux.mjs'
 import { asLinkHandle, createLinkPipe } from '../pipe.mjs'
-import {
-	attachChannelMessageListener,
-	attachDataChannelListener,
-	attachIceCandidateListener,
-	loadNodeRtcPolyfill,
-	dataToBytes,
-	waitForChannelState,
-} from '../rtc.mjs'
+import { loadNodeRtcPolyfill, waitForChannelState } from '../rtc/index.mjs'
 import { extractDtlsFingerprint } from '../sdp_fingerprint.mjs'
 
 import { LINK_LEVEL_WEBRTC } from './levels.mjs'
 
 /**
- * 将错误对象格式化为短字符串。
  * @param {unknown} error 原始错误
  * @returns {string} 短 reason
  */
@@ -35,27 +28,21 @@ function formatErrorReason(error) {
 let cachedAvailable = null
 
 /**
- * @returns {boolean} 是否跑在 Deno
- */
-function isDenoRuntime() {
-	return typeof globalThis.Deno !== 'undefined'
-}
-
-/**
- * 探测 WebRTC（node-datachannel）是否可用。
+ * 探测 WebRTC（node-datachannel 或纯 JS fallback）是否可用。
  * @returns {Promise<boolean>} 可用为 true
  */
 export async function canUseWebRtcLink() {
 	if (cachedAvailable !== null) return cachedAvailable
 	try {
-		await loadNodeRtcPolyfill()
+		const rtc = await loadNodeRtcPolyfill()
 		cachedAvailable = true
+		nodeDebug('p2p:webrtc backend', { backend: rtc.backend })
 	}
 	catch (error) {
 		cachedAvailable = false
 		const reason = formatErrorReason(error)
 		nodeDebug('p2p:webrtc unavailable', {
-			err: isDenoRuntime()
+			err: typeof globalThis.Deno !== 'undefined'
 				? `${reason} | deno: see docs/runtime.md (node-datachannel scripts only)`
 				: reason,
 		})
@@ -73,15 +60,16 @@ export async function canUseWebRtcLink() {
  * @param {number} [options.heartbeatMs] 心跳间隔
  * @param {number} [options.idleTimeoutMs] 无入站流量超时
  * @param {number} [options.handshakeTimeoutMs] 握手超时
- * @param {{ RTCPeerConnection: typeof RTCPeerConnection } | null} [options.rtc] RTC 构造器
+ * @param {import('../rtc/polyfill.mjs').LoadedRtcPolyfill} [options.rtc] RTC 构造器
  * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array, nonce?: string } | null} [options.localIdentity] 本地握手身份
  * @returns {Promise<import('./index.mjs').LinkHandle>} link 句柄
  */
 export async function createWebRtcLink(options) {
 	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
-	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
 	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
+	// 纯 JS 后端只做 trickle（SDP 不含 candidate）；强制开启 trickle。
+	const trickleIceOff = !rtc.forcesTrickleIce && getSignalingRuntimeConfig().trickleIceOff === true
 	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
@@ -187,14 +175,6 @@ export async function createWebRtcLink(options) {
 		await flushQueuedIceCandidates()
 	}
 
-	/**
-	 * @param {unknown} error addIceCandidate 错误
-	 * @returns {boolean} 是否应暂存后重试
-	 */
-	function shouldRetryQueuedIce(error) {
-		return /without ice transport/i.test(String(error?.message ?? error ?? ''))
-	}
-
 	/**
 	 * @returns {Promise<void>}
 	 */
@@ -216,7 +196,7 @@ export async function createWebRtcLink(options) {
 				await peerConnection.addIceCandidate(candidate)
 			}
 			catch (error) {
-				if (shouldRetryQueuedIce(error)) {
+				if (/without ice transport/i.test(String(error?.message ?? error))) {
 					remoteSignalQueue.unshift(candidate)
 					return
 				}
@@ -261,7 +241,7 @@ export async function createWebRtcLink(options) {
 				await peerConnection.addIceCandidate(message.candidate)
 			}
 			catch (error) {
-				if (shouldRetryQueuedIce(error)) {
+				if (/without ice transport/i.test(String(error?.message ?? error))) {
 					remoteSignalQueue.push(message.candidate)
 					return
 				}
@@ -272,19 +252,23 @@ export async function createWebRtcLink(options) {
 
 	/**
 	 * @param {RTCDataChannel} channel RTC 数据通道
-	 * @returns {Promise<void>}
+	 * @returns {void}
 	 */
-	async function attachChannel(channel) {
+	function attachChannel(channel) {
 		if (channel.label === CHANNEL_CONTROL) controlChannel = channel
 		else if (channel.label === CHANNEL_BULK) bulkChannel = channel
 		else return
-		attachChannelMessageListener(channel, data => {
+		/**
+		 * @param {MessageEvent} event 入站消息事件
+		 * @returns {void}
+		 */
+		channel.onmessage = event => {
 			try {
-				if (typeof data === 'string') pipe.handleInbound(data)
-				else pipe.handleInbound(dataToBytes(data))
+				const data = event.data
+				pipe.handleInbound(typeof data === 'string' ? data : toBytes(data, { allowString: true }))
 			}
 			catch { /* drop */ }
-		})
+		}
 		attachBackpressurePump(channel)
 	}
 
@@ -312,20 +296,29 @@ export async function createWebRtcLink(options) {
 		void handleRemoteSignal(message).catch(error => pipe.close(`signal-error:${formatErrorReason(error)}`))
 	}) ?? null
 
-	attachIceCandidateListener(peerConnection, event => {
+	/**
+	 * @param {RTCPeerConnectionIceEvent} event ICE candidate 事件
+	 * @returns {void}
+	 */
+	peerConnection.onicecandidate = event => {
 		if (trickleIceOff || !event.candidate) return
 		void sendSignal({
 			type: 'ice',
 			candidate: typeof event.candidate.toJSON === 'function' ? event.candidate.toJSON() : event.candidate,
 		}).catch(error => pipe.close(`signal-send-failed:${formatErrorReason(error)}`))
-	})
-	attachDataChannelListener(peerConnection, event => {
-		void attachChannel(event.channel)
-			.then(() => maybeStartPostOpenFlow())
-			.catch(error => pipe.close(`channel-attach-failed:${error?.message ?? error}`))
-	})
+	}
+	/**
+	 * @param {RTCDataChannelEvent} event 远端 data channel 事件
+	 * @returns {void}
+	 */
+	peerConnection.ondatachannel = event => {
+		attachChannel(event.channel)
+		void maybeStartPostOpenFlow().catch(error => pipe.close(`channel-attach-failed:${formatErrorReason(error)}`))
+	}
 
-	/** 连接失败/关闭时关掉 pipe。 */
+	/**
+	 * 连接失败/断开时递增重连计数并关闭 pipe。
+	 */
 	peerConnection.onconnectionstatechange = () => {
 		if (['failed', 'closed', 'disconnected'].includes(peerConnection.connectionState)) {
 			reconnectCount++
@@ -334,8 +327,8 @@ export async function createWebRtcLink(options) {
 	}
 
 	if (options.initiator) {
-		await attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
-		await attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
+		attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
+		attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
 		const offer = await peerConnection.createOffer()
 		await peerConnection.setLocalDescription(offer)
 		await waitForIceGatheringComplete()
@@ -345,7 +338,7 @@ export async function createWebRtcLink(options) {
 		})
 	}
 
-	void maybeStartPostOpenFlow().catch(error => pipe.close(`open-flow-failed:${error?.message ?? error}`))
+	void maybeStartPostOpenFlow().catch(error => pipe.close(`open-flow-failed:${formatErrorReason(error)}`))
 
 	return asLinkHandle(pipe, {
 		/**
@@ -353,7 +346,7 @@ export async function createWebRtcLink(options) {
 		 * @param {'control' | 'bulk'} name 通道名
 		 * @returns {RTCDataChannel | null} 测试用通道
 		 */
-		_channelForTest(name) {
+		channelForTest(name) {
 			return name === CHANNEL_CONTROL ? controlChannel : bulkChannel
 		},
 	})

package/link/rtc/channel.mjs

@@ -0,0 +1,41 @@
+/**
+ * 等待 data channel 进入 open 或 close 状态，超时则 reject。
+ * 同一 channel 可并发等待：新订阅链式调用已有 onopen/onclose，cleanup 只摘掉自身。
+ * @param {RTCDataChannel} channel RTC 数据通道
+ * @param {'open' | 'close'} eventName 目标状态事件名
+ * @param {number} timeoutMs 超时毫秒数
+ * @returns {Promise<void>}
+ */
+export function waitForChannelState(channel, eventName, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		if (eventName === 'open' && channel.readyState === 'open') return resolve()
+		if (eventName === 'close' && channel.readyState === 'closed') return resolve()
+		const eventHandlerProperty = eventName === 'open' ? 'onopen' : 'onclose'
+		const previousHandler = channel[eventHandlerProperty]
+		let active = true
+		const timer = setTimeout(() => {
+			cleanup()
+			reject(new Error(`p2p: data channel ${eventName} timeout after ${timeoutMs}ms`))
+		}, timeoutMs)
+		/**
+		 * 清除超时并恢复 data channel 事件 handler。
+		 */
+		const cleanup = () => {
+			if (!active) return
+			active = false
+			clearTimeout(timer)
+			if (channel[eventHandlerProperty] === chained) channel[eventHandlerProperty] = previousHandler
+		}
+		/**
+		 * @param {...any} eventArguments 原 handler 参数
+		 * @returns {void}
+		 */
+		const chained = (...eventArguments) => {
+			previousHandler?.(...eventArguments)
+			if (!active) return
+			cleanup()
+			resolve()
+		}
+		channel[eventHandlerProperty] = chained
+	})
+}