@steve02081504/fount-p2p 0.0.9 → 0.0.11

package/README.md

@@ -24,7 +24,9 @@ await startNode({ nodeDir: '/path/to/p2p/node' })
 await ensureUserRoom()
 ```
 
-Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/registries/event_type`.
+Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/` or choose WebRTC / BLE / LAN yourself.
+
+Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/transport/signal_crypto`, `@steve02081504/fount-p2p/registries/event_type`.
 
 ## Layout
 
@@ -33,31 +35,47 @@ Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`,
 | L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
-| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery, RTC links, rooms |
-| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/` | Federation, store-and-forward, DAG, EVFS |
+| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery + fount-network registry/rooms (`link/providers` are package-private) |
+| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `governance/`, `reputation/` | Federation, store-and-forward, DAG, EVFS, tunables |
 | — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
 
 Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscoveryProvider`, …).
 
-Root contains only the facade and package metadata; all modules live in layered subdirectories. After a layout migration, run `node scripts/cleanup-root-duplicates.mjs` to drop stale root stubs.
+**Transport modules** (exported under `./transport/*`):
+
+| Module | Role |
+|---|---|
+| `link_registry.mjs` | Fount-network facade: dial fallback, scope/overlay |
+| `runtime_bootstrap.mjs` | Progressive `ensureRuntime` (register + background listen / discovery / BT) |
+| `offer_answer.mjs` | Discovery-signal glare for offer/answer providers |
+| `signal_crypto.mjs` | Rendezvous topics + AES-GCM signal packets |
+
+`ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
+
+Root contains only the facade and package metadata; all modules live in layered subdirectories.
 
 ## Tests
 
 ```bash
 npm test              # package pure + integration (Node)
 npm run test:fount    # cross-repo bridge (Deno; requires fount on PATH)
-npm run test:live     # RTC / link smoke (requires node-datachannel)
+npm run test:live     # link / LAN / glare smoke
 npm run test:sim      # tunables co-evolution sim (dev only, not published; --social-tunables to write back)
 ```
 
 During development: `node scripts/check-imports.mjs` validates relative imports. After a layout migration, `node scripts/cleanup-root-duplicates.mjs` removes stale root-level stubs.
 
+Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harness fidelity: [sim/AGENTS.md](./sim/AGENTS.md).
+
 ## Optional dependencies
 
-- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth discovery (attempted by default; skipped when not installed)
+- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is subprocess-only; see [docs/runtime.md](./docs/runtime.md).
+- `node-datachannel` — WebRTC DataChannels (dependency).
+- `ws` — Nostr discovery/signaling WebSockets (dependency).
 
 Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.
 
 ## Docs
 
-- Signaling and link setup: [`docs/signaling.md`](./docs/signaling.md)
+- Transports and provider fallback: [`docs/transports.md`](./docs/transports.md)
+- Signaling and WebRTC glare: [`docs/signaling.md`](./docs/signaling.md)

package/discovery/bt/index.mjs

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer'
 
 import { getBtPeerHint } from './peer_hints.mjs'
-import { loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
+import { canUseBluetoothRuntime, loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
 
 /** 重导出 waitPoweredOn，供 discovery 调用方使用。 */
 export { waitPoweredOn } from './runtime.mjs'
