@steve02081504/fount-p2p 0.0.12 → 0.0.14

package/discovery/lan.mjs

@@ -0,0 +1,279 @@
+import { Buffer } from 'node:buffer'
+import dgram from 'node:dgram'
+
+import { base64ToBytes, bytesToBase64 } from '../core/bytes_codec.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
+
+import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
+import { ingestNetworkAdvert } from './adverts.mjs'
+import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
+import { getLanPeerHint } from './lan_peer_hints.mjs'
+
+const DEFAULT_PORT = 53531
+const DEFAULT_GROUP = '239.255.42.99'
+const BEACON_INTERVAL_MS = 30_000
+
+/** @type {Map<string, number>} nodeHash → lastSeenAt */
+const visibleByHash = new Map()
+
+/**
+ * 记入 LAN 可见池。
+ * @param {string} nodeHash 节点 hash
+ * @param {number} [now=Date.now()] 当前时间
+ * @returns {void}
+ */
+export function noteLanVisibleNode(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!isHex64(hash)) return
+	visibleByHash.set(hash, now)
+}
+
+/**
+ * 列出未过期的 LAN 可见 nodeHash。
+ * @param {number} [now=Date.now()] 当前时间
+ * @param {number} [ttlMs=BEACON_INTERVAL_MS * 3] TTL
+ * @returns {string[]} 可见 nodeHash 列表
+ */
+export function listLanVisibleNodeHashes(now = Date.now(), ttlMs = BEACON_INTERVAL_MS * 3) {
+	/** @type {string[]} */
+	const out = []
+	for (const [hash, seenAt] of visibleByHash)
+		if (now - seenAt <= ttlMs) out.push(hash)
+		else visibleByHash.delete(hash)
+
+	return out
+}
+
+/** @returns {void} 测试用 */
+export function clearLanVisibleNodes() {
+	visibleByHash.clear()
+}
+
+/**
+ * Untrusted ingress：验签 network advert 后写入可见池 / peer hint。
+ * @param {Uint8Array} advertBytes 加密 network advert
+ * @param {{ address?: string, skipNodeHash?: string }} [meta] 发送方地址 / 本机 nodeHash（过滤自回环）
+ * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签结果
+ */
+export async function acceptLanPresenceAdvert(advertBytes, meta = {}) {
+	if (!advertBytes?.byteLength) return null
+	const ingested = await ingestNetworkAdvert(advertBytes, meta)
+	if (!ingested) return null
+	const skipHash = meta.skipNodeHash ? normalizeHex64(meta.skipNodeHash) : null
+	if (skipHash && ingested.verifiedNodeHash === skipHash) return ingested
+	const firstSeen = !visibleByHash.has(ingested.verifiedNodeHash)
+	noteLanVisibleNode(ingested.verifiedNodeHash)
+	noteAdvertPeerHints(ingested.verifiedNodeHash, ingested.body, meta)
+	if (firstSeen) {
+		const host = String(meta.address || '').trim()
+		nodeDebug('p2p:lan peer visible', {
+			peer: shortHash(ingested.verifiedNodeHash),
+			host: host || undefined,
+			tcpPort: ingested.body?.tcpPort,
+		})
+	}
+	return ingested
+}
+
+/**
+ * LAN UDP presence：段内 beacon，非 topic 订阅模型。
+ * @param {{ port?: number, group?: string }} [options] 配置
+ * @returns {import('./index.mjs').DiscoveryProvider} LAN 发现提供者
+ */
+export function createLanDiscoveryProvider(options = {}) {
+	const port = Number(options.port) || DEFAULT_PORT
+	const group = String(options.group || DEFAULT_GROUP)
+	/** @type {import('node:dgram').Socket | null} */
+	let socket = null
+	let bound = false
+	let bindPromise = null
+	let refs = 0
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let beaconTimer = null
+	/** @type {string | null} */
+	let selfNodeHash = null
+	/** @type {Set<string>} */
+	const joinedAddresses = new Set()
+
+	/**
+	 * @param {import('node:dgram').Socket} sock UDP socket
+	 * @returns {void}
+	 */
+	function ensureMemberships(sock) {
+		for (const addr of listMulticastIpv4Addresses()) {
+			if (joinedAddresses.has(addr)) continue
+			try {
+				sock.addMembership(group, addr)
+				joinedAddresses.add(addr)
+			}
+			catch { /* ignore per-interface join failure */ }
+		}
+		if (!joinedAddresses.size)
+			try { sock.addMembership(group) } catch { /* ignore */ }
+	}
+	function getSocket() {
+		return socket ||= dgram.createSocket({ type: 'udp4', reuseAddr: true })
+	}
+
+	/**
+	 * @returns {Promise<void>}
+	 */
+	async function ensureBound() {
+		if (bound) return
+		if (!bindPromise)
+			bindPromise = (async () => {
+				const sock = getSocket()
+				await new Promise((resolve, reject) => {
+					sock.once('error', reject)
+					sock.bind(port, '0.0.0.0', () => {
+						sock.off('error', reject)
+						ensureMemberships(sock)
+						sock.setMulticastTTL(1)
+						resolve()
+					})
+				})
+				if (refs <= 0) {
+					try { sock.close() } catch { /* ignore */ }
+					if (socket === sock) socket = null
+					bound = false
+					joinedAddresses.clear()
+					return
+				}
+				sock.on('message', (raw, rinfo) => {
+					let packet
+					try { packet = JSON.parse(String(raw)) } catch { return }
+					if (packet?.type !== 'presence') return
+					let advertBytes
+					try {
+						advertBytes = packet.advertBytes
+							? base64ToBytes(packet.advertBytes)
+							: null
+					}
+					catch { return }
+					if (!advertBytes?.byteLength) return
+					void acceptLanPresenceAdvert(advertBytes, {
+						address: rinfo?.address,
+						provider: 'lan',
+						skipNodeHash: selfNodeHash || undefined,
+					}).catch(() => { })
+				})
+				bound = true
+			})().finally(() => {
+				if (!bound) bindPromise = null
+			})
+		await bindPromise
+	}
+
+	/**
+	 * @param {object} beacon beacon 载荷
+	 * @returns {Promise<void>}
+	 */
+	async function multicastBeacon(beacon) {
+		await ensureBound()
+		const sock = getSocket()
+		ensureMemberships(sock)
+		const packet = Buffer.from(JSON.stringify({ type: 'presence', ...beacon }))
+		const addrs = listMulticastIpv4Addresses()
+		/**
+		 * @param {string | undefined} ifaceAddr 组播出口地址
+		 * @returns {Promise<void>}
+		 */
+		const sendOnce = ifaceAddr => new Promise((resolve, reject) => {
+			if (ifaceAddr) sock.setMulticastInterface(ifaceAddr)
+			sock.send(packet, port, group, error => error ? reject(error) : resolve())
+		})
+		if (!addrs.length) {
+			await sendOnce()
+			return
+		}
+		let sent = 0
+		/** @type {unknown} */
+		let lastError = null
+		for (const addr of addrs) {
+			try {
+				await sendOnce(addr)
+				sent++
+			}
+			catch (error) {
+				lastError = error
+			}
+		}
+		if (!sent) throw lastError || new Error('p2p: lan multicast send failed')
+	}
+
+	/**
+	 * @returns {() => void} 释放引用；引用归零时关闭 socket
+	 */
+	function acquire() {
+		refs++
+		void ensureBound().catch(() => { })
+		return () => {
+			refs = Math.max(0, refs - 1)
+			if (refs > 0 || !socket) return
+			if (beaconTimer) { clearInterval(beaconTimer); beaconTimer = null }
+			selfNodeHash = null
+			joinedAddresses.clear()
+			try { socket.close() } catch { /* ignore */ }
+			socket = null
+			bound = false
+			bindPromise = null
+		}
+	}
+
+	return {
+		id: 'lan',
+		priority: 10,
+		caps: { canDiscover: true, canSignal: false, canRelay: false },
+		/**
+		 * @param {{ limit?: number, roomSecret?: string }} [options] 扫描选项
+		 * @returns {Promise<string[]>} 可见 nodeHash；群扫描时 LAN 无群语义，返回空
+		 */
+		async listVisibleNodeHashes(options = {}) {
+			if (options.roomSecret) return []
+			const limit = Math.max(1, Number(options.limit) || 64)
+			await ensureBound().catch(() => { })
+			return listLanVisibleNodeHashes().slice(0, limit)
+		},
+		/**
+		 * 有 LAN peer hint 则可经 lan_tcp 拨号（门面 dialer 完成建链）。
+		 * @param {string} nodeHash 目标
+		 * @returns {Promise<boolean>} 存在 peer hint 时为 true
+		 */
+		async connectToNode(nodeHash) {
+			const hash = normalizeHex64(nodeHash)
+			return isHex64(hash) && !!getLanPeerHint(hash)
+		},
+		/**
+		 * @param {() => Promise<{ nodeHash?: string, tcpPort?: number, advertBytes?: Uint8Array, advertBody?: object } | null>} getBeacon 本机 beacon
+		 * @returns {Promise<() => void>} 停止函数
+		 */
+		async startPresence(getBeacon) {
+			const release = acquire()
+			/**
+			 * @returns {Promise<void>}
+			 */
+			const send = async () => {
+				const body = await getBeacon?.()
+				if (!body) return
+				if (body.nodeHash) selfNodeHash = normalizeHex64(body.nodeHash)
+				const advertBytes = body.advertBytes?.byteLength
+					? body.advertBytes
+					: null
+				if (!advertBytes?.byteLength) return
+				await multicastBeacon({
+					nodeHash: body.nodeHash,
+					tcpPort: body.tcpPort,
+					advertBytes: bytesToBase64(advertBytes),
+				})
+			}
+			void send().catch(() => { })
+			beaconTimer = setInterval(() => { void send().catch(() => { }) }, BEACON_INTERVAL_MS)
+			beaconTimer.unref?.()
+			return () => {
+				if (beaconTimer) { clearInterval(beaconTimer); beaconTimer = null }
+				release()
+			}
+		},
+	}
+}

