@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/transport/mesh_keepalive.mjs

@@ -0,0 +1,217 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { listVisibleNodeHashes as discoveryListVisible } from '../discovery/index.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
+import { applyNetworkHint, loadPeerPoolView, promoteExplorePeer } from '../node/network.mjs'
+import { loadReputation } from '../node/reputation_store.mjs'
+import { getRoutingProfile } from '../node/routing_profile.mjs'
+
+import { pickMeshEvictionVictim, resolveMeshPoolLimits, selectMeshLinkTargets } from './peer_pool.mjs'
+import { loadTransportTunables } from './tunables.mjs'
+
+/** 本机主动关链：不清槽重拨，由下次 tick / 调用方决定。 */
+const INTENTIONAL_CLOSE = new Set([
+	'budget-evict',
+	'manual-close',
+	'registry-shutdown',
+	'inbound-no-nodehash',
+])
+
+/**
+ * @param {string | undefined} reason 关链原因
+ * @returns {boolean} 是否为本机主动关链（不重拨）
+ */
+export function isMeshIntentionalClose(reason) {
+	return INTENTIONAL_CLOSE.has(String(reason || ''))
+}
+
+/**
+ * 创建 mesh 保活控制器：扫描可见节点、按 N/K 拨号、稳定探索晋升熟人。
+ * @param {object} deps 依赖
+ * @param {object} deps.registry link registry（ensureLinkToNode / listLinks / onLinkUp / onLinkDown）
+ * @param {boolean} [deps.enabled=true] 是否启用
+ * @returns {{ exploreLinkHashes: Set<string>, start: () => void, stop: () => Promise<void> }} mesh 保活控制器
+ */
+export function createMeshKeepalive(deps) {
+	const { registry, enabled = true } = deps
+	const tunables = loadTransportTunables()
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let timer = null
+	/** @type {Set<string>} */
+	const exploreLinks = new Set()
+	/** @type {Map<string, number>} */
+	const exploreStableSince = new Map()
+	/** @type {(() => void) | null} */
+	let stopLinkDown = null
+	/** @type {(() => void) | null} */
+	let stopLinkUp = null
+	/** @type {Promise<void> | null} */
+	let tickInflight = null
+
+	/**
+	 * 非熟人活跃链记入探索槽（含入站）；熟人则清掉探索标记。
+	 * @param {string} nodeHash 对端
+	 * @param {string[]} [trustedPeers] 熟人表；省略则读盘
+	 * @returns {void}
+	 */
+	function syncExploreMark(nodeHash, trustedPeers) {
+		const hash = normalizeHex64(nodeHash)
+		if (!hash) return
+		const trusted = trustedPeers ?? loadPeerPoolView().trustedPeers
+		if (trusted.includes(hash)) {
+			exploreLinks.delete(hash)
+			exploreStableSince.delete(hash)
+			return
+		}
+		exploreLinks.add(hash)
+	}
+
+	/**
+	 * 为拨号腾出空位：优先踢探索。
+	 * @param {number} needSlots 需要空位
+	 * @param {string[]} trustedPeers 熟人表
+	 * @returns {Promise<void>}
+	 */
+	async function evictExploreForRoom(needSlots, trustedPeers) {
+		for (let i = 0; i < needSlots; i++) {
+			const connected = registry.listLinks().map(entry => entry.nodeHash)
+			const victimHash = pickMeshEvictionVictim(connected, exploreLinks, trustedPeers, () => 0)
+			if (!victimHash || trustedPeers.includes(victimHash)) break
+			const entry = registry.listLinks().find(item => item.nodeHash === victimHash)
+			if (!entry?.link?.close) break
+			await entry.link.close('budget-evict')
+			exploreLinks.delete(victimHash)
+			exploreStableSince.delete(victimHash)
+			nodeDebug('p2p:mesh evict', { peer: shortHash(victimHash), reason: 'budget-evict' })
+		}
+	}
+
+	/**
+	 * @returns {Promise<void>}
+	 */
+	async function tick() {
+		if (!enabled) return
+		const limits = resolveMeshPoolLimits(getRoutingProfile(), tunables)
+		const promoteMs = Math.max(60_000, Number(tunables.meshPromoteStableMs) || 30 * 60_000)
+		const scanLimit = Math.max(8, Number(tunables.meshScanLimit) || 64)
+		const visible = await discoveryListVisible({ limit: scanLimit })
+		for (const hash of visible)
+			applyNetworkHint({ nodeHash: hash, source: 'mesh:scan', kind: 'visible', weight: 0.15 })
+
+		const peers = loadPeerPoolView()
+		const rep = loadReputation()
+		const now = Date.now()
+		const connected = new Set(registry.listLinks().map(entry => entry.nodeHash))
+		for (const nodeHash of connected)
+			syncExploreMark(nodeHash, peers.trustedPeers)
+
+		const targets = selectMeshLinkTargets({
+			selfNodeHash: registry.localIdentity.nodeHash,
+			trustedPeers: peers.trustedPeers,
+			exploreCandidates: [...new Set([...peers.explorePeers, ...visible])],
+			hintSources: peers.hintSources,
+			limits,
+			connectedHashes: connected,
+			rep,
+			blockedPeers: peers.blockedPeers,
+			now,
+		})
+		const toDial = targets.filter(nodeHash => !connected.has(nodeHash))
+		nodeDebug('p2p:mesh tick', {
+			N: limits.N,
+			K_max: limits.K_max,
+			visible: visible.map(hash => shortHash(hash)),
+			connected: [...connected].map(hash => shortHash(hash)),
+			dial: toDial.map(hash => shortHash(hash)),
+		})
+		const overflow = connected.size + toDial.length - limits.N
+		if (overflow > 0)
+			await evictExploreForRoom(overflow, peers.trustedPeers)
+
+		for (const nodeHash of toDial)
+			void registry.ensureLinkToNode(nodeHash).then(link => {
+				if (link) {
+					syncExploreMark(nodeHash, peers.trustedPeers)
+					nodeDebug('p2p:mesh dial ok', { peer: shortHash(nodeHash), provider: link.providerId })
+				}
+				else
+					nodeDebug('p2p:mesh dial miss', { peer: shortHash(nodeHash) })
+			}).catch(error => {
+				nodeDebug('p2p:mesh dial fail', {
+					peer: shortHash(nodeHash),
+					err: String(error?.message || error),
+				})
+			})
+
+		const connectedAfter = new Set(registry.listLinks().map(entry => entry.nodeHash))
+		for (const nodeHash of connectedAfter) {
+			if (peers.trustedPeers.includes(nodeHash)) {
+				exploreStableSince.delete(nodeHash)
+				continue
+			}
+			if (!exploreLinks.has(nodeHash)) continue
+			const since = exploreStableSince.get(nodeHash) ?? now
+			if (!exploreStableSince.has(nodeHash)) exploreStableSince.set(nodeHash, since)
+			else if (now - since >= promoteMs) {
+				promoteExplorePeer(nodeHash)
+				exploreLinks.delete(nodeHash)
+				exploreStableSince.delete(nodeHash)
+				nodeDebug('p2p:mesh promote', { peer: shortHash(nodeHash) })
+			}
+		}
+		for (const hash of [...exploreStableSince.keys()])
+			if (!connectedAfter.has(hash)) exploreStableSince.delete(hash)
+	}
+
+	/**
+	 * @returns {Promise<void>}
+	 */
+	function runTick() {
+		if (tickInflight) return tickInflight
+		tickInflight = tick().catch(error => {
+			nodeDebug('p2p:mesh tick fail', { err: String(error?.message || error) })
+		}).finally(() => { tickInflight = null })
+		return tickInflight
+	}
+
+	return {
+		/** @returns {Set<string>} 探索链路集合（trim 时优先驱逐） */
+		exploreLinkHashes: exploreLinks,
+		/**
+		 * 启动 mesh 扫描 / 拨号 / 晋升循环。
+		 * @returns {void}
+		 */
+		start() {
+			if (!enabled || timer) return
+			nodeDebug('p2p:mesh start', { self: shortHash(registry.localIdentity?.nodeHash) })
+			stopLinkUp = registry.onLinkUp?.(nodeHash => {
+				syncExploreMark(nodeHash)
+			}) ?? null
+			stopLinkDown = registry.onLinkDown((nodeHash, reason) => {
+				const hash = normalizeHex64(nodeHash)
+				exploreLinks.delete(hash)
+				exploreStableSince.delete(hash)
+				nodeDebug('p2p:mesh link down', { peer: shortHash(hash), reason })
+				// 主动关链不立刻补洞（避免 budget-evict 刚踢又连）；意外断链用 tick 按 N/K 重选，而非粘住原对端。
+				if (isMeshIntentionalClose(reason)) return
+				void runTick()
+			})
+			void runTick()
+			timer = setInterval(() => { void runTick() }, Math.max(15_000, Number(tunables.meshKeepaliveIntervalMs) || 60_000))
+			timer.unref?.()
+		},
+		/**
+		 * 停止保活并清空探索标记。
+		 * @returns {Promise<void>}
+		 */
+		async stop() {
+			if (timer) { clearInterval(timer); timer = null }
+			stopLinkUp?.()
+			stopLinkUp = null
+			stopLinkDown?.()
+			stopLinkDown = null
+			exploreLinks.clear()
+			exploreStableSince.clear()
+			if (tickInflight) await tickInflight.catch(() => { })
+		},
+	}
+}

