@steve02081504/fount-p2p 0.0.29 → 0.0.30

package/discovery/bt/index.mjs

@@ -297,9 +297,7 @@ export function createBluetoothDiscoveryProvider() {
 				cleanup()
 				reject(new Error('p2p: bt signal peripheral timeout'))
 			}, 8_000)
-			/**
-			 * @returns {void}
-			 */
+			/** 清理信号超时计时器并移除 discover 监听器 */
 			function cleanup() {
 				clearTimeout(deadline)
 				noble.removeListener('discover', onDiscover)

package/discovery/nostr.mjs

@@ -243,6 +243,7 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
 			reject(error)
 		}
 		/**
+		 * 收到 abort 信号时失败
 		 * @returns {void}
 		 */
 		const onAbort = () => fail(new Error('nostr: aborted'))
@@ -294,6 +295,7 @@ function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
 			else resolve(ok)
 		}
 		/**
+		 * 收到 abort 信号时以失败结束
 		 * @returns {void}
 		 */
 		const onAbort = () => finish(false, new Error('nostr: aborted'))
@@ -492,9 +494,7 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 	if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
 	clearSharedRelayReconnect(session)
-	/**
-	 * @returns {void}
-	 */
+	/** 启动/恢复共享会话连接 */
 	const start = () => {
 		session.reconnectTimer = null
 		if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return

package/files/chunk/store.mjs

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 
 import { isHex64 } from '../../core/hexIds.mjs'
+import { trackFileStream } from '../../node/handles.mjs'
 import { getNodeDir } from '../../node/instance.mjs'
 
 /**
@@ -50,7 +51,7 @@ export async function getChunk(hash) {
  * @returns {import('node:fs').ReadStream} 可读流
  */
 export function createChunkReadStream(hash) {
-	return fs.createReadStream(chunkStorePath(hash))
+	return trackFileStream(fs.createReadStream(chunkStorePath(hash)))
 }
 
 /**
@@ -72,5 +73,5 @@ export async function putChunk(hash, data) {
 export async function putChunkFromStream(hash, readable) {
 	const filePath = chunkStorePath(hash)
 	await fsp.mkdir(dirname(filePath), { recursive: true })
-	await pipeline(readable, fs.createWriteStream(filePath))
+	await pipeline(readable, trackFileStream(fs.createWriteStream(filePath)))
 }

package/index.mjs

@@ -11,6 +11,7 @@ import {
 import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
+	closeNode,
 	getNodeDir,
 	initNode,
 	isNodeInitialized,
@@ -58,6 +59,7 @@ import {
 export {
 	attachReputationSyncWire,
 	attachNodeScopeDefaultFeatures,
+	closeNode,
 	configureLinkRegistry,
 	createGroupLinkSet,
 	createScopedLinkRoom,

package/infra/priority.mjs

@@ -28,9 +28,7 @@ export function getInfraPriority() {
 	return { ...priorityConfig }
 }
 
-/**
- * @returns {void}
- */
+/** 将优先级配置应用到 link registry */
 export function applyPriorityToRegistry() {
 	const registry = getLinkRegistry()
 	if (!priorityConfig.useLocalReputation) {

package/infra/service.mjs

@@ -42,9 +42,7 @@ export function consumeOverlayRateToken(buckets, sender, now, limits) {
 	return true
 }
 
-/**
- * @returns {void}
- */
+/** 安装 overlay 速率门 */
 function installOverlayRateLimit() {
 	const limits = {
 		perMin: Math.max(1, Number(infraTunables.overlayRatePerMin) || 120),
@@ -56,9 +54,7 @@ function installOverlayRateLimit() {
 	})
 }
 
-/**
- * @returns {void}
- */
+/** 移除 overlay 速率门并清空桶 */
 function removeOverlayRateLimit() {
 	clearOverlayRateGate()
 	overlayRateBuckets.clear()

package/link/providers/ble_gatt.mjs

@@ -80,9 +80,7 @@ async function dialBleGatt(options) {
 			cleanup()
 			reject(new Error('p2p: ble_gatt peripheral scan timeout'))
 		}, 8_000)
-		/**
-		 * @returns {void}
-		 */
+		/** 清理扫描超时计时器与监听器并停止 BLE 扫描 */
 		function cleanup() {
 			clearTimeout(deadline)
 			noble.removeListener('discover', onDiscover)
@@ -249,9 +247,7 @@ export function createBleGattLinkProvider() {
 					sessionInbound = handler
 					return () => { sessionInbound = null }
 				},
-				/**
-				 * @returns {void}
-				 */
+				/** 关闭入站 transport */
 				closeTransport() {
 					activeInbound = null
 					sessionInbound = null

package/link/providers/lan_tcp.mjs

@@ -35,9 +35,7 @@ function connectTcp(host, port, timeoutMs = LAN_TCP_CONNECT_TIMEOUT_MS) {
 			conn.off('connect', onConnect)
 			reject(error)
 		}
-		/**
-		 * @returns {void}
-		 */
+		/** TCP 连接成功并返回 socket */
 		function onConnect() {
 			clearTimeout(timer)
 			conn.off('error', onError)
@@ -111,9 +109,7 @@ function attachLengthPrefix(socket, onPayload) {
 			header.writeUInt32BE(body.length)
 			socket.write(Buffer.concat([header, body]))
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 仅移除 data 监听器 */
 		destroy() {
 			socket.off('data', onData)
 		},
@@ -149,9 +145,7 @@ function createTcpPipe(options) {
 		sendFrame(_action, frame) {
 			codec.write(frame)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 关闭 transport 与 socket */
 		closeTransport() {
 			codec.destroy()
 			socket.destroy()

package/node/handles.mjs

@@ -0,0 +1,49 @@
+/**
+ * 节点生命周期内打开的文件流注册表。
+ *
+ * 文件流（chunk 读流 / 写流）在 Windows 上若未 destroy 会占用文件句柄，
+ * 导致节点目录删除失败。这里集中跟踪，`closeNode()` 通过
+ * `closeAllFileStreams()` 一次性释放全部仍打开的流。
+ */
+
+/** @type {Set<import('node:stream').Readable | import('node:stream').Writable>} */
+const streams = new Set()
+
+/**
+ * 跟踪一个文件流：销毁/关闭/出错时自动从注册表移除。
+ * @template {import('node:stream').Readable | import('node:stream').Writable} T
+ * @param {T} stream 文件流
+ * @returns {T} 原流
+ */
+export function trackFileStream(stream) {
+	streams.add(stream)
+	/** @returns {void} */
+	const forget = () => streams.delete(stream)
+	stream.once('close', forget)
+	stream.once('error', forget)
+	return stream
+}
+
+/**
+ * 关闭并销毁所有仍在打开的文件流（测试 teardown / 节点关闭）。
+ * @returns {Promise<number>} 被销毁的流数量
+ */
+export async function closeAllFileStreams() {
+	const targeted = [...streams]
+	const pending = []
+	for (const stream of targeted) {
+		if (!stream.closed)
+			pending.push(new Promise(resolve => stream.once('close', resolve)))
+		stream.destroy()
+	}
+	await Promise.all(pending)
+	for (const stream of targeted) streams.delete(stream)
+	return targeted.length
+}
+
+/**
+ * @returns {boolean} 是否仍有未释放的文件流（测试断言用）
+ */
+export function hasOpenFileStreams() {
+	return streams.size > 0
+}

package/node/instance.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path'
 
 import { createFsEntityStore } from './entity_store.mjs'
+import { closeAllFileStreams } from './handles.mjs'
 import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './signaling_config.mjs'
 
 /** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void, info?: (...args: unknown[]) => void, log?: (...args: unknown[]) => void }} NodeLogger */
@@ -37,7 +38,7 @@ export function getRtcPolyfillCacheEpoch() {
  * @returns {NodeRuntime} 初始化后的运行时
  */
 export function initNode(options) {
-	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or resetNodeForTests')
+	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or closeNode')
 	if (options?.logger !== undefined || options?.signaling !== undefined)
 		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
 	const nodeDir = path.resolve(options.nodeDir)
@@ -138,11 +139,13 @@ export function onNodeChange(listener) {
 }
 
 /**
- * 测试专用：重置节点运行时。
- * @returns {void}
+ * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时与监听器。
+ * 之后可用 initNode 重新引导。
+ * @returns {Promise<void>}
  */
-export function resetNodeForTests() {
+export async function closeNode() {
 	runtime = null
 	changeListeners.clear()
 	rtcPolyfillCacheEpoch++
+	await closeAllFileStreams()
 }

package/node/reputation_sync.mjs

@@ -78,9 +78,7 @@ function normalizeHashList(list) {
 		.filter(id => isHex64(id)))]
 }
 
-/**
- * @returns {void}
- */
+/** 将当前 sync 配置写盘 */
 function persistSyncConfig() {
 	writeNodeJsonSync(SYNC_DATA_NAME, loadSyncConfig())
 }
@@ -304,9 +302,7 @@ export async function pullReputationFromNode(nodeHash) {
 	return await resultPromise
 }
 
-/**
- * @returns {void}
- */
+/** 重置 sync 运行时（测试用） */
 export function resetReputationSyncForTests() {
 	syncConfig = null
 	detachReputationSyncWire()

package/package.json

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

package/transport/group_link_set.mjs

@@ -99,9 +99,7 @@ export function createGroupLinkSet(options) {
 		scheduleDial()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 按成员选择目标并拨号 */
 	function selectAndDial() {
 		if (!autoconnectEnabled || !active) return
 		const targets = dialAll
@@ -119,9 +117,7 @@ export function createGroupLinkSet(options) {
 				void registry.ensureLinkToNode(nodeHash).catch(() => null)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 延迟调度一次拨号 */
 	function scheduleDial() {
 		if (!autoconnectEnabled || !active || dialTimer) return
 		dialTimer = setTimeout(() => { dialTimer = null; selectAndDial() }, 200)

package/transport/link_registry.mjs

@@ -719,9 +719,7 @@ export function configureLinkRegistry(options = {}) {
 	pendingRegistryOptions = { ...pendingRegistryOptions, ...options }
 }
 
-/**
- * @returns {void}
- */
+/** 重置 link registry 运行时（测试用） */
 export function resetLinkRegistryForTests() {
 	defaultRegistry = null
 	pendingRegistryOptions = null

package/transport/offer_answer.mjs

@@ -48,9 +48,7 @@ export function createBufferedSignalSession(sendRemote) {
 			for (const handler of handlers)
 				handler(message)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空积压消息 */
 		clear() {
 			backlog.length = 0
 			handlers.clear()

package/transport/runtime_bootstrap.mjs

@@ -111,9 +111,7 @@ export function createRuntimeBootstrap(deps) {
 			?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册默认 discovery provider（lan/nostr） */
 	function registerDiscoveryDefaults() {
 		const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
 		if (!providerIds.has('lan'))
@@ -124,9 +122,7 @@ export function createRuntimeBootstrap(deps) {
 			registerNostrProvider()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册/替换 nostr discovery provider */
 	function registerNostrProvider() {
 		unregisterDiscoveryProvider('nostr')
 		registerDiscoveryProvider(createNostrDiscoveryProvider({

package/utils/async_mutex.mjs

@@ -42,9 +42,7 @@ export async function withAsyncMutex(key, criticalSection) {
 	const lockKey = key
 	const state = mutexState(lockKey)
 	return new Promise((resolve, reject) => {
-		/**
-		 * @returns {void}
-		 */
+		/** 执行临界区并最终释放锁 */
 		const run = () => {
 			Promise.resolve()
 				.then(criticalSection)

package/utils/ttl_map.mjs

@@ -56,9 +56,7 @@ export function createTtlMap(ttlMs, maxSize = 4096) {
 			}
 			return entry.value
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空全部条目 */
 		clear() {
 			map.clear()
 		},