@steve02081504/fount-p2p 0.0.0

package/entity/presentation_registry.mjs

@@ -0,0 +1,44 @@
+/** @typedef {{ query?: { locales?: string | string[] } }} ExpressLikeRequest */
+
+/** @type {((replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>) | null} */
+let infoDefaultsProvider = null
+
+/** @type {((req: ExpressLikeRequest, replicaUsername: string) => string[]) | null} */
+let localesFromRequestProvider = null
+
+/**
+ * @param {(replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>} provider 资料默认值解析器
+ * @returns {void}
+ */
+export function registerEntityPresentationProvider(provider) {
+	infoDefaultsProvider = provider
+}
+
+/**
+ * @param {(req: ExpressLikeRequest, replicaUsername: string) => string[]} provider 请求区域设置解析器
+ * @returns {void}
+ */
+export function registerLocalesFromRequestProvider(provider) {
+	localesFromRequestProvider = provider
+}
+
+/**
+ * @param {string} replicaUsername 查看者 replica
+ * @param {string} entityHash 目标实体
+ * @param {string[]} locales 区域设置优先级
+ * @returns {Promise<object | null>} 展示默认值或 null
+ */
+export async function resolveInfoDefaultsForEntity(replicaUsername, entityHash, locales) {
+	if (!infoDefaultsProvider) return null
+	return infoDefaultsProvider(replicaUsername, entityHash, locales)
+}
+
+/**
+ * @param {ExpressLikeRequest} req HTTP 请求
+ * @param {string} replicaUsername 查看者 replica
+ * @returns {string[]} 区域设置列表
+ */
+export function localesFromRequest(req, replicaUsername) {
+	if (localesFromRequestProvider) return localesFromRequestProvider(req, replicaUsername)
+	return ['zh-CN', 'en-UK']
+}

package/entity/profile.mjs

