@steve02081504/fount-p2p 0.0.10 → 0.0.12

package/transport/runtime_bootstrap.mjs

@@ -0,0 +1,369 @@
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+import { advertiseTopic, listenSignals, listDiscoveryProviders, registerDiscoveryProvider } from '../discovery/index.mjs'
+import { createMdnsDiscoveryProvider } from '../discovery/mdns.mjs'
+import { mergeSignalingRelayUrls, createNostrDiscoveryProvider } from '../discovery/nostr.mjs'
+import { buildSignedAdvert } from '../link/handshake.mjs'
+import { createBleGattLinkProvider } from '../link/providers/ble_gatt.mjs'
+import {
+	listLinkProviders,
+	registerLinkProvider,
+	unregisterLinkProvider,
+} from '../link/providers/index.mjs'
+import { createLanTcpLinkProvider } from '../link/providers/lan_tcp.mjs'
+import { createWebRtcLinkProvider } from '../link/providers/webrtc.mjs'
+import { getNodeTransportSettings } from '../node/identity.mjs'
+import { getSignalingRuntimeConfig } from '../node/instance.mjs'
+
+import { encryptSignalPacket } from './signal_crypto.mjs'
+
+/**
+ * Provider 是否会在 isAvailable() 调用时触发 native/异步探测（不得在 ensureRuntime 快路径调用）。
+ * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+ * @returns {boolean} `caps.probe === 'native'` 时 true
+ */
+export function providerHasNativeProbe(provider) {
+	return provider.caps?.probe === 'native'
+}
+
+/**
+ * 收集快路径应 listen 的 provider（仅 owned lan_tcp + 同步可用者）。
+ * 切勿调用 caps.probe==='native' 的 isAvailable（会触发 ble/webrtc 探测）。
+ * @param {import('../link/providers/index.mjs').LinkProvider | null} ownedLanTcp 本 registry 持有的 lan_tcp
+ * @returns {import('../link/providers/index.mjs').LinkProvider[]} 可在 ensureRuntime 快路径 listen 的 provider
+ */
+export function collectFastListenProviders(ownedLanTcp) {
+	/** @type {import('../link/providers/index.mjs').LinkProvider[]} */
+	const listenProviders = []
+	if (ownedLanTcp) listenProviders.push(ownedLanTcp)
+	for (const provider of listLinkProviders()) {
+		const id = String(provider.id)
+		if (id.startsWith('lan_tcp') || id.startsWith('ble_gatt')) continue
+		if (typeof provider.ensureListening !== 'function') continue
+		if (providerHasNativeProbe(provider)) continue
+		if (typeof provider.isAvailable === 'function')
+			try {
+				const available = provider.isAvailable()
+				// 未标 probe:native 却返回 thenable：跳过，勿 await。
+				if (available && typeof available.then === 'function') continue
+				if (!available) continue
+			}
+			catch { continue }
+
+		listenProviders.push(provider)
+	}
+	return listenProviders
+}
+
+/**
+ * Discovery + link listen 暖机（ensureRuntime 立即返回；listen/公网/BT 后台渐进）。
+ * @param {object} deps 依赖注入
+ * @param {{ nodeHash: string, nodePubKey: string, secretKey: Uint8Array }} deps.localIdentity 本地身份
+ * @param {string} deps.selfTopic 本机 rendezvous topic
+ * @param {boolean} deps.autoRegisterDiscoveryProviders 是否自动注册 discovery provider
+ * @param {boolean} deps.autoRegisterLinkProviders 是否自动注册内置 link provider
+ * @param {(link: object) => void} deps.onInboundLink 入站链路回调
+ * @param {(bytes: Uint8Array) => Promise<void>} deps.handleIncomingSignal 入站加密信令处理
+ * @returns {{
+ *   ensureRuntime: () => Promise<void>,
+ *   whenListening: () => Promise<void>,
+ *   whenSignalListening: () => Promise<void>,
+ *   buildLocalAdvert: (topic: string) => Promise<object>,
+ *   lanTcpPort: () => number | null,
+ *   ownedLanTcp: () => object | null,
+ *   ownedBleGatt: () => object | null,
+ *   shutdown: () => Promise<void>,
+ * }} 运行时暖机句柄
+ */
+export function createRuntimeBootstrap(deps) {
+	const {
+		localIdentity,
+		selfTopic,
+		autoRegisterDiscoveryProviders,
+		autoRegisterLinkProviders,
+		onInboundLink,
+		handleIncomingSignal,
+	} = deps
+
+	let runtimeStarted = false
+	/** @type {Promise<void> | null} */
+	let runtimeStart = null
+	/** @type {Promise<void> | null} */
+	let lanListenReady = null
+	/** @type {Promise<void> | null} selfTopic listenSignals 已挂上（offer/answer dial 前必须等） */
+	let signalListenReady = null
+	/** @type {Promise<void> | null} */
+	let runtimeWarm = null
+	/** @type {Promise<void> | null} */
+	let bluetoothWarm = null
+	/** @type {(() => void) | null} */
+	let stopAdvert = null
+	/** @type {(() => void) | null} */
+	let stopSignalListener = null
+	/** @type {Array<() => void>} */
+	const stopLinkListeners = []
+	/** @type {ReturnType<typeof createLanTcpLinkProvider> | null} */
+	let ownedLanTcp = null
+	/** @type {ReturnType<typeof createBleGattLinkProvider> | null} */
+	let ownedBleGatt = null
+	/** @type {number} shutdown 时递增，后台任务检查后退出 */
+	let generation = 0
+
+	/**
+	 * 暖机是否仍在运行（shutdown 后为 false）。
+	 * @returns {boolean} runtime 已启动且未 shutdown 时 true
+	 */
+	function isLive() {
+		return runtimeStarted
+	}
+
+	/**
+	 * 自动注册默认 LinkProvider（lan_tcp / webrtc / ble_gatt）。
+	 * @returns {Promise<void>}
+	 */
+	async function ensureLinkProviders() {
+		if (!autoRegisterLinkProviders) return
+		if (!ownedLanTcp) {
+			ownedLanTcp = createLanTcpLinkProvider()
+			registerLinkProvider(ownedLanTcp)
+		}
+		if (!ownedBleGatt) {
+			ownedBleGatt = createBleGattLinkProvider()
+			registerLinkProvider(ownedBleGatt)
+		}
+		const ids = new Set(listLinkProviders().map(provider => provider.id))
+		if (!ids.has('webrtc'))
+			registerLinkProvider(createWebRtcLinkProvider())
+	}
+
+	/**
+	 * 本 registry 的 LAN TCP 监听端口。
+	 * @returns {number | null} listen 端口；未 listen 为 null
+	 */
+	function lanTcpPort() {
+		const endpoint = typeof ownedLanTcp?.localEndpoint === 'function' ? ownedLanTcp.localEndpoint() : null
+		return normalizeTcpPort(endpoint?.port)
+	}
+
+	/**
+	 * 等待本地 lan_tcp listen 落定。shell / startNode 不应调用。
+	 * @returns {Promise<void>}
+	 */
+	async function whenListening() {
+		if (lanListenReady) await lanListenReady.catch(() => { })
+	}
+
+	/**
+	 * 等待 selfTopic 信令监听挂上（needsOfferAnswer dial 前调用）。
+	 * @returns {Promise<void>}
+	 */
+	async function whenSignalListening() {
+		if (signalListenReady) await signalListenReady.catch(() => { })
+	}
+
+	/**
+	 * 构造带本机身份与（若已 listen）tcpPort 的签名 advert。
+	 * @param {string} topic 广播主题
+	 * @returns {Promise<object>} 签名 advert
+	 */
+	async function buildLocalAdvert(topic) {
+		await whenListening()
+		const tcpPort = lanTcpPort()
+		return await buildSignedAdvert(topic, Date.now(), {
+			...localIdentity,
+			...tcpPort != null ? { tcpPort } : {},
+		})
+	}
+
+	/**
+	 * 对单个 link provider 调用 ensureListening，收集 stop。
+	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+	 * @returns {Promise<void>}
+	 */
+	async function startProviderListening(provider) {
+		if (typeof provider.ensureListening !== 'function') return
+		try {
+			const stop = await provider.ensureListening({
+				localIdentity,
+				onInbound: onInboundLink,
+			})
+			if (typeof stop === 'function') stopLinkListeners.push(stop)
+		}
+		catch { /* provider listen unavailable — normal degrade */ }
+	}
+
+	/**
+	 * 把晚注册 provider 的 stop 链到现有 cleanup。
+	 * @param {'signal' | 'advert'} kind 停止钩子类型
+	 * @param {() => void} stop 新 provider 的取消函数
+	 * @returns {void}
+	 */
+	function chainStop(kind, stop) {
+		if (kind === 'signal') {
+			const prev = stopSignalListener
+			/**
+			 *
+			 */
+			stopSignalListener = () => {
+				try { stop() } catch { /* ignore */ }
+				prev?.()
+			}
+			return
+		}
+		const prev = stopAdvert
+		/**
+		 *
+		 */
+		stopAdvert = () => {
+			try { stop() } catch { /* ignore */ }
+			prev?.()
+		}
+	}
+
+	/**
+	 * 后台探测 BT discovery / ble_gatt listen。
+	 * @param {number} gen 启动世代
+	 * @returns {Promise<void>}
+	 */
+	async function warmBluetoothTask(gen) {
+		if (autoRegisterDiscoveryProviders) {
+			const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
+			if (!providerIds.has('bt')) {
+				const bt = await import('../discovery/bt/index.mjs').catch(() => null)
+				if (generation !== gen || !isLive()) return
+				if (await bt?.canUseBluetoothDiscovery?.()) {
+					if (generation !== gen || !isLive()) return
+					const provider = bt.createBluetoothDiscoveryProvider()
+					registerDiscoveryProvider(provider)
+					if (generation !== gen || !isLive()) return
+					if (provider.caps?.canSignal && typeof provider.onSignal === 'function')
+						try {
+							const stop = await provider.onSignal(selfTopic, bytes => {
+								void handleIncomingSignal(bytes).catch(() => { })
+							})
+							if (typeof stop === 'function' && generation === gen && isLive())
+								chainStop('signal', stop)
+						}
+						catch { /* ignore */ }
+					if (provider.caps?.canDiscover && typeof provider.advertise === 'function')
+						try {
+							const stop = await provider.advertise(selfTopic, encryptSignalPacket(selfTopic, {
+								type: 'advert',
+								body: await buildLocalAdvert(selfTopic),
+							}))
+							if (typeof stop === 'function' && generation === gen && isLive())
+								chainStop('advert', stop)
+						}
+						catch { /* ignore */ }
+				}
+			}
+		}
+		if (generation !== gen || !isLive()) return
+		if (ownedBleGatt && await Promise.resolve(ownedBleGatt.isAvailable())) {
+			if (generation !== gen || !isLive()) return
+			await startProviderListening(ownedBleGatt)
+		}
+	}
+
+	/**
+	 * 后台：lan_tcp listen → selfTopic listenSignals/advertise。
+	 * @param {number} gen 启动世代（shutdown 时递增以作废后台任务）
+	 * @returns {Promise<void>}
+	 */
+	function warmListenAndDiscovery(gen) {
+		const listenProviders = collectFastListenProviders(ownedLanTcp)
+		// 同步挂上 Promise，避免 ensureRuntime 返回后 buildLocalAdvert 看不到 lanListenReady。
+		lanListenReady = Promise.all(listenProviders.map(provider => startProviderListening(provider))).then(() => { })
+		signalListenReady = (async () => {
+			await lanListenReady.catch(() => { })
+			if (generation !== gen || !isLive()) return
+			if (!listDiscoveryProviders().length) return
+			stopSignalListener = await listenSignals(selfTopic, bytes => {
+				void handleIncomingSignal(bytes).catch(() => { })
+			})
+		})()
+		return (async () => {
+			await signalListenReady.catch(() => { })
+			if (generation !== gen || !isLive()) return
+			if (!listDiscoveryProviders().length) return
+			stopAdvert = await advertiseTopic(selfTopic, encryptSignalPacket(selfTopic, {
+				type: 'advert',
+				body: await buildLocalAdvert(selfTopic),
+			}))
+		})()
+	}
+
+	/**
+	 * 仅注册 provider 并调度后台暖机后立即返回。
+	 * @returns {Promise<void>}
+	 */
+	async function ensureRuntime() {
+		if (runtimeStarted) return
+		if (runtimeStart) return await runtimeStart
+		runtimeStart = (async () => {
+			runtimeStarted = true
+			const gen = generation
+			await ensureLinkProviders()
+			if (autoRegisterDiscoveryProviders) {
+				const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
+				if (!providerIds.has('mdns'))
+					registerDiscoveryProvider(createMdnsDiscoveryProvider())
+				if (!providerIds.has('nostr'))
+					registerDiscoveryProvider(createNostrDiscoveryProvider({
+						relayUrls: getSignalingRuntimeConfig().relayOverride
+							?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls),
+					}))
+			}
+			bluetoothWarm = warmBluetoothTask(gen).catch(() => { })
+			runtimeWarm = warmListenAndDiscovery(gen)
+			void runtimeWarm.catch(() => { })
+		})()
+		try {
+			await runtimeStart
+		}
+		finally {
+			runtimeStart = null
+		}
+	}
+
+	/**
+	 * 停止暖机与 owned providers（链路表由 registry 自行清理）。
+	 * 不 await bluetoothWarm：noble/poweredOn 可能挂死；generation 已作废其后副作用。
+	 * @returns {Promise<void>}
+	 */
+	async function shutdown() {
+		runtimeStarted = false
+		generation++
+		await runtimeWarm?.catch(() => { })
+		stopAdvert?.()
+		stopSignalListener?.()
+		stopAdvert = null
+		stopSignalListener = null
+		for (const stop of stopLinkListeners.splice(0))
+			try { stop() } catch { /* ignore */ }
+		if (ownedLanTcp) {
+			unregisterLinkProvider(ownedLanTcp.id)
+			ownedLanTcp = null
+		}
+		if (ownedBleGatt) {
+			unregisterLinkProvider(ownedBleGatt.id)
+			ownedBleGatt = null
+		}
+		lanListenReady = null
+		signalListenReady = null
+		runtimeWarm = null
+		bluetoothWarm = null
+	}
+
+	return {
+		ensureRuntime,
+		whenListening,
+		whenSignalListening,
+		buildLocalAdvert,
+		lanTcpPort,
+		/** @returns {ReturnType<typeof createLanTcpLinkProvider> | null} 本 registry 持有的 lan_tcp */
+		ownedLanTcp: () => ownedLanTcp,
+		/** @returns {ReturnType<typeof createBleGattLinkProvider> | null} 本 registry 持有的 ble_gatt */
+		ownedBleGatt: () => ownedBleGatt,
+		shutdown,
+	}
+}

