@steve02081504/fount-p2p 0.0.36 → 0.0.37

package/discovery/nostr/session.mjs

@@ -0,0 +1,584 @@
+import { randomBytes } from 'node:crypto'
+import { isIP } from 'node:net'
+
+import WebSocket from 'ws'
+
+import { base64ToBytes } from '../../core/bytes_codec.mjs'
+import { nodeDebug } from '../../node/log.mjs'
+
+/** 单中继 WebSocket 首连超时（短超时 + 并行，避免串行 10s×N）。 */
+export const NOSTR_CONNECT_TIMEOUT_MS = 2_000
+/** 先 close，超时未 CLOSED 再 terminate（给对端优雅关闭的窗口）。 */
+const NOSTR_CLOSE_GRACE_MS = 1_000
+/** 单 relay 等待 EVENT OK 回执超时。 */
+const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
+/** 共享 relay 会话断线后重连间隔。 */
+const NOSTR_RECONNECT_DELAY_MS = 500
+/** 无 sub/publish 工作时共享 relay 空闲回收延迟（给连续 send 复用窗口）。 */
+const NOSTR_IDLE_DROP_MS = 2_000
+
+/**
+ * @param {string[] | undefined | null} urls 原始列表
+ * @returns {string[]} 去重后的列表
+ */
+export function dedupeRelayUrls(urls) {
+	const seen = new Set()
+	return (urls || [])
+		.filter(url => url && !seen.has(url) && (seen.add(url), true))
+}
+
+/**
+ * 关掉 WebSocket：已连上则先 close，grace 内未 CLOSED 再 terminate。
+ * @param {import('ws').WebSocket} ws 连接
+ * @returns {void}
+ */
+function dropWebSocket(ws) {
+	if (ws.readyState === WebSocket.CLOSED) return
+	if (ws.readyState === WebSocket.CONNECTING) {
+		try { ws.terminate() } catch { /* ignore */ }
+		return
+	}
+	const timer = setTimeout(() => {
+		if (ws.readyState !== WebSocket.CLOSED)
+			try { ws.terminate() } catch { /* ignore */ }
+	}, NOSTR_CLOSE_GRACE_MS)
+	timer.unref()
+	ws.once('close', () => clearTimeout(timer))
+	try {
+		ws.close()
+	}
+	catch {
+		clearTimeout(timer)
+		try { ws.terminate() } catch { /* ignore */ }
+	}
+}
+
+/**
+ * 生成钉死地址集的 dns.lookup 形状函数：忽略请求的 hostname，始终返回给定地址，
+ * 供 `new WebSocket(url, { lookup })` / node:http(s) 使用，避免对同一 hostname 的第二次不受控解析。
+ * @param {string[]} addresses 已校验/受控解析的地址
+ * @returns {(hostname: string, options: object | ((err: Error | null, address?: string | object[], family?: number) => void), callback?: (err: Error | null, address?: string | object[], family?: number) => void) => void} lookup 函数
+ */
+export function pinnedLookup(addresses) {
+	return (hostname, options, callback) => {
+		if (typeof options === 'function') {
+			callback = options
+			options = {}
+		}
+		const family = addresses.length ? isIP(addresses[0]) : 0
+		if (options?.all)
+			callback(null, addresses.map(address => ({ address, family: isIP(address) })), family)
+		else
+			callback(null, addresses[0], family)
+	}
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {number} [timeoutMs] 超时毫秒
+ * @param {AbortSignal} [signal] 取消信号
+ * @param {{ hostname: string, addresses: string[] } | ((url: string) => Promise<{ hostname: string, addresses: string[] } | null>) | null} [connectTarget] 已解析的连接目标（钉 IP 用）或解析函数
+ * @returns {Promise<import('ws').WebSocket>} 已打开的 WebSocket
+ */
+export function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal, connectTarget) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		let settled = false
+		/**
+		 * @param {Error} error 失败原因
+		 * @returns {void}
+		 */
+		const fail = error => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', onAbort)
+			if (ws) dropWebSocket(ws)
+			reject(error)
+		}
+		/**
+		 * 收到 abort 信号时失败
+		 * @returns {void}
+		 */
+		const onAbort = () => fail(new Error('nostr: aborted'))
+		const timer = setTimeout(() => fail(new Error(`nostr: connect timeout for ${relayUrl}`)), timeoutMs)
+		timer.unref()
+		signal?.addEventListener('abort', onAbort, { once: true })
+		let ws = null
+		void (async () => {
+			let wsOptions
+			try {
+				const target = typeof connectTarget === 'function' ? await connectTarget(relayUrl) : connectTarget
+				if (connectTarget != null && (!target || !target.addresses?.length)) {
+					fail(new Error(`nostr: connect target resolution returned empty for ${relayUrl}`))
+					return
+				}
+				if (target) wsOptions = { lookup: pinnedLookup(target.addresses) }
+			}
+			catch (error) {
+				fail(error instanceof Error ? error : new Error(String(error)))
+				return
+			}
+			if (settled) return
+			ws = new WebSocket(relayUrl, wsOptions)
+			ws.once('open', () => {
+				if (settled) return
+				settled = true
+				clearTimeout(timer)
+				signal?.removeEventListener('abort', onAbort)
+				resolve(ws)
+			})
+			ws.once('error', () => {
+				fail(new Error(`nostr: websocket error for ${relayUrl}`))
+			})
+		})()
+	})
+}
+
+/**
+ * @param {import('ws').WebSocket} ws 已连接 relay
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @param {() => boolean} isCurrent 该尝试是否仍是 publishRequest 的当前尝试（断线重发后过期）
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		let settled = false
+		/**
+		 * @param {boolean} ok relay 是否接受
+		 * @param {Error | null} [error] 失败原因
+		 * @returns {void}
+		 */
+		const finish = (ok, error = null) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', onAbort)
+			ws.off('message', onMessage)
+			// 过期的 in-flight 尝试：只清理自身监听器/定时器，不结算，避免影响重发后的当前尝试。
+			if (!isCurrent()) return
+			if (error) reject(error)
+			else resolve(ok)
+		}
+		/**
+		 * 收到 abort 信号时以失败结束
+		 * @returns {void}
+		 */
+		const onAbort = () => finish(false, new Error('nostr: aborted'))
+		/**
+		 * @param {import('ws').RawData} data relay 消息
+		 * @returns {void}
+		 */
+		const onMessage = data => {
+			let parsed
+			try { parsed = JSON.parse(String(data)) } catch { return }
+			if (parsed?.[0] !== 'OK' || parsed[1] !== event.id) return
+			const accepted = parsed[2] === true
+			if (!accepted)
+				nodeDebug('p2p:nostr publish rejected', {
+					url: relayUrl,
+					reason: String(parsed[3] || 'rejected'),
+				})
+			finish(accepted)
+		}
+		const timer = setTimeout(
+			() => finish(false, new Error(`nostr: publish ok timeout for ${relayUrl}`)),
+			NOSTR_PUBLISH_OK_TIMEOUT_MS,
+		)
+		timer.unref()
+		signal?.addEventListener('abort', onAbort, { once: true })
+		ws.on('message', onMessage)
+		try {
+			ws.send(JSON.stringify(['EVENT', event]))
+		}
+		catch (error) {
+			finish(false, error instanceof Error ? error : new Error(String(error)))
+		}
+	})
+}
+
+/**
+ * 一次共享 relay publish 请求：入队（pending）与已派发（inflight）时共用同一结构。
+ * attempt 标识每次实际发送尝试，断线重发会递增；旧的 in-flight 尝试据此自检为过期后自我清理，
+ * 不再结算当前尝试。
+ * @typedef {{
+ *   event: object,
+ *   signal: AbortSignal | undefined,
+ *   attempt: number,
+ *   onAbort: (() => void) | null,
+ *   removeAbort: (() => void) | null,
+ *   resolve: (ok: boolean) => void,
+ *   reject: (err: Error) => void,
+ * }} NostrPublishRequest
+ */
+
+/**
+ * 共享 relay 会话：多 SUB / publish 复用同一 URL 的 WebSocket，避免 signal/presence/advert 各建一池、
+ * 以及每次 send 重开一条连接（内存泄漏）。
+ * 仍有活跃 sub 或待发 publish 时断线会自动重连并重发 REQ / 重发 EVENT。
+ * @typedef {{
+ *   ws: import('ws').WebSocket | null,
+ *   connecting: boolean,
+ *   reconnectTimer: ReturnType<typeof setTimeout> | null,
+ *   idleTimer: ReturnType<typeof setTimeout> | null,
+ *   connectTarget: { hostname: string, addresses: string[] } | ((url: string) => Promise<{ hostname: string, addresses: string[] } | null>) | null,
+ *   subs: Map<string, { filter: object, onEvent: (event: object, relayUrl: string) => void }>,
+ *   pendingPublishes: Array<NostrPublishRequest>,
+ *   inflightPublishes: Array<NostrPublishRequest>,
+ * }} SharedRelaySession
+ */
+
+/** @type {Map<string, SharedRelaySession>} */
+const sharedRelaySessions = new Map()
+
+/**
+ * 会话是否仍有需要连接的工作（sub 或待发 publish）。
+ * @param {SharedRelaySession} session 会话
+ * @returns {boolean} 是否有活跃工作
+ */
+function hasPendingWork(session) {
+	return session.subs.size || session.pendingPublishes.length || session.inflightPublishes.length
+}
+
+/**
+ * 取消会话的空闲回收定时器。
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function clearIdleDrop(session) {
+	if (!session.idleTimer) return
+	clearTimeout(session.idleTimer)
+	session.idleTimer = null
+}
+
+/**
+ * 会话无 sub 时，待 publish 清空后延迟回收空闲 socket（给连续 send 复用窗口）。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function scheduleIdleDrop(relayUrl, session) {
+	if (session.subs.size || session.idleTimer) return
+	session.idleTimer = setTimeout(() => {
+		session.idleTimer = null
+		if (!isLiveSharedSession(relayUrl, session) || hasPendingWork(session)) return
+		sharedRelaySessions.delete(relayUrl)
+		clearSharedRelayReconnect(session)
+		if (session.ws) dropWebSocket(session.ws)
+		session.ws = null
+	}, NOSTR_IDLE_DROP_MS)
+	session.idleTimer.unref?.()
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @returns {boolean} session 是否仍是该 URL 的活动会话
+ */
+function isLiveSharedSession(relayUrl, session) {
+	return sharedRelaySessions.get(relayUrl) === session
+}
+
+/**
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function clearSharedRelayReconnect(session) {
+	if (!session.reconnectTimer) return
+	clearTimeout(session.reconnectTimer)
+	session.reconnectTimer = null
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {import('ws').WebSocket} ws 已打开连接
+ * @returns {void}
+ */
+function attachSharedRelaySocket(relayUrl, session, ws) {
+	session.ws = ws
+	// 提升监听器上限：每个并发 publish 的临时 message 监听 + 会话自身监听，避免 MaxListenersExceededWarning。
+	ws.setMaxListeners(session.pendingPublishes.length + session.inflightPublishes.length + 8)
+	nodeDebug('p2p:nostr relay up', { url: relayUrl })
+	ws.on('message', data => {
+		let parsed
+		try { parsed = JSON.parse(String(data)) } catch { return }
+		if (parsed?.[0] !== 'EVENT') return
+		const subId = String(parsed[1] || '')
+		const nostrEvent = parsed[2]
+		const sub = session.subs.get(subId)
+		if (!sub || !nostrEvent) return
+		try { sub.onEvent(nostrEvent, relayUrl) } catch { /* ignore */ }
+	})
+	ws.once('close', () => {
+		if (!isLiveSharedSession(relayUrl, session)) return
+		session.ws = null
+		// 尚未确认的 inflight publish 重新入队，重连后由 flushPendingPublishes 重发。
+		if (session.inflightPublishes.length) {
+			session.pendingPublishes.push(...session.inflightPublishes)
+			for (const publishRequest of session.inflightPublishes)
+				attachQueuedAbort(session, publishRequest)
+			session.inflightPublishes = []
+		}
+		if (!hasPendingWork(session)) {
+			sharedRelaySessions.delete(relayUrl)
+			return
+		}
+		scheduleSharedRelayConnect(relayUrl, session, NOSTR_RECONNECT_DELAY_MS)
+	})
+	for (const [subId, sub] of session.subs)
+		try { ws.send(JSON.stringify(['REQ', subId, sub.filter])) } catch { /* ignore */ }
+	flushPendingPublishes(relayUrl, session, ws)
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {number} [delayMs=0] 延迟毫秒（断线重连用）
+ * @returns {void}
+ */
+function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
+	if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
+	clearSharedRelayReconnect(session)
+	/** 启动/恢复共享会话连接 */
+	const start = () => {
+		session.reconnectTimer = null
+		if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
+		if (!hasPendingWork(session)) {
+			sharedRelaySessions.delete(relayUrl)
+			return
+		}
+		session.connecting = true
+		void connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS, undefined, session.connectTarget).then(ws => {
+			session.connecting = false
+			if (!isLiveSharedSession(relayUrl, session) || !hasPendingWork(session)) {
+				sharedRelaySessions.delete(relayUrl)
+				dropWebSocket(ws)
+				return
+			}
+			attachSharedRelaySocket(relayUrl, session, ws)
+		}).catch(error => {
+			session.connecting = false
+			if (!isLiveSharedSession(relayUrl, session)) return
+			nodeDebug('p2p:nostr relay fail', {
+				url: relayUrl,
+				err: String(error?.message || error),
+			})
+			if (!hasPendingWork(session)) {
+				sharedRelaySessions.delete(relayUrl)
+				return
+			}
+			scheduleSharedRelayConnect(relayUrl, session, NOSTR_RECONNECT_DELAY_MS)
+		})
+	}
+	if (delayMs <= 0) {
+		// 让同一 tick 内的 registerSharedRelaySub 先写入 subs，再决定是否连接。
+		queueMicrotask(start)
+		return
+	}
+	nodeDebug('p2p:nostr relay reconnect', { url: relayUrl, delayMs })
+	session.reconnectTimer = setTimeout(start, delayMs)
+	session.reconnectTimer.unref?.()
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {{ hostname: string, addresses: string[] } | ((url: string) => Promise<{ hostname: string, addresses: string[] } | null>) | null} [connectTarget] 钉 IP 用的连接目标（首个请求方提供；重连复用）
+ * @returns {SharedRelaySession} 共享会话
+ */
+function acquireSharedRelay(relayUrl, connectTarget) {
+	const existing = sharedRelaySessions.get(relayUrl)
+	if (existing) return existing
+	/** @type {SharedRelaySession} */
+	const session = {
+		ws: null,
+		connecting: false,
+		reconnectTimer: null,
+		idleTimer: null,
+		connectTarget: connectTarget || null,
+		subs: new Map(),
+		pendingPublishes: [],
+		inflightPublishes: [],
+	}
+	sharedRelaySessions.set(relayUrl, session)
+	scheduleSharedRelayConnect(relayUrl, session)
+	return session
+}
+
+/**
+ * @param {string} relayUrl 中继 URL
+ * @param {string} subscriptionId 订阅 id
+ * @returns {void}
+ */
+function releaseSharedRelaySub(relayUrl, subscriptionId) {
+	const session = sharedRelaySessions.get(relayUrl)
+	if (!session) return
+	session.subs.delete(subscriptionId)
+	const { ws } = session
+	if (ws?.readyState === WebSocket.OPEN)
+		try { ws.send(JSON.stringify(['CLOSE', subscriptionId])) } catch { /* ignore */ }
+	if (hasPendingWork(session)) return
+	sharedRelaySessions.delete(relayUrl)
+	clearSharedRelayReconnect(session)
+	clearIdleDrop(session)
+	if (ws) dropWebSocket(ws)
+}
+
+/**
+ * 在已打开的共享连接上登记 REQ；连接中则等 attach 时统一重放。
+ * @param {SharedRelaySession} session 会话
+ * @param {string} subscriptionId 订阅 id
+ * @param {object} filter Nostr filter
+ * @param {(event: object, relayUrl: string) => void} onEvent 事件回调
+ * @returns {void}
+ */
+function registerSharedRelaySub(session, subscriptionId, filter, onEvent) {
+	session.subs.set(subscriptionId, { filter, onEvent })
+	clearIdleDrop(session)
+	const { ws } = session
+	if (ws?.readyState !== WebSocket.OPEN) return
+	try { ws.send(JSON.stringify(['REQ', subscriptionId, filter])) } catch { /* ignore */ }
+}
+
+/**
+ * 将已入队的 publish 逐个派发到已打开 socket 上；复用 publishEventOnRelay 等 OK 回执。
+ * 每个 publish 独立携带自己的 message/abort 监听，socket 共享安全。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {import('ws').WebSocket} socket 已打开连接
+ * @returns {void}
+ */
+function flushPendingPublishes(relayUrl, session, socket) {
+	const pending = session.pendingPublishes
+	session.pendingPublishes = []
+	for (const publishRequest of pending) {
+		publishRequest.removeAbort?.()
+		publishRequest.onAbort = null
+		publishRequest.removeAbort = null
+		const attempt = ++publishRequest.attempt
+		session.inflightPublishes.push(publishRequest)
+		void publishEventOnRelay(socket, relayUrl, publishRequest.event, publishRequest.signal, () => publishRequest.attempt === attempt)
+			.then(
+				ok => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.resolve(ok)),
+				error => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.reject(error)),
+			)
+	}
+}
+
+/**
+ * 为队列中的 publish 挂上 abort 处理：先移除监听器（释放 signal 对回调/event/session 的引用），
+ * 再从队列删除并 reject。
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['pendingPublishes'][number]} publishRequest 待发请求
+ * @returns {void}
+ */
+function attachQueuedAbort(session, publishRequest) {
+	const { signal, reject } = publishRequest
+	/**
+	 * 处理 abort 事件
+	 */
+	publishRequest.onAbort = () => {
+		publishRequest.removeAbort?.()
+		const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
+		if (pendingIndex < 0) return
+		session.pendingPublishes.splice(pendingIndex, 1)
+		reject(new Error('nostr: aborted'))
+	}
+	/**
+	 * 移除 abort 监听器
+	 */
+	publishRequest.removeAbort = () => {
+		if (signal) signal.removeEventListener('abort', publishRequest.onAbort)
+	}
+	if (signal) signal.addEventListener('abort', publishRequest.onAbort, { once: true })
+}
+
+/**
+ * publish 在 socket 上得到 OK / 失败 / abort 后结算：从 inflight 移除并 settle。
+ * 仅结算仍与当前 attempt 匹配的请求：断线重发后 attempt 已递增，旧尝试的结算在此短路，
+ * 避免提前结算重发后的当前尝试。已被 requeue（断线重发）的请求不在 inflight，跳过结算。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['inflightPublishes'][number]} publishRequest 已发送请求
+ * @param {number} attempt 本次发送的 attempt 标识
+ * @param {() => void} settle 结算回调（resolve/reject）
+ * @returns {void}
+ */
+function settleInflightPublish(relayUrl, session, publishRequest, attempt, settle) {
+	if (publishRequest.attempt !== attempt) return
+	const inflightIndex = session.inflightPublishes.indexOf(publishRequest)
+	if (inflightIndex < 0) return
+	session.inflightPublishes.splice(inflightIndex, 1)
+	settle()
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
+}
+
+/**
+ * 通过共享 relay 会话发布 EVENT：复用已打开 socket，避免每次 send 重开一条连接（内存泄漏）。
+ * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发。
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @param {{ hostname: string, addresses: string[] } | ((url: string) => Promise<{ hostname: string, addresses: string[] } | null>) | null} [connectTarget] 钉 IP 用的连接目标
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+export function publishViaSharedRelay(relayUrl, event, signal, connectTarget) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		const session = acquireSharedRelay(relayUrl, connectTarget)
+		clearIdleDrop(session)
+		/** @type {SharedRelaySession['pendingPublishes'][number]} */
+		const publishRequest = { event, signal, attempt: 0, resolve, reject, onAbort: null, removeAbort: null }
+		attachQueuedAbort(session, publishRequest)
+		session.pendingPublishes.push(publishRequest)
+		if (session.ws?.readyState === WebSocket.OPEN)
+			flushPendingPublishes(relayUrl, session, session.ws)
+		else
+			scheduleSharedRelayConnect(relayUrl, session)
+	})
+}
+
+/**
+ * 内部：按 rendezvous 键订阅 Nostr kind（topic 不导出）。多订阅共享每 URL 一条连接。
+ * @param {string[]} relayUrls 中继 URL 列表
+ * @param {{ kind: number, rendezvousKey: string, tagX: string, onPayload: (bytes: Uint8Array, meta: { relayUrl: string, event: object }) => void | Promise<void>, addressable?: boolean, resolveConnectTarget?: (url: string) => Promise<{ hostname: string, addresses: string[] } | null> }} options 订阅选项
+ * @returns {() => void} 取消订阅
+ */
+export function subscribeNostrKind(relayUrls, options) {
+	const { kind, rendezvousKey, tagX, onPayload, addressable = false, resolveConnectTarget } = options
+	const subscriptionId = randomBytes(8).toString('hex')
+	const filter = { kinds: [kind], '#t': [rendezvousKey], '#x': [tagX] }
+	if (addressable) filter['#d'] = [rendezvousKey]
+	/**
+	 * @param {object} nostrEvent Nostr EVENT
+	 * @param {string} relayUrl 来源中继
+	 * @returns {void}
+	 */
+	const onEvent = (nostrEvent, relayUrl) => {
+		if (nostrEvent?.kind !== kind) return
+		try {
+			const result = onPayload(base64ToBytes(nostrEvent.content), { relayUrl, event: nostrEvent })
+			if (result?.then) void result.catch(() => { })
+		}
+		catch { /* ignore */ }
+	}
+	const urls = dedupeRelayUrls(relayUrls)
+	for (const relayUrl of urls)
+		registerSharedRelaySub(acquireSharedRelay(relayUrl, resolveConnectTarget), subscriptionId, filter, onEvent)
+	return () => {
+		for (const relayUrl of urls) releaseSharedRelaySub(relayUrl, subscriptionId)
+	}
+}

