@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/node/entity_store.mjs

@@ -80,9 +80,9 @@ export function createFsEntityStore(baseDir) {
 				const entries = await fsp.readdir(root, { withFileTypes: true })
 				return entries.filter(e => e.isDirectory()).map(e => e.name.toLowerCase()).filter(h => parseEntityHash(h))
 			}
-			catch (err) {
-				if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return []
-				throw err
+			catch (error) {
+				if (/** @type {NodeJS.ErrnoException} */ error.code === 'ENOENT') return []
+				throw error
 			}
 		},
 
@@ -115,9 +115,9 @@ export function createFsEntityStore(baseDir) {
 			try {
 				return await fsp.readFile(filePath)
 			}
-			catch (err) {
-				if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return null
-				throw err
+			catch (error) {
+				if (/** @type {NodeJS.ErrnoException} */ error.code === 'ENOENT') return null
+				throw error
 			}
 		},
 

package/node/identity.mjs

@@ -66,9 +66,9 @@ export function getNodeHash() {
  */
 export function getNodeTransportSettings() {
 	const data = loadNodeFile()
-	const relayUrls = Array.isArray(data.relayUrls)
-		? data.relayUrls.map(url => String(url).trim()).filter(url => url.startsWith('wss://'))
-		: []
+	const relayUrls = (data.relayUrls || [])
+		.map(url => url.trim())
+		.filter(url => url.startsWith('wss://'))
 	const batterySaver = !!data.batterySaver
 	const mailbox = normalizeMailboxSettings(data.mailbox || {})
 	return { relayUrls, batterySaver, mailbox }
@@ -82,7 +82,7 @@ export function saveNodeTransportSettings(patch) {
 	const data = loadNodeFile()
 	if (patch.batterySaver != null) data.batterySaver = !!patch.batterySaver
 	if (patch.relayUrls)
-		data.relayUrls = patch.relayUrls.map(url => String(url).trim()).filter(url => url.startsWith('wss://'))
+		data.relayUrls = patch.relayUrls.map(url => url.trim()).filter(url => url.startsWith('wss://'))
 	if (patch.mailbox)
 		data.mailbox = normalizeMailboxSettings({ ...data.mailbox, ...patch.mailbox })
 	saveNodeFile(data)

package/node/instance.mjs

@@ -3,7 +3,7 @@ import path from 'node:path'
 import { createFsEntityStore } from './entity_store.mjs'
 import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './signaling_config.mjs'
 
-/** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void }} NodeLogger */
+/** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void, info?: (...args: unknown[]) => void, log?: (...args: unknown[]) => void }} NodeLogger */
 
 /** @typedef {import('./signaling_config.mjs').SignalingRuntimeConfig} SignalingRuntimeConfig */
 
@@ -11,7 +11,7 @@ import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './
  * @typedef {{
  *   nodeDir: string
  *   entityStore: import('./entity_store.mjs').EntityStore
- *   logger: NodeLogger
+ *   logger: NodeLogger | null
  *   signaling: SignalingRuntimeConfig
  * }} NodeRuntime
  */
@@ -22,37 +22,28 @@ let runtime = null
 /** @type {Set<(event: string, payload?: unknown) => void>} */
 const changeListeners = new Set()
 
-/** @type {NodeLogger} */
-const noopLogger = {
-	/**
-	 *
-	 */
-	warn() { },
-	/**
-	 *
-	 */
-	error() { },
-}
-
 /**
- * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore, logger?: NodeLogger, signaling?: SignalingRuntimeConfig }} options 节点目录与可选注入
- * @returns {NodeRuntime} 单节点运行时句柄
+ * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore }} options - 节点目录与可选 entity store
+ * @returns {NodeRuntime} 初始化后的运行时
  */
 export function initNode(options) {
+	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or resetNodeForTests')
+	if (options?.logger !== undefined || options?.signaling !== undefined)
+		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
 	const nodeDir = path.resolve(String(options.nodeDir || '').trim())
 	if (!nodeDir) throw new Error('p2p: initNode requires nodeDir')
 	const entityStore = options.entityStore ?? createFsEntityStore(path.join(nodeDir, 'entities'))
 	runtime = {
 		nodeDir,
 		entityStore,
-		logger: options.logger ?? console,
-		signaling: options.signaling ?? resolveSignalingRuntimeConfig(),
+		logger: console,
+		signaling: resolveSignalingRuntimeConfig(),
 	}
 	return runtime
 }
 
 /**
- * @returns {NodeRuntime} 已初始化的节点运行时
+ * @returns {NodeRuntime} 当前节点运行时
  */
 export function getNode() {
 	if (!runtime) throw new Error('p2p: node not initialized — call initNode() first')
@@ -67,7 +58,26 @@ export function isNodeInitialized() {
 }
 
 /**
- * @returns {SignalingRuntimeConfig} 信令传输策略（未 init 时返回生产默认，不读测试 env）
+ * @param {NodeLogger | null} logger - 节点日志器，null 表示静默
+ * @returns {void}
+ */
+export function setNodeLogger(logger) {
+	if (!runtime) throw new Error('p2p: setNodeLogger requires initNode')
+	runtime.logger = logger ?? null
+}
+
+/**
+ * @param {Partial<SignalingRuntimeConfig>} config - signaling 运行时补丁
+ * @returns {void}
+ */
+export function setSignalingRuntimeConfig(config) {
+	if (!runtime) throw new Error('p2p: setSignalingRuntimeConfig requires initNode')
+	runtime.signaling = resolveSignalingRuntimeConfig({ ...runtime.signaling, ...config })
+	emitNodeChange('signaling-changed', runtime.signaling)
+}
+
+/**
+ * @returns {SignalingRuntimeConfig} 当前 signaling 配置
  */
 export function getSignalingRuntimeConfig() {
 	return runtime?.signaling ?? defaultSignalingRuntimeConfig()
@@ -81,22 +91,22 @@ export function getNodeDir() {
 }
 
 /**
- * @returns {import('./entity_store.mjs').EntityStore} 注入的 EntityStore
+ * @returns {import('./entity_store.mjs').EntityStore} 当前 entity store
  */
 export function getEntityStore() {
 	return getNode().entityStore
 }
 
 /**
- * @returns {NodeLogger} 节点日志器（未 init 时为 no-op）
+ * @returns {NodeLogger | null} 当前节点日志器
  */
 export function getNodeLogger() {
-	return runtime?.logger ?? noopLogger
+	return runtime?.logger ?? null
 }
 
 /**
- * @param {string} event 事件名
- * @param {unknown} [payload] 载荷
+ * @param {string} event - 变更事件名
+ * @param {unknown} [payload] - 事件载荷
  * @returns {void}
  */
 export function emitNodeChange(event, payload) {
@@ -106,10 +116,19 @@ export function emitNodeChange(event, payload) {
 }
 
 /**
- * @param {(event: string, payload?: unknown) => void} listener 回调
- * @returns {() => void} 取消订阅
+ * @param {(event: string, payload?: unknown) => void} listener - 变更回调
+ * @returns {() => void} 取消监听的 dispose
  */
 export function onNodeChange(listener) {
 	changeListeners.add(listener)
 	return () => changeListeners.delete(listener)
 }
+
+/**
+ * 测试专用：重置节点运行时。
+ * @returns {void}
+ */
+export function resetNodeForTests() {
+	runtime = null
+	changeListeners.clear()
+}

package/node/local_data_revision.mjs

@@ -0,0 +1,26 @@
+/** 本机落盘数据 revision：信任图等订阅方只读，store 不反向依赖 trust_graph。 */
+
+let revision = 0
+
+/**
+ * 本机数据 revision +1（信任图等订阅方）。
+ * @returns {void}
+ */
+export function bumpLocalDataRevision() {
+	revision++
+}
+
+/**
+ * @returns {number} 当前本机数据 revision
+ */
+export function getLocalDataRevision() {
+	return revision
+}
+
+/**
+ * 测试用：清零 revision。
+ * @returns {void}
+ */
+export function resetLocalDataRevisionForTests() {
+	revision = 0
+}

package/node/log.mjs

@@ -0,0 +1,56 @@
+import { getNodeLogger } from './instance.mjs'
+
+/**
+ * 连接/发现诊断日志开关。
+ * CLI（非 --quiet）默认打开；非 CLI 用 `setConnectivityDebug(true)`。
+ * @type {boolean}
+ */
+let connectivityDebug = false
+
+/**
+ * @param {boolean} enabled 是否输出连接诊断
+ * @returns {void}
+ */
+export function setConnectivityDebug(enabled) {
+	connectivityDebug = !!enabled
+}
+
+/**
+ * @returns {boolean} 当前是否输出连接诊断
+ */
+export function isConnectivityDebug() {
+	return connectivityDebug
+}
+
+/**
+ * 缩短 nodeHash 便于对照两边日志。
+ * @param {string | null | undefined} hash 完整 hash
+ * @param {number} [n=8] 前缀长度
+ * @returns {string} 短 hash
+ */
+export function shortHash(hash, n = 8) {
+	const value = String(hash || '')
+	return value.length <= n ? value : value.slice(0, n)
+}
+
+/**
+ * 连接诊断 info（未开启或无 logger 时静默）。
+ * @param {string} message 消息
+ * @param {object} [extra] 附加字段
+ * @returns {void}
+ */
+export function nodeDebug(message, extra) {
+	if (!connectivityDebug) return
+	const logger = getNodeLogger()
+	if (!logger?.info) return
+	if (extra === undefined) logger.info(message)
+	else logger.info(message, extra)
+}
+
+/**
+ * 测试专用：关掉连接诊断。
+ * @returns {void}
+ */
+export function resetConnectivityDebugForTests() {
+	connectivityDebug = false
+}

package/node/network.mjs

@@ -1,9 +1,9 @@
 import { isEntityHash128 } from '../core/entity_id.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
-import { invalidateTrustGraphCache } from '../trust_graph/cache.mjs'
 
 import { loadDenylist } from './denylist.mjs'
 import { getNodeDir, isNodeInitialized } from './instance.mjs'
+import { bumpLocalDataRevision } from './local_data_revision.mjs'
 import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
 
 
@@ -28,6 +28,7 @@ import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
 
 const DATA_NAME = 'network'
 const MAX_EXPLORE = 500
+const MAX_TRUSTED = 64
 const MAX_HINTS = 256
 const MAX_HINTS_PER_SOURCE = 12
 const DEFAULT_EXPLORE_TTL_MS = 7 * 24 * 60 * 60 * 1000
@@ -52,18 +53,18 @@ export function normalizeNetwork(raw) {
 	 * @returns {string[]} 去重 nodeHash 列表
 	 */
 	const pickIds = key => [...new Set(
-		(Array.isArray(file[key]) ? file[key] : [])
-			.map(id => normalizeHex64(id) || String(id).trim())
+		(file[key] || [])
+			.map(id => normalizeHex64(id) || id.trim())
 			.filter(id => isHex64(id)),
 	)]
-	const hints = (Array.isArray(file.hints) ? file.hints : [])
+	const hints = (file.hints || [])
 		.map(hint => ({
-			nodeHash: normalizeHex64(hint?.nodeHash) || '',
-			source: String(hint?.source || '').trim(),
-			kind: String(hint?.kind || '').trim(),
-			weight: Number.isFinite(Number(hint?.weight)) ? Number(hint.weight) : 0.1,
-			expiresAt: Number(hint?.expiresAt) || 0,
-			...hint?.groupId ? { groupId: String(hint.groupId).trim() } : {},
+			nodeHash: normalizeHex64(hint.nodeHash) || '',
+			source: hint.source?.trim() || '',
+			kind: hint.kind?.trim() || '',
+			weight: Number.isFinite(Number(hint.weight)) ? Number(hint.weight) : 0.1,
+			expiresAt: Number(hint.expiresAt) || 0,
+			...hint.groupId ? { groupId: hint.groupId.trim() } : {},
 		}))
 		.filter(hint => isHex64(hint.nodeHash))
 	return {
@@ -97,10 +98,10 @@ export function capHintsBySource(hints, maxPerSource = MAX_HINTS_PER_SOURCE) {
 	const counts = new Map()
 	const out = []
 	for (const hint of [...hints].reverse()) {
-		const src = String(hint.source || 'unknown')
-		const n = counts.get(src) ?? 0
+		const source = String(hint.source || 'unknown')
+		const n = counts.get(source) ?? 0
 		if (n >= maxPerSource) continue
-		counts.set(src, n + 1)
+		counts.set(source, n + 1)
 		out.unshift(hint)
 	}
 	return out
@@ -115,10 +116,11 @@ export function saveNetwork(data) {
 	const now = Date.now()
 	clean.hints = capHintsBySource(clean.hints.filter(h => !h.expiresAt || h.expiresAt > now)).slice(-MAX_HINTS)
 	clean.explorePeers = clean.explorePeers.slice(-MAX_EXPLORE)
+	clean.trustedPeers = clean.trustedPeers.slice(-MAX_TRUSTED)
 	writeNodeJsonSync(DATA_NAME, clean)
 	networkCache = clean
 	networkCacheNodeDir = isNodeInitialized() ? getNodeDir() : ''
-	invalidateTrustGraphCache()
+	bumpLocalDataRevision()
 }
 
 /**
@@ -196,6 +198,36 @@ export function mergeNetworkPeerPools(patch = {}) {
 	saveNetwork(net)
 }
 
+/**
+ * 稳定探索对端升入熟人池（从 explore 移除并追加 trusted）。
+ * @param {string} nodeHash 对端 nodeHash
+ * @returns {void}
+ */
+export function promoteExplorePeer(nodeHash) {
+	const net = loadNetwork()
+	const id = normalizeHex64(nodeHash)
+	if (!isHex64(id)) return
+	net.explorePeers = net.explorePeers.filter(peer => peer !== id)
+	if (!net.trustedPeers.includes(id)) net.trustedPeers.push(id)
+	net.lastRosterAt = Date.now()
+	saveNetwork(net)
+}
+
+/**
+ * 整表替换 trusted/explore 池（可缩池）。
+ * @param {{ trustedPeers?: string[], explorePeers?: string[] }} pools - 要替换的 peer 池
+ * @returns {void}
+ */
+export function replaceNetworkPeerPools(pools = {}) {
+	const net = loadNetwork()
+	if (Array.isArray(pools.trustedPeers))
+		net.trustedPeers = pools.trustedPeers.map(id => normalizeHex64(id)).filter(id => isHex64(id))
+	if (Array.isArray(pools.explorePeers))
+		net.explorePeers = pools.explorePeers.map(id => normalizeHex64(id)).filter(id => isHex64(id))
+	net.lastRosterAt = Date.now()
+	saveNetwork(net)
+}
+
 /**
  * @param {string} groupId 群 scope
  * @param {'node' | 'subject' | 'entity'} scope denylist 作用域

package/node/reputation_store.mjs

@@ -18,10 +18,10 @@ import {
 } from '../reputation/engine.mjs'
 import { pickNodeScoreFromReputation } from '../reputation/pick_score.mjs'
 import reputationTunables from '../reputation/tunables.json' with { type: 'json' }
-import { invalidateTrustGraphCache } from '../trust_graph/cache.mjs'
 import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
 import { getNodeDir, getNodeLogger, isNodeInitialized } from './instance.mjs'
+import { bumpLocalDataRevision } from './local_data_revision.mjs'
 import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
 
 const DATA_NAME = 'reputation'
@@ -88,7 +88,7 @@ export function saveReputation(data) {
 	pruneReputationFile(data)
 	writeNodeJsonSync(DATA_NAME, data)
 	reputationCache = data
-	invalidateTrustGraphCache()
+	bumpLocalDataRevision()
 }
 
 /**
@@ -211,7 +211,7 @@ export async function applyVolatileSlashAlert(alert) {
  * @param {object} [groupSettings] 群设置
  * @returns {object} VOLATILE 载荷
  */
-export function buildAndApplyUnverifiedSlashAlert(senderPubKeyHash, content, groupSettings = {}) {
+export function buildUnverifiedSlashAlert(senderPubKeyHash, content, groupSettings = {}) {
 	const targetPubKeyHash = assertHex64(content.targetPubKeyHash, 'slash target')
 	const claim = Number.isFinite(Number(content.claim)) ? Number(content.claim) : reputationTunables.slashDefaultClaim
 	const sender = assertHex64(senderPubKeyHash, 'slash sender')
@@ -268,7 +268,7 @@ export function applyDecayCollusionAfterSlash(targetPubKeyHash, inviteEdges) {
 	void mutateReputation(data => {
 		const applied = applyDecayCollusionAfterSlashPure(data, targetPubKeyHash, inviteEdges)
 		if (applied.length)
-			getNodeLogger().warn?.('reputation: collusion decay after slash', {
+			getNodeLogger()?.warn?.('reputation: collusion decay after slash', {
 				target: targetPubKeyHash.trim().toLowerCase(),
 				upstreamCount: applied.length,
 				hops: applied.map(row => row.hop),