Easytier/plans/004-reuse-ospf-route-graph.md

计划 004：复用 OSPF route-table 构图以减少拓扑更新成本

执行者说明：按步骤执行本计划。每一步都必须运行验证命令，并确认结果符合预期后再继续。如果触发“STOP 条件”中的任一情况，立即停止并报告，不要自行发挥。完成后更新 plans/README.md 中本计划的状态行，除非 reviewer 明确说明由他们维护索引。

漂移检查（首先运行）：git diff --stat 78146d16..HEAD -- easytier/src/peers/peer_ospf_route.rs easytier/src/tests 如果本计划写成后任何范围内文件发生变化，继续前必须对照“当前状态”中的摘录与实时代码；如果不匹配，按 STOP 条件处理。

状态

• 优先级: P2
• 工作量: M
• 风险: MED
• 依赖: plans/003-avoid-noop-ospf-route-rebuilds.md
• 类别: perf
• 计划生成于: commit 78146d16, 2026-06-18

为什么重要

每次 OSPF 拓扑更新当前会分别为 least-hop 和 least-cost route table 调用 build_from_synced_info。每次调用都会从 synced info 重新构建 peer graph，并重新构建 peer/CIDR indexes。对于 peer 数和 proxy CIDR 数较大的 mesh，这把一次拓扑变化放大成两次完整构图和多次 map/trie 重建。完成后应保持 route selection 结果不变，同时复用同一份 graph/materialized synced view，减少 CPU 和分配成本。

当前状态

• easytier/src/peers/peer_ospf_route.rs — update_route_table、graph builder、least-hop/least-cost map generation、CIDR trie rebuild 均在此文件。

当前代码摘录：

// easytier/src/peers/peer_ospf_route.rs:1628
// build next hop map
let (graph, start_node) =
    Self::build_peer_graph_from_synced_info(my_peer_id, synced_info, cost_calc);

// easytier/src/peers/peer_ospf_route.rs:1649
if matches!(policy, NextHopPolicy::LeastHop) {
    self.gen_next_hop_map_with_least_hop(&graph, &start_node, version);
} else {
    self.gen_next_hop_map_with_least_cost(&graph, &start_node, version);
};

// easytier/src/peers/peer_ospf_route.rs:1655
let mut new_cidr_prefix_trie = PrefixMap::new();
let mut new_cidr_v6_prefix_trie = PrefixMap::new();

// easytier/src/peers/peer_ospf_route.rs:2453
fn update_route_table(&self) {
    // ...
    self.route_table.build_from_synced_info(
        self.my_peer_id,
        &self.synced_route_info,
        NextHopPolicy::LeastHop,
        calc_locked.as_ref().unwrap(),
    );

    self.route_table_with_cost.build_from_synced_info(
        self.my_peer_id,
        &self.synced_route_info,
        NextHopPolicy::LeastCost,
        calc_locked.as_ref().unwrap(),
    );
}

仓库约定：core routing behavior must be preserved。先添加 characterization tests，再重构；不要在同一计划里改 route policy。

需要使用的命令

Purpose	Command	Expected on success
Format	cargo fmt --all -- --check	exit 0
Lint	cargo clippy --all-targets --features full --all -- -D warnings	exit 0, no warnings
Targeted tests	cargo test --package easytier peer_ospf_route --features full -- --nocapture	exit 0; route characterization tests pass
Archive tests	cargo nextest archive --archive-file tests.tar.zst --package easytier --features full	exit 0

临时目录约定

• 临时文件、scratch 目录和 disposable worktree 必须放在 $HOME/tmp 下。
• 如果 $HOME/tmp 不存在且本计划需要临时空间，先创建它。
• 不要把临时产物放进被修改仓库。

范围

范围内（只能修改这些文件）：

