@steve02081504/fount-p2p 0.0.0

package/mailbox/rate.mjs

@@ -0,0 +1,86 @@
+/**
+ * Mailbox 入站 put 限速（按来源节点，节点级单例）。
+ */
+
+const DEFAULT_WINDOW_MS = 60_000
+const DEFAULT_MAX_PUTS = 20
+const MAX_KEYS = 8000
+const EXPIRE_SWEEP_BATCH = 64
+
+/** @type {Map<string, { count: number, resetAt: number }>} */
+const inboundByKey = new Map()
+
+/**
+ * @param {object} [limits] 可选限额
+ * @returns {{ windowMs: number, maxPuts: number }} 生效限额
+ */
+export function resolveMailboxRateLimits(limits = {}) {
+	return {
+		windowMs: Math.max(1000, Number(limits.windowMs) || DEFAULT_WINDOW_MS),
+		maxPuts: Math.max(1, Math.min(256, Number(limits.maxPuts) || DEFAULT_MAX_PUTS)),
+	}
+}
+
+/**
+ * @param {string} fromNodeHash 来源节点
+ * @returns {string} 限速键
+ */
+export function mailboxRateKey(fromNodeHash) {
+	return String(fromNodeHash || '').trim()
+}
+
+/**
+ * @param {number} now 当前时间戳
+ * @returns {void}
+ */
+function sweepExpiredEntries(now) {
+	let scanned = 0
+	for (const [rateKey, rateEntry] of inboundByKey) {
+		if (now > rateEntry.resetAt) inboundByKey.delete(rateKey)
+		if (++scanned >= EXPIRE_SWEEP_BATCH) break
+	}
+}
+
+/**
+ * @param {string} key 限速键
+ * @returns {void}
+ */
+function touchLruKey(key) {
+	const entry = inboundByKey.get(key)
+	if (!entry) return
+	inboundByKey.delete(key)
+	inboundByKey.set(key, entry)
+}
+
+/**
+ * @param {string} key 新插入键
+ * @returns {void}
+ */
+function evictLruIfNeeded(key) {
+	if (inboundByKey.has(key) || inboundByKey.size < MAX_KEYS) return
+	const oldest = inboundByKey.keys().next().value
+	if (oldest != null) inboundByKey.delete(oldest)
+}
+
+/**
+ * @param {string} fromNodeHash 来源节点
+ * @param {object} [limits] 可选限额
+ * @returns {boolean} 允许新 put 则为 true
+ */
+export function takeIncomingMailboxPutSlot(fromNodeHash, limits) {
+	const { windowMs, maxPuts } = resolveMailboxRateLimits(limits)
+	const key = mailboxRateKey(fromNodeHash)
+	const now = Date.now()
+	if (inboundByKey.size >= MAX_KEYS) sweepExpiredEntries(now)
+	evictLruIfNeeded(key)
+	let entry = inboundByKey.get(key)
+	if (!entry || now > entry.resetAt) entry = { count: 0, resetAt: now + windowMs }
+	if (entry.count >= maxPuts) {
+		touchLruKey(key)
+		return false
+	}
+	entry.count++
+	inboundByKey.set(key, entry)
+	touchLruKey(key)
+	return true
+}

package/mailbox/settings.mjs

