@steve02081504/fount-p2p 0.0.22 → 0.0.24

package/transport/node_scope.mjs

@@ -1,289 +0,0 @@
-import { attachNodeScopeFedChunkResponder } from '../files/chunk_responder.mjs'
-import { attachMailboxWire } from '../mailbox/wire.mjs'
-import { attachPartWire } from '../wire/part_ingress.mjs'
-import { attachPartQueryWire } from '../wire/part_query.mjs'
-
-import { sendToNodeLink, subscribeScope } from './link_registry.mjs'
-
-/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
-const nodeActionHandlers = new Map()
-
-/** @type {Set<(context: NodeScopeContext, wire: NodeScopeWire) => void>} */
-const nodeScopeWireHooks = new Set()
-
-/** @type {NodeScopeContext} */
-const nodeScopeContext = { replicaUsername: '' }
-
-/** @type {NodeScopeWire | null} */
-let nodeScopeWire = null
-
-/** @type {(() => void) | null} */
-let nodeScopeSubscribeCleanup = null
-
-/** @type {Set<() => void>} */
-const nodeScopeFeatureDisposers = new Set()
-
-/** @type {Map<string, { count: number, disposeCore: () => void }>} */
-const featureAttachRefs = new Map()
-
-/**
- * @typedef {{ replicaUsername: string }} NodeScopeContext
- */
-
-/**
- * @typedef {{
- *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => () => void
- *   send: (name: string, payload: unknown, peerId: string | null) => void
- * }} NodeScopeWire
- */
-
-/**
- * @param {string} peerId 对端 nodeHash
- * @param {string} action 动作名
- * @param {unknown} payload 载荷
- * @returns {Promise<boolean>} 是否成功发出
- */
-const sendNodeAction = (peerId, action, payload) =>
-	sendToNodeLink(peerId, { scope: 'node', action, payload })
-
-/**
- * @returns {NodeScopeWire} node scope 的 wire 适配器
- */
-function createNodeScopeWire() {
-	return {
-		/**
-		 * @param {string} name - action 名
-		 * @param {(payload: unknown, peerId: string) => void} handler - 入站处理器
-		 * @returns {() => void} 取消注册的 dispose
-		 */
-		on(name, handler) {
-			if (!nodeActionHandlers.has(name)) nodeActionHandlers.set(name, new Set())
-			nodeActionHandlers.get(name).add(handler)
-			return () => {
-				const set = nodeActionHandlers.get(name)
-				if (!set) return
-				set.delete(handler)
-				if (!set.size) nodeActionHandlers.delete(name)
-			}
-		},
-		/**
-		 * @param {string} name - action 名
-		 * @param {unknown} payload - 出站载荷
-		 * @param {string | null} peerId - 目标 peer，null 时忽略
-		 * @returns {void}
-		 */
-		send(name, payload, peerId) {
-			if (!peerId) return
-			void sendNodeAction(peerId, name, payload).catch(() => { })
-		},
-	}
-}
-
-/**
- * @returns {boolean} 是否已订阅 node scope
- */
-export function isNodeScopeSubscribed() {
-	return nodeScopeSubscribeCleanup != null
-}
-
-/**
- * @param {string} action - action 名
- * @returns {boolean} 是否已挂载处理器
- */
-export function hasNodeScopeAction(action) {
-	return (nodeActionHandlers.get(action)?.size ?? 0) > 0
-}
-
-/**
- * @param {string} action - action 名
- * @returns {number} 已注册的处理器数量
- */
-export function countNodeScopeActionHandlers(action) {
-	return nodeActionHandlers.get(action)?.size ?? 0
-}
-
-/**
- * 测试/调试：直接派发已挂载的 node action。
- * @param {string} action - action 名
- * @param {unknown} payload - 载荷
- * @param {string} peerId - 发送方 nodeHash
- * @returns {boolean} 是否有处理器被调用
- */
-export function dispatchNodeScopeAction(action, payload, peerId) {
-	const handlers = nodeActionHandlers.get(action)
-	if (!handlers?.size) return false
-	for (const handler of handlers)
-		try { handler(payload, peerId) } catch { /* ignore */ }
-	return true
-}
-
-/**
- * @returns {NodeScopeWire | null} 当前 wire，未 ensure 时为 null
- */
-export function getNodeScopeWire() {
-	return nodeScopeWire
-}
-
-/**
- * @returns {NodeScopeContext} 可变 node scope 上下文
- */
-export function getNodeScopeContext() {
-	return nodeScopeContext
-}
-
-/**
- * 只订阅 node scope 派发，不挂任何 feature。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消订阅的 dispose
- */
-export function ensureNodeScope(options = {}) {
-	if (options.replicaUsername != null)
-		nodeScopeContext.replicaUsername = String(options.replicaUsername)
-	if (nodeScopeSubscribeCleanup) return nodeScopeSubscribeCleanup
-	nodeScopeSubscribeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
-		const handlers = nodeActionHandlers.get(envelope.action)
-		if (!handlers?.size) return
-		for (const handler of handlers)
-			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
-	})
-	if (!nodeScopeWire) {
-		nodeScopeWire = createNodeScopeWire()
-		for (const hook of nodeScopeWireHooks)
-			try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
-	}
-	return nodeScopeSubscribeCleanup
-}
-
-/**
- * @param {(context: NodeScopeContext, wire: NodeScopeWire) => void} hook - wire 创建时回调
- * @returns {() => void} 取消注册的 dispose
- */
-export function registerNodeScopeWireHook(hook) {
-	nodeScopeWireHooks.add(hook)
-	if (nodeScopeWire)
-		try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
-	return () => nodeScopeWireHooks.delete(hook)
-}
-
-/**
- * @param {() => void} dispose - feature 卸载函数
- * @returns {() => void} 包装后的 dispose（同时从跟踪集移除）
- */
-function trackFeatureDisposer(dispose) {
-	nodeScopeFeatureDisposers.add(dispose)
-	return () => {
-		dispose()
-		nodeScopeFeatureDisposers.delete(dispose)
-	}
-}
-
-/**
- * 同一 feature 多次 attach 共享一份 wire；dispose 引用计数归零才卸。
- * @param {string} key - feature 去重键
- * @param {() => () => void} attachCore - 首次 attach 时执行，返回核心 dispose
- * @returns {() => void} 引用计数包装的 dispose
- */
-function attachFeatureRefCounted(key, attachCore) {
-	let entry = featureAttachRefs.get(key)
-	if (!entry) {
-		entry = { count: 0, disposeCore: attachCore() }
-		featureAttachRefs.set(key, entry)
-	}
-	entry.count++
-	return trackFeatureDisposer(() => {
-		const cur = featureAttachRefs.get(key)
-		if (!cur) return
-		cur.count--
-		if (cur.count > 0) return
-		cur.disposeCore()
-		featureAttachRefs.delete(key)
-	})
-}
-
-/**
- * 自定义 node scope feature（与 mailbox/part 相同 refcount 语义）。
- * @param {string} key - feature 去重键
- * @param {(wire: NodeScopeWire, context: NodeScopeContext) => () => void} attachCore - 首次 attach 注册 handler，返回核心 dispose
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 引用计数包装的 dispose
- */
-export function attachNodeScopeFeature(key, attachCore, options = {}) {
-	ensureNodeScope(options)
-	return attachFeatureRefCounted(key, () => attachCore(nodeScopeWire, nodeScopeContext))
-}
-
-/**
- * refcount 挂载 mailbox wire。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消挂载的 dispose
- */
-export function attachNodeScopeMailbox(options = {}) {
-	ensureNodeScope(options)
-	return attachFeatureRefCounted('mailbox', () => attachMailboxWire(nodeScopeContext, nodeScopeWire))
-}
-
-/**
- * refcount 挂载 part ingress wire。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消挂载的 dispose
- */
-export function attachNodeScopePart(options = {}) {
-	ensureNodeScope(options)
-	return attachFeatureRefCounted('part', () => attachPartWire(nodeScopeContext, nodeScopeWire))
-}
-
-/**
- * refcount 挂载 part_query wire。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消挂载的 dispose
- */
-export function attachNodeScopePartQuery(options = {}) {
-	ensureNodeScope(options)
-	return attachFeatureRefCounted('partQuery', () => attachPartQueryWire(nodeScopeContext, nodeScopeWire))
-}
-
-/**
- * refcount 挂载 fed chunk responder。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消挂载的 dispose
- */
-export function attachNodeScopeChunks(options = {}) {
-	ensureNodeScope(options)
-	return attachFeatureRefCounted('chunks', () =>
-		attachNodeScopeFedChunkResponder(() => nodeScopeContext.replicaUsername, nodeScopeWire))
-}
-
-/**
- * 全业务 preset（等价旧 ensureNodeScopeRuntime 默认行为）。
- * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
- * @returns {() => void} 取消全部 preset 挂载的 dispose
- */
-export function attachUserRoomDefaultWires(options = {}) {
-	const disposers = [
-		attachNodeScopePart(options),
-		attachNodeScopePartQuery(options),
-		attachNodeScopeMailbox(options),
-		attachNodeScopeChunks(options),
-	]
-	return () => {
-		for (const dispose of disposers) dispose()
-	}
-}
-
-/**
- * 卸掉 feature 挂载；可选保留 node scope 订阅。
- * @param {{ keepSubscribe?: boolean }} [options] - true 时保留 node scope 订阅
- * @returns {void}
- */
-export function stopNodeScopeRuntime(options = {}) {
-	for (const dispose of [...nodeScopeFeatureDisposers]) dispose()
-	nodeScopeFeatureDisposers.clear()
-	for (const entry of featureAttachRefs.values())
-		try { entry.disposeCore() } catch { /* ignore */ }
-	featureAttachRefs.clear()
-	if (options.keepSubscribe) return
-	nodeScopeSubscribeCleanup?.()
-	nodeScopeSubscribeCleanup = null
-	nodeScopeWire = null
-	nodeActionHandlers.clear()
-}

