@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/link/providers/ble_gatt.mjs

@@ -4,9 +4,10 @@ import { randomBytes } from 'node:crypto'
 import { normalizeHex64 } from '../../core/hexIds.mjs'
 import { getBtPeerHint } from '../../discovery/bt/peer_hints.mjs'
 import { canUseBluetoothRuntime, loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from '../../discovery/bt/runtime.mjs'
-import { asLinkHandle, coercePipeInbound, createLinkPipe } from '../pipe.mjs'
+import { asLinkHandle } from '../pipe.mjs'
 
 import { LINK_LEVEL_BLE_GATT } from './levels.mjs'
+import { buildLinkOpen, createLinkIdBoundPipe, parseLinkOpen } from './link_id_pipe.mjs'
 
 /** BLE GATT 数据 service UUID。 */
 export const BLE_DATA_SERVICE_UUID = 'f017f017f017f017f017f017f017f019'
@@ -28,19 +29,13 @@ export async function canUseBleGattLink() {
  * @returns {Promise<import('./index.mjs').LinkHandle>} 已启动握手的 link
  */
 async function openGattPipe(options) {
-	const linkId = normalizeHex64(options.linkId)
-	if (!linkId) throw new Error('p2p: ble_gatt linkId required')
-
-	const pipe = createLinkPipe({
+	const pipe = createLinkIdBoundPipe({
 		providerId: 'ble_gatt',
 		level: LINK_LEVEL_BLE_GATT,
 		initiator: !!options.initiator,
+		linkId: options.linkId,
 		nodeHash: options.nodeHash,
 		localIdentity: options.localIdentity,
-		/** @returns {string} 本端 binding（linkId） */
-		getLocalBinding: () => linkId,
-		/** @returns {string} 对端 binding（linkId） */
-		getRemoteBinding: () => linkId,
 		/**
 		 * @param {string} text control JSON
 		 * @returns {Promise<void>}
@@ -60,18 +55,17 @@ async function openGattPipe(options) {
 	})
 
 	const stopNotify = options.onNotify(data => {
-		pipe.handleInbound(coercePipeInbound(data))
+		pipe.handleInbound(data)
 	})
 	pipe.onDown(() => {
 		try { stopNotify() } catch { /* ignore */ }
 	})
 
 	if (options.initiator)
-		await Promise.resolve(options.write(Buffer.from(JSON.stringify({
-			type: 'link-open',
-			linkId,
-			from: options.localIdentity?.nodeHash || '',
-		}), 'utf8')))
+		await Promise.resolve(options.write(Buffer.from(
+			buildLinkOpen(normalizeHex64(options.linkId), options.localIdentity?.nodeHash),
+			'utf8',
+		)))
 
 	await pipe.startHandshake()
 	return asLinkHandle(pipe)
@@ -131,7 +125,7 @@ async function dialBleGatt(options) {
 	/** @type {Set<(data: Buffer) => void>} */
 	const notifyHandlers = new Set()
 	characteristic.on('data', data => {
-		if (data == null) return
+		if (!data) return
 		for (const handler of notifyHandlers)
 			handler(Buffer.from(data))
 	})
@@ -213,9 +207,9 @@ export function createBleGattLinkProvider() {
 			 * @returns {void}
 			 */
 			onWriteRequest(_connection, data, _offset, _withoutResponse, callback) {
-				const buf = Buffer.from(data)
-				if (sessionInbound) sessionInbound(buf)
-				else void acceptPeripheralWrite(buf).catch(() => { })
+				const buffer = Buffer.from(data)
+				if (sessionInbound) sessionInbound(buffer)
+				else void acceptPeripheralWrite(buffer).catch(() => { })
 				callback(bleno.Characteristic.RESULT_SUCCESS)
 			},
 		})
@@ -234,25 +228,19 @@ export function createBleGattLinkProvider() {
 	}
 
 	/**
-	 * @param {Buffer} buf 入站写（首包应为 link-open）
+	 * @param {Buffer} buffer 入站写（首包应为 link-open）
 	 * @returns {Promise<void>}
 	 */
-	async function acceptPeripheralWrite(buf) {
+	async function acceptPeripheralWrite(buffer) {
 		if (activeInbound || acceptInflight || !onInbound || !localIdentity) return
-		let parsed
-		try {
-			parsed = JSON.parse(Buffer.from(buf).toString('utf8'))
-		}
-		catch {
-			return
-		}
-		if (parsed?.type !== 'link-open' || !parsed.linkId) return
+		const opened = parseLinkOpen(buffer)
+		if (!opened) return
 		acceptInflight = true
 		try {
 			const link = await openGattPipe({
 				initiator: false,
-				linkId: parsed.linkId,
-				nodeHash: normalizeHex64(parsed.from) || null,
+				linkId: opened.linkId,
+				nodeHash: opened.from,
 				localIdentity,
 				/**
 				 * @param {Buffer} data 出站

package/link/providers/lan_tcp.mjs

@@ -4,9 +4,10 @@ import net from 'node:net'
 
 import { normalizeHex64 } from '../../core/hexIds.mjs'
 import { getLanPeerHint } from '../../discovery/lan_peer_hints.mjs'
-import { asLinkHandle, coercePipeInbound, createLinkPipe } from '../pipe.mjs'
+import { asLinkHandle } from '../pipe.mjs'
 
 import { LINK_LEVEL_LAN_TCP } from './levels.mjs'
+import { buildLinkOpen, createLinkIdBoundPipe, parseLinkOpen } from './link_id_pipe.mjs'
 
 const MAX_FRAME_BYTES = 1 << 20
 
@@ -85,22 +86,17 @@ function attachLengthPrefix(socket, onPayload) {
 /**
  * 在已挂 codec 的 socket 上创建 pipe。
  * @param {object} options 配置
- * @returns {ReturnType<typeof createLinkPipe>} pipe 句柄
+ * @returns {ReturnType<typeof createLinkIdBoundPipe>} pipe 句柄
  */
 function createTcpPipe(options) {
-	const linkId = normalizeHex64(options.linkId)
-	if (!linkId) throw new Error('p2p: lan_tcp linkId required')
 	const { socket, codec } = options
-	const pipe = createLinkPipe({
+	const pipe = createLinkIdBoundPipe({
 		providerId: 'lan_tcp',
 		level: LINK_LEVEL_LAN_TCP,
 		initiator: !!options.initiator,
+		linkId: options.linkId,
 		nodeHash: options.nodeHash,
 		localIdentity: options.localIdentity,
-		/** @returns {string} 本端 binding（linkId） */
-		getLocalBinding: () => linkId,
-		/** @returns {string} 对端 binding（linkId） */
-		getRemoteBinding: () => linkId,
 		/**
 		 * @param {string} text control JSON
 		 * @returns {void}
@@ -141,8 +137,8 @@ function createTcpPipe(options) {
  * @returns {Promise<import('./index.mjs').LinkHandle>} 已启动握手的 link
  */
 async function openTcpPipe(options) {
-	const socket = options.socket
-	/** @type {ReturnType<typeof createLinkPipe> | null} */
+	const { socket } = options
+	/** @type {ReturnType<typeof createLinkIdBoundPipe> | null} */
 	let pipe = null
 	/** @type {Buffer[]} */
 	const pending = []
@@ -151,19 +147,15 @@ async function openTcpPipe(options) {
 			pending.push(payload)
 			return
 		}
-		pipe.handleInbound(coercePipeInbound(payload))
+		pipe.handleInbound(payload)
 	})
 
 	pipe = createTcpPipe({ ...options, codec, socket })
 	for (const payload of pending.splice(0))
-		pipe.handleInbound(coercePipeInbound(payload))
+		pipe.handleInbound(payload)
 
 	if (options.initiator)
-		codec.write(JSON.stringify({
-			type: 'link-open',
-			linkId: normalizeHex64(options.linkId),
-			from: options.localIdentity?.nodeHash || '',
-		}))
+		codec.write(buildLinkOpen(normalizeHex64(options.linkId), options.localIdentity?.nodeHash))
 
 	await pipe.startHandshake()
 	return asLinkHandle(pipe)
@@ -238,30 +230,23 @@ export function createLanTcpLinkProvider() {
 			socket.destroy()
 			return
 		}
-		/** @type {ReturnType<typeof createLinkPipe> | null} */
+		/** @type {ReturnType<typeof createLinkIdBoundPipe> | null} */
 		let pipe = null
 		const codec = attachLengthPrefix(socket, payload => {
 			if (pipe) {
-				pipe.handleInbound(coercePipeInbound(payload))
+				pipe.handleInbound(payload)
 				return
 			}
-			let parsed
-			try {
-				parsed = JSON.parse(payload.toString('utf8'))
-			}
-			catch {
-				socket.destroy()
-				return
-			}
-			if (parsed?.type !== 'link-open' || !parsed.linkId) {
+			const opened = parseLinkOpen(payload)
+			if (!opened) {
 				socket.destroy()
 				return
 			}
 			try {
 				pipe = createTcpPipe({
 					initiator: false,
-					linkId: parsed.linkId,
-					nodeHash: normalizeHex64(parsed.from) || null,
+					linkId: opened.linkId,
+					nodeHash: opened.from,
 					localIdentity,
 					socket,
 					codec,
@@ -324,7 +309,7 @@ export function createLanTcpLinkProvider() {
 					server.listen(0, '0.0.0.0', () => {
 						server.off('error', reject)
 						const addr = server.address()
-						listenPort = typeof addr === 'object' && addr ? addr.port : 0
+						listenPort = addr?.port || 0
 						resolve()
 					})
 				})

package/link/providers/link_id_pipe.mjs

@@ -0,0 +1,46 @@
+import { Buffer } from 'node:buffer'
+
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { createLinkPipe } from '../pipe.mjs'
+
+/**
+ * 构造 link-open control JSON。
+ * @param {string} linkId 链路 id（64 hex）
+ * @param {string} [fromNodeHash] 本端 nodeHash
+ * @returns {string} JSON 文本
+ */
+export function buildLinkOpen(linkId, fromNodeHash = '') {
+	return JSON.stringify({ type: 'link-open', linkId, from: fromNodeHash || '' })
+}
+
+/**
+ * 解析 link-open；非法返回 null。
+ * @param {string | Uint8Array | Buffer} raw 原始 control
+ * @returns {{ linkId: string, from: string | null } | null} 解析结果
+ */
+export function parseLinkOpen(raw) {
+	let parsed
+	try {
+		parsed = JSON.parse(typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf8'))
+	}
+	catch { return null }
+	if (parsed?.type !== 'link-open' || !parsed.linkId) return null
+	return { linkId: String(parsed.linkId), from: normalizeHex64(parsed.from) || null }
+}
+
+/**
+ * 以固定 linkId 作为 hello/auth binding 的 pipe。
+ * @param {Parameters<typeof createLinkPipe>[0] & { linkId: string }} options pipe 配置（须含 linkId）
+ * @returns {ReturnType<typeof createLinkPipe>} link pipe
+ */
+export function createLinkIdBoundPipe(options) {
+	const linkId = normalizeHex64(options.linkId)
+	if (!linkId) throw new Error(`p2p: ${options.providerId || 'link'} linkId required`)
+	return createLinkPipe({
+		...options,
+		/** @returns {string} 本地 binding */
+		getLocalBinding: () => linkId,
+		/** @returns {string} 远端 binding */
+		getRemoteBinding: () => linkId,
+	})
+}

package/link/providers/webrtc.mjs

@@ -11,10 +11,11 @@ import {
 } from '../channel_mux.mjs'
 import { asLinkHandle, createLinkPipe } from '../pipe.mjs'
 import {
+	attachChannelMessageListener,
 	attachDataChannelListener,
 	attachIceCandidateListener,
 	loadNodeRtcPolyfill,
-	signalDataToBytes,
+	dataToBytes,
 	waitForChannelState,
 } from '../rtc.mjs'
 import { extractDtlsFingerprint } from '../sdp_fingerprint.mjs'
@@ -30,22 +31,6 @@ function formatErrorReason(error) {
 	return String(error?.message ?? error ?? 'unknown-error').replace(/\s+/g, ' ').slice(0, 240)
 }
 
-/**
- * 绑定 data channel message 回调。
- * @param {RTCDataChannel} channel RTC 数据通道
- * @param {(data: unknown) => void} handler 消息处理器
- * @returns {void}
- */
-function attachChannelMessageListener(channel, handler) {
-	channel.addEventListener?.('message', event => handler(event?.data))
-	/**
-	 * @param {MessageEvent} event 消息事件
-	 * @returns {void}
-	 */
-	channel.onmessage = event => handler(event?.data)
-	channel.onMessage?.subscribe(message => handler(message))
-}
-
 let cachedAvailable = null
 
 /**
@@ -83,7 +68,7 @@ export async function createWebRtcLink(options) {
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
 	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
 	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
-	const pc = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
+	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
 	let remoteDescriptionSet = false
@@ -113,9 +98,9 @@ export async function createWebRtcLink(options) {
 		idleTimeoutMs: options.idleTimeoutMs,
 		handshakeTimeoutMs,
 		/** @returns {string} 本端 DTLS fingerprint */
-		getLocalBinding: () => extractDtlsFingerprint(pc.localDescription?.sdp || ''),
+		getLocalBinding: () => extractDtlsFingerprint(peerConnection.localDescription?.sdp || ''),
 		/** @returns {string} 对端 DTLS fingerprint */
-		getRemoteBinding: () => extractDtlsFingerprint(pc.remoteDescription?.sdp || ''),
+		getRemoteBinding: () => extractDtlsFingerprint(peerConnection.remoteDescription?.sdp || ''),
 		/**
 		 * @param {string} text control JSON
 		 * @returns {void}
@@ -141,15 +126,15 @@ export async function createWebRtcLink(options) {
 			sendQueues?.clear()
 			try { controlChannel?.close() } catch { /* ignore */ }
 			try { bulkChannel?.close() } catch { /* ignore */ }
-			try { await pc.close() } catch { /* ignore */ }
+			try { await peerConnection.close() } catch { /* ignore */ }
 		},
 		/**
 		 * @returns {object} WebRTC 附加 stats
 		 */
 		extraStats() {
 			return {
-				connectionState: pc.connectionState,
-				iceConnectionState: pc.iceConnectionState,
+				connectionState: peerConnection.connectionState,
+				iceConnectionState: peerConnection.iceConnectionState,
 				reconnectCount,
 				pending: sendQueues?.pending() ?? { control: 0, bulk: 0 },
 				controlBufferedAmount: controlChannel?.bufferedAmount ?? 0,
@@ -167,10 +152,14 @@ export async function createWebRtcLink(options) {
 	function attachBackpressurePump(channel) {
 		configureBufferedAmountLowThreshold(channel, CHANNEL_LOW_THRESHOLD_BYTES)
 		onBufferedAmountLow(channel, () => {
-			if (channel.label === CHANNEL_CONTROL) controlLowEvents++
-			if (channel.label === CHANNEL_BULK) bulkLowEvents++
-			if (channel.label === CHANNEL_CONTROL) sendQueues?.flush(CHANNEL_CONTROL)
-			if (channel.label === CHANNEL_BULK) sendQueues?.flush(CHANNEL_BULK)
+			if (channel.label === CHANNEL_CONTROL) {
+				controlLowEvents++
+				sendQueues?.flush(CHANNEL_CONTROL)
+			}
+			else if (channel.label === CHANNEL_BULK) {
+				bulkLowEvents++
+				sendQueues?.flush(CHANNEL_BULK)
+			}
 		})
 	}
 
@@ -179,7 +168,7 @@ export async function createWebRtcLink(options) {
 	 * @returns {Promise<void>}
 	 */
 	async function applyRemoteDescription(description) {
-		await pc.setRemoteDescription(description)
+		await peerConnection.setRemoteDescription(description)
 		remoteDescriptionSet = true
 		await flushQueuedIceCandidates()
 	}
@@ -196,9 +185,9 @@ export async function createWebRtcLink(options) {
 	 * @returns {Promise<void>}
 	 */
 	async function waitForIceGatheringComplete() {
-		if (!trickleIceOff || pc.iceGatheringState === 'complete') return
+		if (!trickleIceOff || peerConnection.iceGatheringState === 'complete') return
 		const deadline = Date.now() + handshakeTimeoutMs
-		while (pc.iceGatheringState !== 'complete' && Date.now() < deadline)
+		while (peerConnection.iceGatheringState !== 'complete' && Date.now() < deadline)
 			await new Promise(resolve => setTimeout(resolve, 50))
 	}
 
@@ -206,11 +195,11 @@ export async function createWebRtcLink(options) {
 	 * @returns {Promise<void>}
 	 */
 	async function flushQueuedIceCandidates() {
-		if (!remoteDescriptionSet || !pc.localDescription) return
+		if (!remoteDescriptionSet || !peerConnection.localDescription) return
 		while (remoteSignalQueue.length) {
 			const candidate = remoteSignalQueue.shift()
 			try {
-				await pc.addIceCandidate(candidate)
+				await peerConnection.addIceCandidate(candidate)
 			}
 			catch (error) {
 				if (shouldRetryQueuedIce(error)) {
@@ -227,33 +216,35 @@ export async function createWebRtcLink(options) {
 	 * @returns {Promise<void>}
 	 */
 	async function handleRemoteSignal(message) {
-		if (!message || typeof message !== 'object') return
-		const signalKey = JSON.stringify(message)
+		if (!message?.type) return
+		const signalKey = message.type === 'ice' && message.candidate
+			? `ice:${message.candidate.candidate ?? ''}:${message.candidate.sdpMid ?? ''}:${message.candidate.sdpMLineIndex ?? ''}`
+			: JSON.stringify(message)
 		if (seenRemoteSignals.has(signalKey)) return
 		seenRemoteSignals.touch(signalKey, true)
 		if (message.type === 'description' && message.description) {
-			if (message.description.type === 'answer' && pc.signalingState === 'stable') return
+			if (message.description.type === 'answer' && peerConnection.signalingState === 'stable') return
 			await applyRemoteDescription(message.description)
 			if (message.description.type === 'offer') {
-				const answer = await pc.createAnswer()
-				await pc.setLocalDescription(answer)
+				const answer = await peerConnection.createAnswer()
+				await peerConnection.setLocalDescription(answer)
 				await flushQueuedIceCandidates()
 				await waitForIceGatheringComplete()
 				await sendSignal({
 					type: 'description',
-					description: pc.localDescription?.toJSON?.() ?? pc.localDescription ?? answer,
+					description: peerConnection.localDescription?.toJSON?.() ?? peerConnection.localDescription ?? answer,
 				})
 				await pipe.maybeSendAuth()
 			}
 			return
 		}
 		if (message.type === 'ice' && message.candidate) {
-			if (!remoteDescriptionSet || !pc.localDescription || pc.signalingState !== 'stable') {
+			if (!remoteDescriptionSet || !peerConnection.localDescription || peerConnection.signalingState !== 'stable') {
 				remoteSignalQueue.push(message.candidate)
 				return
 			}
 			try {
-				await pc.addIceCandidate(message.candidate)
+				await peerConnection.addIceCandidate(message.candidate)
 			}
 			catch (error) {
 				if (shouldRetryQueuedIce(error)) {
@@ -276,7 +267,7 @@ export async function createWebRtcLink(options) {
 		attachChannelMessageListener(channel, data => {
 			try {
 				if (typeof data === 'string') pipe.handleInbound(data)
-				else pipe.handleInbound(signalDataToBytes(data))
+				else pipe.handleInbound(dataToBytes(data))
 			}
 			catch { /* drop */ }
 		})
@@ -307,36 +298,36 @@ export async function createWebRtcLink(options) {
 		void handleRemoteSignal(message).catch(error => pipe.close(`signal-error:${formatErrorReason(error)}`))
 	}) ?? null
 
-	attachIceCandidateListener(pc, event => {
+	attachIceCandidateListener(peerConnection, event => {
 		if (trickleIceOff || !event.candidate) return
 		void sendSignal({
 			type: 'ice',
 			candidate: typeof event.candidate.toJSON === 'function' ? event.candidate.toJSON() : event.candidate,
 		}).catch(error => pipe.close(`signal-send-failed:${formatErrorReason(error)}`))
 	})
-	attachDataChannelListener(pc, event => {
+	attachDataChannelListener(peerConnection, event => {
 		void attachChannel(event.channel)
 			.then(() => maybeStartPostOpenFlow())
 			.catch(error => pipe.close(`channel-attach-failed:${error?.message ?? error}`))
 	})
 
 	/** 连接失败/关闭时关掉 pipe。 */
-	pc.onconnectionstatechange = () => {
-		if (['failed', 'closed', 'disconnected'].includes(pc.connectionState)) {
+	peerConnection.onconnectionstatechange = () => {
+		if (['failed', 'closed', 'disconnected'].includes(peerConnection.connectionState)) {
 			reconnectCount++
-			void pipe.close(`connection-${pc.connectionState}`)
+			void pipe.close(`connection-${peerConnection.connectionState}`)
 		}
 	}
 
 	if (options.initiator) {
-		await attachChannel(pc.createDataChannel(CHANNEL_CONTROL))
-		await attachChannel(pc.createDataChannel(CHANNEL_BULK))
-		const offer = await pc.createOffer()
-		await pc.setLocalDescription(offer)
+		await attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
+		await attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
+		const offer = await peerConnection.createOffer()
+		await peerConnection.setLocalDescription(offer)
 		await waitForIceGatheringComplete()
 		await sendSignal({
 			type: 'description',
-			description: pc.localDescription?.toJSON?.() ?? pc.localDescription ?? offer,
+			description: peerConnection.localDescription?.toJSON?.() ?? peerConnection.localDescription ?? offer,
 		})
 	}
 

package/link/rtc.mjs

@@ -1,7 +1,8 @@
 import process from 'node:process'
 
+import { toBytes } from '../core/bytes_codec.mjs'
 import { getSignalingRuntimeConfig } from '../node/instance.mjs'
-import { wrapRtcPeerConnectionForMdns } from '../transport/rtc_mdns_filter.mjs'
+import { wrapRtcPeerConnectionForIceLocalHostname } from '../transport/rtc_ice_local_hostname.mjs'
 
 /**
  * 注册进程退出时销毁 libdatachannel 全部原生资源（仅一次）。
@@ -19,9 +20,9 @@ process.on('exit', () => {
  */
 export async function loadNodeRtcPolyfill() {
 	const mod = await import('node-datachannel/polyfill')
-	const { mdnsPolicy } = getSignalingRuntimeConfig()
+	const { iceLocalHostnamePolicy } = getSignalingRuntimeConfig()
 	return {
-		RTCPeerConnection: wrapRtcPeerConnectionForMdns(mod.RTCPeerConnection, mod.RTCIceCandidate, mdnsPolicy),
+		RTCPeerConnection: wrapRtcPeerConnectionForIceLocalHostname(mod.RTCPeerConnection, mod.RTCIceCandidate, iceLocalHostnamePolicy),
 		RTCIceCandidate: mod.RTCIceCandidate,
 	}
 }
@@ -96,14 +97,25 @@ export function waitForChannelState(channel, eventName, timeoutMs) {
 }
 
 /**
- * 将信令/消息数据统一转为 Uint8Array。
- * @param {unknown} data 原始数据（字符串、ArrayBuffer、TypedArray 等）
- * @returns {Uint8Array} 字节视图
+ * 绑定 data channel message 回调（addEventListener / onmessage / onMessage.subscribe）。
+ * @param {RTCDataChannel} channel data channel
+ * @param {(data: unknown) => void} handler 消息回调
+ * @returns {void}
+ */
+export function attachChannelMessageListener(channel, handler) {
+	channel.addEventListener?.('message', event => handler(event?.data))
+	/**
+	 * @param {{ data?: unknown }} event message 事件
+	 * @returns {void}
+	 */
+	channel.onmessage = event => handler(event?.data)
+	channel.onMessage?.subscribe(message => handler(message))
+}
+
+/**
+ * @param {unknown} data 通道原始数据
+ * @returns {Uint8Array} 字节
  */
-export function signalDataToBytes(data) {
-	if (data instanceof Uint8Array) return data
-	if (data instanceof ArrayBuffer) return new Uint8Array(data)
-	if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
-	if (typeof data === 'string') return new TextEncoder().encode(data)
-	return new TextEncoder().encode(String(data ?? ''))
+export function dataToBytes(data) {
+	return toBytes(data, { allowString: true })
 }

package/mailbox/consumer_registry.mjs

@@ -54,8 +54,8 @@ export async function dispatchMailboxRecordsToConsumers(username, records) {
 			const ids = await handler(username, scoped)
 			for (const id of ids || []) delivered.add(String(id))
 		}
-		catch (err) {
-			console.error('mailbox: consumer batch failed, retry per record', err)
+		catch (error) {
+			console.error('mailbox: consumer batch failed, retry per record', error)
 			for (const row of scoped)
 				try {
 					const ids = await handler(username, [row])

package/mailbox/deliver_or_store.mjs

@@ -1,6 +1,6 @@
 import { normalizeHex64 } from '../core/hexIds.mjs'
 import { getNodeTransportSettings, getNodeHash } from '../node/identity.mjs'
-import { deliverToUserRoomPeers, ensureUserRoom } from '../transport/user_room.mjs'
+import { activeLinkRoster, deliverToUserRoomPeers } from '../transport/user_room.mjs'
 import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../trust_graph/registry.mjs'
 
 import { allowMailboxRelayForTier } from './importance.mjs'
@@ -23,9 +23,9 @@ import {
  * @returns {Promise<string | null>} 已验证的 remote nodeHash
  */
 async function resolveRemoteNodeHashForPeer(username, peerId) {
+	void username
 	if (!peerId) return null
-	const slot = await ensureUserRoom({ replicaUsername: username })
-	const entry = slot?.getRoster()?.find(row => row.peerId === peerId)
+	const entry = activeLinkRoster().find(row => row.peerId === peerId)
 	const remote = entry?.remoteNodeHash?.trim().toLowerCase()
 	return remote || null
 }
@@ -51,9 +51,9 @@ async function resolveRelayHopForIngress(record) {
  * @returns {Promise<{ maxHop: number, relayFanoutTrusted: number, relayFanoutNormal: number, wantFanout: number, batterySaver: boolean }>} 按在线 peer 数缩放的路由
  */
 async function resolveRouting(username) {
+	void username
 	const { batterySaver, mailbox } = getNodeTransportSettings()
-	const slot = await ensureUserRoom({ replicaUsername: username })
-	const peerCount = slot?.getRoster()?.length ?? 0
+	const peerCount = activeLinkRoster().length
 	return resolveMailboxRoutingForPeerCount(peerCount, mailbox, batterySaver)
 }
 
@@ -147,7 +147,7 @@ export async function respondMailboxWant(want, sendGive, peerId) {
 	const { getMailboxRecords, takeMailboxForRecipient } = await import('./store.mjs')
 	const recipient = normalizeHex64(want.toPubKeyHash)
 	if (!recipient) return
-	const ids = Array.isArray(want.ids) ? want.ids : []
+	const ids = want.ids || []
 	const rows = (ids.length
 		? await getMailboxRecords(ids)
 		: await takeMailboxForRecipient(recipient)

package/mailbox/wire.mjs

@@ -11,30 +11,34 @@ import { parseMailboxGive, parseMailboxPut, parseMailboxWant } from './parse.mjs
 
 /**
  * @param {MailboxWireContext} wireContext 入站上下文
- * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire Trystero 适配器
- * @returns {void}
+ * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => (() => void) | void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire Trystero 适配器
+ * @returns {() => void} 取消挂载的 dispose
  */
 export function attachMailboxWire(wireContext, wire) {
-	wire.on('mailbox_put', (payload, peerId) => {
-		const put = parseMailboxPut(payload)
-		if (!put.ok) return
-		void ingestMailboxPut(wireContext, put.value, peerId).catch(err => console.error('mailbox: put ingest failed', err))
-	})
-
-	wire.on('mailbox_want', (payload, peerId) => {
-		const want = parseMailboxWant(payload)
-		if (!want.ok) return
-		void respondMailboxWant(want.value, (giveWire, targetPeerId) => {
-			try {
-				wire.send('mailbox_give', giveWire, targetPeerId)
-			}
-			catch { /* disconnected */ }
-		}, peerId).catch(err => console.error('mailbox: want failed', err))
-	})
-
-	wire.on('mailbox_give', payload => {
-		const give = parseMailboxGive(payload)
-		if (!give.ok) return
-		void ingestMailboxGive(wireContext, give.value).catch(err => console.error('mailbox: give ingest failed', err))
-	})
+	const offs = [
+		wire.on('mailbox_put', (payload, peerId) => {
+			const put = parseMailboxPut(payload)
+			if (!put.ok) return
+			void ingestMailboxPut(wireContext, put.value, peerId).catch(error => console.error('mailbox: put ingest failed', error))
+		}),
+		wire.on('mailbox_want', (payload, peerId) => {
+			const want = parseMailboxWant(payload)
+			if (!want.ok) return
+			void respondMailboxWant(want.value, (giveWire, targetPeerId) => {
+				try {
+					wire.send('mailbox_give', giveWire, targetPeerId)
+				}
+				catch { /* disconnected */ }
+			}, peerId).catch(error => console.error('mailbox: want failed', error))
+		}),
+		wire.on('mailbox_give', payload => {
+			const give = parseMailboxGive(payload)
+			if (!give.ok) return
+			void ingestMailboxGive(wireContext, give.value).catch(error => console.error('mailbox: give ingest failed', error))
+		}),
+	]
+	return () => {
+		for (const off of offs)
+			try { off?.() } catch { /* ignore */ }
+	}
 }