package/transport/signal_crypto.mjs

@@ -0,0 +1,104 @@
+import { Buffer } from 'node:buffer'
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { sha256Hex } from '../crypto/crypto.mjs'
+import { createLruMap } from '../utils/lru.mjs'
+
+const SIGNAL_DOMAIN = 'fount-signal'
+const NODE_TOPIC_DOMAIN = 'fount-rdv-node:'
+const GROUP_TOPIC_DOMAIN = 'fount-rdv-group:'
+
+/** topic → AES-256 密钥缓存上限（群/节点 topic 会随时间增长，须有界） */
+export const SIGNAL_KEY_CACHE_MAX = 512
+
+/**
+ * 由 nodeHash 派生节点 rendezvous topic。
+ * @param {string} nodeHash 节点 64 hex
+ * @returns {string} rendezvous topic 哈希
+ */
+export function nodeRendezvousTopic(nodeHash) {
+	return sha256Hex(`${NODE_TOPIC_DOMAIN}${normalizeHex64(nodeHash)}`)
+}
+
+/**
+ * 由房间密钥派生群组 rendezvous topic。
+ * @param {string} roomSecret 房间密钥
+ * @returns {string} rendezvous topic 哈希
+ */
+export function groupRendezvousTopic(roomSecret) {
+	return sha256Hex(`${GROUP_TOPIC_DOMAIN}${roomSecret}`)
+}
+
+/** topic → AES-256 密钥 LRU */
+const signalKeysByTopic = createLruMap(SIGNAL_KEY_CACHE_MAX)
+
+/**
+ * 由 topic 派生信令 AES 密钥（同 topic 复用，避免每包 SHA-256）。
+ * @param {string} topic rendezvous 主题
+ * @returns {Buffer} AES-256 密钥
+ */
+function signalKeyForTopic(topic) {
+	let cached = signalKeysByTopic.get(topic)
+	if (cached) {
+		signalKeysByTopic.touch(topic, cached)
+		return cached
+	}
+	cached = createHash('sha256').update(`${SIGNAL_DOMAIN}:${topic}`).digest()
+	signalKeysByTopic.touch(topic, cached)
+	return cached
+}
+
+/**
+ * 当前密钥缓存条目数（测试用）。
+ * @returns {number} 缓存大小
+ */
+export function signalKeyCacheSize() {
+	return signalKeysByTopic.size
+}
+
+/**
+ * 加密信令包为 AES-GCM 字节序列。
+ * @param {string} topic rendezvous 主题
+ * @param {unknown} packet 待加密 JSON 对象
+ * @returns {Uint8Array} 加密后的字节
+ */
+export function encryptSignalPacket(topic, packet) {
+	const iv = randomBytes(12)
+	const cipher = createCipheriv('aes-256-gcm', signalKeyForTopic(topic), iv)
+	const ciphertext = Buffer.concat([
+		cipher.update(Buffer.from(JSON.stringify(packet), 'utf8')),
+		cipher.final(),
+	])
+	return Buffer.from(JSON.stringify({
+		iv: iv.toString('base64'),
+		authTag: cipher.getAuthTag().toString('base64'),
+		ciphertext: ciphertext.toString('base64'),
+	}))
+}
+
+/**
+ * 解密信令包；失败时返回 null。
+ * @param {string} topic rendezvous 主题
+ * @param {Uint8Array} bytes 加密字节
+ * @returns {object | null} 解密后的 JSON 对象
+ */
+export function decryptSignalPacket(topic, bytes) {
+	try {
+		const payload = JSON.parse(Buffer.from(bytes).toString('utf8'))
+		const decipher = createDecipheriv(
+			'aes-256-gcm',
+			signalKeyForTopic(topic),
+			Buffer.from(payload.iv, 'base64'),
+		)
+		decipher.setAuthTag(Buffer.from(payload.authTag, 'base64'))
+		const plain = Buffer.concat([
+			decipher.update(Buffer.from(payload.ciphertext, 'base64')),
+			decipher.final(),
+		])
+		return JSON.parse(plain.toString('utf8'))
+	}
+	catch {
+		return null
+	}
+}

