@steve02081504/fount-p2p 0.0.5 → 0.0.7

package/rooms/scoped_link.mjs

@@ -1,5 +1,6 @@
+import { noteAdvertPeerHints } from '../discovery/advert_peer_hints.mjs'
 import { advertiseTopic, subscribeTopic } from '../discovery/index.mjs'
-import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
+import { verifySignedAdvert } from '../link/handshake.mjs'
 import {
 	groupRendezvousTopic,
 	decryptSignalPacket,
@@ -9,17 +10,17 @@ import {
 
 /**
  * 在指定 scope 与 roomSecret 下创建 link 层房间（discovery + registry 转发）。
- * @param {object} opts 房间选项
- * @param {string} opts.scope link registry scope（如 `group:{id}`）
- * @param {string} opts.roomSecret 房间 rendezvous 密钥
- * @param {(nodeHash: string) => boolean} [opts.allowNode] 是否允许与某 nodeHash 通信
- * @returns {{ start: () => Promise<void>, leave: () => Promise<void>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true> }} 房间句柄
+ * @param {object} options 房间选项
+ * @param {string} options.scope link registry scope（如 `group:{id}`）
+ * @param {string} options.roomSecret 房间 rendezvous 密钥
+ * @param {(nodeHash: string) => boolean} [options.allowNode] 是否允许与某 nodeHash 通信
+ * @returns {{ start: () => Promise<void>, leave: () => Promise<void>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], onPeerJoin: (callback: (peerId: string) => void) => () => void, onPeerLeave: (callback: (peerId: string) => void) => () => void, getPeers: () => Record<string, true> }} 房间句柄
  */
-export function createScopedLinkRoom(opts) {
+export function createScopedLinkRoom(options) {
 	const registry = getLinkRegistry()
-	const scope = String(opts.scope)
-	const topic = groupRendezvousTopic(opts.roomSecret)
-	const allowNode = typeof opts.allowNode === 'function' ? opts.allowNode : () => true
+	const scope = String(options.scope)
+	const topic = groupRendezvousTopic(options.roomSecret)
+	const allowNode = typeof options.allowNode === 'function' ? options.allowNode : () => true
 	/** @type {Set<string>} */
 	const discoveredPeers = new Set()
 	/** @type {Set<string>} */
@@ -102,18 +103,19 @@ export function createScopedLinkRoom(opts) {
 				if (!discoveredPeers.has(nodeHash)) return
 				notePeerLeave(nodeHash)
 			}))
-			cleanups.add(await subscribeTopic(topic, async bytes => {
+			cleanups.add(await subscribeTopic(topic, async (bytes, meta) => {
 				const packet = decryptSignalPacket(topic, bytes)
 				if (packet?.type !== 'advert' || !packet.body) return
 				const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
 				if (!verifiedNodeHash || !allowNode(verifiedNodeHash)) return
+				noteAdvertPeerHints(verifiedNodeHash, packet.body, meta)
 				discoveredPeers.add(verifiedNodeHash)
 				await registry.ensureLinkToNode(verifiedNodeHash).catch(() => null)
 				if (registry.getLink(verifiedNodeHash)) notePeerJoin(verifiedNodeHash)
 			}))
 			cleanups.add(await advertiseTopic(topic, encryptSignalPacket(topic, {
 				type: 'advert',
-				body: await buildSignedAdvert(topic, Date.now(), registry.localIdentity),
+				body: await registry.buildLocalAdvert(topic),
 			})))
 			for (const peerId of activePeerIds())
 				notePeerJoin(peerId)
@@ -156,24 +158,24 @@ export function createScopedLinkRoom(opts) {
 			]
 		},
 		/**
-		 * @param {(peerId: string) => void} cb 新 peer 上线回调
+		 * @param {(peerId: string) => void} callback 新 peer 上线回调
 		 * @returns {() => void} 取消订阅
 		 */
-		onPeerJoin(cb) {
-			joinListeners.add(cb)
+		onPeerJoin(callback) {
+			joinListeners.add(callback)
 			for (const peerId of activePeerIds())
 				announcedPeers.add(peerId)
 			for (const peerId of announcedPeers)
-				try { cb(peerId) } catch { /* ignore */ }
-			return () => joinListeners.delete(cb)
+				try { callback(peerId) } catch { /* ignore */ }
+			return () => joinListeners.delete(callback)
 		},
 		/**
-		 * @param {(peerId: string) => void} cb peer 离线回调
+		 * @param {(peerId: string) => void} callback peer 离线回调
 		 * @returns {() => void} 取消订阅
 		 */
-		onPeerLeave(cb) {
-			leaveListeners.add(cb)
-			return () => leaveListeners.delete(cb)
+		onPeerLeave(callback) {
+			leaveListeners.add(callback)
+			return () => leaveListeners.delete(callback)
 		},
 		/**
 		 * @returns {Record<string, true>} 当前活跃 peer 的 nodeHash 集合

package/timeline/append_core.mjs

@@ -14,17 +14,17 @@ import { computeDagTipIdsFromEvents } from '../governance/branch.mjs'
  * 为追加事件计算 HLC 与 DAG 前驱（chat 群与 social 时间线共用）。
  * @param {object[]} previous 已有事件
  * @param {object} event 待追加事件
- * @param {{ multiTip?: boolean }} [opts] chat 在多 tip 时连接全部 tip
+ * @param {{ multiTip?: boolean }} [options] chat 在多 tip 时连接全部 tip
  * @returns {{ hlc: object, prev_event_ids: string[], last: object | undefined }} HLC、前驱与末条事件
  */
-export function computeAppendHlcAndPrev(previous, event, opts = {}) {
+export function computeAppendHlcAndPrev(previous, event, options = {}) {
 	const last = previous[previous.length - 1]
 	const hlc = nextHlc(last?.hlc, event.timestamp ?? Date.now())
 	const tips = computeDagTipIdsFromEvents(previous)
 	let prev_event_ids
 	if (event.prev_event_ids?.length)
 		prev_event_ids = sortedPrevEventIds(event.prev_event_ids)
-	else if (opts.multiTip && tips.length > 1)
+	else if (options.multiTip && tips.length > 1)
 		prev_event_ids = sortedPrevEventIds(tips)
 	else if (tips.length)
 		prev_event_ids = sortedPrevEventIds(tips)

package/transport/group_link_set.mjs

@@ -1,5 +1,6 @@
+import { noteAdvertPeerHints } from '../discovery/advert_peer_hints.mjs'
 import { advertiseTopic, subscribeTopic } from '../discovery/index.mjs'
-import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
+import { verifySignedAdvert } from '../link/handshake.mjs'
 import { loadPeerPoolView } from '../node/network.mjs'
 import { loadReputation } from '../node/reputation_store.mjs'
 
@@ -14,22 +15,22 @@ import { resolveFederationPoolLimits, selectLinkTargetsFromMembers } from './pee
 
 /**
  * 创建基于 link registry 的群组联邦房间。
- * @param {object} opts 选项
- * @param {string} opts.groupId 群组 id
- * @param {string} opts.roomSecret 房间密钥（用于 rendezvous topic）
- * @param {string[]} opts.members 初始成员 nodeHash 列表
- * @param {object} [opts.groupSettings] 群设置（连接预算：trustedPeerSlots/explorePeerSlots/maxPeers 等）
- * @returns {{ groupId: string, scope: string, start: () => Promise<void>, leave: () => Promise<void>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>, send: (actionName: string, payload: unknown, peerId?: string | null) => Promise<number>, onEnvelope: (cb: (senderNodeHash: string, envelope: object) => void) => () => void, onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], registerCleanup: (fn: () => void) => void, isActive: () => boolean }} 群组 link set 接口
+ * @param {object} options 选项
+ * @param {string} options.groupId 群组 id
+ * @param {string} options.roomSecret 房间密钥（用于 rendezvous topic）
+ * @param {string[]} options.members 初始成员 nodeHash 列表
+ * @param {object} [options.groupSettings] 群设置（连接预算：trustedPeerSlots/explorePeerSlots/maxPeers 等）
+ * @returns {{ groupId: string, scope: string, start: () => Promise<void>, leave: () => Promise<void>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>, send: (actionName: string, payload: unknown, peerId?: string | null) => Promise<number>, onEnvelope: (callback: (senderNodeHash: string, envelope: object) => void) => () => void, onPeerJoin: (callback: (peerId: string) => void) => () => void, onPeerLeave: (callback: (peerId: string) => void) => () => void, getPeers: () => Record<string, true>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], registerCleanup: (cleanup: () => void) => void, isActive: () => boolean }} 群组 link set 接口
  */
-export function createGroupLinkSet(opts) {
-	const registry = opts.registry ?? getLinkRegistry()
-	const autoconnect = opts.autoconnect !== false
-	const groupId = String(opts.groupId)
+export function createGroupLinkSet(options) {
+	const registry = options.registry ?? getLinkRegistry()
+	const autoconnect = options.autoconnect !== false
+	const groupId = String(options.groupId)
 	const scope = `group:${groupId}`
-	const topic = groupRendezvousTopic(opts.roomSecret)
-	const members = new Set((Array.isArray(opts.members) ? opts.members : []).map(String))
+	const topic = groupRendezvousTopic(options.roomSecret)
+	const members = new Set((Array.isArray(options.members) ? options.members : []).map(String))
 	const selfNodeHash = registry.localIdentity.nodeHash
-	const groupSettings = opts.groupSettings ?? {}
+	const groupSettings = options.groupSettings ?? {}
 	// 初始成员是调用方明确知道的引导集合（如 introducer/creator/seed），作为必连锚点保证引导期连通。
 	const initialAnchors = new Set(members)
 	/** @type {ReturnType<typeof setTimeout> | null} */
@@ -50,12 +51,12 @@ export function createGroupLinkSet(opts) {
 
 	/**
 	 * 注册 leave 时执行的清理回调。
-	 * @param {() => void} fn 清理函数
+	 * @param {() => void} cleanup 清理函数
 	 * @returns {void}
 	 */
-	function registerCleanup(fn) {
-		if (typeof fn !== 'function') return
-		cleanups.add(fn)
+	function registerCleanup(cleanup) {
+		if (typeof cleanup !== 'function') return
+		cleanups.add(cleanup)
 	}
 
 	/**
@@ -186,17 +187,18 @@ export function createGroupLinkSet(opts) {
 			if (!members.has(nodeHash) || nodeHash === selfNodeHash) return
 			notePeerLeave(nodeHash)
 		}))
-		registerCleanup(await subscribeTopic(topic, async bytes => {
+		registerCleanup(await subscribeTopic(topic, async (bytes, meta) => {
 			const packet = decryptSignalPacket(topic, bytes)
 			if (packet?.type !== 'advert' || !packet.body) return
 			const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
 			if (!verifiedNodeHash || verifiedNodeHash === selfNodeHash) return
+			noteAdvertPeerHints(verifiedNodeHash, packet.body, meta)
 			// 发现新成员：并入成员集并去抖重算稀疏建链目标（notePeerCandidate 内部会 scheduleDial）。
 			notePeerCandidate(verifiedNodeHash)
 		}))
 		registerCleanup(await advertiseTopic(topic, encryptSignalPacket(topic, {
 			type: 'advert',
-			body: await buildSignedAdvert(topic, Date.now(), registry.localIdentity),
+			body: await registry.buildLocalAdvert(topic),
 		})))
 		if (autoconnect) selectAndDial()
 		for (const { peerId } of activeRoster())
@@ -255,34 +257,34 @@ export function createGroupLinkSet(opts) {
 		},
 		/**
 		 * 订阅入站 envelope。
-		 * @param {(senderNodeHash: string, envelope: object) => void} cb 回调
+		 * @param {(senderNodeHash: string, envelope: object) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onEnvelope(cb) {
-			envelopeListeners.add(cb)
-			return () => envelopeListeners.delete(cb)
+		onEnvelope(callback) {
+			envelopeListeners.add(callback)
+			return () => envelopeListeners.delete(callback)
 		},
 		/**
 		 * 订阅 peer 加入事件（含当前已在线 peer 的即时回调）。
-		 * @param {(peerId: string) => void} cb 回调
+		 * @param {(peerId: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onPeerJoin(cb) {
-			peerJoinListeners.add(cb)
+		onPeerJoin(callback) {
+			peerJoinListeners.add(callback)
 			for (const { peerId } of activeRoster())
 				if (peerId) announcedPeers.add(peerId)
 			for (const peerId of announcedPeers)
-				try { cb(peerId) } catch { /* ignore */ }
-			return () => peerJoinListeners.delete(cb)
+				try { callback(peerId) } catch { /* ignore */ }
+			return () => peerJoinListeners.delete(callback)
 		},
 		/**
 		 * 订阅 peer 离开事件。
-		 * @param {(peerId: string) => void} cb 回调
+		 * @param {(peerId: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onPeerLeave(cb) {
-			peerLeaveListeners.add(cb)
-			return () => peerLeaveListeners.delete(cb)
+		onPeerLeave(callback) {
+			peerLeaveListeners.add(callback)
+			return () => peerLeaveListeners.delete(callback)
 		},
 		/**
 		 * 返回当前在线 peer 的 Record 映射。