@steve02081504/fount-p2p 0.0.0

package/utils/json_io.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * @param {string} filePath 绝对路径
+ * @returns {Promise<object | null>} JSON 或 null
+ */
+export async function readJsonFile(filePath) {
+	try {
+		const raw = await fsp.readFile(filePath, 'utf8')
+		return JSON.parse(raw)
+	}
+	catch (err) {
+		if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return null
+		throw err
+	}
+}
+
+/**
+ * @param {string} filePath 绝对路径
+ * @param {unknown} data 可序列化对象
+ * @returns {Promise<void>}
+ */
+export async function writeJsonFile(filePath, data) {
+	await fsp.mkdir(path.dirname(filePath), { recursive: true })
+	const tmp = `${filePath}.tmp`
+	await fsp.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+	await fsp.rename(tmp, filePath)
+}
+
+/**
+ * @param {string} filePath 绝对路径
+ * @returns {object | null} JSON 或 null
+ */
+export function readJsonFileSync(filePath) {
+	try {
+		const raw = fs.readFileSync(filePath, 'utf8')
+		return JSON.parse(raw)
+	}
+	catch (err) {
+		if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return null
+		throw err
+	}
+}
+
+/**
+ * @param {string} filePath 绝对路径
+ * @param {unknown} data 可序列化对象
+ * @returns {void}
+ */
+export function writeJsonFileSync(filePath, data) {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true })
+	const tmp = `${filePath}.tmp`
+	fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+	fs.renameSync(tmp, filePath)
+}

package/utils/lru.mjs

@@ -0,0 +1,22 @@
+/**
+ * @template K, V
+ * @param {number} max 最大条目
+ * @returns {Map<K, V> & { touch: (key: K, value: V) => void }} 带 touch 方法的 LRU Map
+ */
+export function createLruMap(max) {
+	/** @type {Map<K, V>} */
+	const map = new Map()
+	/**
+	 * @param {K} key 键
+	 * @param {V} value 值
+	 */
+	const touch = (key, value) => {
+		if (map.has(key)) map.delete(key)
+		map.set(key, value)
+		while (map.size > max) {
+			const oldest = map.keys().next().value
+			map.delete(oldest)
+		}
+	}
+	return Object.assign(map, { touch })
+}

package/utils/map_pool.mjs

@@ -0,0 +1,27 @@
+/**
+ * 有限并发 map（进程内，无外部依赖）。
+ * @template T, R
+ * @param {T[]} items 待处理项
+ * @param {(item: T, index: number) => Promise<R>} fn 异步映射
+ * @param {number} concurrency 并发上限
+ * @returns {Promise<R[]>} 与 items 同序的结果
+ */
+export async function mapPool(items, fn, concurrency) {
+	if (!items.length) return []
+	const limit = Math.max(1, Math.min(concurrency, items.length))
+	/** @type {R[]} */
+	const results = new Array(items.length)
+	let nextIndex = 0
+
+	/** @returns {Promise<void>} */
+	const worker = async () => {
+		for (; ;) {
+			const i = nextIndex++
+			if (i >= items.length) return
+			results[i] = await fn(items[i], i)
+		}
+	}
+
+	await Promise.all(Array.from({ length: limit }, () => worker()))
+	return results
+}

package/wire/group_part.mjs

@@ -0,0 +1,43 @@
+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 }} ctx 入站上下文
+ * @param {string} groupId 群 ID
+ * @param {import('./part_ingress.mjs').PartWireAdapter} wire Trystero 适配器
+ * @param {{ allowPartInvoke?: (payload: object) => boolean }} [options] 入站过滤
+ * @returns {void}
+ */
+export function attachGroupPartWire(ctx, groupId, wire, options = {}) {
+	attachPartWire(ctx, {
+		send: wire.send.bind(wire),
+		on: wrapWireOn(wire, groupId),
+	}, options)
+}

package/wire/ingress.mjs