@@ -15,19 +15,11 @@ const MAX_SIGNAL_BLOB_BYTES = 8 * 1024
 const PERIPHERAL_RESCAN_MS = 15_000
 
 /**
- * 探测本机 noble 运行时是否具备 BT 扫描所需 API。
- * @returns {Promise<boolean>} noble 可加载且具备 startScanningAsync 与 waitForPoweredOn(Async) 时为 true
+ * 探测本机 BT discovery 是否可用；失败则回落其它 discovery，不抛错。
+ * @returns {Promise<boolean>} 可用为 true
  */
 export async function canUseBluetoothDiscovery() {
-	try {
-		const noble = await loadNoble()
-		if (typeof noble.startScanningAsync !== 'function') return false
-		const wait = noble.waitForPoweredOnAsync ?? noble.waitForPoweredOn
-		return typeof wait === 'function'
-	}
-	catch {
-		return false
-	}
+	return canUseBluetoothRuntime()
 }
 
 /**

package/discovery/bt/probe_child.mjs

@@ -0,0 +1,20 @@
+/**
+ * 子进程 BT 可用性探测：load → poweredOn → stop → exit。
+ * 由 `canUseBluetoothRuntime` spawn；勿在父进程直接跑 waitPoweredOn（会拖住事件循环）。
+ */
+import process from 'node:process'
+
+import { loadNoble, waitPoweredOn } from './runtime.mjs'
+
+const timeoutMs = Number(process.env.FOUNT_BT_PROBE_MS || 3000)
+
+try {
+	const noble = await loadNoble()
+	if (!noble?.startScanningAsync) process.exit(2)
+	await waitPoweredOn(noble, timeoutMs)
+	try { noble.stop() } catch { /* Windows 上 stop 偶发崩；子进程反正要退出 */ }
+	process.exit(0)
+}
+catch {
+	process.exit(1)
+}

package/discovery/bt/runtime.mjs