package/wire/group_part.mjs

@@ -1,43 +0,0 @@
-import { isPlainObject } from './ingress.mjs'
-import { attachPartWire } from './part_ingress.mjs'
-
-/**
- * @param {unknown} data part_invoke 载荷
- * @param {string} groupId 群 ID
- * @returns {object | null} 校验通过后的载荷
- */
-function assertGroupContext(data, groupId) {
-	if (!isPlainObject(data)) return null
-	if (data.groupId !== groupId) return null
-	return data
-}
-
-/**
- * @param {import('./part_ingress.mjs').PartWireAdapter} wire 底层适配器
- * @param {string} groupId 群 ID
- * @returns {import('./part_ingress.mjs').PartWireAdapter['on']} 注入 groupId 的 on 包装
- */
-function wrapWireOn(wire, groupId) {
-	return (name, handler) => {
-		wire.on(name, (data, peerId) => {
-			const payload = assertGroupContext(data, groupId)
-			if (!payload) return
-			handler(payload, peerId)
-		})
-	}
-}
-
-/**
- * 群联邦房间挂载 part_wire（要求线载荷带 `groupId`）。
- * @param {{ replicaUsername?: string }} wireContext 入站上下文
- * @param {string} groupId 群 ID
- * @param {import('./part_ingress.mjs').PartWireAdapter} wire Trystero 适配器
- * @param {{ allowPartInvoke?: (payload: object) => boolean }} [options] 入站过滤
- * @returns {void}
- */
-export function attachGroupPartWire(wireContext, groupId, wire, options = {}) {
-	attachPartWire(wireContext, {
-		send: wire.send.bind(wire),
-		on: wrapWireOn(wire, groupId),
-	}, options)
-}

