@steve02081504/fount-p2p 0.0.27 → 0.0.28

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

@@ -128,7 +128,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)
@@ -499,7 +499,7 @@ 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
@@ -518,7 +518,7 @@ function releaseSharedRelaySub(relayUrl, subscriptionId) {
  */
 function registerSharedRelaySub(session, subscriptionId, filter, onEvent) {
 	session.subs.set(subscriptionId, { filter, onEvent })
-	const ws = session.ws
+	const { ws } = session
 	if (ws?.readyState !== WebSocket.OPEN) return
 	try { ws.send(JSON.stringify(['REQ', subscriptionId, filter])) } catch { /* ignore */ }
 }

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.28",
 	"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