@@ -0,0 +1,58 @@
+/**
+ * P2P / Trystero 入站 wire 公共工具（外来网络边界）。
+ */
+import { Buffer } from 'node:buffer'
+
+import { isHex64, isSignatureHex128 } from '../core/hexIds.mjs'
+
+/**
+ * @param {unknown} value 待判定值
+ * @returns {value is Record<string, unknown>} 是否为非 null 的普通对象（非数组）
+ */
+export function isPlainObject(value) {
+	return value != null && !Array.isArray(value) && typeof value === 'object'
+}
+
+/**
+ * 解析 WebSocket / Trystero 入站 JSON 帧。
+ * @param {unknown} raw `ws` message 或字符串
+ * @returns {Record<string, unknown> | null} 解析失败或非对象时为 null
+ */
+export function parseInboundJson(raw) {
+	if (raw == null) return null
+	const text = typeof raw === 'string'
+		? raw
+		: Buffer.isBuffer(raw)
+			? raw.toString('utf8')
+			: String(raw)
+	let parsed
+	try {
+		parsed = JSON.parse(text)
+	}
+	catch {
+		return null
+	}
+	return isPlainObject(parsed) ? parsed : null
+}
+
+/**
+ * @param {unknown} event 单条 DAG 行
+ * @returns {boolean} 是否具备完整远程签名形态
+ */
+export function isSignedDagEventRow(event) {
+	return isPlainObject(event)
+		&& isHex64(event.id)
+		&& isSignatureHex128(event.signature)
+}
+
+/**
+ * 从联邦 `dag_event` 载荷取出已签名事件行。
+ * @param {unknown} payload Trystero 载荷（完整签名事件）
+ * @param {string} groupId 本群 ID
+ * @returns {object | null} 验形通过的事件；否则 null
+ */
+export function extractInboundSignedEvent(payload, groupId) {
+	if (!isSignedDagEventRow(payload)) return null
+	if (payload.groupId && String(payload.groupId) !== groupId) return null
+	return payload
+}

package/wire/part_common.mjs

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,71 @@
+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 => {
+		/**
+		 *
+		 */
+		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
+}
+
+/**
+ * 单向 part_invoke fanout（mailbox put 等）。
+ * @param {string} username 用户
+ * @param {string} partpath part 路径
+ * @param {import('./part_invoke.mjs').PartInvoke} invoke 调用体
+ * @param {number} limit fanout 上限
+ * @param {string} [nodeHash] 来源节点
+ * @param {string} [groupId] 群上下文
+ * @returns {Promise<number>} 发送次数
+ */
+export async function fanoutPartInvoke(username, partpath, invoke, limit, nodeHash, groupId) {
+	return requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).fanoutToTopNodes(username, 'part_invoke', buildPartInvokePayload({
+		partpath,
+		invoke,
+		nodeHash,
+		groupId,
+	}), limit)
+}

package/wire/part_ingress.mjs

