@steve02081504/fount-p2p 0.0.6 → 0.0.8

package/core/tcp_port.mjs

@@ -0,0 +1,11 @@
+/**
+ * 规范化 TCP 端口（advert / peer hint 共用）。
+ * @param {unknown} port 原始端口
+ * @returns {number | null} 有效端口或 null（未提供 / 非法）
+ */
+export function normalizeTcpPort(port) {
+	if (port == null || port === '') return null
+	const value = Number(port)
+	if (!Number.isInteger(value) || value < 1 || value > 65535) return null
+	return value
+}

package/discovery/advert_peer_hints.mjs

@@ -0,0 +1,21 @@
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+
+import { noteBtPeerHint } from './bt/peer_hints.mjs'
+import { noteLanPeerHint } from './lan_peer_hints.mjs'
+
+/**
+ * 从已验证的 discovery advert + provider meta 写入 LAN/BT peer hints。
+ * 任意 discovery 路径（node / group / scoped topic）收到 advert 时都应调用。
+ * @param {string} verifiedNodeHash 验签通过的 nodeHash
+ * @param {{ tcpPort?: unknown } | null | undefined} body advert body
+ * @param {{ address?: unknown, peripheralId?: unknown } | null | undefined} meta discovery provider meta
+ * @returns {void}
+ */
+export function noteAdvertPeerHints(verifiedNodeHash, body, meta) {
+	if (meta?.peripheralId)
+		noteBtPeerHint(verifiedNodeHash, meta.peripheralId)
+	const tcpPort = normalizeTcpPort(body?.tcpPort)
+	const address = String(meta?.address || '').trim()
+	if (tcpPort != null && address)
+		noteLanPeerHint(verifiedNodeHash, { host: address, port: tcpPort })
+}

package/discovery/{bt.mjs → bt/index.mjs}

@@ -1,56 +1,19 @@
 import { Buffer } from 'node:buffer'