@@ -0,0 +1,53 @@
+import { getNodeTransportSettings } from '../node/identity.mjs'
+import {
+	resolveMailboxRelayFanout,
+	resolveMailboxWantFanout,
+} from '../trust_graph/resolve.mjs'
+
+import mailboxTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * @param {object} raw 节点 mailbox 配置片段
+ * @param {number} [peerCount=0] 已知在线 relay 候选数（0 时用 floor）
+ * @returns {{ maxHop: number, relayFanoutTrusted: number, relayFanoutNormal: number, wantFanout: number }} 规范化 mailbox 配置
+ */
+export function normalizeMailboxSettings(raw = {}, peerCount = 0) {
+	const maxHop = Math.max(1, Math.min(8, Number(raw.maxHop) || mailboxTunables.maxHop))
+	const capTrusted = mailboxTunables.relayFanoutTrustedCap ?? 32
+	const capWant = mailboxTunables.wantFanoutCap ?? 32
+	const n = Math.max(0, Math.floor(Number(peerCount) || 0))
+	const relayFanoutTrusted = Number.isFinite(Number(raw.relayFanoutTrusted))
+		? Math.max(1, Math.min(capTrusted, Math.floor(Number(raw.relayFanoutTrusted))))
+		: resolveMailboxRelayFanout(n, mailboxTunables)
+	const relayFanoutNormal = Math.max(1, Math.min(capTrusted, Number(raw.relayFanoutNormal) || mailboxTunables.relayFanoutNormal))
+	const wantFanout = Number.isFinite(Number(raw.wantFanout))
+		? Math.max(1, Math.min(capWant, Math.floor(Number(raw.wantFanout))))
+		: resolveMailboxWantFanout(n, mailboxTunables)
+	return { maxHop, relayFanoutTrusted, relayFanoutNormal, wantFanout }
+}
+
+/**
+ * @param {number} peerCount 已知在线 relay 候选数
+ * @param {object} [raw] 节点 mailbox 配置片段
+ * @param {boolean} [batterySaver=false] 省电模式
+ * @returns {{ maxHop: number, relayFanoutTrusted: number, relayFanoutNormal: number, wantFanout: number, batterySaver: boolean }} 缩放后的路由
+ */
+export function resolveMailboxRoutingForPeerCount(peerCount, raw = {}, batterySaver = false) {
+	const base = normalizeMailboxSettings(raw, peerCount)
+	if (!batterySaver) return { ...base, batterySaver: false }
+	return {
+		maxHop: base.maxHop,
+		relayFanoutTrusted: Math.max(1, Math.ceil(base.relayFanoutTrusted / 2)),
+		relayFanoutNormal: Math.max(1, Math.ceil(base.relayFanoutNormal / 2)),
+		wantFanout: Math.max(1, Math.ceil(base.wantFanout / 2)),
+		batterySaver: true,
+	}
+}
+
+/**
+ * @returns {{ maxHop: number, relayFanoutTrusted: number, relayFanoutNormal: number, wantFanout: number, batterySaver: boolean }} mailbox 路由配置
+ */
+export function getMailboxRoutingSettings() {
+	const { batterySaver, mailbox } = getNodeTransportSettings()
+	return resolveMailboxRoutingForPeerCount(0, mailbox, batterySaver)
+}

package/mailbox/store.mjs