package/discovery/lan_interfaces.mjs

@@ -0,0 +1,78 @@
+import os from 'node:os'
+
+/** advert / 组播 beacon 携带的 LAN IPv4 上限 */
+export const MAX_LAN_HOSTS = 4
+
+const IPV4_RE = /^(?:\d{1,3}\.){3}\d{1,3}$/
+
+/**
+ * untrusted ingress：清洗 advert body 中的 LAN IPv4 列表。
+ * @param {unknown} input 原始 lanHosts
+ * @returns {string[]} 去重后的 IPv4 列表
+ */
+export function normalizeLanHosts(input) {
+	if (!input) return []
+	const arr = Array.isArray(input) ? input : [input]
+	const seen = new Set()
+	/** @type {string[]} */
+	const out = []
+	for (const item of arr) {
+		const host = String(item || '').trim()
+		if (!host || !IPV4_RE.test(host) || seen.has(host)) continue
+		seen.add(host)
+		out.push(host)
+		if (out.length >= MAX_LAN_HOSTS) break
+	}
+	return out
+}
+
+/**
+ * @param {string} addr IPv4
+ * @returns {number} 排序权重（越小越优先）
+ */
+function lanAddressRank(addr) {
+	if (addr.startsWith('169.254.')) return 100
+	if (addr.startsWith('192.168.56.')) return 90
+	if (addr.startsWith('192.168.')) return 10
+	if (addr.startsWith('10.')) return 20
+	const match = /^172\.(\d+)\./u.exec(addr)
+	if (match && Number(match[1]) >= 16 && Number(match[1]) <= 31) return 30
+	return 50
+}
+
+/**
+ * @param {string[]} addrs IPv4 列表
+ * @returns {string[]} 按 LAN 可达性优先排序
+ */
+function prioritizeLanAddresses(addrs) {
+	return [...addrs].sort((left, right) => lanAddressRank(left) - lanAddressRank(right))
+}
+
+/**
+ * @param {string | number} family os.networkInterfaces family
+ * @returns {boolean} 是否 IPv4
+ */
+function isIpv4Family(family) {
+	return family === 'IPv4' || family === 4
+}
+
+/**
+ * 本机可用于 LAN 组播 / advert 的非 internal IPv4 地址。
+ * @returns {string[]} 去重、排序后的地址列表
+ */
+export function listMulticastIpv4Addresses() {
+	const seen = new Set()
+	/** @type {string[]} */
+	const addrs = []
+	for (const ifaces of Object.values(os.networkInterfaces())) {
+		if (!ifaces) continue
+		for (const iface of ifaces) {
+			if (iface.internal || !isIpv4Family(iface.family)) continue
+			const addr = String(iface.address || '').trim()
+			if (!addr || seen.has(addr)) continue
+			seen.add(addr)
+			addrs.push(addr)
+		}
+	}
+	return prioritizeLanAddresses(addrs).slice(0, MAX_LAN_HOSTS)
+}