package/transport/node_scope.mjs

@@ -0,0 +1,289 @@
+import { attachNodeScopeFedChunkResponder } from '../files/chunk_responder.mjs'
+import { attachMailboxWire } from '../mailbox/wire.mjs'
+import { attachPartWire } from '../wire/part_ingress.mjs'
+import { attachPartQueryWire } from '../wire/part_query.mjs'
+
+import { sendToNodeLink, subscribeScope } from './link_registry.mjs'
+
+/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
+const nodeActionHandlers = new Map()
+
+/** @type {Set<(context: NodeScopeContext, wire: NodeScopeWire) => void>} */
+const nodeScopeWireHooks = new Set()
+
+/** @type {NodeScopeContext} */
+const nodeScopeContext = { replicaUsername: '' }
+
+/** @type {NodeScopeWire | null} */
+let nodeScopeWire = null
+
+/** @type {(() => void) | null} */
+let nodeScopeSubscribeCleanup = null
+
+/** @type {Set<() => void>} */
+const nodeScopeFeatureDisposers = new Set()
+
+/** @type {Map<string, { count: number, disposeCore: () => void }>} */
+const featureAttachRefs = new Map()
+
+/**
+ * @typedef {{ replicaUsername: string }} NodeScopeContext
+ */
+
+/**
+ * @typedef {{
+ *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => () => void
+ *   send: (name: string, payload: unknown, peerId: string | null) => void
+ * }} NodeScopeWire
+ */
+
+/**
+ * @param {string} peerId 对端 nodeHash
+ * @param {string} action 动作名
+ * @param {unknown} payload 载荷
+ * @returns {Promise<boolean>} 是否成功发出
+ */
+const sendNodeAction = (peerId, action, payload) =>
+	sendToNodeLink(peerId, { scope: 'node', action, payload })
+
+/**
+ * @returns {NodeScopeWire} node scope 的 wire 适配器
+ */
+function createNodeScopeWire() {
+	return {
+		/**
+		 * @param {string} name - action 名
+		 * @param {(payload: unknown, peerId: string) => void} handler - 入站处理器
+		 * @returns {() => void} 取消注册的 dispose
+		 */
+		on(name, handler) {
+			if (!nodeActionHandlers.has(name)) nodeActionHandlers.set(name, new Set())
+			nodeActionHandlers.get(name).add(handler)
+			return () => {
+				const set = nodeActionHandlers.get(name)
+				if (!set) return
+				set.delete(handler)
+				if (!set.size) nodeActionHandlers.delete(name)
+			}
+		},
+		/**
+		 * @param {string} name - action 名
+		 * @param {unknown} payload - 出站载荷
+		 * @param {string | null} peerId - 目标 peer，null 时忽略
+		 * @returns {void}
+		 */
+		send(name, payload, peerId) {
+			if (!peerId) return
+			void sendNodeAction(peerId, name, payload).catch(() => { })
+		},
+	}
+}
+
+/**
+ * @returns {boolean} 是否已订阅 node scope
+ */
+export function isNodeScopeSubscribed() {
+	return nodeScopeSubscribeCleanup != null
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {boolean} 是否已挂载处理器
+ */
+export function hasNodeScopeAction(action) {
+	return (nodeActionHandlers.get(action)?.size ?? 0) > 0
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {number} 已注册的处理器数量
+ */
+export function countNodeScopeActionHandlers(action) {
+	return nodeActionHandlers.get(action)?.size ?? 0
+}
+
+/**
+ * 测试/调试：直接派发已挂载的 node action。
+ * @param {string} action - action 名
+ * @param {unknown} payload - 载荷
+ * @param {string} peerId - 发送方 nodeHash
+ * @returns {boolean} 是否有处理器被调用
+ */
+export function dispatchNodeScopeAction(action, payload, peerId) {
+	const handlers = nodeActionHandlers.get(action)
+	if (!handlers?.size) return false
+	for (const handler of handlers)
+		try { handler(payload, peerId) } catch { /* ignore */ }
+	return true
+}
+
+/**
+ * @returns {NodeScopeWire | null} 当前 wire，未 ensure 时为 null
+ */
+export function getNodeScopeWire() {
+	return nodeScopeWire
+}
+
+/**
+ * @returns {NodeScopeContext} 可变 node scope 上下文
+ */
+export function getNodeScopeContext() {
+	return nodeScopeContext
+}
+
+/**
+ * 只订阅 node scope 派发，不挂任何 feature。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消订阅的 dispose
+ */
+export function ensureNodeScope(options = {}) {
+	if (options.replicaUsername != null)
+		nodeScopeContext.replicaUsername = String(options.replicaUsername)
+	if (nodeScopeSubscribeCleanup) return nodeScopeSubscribeCleanup
+	nodeScopeSubscribeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
+		const handlers = nodeActionHandlers.get(envelope.action)
+		if (!handlers?.size) return
+		for (const handler of handlers)
+			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
+	})
+	if (!nodeScopeWire) {
+		nodeScopeWire = createNodeScopeWire()
+		for (const hook of nodeScopeWireHooks)
+			try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	}
+	return nodeScopeSubscribeCleanup
+}
+
+/**
+ * @param {(context: NodeScopeContext, wire: NodeScopeWire) => void} hook - wire 创建时回调
+ * @returns {() => void} 取消注册的 dispose
+ */
+export function registerNodeScopeWireHook(hook) {
+	nodeScopeWireHooks.add(hook)
+	if (nodeScopeWire)
+		try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	return () => nodeScopeWireHooks.delete(hook)
+}
+
+/**
+ * @param {() => void} dispose - feature 卸载函数
+ * @returns {() => void} 包装后的 dispose（同时从跟踪集移除）
+ */
+function trackFeatureDisposer(dispose) {
+	nodeScopeFeatureDisposers.add(dispose)
+	return () => {
+		dispose()
+		nodeScopeFeatureDisposers.delete(dispose)
+	}
+}
+
+/**
+ * 同一 feature 多次 attach 共享一份 wire；dispose 引用计数归零才卸。
+ * @param {string} key - feature 去重键
+ * @param {() => () => void} attachCore - 首次 attach 时执行，返回核心 dispose
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+function attachFeatureRefCounted(key, attachCore) {
+	let entry = featureAttachRefs.get(key)
+	if (!entry) {
+		entry = { count: 0, disposeCore: attachCore() }
+		featureAttachRefs.set(key, entry)
+	}
+	entry.count++
+	return trackFeatureDisposer(() => {
+		const cur = featureAttachRefs.get(key)
+		if (!cur) return
+		cur.count--
+		if (cur.count > 0) return
+		cur.disposeCore()
+		featureAttachRefs.delete(key)
+	})
+}
+
+/**
+ * 自定义 node scope feature（与 mailbox/part 相同 refcount 语义）。
+ * @param {string} key - feature 去重键
+ * @param {(wire: NodeScopeWire, context: NodeScopeContext) => () => void} attachCore - 首次 attach 注册 handler，返回核心 dispose
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+export function attachNodeScopeFeature(key, attachCore, options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted(key, () => attachCore(nodeScopeWire, nodeScopeContext))
+}
+
+/**
+ * refcount 挂载 mailbox wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeMailbox(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('mailbox', () => attachMailboxWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 part ingress wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePart(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('part', () => attachPartWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 part_query wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePartQuery(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('partQuery', () => attachPartQueryWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 fed chunk responder。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeChunks(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('chunks', () =>
+		attachNodeScopeFedChunkResponder(() => nodeScopeContext.replicaUsername, nodeScopeWire))
+}
+
+/**
+ * 全业务 preset（等价旧 ensureNodeScopeRuntime 默认行为）。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消全部 preset 挂载的 dispose
+ */
+export function attachUserRoomDefaultWires(options = {}) {
+	const disposers = [
+		attachNodeScopePart(options),
+		attachNodeScopePartQuery(options),
+		attachNodeScopeMailbox(options),
+		attachNodeScopeChunks(options),
+	]
+	return () => {
+		for (const dispose of disposers) dispose()
+	}
+}
+
+/**
+ * 卸掉 feature 挂载；可选保留 node scope 订阅。
+ * @param {{ keepSubscribe?: boolean }} [options] - true 时保留 node scope 订阅
+ * @returns {void}
+ */
+export function stopNodeScopeRuntime(options = {}) {
+	for (const dispose of [...nodeScopeFeatureDisposers]) dispose()
+	nodeScopeFeatureDisposers.clear()
+	for (const entry of featureAttachRefs.values())
+		try { entry.disposeCore() } catch { /* ignore */ }
+	featureAttachRefs.clear()
+	if (options.keepSubscribe) return
+	nodeScopeSubscribeCleanup?.()
+	nodeScopeSubscribeCleanup = null
+	nodeScopeWire = null
+	nodeActionHandlers.clear()
+}