package/transport/user_room.mjs

@@ -3,12 +3,24 @@ 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 { shuffleInPlace } from '../utils/shuffle.mjs'
 import { attachPartWire } from '../wire/part_ingress.mjs'
 import { attachPartQueryWire } from '../wire/part_query.mjs'
 
 import { listLinks, sendToNodeLink, subscribeScope, getLinkRegistry } from './link_registry.mjs'
 import { USER_ROOM_SCOPE } from './room_scopes.mjs'
 
+/**
+ * 经 node scope 向对端发 action。
+ * @param {string} peerId 对端 nodeHash
+ * @param {string} action 动作名
+ * @param {unknown} payload 载荷
+ * @returns {Promise<boolean>} 是否发出
+ */
+const sendNodeAction = (peerId, action, payload) =>
+	sendToNodeLink(peerId, { scope: 'node', action, payload })
+
+
 /**
  * 在 node scope action 表上注册 fed_chunk_get / fed_chunk_data handler，
  * 供用户房间（本地 + 远端）双向 chunk 传输使用。
@@ -63,9 +75,8 @@ function createNodeScopeWire() {
 		 * @returns {void}
 		 */
 		on(name, handler) {
-			const key = String(name)
-			if (!nodeActionHandlers.has(key)) nodeActionHandlers.set(key, new Set())
-			nodeActionHandlers.get(key).add(handler)
+			if (!nodeActionHandlers.has(name)) nodeActionHandlers.set(name, new Set())
+			nodeActionHandlers.get(name).add(handler)
 		},
 		/**
 		 * 向指定 peer 发送 node scope action。
@@ -76,7 +87,7 @@ function createNodeScopeWire() {
 		 */
 		send(name, payload, peerId) {
 			if (!peerId) return
-			void sendToNodeLink(peerId, { scope: 'node', action: String(name), payload }).catch(() => { })
+			void sendNodeAction(peerId, name, payload).catch(() => { })
 		},
 	}
 }