@@ -1,4 +1,8 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
 
 /**
  * 解析 Bluetooth 角色（scan / dual）。
@@ -13,20 +17,110 @@ export function resolveBtRole() {
 }
 
 /**
- * 加载 Noble BLE central。
+ * 廉价硬件探测：明确无适配器时跳过 noble/bleno import（加载本身会拉起 native，无适配器时常在 teardown SIGSEGV）。
+ * @returns {boolean | null} true=有迹象，false=明确无，null=未知（继续尝试加载，失败则回落）
+ */
+export function probeBluetoothHardware() {
+	if (process.platform === 'linux') try {
+		const dir = '/sys/class/bluetooth'
+		if (!existsSync(dir)) return false
+		return readdirSync(dir).some(name => name && !name.startsWith('.'))
+	}
+	catch {
+		return false
+	}
+	return null
+}
+
+/** @type {boolean | null} canUseBluetoothRuntime 缓存 */
+let cachedRuntimeOk = null
+/** @type {Promise<boolean> | null} 并发 canUse 合并为一次子进程探测 */
+let probeInflight = null
+
+const PROBE_CHILD = join(dirname(fileURLToPath(import.meta.url)), 'probe_child.mjs')
+
+/**
+ * 在子进程中探测 BT（父进程 waitPoweredOn 会拖住事件循环；stop() 还可能 AV）。
+ * @param {number} timeoutMs waitPoweredOn 超时
+ * @returns {Promise<boolean>} 子进程 exit 0 为可用
+ */
+function probeBluetoothInSubprocess(timeoutMs) {
+	return new Promise(resolve => {
+		const child = spawn(process.execPath, [PROBE_CHILD], {
+			stdio: 'ignore',
+			env: {
+				...process.env,
+				FOUNT_BT_PROBE_MS: String(timeoutMs),
+			},
+			windowsHide: true,
+		})
+		// 探测是旁路缓存填充；勿拖住父进程事件循环 / shutdown 退出。
+		child.unref()
+		let settled = false
+		/**
+		 * @param {boolean} ok 探测结果
+		 * @returns {void}
+		 */
+		const finish = ok => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			resolve(ok)
+		}
+		const timer = setTimeout(() => {
+			child.kill('SIGKILL')
+			finish(false)
+		}, timeoutMs + 5_000)
+		timer.unref()
+		child.once('error', () => finish(false))
+		child.once('exit', (code, signal) => {
+			if (signal) finish(false)
+			else finish(code === 0)
+		})
+	})
+}
+
+/**
+ * 探测 BT 栈是否真正可用（硬件迹象 → 子进程 load → poweredOn）。
+ * 任一步失败返回 false；不抛错。
+ * @param {number} [timeoutMs=3000] waitPoweredOn 超时
+ * @returns {Promise<boolean>} 可用为 true
+ */
+export async function canUseBluetoothRuntime(timeoutMs = 3000) {
+	if (cachedRuntimeOk !== null) return cachedRuntimeOk
+	if (probeBluetoothHardware() === false) {
+		cachedRuntimeOk = false
+		return false
+	}
+	if (!probeInflight) {
+		probeInflight = probeBluetoothInSubprocess(timeoutMs)
+			.then(ok => {
+				cachedRuntimeOk = ok
+				return ok
+			})
+			.finally(() => { probeInflight = null })
+	}
+	return probeInflight
+}
+
+/**
+ * 加载 Noble BLE central。明确无适配器时直接抛错，避免无意义的 native import。
  * @returns {Promise<any>} noble 运行时
  */
 export async function loadNoble() {
+	if (probeBluetoothHardware() === false)
+		throw new Error('p2p: no bluetooth adapter')
 	const mod = await import('@stoprocent/noble')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
+	return mod?.withBindings?.('default') || mod?.default || mod
 }
 
 /**
- * 加载 Bleno BLE peripheral。
+ * 加载 Bleno BLE peripheral。明确无适配器时直接抛错，避免无意义的 native import。
  * @returns {Promise<any>} bleno 运行时
  */
 export async function loadBleno() {
+	if (probeBluetoothHardware() === false)
+		throw new Error('p2p: no bluetooth adapter')
 	const mod = await import('@stoprocent/bleno')
 	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
 	return mod.default ?? mod
@@ -40,7 +134,7 @@ export async function loadBleno() {
  */
 export async function waitPoweredOn(runtime, timeout) {
 	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
-	if (typeof wait !== 'function')
+	if (!wait)
 		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
 	return wait.call(runtime, timeout)
 }

package/discovery/index.mjs

@@ -23,6 +23,14 @@ export function unregisterDiscoveryProvider(id) {
 	providers.delete(String(id))
 }
 
+/**
+ * 清空全部 discovery provider。
+ * @returns {void}
+ */
+export function clearDiscoveryProviders() {
+	providers.clear()
+}
+
 /**
  * 列出已注册的 discovery provider（按 priority 排序）。
  * @returns {DiscoveryProvider[]} 提供者列表
@@ -32,29 +40,40 @@ export function listDiscoveryProviders() {
 }
 
 /**
- * 通过所有可用 provider 广播 topic advert。
- * 单路失败静默（正常降级）；其它 provider 仍可成功。
- * @param {string} topic advert 主题
- * @param {Uint8Array} bytes advert 载荷
+ * 并行启动各 provider 的 async 钩子；单路失败静默。
+ * @param {DiscoveryProvider[]} list 提供者列表
+ * @param {(provider: DiscoveryProvider) => Promise<(() => void) | null | undefined>} run 单路启动
  * @returns {Promise<() => void>} 统一取消函数
  */
-export async function advertiseTopic(topic, bytes) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canDiscover || typeof provider.advertise !== 'function') continue
-		let cleanup = null
+async function startProvidersParallel(list, run) {
+	const settled = await Promise.all(list.map(async provider => {
 		try {
-			cleanup = await provider.advertise(topic, bytes)
+			const cleanup = await run(provider)
+			return typeof cleanup === 'function' ? cleanup : null
 		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
+		catch {
+			return null
+		}
+	}))
+	const cleanups = settled.filter(Boolean)
 	return () => {
 		for (const cleanup of cleanups)
 			try { cleanup() } catch { /* ignore */ }
 	}
 }
 
+/**
+ * 通过所有可用 provider 广播 topic advert。
+ * 单路失败静默（正常降级）；其它 provider 仍可成功。
+ * @param {string} topic advert 主题
+ * @param {Uint8Array} bytes advert 载荷
+ * @returns {Promise<() => void>} 统一取消函数
+ */
+export async function advertiseTopic(topic, bytes) {
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.advertise === 'function')
+	return startProvidersParallel(list, provider => provider.advertise(topic, bytes))
+}
+
 /**
  * 通过所有可用 provider 订阅 topic advert。
  * 单路失败静默（正常降级）。
@@ -63,20 +82,8 @@ export async function advertiseTopic(topic, bytes) {
  * @returns {Promise<() => void>} 统一取消函数
  */
 export async function subscribeTopic(topic, onAdvert) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canDiscover || typeof provider.subscribe !== 'function') continue