package/wire/part_common.mjs

@@ -1,55 +0,0 @@
-import { unwrapPartInvokeResult } from './part_invoke.mjs'
-
-/** 时间线 part_timeline_put fanout 上限 */
-export const TIMELINE_FANOUT_LIMIT = 8
-/** part_invoke RPC collect 默认响应数 */
-export const PART_INVOKE_FANOUT_DEFAULT = 6
-/** User Room 随机 peer 转发默认上限 */
-export const USER_ROOM_PEER_FANOUT_DEFAULT = 6
-
-/**
- * @param {object} fields 载荷字段
- * @param {string} fields.partpath part 路径
- * @param {import('./part_invoke.mjs').PartInvoke} fields.invoke 调用体
- * @param {string} [fields.nodeHash] 来源节点
- * @param {string} [fields.requestId] RPC 请求 id
- * @param {string} [fields.groupId] 群上下文（mailbox give ingest）
- * @returns {object} part_invoke 线载荷
- */
-export function buildPartInvokePayload({ partpath, invoke, nodeHash, requestId, groupId }) {
-	return {
-		partpath,
-		invoke,
-		...nodeHash ? { nodeHash } : {},
-		...requestId ? { requestId } : {},
-		...groupId ? { groupId } : {},
-	}
-}
-
-/**
- * @param {import('./part_invoke.mjs').PartInvokeResponse[]} results collect 原始结果
- * @returns {object[]} 仅含成功 result 的载荷
- */
-export function partInvokeDataRows(results) {
-	/** @type {object[]} */
-	const rows = []
-	for (const row of results) {
-		const data = unwrapPartInvokeResult(row)
-		if (data != null) rows.push(/** @type {object} */ data)
-	}
-	return rows
-}
-
-/**
- * @param {import('./part_invoke.mjs').PartInvokeResponse[]} results collect 原始结果
- * @returns {string[]} 邻居返回的错误信息
- */
-export function partInvokeErrorMessages(results) {
-	/** @type {string[]} */
-	const errors = []
-	for (const row of results) {
-		const message = row?.error?.message
-		if (message) errors.push(message)
-	}
-	return errors
-}