@@ -0,0 +1,172 @@
+
+import { dispatchDeliveryInbound, dispatchRpcInbound } from '../registries/inbound.mjs'
+
+import { isPlainObject } from './ingress.mjs'
+import { buildPartInvokePayload } from './part_common.mjs'
+import {
+	isPartInvoke,
+	isPartInvokeResponse,
+	normalizePartpath,
+	unwrapPartInvokeResult,
+} from './part_invoke.mjs'
+
+/** @typedef {import('./part_invoke.mjs').PartInvokeResponse} PartInvokeResponse */
+
+/** @type {Map<string, { responses: PartInvokeResponse[], finish: () => void, maxResponses: number, respondedPeers: Set<string> }>} */
+export const pendingPartInvoke = new Map()
+
+/**
+ * @typedef {{
+ *   send: (name: string, payload: unknown, peerId: string | null) => void
+ *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => void
+ * }} PartWireAdapter
+ */
+
+/**
+ * @typedef {{ replicaUsername?: string }} PartWireContext
+ */
+
+/**
+ * @param {object} data 入站 part_timeline_put 载荷
+ * @param {string} partpath 已规范化 part 路径
+ * @returns {object | null} 白名单字段
+ */
+function parsePartTimelinePut(data, partpath) {
+	const timelineEntityHash = String(data.timelineEntityHash || '').trim().toLowerCase()
+	if (!timelineEntityHash || !isPlainObject(data.event)) return null
+	return {
+		type: 'part_timeline_put',
+		partpath,
+		timelineEntityHash,
+		event: data.event,
+		...data.nodeHash ? { nodeHash: String(data.nodeHash).trim() } : {},
+		...data.groupId ? { groupId: String(data.groupId).trim() } : {},
+	}
+}
+
+/**
+ * @param {PartWireContext} ctx 入站上下文
+ * @param {object} payload part_invoke 请求
+ * @returns {Promise<PartInvokeResponse | null>} RPC 处理器返回值
+ */
+async function dispatchPartInvoke(ctx, payload) {
+	const partpath = normalizePartpath(payload?.partpath)
+	const invoke = payload?.invoke
+	if (!partpath || !isPlainObject(invoke)) return null
+	return dispatchRpcInbound({
+		replicaUsername: ctx.replicaUsername,
+		requesterNodeHash: payload.nodeHash ? String(payload.nodeHash).trim() : null,
+		groupId: payload.groupId ? String(payload.groupId).trim() : undefined,
+		peerId: payload.peerId,
+	}, {
+		type: 'part_invoke',
+		partpath,
+		invoke,
+		nodeHash: payload.nodeHash,
+		groupId: payload.groupId,
+		requestId: payload.requestId,
+	})
+}
+
+/**
+ * 挂载 part_timeline_put / part_invoke / part_invoke_response。
+ * @param {PartWireContext} ctx 入站上下文
+ * @param {PartWireAdapter} wire Trystero 适配器
+ * @param {{ allowPartInvoke?: (payload: object) => boolean }} [options] 入站过滤
+ * @returns {void}
+ */
+export function attachPartWire(ctx, wire, options = {}) {
+	wire.on('part_timeline_put', data => {
+		if (!isPlainObject(data)) return
+		const partpath = normalizePartpath(data.partpath)
+		if (!partpath) return
+		const message = parsePartTimelinePut(data, partpath)
+		if (!message) return
+		void dispatchDeliveryInbound({
+			replicaUsername: ctx.replicaUsername,
+			requesterNodeHash: data.nodeHash ? String(data.nodeHash).trim() : null,
+		}, message)
+	})
+
+	wire.on('part_invoke', (data, peerId) => {
+		if (!isPlainObject(data)) return
+		if (options.allowPartInvoke?.(data) === false) return
+		const payload = { ...data, peerId }
+		if (payload.requestId)
+			void handleIncomingPartInvokeRequest(ctx, payload, wire, peerId)
+		else
+			void handleIncomingPartInvokeFireAndForget(ctx, payload, wire, peerId)
+	})
+
+	wire.on('part_invoke_response', (data, peerId) => {
+		if (!isPlainObject(data)) return
+		handleIncomingPartInvokeResponse(data, peerId)
+	})
+}
+
+/**
+ * @param {PartWireContext} ctx 入站上下文
+ * @param {object} payload part_invoke 请求（含 requestId）
+ * @param {PartWireAdapter} wire 发送适配器
+ * @param {string} peerId 对端
+ * @returns {Promise<void>}
+ */
+export async function handleIncomingPartInvokeRequest(ctx, payload, wire, peerId) {
+	const partpath = normalizePartpath(payload?.partpath)
+	if (!partpath || !payload.requestId) return
+
+	const response = await dispatchPartInvoke(ctx, { ...payload, peerId })
+	if (response == null || !isPartInvokeResponse(response)) return
+
+	try {
+		wire.send('part_invoke_response', {
+			requestId: payload.requestId,
+			partpath,
+			response,
+		}, peerId)
+	}
+	catch { /* disconnected */ }
+}
+
+/**
+ * @param {PartWireContext} ctx 入站上下文
+ * @param {object} payload part_invoke 请求（无 requestId）
+ * @param {PartWireAdapter} wire 发送适配器
+ * @param {string} peerId 对端
+ * @returns {Promise<void>}
+ */
+export async function handleIncomingPartInvokeFireAndForget(ctx, payload, wire, peerId) {
+	const partpath = normalizePartpath(payload?.partpath)
+	if (!partpath) return
+
+	const response = await dispatchPartInvoke(ctx, { ...payload, peerId })
+	const followUp = unwrapPartInvokeResult(response)
+	if (!isPartInvoke(followUp)) return
+	try {
+		wire.send('part_invoke', buildPartInvokePayload({
+			partpath,
+			invoke: followUp,
+			nodeHash: payload.nodeHash,
+			groupId: payload.groupId,
+		}), peerId)
+	}
+	catch { /* disconnected */ }
+}
+
+/**
+ * @param {object} payload 响应
+ * @param {string} [peerId] Trystero 对端 id，用于同 peer 去重
+ * @returns {void}
+ */
+export function handleIncomingPartInvokeResponse(payload, peerId = '') {
+	const pending = pendingPartInvoke.get(String(payload?.requestId || ''))
+	if (!pending || payload?.response == null) return
+	const peerKey = String(peerId || payload?.nodeHash || '').trim()
+	if (peerKey) {
+		if (pending.respondedPeers.has(peerKey)) return
+		pending.respondedPeers.add(peerKey)
+	}
+	if (!isPartInvokeResponse(payload.response)) return
+	pending.responses.push(payload.response)
+	if (pending.responses.length >= pending.maxResponses) pending.finish()
+}

package/wire/part_invoke.mjs