-		let cleanup = null
-		try {
-			cleanup = await provider.subscribe(topic, onAdvert)
-		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
-	return () => {
-		for (const cleanup of cleanups)
-			try { cleanup() } catch { /* ignore */ }
-	}
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.subscribe === 'function')
+	return startProvidersParallel(list, provider => provider.subscribe(topic, onAdvert))
 }
 
 /**
@@ -93,13 +100,15 @@ 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 {
-		if (await Promise.resolve(provider.sendSignal(topic, to, bytes)) !== false)
-			sent = true
-	}
-	catch (error) {
-		lastError = error
-	}
+	await Promise.all(capable.map(async provider => {
+		try {
+			if (await Promise.resolve(provider.sendSignal(topic, to, bytes)) !== false)
+				sent = true
+		}
+		catch (error) {
+			lastError = error
+		}
+	}))
 	if (!sent) throw lastError || new Error('p2p: no discovery provider delivered signal')
 }
 
@@ -111,18 +120,6 @@ export async function sendSignal(topic, to, bytes) {
  * @returns {Promise<() => void>} 统一取消函数
  */
 export async function listenSignals(topic, onSignal) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canSignal || typeof provider.onSignal !== 'function') continue
-		let cleanup = null
-		try {
-			cleanup = await provider.onSignal(topic, onSignal)
-		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
-	return () => {
-		for (const cleanup of cleanups)
-			try { cleanup() } catch { /* ignore */ }
-	}
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canSignal && typeof provider.onSignal === 'function')
+	return startProvidersParallel(list, provider => provider.onSignal(topic, onSignal))
 }

package/discovery/mdns.mjs

@@ -6,6 +6,7 @@ const DEFAULT_GROUP = '239.255.42.99'
 
 /**
  * 轻量 multicast 发现插件：不做完整 DNS-SD，只复用 mDNS 的 LAN multicast 发现思路。
+ * 引用计数为 0 时关闭 UDP socket，避免 shutdown 后句柄拖住进程。
  *
  * @param {{ port?: number, group?: string }} [options] 组播端口与组地址
  * @returns {import('./index.mjs').DiscoveryProvider} mDNS 发现提供者
@@ -13,14 +14,24 @@ const DEFAULT_GROUP = '239.255.42.99'
 export function createMdnsDiscoveryProvider(options = {}) {
 	const port = Number(options.port) || DEFAULT_PORT
 	const group = String(options.group || DEFAULT_GROUP)
-	const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true })
+	/** @type {import('node:dgram').Socket | null} */
+	let socket = null
 	let bound = false
 	let bindPromise = null
+	let refs = 0
 	/** @type {Map<string, Set<Function>>} */
 	const advertListeners = new Map()
 	/** @type {Map<string, Set<Function>>} */
 	const signalListeners = new Map()
 