package/wire/part_fanout.mjs

@@ -1,52 +0,0 @@
-import { randomUUID } from 'node:crypto'
-
-import { getNodeHash } from '../node/identity.mjs'
-import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../trust_graph/registry.mjs'
-
-import {
-	buildPartInvokePayload,
-	PART_INVOKE_FANOUT_DEFAULT,
-} from './part_common.mjs'
-import { pendingPartInvoke } from './part_ingress.mjs'
-
-/** @typedef {import('./part_invoke.mjs').PartInvokeResponse} PartInvokeResponse */
-
-/**
- * @param {string} username 用户（trust graph fanout 上下文）
- * @param {string} partpath part 路径
- * @param {import('./part_invoke.mjs').PartInvoke} invoke 调用体
- * @param {number} [timeoutMs=2500] 超时
- * @param {number} [maxResponses=6] 最多响应数
- * @returns {Promise<PartInvokeResponse[]>} 邻居 PartInvokeResponse（含 error）
- */
-export async function collectPartInvokeResponses(username, partpath, invoke, timeoutMs = 2500, maxResponses = PART_INVOKE_FANOUT_DEFAULT) {
-	const requestId = randomUUID()
-	const nodeHash = getNodeHash()
-	/** @type {PartInvokeResponse[]} */
-	const responses = []
-
-	const waitForResponses = new Promise(resolve => {
-		/**
-		 * 超时或收齐响应后结束等待并清理 pending part_invoke。
-		 */
-		const finish = () => {
-			clearTimeout(timer)
-			pendingPartInvoke.delete(requestId)
-			resolve(responses)
-		}
-		const timer = setTimeout(finish, timeoutMs)
-		pendingPartInvoke.set(requestId, { responses, finish, maxResponses, respondedPeers: new Set() })
-	})
-
-	const sent = await requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).fanoutToTopNodes(username, 'part_invoke', buildPartInvokePayload({
-		partpath,
-		invoke,
-		nodeHash,
-		requestId,
-	}), maxResponses)
-
-	const pending = pendingPartInvoke.get(requestId)
-	if (pending && sent === 0) pending.finish()
-
-	return waitForResponses
-}