package/docs/nostr_relay_discovery.md

@@ -0,0 +1,92 @@
+# Nostr Relay Discovery & Routing
+
+Nostr is the fount-network fallback transport (`link` level −∞, discovery `priority` 100). This document covers the **relay pool**, NIP-66 discovery, health scoring, advert relay-field signing, and handshake routing. Top-level surface: [signaling.md](signaling.md) · [transports.md](transports.md) · [mesh.md](mesh.md).
+
+Source layout (`discovery/nostr/`):
+- `index.mjs` — provider (presence / signal / advert subscriptions)
+- `relays.mjs` — pool, health, NIP-66 discovery, normalization, persistence
+- `selection.mjs` — handshake routing, backoff, fanout
+- `session.mjs` — shared relay WebSocket sessions / subscribe primitives
+- `census.mjs` — population census worker (kind 30789, HT estimate)
+- `census_math.mjs` — census pure functions (inclusion-probability update, HT estimator)
+- `constants.mjs` — hard limits
+
+## Three-tier sets
+
+`relayPool` (all known) → `workingRelays` (top-`WORKING_RELAYS_COUNT` by health) → `listenRelays` (top-`LISTEN_RELAYS_COUNT` working subset used for publish/listen).
+
+- `public`/`manual` entries are **pinned**: always in `working`/`listen` and never evicted by `clearStale` or pool-cap. Pin count may exceed the nominal caps.
+- `nip66`/`peer` entries are disposable: evicted when stale (`PROBE_STALE_MS`) or when the pool exceeds `POOL_CAP`.
+- Fresh nodes are seeded with `DEFAULT_RELAY_URLS` (`source: 'public'`) so `listenRelays` is never empty at cold start.
+- Persistent connections stay bounded by `workingRelays` (`WORKING_RELAYS_COUNT`, max 32); pins influence selection, not simultaneous connections.
+
+## URL normalization (single ingress)
+
+`normalizeNostrRelayUrl` (in `relays.mjs`) is the only entry for every inbound URL (NIP-66 `d` tag, manual config, peer advert):
+
+- `wss://` always; `ws://` only for loopback/private hosts (local dev/tests).
+- hostname lowercased, default port removed, trailing slashes removed, non-empty path kept.
+- Invalid → `null` → dropped with an audit log (`nodeDebug('invalidRelayUrl', { url, reason })`), never silently cleaned.
+
+## Health score
+
+```text
+failureRate = failureCount / (successCount + failureCount)
+rtt         = clamp(rttMs ?? DEFAULT_RTT_MS, 1, MAX_RTT_MS)
+score       = rtt * (1 + failureRate * FAILURE_WEIGHT)     // FAILURE_WEIGHT = 4
+score      *= STALE_PENALTY                                 // ×2 if lastProbe older than PROBE_STALE_MS
+```
+
+Lower is better. `recordProbeSuccess` / `recordProbeFailure` / `recordPublishResult` share the same counters. Writes to `nodeDir/nostr/relays.json` are **throttled** (2s debounce).
+
+## Persistence
+
+`nodeDir/nostr/relays.json`:
+
+```text
+{
+  "updatedAt": 1234567890,
+  "nostrRelays": [{ "url", "rttMs", "successCount", "failureCount", "lastSuccess", "lastFailure", "lastProbe", "firstSeen", "lastSeen", "source", "nips", "clearnet", "monitorCount" }],
+  "peerRoutes": { "<nodeHash64>": { "listenRelays", "peerPool", "lastGoodNostrRelays", "lastSeen" } }
+}
+```
+
+`peerRoutes` is a local-only cache (never shared).
+
+## NIP-66 discovery
+
+- Bootstrap: `NIP66_BOOTSTRAP_RELAYS` + all `public`/`manual` as fallback, parallel, 10s connect timeout; refreshed every `NIP66_REFRESH_MS` (6h).
+- `REQ` kind 30166 (limit 500) + optional 10166; parse `d` (url), `n` (clearnet only), `N` (must include NIP-01 or be absent), `rtt-open/read/write`.
+- **Trust layering**: same URL reported by ≥2 distinct pubkeys → `monitorCount ≥ 2`; single report is untrusted. All candidates are probed; a successful probe upserts the entry (`source: 'nip66'`, real `monitorCount`), a failed probe drops it. Probes per round are bounded (`MAX_NIP66_PROBES_PER_ROUND`).
+- Discovery is non-blocking (first round deferred to the next macrotask) and cancellable (AbortSignal tears down sockets + NIP-11 fetches), so it never blocks `ensureRuntime` or shutdown.
+- `setNostrRelayDiscoveryEnabledForTests(false)` / `setNip66BootstrapRelaysForTests(urls)` are test-only hooks.
+
+## Advert relay fields & signature
+
+`link/handshake.mjs` extends the advert signature domain: after `lanHosts`, append `\0relays:<hex>` where `<hex>` = UTF-8→hex of `{ p: pool, l: listen }` (both sorted by url, `pool` items `{url, rtt}`).
+
+- `sanitizeAdvertRelayFields` (verify/inbound path): pool ≤ `MAX_ADVERT_RELAY_POOL` (16), rtt ∈ [0, `MAX_RTT_MS`], deduped; listen ≤ `MAX_ADVERT_LISTEN_RELAYS` (32), deduped; dropped entries logged. `buildSignedAdvert` (outbound) uses a strict variant that throws on invalid locally-supplied relay fields instead of dropping them.
+- `verifySignedAdvert` now returns `{ nodeHash, relayPool, listenRelays }` (sanitized). `ingest*Advert` passes these through; consumers must use the verified values, never the raw body.
+- **Any tampering with relay fields invalidates the signature** → advert rejected.
+
+## Handshake routing (`selection.mjs`)
+
+`handshakeTargets(nodeHash, attempt)`:
+- **Round 0**: peer-claimed `listenRelays` top 4 by composite score (own health + peer rtt); else local `workingRelays` top 4; else pinned top 4.
+- **Round ≥1**: backoff `min(2000 · 2^(attempt−1), 60000)`; base on `lastGoodNostrRelays` (expanded via `expandFromHistory` ≤ 16), or weighted-random sample of `workingRelays` (weight `1/score`); round-0 core always included; fanout capped at `MAX_ROUTING_FANOUT` (64).
+- Retries ≤ `MAX_ROUTING_ATTEMPTS` (4).
+
+`routePublishEvent(toNodeHash, event, signal)`: publishes to the current round's targets in parallel via shared sessions; any `OK` records `lastGoodNostrRelays` (last 16) + success; all-fail records failures and backs off. `sendNodeSignal` uses routing; an explicit relay override (test/user pin) publishes directly.
+
+## Census (population estimate)
+
+`census.mjs` implements a population census over nostr (event kind 30789, `t=fount` / `x=census`, content = base64 of the signed packet). It is driven by the `features.census` switch (`setP2PFeatures`).
+
+- Each node keeps an inclusion probability `p`; per window it publishes an Ed25519-signed packet `{ nodeHash, nodePubKey, ts, p, sig }` (message `fount-census\0ts\0nodeHash\0p`) when `rand < p`.
+- The multiplier updates `p' = p·(T/E)` (T = `CENSUS_TARGET_EVENTS`, E = observed window events); E == 0 probes upward by `CENSUS_GROW_FACTOR`. `clampP` keeps `p` in `[CENSUS_MIN_P, 1]`.
+- Readers estimate online nodes with the HT estimator `M̂ = Σ(1/p)` (`estimatePopulation` in `census_math.mjs`), subtract the self-event's weight (`−1/p_self`) and add exactly 1 for the self node.
+- Ingress packets are untrusted: `verifyCensusPacket` canonicalizes, checks `ts` within `CENSUS_TTL_MS`, requires `p ∈ [CENSUS_MIN_P, 1]`, and verifies `nodeHash = sha256(nodePubKey)` plus the Ed25519 signature before `noteCensusEvent` stores the event (deduped by `nodeHash`).
+
+## Config
+
+`channels.nostr.relay` (non-empty array) **overrides** the whole relay set — published/subscribed relays come from that list, not the pool. Without it, `resolveNostrRelayUrls()` returns `getListenRelays()`.

package/files/manifest/fetch.mjs

@@ -71,12 +71,10 @@ export async function fetchPublicManifest(context) {
 	if (!shared) return hasLocalPublic ? local : null
 
 	if (hasLocalPublic) {
-		if (wantCache) 
-			void shared.then(async result => {
-				if (result && shouldPreferIncomingPublicManifest(local, result))
-					await cachePublicManifest(ownerEntityHash, logicalPath, result)
-			})
-		
+		if (wantCache) void shared.then(async result => {
+			if (result && shouldPreferIncomingPublicManifest(local, result))
+				await cachePublicManifest(ownerEntityHash, logicalPath, result)
+		})
 		return local
 	}