package/discovery/lan_peer_hints.mjs

@@ -5,11 +5,15 @@ import { createTtlMap } from '../utils/ttl_map.mjs'
 /** LAN peer hint 存活时间。 */
 export const LAN_PEER_HINT_TTL_MS = 5 * 60_000
 
-/** @type {ReturnType<typeof createTtlMap<{ host: string, port: number }>>} */
+/** 单 peer 保留的 endpoint 上限。 */
+const MAX_ENDPOINTS = 8
+
+/** @type {ReturnType<typeof createTtlMap<{ endpoints: { host: string, port: number }[] }>>} */
 const hints = createTtlMap(LAN_PEER_HINT_TTL_MS)
 
 /**
  * 记录 LAN 上观察到的 nodeHash → host:port。
+ * 最新写入排在最前（dial / getLanPeerHint 优先用新观测）。
  * @param {string} nodeHash 节点 64 hex
  * @param {{ host: string, port: number }} endpoint 端点
  * @returns {void}
@@ -19,19 +23,32 @@ export function noteLanPeerHint(nodeHash, endpoint) {
 	const host = String(endpoint?.host || '').trim()
 	const port = normalizeTcpPort(endpoint?.port)
 	if (!hash || !host || !port) return
-	hints.set(hash, { host, port })
+	const existing = hints.get(hash)?.endpoints ?? []
+	const next = existing.filter(item => !(item.host === host && item.port === port))
+	next.unshift({ host, port })
+	hints.set(hash, { endpoints: next.slice(0, MAX_ENDPOINTS) })
 }
 
 /**
- * 查询未过期的 LAN peer hint。
+ * 查询未过期的首个 LAN peer hint（最新观测）。
  * @param {string} nodeHash 节点 64 hex
  * @param {number} [now=Date.now()] 当前时间（测试可注入）
  * @returns {{ host: string, port: number } | null} hint 或 null
  */
 export function getLanPeerHint(nodeHash, now = Date.now()) {
+	return listLanPeerHints(nodeHash, now)[0] ?? null
+}
+
+/**
+ * 查询未过期的全部 LAN peer hint（最新在前）。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ host: string, port: number }[]} hint 列表
+ */
+export function listLanPeerHints(nodeHash, now = Date.now()) {
 	const hash = normalizeHex64(nodeHash)
-	if (!hash) return null
-	return hints.get(hash, now)
+	if (!hash) return []
+	return hints.get(hash, now)?.endpoints ?? []
 }
 
 /**