@@ -0,0 +1,256 @@
+import { parseEntityHash } from '../core/entity_id.mjs'
+import { getEntityStore } from '../node/instance.mjs'
+
+import { profileAvatarFileUrl } from './files/url.mjs'
+import {
+	applyAvatarToAllLocales,
+	normalizeLocalizedMap,
+	resolveProfilePresentation,
+} from './localized_core.mjs'
+import { resolveInfoDefaultsForEntity } from './presentation_registry.mjs'
+import { isWritableLocalEntity } from './replica.mjs'
+
+/** 超过该毫秒未心跳则视为离线 */
+const HEARTBEAT_STALE_MS = 120_000
+
+const MANUAL_STATUSES = new Set(['online', 'idle', 'dnd', 'invisible', 'away', 'busy', 'offline'])
+const PROFILE_JSON = 'profile.json'
+
+/**
+ * @param {string} entityHash 128 位 entityHash
+ * @param {{ nodeHash: string, subjectHash: string }} parsed parseEntityHash 结果
+ * @returns {object} 默认资料
+ */
+function getDefaultProfile(entityHash, parsed) {
+	return {
+		entityHash,
+		nodeHash: parsed.nodeHash,
+		subjectHash: parsed.subjectHash,
+		localized: {},
+		status: 'online',
+		customStatus: '',
+		lastSeenAt: 0,
+		stats: {
+			joinedAt: Date.now(),
+			messageCount: 0,
+			groupCount: 0,
+			channelCount: 0,
+		},
+	}
+}
+
+/**
+ * @param {object} profileData 原始对象
+ * @returns {object} 可写入磁盘的资料
+ */
+function toStoredProfile(profileData) {
+	return {
+		entityHash: profileData.entityHash,
+		nodeHash: profileData.nodeHash,
+		subjectHash: profileData.subjectHash,
+		localized: normalizeLocalizedMap(profileData.localized),
+		status: profileData.status || 'online',
+		customStatus: String(profileData.customStatus || '').trim(),
+		lastSeenAt: profileData.lastSeenAt || 0,
+		stats: {
+			joinedAt: profileData.stats?.joinedAt || Date.now(),
+			messageCount: profileData.stats?.messageCount || 0,
+			groupCount: profileData.stats?.groupCount || 0,
+			channelCount: profileData.stats?.channelCount || 0,
+		},
+	}
+}
+
+/**
+ * @param {object} profile 用户资料
+ * @param {string} [viewerEntityHash] 查看者 entityHash
+ * @param {{ isSelf?: boolean }} [options] isSelf 为 true 时隐身对本人可见
+ * @returns {string} 有效状态
+ */
+export function computeEffectiveStatus(profile, viewerEntityHash, options = {}) {
+	const stored = String(profile?.status || 'online')
+	const isSelf = options.isSelf
+		?? (viewerEntityHash && profile?.entityHash === viewerEntityHash)
+	const lastSeen = profile?.lastSeenAt || 0
+	const recentlySeen = lastSeen > 0 && Date.now() - lastSeen < HEARTBEAT_STALE_MS
+
+	if (stored === 'invisible')
+		return isSelf ? 'invisible' : 'offline'
+
+	if (!recentlySeen)
+		return 'offline'
+
+	return stored
+}
+
+/**
+ * @param {string} entityHash 128 位 entityHash
+ * @param {string | null} [replicaUsername] 展示默认字段用
+ * @param {{ groupId?: string, skipPresentation?: boolean, locales?: string[], infoDefaults?: object }} [options] 选项
+ * @returns {Promise<object>} 资料对象
+ */
+export async function getProfile(entityHash, replicaUsername = null, options = {}) {
+	const parsed = parseEntityHash(entityHash)
+	if (!parsed) throw new Error('invalid entityHash')
+
+	const store = getEntityStore()
+	const defaultProfile = getDefaultProfile(parsed.entityHash, parsed)
+	let stored = defaultProfile
+
+	const onDisk = await store.readEntityJson(parsed.entityHash, PROFILE_JSON)
+	if (onDisk)
+		stored = toStoredProfile({ ...defaultProfile, ...onDisk })
+	else if (isWritableLocalEntity(parsed.entityHash))
+		await store.writeEntityJson(parsed.entityHash, PROFILE_JSON, stored)
+
+	const locales = options.locales || ['zh-CN', 'en-UK']
+	const merged = {
+		...stored,
+		entityHash: parsed.entityHash,
+		nodeHash: parsed.nodeHash,
+		subjectHash: parsed.subjectHash,
+	}
+
+	if (options.skipPresentation) return merged
+
+	let infoDefaults = options.infoDefaults
+	if (!infoDefaults && replicaUsername)
+		infoDefaults = await resolveInfoDefaultsForEntity(replicaUsername, parsed.entityHash, locales)
+	if (!infoDefaults)
+		infoDefaults = { name: `${parsed.subjectHash.slice(0, 8)}…${parsed.subjectHash.slice(-4)}`, avatar: '', description: '', description_markdown: '', version: '', author: '', home_page: '', issue_page: '', tags: [], links: [] }
+
+	const resolved = resolveProfilePresentation(merged, locales, infoDefaults)
+	return {
+		...merged,
+		...resolved,
+		infoDefaults,
+		localeKeys: Object.keys(merged.localized),
+	}
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名 所有者
+ * @param {string} entityHash 128 位 entityHash
+ * @returns {Promise<void>}
+ */
+export async function recordHeartbeat(replicaUsername, entityHash) {
+	void replicaUsername
+	const profile = await getProfile(entityHash, null, { skipPresentation: true })
+	profile.lastSeenAt = Date.now()
+	await getEntityStore().writeEntityJson(entityHash, PROFILE_JSON, toStoredProfile(profile))
+	return { lastSeenAt: profile.lastSeenAt }
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名 所有者
+ * @param {string} entityHash 128 位 entityHash
+ * @param {object} updates 更新内容
+ * @param {{ groupId?: string, skipPresentation?: boolean, locales?: string[] }} [options] 选项
+ * @returns {Promise<object>} 更新后的资料
+ */
+export async function updateProfile(replicaUsername, entityHash, updates, options = {}) {
+	if (!isWritableLocalEntity(entityHash))
+		throw new Error('entity not writable on this replica')
+
+	const profile = await getProfile(entityHash, replicaUsername, {
+		groupId: options.groupId,
+		skipPresentation: true,
+	})
+	const parsed = parseEntityHash(entityHash)
+
+	const localized = updates.localized != null
+		? normalizeLocalizedMap(updates.localized)
+		: profile.localized
+
+	const updatedProfile = toStoredProfile({
+		...profile,
+		entityHash: parsed.entityHash,
+		nodeHash: parsed.nodeHash,
+		subjectHash: parsed.subjectHash,
+		localized,
+		status: updates.status != null ? updates.status : profile.status,
+		customStatus: updates.customStatus != null ? updates.customStatus : profile.customStatus,
+		lastSeenAt: updates.lastSeenAt != null ? updates.lastSeenAt : profile.lastSeenAt,
+		stats: updates.stats ? { ...profile.stats, ...updates.stats } : profile.stats,
+	})
+
+	await getEntityStore().writeEntityJson(entityHash, PROFILE_JSON, updatedProfile)
+	if (options.skipPresentation) return updatedProfile
+	const locales = options.locales || ['zh-CN', 'en-UK']
+	const infoDefaults = await resolveInfoDefaultsForEntity(replicaUsername, entityHash, locales)
+	const resolved = resolveProfilePresentation(updatedProfile, locales, infoDefaults)
+	return { ...updatedProfile, ...resolved, infoDefaults, localeKeys: Object.keys(updatedProfile.localized) }
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名 所有者
+ * @param {string} entityHash 128 位 entityHash
+ * @param {Buffer} fileBuffer 文件缓冲区
+ * @param {string} filename 文件名
+ * @returns {Promise<string>} 头像 URL
+ */
+export async function uploadAvatar(replicaUsername, entityHash, fileBuffer, filename) {
+	if (!isWritableLocalEntity(entityHash))
+		throw new Error('entity not writable on this replica')
+
+	const { putFileManifest } = await import('./files/evfs.mjs')
+	await putFileManifest({
+		ownerEntityHash: entityHash,
+		logicalPath: 'profile/avatar',
+		plaintext: fileBuffer,
+		name: filename || 'avatar',
+		mimeType: 'image/png',
+		ceMode: 'convergent',
+	})
+
+	const avatarUrl = profileAvatarFileUrl(entityHash)
+	const profile = await getProfile(entityHash, replicaUsername, { skipPresentation: true })
+	await updateProfile(replicaUsername, entityHash, {
+		localized: applyAvatarToAllLocales(profile.localized, avatarUrl),
+	}, { skipPresentation: true })
+	return avatarUrl
+}
+
+/**
+ * @param {string} entityHash 128 位 entityHash
+ * @returns {Promise<object>} 统计字段
+ */
+export async function getStats(entityHash) {
+	const profile = await getProfile(entityHash)
+	return profile.stats
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名 所有者
+ * @param {string} entityHash 128 位 entityHash
+ * @param {string} status 状态
+ * @param {string} [customStatus] 自定义状态
+ * @returns {Promise<{ status: string, customStatus: string, lastSeenAt: number }>} 更新后的状态字段
+ */
+export async function updateStatus(replicaUsername, entityHash, status, customStatus = '') {
+	if (!MANUAL_STATUSES.has(status))
+		throw new Error('invalid status')
+	const updated = await updateProfile(replicaUsername, entityHash, {
+		status,
+		customStatus,
+		lastSeenAt: Date.now(),
+	}, { skipPresentation: true })
+	return {
+		status: updated.status,
+		customStatus: updated.customStatus,
+		lastSeenAt: updated.lastSeenAt,
+	}
+}
+
+/**
+ * 确保本节点操作者实体目录存在。
+ * @param {string} replicaUsername 副本用户名 所有者
+ * @param {string} entityHash 128 位 entityHash
+ * @returns {Promise<object>} 本节点实体资料
+ */
+export async function ensureLocalEntityProfile(replicaUsername, entityHash) {
+	void replicaUsername
+	if (!isWritableLocalEntity(entityHash))
+		throw new Error('entity not on local node')
+	return getProfile(entityHash, replicaUsername, { skipPresentation: true })
+}

package/entity/replica.mjs

@@ -0,0 +1,20 @@
+import { parseEntityHash } from '../core/entity_id.mjs'
+import { operatorEntityHashFromKeys, getNodeHash } from '../node/identity.mjs'
+
+/**
+ * @param {string} recoveryPubKeyHex 64 位十六进制 recovery 公钥
+ * @returns {string | null} 本节点操作者 entityHash
+ */
+export function resolveLocalOperatorEntityHash(recoveryPubKeyHex) {
+	return operatorEntityHashFromKeys(getNodeHash(), recoveryPubKeyHex)
+}
+
+/**
+ * @param {string} entityHash 目标 entityHash
+ * @returns {boolean} 是否为本节点可写实体
+ */
+export function isWritableLocalEntity(entityHash) {
+	const parsed = parseEntityHash(entityHash)
+	if (!parsed) return false
+	return parsed.nodeHash === getNodeHash()
+}

package/entity/session_snapshot_registry.mjs

@@ -0,0 +1,38 @@
+/** @type {Map<string, (replicaUsername: string, groupId: string) => Promise<object | null>>} */
+const providersByOwner = new Map()
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(replicaUsername: string, groupId: string) => Promise<object | null>} provider 物化会话
+ * @returns {void}
+ */
+export function registerMaterializedSessionProvider(ownerId, provider) {
+	providersByOwner.set(String(ownerId), provider)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterMaterializedSessionProvider(ownerId) {
+	providersByOwner.delete(String(ownerId))
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名
+ * @param {string} groupId 群 ID
+ * @param {string} [ownerId] 注册方 id；省略时遍历所有 provider
+ * @returns {Promise<object | null>} 物化会话
+ */
+export async function getMaterializedSession(replicaUsername, groupId, ownerId) {
+	if (ownerId != null) {
+		const provider = providersByOwner.get(String(ownerId))
+		if (!provider) return null
+		return provider(replicaUsername, groupId)
+	}
+	for (const provider of providersByOwner.values()) {
+		const session = await provider(replicaUsername, groupId)
+		if (session) return session
+	}
+	return null
+}

package/federation/chunk_fetch_pending.mjs

@@ -0,0 +1,128 @@
+import { b64ToU8 } from '../core/bytes_codec.mjs'
+import { verifiedChunkBytes } from '../files/chunk_fetch_verify.mjs'
+
+/** @type {Map<string, { expectedHash: string, timer: ReturnType<typeof setTimeout>, resolve: (v: Uint8Array | null) => void, reject?: (e: Error) => void }>} */
+export const pendingChunkFetches = new Map()
+
+/**
+ *
+ */
+export const MAX_PENDING_CHUNK_FETCHES = 2048
+
+/**
+ * 注册 chunk 拉取等待槽（requestId 或 compositeKey）。
+ * @param {string} key 唯一等待键
+ * @param {string} expectedHash 期望 64 hex 密文哈希
+ * @param {number} timeoutMs 超时毫秒
+ * @param {{ rejectOnTimeout?: boolean }} [opts] rejectOnTimeout 时 Promise 以 Error 拒绝
+ * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待 Promise 与取消函数
+ */
+export function registerChunkFetchWait(key, expectedHash, timeoutMs, opts = {}) {
+	if (!key || pendingChunkFetches.size >= MAX_PENDING_CHUNK_FETCHES)
+		return {
+			done: Promise.resolve(null), /**
+		 *
+		 */
+			cancel: () => { }
+		}
+
+	/** @type {(value: Uint8Array | null | Error) => void} */
+	let settle
+	const done = new Promise((resolve, reject) => {
+		/**
+		 * @param {Uint8Array | null | Error} value 块数据或错误
+		 * @returns {void}
+		 */
+		function settleWait(value) {
+			if (value instanceof Error) reject(value)
+			else resolve(value)
+		}
+		settle = settleWait
+	})
+	const timer = setTimeout(() => {
+		pendingChunkFetches.delete(key)
+		if (opts.rejectOnTimeout)
+			settle(new Error('chunk fetch timeout'))
+		else
+			settle(null)
+	}, timeoutMs)
+
+	/**
+	 * @param {Uint8Array | null} data 块数据
+	 * @returns {void}
+	 */
+	function finish(data) {
+		clearTimeout(timer)
+		pendingChunkFetches.delete(key)
+		settle(data)
+	}
+
+	/**
+	 * @param {Error | unknown} err 拒绝原因
+	 * @returns {void}
+	 */
+	function rejectWait(err) {
+		finish(err instanceof Error ? err : new Error(String(err)))
+	}
+
+	pendingChunkFetches.set(key, {
+		expectedHash,
+		timer,
+		resolve: finish,
+		reject: rejectWait,
+	})
+
+	return {
+		done,
+		/**
+		 *
+		 */
+		cancel: () => {
+			clearTimeout(timer)
+			pendingChunkFetches.delete(key)
+			settle(null)
+		},
+	}
+}
+
+/**
+ * 按等待键解析入站 chunk 响应（校验哈希后 resolve）。
+ * @param {string} key 等待键
+ * @param {string} expectedHash 期望哈希
+ * @param {Uint8Array | null} bytes 密文块
+ * @returns {boolean} 是否命中并完成等待
+ */
+export function resolveChunkFetchWait(key, expectedHash, bytes) {
+	const entry = pendingChunkFetches.get(key)
+	if (!entry || entry.expectedHash !== expectedHash) return false
+	const verified = bytes ? verifiedChunkBytes(expectedHash, bytes) : null
+	if (bytes && !verified) return false
+	clearTimeout(entry.timer)
+	pendingChunkFetches.delete(key)
+	entry.resolve(verified)
+	return true
+}
+
+/**
+ * 处理 fed_chunk_data / 带 requestId 的响应载荷。
+ * @param {object} payload 入站载荷
+ * @returns {boolean} 是否命中 pending
+ */
+export function resolvePendingChunkFetch(payload) {
+	const requestId = String(payload?.requestId || '')
+	if (!requestId) return false
+	const entry = pendingChunkFetches.get(requestId)
+	if (!entry) return false
+	if (payload?.dataB64) {
+		try {
+			const bytes = b64ToU8(String(payload.dataB64))
+			return resolveChunkFetchWait(requestId, entry.expectedHash, bytes)
+		}
+		catch { /* keep waiting */ }
+		return false
+	}
+	clearTimeout(entry.timer)
+	pendingChunkFetches.delete(requestId)
+	entry.resolve(null)
+	return true
+}

package/federation/chunk_fetch_scheduler.mjs

@@ -0,0 +1,97 @@
+/**
+ * 联邦分块拉取调度：按 peer 轮转分配缺失块，支持超时重试与广播兜底。
+ */
+
+/** @typedef {'pending' | 'inflight' | 'done' | 'failed'} ChunkFetchState */
+
+/**
+ * @param {string[]} chunkHashes 缺失块哈希（有序）
+ * @param {string[]} peerIds 可用 peerId 列表
+ * @returns {Map<string, string>} chunkHash → 首选 peerId
+ */
+export function assignChunksToPeers(chunkHashes, peerIds) {
+	/** @type {Map<string, string>} */
+	const out = new Map()
+	if (!peerIds.length) return out
+	const list = peerIds.filter(Boolean)
+	for (let i = 0; i < chunkHashes.length; i++)
+		out.set(chunkHashes[i], list[i % list.length])
+	return out
+}
+
+/**
+ * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
+ * @param {string[]} chunkHashes 待拉取块
+ * @param {string[]} peerIds 可用 peer
+ * @param {{ maxAttempts?: number }} [opts] 选项
+ * @returns {{ assignments: Map<string, string>, broadcast: string[] }} 分配与需广播块
+ */
+export function planChunkFetches(table, chunkHashes, peerIds, opts = {}) {
+	const maxAttempts = Math.max(1, Number(opts.maxAttempts) || 3)
+	const assignments = assignChunksToPeers(chunkHashes, peerIds)
+	/** @type {string[]} */
+	const broadcast = []
+	for (const hash of chunkHashes) {
+		const row = table.get(hash) || { state: 'pending', attempts: 0 }
+		if (row.state === 'done') continue
+		if (row.state === 'inflight') continue
+		if (row.attempts >= maxAttempts) {
+			broadcast.push(hash)
+			continue
+		}
+		const peerId = assignments.get(hash)
+		if (!peerId) broadcast.push(hash)
+	}
+	return { assignments, broadcast }
+}
+
+/**
+ * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
+ * @param {string} chunkHash 块哈希
+ * @param {string} peerId 目标 peer
+ * @returns {void}
+ */
+export function markChunkInflight(table, chunkHash, peerId) {
+	const prev = table.get(chunkHash) || { state: 'pending', attempts: 0 }
+	table.set(chunkHash, {
+		state: 'inflight',
+		peerId,
+		attempts: prev.attempts + 1,
+	})
+}
+
+/**
+ * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
+ * @param {string} chunkHash 块哈希
+ * @returns {void}
+ */
+export function markChunkDone(table, chunkHash) {
+	table.set(chunkHash, { state: 'done', attempts: 0 })
+}
+
+/**
+ * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
+ * @param {string} chunkHash 块哈希
+ * @returns {void}
+ */
+export function markChunkFailed(table, chunkHash) {
+	const prev = table.get(chunkHash) || { state: 'pending', attempts: 0 }
+	table.set(chunkHash, { state: 'failed', attempts: prev.attempts })
+}
+
+/**
+ * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
+ * @returns {{ done: number, pending: number, inflight: number, failed: number, total: number }} 进度
+ */
+export function chunkFetchProgress(table) {
+	let done = 0
+	let pending = 0
+	let inflight = 0
+	let failed = 0
+	for (const row of table.values())
+		if (row.state === 'done') done++
+		else if (row.state === 'inflight') inflight++
+		else if (row.state === 'failed') failed++
+		else pending++
+	return { done, pending, inflight, failed, total: table.size }
+}