• easytier/src/peers/peer_ospf_route.rs
• easytier/src/tests/*（仅新增/调整 route-table characterization tests）

范围外（即使看起来相关也不要触碰）：

• Route protocol schema and wire format。
• Credential/trust semantics。
• Peer center、foreign network manager、data-plane tunnels。
• Any UI or config surface。

Git 工作流

• Branch: advisor/004-reuse-ospf-route-graph
• Commit message style follows existing conventional commits, for example refactor: introduce HedgeExt for task hedging; rewrite NatDstQuicConnector.
• Do NOT push or open a PR unless the operator instructed it.

步骤

步骤 1：添加 route-table characterization tests

在修改实现前，新增测试覆盖至少一个包含以下元素的小拓扑：

• 本 peer、两个 reachable peers、一个 unreachable 或 outdated peer。
• 至少一个 IPv4 proxy CIDR 和一个 IPv6 proxy CIDR。
• least-hop 和 least-cost 结果不同或至少都被断言。

测试应断言当前 route_table 和 route_table_with_cost 对 peer next-hop、peer reachability、CIDR lookup 的结果。优先使用现有测试 helper；如果内部 API 不便，添加 #[cfg(test)] helper，不改变生产 API。

验证：cargo test --package easytier peer_ospf_route --features full -- --nocapture → exit 0；新增 characterization tests 在重构前通过。

步骤 2：抽出一次性 graph build 输入

在 peer_ospf_route.rs 中把 build_from_synced_info 内部的 graph construction 拆成私有 helper，例如：

• build_peer_graph_from_synced_info(...) 已存在则复用。
• 新增 small struct 持有 graph、start_node、version 和后续 index rebuild 需要的 synced snapshot references。

不要改变 gen_next_hop_map_with_least_hop 或 gen_next_hop_map_with_least_cost 的算法。

验证：cargo test --package easytier peer_ospf_route --features full -- --nocapture → exit 0。

步骤 3：让 update_route_table 对两种 policy 复用 graph

把 update_route_table 改为在持有 cost_calculator read lock 时构建一次 graph/materialized input，然后分别对 self.route_table 和 self.route_table_with_cost 应用 least-hop / least-cost generation。

如果现有 RouteTable::build_from_synced_info 是唯一封装点，可以新增一个 sibling method，例如 build_from_prebuilt_graph(...)，保持旧方法用于兼容 tests 或其他调用方。

验证：cargo test --package easytier peer_ospf_route --features full -- --nocapture → exit 0；characterization tests 仍通过。

步骤 4：避免重复构建共享 indexes

检查 build_from_synced_info 中 peer info map、IPv4 map、CIDR tries 的生成是否依赖 policy-specific next-hop map。如果只依赖 reachability 或 synced info，可移动到共享 helper；如果依赖每个 RouteTable 自己的 next_hop_map，不要强行共享，避免改变 semantics。

允许分阶段收益：只共享 graph build 也可完成本计划；共享 CIDR/index 只有在 characterization tests 能证明 behavior 不变时才做。

验证：cargo test --package easytier peer_ospf_route --features full -- --nocapture → exit 0。

步骤 5：运行完整相关门禁

验证：

• cargo fmt --all -- --check → exit 0。
• cargo clippy --all-targets --features full --all -- -D warnings → exit 0。
• cargo nextest archive --archive-file tests.tar.zst --package easytier --features full → exit 0。

测试计划

• 新增 route-table characterization tests，先在重构前证明现有行为，再在重构后保持通过。
• 测试覆盖 least-hop、least-cost、CIDR lookup、unreachable peer exclusion。
• 如果可行，加入一个轻量 counter/helper 在 test-only path 确认 graph builder 调用次数从 2 降为 1；如果这需要侵入生产代码，则不要做。

完成标准

• update_route_table 不再对同一 synced topology 构建两次 peer graph。
• least-hop 和 least-cost route outputs 与 characterization tests 中的旧行为一致。
• 没有改变 routing protocol、credential trust 或 config behavior。
• cargo fmt --all -- --check exits 0。
• cargo clippy --all-targets --features full --all -- -D warnings exits 0。
• cargo nextest archive --archive-file tests.tar.zst --package easytier --features full exits 0。
• 没有修改范围外文件。
• 已更新 plans/README.md 中本计划的状态行。

STOP 条件

• plans/003-avoid-noop-ospf-route-rebuilds.md 未完成，且当前 route rebuild trigger 仍会对 no-op payload 重算。
• 复用 graph 需要改变 least-hop 或 least-cost algorithm。
• 现有代码让 cost_calc 在两次 build 之间发生有意状态变化；如果确认 begin_update/end_update 依赖两次独立 build，停止并报告。
• Characterization tests 无法稳定构造 route-table expected outputs。

维护说明

• reviewer 应重点审查是否在锁持有期间引入更长 critical section。
• 未来新增 route policy 时应复用本计划抽出的 prebuilt graph input，而不是再调用完整 build_from_synced_info。
• 本计划不拆分 peer_ospf_route.rs 大文件；只做局部性能重构。