@@ -96,9 +107,9 @@ function activeLinkRoster() {
  */
 async function ensureNodeScopeRuntime(wireContext) {
 	if (nodeScopeCleanup) return
-	nodeScopeReplicaUsername = String(wireContext.replicaUsername || nodeScopeReplicaUsername || '')
+	nodeScopeReplicaUsername = wireContext.replicaUsername || nodeScopeReplicaUsername || ''
 	nodeScopeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
-		const handlers = nodeActionHandlers.get(String(envelope?.action || ''))
+		const handlers = nodeActionHandlers.get(envelope.action)
 		if (!handlers?.size) return
 		for (const handler of handlers)
 			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
@@ -188,7 +199,7 @@ export async function ensureUserRoom(wireContext = {}) {
 				 * @returns {void}
 				 */
 				sendToPeer(peerId, actionName, payload) {
-					void sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload }).catch(() => { })
+					void sendNodeAction(peerId, actionName, payload).catch(() => { })
 				},
 				/**
 				 * 返回当前活跃链路 roster。
@@ -201,7 +212,7 @@ export async function ensureUserRoom(wireContext = {}) {
 				 * @returns {string | null} 对端 id；无链路时为 null
 				 */
 				getPeerIdByNodeHash(nodeHash) {
-					return getLinkRegistry().getLink(nodeHash) ? String(nodeHash) : null
+					return getLinkRegistry().getLink(nodeHash) ? nodeHash : null
 				},
 			}
 			return userRoomSlot