@@ -0,0 +1,81 @@
+import { isPlainObject } from './ingress.mjs'
+
+const PARTPATH_RE = /^[\w-]+(?:\/[\w-]+)*$/
+
+/** @typedef {string} PartInvokeKind */
+
+/**
+ * @typedef {object & { kind: PartInvokeKind }} PartInvoke
+ */
+
+/** @typedef {{ message: string, code: string }} PartInvokeError */
+
+/**
+ * @typedef {object} PartInvokeResultResponse
+ * @property {unknown} result
+ */
+
+/**
+ * @typedef {object} PartInvokeErrorResponse
+ * @property {PartInvokeError} error
+ */
+
+/** @typedef {PartInvokeResultResponse | PartInvokeErrorResponse} PartInvokeResponse */
+
+/**
+ * @typedef {object} SocialRpcPartInvokeResponse
+ * @property {object} result RPC 响应体
+ */
+
+/**
+ * @typedef {object} TimelinePutPartInvokeResponse
+ * @property {{ ok: boolean }} result timeline ingest 结果
+ */
+
+/**
+ * @param {unknown} value 候选响应
+ * @returns {value is PartInvokeResponse} 是否为 part_invoke 响应体
+ */
+export function isPartInvokeResponse(value) {
+	if (!isPlainObject(value)) return false
+	const hasResult = Object.prototype.hasOwnProperty.call(value, 'result')
+	const hasError = Object.prototype.hasOwnProperty.call(value, 'error')
+	if (hasResult === hasError) return false
+	if (hasError) {
+		const err = value.error
+		return isPlainObject(err)
+			&& typeof err.message === 'string'
+			&& err.message.length > 0
+			&& typeof err.code === 'string'
+			&& err.code.length > 0
+	}
+	return true
+}
+
+/**
+ * @param {PartInvokeResponse | null | undefined} response RPC 响应
+ * @returns {unknown | null} 成功 `result`；失败或空为 null
+ */
+export function unwrapPartInvokeResult(response) {
+	if (!response || !isPartInvokeResponse(response) || 'error' in response) return null
+	return response.result ?? null
+}
+
+/**
+ * @param {unknown} value partpath 字符串
+ * @returns {string | null} 规范化 partpath
+ */
+export function normalizePartpath(value) {
+	const path = String(value || '').trim().replace(/^\/+|\/+$/g, '')
+	return PARTPATH_RE.test(path) ? path : null
+}
+
+/**
+ * @param {unknown} value invoke 体
+ * @returns {value is PartInvoke} 是否含已知 kind
+ */
+export function isPartInvoke(value) {
+	if (!isPlainObject(value)) return false
+	const kind = value.kind
+	return typeof kind === 'string' && kind.length > 0
+}

package/wire/rate_bucket.mjs

@@ -0,0 +1,49 @@
+/**
+ * 60 秒令牌桶限速（fed_chunk / fed_emoji 等 want-data 线共用）。
+ */
+
+import { createLruMap } from '../utils/lru.mjs'
+
+const WINDOW_MS = 60_000
+const BUCKET_MAP_MAX = 5000
+
+/** @type {ReturnType<typeof createLruMap<string, { tokens: number, bytes: number, lastRefill: number }>>} */
+const buckets = createLruMap(BUCKET_MAP_MAX)
+
+/**
+ * @param {string} bucketKey 房间或资源键
+ * @param {{ maxCount: number, byteCount?: number, maxBytesPerWindow?: number }} limits 限额
+ * @returns {boolean} 是否允许本次消费
+ */
+export function consumeWireRateBucket(bucketKey, limits) {
+	const byteCount = Math.max(0, Number(limits.byteCount) || 0)
+	const maxBytes = Number(limits.maxBytesPerWindow) || 0
+	const maxCount = limits.maxCount
+	const now = Date.now()
+	let bucket = buckets.get(bucketKey)
+	if (!bucket) {
+		bucket = {
+			tokens: maxCount,
+			bytes: maxBytes > 0 ? maxBytes : Number.POSITIVE_INFINITY,
+			lastRefill: now,
+		}
+		buckets.touch(bucketKey, bucket)
+	}
+	else buckets.touch(bucketKey, bucket)
+	const elapsed = now - bucket.lastRefill
+	if (elapsed > 0) {
+		const rate = maxCount / WINDOW_MS
+		bucket.tokens = Math.min(maxCount, bucket.tokens + elapsed * rate)
+		if (maxBytes > 0) {
+			const byteRate = maxBytes / WINDOW_MS
+			bucket.bytes = Math.min(maxBytes, bucket.bytes + elapsed * byteRate)
+		}
+		bucket.lastRefill = now
+	}
+	if (bucket.tokens < 1) return false
+	if (maxBytes > 0 && bucket.bytes < byteCount) return false
+	bucket.tokens -= 1
+	if (maxBytes > 0) bucket.bytes -= byteCount
+	buckets.touch(bucketKey, bucket)
+	return true
+}