@steve02081504/fount-p2p 0.0.24 → 0.0.26

package/README.md

@@ -34,7 +34,7 @@ Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / ro
 
 Dial order is descending link **`level`**: `lan_tcp` → `webrtc` → `ble_gatt` → `nostr` (−∞ last resort). Discovery **`priority`** only orders handshake / presence media. Details: [docs/transports.md](./docs/transports.md).
 
-Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope`, `room_scopes`, `remote_user_room`, `scoped_link`. Other `transport/*` modules are internal.
+Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope/wire`, `node_scope/features`, `room_scopes`, `remote_user_room`, `scoped_link`. Other `transport/*` modules are internal.
 
 ## Infra relay (optional)
 
@@ -85,7 +85,7 @@ Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscovery
 | Module | Role |
 |---|---|
 | `link_registry.mjs` | fount-network facade: dial fallback, scope/overlay |
-| `user_room.mjs` / `group_link_set.mjs` / `node_scope/` | rooms + composable node-scope wires |
+| `user_room.mjs` / `group_link_set.mjs` / `node_scope/wire` + `node_scope/features` | rooms + composable node-scope wires (`registerNodeScopeWireHook`, attaches) |
 | `room_scopes.mjs` / `remote_user_room.mjs` | scope constants / remote user slot |
 
 `runtime_bootstrap`, `offer_answer` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).

package/federation/part_query/runtime.mjs

@@ -285,7 +285,6 @@ export async function processIncomingPartQueryRequest(wireContext, wire, request
 
 	const selfHash = nodeHashOf()
 	const exclude = new Set([selfHash, request.originNodeHash, String(peerId || '').trim().toLowerCase()].filter(Boolean))
-	const neighbors = username ? await selectQueryNeighbors(username, exclude, dependencies) : []
 	const forwardPayload = { ...request, ttl: nextTtl }
 
 	/** @type {RelayPending} */
@@ -304,18 +303,25 @@ export async function processIncomingPartQueryRequest(wireContext, wire, request
 		state,
 	}
 	state.relayPending.set(request.requestId, pending)
-
-	let sent = 0
-	for (const target of neighbors)
-		if (await deliverQuery(target, 'part_query_req', forwardPayload, dependencies)) sent++
-	pending.expected = sent
-
-	if (sent === 0 || pending.received >= pending.expected) {
-		flushRelayPending(pending)
-		return
-	}
-
+	// 先挂 hop 超时：勿等 select/deliver settle，否则 stuck send 永不 flush upstream（#13 同类）
 	pending.timer = setTimeout(() => flushRelayPending(pending), resolvePartQueryHopTimeoutMs(request.ttl))
+
+	void (async () => {
+		try {
+			const neighbors = username ? await selectQueryNeighbors(username, exclude, dependencies) : []
+			if (pending.flushed) return
+			let sent = 0
+			for (const target of neighbors)
+				if (await deliverQuery(target, 'part_query_req', forwardPayload, dependencies)) sent++
+			if (pending.flushed) return
+			pending.expected = sent
+			if (sent === 0 || pending.received >= pending.expected)
+				flushRelayPending(pending)
+		}
+		catch {
+			if (!pending.flushed) flushRelayPending(pending)
+		}
+	})()
 }
 
 /**
@@ -353,6 +359,7 @@ export function handleIncomingPartQueryResponse(response, peerId = '', dependenc
 
 /**
  * 多跳查询：本地 handler + 网络回流（反向路径聚合）；本地缓存命中则不广播。
+ * `timeoutMs` 端到端约束：select/deliver 挂起也不阻塞返回。
  * @param {string} username trust graph 上下文
  * @param {string} partpath part 路径
  * @param {string} kind 查询标签
@@ -420,14 +427,20 @@ export async function queryNetwork(username, partpath, kind, query, options = {}
 
 	const selfHash = nodeHashOf()
 	const exclude = new Set([selfHash, parsed.originNodeHash])
-	const neighbors = await selectQueryNeighbors(username, exclude, options)
-	let sent = 0
-	for (const target of neighbors)
-		if (await deliverQuery(target, 'part_query_req', parsed, options)) sent++
-	bag.expected = sent
-
-	if (sent === 0 || bag.received >= bag.expected)
-		finishMultiWireWaiters(state.originWaits, parsed.requestId, '')
+	// 勿 await select/deliver：否则 timeout 已触发也要等扇出 settle（#13）
+	void (async () => {
+		try {
+			const neighbors = await selectQueryNeighbors(username, exclude, options)
+			let sent = 0
+			for (const target of neighbors)
+				if (await deliverQuery(target, 'part_query_req', parsed, options)) sent++
+			bag.expected = sent
+			if (sent === 0 || bag.received >= bag.expected)
+				finishMultiWireWaiters(state.originWaits, parsed.requestId, '')
+		}
+		catch { /* pending wait 超时负责 settle */ }
+	})()
+
 	await waitPromise
 	state.originBags.delete(parsed.requestId)
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.24",
+	"version": "0.0.26",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -11,7 +11,7 @@
 	"type": "module",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/steve02081504/fount-p2p.git",