-import process from 'node:process'
+
+import { getBtPeerHint } from './peer_hints.mjs'
+import { loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
+
+/** 重导出 waitPoweredOn，供 discovery 调用方使用。 */
+export { waitPoweredOn } from './runtime.mjs'
 
 const BT_SERVICE_UUID = 'f017f017f017f017f017f017f017f017'
 const BT_CHARACTERISTIC_UUID = 'f017f017f017f017f017f017f017f018'
+const BT_SIGNAL_CHAR_UUID = 'f017f017f017f017f017f017f017f01b'
 const BT_DEVICE_NAME = 'fount-bt'
 const MAX_ADVERT_BLOB_BYTES = 12 * 1024
+const MAX_SIGNAL_BLOB_BYTES = 8 * 1024
 const PERIPHERAL_RESCAN_MS = 15_000
 
-/**
- * 解析 Bluetooth 发现角色（scan / dual）。
- * @returns {'scan' | 'dual'} 当前平台或环境变量指定的角色
- */
-function resolveBtRole() {
-	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
-	if (override === 'dual') return 'dual'
-	if (override === 'scan') return 'scan'
-	return process.platform === 'win32' ? 'scan' : 'dual'
-}
-
-/**
- * 加载 Noble BLE central 库。
- * @returns {Promise<any>} Noble 运行时实例
- */
-async function loadNoble() {
-	const mod = await import('@stoprocent/noble')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 加载 Bleno BLE peripheral 库。
- * @returns {Promise<any>} Bleno 运行时实例
- */
-async function loadBleno() {
-	const mod = await import('@stoprocent/bleno')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 等待 BLE 运行时进入 poweredOn（兼容 noble v1/v2 与 bleno）。
- * @param {*} runtime noble 或 bleno 实例
- * @param {number} [timeout] 超时毫秒
- * @returns {Promise<void>}
- */
-export async function waitPoweredOn(runtime, timeout) {
-	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
-	if (typeof wait !== 'function')
-		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
-	return wait.call(runtime, timeout)
-}
-
 /**
  * 探测本机 noble 运行时是否具备 BT 扫描所需 API。
  * @returns {Promise<boolean>} noble 可加载且具备 startScanningAsync 与 waitForPoweredOn(Async) 时为 true
@@ -125,6 +88,7 @@ function addListener(bucket, topic, listener) {
  * - 默认在 Windows 上只启用 scan 侧发现（单适配器 central+peripheral 常冲突）
  * - 其他平台默认 dual：advertise + scan
  * - 通过固定 BLE service + read characteristic 传输完整 advert 列表，避免 31-byte 广告包限制
+ * - dual 下额外暴露 write characteristic 传短信令；central 可按 peer hint 写信令
  *
  * @returns {import('./index.mjs').DiscoveryProvider} Bluetooth 发现提供者
  */
@@ -134,6 +98,8 @@ export function createBluetoothDiscoveryProvider() {
 	const adverts = new Map()
 	/** @type {Map<string, Set<Function>>} */
 	const advertListeners = new Map()
+	/** @type {Map<string, Set<Function>>} */
+	const signalListeners = new Map()
 	/** @type {Map<string, number>} */
 	const inspectedAt = new Map()
 	let nobleRuntime = null
@@ -149,17 +115,17 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return null
 		if (blenoRuntime) return blenoRuntime
 		const bleno = await loadBleno()
-		const characteristic = new bleno.Characteristic({
+		const advertCharacteristic = new bleno.Characteristic({
 			uuid: BT_CHARACTERISTIC_UUID,
 			properties: ['read'],
 			/**
-			 * BLE characteristic 读请求回调。
-			 * @param {*} _handle Bleno handle（未使用）
-			 * @param {number} offset 读取偏移
-			 * @param {Function} callback Bleno 结果回调
+			 * stoprocent/bleno onReadRequest(connection, offset, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {number} offset 偏移
+			 * @param {Function} callback 结果
 			 * @returns {void}
 			 */
-			onReadRequest(_handle, offset, callback) {
+			onReadRequest(_connection, offset, callback) {
 				try {
 					const blob = serializeAdvertBlob(adverts)
 					if (offset > blob.length) {
@@ -173,11 +139,39 @@ export function createBluetoothDiscoveryProvider() {
 				}
 			},
 		})
+		const signalCharacteristic = new bleno.Characteristic({
+			uuid: BT_SIGNAL_CHAR_UUID,
+			properties: ['write', 'writeWithoutResponse'],
+			/**
+			 * stoprocent/bleno onWriteRequest(connection, data, offset, withoutResponse, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {Buffer} data 信令 blob
+			 * @param {number} _offset 偏移
+			 * @param {boolean} _withoutResponse 无响应写
+			 * @param {Function} callback 结果
+			 * @returns {void}
+			 */
+			onWriteRequest(_connection, data, _offset, _withoutResponse, callback) {
+				try {
+					const parsed = JSON.parse(Buffer.from(data).toString('utf8'))
+					const topic = String(parsed?.topic || '')
+					const bytes = Uint8Array.from(Buffer.from(String(parsed?.data || ''), 'base64'))
+					if (topic && bytes.byteLength) 
+						for (const listener of signalListeners.get(topic) || [])
+							listener(bytes, { provider: 'bt' })
+					
+					callback(bleno.Characteristic.RESULT_SUCCESS)
+				}
+				catch {
+					callback(bleno.Characteristic.RESULT_UNLIKELY_ERROR)
+				}
+			},
+		})
 		await waitPoweredOn(bleno, 5_000)
 		await bleno.setServicesAsync([
 			new bleno.PrimaryService({
 				uuid: BT_SERVICE_UUID,
-				characteristics: [characteristic],
+				characteristics: [advertCharacteristic, signalCharacteristic],
 			}),
 		])
 		blenoRuntime = bleno
@@ -192,14 +186,14 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return
 		const bleno = await ensurePeripheralRuntime()
 		if (!bleno) return
-		if (!adverts.size) {
+		if (!adverts.size && !signalListeners.size) {
 			if (advertisingStarted) {
 				await bleno.stopAdvertisingAsync().catch(() => { })
 				advertisingStarted = false
 			}
 			return
 		}
-		serializeAdvertBlob(adverts)
+		if (adverts.size) serializeAdvertBlob(adverts)
 		if (!advertisingStarted) {
 			await bleno.startAdvertisingAsync(BT_DEVICE_NAME, [BT_SERVICE_UUID])
 			advertisingStarted = true
@@ -256,10 +250,94 @@ export function createBluetoothDiscoveryProvider() {
 		scanningStarted = true
 	}
 
+	/**
+	 * Central：按 peer hint 连接并对端 signal characteristic 写短包。
+	 * @param {string} topic 信令 topic
+	 * @param {string} to 目标 nodeHash
+	 * @param {Uint8Array} bytes 载荷
+	 * @returns {Promise<void>}
+	 */
+	async function sendSignalViaGatt(topic, to, bytes) {
+		const hint = getBtPeerHint(to)
+		if (!hint) throw new Error('p2p: bt signal missing peer hint')
+		const blob = Buffer.from(JSON.stringify({
+			topic: String(topic),
+			to: String(to),
+			data: Buffer.from(bytes).toString('base64'),
+		}), 'utf8')
+		if (blob.byteLength > MAX_SIGNAL_BLOB_BYTES)
+			throw new Error(`p2p: bt signal blob exceeds ${MAX_SIGNAL_BLOB_BYTES} bytes`)
+		await ensureScanRuntime()
+		const noble = nobleRuntime
+		const wantId = hint.peripheralId
+		/**
+		 * 先查 noble 已缓存的 peripheral，避免只等下一次 advertise 漏报。
+		 * @returns {*|null} 已缓存的 peripheral，未命中为 null
+		 */
+		function cachedPeripheral() {
+			const table = noble?._peripherals
+			if (!table || typeof table !== 'object') return null
+			for (const found of Object.values(table)) {
+				const id = String(found?.id || found?.address || '')
+				if (id === wantId) return found
+			}
+			return null
+		}
+		const peripheral = cachedPeripheral() ?? await new Promise((resolve, reject) => {
+			const deadline = setTimeout(() => {
+				cleanup()
+				reject(new Error('p2p: bt signal peripheral timeout'))
+			}, 8_000)
+			/**
+			 * @returns {void}
+			 */
+			function cleanup() {
+				clearTimeout(deadline)
+				noble.removeListener('discover', onDiscover)
+			}
+			/**
+			 * @param {*} found peripheral
+			 * @returns {void}
+			 */
+			function onDiscover(found) {
+				const id = String(found?.id || found?.address || '')
+				if (id !== wantId) return
+				cleanup()
+				resolve(found)
+			}
+			noble.on('discover', onDiscover)
+			const again = cachedPeripheral()
+			if (again) {
+				cleanup()
+				resolve(again)
+			}
+		})
+		try {
+			await peripheral.connectAsync()
+			const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
+				[BT_SERVICE_UUID],
+				[BT_SIGNAL_CHAR_UUID],
+			)
+			if (!characteristics?.length) throw new Error('p2p: bt signal characteristic missing')
+			await characteristics[0].writeAsync(blob, false)
+		}
+		finally {
+			try { await peripheral.disconnectAsync() } catch { /* ignore */ }
+		}
+	}
+
 	return {
 		id: 'bt',
 		priority: 20,
-		caps: { canDiscover: true, canSignal: false, canRelay: false },
+		caps: { canDiscover: true, canSignal: true, canRelay: false },
+		/**
+		 * 是否具备对该 peer 的 GATT 信令能力（需未过期 BT peer hint）。
+		 * @param {string} to 目标 nodeHash
+		 * @returns {boolean} 有 hint 则可尝试
+		 */
+		canSignalTo(to) {
+			return !!getBtPeerHint(to)
+		},
 		/**
 		 * 广播指定 topic 的 advert。
 		 * @param {string} topic advert 主题
@@ -285,5 +363,31 @@ export function createBluetoothDiscoveryProvider() {
 			await ensureScanRuntime()
 			return addListener(advertListeners, String(topic), onAdvert)
 		},
+		/**
+		 * 经 GATT 向近场 peer 发送信令。
+		 * @param {string} topic 信令 topic
+		 * @param {string} to 目标 nodeHash
+		 * @param {Uint8Array} bytes 载荷
+		 * @returns {Promise<void>}
+		 */
+		async sendSignal(topic, to, bytes) {
+			await sendSignalViaGatt(topic, to, bytes)
+		},
+		/**
+		 * 监听经本机 peripheral signal characteristic 写入的信令。
+		 * @param {string} topic 信令 topic
+		 * @param {Function} onSignal 回调
+		 * @returns {Promise<() => void>} 取消订阅
+		 */
+		async onSignal(topic, onSignal) {
+			if (role === 'scan') return () => { }
+			await ensurePeripheralRuntime()
+			await refreshAdvertising()
+			const stop = addListener(signalListeners, String(topic), onSignal)
+			return () => {
+				stop()
+				void refreshAdvertising().catch(() => { })
+			}
+		},
 	}
 }

package/discovery/bt/peer_hints.mjs

@@ -0,0 +1,41 @@
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { createTtlMap } from '../../utils/ttl_map.mjs'
+
+/** BT peer hint 存活时间。 */
+export const BT_PEER_HINT_TTL_MS = 5 * 60_000
+
+/** @type {ReturnType<typeof createTtlMap<{ peripheralId: string }>>} */
+const hints = createTtlMap(BT_PEER_HINT_TTL_MS)
+
+/**
+ * 记录近场 BT 扫描到的 nodeHash → peripheral 映射。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {string} peripheralId noble peripheral id / address
+ * @returns {void}
+ */
+export function noteBtPeerHint(nodeHash, peripheralId) {
+	const hash = normalizeHex64(nodeHash)
+	const id = String(peripheralId || '').trim()
+	if (!hash || !id) return
+	hints.set(hash, { peripheralId: id })
+}
+
+/**
+ * 查询未过期的 BT peer hint。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ peripheralId: string } | null} hint 或 null
+ */
+export function getBtPeerHint(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 BT peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearBtPeerHints() {
+	hints.clear()
+}

package/discovery/bt/runtime.mjs

@@ -0,0 +1,46 @@
+import process from 'node:process'
+
+/**
+ * 解析 Bluetooth 角色（scan / dual）。
+ * Win32 默认 scan（单适配器 central+peripheral 常冲突）；可用 FOUNT_BT_DISCOVERY_ROLE 覆盖。
+ * @returns {'scan' | 'dual'} 生效角色
+ */
+export function resolveBtRole() {
+	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
+	if (override === 'dual') return 'dual'
+	if (override === 'scan') return 'scan'
+	return process.platform === 'win32' ? 'scan' : 'dual'
+}
+
+/**
+ * 加载 Noble BLE central。
+ * @returns {Promise<any>} noble 运行时
+ */
+export async function loadNoble() {
+	const mod = await import('@stoprocent/noble')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 加载 Bleno BLE peripheral。
+ * @returns {Promise<any>} bleno 运行时
+ */
+export async function loadBleno() {
+	const mod = await import('@stoprocent/bleno')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 等待 BLE 运行时 poweredOn（兼容 noble/bleno v1/v2）。
+ * @param {*} runtime noble 或 bleno
+ * @param {number} [timeout] 超时毫秒
+ * @returns {Promise<void>}
+ */
+export async function waitPoweredOn(runtime, timeout) {
+	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
+	if (typeof wait !== 'function')
+		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
+	return wait.call(runtime, timeout)
+}

package/discovery/index.mjs

@@ -1,4 +1,4 @@
-/** @typedef {{ id: string, priority: number, caps: { canDiscover?: boolean, canSignal?: boolean, canRelay?: boolean }, advertise?: (topic: string, bytes: Uint8Array) => (() => void) | Promise<() => void>, subscribe?: (topic: string, onAdvert: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void>, sendSignal?: (topic: string, to: string, bytes: Uint8Array) => void | Promise<void>, onSignal?: (topic: string, onSignal: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void> }} DiscoveryProvider */
+/** @typedef {{ id: string, priority: number, caps: { canDiscover?: boolean, canSignal?: boolean, canRelay?: boolean }, advertise?: (topic: string, bytes: Uint8Array) => (() => void) | Promise<() => void>, subscribe?: (topic: string, onAdvert: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void>, canSignalTo?: (to: string) => boolean, sendSignal?: (topic: string, to: string, bytes: Uint8Array) => void | Promise<void>, onSignal?: (topic: string, onSignal: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void> }} DiscoveryProvider */
 
 /** @type {Map<string, DiscoveryProvider>} */
 const providers = new Map()
@@ -95,15 +95,14 @@ export async function sendSignal(topic, to, bytes) {
 	if (!capable.length) throw new Error('p2p: no discovery provider can signal')
 	let sent = false
 	let lastError = null
-	for (const provider of capable)
-		try {
-			await Promise.resolve(provider.sendSignal(topic, to, bytes))
-			sent = true
-		}
-		catch (error) {
-			lastError = error
-			console.warn(`p2p: discovery signal failed for ${provider.id}`, error)
-		}
+	for (const provider of capable) if (provider?.canSignalTo?.(to)) try {
+		await Promise.resolve(provider.sendSignal(topic, to, bytes))
+		sent = true
+	}
+	catch (error) {
+		lastError = error
+		console.warn(`p2p: discovery signal failed for ${provider.id}`, error)
+	}
 	if (!sent) throw lastError || new Error('p2p: no discovery provider delivered signal')
 }
 

package/discovery/lan_peer_hints.mjs

@@ -0,0 +1,43 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+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 }>>} */
+const hints = createTtlMap(LAN_PEER_HINT_TTL_MS)
+
+/**
+ * 记录 LAN 上观察到的 nodeHash → host:port。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {{ host: string, port: number }} endpoint 端点
+ * @returns {void}
+ */
+export function noteLanPeerHint(nodeHash, endpoint) {
+	const hash = normalizeHex64(nodeHash)
+	const host = String(endpoint?.host || '').trim()
+	const port = normalizeTcpPort(endpoint?.port)
+	if (!hash || !host || !port) return
+	hints.set(hash, { host, port })
+}
+
+/**
+ * 查询未过期的 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()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 LAN peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearLanPeerHints() {
+	hints.clear()
+}

package/discovery/mdns.mjs

@@ -38,7 +38,7 @@ export function createMdnsDiscoveryProvider(options = {}) {
 						resolve()
 					})
 				})
-				socket.on('message', raw => {
+				socket.on('message', (raw, rinfo) => {
 					let packet
 					try { packet = JSON.parse(String(raw)) } catch { return }
 					const listeners = packet.type === 'advert'
@@ -46,8 +46,12 @@ export function createMdnsDiscoveryProvider(options = {}) {
 						: signalListeners.get(String(packet.topic || ''))
 					if (!listeners?.size) return
 					const bytes = Uint8Array.from(Buffer.from(String(packet.data || ''), 'base64'))
+					const meta = {
+						provider: 'mdns',
+						address: String(rinfo?.address || ''),
+					}
 					for (const listener of listeners)
-						listener(bytes, { provider: 'mdns' })
+						listener(bytes, meta)
 				})
 				bound = true
 			})()

package/index.mjs

@@ -1,6 +1,7 @@
 /**
- * Federation P2P 门面：通用引导与房间/发现入口。
- * 重型子系统请直接从子路径导入（如 `./dag/index.mjs`）。
+ * Federation P2P 门面：fount 网络引导与房间/发现入口。
+ * 上层只面对 nodeHash + envelope，不选择 WebRTC/BLE 等传输。
+ * 重型子系统请从子路径导入（如 `./dag`）；勿导入未导出的 `link/`。
  */
 import { registerDiscoveryProvider } from './discovery/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'