@steve02081504/fount-p2p 0.0.0

package/transport/rtc_connection_budget.mjs

@@ -0,0 +1,180 @@
+/**
+ * Trystero/WebRTC 连接预算（进程内）+ 单源槽位配额与 trusted 保留。
+ */
+
+/** @type {Map<string, { active: Set<string>, joinTimestamps: number[], overloadUntil: number, sourceByPeer: Map<string, string>, trustedPeers: Set<string>, peerNodeHash: Map<string, string> }>} */
+const budgets = new Map()
+
+/** 单来源最多占用的非 trusted 槽位比例 */
+export const MAX_SOURCE_SLOT_FRACTION = 0.25
+
+/** 默认 trusted 保留比例 */
+const DEFAULT_TRUSTED_RESERVE_FRACTION = 0.25
+
+/** 默认 trusted 绝对保留槽位 */
+const DEFAULT_MIN_TRUSTED_RESERVED = 3
+
+/**
+ * @param {object} [limits] 限额
+ * @returns {{ maxActive: number, maxJoinsPerMin: number, overloadCooldownMs: number, trustedPeers?: string[], trustedReserveFraction: number, minTrustedReserved: number }} 生效限额
+ */
+export function resolveRtcBudgetLimits(limits = {}) {
+	return {
+		maxActive: Math.max(4, Math.min(128, Number(limits.maxActive) || 32)),
+		maxJoinsPerMin: Math.max(1, Math.min(120, Number(limits.maxJoinsPerMin) || 12)),
+		overloadCooldownMs: Math.max(1000, Number(limits.overloadCooldownMs) || 15_000),
+		trustedPeers: Array.isArray(limits.trustedPeers) ? limits.trustedPeers.map(String) : [],
+		trustedReserveFraction: Math.max(0.1, Math.min(0.5, Number(limits.trustedReserveFraction) || DEFAULT_TRUSTED_RESERVE_FRACTION)),
+		minTrustedReserved: Math.max(1, Math.floor(Number(limits.minTrustedReserved) || DEFAULT_MIN_TRUSTED_RESERVED)),
+	}
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {object} [limits] RTC 限额
+ * @returns {{ active: Set<string>, joinTimestamps: number[], overloadUntil: number, sourceByPeer: Map<string, string>, trustedPeers: Set<string> }} 桶
+ */
+function bucketFor(roomKey, limits = {}) {
+	let bucket = budgets.get(roomKey)
+	if (!bucket) {
+		bucket = {
+			active: new Set(),
+			joinTimestamps: [],
+			overloadUntil: 0,
+			sourceByPeer: new Map(),
+			trustedPeers: new Set(resolveRtcBudgetLimits(limits).trustedPeers || []),
+			peerNodeHash: new Map(),
+		}
+		budgets.set(roomKey, bucket)
+	}
+	for (const id of resolveRtcBudgetLimits(limits).trustedPeers || [])
+		bucket.trustedPeers.add(String(id))
+	return bucket
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {object} [limits] 限额
+ * @returns {boolean} 是否处于过载冷却
+ */
+export function isRtcRoomOverloaded(roomKey, limits = {}) {
+	const { overloadCooldownMs } = resolveRtcBudgetLimits(limits)
+	const bucket = bucketFor(roomKey, limits)
+	return Date.now() < bucket.overloadUntil
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {string} peerId 对等端 id
+ * @param {object} [limits] 限额
+ * @param {string} [sourceId='peer'] 来源标识（用于单源配额）
+ * @returns {boolean} 是否允许新 join/握手
+ */
+export function takeRtcJoinSlot(roomKey, peerId, limits = {}, sourceId = 'peer') {
+	const { maxActive, maxJoinsPerMin, overloadCooldownMs, trustedReserveFraction, minTrustedReserved } = resolveRtcBudgetLimits(limits)
+	const bucket = bucketFor(roomKey, limits)
+	const now = Date.now()
+	if (now < bucket.overloadUntil) return false
+	bucket.joinTimestamps = bucket.joinTimestamps.filter(t => now - t < 60_000)
+	if (bucket.joinTimestamps.length >= maxJoinsPerMin) {
+		bucket.overloadUntil = now + overloadCooldownMs
+		return false
+	}
+	if (peerId && bucket.active.has(peerId)) return true
+
+	const isTrusted = peerId && bucket.trustedPeers.has(peerId)
+	const trustedReserved = Math.max(minTrustedReserved, Math.floor(maxActive * trustedReserveFraction))
+	const maxNonTrusted = Math.max(1, maxActive - trustedReserved)
+	const nonTrustedCount = [...bucket.active].filter(id => !bucket.trustedPeers.has(id)).length
+	if (!isTrusted) {
+		const source = String(sourceId || 'peer')
+		const sameSource = [...bucket.sourceByPeer.entries()].filter(([, s]) => s === source).length
+		const sourceCap = Math.max(1, Math.floor(maxActive * MAX_SOURCE_SLOT_FRACTION))
+		if (sameSource >= sourceCap) return false
+		if (nonTrustedCount >= maxNonTrusted && bucket.active.size >= maxActive) {
+			bucket.overloadUntil = now + overloadCooldownMs
+			return false
+		}
+	}
+
+	if (bucket.active.size >= maxActive && !isTrusted) {
+		bucket.overloadUntil = now + overloadCooldownMs
+		return false
+	}
+	bucket.joinTimestamps.push(now)
+	if (peerId) {
+		bucket.active.add(peerId)
+		bucket.sourceByPeer.set(peerId, String(sourceId || 'peer'))
+	}
+	return true
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {string} peerId Trystero 对端 id
+ * @param {string} nodeHash 对等 nodeHash
+ * @param {object} [limits] 限额（含 trustedPeers nodeHash 列表）
+ * @returns {void}
+ */
+export function annotateRtcPeerNodeHash(roomKey, peerId, nodeHash, limits = {}) {
+	const bucket = budgets.get(roomKey)
+	if (!bucket || !peerId || !nodeHash) return
+	bucket.peerNodeHash.set(peerId, String(nodeHash).trim())
+	for (const trusted of resolveRtcBudgetLimits(limits).trustedPeers || [])
+		if (String(trusted).trim() === String(nodeHash).trim())
+			bucket.trustedPeers.add(peerId)
+
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {string} peerId Trystero 对端 id
+ * @param {string} sourceId 来源标识（PEX hint source / explore 源）
+ * @returns {void}
+ */
+export function setRtcPeerSource(roomKey, peerId, sourceId) {
+	const bucket = budgets.get(roomKey)
+	if (!bucket || !peerId) return
+	bucket.sourceByPeer.set(peerId, String(sourceId || 'peer'))
+}
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {string} peerId 对等端 id
+ * @returns {void}
+ */
+export function releaseRtcPeer(roomKey, peerId) {
+	const bucket = budgets.get(roomKey)
+	if (!bucket || !peerId) return
+	bucket.active.delete(peerId)
+	bucket.sourceByPeer.delete(peerId)
+	bucket.peerNodeHash.delete(peerId)
+}
+
+/** RTC 过载时跳过的非关键联邦 action */
+const NON_CRITICAL_FED_ACTIONS = new Set([
+	'fed_pex',
+	'fed_partition_bridge',
+	'fed_chunk_put',
+	'fed_chunk_get',
+	'fed_chunk_data',
+	'fed_chunk_ack',
+	'part_invoke',
+	'discovery_announce',
+	'discovery_query',
+	'char_rpc',
+	'fed_volatile',
+	'fed_tip_ping',
+	'fed_archive_digest_obs',
+])
+
+/**
+ * @param {string} roomKey 房间键
+ * @param {string} actionName Trystero 动作
+ * @param {object} [limits] 限额
+ * @returns {boolean} 是否允许处理/发送该 action
+ */
+export function isFederationActionAllowedUnderLoad(roomKey, actionName, limits = {}) {
+	if (!isRtcRoomOverloaded(roomKey, limits)) return true
+	return !NON_CRITICAL_FED_ACTIONS.has(String(actionName || '').trim())
+}

package/transport/rtc_mdns_filter.mjs

@@ -0,0 +1,118 @@
+/**
+ * 服务端 WebRTC polyfill（werift / node-datachannel）在 Windows 等环境常产出 `.local` mDNS host candidate，
+ * 远端无法解析。按策略改写为 loopback 或丢弃。
+ */
+
+/** @typedef {'none' | 'rewrite-loopback' | 'drop'} MdnsCandidatePolicy */
+
+/**
+ * @param {string | null | undefined} candidateSdp ICE candidate SDP 行
+ * @param {MdnsCandidatePolicy} policy 处理策略
+ * @returns {string | null} 处理后的 SDP；drop 策略下不可用时返回 null
+ */
+export function applyMdnsHostCandidatePolicy(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 {MdnsCandidatePolicy} policy 处理策略
+ * @returns {RTCIceCandidate | { candidate?: string } | null | undefined} 过滤/改写后的 candidate
+ */
+export function filterMdnsIceCandidate(candidate, RTCIceCandidateCtor, policy) {
+	if (!candidate || policy === 'none') return candidate
+	const raw = typeof candidate === 'string'
+		? candidate
+		: candidate.candidate ?? candidate.toJSON?.()?.candidate ?? ''
+	const rewritten = applyMdnsHostCandidatePolicy(raw, policy)
+	if (!rewritten) return null
+	if (rewritten === raw) return candidate
+	try {
+		const init = typeof candidate.toJSON === 'function'
+			? { ...candidate.toJSON(), candidate: rewritten }
+			: { candidate: rewritten, sdpMid: candidate.sdpMid, sdpMLineIndex: candidate.sdpMLineIndex }
+		return new RTCIceCandidateCtor(init)
+	}
+	catch {
+		return { ...candidate, candidate: rewritten }
+	}
+}
+
+/**
+ * @param {typeof RTCPeerConnection} BaseRTC 原始 polyfill 类
+ * @param {typeof RTCIceCandidate} [RTCIceCandidate] ICE candidate 构造函数
+ * @param {MdnsCandidatePolicy} [policy='drop'] mDNS 策略
+ * @returns {typeof RTCPeerConnection} 包装后的 RTCPeerConnection 类（none 时原样返回）
+ */
+export function wrapRtcPeerConnectionForMdns(BaseRTC, RTCIceCandidate = globalThis.RTCIceCandidate, policy = 'drop') {
+	if (policy === 'none') return BaseRTC
+
+	/**
+	 * @param {RTCPeerConnectionIceEvent} event ICE 候选事件
+	 * @param {(event: RTCPeerConnectionIceEvent) => void} handler 用户 handler
+	 * @returns {void}
+	 */
+	function invokeFilteredIceHandler(event, handler) {
+		if (!event?.candidate) {
+			handler(event)
+			return
+		}
+		const filtered = filterMdnsIceCandidate(event.candidate, RTCIceCandidate, policy)
+		if (!filtered) return
+		if (filtered === event.candidate) {
+			handler(event)
+			return
+		}
+		handler({ ...event, candidate: filtered })
+	}
+
+	return class MdnsFilteredRTCPeerConnection extends BaseRTC {
+		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
+		#userIceHandler = null
+
+		/**
+		 * @param {RTCConfiguration} [config] RTC 配置
+		 */
+		constructor(config) {
+			super(config)
+			/** @param {RTCPeerConnectionIceEvent} event ICE 候选事件 */
+			const relayIce = event => {
+				if (this.#userIceHandler)
+					invokeFilteredIceHandler(event, this.#userIceHandler)
+			}
+			super.onicecandidate = relayIce
+			const iceObs = this.onIceCandidate
+			if (iceObs && typeof iceObs.subscribe === 'function')
+				iceObs.subscribe(candidate => {
+					if (!this.#userIceHandler) return
+					if (!candidate) {
+						this.#userIceHandler({ candidate: null })
+						return
+					}
+					const filtered = filterMdnsIceCandidate(candidate, RTCIceCandidate, policy)
+					if (filtered)
+						this.#userIceHandler({ candidate: filtered })
+				})
+
+		}
+
+		/** @returns {((event: RTCPeerConnectionIceEvent) => void) | null} 用户 ICE 处理器 */
+		get onicecandidate() {
+			return this.#userIceHandler
+		}
+
+		/** @param {((event: RTCPeerConnectionIceEvent) => void) | null} handler ICE 处理器 */
+		set onicecandidate(handler) {
+			this.#userIceHandler = handler
+		}
+	}
+}

package/transport/stale_peer_log.mjs

@@ -0,0 +1,50 @@
+/**
+ * 联邦/房间陈旧 peer 自愈修剪可观测性：进程内计数器 + 近期记录 + debug_logs。
+ *
+ * 无回退行为——仅在发生处记录异常「身份映射滞后于活跃连接」
+ * （群/房间 + peerId + nodeHash），以便追踪 onPeerLeave 遗漏。
+ * 计数通过 catchup stats 暴露给测试；磁盘记录可在 debug_logs/ 下 grep。
+ */
+import { debugLog } from '../utils/debug_log.mjs'
+
+/** @type {Map<string, number>} scopeId → 累计修剪次数 */
+const pruneCounts = new Map()
+/** @type {Array<{ ts: number, scope: string, peerId: string, nodeHash: string | null, meta?: object }>} */
+const recent = []
+const RECENT_CAP = 200
+
+/**
+ * 记录一批陈旧 peer 修剪。
+ * @param {string} scope 计数器 scope（群 id / 房间标签）
+ * @param {Array<{ peerId: string, remoteNodeHash?: string }>} staleEntries 被修剪条目
+ * @param {object} [meta] 写入磁盘记录的额外上下文（partitionId / room）
+ * @returns {void}
+ */
+export function recordStalePeerPrune(scope, staleEntries, meta = {}) {
+	if (!staleEntries?.length) return
+	pruneCounts.set(scope, (pruneCounts.get(scope) || 0) + staleEntries.length)
+	const ts = Date.now()
+	const lines = []
+	for (const { peerId, remoteNodeHash } of staleEntries) {
+		const record = { ts, scope, peerId, nodeHash: remoteNodeHash || null, ...meta }
+		recent.push(record)
+		lines.push(JSON.stringify(record))
+	}
+	while (recent.length > RECENT_CAP) recent.shift()
+	void debugLog('federation_stale_peer', `${lines.join('\n')}\n`).catch(() => { /* best-effort observability */ })
+}
+
+/**
+ * @param {string} scope 计数器 scope
+ * @returns {number} 该 scope 累计修剪次数
+ */
+export function getStalePeerPruneCount(scope) {
+	return pruneCounts.get(scope) || 0
+}
+
+/**
+ * @returns {Array<{ ts: number, scope: string, peerId: string, nodeHash: string | null, meta?: object }>} 近期修剪记录
+ */
+export function getRecentStalePeerPrunes() {
+	return [...recent]
+}

package/transport/user_room.mjs

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto'
+
+import { attachMailboxWire } from '../mailbox/wire.mjs'
+import { ensureNodeDefaults, getNodeHash } from '../node/identity.mjs'
+import { registerFederationRoomProvider } from '../registries/room_provider.mjs'
+import { attachPartWire } from '../wire/part_ingress.mjs'
+
+import { listLinks, sendToNodeLink, subscribeScope, getLinkRegistry } from './link_registry.mjs'
+import { USER_ROOM_SCOPE } from './room_scopes.mjs'
+
+/**
+ * 在 node scope action 表上注册 fed_chunk_get / fed_chunk_data handler，
+ * 供用户房间（本地 + 远端）双向 chunk 传输使用。
+ * @param {string} username 副本用户名 用户名
+ * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire action 表
+ * @returns {void}
+ */
+function attachUserRoomChunkHandlers(username, wire) {
+	import('../files/chunk_responder.mjs').then(({ attachNodeScopeFedChunkResponder }) => {
+		attachNodeScopeFedChunkResponder(username, wire)
+	}).catch(error => console.error('p2p: failed to attach chunk handlers to node scope', error))
+}
+
+/** @type {Promise<UserRoomSlot | null> | null} */
+let userRoomInflight = null
+
+/** @type {UserRoomSlot | null} */
+export let userRoomSlot = null
+
+/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
+const nodeActionHandlers = new Map()
+/** @type {Set<(username: string, wire: { on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }) => void>} */
+const nodeScopeWireHooks = new Set()
+/** @type {string} */
+let nodeScopeReplicaUsername = ''
+/** @type {ReturnType<typeof createNodeScopeWire> | null} */
+let nodeScopeWire = null
+let nodeScopeCleanup = null
+
+/**
+ * Chat 等非 P2P 模块可向 node scope 注册 fed_emoji 等 handler（避免 p2p→shell 硬依赖）。
+ * @param {(username: string, wire: { on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }) => void} hook 注册回调
+ * @returns {() => void} 取消注册
+ */
+export function registerUserRoomNodeScopeHook(hook) {
+	nodeScopeWireHooks.add(hook)
+	if (nodeScopeWire)
+		try { hook(nodeScopeReplicaUsername, nodeScopeWire) } catch { /* ignore */ }
+	return () => nodeScopeWireHooks.delete(hook)
+}
+
+/**
+ * 创建 node scope 的 on/send wire 表。
+ * @returns {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire 接口
+ */
+function createNodeScopeWire() {
+	return {
+		/**
+		 * 注册 node scope action handler。
+		 * @param {string} name action 名称
+		 * @param {(payload: unknown, peerId: string) => void} handler 入站回调
+		 * @returns {void}
+		 */
+		on(name, handler) {
+			const key = String(name)
+			if (!nodeActionHandlers.has(key)) nodeActionHandlers.set(key, new Set())
+			nodeActionHandlers.get(key).add(handler)
+		},
+		/**
+		 * 向指定 peer 发送 node scope action。
+		 * @param {string} name action 名称
+		 * @param {unknown} payload 载荷
+		 * @param {string | null} peerId 目标 peer id
+		 * @returns {void}
+		 */
+		send(name, payload, peerId) {
+			if (!peerId) return
+			void sendToNodeLink(peerId, { scope: 'node', action: String(name), payload }).catch(() => { })
+		},
+	}
+}
+
+/**
+ * 返回当前所有活跃链路的 roster。
+ * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 在线 peer 列表
+ */
+function activeLinkRoster() {
+	return listLinks().map(({ nodeHash }) => ({ peerId: nodeHash, remoteNodeHash: nodeHash }))
+}
+
+/**
+ * 初始化 node scope 订阅与 wire 派发（幂等）。
+ * @param {{ replicaUsername?: string }} ctx 入站上下文
+ * @returns {Promise<void>}
+ */
+async function ensureNodeScopeRuntime(ctx) {
+	if (nodeScopeCleanup) return
+	nodeScopeReplicaUsername = String(ctx.replicaUsername || nodeScopeReplicaUsername || '')
+	nodeScopeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
+		const handlers = nodeActionHandlers.get(String(envelope?.action || ''))
+		if (!handlers?.size) return
+		for (const handler of handlers)
+			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
+	})
+	const wire = createNodeScopeWire()
+	nodeScopeWire = wire
+	attachPartWire({ replicaUsername: ctx.replicaUsername }, wire)
+	attachMailboxWire({ replicaUsername: ctx.replicaUsername }, wire)
+	attachUserRoomChunkHandlers(ctx.replicaUsername || '', wire)
+	for (const hook of nodeScopeWireHooks)
+		try { hook(ctx.replicaUsername || '', wire) } catch { /* ignore */ }
+}
+
+/**
+ * 用户级 node scope 房间（`fount-node-{nodeHash}`），单节点单实例。
+ *
+ * @typedef {{
+ *   roomId: string
+ *   roomSecret: string
+ *   room: object
+ *   sendToPeer: (peerId: string, actionName: string, payload: unknown) => void
+ *   getRoster: () => Array<{ peerId: string, remoteNodeHash: string | undefined }>
+ *   getPeerIdByNodeHash: (nodeHash: string) => string | null
+ * }} UserRoomSlot
+ */
+
+registerFederationRoomProvider('user-room', () => {
+	if (!userRoomSlot) return []
+	return [{
+		groupId: USER_ROOM_SCOPE,
+		/** @returns {Array<{ peerId: string, remoteNodeHash: string | undefined }>} 房间 roster 列表 */
+		getRoster: () => userRoomSlot.getRoster(),
+		/**
+		 * @param {string} nodeHash 64 位十六进制
+		 * @returns {string | null} 对端 id
+		 */
+		getPeerIdByNodeHash: nodeHash => userRoomSlot.getPeerIdByNodeHash(nodeHash),
+		/**
+		 * @param {string} peerId 目标 peer
+		 * @param {string} actionName 节点 scope action
+		 * @param {unknown} payload 载荷
+		 * @returns {void}
+		 */
+		sendToPeer: (peerId, actionName, payload) => userRoomSlot.sendToPeer(peerId, actionName, payload),
+	}]
+})
+
+/**
+ * @returns {{ appId: string, password: string, roomId: string, nodeHash: string }} 用户房间参数
+ */
+export function resolveUserRoomCredentials() {
+	const nodeHash = getNodeHash()
+	const password = createHash('sha256').update(`fount-user-room:${nodeHash}`).digest('hex')
+	return {
+		appId: 'fount-user-fed',
+		password,
+		roomId: `fount-node-${nodeHash}`,
+		nodeHash,
+	}
+}
+
+/**
+ * @param {{ replicaUsername?: string }} [ctx] 入站上下文（part/mailbox 派发用）
+ * @returns {Promise<UserRoomSlot | null>} 用户级联邦房间槽
+ */
+export async function ensureUserRoom(ctx = {}) {
+	if (userRoomSlot) return userRoomSlot
+	if (userRoomInflight) return await userRoomInflight
+
+	userRoomInflight = (async () => {
+		ensureNodeDefaults()
+		try {
+			await getLinkRegistry().ensureRuntime()
+			await ensureNodeScopeRuntime(ctx)
+			const creds = resolveUserRoomCredentials()
+			/** @type {UserRoomSlot} */
+			userRoomSlot = {
+				roomId: creds.roomId,
+				roomSecret: creds.password,
+				room: null,
+				/**
+				 * 经 node scope 向 peer 发送 action。
+				 * @param {string} peerId 目标 peer id
+				 * @param {string} actionName action 名称
+				 * @param {unknown} payload 载荷
+				 * @returns {void}
+				 */
+				sendToPeer(peerId, actionName, payload) {
+					void sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload }).catch(() => { })
+				},
+				/**
+				 * 返回当前活跃链路 roster。
+				 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 在线 peer 列表
+				 */
+				getRoster: () => activeLinkRoster(),
+				/**
+				 * 按 nodeHash 查找 peer id。
+				 * @param {string} nodeHash 目标节点 64 hex
+				 * @returns {string | null} 对端 id；无链路时为 null
+				 */
+				getPeerIdByNodeHash(nodeHash) {
+					return getLinkRegistry().getLink(nodeHash) ? String(nodeHash) : null
+				},
+			}
+			return userRoomSlot
+		}
+		catch (error) {
+			console.error('p2p: node scope init failed', error)
+			userRoomSlot = null
+			return null
+		}
+		finally {
+			userRoomInflight = null
+		}
+	})()
+
+	return await userRoomInflight
+}
+
+/**
+ * @returns {void}
+ */
+export function invalidateUserRoom() {
+	userRoomSlot = null
+	userRoomInflight = null
+	nodeScopeWire = null
+	nodeScopeReplicaUsername = ''
+	nodeScopeCleanup = null
+}
+
+/**
+ * @param {string} username 副本用户名
+ * @param {string} actionName 节点 scope action
+ * @param {unknown} payload 载荷
+ * @param {string | null} [exceptPeerId] 跳过的 peer
+ * @param {number} [limit] 最多转发 peer 数
+ * @returns {Promise<number>} 实际转发的 peer 数
+ */
+export async function deliverToUserRoomPeers(username, actionName, payload, exceptPeerId = null, limit) {
+	const { USER_ROOM_PEER_FANOUT_DEFAULT } = await import('../wire/part_common.mjs')
+	const fanoutLimit = limit ?? USER_ROOM_PEER_FANOUT_DEFAULT
+	const slot = await ensureUserRoom({ replicaUsername: username })
+	if (!slot) return 0
+	const body = { ...payload, nodeHash: getNodeHash() }
+	let sent = 0
+	const peers = [...slot.getRoster()
+		.filter(({ peerId }) => peerId && peerId !== exceptPeerId)]
+	for (let swapIndex = peers.length - 1; swapIndex > 0; swapIndex--) {
+		const pickIndex = Math.floor(Math.random() * (swapIndex + 1))
+		const tmp = peers[swapIndex]
+		peers[swapIndex] = peers[pickIndex]
+		peers[pickIndex] = tmp
+	}
+	for (const { peerId } of peers)
+		try {
+			if (await sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload: body }))
+				sent++
+			if (sent >= fanoutLimit) break
+		}
+		catch { /* disconnected */ }
+
+	return sent
+}