@@ -0,0 +1,256 @@
+import { mkdir, readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { jsonlMutexKey, writeJsonl } from '../dag/storage.mjs'
+import { mailboxStorePath } from '../node/user_paths.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
+
+import {
+	defaultTtlMsForTier,
+	sortMailboxForRetention,
+} from './importance.mjs'
+import {
+	MAX_BUCKET_BYTES,
+	MAX_BUCKET_ENTRIES,
+	mailboxBucketKey,
+	mailboxRecordBytes,
+	pruneMailboxBuckets,
+	pruneMailboxGlobalFair,
+} from './prune.mjs'
+
+/**
+ *
+ */
+export { MAX_BUCKET_BYTES, MAX_BUCKET_ENTRIES, mailboxBucketKey, mailboxRecordBytes }
+
+/** 单条 mailbox envelope JSON 字节上限 */
+export const MAX_ENTRY_BYTES = 256 * 1024
+
+/**
+ * @typedef {'trusted' | 'normal' | 'quarantine'} MailboxTier
+ */
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   app: string,
+ *   toPubKeyHash: string,
+ *   dmSessionTag?: string,
+ *   groupId?: string,
+ *   channelId?: string,
+ *   envelope: object,
+ *   storedAt: number,
+ *   expiresAt: number,
+ *   fromNodeHash: string,
+ *   hop: number,
+ *   tier?: MailboxTier,
+ *   importance?: number,
+ * }} MailboxRecord
+ */
+
+/**
+ * @param {unknown} value 入站 hop
+ * @returns {number} 非负整数 hop
+ */
+export function normalizeMailboxHop(value) {
+	const n = Number(value)
+	if (!Number.isFinite(n)) return 0
+	return Math.max(0, Math.floor(n))
+}
+
+/**
+ * @returns {string} mailbox store 进程内互斥键
+ */
+function mailboxStoreMutexKey() {
+	return jsonlMutexKey(mailboxStorePath())
+}
+
+/**
+ * @param {number} hop 转发跳数
+ * @returns {MailboxTier} 信誉分层
+ */
+export function mailboxTierFromHop(hop) {
+	if (hop <= 0) return 'trusted'
+	if (hop === 1) return 'normal'
+	return 'quarantine'
+}
+
+/**
+ * @param {object | null | undefined} row mailbox 记录
+ * @returns {boolean} 是否可交给 Part 消费者（排除 quarantine 与缺字段）
+ */
+export function isDeliverableMailboxRecord(row) {
+	if (!row?.envelope || typeof row.envelope !== 'object') return false
+	if (!String(row.app || '').trim()) return false
+	return row.tier === 'trusted' || row.tier === 'normal'
+}
+
+/**
+ * @param {object | null | undefined} record mailbox 记录
+ * @returns {boolean} envelope 是否在存储限额内
+ */
+export function isMailboxRecordWithinSizeLimit(record) {
+	if (!record?.envelope || typeof record.envelope !== 'object') return false
+	return JSON.stringify(record.envelope).length <= MAX_ENTRY_BYTES
+}
+
+/**
+ * 入站 wire 转发：不信任自报 hop，至少为 1；若本地已有同 id 则单调递增。
+ * @param {unknown} wireHop 线载荷 hop
+ * @param {unknown} [existingStoredHop] 本地已存 hop
+ * @returns {number} 本节点存储 hop
+ */
+export function relayHopAfterWireIngress(wireHop, existingStoredHop) {
+	const fromWire = Math.max(normalizeMailboxHop(wireHop) + 1, 1)
+	if (existingStoredHop == null || !Number.isFinite(Number(existingStoredHop)))
+		return fromWire
+	return Math.max(fromWire, normalizeMailboxHop(existingStoredHop) + 1)
+}
+
+/**
+ * @returns {Promise<MailboxRecord[]>} 全部有效记录
+ */
+async function readAll() {
+	try {
+		const text = await readFile(mailboxStorePath(), 'utf8')
+		/** @type {MailboxRecord[]} */
+		const rows = []
+		for (const line of text.split('\n')) {
+			const trimmed = line.trim()
+			if (!trimmed) continue
+			try {
+				rows.push(JSON.parse(trimmed))
+			}
+			catch { /* skip corrupt line */ }
+		}
+		return rows
+	}
+	catch { return [] }
+}
+
+/**
+ * @param {MailboxRecord[]} rows 待写入记录
+ * @returns {Promise<void>}
+ */
+async function writeAll(rows) {
+	const filePath = mailboxStorePath()
+	await mkdir(dirname(filePath), { recursive: true })
+	const now = Date.now()
+	const kept = pruneMailboxGlobalFair(
+		pruneMailboxBuckets(sortMailboxForRetention(rows.filter(record => record.expiresAt > now))),
+	)
+	await writeJsonl(filePath, kept)
+}
+
+/**
+ * @param {object} envelope 载荷
+ * @returns {string} 稳定信封 id
+ */
+export function mailboxEnvelopeId(envelope) {
+	const id = String(envelope?.id || '').trim().toLowerCase()
+	if (!id) throw new Error('mailbox envelope id required')
+	return id
+}
+
+/**
+ * @param {object} record mailbox 记录字段
+ * @returns {Promise<boolean>} 是否新写入
+ */
+export async function storeMailboxRecord(record) {
+	if (!isMailboxRecordWithinSizeLimit(record)) return false
+	const toPubKeyHash = normalizeHex64(record.toPubKeyHash)
+	if (!isHex64(toPubKeyHash)) return false
+	const hop = normalizeMailboxHop(record.hop)
+	const tier = record.tier
+	if (!['trusted', 'normal', 'quarantine'].includes(tier)) return false
+	const app = String(record.app || '').trim()
+	if (!app) return false
+	let id
+	try {
+		id = mailboxEnvelopeId(record.envelope)
+	}
+	catch {
+		return false
+	}
+	return withAsyncMutex(mailboxStoreMutexKey(), async () => {
+		const rows = await readAll()
+		if (rows.some(row => row.id === id)) return false
+		const ttlMs = Number(record.ttlMs) || defaultTtlMsForTier(tier)
+		rows.push({
+			id,
+			app,
+			toPubKeyHash,
+			dmSessionTag: record.dmSessionTag?.trim().toLowerCase() || undefined,
+			groupId: record.groupId || undefined,
+			channelId: record.channelId || undefined,
+			envelope: record.envelope,
+			storedAt: Date.now(),
+			expiresAt: Date.now() + ttlMs,
+			fromNodeHash: String(record.fromNodeHash || '').trim(),
+			hop,
+			tier,
+			importance: Number.isFinite(Number(record.importance)) ? Number(record.importance) : undefined,
+		})
+		await writeAll(rows)
+		return true
+	})
+}
+
+/**
+ * @param {string} toPubKeyHash 收件人
+ * @returns {Promise<string[]>} record id 列表
+ */
+export async function listMailboxIdsForRecipient(toPubKeyHash) {
+	const recipient = normalizeHex64(toPubKeyHash)
+	return (await readAll())
+		.filter(record => record.toPubKeyHash === recipient)
+		.map(record => record.id)
+}
+
+/**
+ * @param {string[]} ids record id 列表
+ * @returns {Promise<MailboxRecord[]>} 匹配记录
+ */
+export async function getMailboxRecords(ids) {
+	const want = new Set(ids.map(id => String(id).trim().toLowerCase()))
+	return (await readAll()).filter(record => want.has(record.id))
+}
+
+/**
+ * @param {string[]} ids 待删除 id
+ * @returns {Promise<void>}
+ */
+export async function deleteMailboxRecords(ids) {
+	const drop = new Set(ids.map(id => String(id).trim().toLowerCase()))
+	return withAsyncMutex(mailboxStoreMutexKey(), async () => {
+		await writeAll((await readAll()).filter(record => !drop.has(record.id)))
+	})
+}
+
+/**
+ * @param {string} toPubKeyHash 收件人
+ * @returns {Promise<MailboxRecord[]>} 待发记录（不删除）
+ */
+export async function takeMailboxForRecipient(toPubKeyHash) {
+	const recipient = normalizeHex64(toPubKeyHash)
+	return (await readAll()).filter(record => record.toPubKeyHash === recipient)
+}
+
+/**
+ * @param {string} toPubKeyHash 收件人 pubKeyHash
+ * @returns {Promise<number>} 未过期条数
+ */
+export async function countMailboxPendingForRecipient(toPubKeyHash) {
+	const recipient = normalizeHex64(toPubKeyHash)
+	const now = Date.now()
+	return (await readAll()).filter(record => record.toPubKeyHash === recipient && record.expiresAt > now).length
+}
+
+/**
+ * @returns {Promise<number>} 未过期条数
+ */
+export async function countMailboxPending() {
+	const now = Date.now()
+	return (await readAll()).filter(record => record.expiresAt > now).length
+}

