@steve02081504/fount-p2p 0.0.40 → 0.0.41

package/AGENTS.md

@@ -39,7 +39,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 
 ## Tests / tools
 
-- `npm test` — pure + integration (Node; `--test-force-exit`)
+- `npm test` — pure + integration + frontend (Node; `--test-force-exit`)
 - `npm run test:live` — live link / LAN smoke
 - `npm run test:fount` — cross-repo Deno bridge (`test/fount/`); see [runtime.md](docs/runtime.md)
 - `npm run test:sim` — tunables co-evolution (dev-only; [sim/AGENTS.md](sim/AGENTS.md))
@@ -73,7 +73,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 
 | File | Directory |
 |---|---|
-| `tunables.json` | `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
+| `tunables.json` | `transport/`, `infra/`, `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
 | `part_query.tunables.json` | `schemas/` |
 
 Sim harness: `sim/tunables_bundle.mjs` (dev-only). See [sim/AGENTS.md](sim/AGENTS.md).

package/docs/evfs.md

@@ -40,6 +40,12 @@ Concurrency: `putChunk` / `putChunkFromStream` / `deleteChunk` / the GC delete p
 
 Outer caller timeouts must **not** abort the in-flight work — background fill continues after the caller gives up.
 
+## `fetchChunk` / public-file chunk reads
+
+- `fetchChunk` accepts the same `fanoutTargets` as `fetchManifest`. With targets it fanouts `fed_chunk_get` **only** to that node set; without targets it falls back to node-scope fanout. Same `username`+chunk hash+mode (`targeted`/`public`) is deduped in-flight.
+- `readPublicFile` / `readManifestPlaintext` forward `options.fanoutTargets` to both the manifest fetch and the chunk fetch, so a cross-node public read can pull profile/avatar content straight from the owner node instead of depending on the node-scope fanout.
+- The public (non-targeted) fanout does **not** block the request window on dialing the whole peer pool: already-linked / group-room-reachable peers are sent immediately, and unreachable peers are dialed in the background and re-sent once linked. (`ensureLinkToNode` no longer gates the send.)
+
 ## Non-public (ACL-gated) manifests
 
 - `file-master-key-wrap` / `vault-wrap` / `identity-wrap` manifests carry no author signature, so the remote-acquisition trust boundary is **not** a signature — it is the **fanout target set** plus the **serving node's authorization**.

package/files/chunk/fetch.mjs

@@ -26,10 +26,14 @@ const chunkInflight = createInflightTable({
  *   ciphertextHash: string,
  *   ownerEntityHash?: string,
  *   groupId?: string,
+ *   fanoutTargets?: string[],
  * }} FetchChunkContext
  */
 
 /**
+ * 拉取密文块。默认走 node-scope public 语义；
+ * 传入 `fanoutTargets` 时只向目标集 fanout（public 文件定向拉取，如 profile/avatar 直接向 owner 节点取块）。
+ * 同 username+hash+模式（含规范化目标集）in-flight 去重；本地已缓存块直接返回。
  * @param {FetchChunkContext} context 上下文
  * @returns {Promise<Uint8Array | null>} 密文块
  */
