@steve02081504/fount-p2p 0.0.27 → 0.0.29

package/README.md

@@ -69,7 +69,7 @@ Reputation pull/apply is separate: `pullReputationFromNode` → JSON; `setReputa
 ## Layout
 
 | Layer | Directory | Role |
-|---|---|---|
+| --- | --- | --- |
 | L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
@@ -83,7 +83,7 @@ Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscovery
 **Public transport modules:**
 
 | Module | Role |
-|---|---|
+| --- | --- |
 | `link_registry.mjs` | fount-network facade: dial fallback, scope/overlay |
 | `user_room.mjs` / `group_link_set.mjs` / `node_scope/wire` + `node_scope/features` | rooms + composable node-scope wires (`registerNodeScopeWireHook`, attaches) |
 | `room_scopes.mjs` / `remote_user_room.mjs` | scope constants / remote user slot |

package/discovery/bt/index.mjs

@@ -9,6 +9,9 @@ import { noteDiscoveryPeerClue } from '../peer_clue.mjs'
 import { getBtPeerHint } from './peer_hints.mjs'
 import { canUseBluetoothRuntime, loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
 
+/**
+ * 重导出有关 BT 生命期的工具函数。
+ */
 export { canUseBluetoothRuntime, waitPoweredOn }
 
 const BT_SERVICE_UUID = 'f017f017f017f017f017f017f017f017'

package/discovery/nostr.mjs

@@ -34,6 +34,8 @@ export const NOSTR_CLOSE_GRACE_MS = 1_000
 export const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
 /** 共享 relay 会话断线后重连间隔。 */
 export const NOSTR_RECONNECT_DELAY_MS = 500
+/** 无 sub/publish 工作时共享 relay 空闲回收延迟（给连续 send 复用窗口）。 */
+export const NOSTR_IDLE_DROP_MS = 2_000
 
 /** Nostr network advert 事件 kind（addressable，可存储）。 */
 export const NOSTR_ADVERT_KIND = 30787
@@ -128,7 +130,7 @@ export async function acceptNostrAdvert(rendezvousKey, bytes, options = {}) {
 	const hash = ingested.verifiedNodeHash
 	const skipHash = options.skipNodeHash ? normalizeHex64(options.skipNodeHash) : null
 	if (skipHash && hash === skipHash) return hash
-	const roomSecret = options.roomSecret
+	const { roomSecret } = options
 	let firstSeen = true
 	if (roomSecret) {
 		firstSeen = !visibleByGroup.get(roomSecret)?.has(hash)
@@ -265,9 +267,10 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
  * @param {string} relayUrl 中继 URL
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
+ * @param {() => boolean} [isCurrent] 该尝试是否仍是 publishRequest 的当前尝试（断线重发后过期）
  * @returns {Promise<boolean>} relay 是否接受 EVENT
  */
-function publishEventOnRelay(ws, relayUrl, event, signal) {
+function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) {
 			reject(new Error('nostr: aborted'))
@@ -285,6 +288,8 @@ function publishEventOnRelay(ws, relayUrl, event, signal) {
 			clearTimeout(timer)
 			signal?.removeEventListener('abort', onAbort)
 			ws.off('message', onMessage)
+			// 过期的 in-flight 尝试：只清理自身监听器/定时器，不结算，避免影响重发后的当前尝试。
+			if (!isCurrent()) return
 			if (error) reject(error)
 			else resolve(ok)
 		}
@@ -331,42 +336,93 @@ function publishEventOnRelay(ws, relayUrl, event, signal) {
  * @returns {Promise<void>}
  */
 async function publishEvent(relayUrls, event, signal) {
-	if (!relayUrls.length) throw new Error('nostr: no relay')
+	const urls = dedupeRelayUrls(relayUrls)
+	if (!urls.length) throw new Error('nostr: no relay')
 	let published = false
 	let lastError = null
-	await Promise.allSettled(relayUrls.map(async relayUrl => {
-		if (signal?.aborted) throw new Error('nostr: aborted')
-		const ws = await connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS, signal)
+	await Promise.allSettled(urls.map(async relayUrl => {
 		try {
-			if (signal?.aborted) throw new Error('nostr: aborted')
-			const ok = await publishEventOnRelay(ws, relayUrl, event, signal)
-			if (ok) published = true
+			if (await publishViaSharedRelay(relayUrl, event, signal)) published = true
 		}
 		catch (error) {
 			lastError = error
-			throw error
-		}
-		finally {
-			dropWebSocket(ws)
 		}
 	}))
 	if (!published) throw lastError || new Error('nostr: no relay accepted publish')
 }
 
 /**
- * 共享 relay 会话：多 SUB 复用同一 URL 的 WebSocket，避免 signal/presence/advert 各建一池。
- * 仍有活跃 sub 时断线会自动重连并重发 REQ。
+ * 一次共享 relay publish 请求：入队（pending）与已派发（inflight）时共用同一结构。
+ * attempt 标识每次实际发送尝试，断线重发会递增；旧的 in-flight 尝试据此自检为过期后自我清理，
+ * 不再结算当前尝试。
+ * @typedef {{
+ *   event: object,
+ *   signal: AbortSignal | undefined,
+ *   attempt: number,
+ *   onAbort: (() => void) | null,
+ *   removeAbort: (() => void) | null,
+ *   resolve: (ok: boolean) => void,
+ *   reject: (err: Error) => void,
+ * }} NostrPublishRequest
+ */
+
+/**
+ * 共享 relay 会话：多 SUB / publish 复用同一 URL 的 WebSocket，避免 signal/presence/advert 各建一池、
+ * 以及每次 send 重开一条连接（内存泄漏）。
+ * 仍有活跃 sub 或待发 publish 时断线会自动重连并重发 REQ / 重发 EVENT。
  * @typedef {{
  *   ws: import('ws').WebSocket | null,
  *   connecting: boolean,
  *   reconnectTimer: ReturnType<typeof setTimeout> | null,
+ *   idleTimer: ReturnType<typeof setTimeout> | null,
  *   subs: Map<string, { filter: object, onEvent: (event: object, relayUrl: string) => void }>,
+ *   pendingPublishes: Array<NostrPublishRequest>,
+ *   inflightPublishes: Array<NostrPublishRequest>,
  * }} SharedRelaySession
  */
 
 /** @type {Map<string, SharedRelaySession>} */
 const sharedRelaySessions = new Map()
 
+/**
+ * 会话是否仍有需要连接的工作（sub 或待发 publish）。
+ * @param {SharedRelaySession} session 会话
+ * @returns {boolean} 是否有活跃工作
+ */
+function hasPendingWork(session) {
+	return session.subs.size  || session.pendingPublishes.length  || session.inflightPublishes.length
+}
+
+/**
+ * 取消会话的空闲回收定时器。
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function clearIdleDrop(session) {
+	if (!session.idleTimer) return
+	clearTimeout(session.idleTimer)
+	session.idleTimer = null
+}
+
+/**
+ * 会话无 sub 时，待 publish 清空后延迟回收空闲 socket（给连续 send 复用窗口）。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function scheduleIdleDrop(relayUrl, session) {
+	if (session.subs.size || session.idleTimer) return
+	session.idleTimer = setTimeout(() => {
+		session.idleTimer = null
+		if (!isLiveSharedSession(relayUrl, session) || hasPendingWork(session)) return
+		sharedRelaySessions.delete(relayUrl)
+		clearSharedRelayReconnect(session)
+		if (session.ws) dropWebSocket(session.ws)
+		session.ws = null
+	}, NOSTR_IDLE_DROP_MS)
+	session.idleTimer.unref?.()
+}
+
 /**
  * @param {string} relayUrl 中继 URL
  * @param {SharedRelaySession} session 会话
@@ -408,7 +464,14 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 	ws.once('close', () => {
 		if (!isLiveSharedSession(relayUrl, session)) return
 		session.ws = null
-		if (!session.subs.size) {
+		// 尚未确认的 inflight publish 重新入队，重连后由 flushPendingPublishes 重发。
+		if (session.inflightPublishes.length) {
+			session.pendingPublishes.push(...session.inflightPublishes)
+			for (const publishRequest of session.inflightPublishes)
+				attachQueuedAbort(session, publishRequest)
+			session.inflightPublishes = []
+		}
+		if (!hasPendingWork(session)) {
 			sharedRelaySessions.delete(relayUrl)
 			return
 		}
@@ -416,6 +479,8 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 	})
 	for (const [subId, sub] of session.subs)
 		try { ws.send(JSON.stringify(['REQ', subId, sub.filter])) } catch { /* ignore */ }
+	flushPendingPublishes(relayUrl, session, ws)
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
 }
 
 /**
@@ -433,16 +498,15 @@ function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 	const start = () => {
 		session.reconnectTimer = null
 		if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
-		if (!session.subs.size) {
+		if (!hasPendingWork(session)) {
 			sharedRelaySessions.delete(relayUrl)
 			return
 		}
 		session.connecting = true
 		void connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS).then(ws => {
 			session.connecting = false
-			if (!isLiveSharedSession(relayUrl, session) || !session.subs.size) {
-				if (!session.subs.size && isLiveSharedSession(relayUrl, session))
-					sharedRelaySessions.delete(relayUrl)
+			if (!isLiveSharedSession(relayUrl, session) || !hasPendingWork(session)) {
+				sharedRelaySessions.delete(relayUrl)
 				dropWebSocket(ws)
 				return
 			}
@@ -454,7 +518,7 @@ function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 				url: relayUrl,
 				err: String(error?.message || error),
 			})
-			if (!session.subs.size) {
+			if (!hasPendingWork(session)) {
 				sharedRelaySessions.delete(relayUrl)
 				return
 			}
@@ -483,7 +547,10 @@ function acquireSharedRelay(relayUrl) {
 		ws: null,
 		connecting: false,
 		reconnectTimer: null,
+		idleTimer: null,
 		subs: new Map(),
+		pendingPublishes: [],
+		inflightPublishes: [],
 	}
 	sharedRelaySessions.set(relayUrl, session)
 	scheduleSharedRelayConnect(relayUrl, session)
@@ -499,12 +566,13 @@ function releaseSharedRelaySub(relayUrl, subscriptionId) {
 	const session = sharedRelaySessions.get(relayUrl)
 	if (!session) return
 	session.subs.delete(subscriptionId)
-	const ws = session.ws
+	const { ws } = session
 	if (ws?.readyState === WebSocket.OPEN)
 		try { ws.send(JSON.stringify(['CLOSE', subscriptionId])) } catch { /* ignore */ }
-	if (session.subs.size) return
+	if (hasPendingWork(session)) return
 	sharedRelaySessions.delete(relayUrl)
 	clearSharedRelayReconnect(session)
+	clearIdleDrop(session)
 	if (ws) dropWebSocket(ws)
 }
 
@@ -518,11 +586,112 @@ function releaseSharedRelaySub(relayUrl, subscriptionId) {
  */
 function registerSharedRelaySub(session, subscriptionId, filter, onEvent) {
 	session.subs.set(subscriptionId, { filter, onEvent })
-	const ws = session.ws
+	clearIdleDrop(session)
+	const { ws } = session
 	if (ws?.readyState !== WebSocket.OPEN) return
 	try { ws.send(JSON.stringify(['REQ', subscriptionId, filter])) } catch { /* ignore */ }
 }
 
+/**
+ * 将已入队的 publish 逐个派发到已打开 socket 上；复用 publishEventOnRelay 等 OK 回执。
+ * 每个 publish 独立携带自己的 message/abort 监听，socket 共享安全。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {import('ws').WebSocket} socket 已打开连接
+ * @returns {void}
+ */
+function flushPendingPublishes(relayUrl, session, socket) {
+	const pending = session.pendingPublishes
+	session.pendingPublishes = []
+	for (const publishRequest of pending) {
+		publishRequest.removeAbort?.()
+		publishRequest.onAbort = null
+		publishRequest.removeAbort = null
+		const attempt = ++publishRequest.attempt
+		session.inflightPublishes.push(publishRequest)
+		void publishEventOnRelay(socket, relayUrl, publishRequest.event, publishRequest.signal, () => publishRequest.attempt === attempt)
+			.then(
+				ok => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.resolve(ok)),
+				error => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.reject(error)),
+			)
+	}
+}
+
+/**
+ * 为队列中的 publish 挂上 abort 处理：先移除监听器（释放 signal 对回调/event/session 的引用），
+ * 再从队列删除并 reject。
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['pendingPublishes'][number]} publishRequest 待发请求
+ * @returns {void}
+ */
+function attachQueuedAbort(session, publishRequest) {
+	const { signal, reject } = publishRequest
+	/**
+	 * 处理 abort 事件
+	 */
+	publishRequest.onAbort = () => {
+		publishRequest.removeAbort?.()
+		const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
+		if (pendingIndex < 0) return
+		session.pendingPublishes.splice(pendingIndex, 1)
+		reject(new Error('nostr: aborted'))
+	}
+	/**
+	 * 移除 abort 监听器
+	 */
+	publishRequest.removeAbort = () => {
+		if (signal) signal.removeEventListener('abort', publishRequest.onAbort)
+	}
+	if (signal) signal.addEventListener('abort', publishRequest.onAbort, { once: true })
+}
+
+/**
+ * publish 在 socket 上得到 OK / 失败 / abort 后结算：从 inflight 移除并 settle。
+ * 仅结算仍与当前 attempt 匹配的请求：断线重发后 attempt 已递增，旧尝试的结算在此短路，
+ * 避免提前结算重发后的当前尝试。已被 requeue（断线重发）的请求不在 inflight，跳过结算。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['inflightPublishes'][number]} publishRequest 已发送请求
+ * @param {number} attempt 本次发送的 attempt 标识
+ * @param {() => void} settle 结算回调（resolve/reject）
+ * @returns {void}
+ */
+function settleInflightPublish(relayUrl, session, publishRequest, attempt, settle) {
+	if (publishRequest.attempt !== attempt) return
+	const inflightIndex = session.inflightPublishes.indexOf(publishRequest)
+	if (inflightIndex < 0) return
+	session.inflightPublishes.splice(inflightIndex, 1)
+	settle()
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
+}
+
+/**
+ * 通过共享 relay 会话发布 EVENT：复用已打开 socket，避免每次 send 重开一条连接（内存泄漏）。
+ * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发。
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+function publishViaSharedRelay(relayUrl, event, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		const session = acquireSharedRelay(relayUrl)
+		clearIdleDrop(session)
+		/** @type {SharedRelaySession['pendingPublishes'][number]} */
+		const publishRequest = { event, signal, attempt: 0, resolve, reject, onAbort: null, removeAbort: null }
+		attachQueuedAbort(session, publishRequest)
+		session.pendingPublishes.push(publishRequest)
+		if (session.ws?.readyState === WebSocket.OPEN)
+			flushPendingPublishes(relayUrl, session, session.ws)
+		else
+			scheduleSharedRelayConnect(relayUrl, session)
+	})
+}
+
 /**
  * 内部：按 rendezvous 键订阅 Nostr kind（topic 不导出）。多订阅共享每 URL 一条连接。
  * @param {string[]} relayUrls 中继 URL 列表

package/index.mjs

@@ -18,6 +18,7 @@ import {
 	setSignalingRuntimeConfig,
 } from './node/instance.mjs'
 import { setConnectivityDebug } from './node/log.mjs'
+import { loadReputation } from './node/reputation_store.mjs'
 import {
 	attachReputationSyncWire,
 	getReputationExportAllowlist,
@@ -30,7 +31,6 @@ import {
 	setTrustSyncDonors,
 	unlockReputationMax,
 } from './node/reputation_sync.mjs'
-import { loadReputation } from './node/reputation_store.mjs'
 import { getRoutingProfile, setRoutingProfile } from './node/routing_profile.mjs'
 import { createGroupLinkSet } from './transport/group_link_set.mjs'
 import {
@@ -38,6 +38,9 @@ import {
 	ensureLinkToNode,
 	ensureOverlayRouter,
 	getLinkRegistry,
+	getPeerHealth,
+	listPeerHealth,
+	onPeerHealth,
 	reloadDiscoveryRelays,
 	sendToNodeLink,
 } from './transport/link_registry.mjs'
@@ -66,6 +69,7 @@ export {
 	getLinkRegistry,
 	getNodeDir,
 	getNodeHash,
+	getPeerHealth,
 	getReputationExportAllowlist,
 	getReputationLocks,
 	getRoutingProfile,
@@ -74,8 +78,10 @@ export {
 	initNode,
 	isInfraRunning,
 	isNodeInitialized,
+	listPeerHealth,
 	loadReputation,
 	lockReputationMax,
+	onPeerHealth,
 	pullReputationFromNode,
 	registerDiscoveryProvider,
 	registerLinkProvider,

package/link/pipe.mjs

@@ -10,6 +10,11 @@ import { buildAuth, buildHello, parseHello, verifyAuth } from './handshake.mjs'
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 
+/** RTT 样本滑动窗口大小。 */
+const RTT_WINDOW_SIZE = 10
+/** 未收到 pong 的 ping 记录保留时长。 */
+const PING_RECORD_TTL_MS = 30000
+
 /**
  * 把 createLinkPipe 句柄收成上层 LinkHandle（可附带测试/内部字段）。
  * @param {ReturnType<typeof createLinkPipe>} pipe pipe 句柄
@@ -42,6 +47,11 @@ export function asLinkHandle(pipe, extras = {}) {
 		 * @returns {ReturnType<typeof pipe.onDown>} 取消订阅
 		 */
 		onDown: (...callArguments) => pipe.onDown(...callArguments),
+		/**
+		 * @param {...any} callArguments 透传 onRtt
+		 * @returns {ReturnType<typeof pipe.onRtt>} 取消订阅
+		 */
+		onRtt: (...callArguments) => pipe.onRtt(...callArguments),
 		/**
 		 * @param {...any} callArguments 透传 close
 		 * @returns {ReturnType<typeof pipe.close>} 关闭完成
@@ -70,6 +80,7 @@ export function asLinkHandle(pipe, extras = {}) {
  * @param {number} [options.heartbeatMs] 心跳间隔
  * @param {number} [options.idleTimeoutMs] 空闲超时
  * @param {number} [options.handshakeTimeoutMs] 握手超时
+ * @param {number} [options.rttWindowSize] RTT 样本滑动窗口大小
  * @returns {object} link 句柄 + 入站 API
  */
 export function createLinkPipe(options) {
@@ -96,6 +107,20 @@ export function createLinkPipe(options) {
 	let lastOutboundAt = 0
 	let sentFrames = 0
 	let recvFrames = 0
+	const rttWindowSize = Math.max(2, Math.floor(Number(options.rttWindowSize) || RTT_WINDOW_SIZE))
+	let pingSeq = 0
+	/** @type {Map<number, number>} seq -> 发送时间戳，未收到 pong 的 ping */
+	const outstandingPings = new Map()
+	let rttMs = null
+	let avgRttMs = null
+	let minRttMs = null
+	let maxRttMs = null
+	let pingCount = 0
+	let pongCount = 0
+	/** @type {number[]} */
+	const rttSamples = []
+	/** @type {Set<(rttMs: number) => void>} */
+	const rttListeners = new Set()
 	const envelopeListeners = new Set()
 	const downListeners = new Set()
 	const completedFrameIds = createLruMap(4096)
@@ -142,7 +167,14 @@ export function createLinkPipe(options) {
 		ready = true
 		clearTimeout(handshakeTimer)
 		heartbeatTimer = setInterval(() => {
-			void send({ scope: 'link', action: 'ping', payload: {} }).catch(() => { })
+			pingCount++
+			const seq = pingSeq++
+			const ts = Date.now()
+			const cutoff = ts - PING_RECORD_TTL_MS
+			for (const [outSeq, outTs] of outstandingPings)
+				if (outTs < cutoff) outstandingPings.delete(outSeq)
+			outstandingPings.set(seq, ts)
+			void send({ scope: 'link', action: 'ping', payload: { ts, seq } }).catch(() => { })
 		}, heartbeatMs)
 		idleTimer = setInterval(() => {
 			if (Date.now() - lastInboundAt > idleTimeoutMs)
@@ -218,10 +250,29 @@ export function createLinkPipe(options) {
 			if (frameId) completedFrameIds.touch(frameId, true)
 			if (envelope?.scope === 'link') {
 				if (envelope.action === 'ping') {
-					void send({ scope: 'link', action: 'pong', payload: {} }).catch(() => { })
+					const pingPayload = envelope.payload ?? {}
+					void send({ scope: 'link', action: 'pong', payload: { ts: pingPayload.ts, seq: pingPayload.seq } }).catch(() => { })
+					return
+				}
+				if (envelope.action === 'pong') {
+					const pongPayload = envelope.payload ?? {}
+					const sentTs = outstandingPings.get(pongPayload.seq)
+					if (Number.isFinite(pongPayload.ts) && sentTs !== undefined && sentTs === pongPayload.ts) {
+						outstandingPings.delete(pongPayload.seq)
+						pongCount++
+						const sample = Date.now() - sentTs
+						if (sample >= 0) {
+							rttMs = sample
+							rttSamples.push(sample)
+							if (rttSamples.length > rttWindowSize) rttSamples.shift()
+							avgRttMs = Math.round(rttSamples.reduce((total, value) => total + value, 0) / rttSamples.length)
+							minRttMs = rttSamples.reduce((minimum, sample) => Math.min(minimum, sample))
+							maxRttMs = rttSamples.reduce((minimum, sample) => Math.max(minimum, sample))
+							emitSafe(rttListeners, rttMs)
+						}
+					}
 					return
 				}
-				if (envelope.action === 'pong') return
 			}
 			if (ready && remoteNodeHash)
 				emitSafe(envelopeListeners, envelope, remoteNodeHash)
@@ -350,6 +401,14 @@ export function createLinkPipe(options) {
 			downListeners.add(callback)
 			return () => downListeners.delete(callback)
 		},
+		/**
+		 * @param {(rttMs: number) => void} callback RTT 样本回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onRtt(callback) {
+			rttListeners.add(callback)
+			return () => rttListeners.delete(callback)
+		},
 		close,
 		handleInbound,
 		startHandshake,
@@ -369,6 +428,12 @@ export function createLinkPipe(options) {
 				lastOutboundAt,
 				sentFrames,
 				recvFrames,
+				rttMs,
+				avgRttMs,
+				minRttMs,
+				maxRttMs,
+				pingCount,
+				pongCount,
 				closeReason,
 				...options.extraStats?.() ?? {},
 			}

package/link/providers/webrtc.mjs

@@ -264,7 +264,7 @@ export async function createWebRtcLink(options) {
 		 */
 		channel.onmessage = event => {
 			try {
-				const data = event.data
+				const { data } = event
 				pipe.handleInbound(typeof data === 'string' ? data : toBytes(data, { allowString: true }))
 			}
 			catch { /* drop */ }

package/link/rtc/ice_local_hostname.mjs

@@ -35,7 +35,7 @@ export function filterIceLocalHostnameCandidate(candidate, RTCIceCandidateCtor,
 	if (!rewritten) return null
 	if (rewritten === raw) return candidate
 	const init = {
-		...(candidate.toJSON?.() || { sdpMid: candidate.sdpMid, sdpMLineIndex: candidate.sdpMLineIndex }),
+		...candidate.toJSON?.() || { sdpMid: candidate.sdpMid, sdpMLineIndex: candidate.sdpMLineIndex },
 		candidate: rewritten,
 	}
 	return new RTCIceCandidateCtor(init)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.27",
+	"version": "0.0.29",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/transport/group_link_set.mjs

@@ -30,7 +30,7 @@ export function createGroupLinkSet(options) {
 	const allowNode = options.allowNode ?? (() => true)
 	const { groupId } = options
 	const scope = options.scope ?? `group:${groupId}`
-	const roomSecret = options.roomSecret
+	const { roomSecret } = options
 	const members = new Set(options.members || [])
 	const selfNodeHash = registry.localIdentity.nodeHash
 	const groupSettings = options.groupSettings ?? {}

package/transport/link_registry.mjs

@@ -17,6 +17,7 @@ import { createLruMap } from '../utils/lru.mjs'
 import { DEFAULT_ICE_SERVERS } from './ice_servers.mjs'
 import { createMeshKeepalive } from './mesh_keepalive.mjs'
 import { createOfferAnswerDial } from './offer_answer.mjs'
+import { createPeerHealthTracker } from './peer_health.mjs'
 import { pickMeshEvictionVictim } from './peer_pool.mjs'
 import { createRuntimeBootstrap } from './runtime_bootstrap.mjs'
 
@@ -480,9 +481,9 @@ export function createLinkRegistry(options = {}) {
 	async function dispatchEnvelope(senderNodeHash, envelope, link) {
 		const { scope } = envelope
 		for (const [prefix, authorizer] of scopeAuthorizers.entries())
-			if (scope.startsWith(prefix)) {
+			if (scope.startsWith(prefix))
 				if (!await authorizer(scope, senderNodeHash, envelope, link)) return
-			}
+
 		for (const [prefix, listeners] of scopeListeners.entries())
 			if (scope.startsWith(prefix))
 				for (const listener of listeners)
@@ -510,6 +511,25 @@ export function createLinkRegistry(options = {}) {
 		return () => scopeAuthorizers.delete(prefix)
 	}
 
+	const peerHealth = createPeerHealthTracker({
+		/**
+		 * @param {(nodeHash: string, link: unknown) => void} listener link up 回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onLinkUp: listener => {
+			linkUpListeners.add(listener)
+			return () => linkUpListeners.delete(listener)
+		},
+		/**
+		 * @param {(nodeHash: string) => void} listener link down 回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onLinkDown: listener => {
+			linkDownListeners.add(listener)
+			return () => linkDownListeners.delete(listener)
+		},
+	})
+
 	return {
 		localIdentity,
 		buildLocalAdvert: bootstrap.buildLocalAdvert,
@@ -629,6 +649,22 @@ export function createLinkRegistry(options = {}) {
 		},
 		registerScopeAuthorizer,
 		subscribeScope,
+		/**
+		 * 获取指定邻居的健康记录。
+		 * @param {string} nodeHash 节点 64 hex
+		 * @returns {import('./peer_health.mjs').PeerHealthEntry | null} 健康记录；无记录时 null
+		 */
+		getPeerHealth: peerHealth.getPeerHealth,
+		/**
+		 * @returns {import('./peer_health.mjs').PeerHealthEntry[]} 所有邻居健康记录
+		 */
+		listPeerHealth: peerHealth.listPeerHealth,
+		/**
+		 * 订阅邻居健康变化。
+		 * @param {(nodeHash: string, entry: import('./peer_health.mjs').PeerHealthEntry) => void} listener 回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onPeerHealth: peerHealth.onPeerHealth,
 		/**
 		 * 监听指定节点的 advert（per-hash，无 topic）。
 		 * @param {string} nodeHash 目标节点 64 hex
@@ -652,6 +688,7 @@ export function createLinkRegistry(options = {}) {
 		 */
 		async shutdown() {
 			await meshKeepalive?.stop()
+			peerHealth.stop()
 			setDiscoveryLinkDialer(null)
 			setDiscoveryPeerClueListener(null)
 			await bootstrap.shutdown()
@@ -744,6 +781,12 @@ export const registerScopeInterest = bindRegistryMethod('registerScopeInterest')
 export const releaseScopeInterest = bindRegistryMethod('releaseScopeInterest')
 /** @type {(...methodArguments: unknown[]) => unknown} */
 export const subscribeScope = bindRegistryMethod('subscribeScope')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const getPeerHealth = bindRegistryMethod('getPeerHealth')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const listPeerHealth = bindRegistryMethod('listPeerHealth')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const onPeerHealth = bindRegistryMethod('onPeerHealth')
 
 /**
  * 注册默认 registry 的 scope authorizer。

package/transport/peer_health.mjs

@@ -0,0 +1,127 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { emitSafe } from '../utils/emit_safe.mjs'
+
+/**
+ * @typedef {{
+ *   nodeHash: string
+ *   connected: boolean
+ *   rttMs: number | null
+ *   avgRttMs: number | null
+ *   lastSeenAt: number
+ *   source: string | null
+ * }} PeerHealthEntry
+ */
+
+/**
+ * 聚合邻居链路健康：在 mesh/link 常态维护期间顺带统计各邻居的 RTT 与可达性。
+ * 订阅 registry 的 link up/down，并对每条活跃链路监听 onRtt/onDown。
+ * @param {object} registry link registry（onLinkUp / onLinkDown）
+ * @returns {{
+ *   getPeerHealth: (nodeHash: string) => PeerHealthEntry | null
+ *   listPeerHealth: () => PeerHealthEntry[]
+ *   onPeerHealth: (listener: (nodeHash: string, entry: PeerHealthEntry) => void) => () => void
+ *   stop: () => void
+ * }} peer health 聚合器
+ */
+export function createPeerHealthTracker(registry) {
+	/** @type {Map<string, PeerHealthEntry>} */
+	const entries = new Map()
+	/** @type {Map<string, () => void>} 每条链路在 registry/link 上的取消订阅回调 */
+	const cleanups = new Map()
+	/** @type {Set<(nodeHash: string, entry: PeerHealthEntry) => void>} */
+	const listeners = new Set()
+
+	/**
+	 * 合并补丁并通知订阅方。
+	 * @param {string} nodeHash 远端节点 64 hex
+	 * @param {Partial<PeerHealthEntry>} patch 补丁
+	 * @returns {void}
+	 */
+	function update(nodeHash, patch) {
+		const entry = entries.get(nodeHash) ?? {
+			nodeHash,
+			connected: false,
+			rttMs: null,
+			avgRttMs: null,
+			lastSeenAt: 0,
+			source: null,
+		}
+		if (patch.connected !== undefined) entry.connected = patch.connected
+		if (patch.rttMs !== undefined) entry.rttMs = patch.rttMs
+		if (patch.avgRttMs !== undefined) entry.avgRttMs = patch.avgRttMs
+		if (patch.lastSeenAt !== undefined) entry.lastSeenAt = patch.lastSeenAt
+		if (patch.source !== undefined) entry.source = patch.source
+		entries.set(nodeHash, entry)
+		emitSafe(listeners, nodeHash, entry)
+	}
+
+	const stopUp = registry.onLinkUp?.((nodeHash, link) => {
+		const hash = normalizeHex64(nodeHash)
+		if (!hash) return
+		const stopRtt = link?.onRtt?.(() => {
+			const stats = link.stats?.() ?? {}
+			update(hash, {
+				rttMs: stats.rttMs ?? null,
+				avgRttMs: stats.avgRttMs ?? null,
+				lastSeenAt: Date.now(),
+			})
+		}) ?? null
+		const stopDown = link?.onDown?.(() => {
+			cleanups.get(hash)?.()
+			cleanups.delete(hash)
+			update(hash, { connected: false, lastSeenAt: Date.now() })
+		}) ?? null
+		update(hash, {
+			connected: true,
+			source: link?.providerId ?? null,
+			lastSeenAt: Date.now(),
+		})
+		cleanups.set(hash, () => {
+			stopRtt?.()
+			stopDown?.()
+		})
+	}) ?? null
+	const stopDown = registry.onLinkDown?.(nodeHash => {
+		const hash = normalizeHex64(nodeHash)
+		if (!hash) return
+		cleanups.get(hash)?.()
+		cleanups.delete(hash)
+		update(hash, { connected: false, lastSeenAt: Date.now() })
+	}) ?? null
+
+	return {
+		/**
+		 * @param {string} nodeHash 远端节点 64 hex
+		 * @returns {PeerHealthEntry | null} 健康记录；无记录时 null
+		 */
+		getPeerHealth(nodeHash) {
+			return entries.get(normalizeHex64(nodeHash)) ?? null
+		},
+		/**
+		 * @returns {PeerHealthEntry[]} 所有邻居健康记录
+		 */
+		listPeerHealth() {
+			return [...entries.values()]
+		},
+		/**
+		 * @param {(nodeHash: string, entry: PeerHealthEntry) => void} listener 变化回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onPeerHealth(listener) {
+			listeners.add(listener)
+			return () => listeners.delete(listener)
+		},
+		/**
+		 * 停止监听并清空聚合。
+		 * @returns {void}
+		 */
+		stop() {
+			stopUp?.()
+			stopDown?.()
+			for (const cleanup of cleanups.values()) cleanup()
+			cleanups.clear()
+			entries.clear()
+			listeners.clear()
+		},
+	}
+}

package/transport/runtime_bootstrap.mjs

@@ -41,7 +41,7 @@ export function collectFastListenProviders(ownedLanTcp) {
 	const listenProviders = []
 	if (ownedLanTcp) listenProviders.push(ownedLanTcp)
 	for (const provider of listLinkProviders()) {
-		const id = provider.id
+		const { id } = provider
 		if (id.startsWith('lan_tcp') || id.startsWith('ble_gatt')) continue
 		if (!provider.ensureListening) continue
 		if (providerHasNativeProbe(provider)) continue