+		"url": "git+https://github.com/steve02081504/fount-p2p.git",
 		"directory": "."
 	},
 	"engines": {
@@ -31,7 +31,7 @@
 		"!scripts/**"
 	],
 	"bin": {
-		"fount-p2p": "./infra/cli.mjs"
+		"fount-p2p": "infra/cli.mjs"
 	},
 	"exports": {
 		".": "./index.mjs",

package/transport/node_scope/wire.mjs

@@ -6,6 +6,9 @@ import { subscribeScope, sendToNodeLink } 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: '' }
 
@@ -108,10 +111,26 @@ export function ensureNodeScope(options = {}) {
 		for (const handler of handlers)
 			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
 	})
-	nodeScopeWire ||= createNodeScopeWire()
+	if (!nodeScopeWire) {
+		nodeScopeWire = createNodeScopeWire()
+		for (const hook of nodeScopeWireHooks)
+			try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	}
 	return nodeScopeSubscribeCleanup
 }
 
+/**
+ * 在 node scope wire 创建时（或已存在时立即）回调；shell 用此挂自定义 action。
+ * @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)
+}
+
 /**
  * 卸掉 scope 订阅与 wire（feature 须先卸）。
  * @returns {void}

package/wire/part/fanout.mjs

@@ -61,10 +61,11 @@ export function partInvokeErrorMessages(results) {
 /**
  * 向 trust-graph top-K 扇出 part_invoke，收集 part_invoke_response。
  * 调用方须已挂载 `attachPartWire`（否则收不到 response）。
+ * `timeoutMs` 端到端约束：fanout 挂起（discoverRoute / stuck send）也不阻塞返回。
  * @param {string} username trust graph 上下文
  * @param {string} partpath part 路径
  * @param {PartInvoke} invoke 调用体
- * @param {number} [timeoutMs=2500] 超时
+ * @param {number} [timeoutMs=2500] 端到端超时
  * @param {number} [maxResponses=6] 最多响应数
  * @returns {Promise<PartInvokeResponse[]>} 邻居 PartInvokeResponse（含 error）
  */
@@ -85,15 +86,16 @@ export async function collectPartInvokeResponses(username, partpath, invoke, tim
 		pendingPartInvoke.set(requestId, { responses, finish, maxResponses, respondedPeers: new Set() })
 	})
 
-	const sent = await requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).fanoutToTopNodes(
+	// 勿 await fanout：否则 timeout 已触发也要等扇出 settle（#13）
+	void 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()
+	).then(sent => {
+		const pending = pendingPartInvoke.get(requestId)
+		if (pending && sent === 0) pending.finish()
+	}, () => { /* pending wait 超时负责 settle */ })
 
 	return waitForResponses
 }