@steve02081504/fount-p2p 0.0.19 → 0.0.21

package/link/rtc/ice_local_hostname.mjs

@@ -0,0 +1,139 @@
+/**
+ * 服务端 WebRTC polyfill 在 Windows 等环境常产出 `.local` host candidate，
+ * 远端无法解析。按 iceLocalHostnamePolicy 改写为 loopback 或丢弃。
+ */
+
+/** @typedef {'none' | 'rewrite-loopback' | 'drop'} IceLocalHostnamePolicy */
+
+/**
+ * @param {string | null | undefined} candidateSdp ICE candidate SDP 行
+ * @param {IceLocalHostnamePolicy} policy 处理策略
+ * @returns {string | null} 处理后的 SDP；drop 策略下不可用时返回 null
+ */
+export function applyIceLocalHostnamePolicy(candidateSdp, policy) {
+	const sdp = String(candidateSdp || '').trim()
+	if (!sdp || !/\.local/i.test(sdp)) return sdp || null
+	if (!/\btyp host\b/i.test(sdp)) return sdp
+	if (policy === 'drop') return null
+	if (policy === 'rewrite-loopback') {
+		const rewritten = sdp.replace(/(\s)[\w-]+\.local(\s|$)/gi, '$1127.0.0.1$2')
+		return rewritten === sdp ? null : rewritten
+	}
+	return sdp
+}
+
+/**
+ * @param {RTCIceCandidate | { candidate?: string } | null | undefined} candidate ICE candidate
+ * @param {typeof RTCIceCandidate} RTCIceCandidateCtor 构造函数
+ * @param {IceLocalHostnamePolicy} policy 处理策略
+ * @returns {RTCIceCandidate | { candidate?: string } | null | undefined} 过滤/改写后的 candidate
+ */
+export function filterIceLocalHostnameCandidate(candidate, RTCIceCandidateCtor, policy) {
+	if (!candidate || policy === 'none') return candidate
+	const raw = candidate.candidate ?? candidate.toJSON?.()?.candidate ?? ''
+	const rewritten = applyIceLocalHostnamePolicy(raw, policy)
+	if (!rewritten) return null
+	if (rewritten === raw) return candidate
+	const init = typeof candidate.toJSON === 'function'
+		? { ...candidate.toJSON(), candidate: rewritten }
+		: { candidate: rewritten, sdpMid: candidate.sdpMid, sdpMLineIndex: candidate.sdpMLineIndex }
+	return new RTCIceCandidateCtor(init)
+}
+
+/**
+ * @param {typeof RTCPeerConnection} BaseRTC 原始 polyfill 类
+ * @param {typeof RTCIceCandidate} RTCIceCandidate ICE candidate 构造函数
+ * @param {IceLocalHostnamePolicy} [policy='drop'] 策略
+ * @returns {typeof RTCPeerConnection} 包装后的 RTCPeerConnection 类（none 时原样返回）
+ */
+export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidate, policy = 'drop') {
+	if (policy === 'none') return BaseRTC
+
+	const baseRoutesIce = typeof BaseRTC.prototype.prepareIceCandidateEvent === 'function'
+
+	return class IceLocalHostnameFilteredRTCPeerConnection extends BaseRTC {
+		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
+		#userIceHandler = null
+		/** @type {Set<(event: unknown) => void>} */
+		#iceListeners = new Set()
+		/** 去重：同一次 native 派发可能既走 attribute 又走 listener */
+		#lastIceEvent = null
+
+		/**
+		 * drop：不派发；rewrite：仅派发替换 candidate 后的事件。
+		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
+		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件；drop 时为 null
+		 */
+		prepareIceCandidateEvent(event) {
+			if (!event?.candidate) return event
+			const filtered = filterIceLocalHostnameCandidate(event.candidate, RTCIceCandidate, policy)
+			if (!filtered) return null
+			return filtered === event.candidate ? event : { candidate: filtered }
+		}
+
+		/**
+		 * @param {RTCConfiguration} [config] RTC 配置
+		 */
+		constructor(config) {
+			super(config)
+			if (baseRoutesIce) return
+
+			// native EventTarget：在派发前规范化，自管 listener，不依赖 stopImmediatePropagation。
+			Object.defineProperty(this, 'onicecandidate', {
+				configurable: true,
+				enumerable: true,
+				/**
+				 * @returns {((event: RTCPeerConnectionIceEvent) => void) | null} 用户 ICE handler
+				 */
+				get: () => this.#userIceHandler,
+				/**
+				 * @param {((event: RTCPeerConnectionIceEvent) => void) | null} handler 用户 ICE handler
+				 * @returns {void}
+				 */
+				set: handler => { this.#userIceHandler = handler },
+			})
+			super.addEventListener('icecandidate', event => this.#deliverIce(event))
+		}
+
+		/**
+		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
+		 * @returns {void}
+		 */
+		#deliverIce = event => {
+			if (this.#lastIceEvent === event) return
+			this.#lastIceEvent = event
+			const normalized = this.prepareIceCandidateEvent(event)
+			if (normalized == null) return
+			this.#userIceHandler?.(normalized)
+			for (const listener of this.#iceListeners) listener(normalized)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @param {boolean | AddEventListenerOptions} [options] 监听选项
+		 * @returns {void}
+		 */
+		addEventListener(type, listener, options) {
+			if (!baseRoutesIce && type === 'icecandidate') {
+				this.#iceListeners.add(listener)
+				return
+			}
+			return super.addEventListener(type, listener, options)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @param {boolean | EventListenerOptions} [options] 监听选项
+		 * @returns {void}
+		 */
+		removeEventListener(type, listener, options) {
+			if (!baseRoutesIce && type === 'icecandidate') {
+				this.#iceListeners.delete(listener)
+				return
+			}
+			return super.removeEventListener(type, listener, options)
+		}
+	}
+}

package/link/rtc/index.mjs

@@ -0,0 +1,16 @@
+/**
+ * 等待 data channel open/close（re-export）。
+ */
+export { waitForChannelState } from './channel.mjs'
+/**
+ * ICE candidate 本地主机名策略（re-export）。
+ */
+export {
+	applyIceLocalHostnamePolicy,
+	filterIceLocalHostnameCandidate,
+	wrapRtcPeerConnectionForIceLocalHostname,
+} from './ice_local_hostname.mjs'
+/**
+ * Node WebRTC polyfill 加载（re-export）。
+ */
+export { clearNodeRtcPolyfillCache, loadNodeRtcPolyfill } from './polyfill.mjs'

package/link/rtc/polyfill.mjs

@@ -0,0 +1,159 @@
+import process from 'node:process'
+
+import { getRtcPolyfillCacheEpoch, getSignalingRuntimeConfig } from '../../node/instance.mjs'
+import { nodeDebug } from '../../node/log.mjs'
+
+import { wrapRtcPeerConnectionForIceLocalHostname } from './ice_local_hostname.mjs'
+import { bridgePeerConnection } from './w3c_bridge.mjs'
+
+/** @type {boolean} */
+let exitCleanupHooked = false
+
+/** @type {Promise<LoadedRtcPolyfill> | null} */
+let cachedDefaultPolyfill = null
+
+/** @type {number} 与 cachedDefaultPolyfill 绑定的策略世代 */
+let cachedDefaultPolyfillEpoch = -1
+
+/**
+ * @typedef {{
+ *   RTCPeerConnection: typeof RTCPeerConnection,
+ *   RTCIceCandidate: typeof RTCIceCandidate,
+ *   backend: string,
+ *   forcesTrickleIce: boolean,
+ * }} LoadedRtcPolyfill
+ * @typedef {{
+ *   id: string,
+ *   forcesTrickleIce?: boolean,
+ *   load: () => Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>,
+ * }} RtcBackend
+ */
+
+/**
+ * 清除默认后端加载缓存（iceLocalHostnamePolicy 变更后调用）。
+ * @returns {void}
+ */
+export function clearNodeRtcPolyfillCache() {
+	cachedDefaultPolyfill = null
+	cachedDefaultPolyfillEpoch = -1
+}
+
+/**
+ * 注册进程退出时销毁 libdatachannel 原生资源（首次成功加载后挂一次）。
+ * libdatachannel 的原生线程在 pc.close() 后仍需时间回收；进程退出时若原生资源未同步销毁，
+ * Windows 上会触发堆损坏（退出码 0xC0000374）。
+ * @returns {Promise<void>}
+ */
+async function ensureNodeDatachannelExitCleanup() {
+	if (exitCleanupHooked) return
+	exitCleanupHooked = true
+	const { cleanup = undefined } = await import('node-datachannel').catch(() => ({}))
+	process.on('exit', () => {
+		try { cleanup?.() } catch { /* already torn down */ }
+	})
+}
+
+/**
+ * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-datachannel 构造器
+ */
+async function loadNodeDatachannelBackend() {
+	const mod = await import('node-datachannel/polyfill')
+	await ensureNodeDatachannelExitCleanup()
+	return {
+		RTCPeerConnection: mod.RTCPeerConnection,
+		RTCIceCandidate: mod.RTCIceCandidate,
+	}
+}
+
+/**
+ * 纯 JS WebRTC DataChannel（Termux / 无 native prebuild 时的 fallback）。
+ * @returns {Promise<{ RTCPeerConnection: typeof RTCPeerConnection, RTCIceCandidate: typeof RTCIceCandidate }>} node-rtc-connection 构造器
+ */
+async function loadNodeRtcConnectionBackend() {
+	const module = await import('node-rtc-connection')
+	return {
+		RTCPeerConnection: /** @type {typeof RTCPeerConnection} */ bridgePeerConnection(module.RTCPeerConnection),
+		RTCIceCandidate: module.RTCIceCandidate,
+	}
+}
+
+/** @type {RtcBackend} */
+const PURE_JS_BACKEND = {
+	id: 'node-rtc-connection',
+	forcesTrickleIce: true,
+	load: loadNodeRtcConnectionBackend,
+}
+
+/**
+ * @returns {RtcBackend[]} 默认后端顺序：优先 native，失败再纯 JS
+ */
+function defaultRtcBackends() {
+	/** @type {RtcBackend[]} */
+	const backends = []
+	// Android/Termux：无官方 prebuild，且 Bionic 不能跑 linux-arm64 glibc 包；直接走纯 JS。
+	if (process.platform !== 'android')
+		backends.push({ id: 'node-datachannel', load: loadNodeDatachannelBackend })
+	backends.push(PURE_JS_BACKEND)
+	return backends
+}
+
+/**
+ * @param {{ backends?: RtcBackend[] }} options 后端列表
+ * @returns {Promise<LoadedRtcPolyfill>} 首个可用后端的 polyfill
+ */
+async function loadNodeRtcPolyfillUncached(options) {
+	const backends = options.backends?.length
+		? [...options.backends, PURE_JS_BACKEND]
+		: defaultRtcBackends()
+	/** @type {unknown} */
+	let lastError = null
+	for (const backend of backends)
+		try {
+			const mod = await backend.load()
+			const { iceLocalHostnamePolicy } = getSignalingRuntimeConfig()
+			return {
+				RTCPeerConnection: wrapRtcPeerConnectionForIceLocalHostname(
+					mod.RTCPeerConnection,
+					mod.RTCIceCandidate,
+					iceLocalHostnamePolicy,
+				),
+				RTCIceCandidate: mod.RTCIceCandidate,
+				backend: backend.id,
+				forcesTrickleIce: backend.forcesTrickleIce === true,
+			}
+		}
+		catch (error) {
+			lastError = error
+			nodeDebug('p2p:webrtc backend unavailable', {
+				backend: backend.id,
+				err: String(error?.message ?? error).replace(/\s+/g, ' ').slice(0, 240),
+			})
+		}
+
+	throw lastError instanceof Error ? lastError : new Error(String(lastError ?? 'no rtc backend'))
+}
+
+/**
+ * 加载 RTC polyfill（node-datachannel 优先，失败则 node-rtc-connection），并按配置包装 RTCPeerConnection。
+ * 默认后端路径会缓存首次成功结果；注入 backends 时不走缓存。
+ * @param {{ backends?: RtcBackend[] }} [options] 可注入后端列表（测试用）
+ * @returns {Promise<LoadedRtcPolyfill>} RTC 构造器
+ */
+export async function loadNodeRtcPolyfill(options = {}) {
+	if (options.backends?.length)
+		return loadNodeRtcPolyfillUncached(options)
+	const epoch = getRtcPolyfillCacheEpoch()
+	if (!cachedDefaultPolyfill || cachedDefaultPolyfillEpoch !== epoch) {
+		cachedDefaultPolyfill = null
+		cachedDefaultPolyfillEpoch = epoch
+		const pending = loadNodeRtcPolyfillUncached(options).catch(error => {
+			if (cachedDefaultPolyfill === pending) {
+				cachedDefaultPolyfill = null
+				cachedDefaultPolyfillEpoch = -1
+			}
+			throw error
+		})
+		cachedDefaultPolyfill = pending
+	}
+	return cachedDefaultPolyfill
+}

package/link/rtc/w3c_bridge.mjs

@@ -0,0 +1,152 @@
+/**
+ * 把 EventEmitter 风格的 RTC（如 node-rtc-connection）桥成 W3C 属性 handler。
+ * 其余链路只认 onicecandidate / onmessage / onbufferedamountlow 等。
+ */
+
+/** @type {WeakSet<object>} */
+const bridgedChannels = new WeakSet()
+
+/**
+ * @param {object} target EventEmitter 目标
+ * @param {string} property W3C 属性名（如 onmessage）
+ * @param {string} eventName EventEmitter 事件名
+ * @param {(payload: unknown) => unknown} [adapt] 事件载荷适配
+ * @returns {void}
+ */
+function defineEmitterHandler(target, property, eventName, adapt = payload => payload) {
+	let handler = null
+	target.on(eventName, payload => handler?.(adapt(payload)))
+	Object.defineProperty(target, property, {
+		configurable: true,
+		enumerable: true,
+		/**
+		 * @returns {((payload: unknown) => void) | null} 当前 handler
+		 */
+		get: () => handler,
+		/**
+		 * @param {((payload: unknown) => void) | null} value 新 handler
+		 * @returns {void}
+		 */
+		set: value => { handler = value },
+	})
+}
+
+/**
+ * @param {RTCDataChannel} channel 原始 data channel
+ * @returns {RTCDataChannel} 已挂 W3C handler 的通道
+ */
+export function bridgeDataChannel(channel) {
+	if (bridgedChannels.has(channel) || typeof channel.on !== 'function') return channel
+	bridgedChannels.add(channel)
+	defineEmitterHandler(channel, 'onmessage', 'message')
+	defineEmitterHandler(channel, 'onopen', 'open')
+	defineEmitterHandler(channel, 'onclose', 'close')
+	defineEmitterHandler(channel, 'onbufferedamountlow', 'bufferedamountlow')
+	return channel
+}
+
+/**
+ * @param {typeof RTCPeerConnection} BaseRTC EventEmitter 风格 RTCPeerConnection
+ * @returns {typeof RTCPeerConnection} W3C handler 版
+ */
+export function bridgePeerConnection(BaseRTC) {
+	return class W3cRtcPeerConnection extends BaseRTC {
+		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
+		#iceHandler = null
+		/** @type {((event: { channel: RTCDataChannel }) => void) | null} */
+		#dataChannelHandler = null
+		/** @type {(() => void) | null} */
+		#connectionStateHandler = null
+		/** @type {Map<string, Set<(event: unknown) => void>>} */
+		#listeners = new Map()
+
+		/**
+		 * @param {RTCConfiguration} [config] RTC 配置
+		 */
+		constructor(config) {
+			super(config)
+			super.on('icecandidate', event => {
+				const normalized = this.prepareIceCandidateEvent(event)
+				if (normalized == null) return
+				this.#iceHandler?.(normalized)
+				this.#emit('icecandidate', normalized)
+			})
+			super.on('datachannel', event => {
+				const adapted = { channel: bridgeDataChannel(event.channel) }
+				this.#dataChannelHandler?.(adapted)
+				this.#emit('datachannel', adapted)
+			})
+			super.on('connectionstatechange', () => {
+				this.#connectionStateHandler?.()
+				this.#emit('connectionstatechange', undefined)
+			})
+		}
+
+		/**
+		 * ICE 事件规范化钩子；子类可覆盖（drop 返回 null，rewrite 返回替换后的事件）。
+		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
+		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件
+		 */
+		prepareIceCandidateEvent(event) {
+			return event
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {unknown} event 事件载荷（icecandidate 须已规范化）
+		 * @returns {void}
+		 */
+		#emit(type, event) {
+			const listeners = this.#listeners.get(type)
+			if (!listeners) return
+			for (const listener of listeners) listener(event)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @returns {void}
+		 */
+		addEventListener(type, listener) {
+			let listeners = this.#listeners.get(type)
+			if (!listeners) {
+				listeners = new Set()
+				this.#listeners.set(type, listeners)
+			}
+			listeners.add(listener)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @returns {void}
+		 */
+		removeEventListener(type, listener) {
+			this.#listeners.get(type)?.delete(listener)
+		}
+
+		/** @returns {((event: RTCPeerConnectionIceEvent) => void) | null} ICE candidate handler */
+		get onicecandidate() { return this.#iceHandler }
+		/** @param {((event: RTCPeerConnectionIceEvent) => void) | null} handler ICE candidate handler */
+		set onicecandidate(handler) { this.#iceHandler = handler }
+
+		/** @returns {((event: { channel: RTCDataChannel }) => void) | null} data channel handler */
+		get ondatachannel() { return this.#dataChannelHandler }
+		/** @param {((event: { channel: RTCDataChannel }) => void) | null} handler data channel handler */
+		set ondatachannel(handler) { this.#dataChannelHandler = handler }
+
+		/** @returns {(() => void) | null} connection state handler */
+		get onconnectionstatechange() { return this.#connectionStateHandler }
+		/** @param {(() => void) | null} handler connection state handler */
+		set onconnectionstatechange(handler) { this.#connectionStateHandler = handler }
+
+		/**
+		 * @param {string} label data channel 标签
+		 * @param {RTCDataChannelInit} [init] 创建选项
+		 * @returns {RTCDataChannel} 已桥接 W3C handler 的通道
+		 */
+		createDataChannel(label, init) {
+			return bridgeDataChannel(super.createDataChannel(label, init))
+		}
+	}
+}

package/mailbox/store.mjs

@@ -20,7 +20,7 @@ import {
 } from './prune.mjs'
 
 /**
- *
+ * mailbox 桶裁剪与计量辅助（re-export）。
  */
 export { MAX_BUCKET_BYTES, MAX_BUCKET_ENTRIES, mailboxBucketKey, mailboxRecordBytes }
 

package/node/instance.mjs

@@ -22,6 +22,16 @@ let runtime = null
 /** @type {Set<(event: string, payload?: unknown) => void>} */
 const changeListeners = new Set()
 
+/** RTC polyfill 缓存世代：策略变更时同步推进，避免动态 import 清缓存前仍命中旧构造器 */
+let rtcPolyfillCacheEpoch = 0
+
+/**
+ * @returns {number} 当前 RTC polyfill 缓存世代
+ */
+export function getRtcPolyfillCacheEpoch() {
+	return rtcPolyfillCacheEpoch
+}
+
 /**
  * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore }} options - 节点目录与可选 entity store
  * @returns {NodeRuntime} 初始化后的运行时
@@ -72,7 +82,10 @@ export function setNodeLogger(logger) {
  */
 export function setSignalingRuntimeConfig(config) {
 	if (!runtime) throw new Error('p2p: setSignalingRuntimeConfig requires initNode')
+	const previousPolicy = runtime.signaling.iceLocalHostnamePolicy
 	runtime.signaling = resolveSignalingRuntimeConfig({ ...runtime.signaling, ...config })
+	if (runtime.signaling.iceLocalHostnamePolicy !== previousPolicy)
+		rtcPolyfillCacheEpoch++
 	emitNodeChange('signaling-changed', runtime.signaling)
 }
 
@@ -131,4 +144,5 @@ export function onNodeChange(listener) {
 export function resetNodeForTests() {
 	runtime = null
 	changeListeners.clear()
+	rtcPolyfillCacheEpoch++
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.19",
+	"version": "0.0.21",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -71,7 +71,7 @@
 	},
 	"dependencies": {
 		"@noble/curves": "latest",
-		"node-datachannel": "latest",
+		"node-rtc-connection": "latest",
 		"on-shutdown": "latest",
 		"ws": "latest"
 	},
@@ -80,6 +80,10 @@
 	},
 	"optionalDependencies": {
 		"@stoprocent/bleno": "latest",
-		"@stoprocent/noble": "latest"
+		"@stoprocent/noble": "latest",
+		"node-datachannel": "latest"
+	},
+	"allowScripts": {
+		"node-datachannel": true
 	}
 }

package/permissions/index.mjs

@@ -1,12 +1,12 @@
 /**
- *
+ * 权限位掩码编解码（re-export）。
  */
 export { createPermissionCodec } from './bitmask.mjs'
 /**
- *
+ * 角色 deny/allow 覆盖合并（re-export）。
  */
 export { applyDenyAllowOverride, mergeRoleOverrides } from './layered.mjs'
 /**
- *
+ * 分层权限求值器（re-export）。
  */
 export { createLayeredEvaluator } from './evaluator.mjs'

package/transport/group_link_set.mjs

@@ -157,7 +157,7 @@ export function createGroupLinkSet(options) {
 	}
 
 	/**
-	 *
+	 * 开启成员自动拨号与 roster 维护。
 	 */
 	function startAutoconnect() {
 		autoconnectEnabled = true
@@ -165,7 +165,7 @@ export function createGroupLinkSet(options) {
 	}
 
 	/**
-	 *
+	 * 停止自动拨号并清除待执行的拨号定时器。
 	 */
 	function stopAutoconnect() {
 		autoconnectEnabled = false

package/transport/link_registry.mjs

@@ -386,7 +386,7 @@ export function createLinkRegistry(options = {}) {
 	})
 
 	/**
-	 *
+	 * 启动 discovery/link runtime 并开启 mesh keepalive。
 	 */
 	const ensureRuntimeWithMesh = async () => {
 		await bootstrap.ensureRuntime()

package/transport/runtime_bootstrap.mjs

@@ -242,7 +242,7 @@ export function createRuntimeBootstrap(deps) {
 							if (typeof stop === 'function' && generation === gen && isLive()) {
 								const prev = stopPresence
 								/**
-								 *
+								 * 停止 presence 广播并链式调用上一轮清理。
 								 */
 								stopPresence = () => { try { stop() } catch { /* ignore */ }; prev?.() }
 							}
@@ -256,7 +256,7 @@ export function createRuntimeBootstrap(deps) {
 							if (typeof stop === 'function' && generation === gen && isLive()) {
 								const prev = stopSignalListener
 								/**
-								 *
+								 * 停止信令监听并链式调用上一轮清理。
 								 */
 								stopSignalListener = () => { try { stop() } catch { /* ignore */ }; prev?.() }
 							}