@@ -234,15 +245,11 @@ export async function deliverToUserRoomPeers(username, actionName, payload, exce
 	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))
-		;[peers[swapIndex], peers[pickIndex]] = [peers[pickIndex], peers[swapIndex]]
-	}
+	const peers = shuffleInPlace(slot.getRoster()
+		.filter(({ peerId }) => peerId && peerId !== exceptPeerId))
 	for (const { peerId } of peers)
 		try {
-			if (await sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload: body }))
+			if (await sendNodeAction(peerId, actionName, body))
 				sent++
 			if (sent >= fanoutLimit) break
 		}

package/trust_graph/send.mjs

@@ -26,7 +26,7 @@ export async function sendToNode(username, targetNodeHash, actionName, payload,
 	await ensureUserRoom({ replicaUsername: username })
 
 	// 已直连 peer 不经 trust-graph scope 也应能收发 node scope action（非成员 CAS chunk / follow hint 等）
-	if (await sendToNodeLink(target, { scope: 'node', action: String(actionName), payload }))
+	if (await sendToNodeLink(target, { scope: 'node', action: actionName, payload }))
 		return true
 
 	const merged = graph ?? await buildMergedGraph(username)

package/utils/emit_safe.mjs

@@ -0,0 +1,11 @@
+/**
+ * 调用一组 listener，单次抛错不影响其余。
+ * @param {Iterable<Function>} listeners 回调集合
+ * @param {...unknown} args 传给每个 listener 的参数
+ * @returns {void}
+ */
+export function emitSafe(listeners, ...args) {
+	for (const listener of listeners)
+		try { listener(...args) }
+		catch { /* ignore */ }
+}

package/utils/shuffle.mjs

@@ -0,0 +1,13 @@
+/**
+ * Fisher–Yates 原地洗牌。
+ * @template T
+ * @param {T[]} arr 待洗牌数组（原地修改）
+ * @returns {T[]} 同一数组引用
+ */
+export function shuffleInPlace(arr) {
+	for (let i = arr.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1))
+		;[arr[i], arr[j]] = [arr[j], arr[i]]
+	}
+	return arr
+}