package/mailbox/tunables.json

@@ -0,0 +1,12 @@
+{
+	"maxHop": 3,
+	"relayFanoutTrustedFloor": 3,
+	"relayFanoutTrustedRatio": 0.3,
+	"relayFanoutTrustedCap": 32,
+	"relayFanoutNormal": 3,
+	"wantFanoutFloor": 3,
+	"wantFanoutRatio": 0.4,
+	"wantFanoutCap": 32,
+	"networkBudgetPerRound": 64,
+	"networkBudgetPerPeerRatio": 2
+}

package/mailbox/wire.mjs

@@ -0,0 +1,40 @@
+import {
+	ingestMailboxGive,
+	ingestMailboxPut,
+	respondMailboxWant,
+} from './deliver_or_store.mjs'
+import { parseMailboxGive, parseMailboxPut, parseMailboxWant } from './parse.mjs'
+
+/**
+ * @typedef {{ replicaUsername?: string }} MailboxWireContext
+ */
+
+/**
+ * @param {MailboxWireContext} ctx 入站上下文
+ * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire Trystero 适配器
+ * @returns {void}
+ */
+export function attachMailboxWire(ctx, wire) {
+	wire.on('mailbox_put', (payload, peerId) => {
+		const put = parseMailboxPut(payload)
+		if (!put.ok) return
+		void ingestMailboxPut(ctx, 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(ctx, give.value).catch(err => console.error('mailbox: give ingest failed', err))
+	})
+}