+	/**
+	 * 懒创建或返回当前 UDP socket。
+	 * @returns {import('node:dgram').Socket} 用于组播 bind/send 的 socket
+	 */
+	function getSocket() {
+		return socket ||= dgram.createSocket({ type: 'udp4', reuseAddr: true })
+	}
+
 	/**
 	 * 绑定 UDP socket 并注册组播消息处理器。
 	 * @returns {Promise<void>}
@@ -29,16 +40,24 @@ export function createMdnsDiscoveryProvider(options = {}) {
 		if (bound) return
 		if (!bindPromise)
 			bindPromise = (async () => {
+				const sock = getSocket()
 				await new Promise((resolve, reject) => {
-					socket.once('error', reject)
-					socket.bind(port, '0.0.0.0', () => {
-						socket.off('error', reject)
-						socket.addMembership(group)
-						socket.setMulticastTTL(1)
+					sock.once('error', reject)
+					sock.bind(port, '0.0.0.0', () => {
+						sock.off('error', reject)
+						sock.addMembership(group)
+						sock.setMulticastTTL(1)
 						resolve()
 					})
 				})
-				socket.on('message', (raw, rinfo) => {
+				// acquire 已全部释放：关掉刚 bind 的 socket，避免泄漏句柄。
+				if (refs <= 0) {
+					try { sock.close() } catch { /* ignore */ }
+					if (socket === sock) socket = null
+					bound = false
+					return
+				}
+				sock.on('message', (raw, rinfo) => {
 					let packet
 					try { packet = JSON.parse(String(raw)) } catch { return }
 					const listeners = packet.type === 'advert'
@@ -70,16 +89,34 @@ export function createMdnsDiscoveryProvider(options = {}) {
 	 */
 	async function multicast(type, topic, bytes) {
 		await ensureBound()
+		const sock = getSocket()
 		const packet = Buffer.from(JSON.stringify({
 			type,
 			topic,
 			data: Buffer.from(bytes).toString('base64'),
 		}))
 		await new Promise((resolve, reject) => {
-			socket.send(packet, port, group, error => error ? reject(error) : resolve())
+			sock.send(packet, port, group, error => error ? reject(error) : resolve())
 		})
 	}
 
+	/**
+	 * 占用 socket；归还后若无引用则关闭。
+	 * @returns {() => void} 释放函数
+	 */
+	function acquire() {
+		refs++
+		void ensureBound().catch(() => { })
+		return () => {
+			refs = Math.max(0, refs - 1)
+			if (refs > 0 || !socket) return
+			try { socket.close() } catch { /* ignore */ }
+			socket = null
+			bound = false
+			bindPromise = null
+		}
+	}
+
 	/**
 	 * 向 topic bucket 注册监听器。
 	 * @param {Map<string, Set<Function>>} bucket topic → 监听器集合
@@ -90,7 +127,11 @@ export function createMdnsDiscoveryProvider(options = {}) {
 	function addListener(bucket, topic, listener) {
 		if (!bucket.has(topic)) bucket.set(topic, new Set())
 		bucket.get(topic).add(listener)
-		return () => bucket.get(topic)?.delete(listener)
+		const release = acquire()
+		return () => {
+			bucket.get(topic)?.delete(listener)
+			release()
+		}
 	}
 
 	return {
@@ -98,24 +139,27 @@ export function createMdnsDiscoveryProvider(options = {}) {
 		priority: 10,
 		caps: { canDiscover: true, canSignal: true, canRelay: false },
 		/**
-		 * 周期性组播广播 advert。
+		 * 周期性组播广播 advert（首发后台，不阻塞调用方）。
 		 * @param {string} topic advert 主题
 		 * @param {Uint8Array} bytes advert 载荷
 		 * @returns {Promise<() => void>} 取消广播函数
 		 */
 		async advertise(topic, bytes) {
-			await multicast('advert', topic, bytes)
+			const release = acquire()
+			void multicast('advert', topic, bytes).catch(() => { })
 			const timer = setInterval(() => { void multicast('advert', topic, bytes).catch(() => { }) }, 30_000)
-			return () => clearInterval(timer)
+			return () => {
+				clearInterval(timer)
+				release()
+			}
 		},
 		/**
-		 * 订阅组播 advert。
+		 * 订阅组播 advert（立即返回；UDP bind 后台完成）。
 		 * @param {string} topic advert 主题
 		 * @param {Function} onAdvert advert 回调
 		 * @returns {Promise<() => void>} 取消订阅函数
 		 */
 		async subscribe(topic, onAdvert) {
-			await ensureBound()
 			return addListener(advertListeners, topic, onAdvert)
 		},
 		/**
@@ -126,16 +170,21 @@ export function createMdnsDiscoveryProvider(options = {}) {
 		 * @returns {Promise<void>}
 		 */
 		async sendSignal(topic, _to, bytes) {
-			await multicast('signal', topic, bytes)
+			const release = acquire()
+			try {
+				await multicast('signal', topic, bytes)
+			}
+			finally {
+				release()
+			}
 		},
 		/**
-		 * 订阅组播信令。
+		 * 订阅组播信令（立即返回；UDP bind 后台完成）。
 		 * @param {string} topic 信令 topic
 		 * @param {Function} onSignal 信令回调
 		 * @returns {Promise<() => void>} 取消订阅函数
 		 */
 		async onSignal(topic, onSignal) {
-			await ensureBound()
 			return addListener(signalListeners, topic, onSignal)
 		},
 	}