package/utils/ttl_map.mjs

@@ -1,21 +1,46 @@
 /**
- * 带 TTL 的 Map：get 时惰性过期删除。
+ * 带 TTL 的 Map：get 时惰性过期；set 时在超上限下先清过期再 LRU 驱逐。
  * @template T
  * @param {number} ttlMs 存活毫秒
- * @returns {{ ttlMs: number, set: (key: string, value: T) => void, get: (key: string, now?: number) => T | null, clear: () => void }} TTL Map 句柄
+ * @param {number} [maxSize=4096] 最大条目（防只写不读时过期项堆积）
+ * @returns {{ ttlMs: number, maxSize: number, size: () => number, set: (key: string, value: T) => void, get: (key: string, now?: number) => T | null, clear: () => void }} TTL Map 句柄
  */
-export function createTtlMap(ttlMs) {
+export function createTtlMap(ttlMs, maxSize = 4096) {
+	const cap = Math.max(1, Math.floor(Number(maxSize) || 4096))
 	/** @type {Map<string, { value: T, seenAt: number }>} */
 	const map = new Map()
+
+	/**
+	 * 删除过期项；若仍满则按插入序驱逐最旧。
+	 * @param {number} now 当前时间
+	 * @returns {void}
+	 */
+	function prune(now) {
+		for (const [key, entry] of map)
+			if (now - entry.seenAt > ttlMs) map.delete(key)
+		while (map.size >= cap) {
+			const oldest = map.keys().next().value
+			map.delete(oldest)
+		}
+	}
+
 	return {
 		ttlMs,
+		maxSize: cap,
+		/**
+		 * @returns {number} 当前条目数（含未 get 的过期项）
+		 */
+		size: () => map.size,
 		/**
 		 * @param {string} key 键
 		 * @param {T} value 值
 		 * @returns {void}
 		 */
 		set(key, value) {
-			map.set(key, { value, seenAt: Date.now() })
+			const now = Date.now()
+			if (map.has(key)) map.delete(key)
+			if (map.size >= cap) prune(now)
+			map.set(key, { value, seenAt: now })
 		},
 		/**
 		 * @param {string} key 键

package/wire/ingress.mjs

@@ -19,7 +19,7 @@ export function isPlainObject(value) {
  * @returns {Record<string, unknown> | null} 解析失败或非对象时为 null
  */
 export function parseInboundJson(raw) {
-	if (raw == null) return null
+	if (!raw) return null
 	const text = typeof raw === 'string'
 		? raw
 		: Buffer.isBuffer(raw)