@@ -50,7 +54,7 @@ export async function fetchChunk(context) {
 
 	const shared = beginFedFanoutFetch({
 		inflight: chunkInflight,
-		inflightKey: `${username}\0${hash}`,
+		inflightKeyBase: `${username}\0${hash}`,
 		username,
 		action: 'fed_chunk_get',
 		/**
@@ -69,6 +73,7 @@ export async function fetchChunk(context) {
 			chunkHash: hash,
 			ownerEntityHash: context.ownerEntityHash,
 		}),
+		fanoutTargets: context.fanoutTargets,
 	})
 	if (!shared) return null
 

package/files/evfs.mjs

@@ -32,7 +32,7 @@ function transferKeyDependenciesForReplica(replicaUsername, manifest) {
 /**
  * @param {string} username 拉取身份
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<boolean>} 全部 part 是否已就位
  */
 async function ensureManifestPartsLocal(username, manifest, options = {}) {
@@ -43,6 +43,7 @@ async function ensureManifestPartsLocal(username, manifest, options = {}) {
 			ciphertextHash: part.hash,
 			ownerEntityHash: manifest.ownerEntityHash,
 			groupId: manifest.transferKeyDescriptor.groupId,
+			fanoutTargets: options.fanoutTargets,
 		})
 		if (!fetchedChunk) return false
 		await putChunk(part.hash, fetchedChunk)
@@ -94,7 +95,7 @@ export async function storeManifestParts(manifest, partBytes) {
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
 export async function readManifestPlaintext(replicaUsername, manifest, options = {}) {
@@ -118,7 +119,7 @@ export async function readManifestPlaintext(replicaUsername, manifest, options =
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
 export async function readManifestPlaintextStream(replicaUsername, manifest, options = {}) {
@@ -229,10 +230,11 @@ export async function putFileManifestFromStream(parameters) {
 
 /**
  * 读取实体公开文件：本地 miss 时经网络取回签名 manifest，chunk miss 走既有 fetchChunk。
+ * 传入 `fanoutTargets` 时 manifest 与 chunk 拉取均定向到目标集（public 文件跨节点直取 owner 节点，避免 node-scope 大扇出）。
  * @param {string} replicaUsername 副本用户名
  * @param {string} entityHash owner entityHash
  * @param {string} logicalPath EVFS 逻辑路径
- * @param {{ username?: string, fetchChunk?: Function, revalidate?: boolean }} [options] miss 拉取；`revalidate` 强制阻塞等待 fanout 择新
+ * @param {{ username?: string, fetchChunk?: Function, revalidate?: boolean, fanoutTargets?: string[] }} [options] miss 拉取；`revalidate` 强制阻塞等待 fanout 择新
  * @returns {Promise<Buffer | null>} 明文或 null
  */
 export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
@@ -243,6 +245,7 @@ export async function readPublicFile(replicaUsername, entityHash, logicalPath, o
 		logicalPath,
 		cache: true,
 		revalidate: options.revalidate === true,
+		fanoutTargets: options.fanoutTargets,
 	})
 	if (!manifest) return null
 	return readManifestPlaintext(replicaUsername, manifest, options)

package/files/fed/fetch_shared.mjs

@@ -1,14 +1,15 @@
 import { randomUUID } from 'node:crypto'
 
 import { resolveNodeHash } from '../chunk/provider_registry.mjs'
-import { fanoutFedFetch } from '../fetch_fanout.mjs'
+import { canonicalizeFanoutTargets, fanoutFedFetch } from '../fetch_fanout.mjs'
 
 /**
  * inflight + pending wait + fanout 共用骨架。
+ * 规范化目标集并拼入 inflight key：`fanoutTargets` 为数组（含空）即定向模式，undefined 为 node-scope public 模式。
  * @template T
  * @param {{
  *   inflight: { acquire: (key: string, start: () => { done: Promise<T | null>, cancel: () => void }) => Promise<T | null> | null },
- *   inflightKey: string,
+ *   inflightKeyBase: string,
  *   username: string,
  *   action: string,
  *   registerWait: (requestId: string) => { done: Promise<T | null>, cancel: () => void },
@@ -19,20 +20,23 @@ import { fanoutFedFetch } from '../fetch_fanout.mjs'
  */
 export function beginFedFanoutFetch({
 	inflight,
-	inflightKey,
+	inflightKeyBase,
 	username,
 	action,
 	registerWait,
 	buildPayload,
 	fanoutTargets,
 }) {
+	const targeted = Array.isArray(fanoutTargets)
+	const canonicalTargets = targeted ? canonicalizeFanoutTargets(fanoutTargets) : undefined
+	const inflightKey = `${inflightKeyBase}\0${targeted ? 'targeted' : 'public'}` + (canonicalTargets?.length ? `\0${canonicalTargets.join('\0')}` : '')
 	return inflight.acquire(inflightKey, () => {
 		const requestId = randomUUID()
 		const wait = registerWait(requestId)
 		void (async () => {
 			try {
 				const { nodeHash } = await resolveNodeHash(username)
-				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash), fanoutTargets)
+				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash), canonicalTargets)
 			}
 			catch { /* pending wait 超时/cancel 负责 settle */ }
 		})()

package/files/fetch_fanout.mjs

@@ -32,6 +32,7 @@ export function canonicalizeFanoutTargets(targets) {
 /**
  * 全局 miss 请求扇出：先向已知 peer 定向发送，再 trust-graph top-K fanout。
  * 已直连 / follow hint peer 可能不在 trust-graph top-K（非成员 emoji CAS / Social 预览路径），故先定向发送。
+ * 拨号不阻塞请求窗口：已直连 peer 立即经现有链路投递，未直连 peer 先经群房间/overlay 尝试并后台拨号补发。
  * @param {string} username 用户
  * @param {string} action wire action 名
  * @param {object} payload 请求载荷
@@ -52,8 +53,20 @@ export async function fanoutFedFetch(username, action, payload, fanoutTargets) {
 
 	const graph = await trustGraph.buildMergedGraph(username)
 	const peerTargets = fetchPeerTargets()
-	await Promise.all(peerTargets.map(nodeHash => ensureLinkToNode(nodeHash).catch(() => null)))
-	for (const nodeHash of peerTargets)
-		void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+	// 已直连 peer 立即经现有链路投递；其余 peer 后台并行：先经群房间/overlay 尝试投递，同时拨号，拨通且首投失败再补发。
+	// 全程不阻塞请求窗口（大 peer 池下 await 全量拨号会超窗口）。
+	const linked = new Set(listLinks().map(({ nodeHash }) => nodeHash))
+	for (const nodeHash of peerTargets) {
+		if (linked.has(nodeHash)) {
+			void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+			continue
+		}
+		const dialed = ensureLinkToNode(nodeHash).catch(() => null)
+		void trustGraph.sendToNode(username, nodeHash, action, payload, graph).then(async sent => {
+			if (sent) return
+			const link = await dialed
+			if (link) await trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+		})
+	}
 	await trustGraph.fanoutToTopNodes(username, action, payload, FEDERATION_CHUNK_FETCH_FANOUT_K)
 }

package/files/manifest/fetch.mjs

@@ -54,7 +54,7 @@ export async function fetchManifest(context) {
 	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
 	const shared = beginFedFanoutFetch({
 		inflight: manifestInflight,
-		inflightKey: `${username}\0${expectedKey}\0${targeted ? 'targeted' : 'public'}` + (fanoutTargets?.length ? `\0${fanoutTargets.join('\0')}` : ''),
+		inflightKeyBase: `${username}\0${expectedKey}`,
 		username,
 		action: 'fed_manifest_get',
 		/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.40",
+	"version": "0.0.41",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",