router

topcoat-router 是整个工作区最大的 crate，src/ 下 2.3 万行（含测试），请求主线和发现主线都落在这里。它不建在 axum 上：服务器用 hyper 1 和 hyper-util 的 auto::Builder，路径匹配用 matchit 0.9，中间件是自己的 Layer trait，handler 拿到的是自己的上下文 Cx。后面每一章讲到请求、响应、上下文、交互时都会链回这里。

五章按「请求进来的顺序」排：

1. 从连接到分发：start / serve / serve_until；accept 循环、三个 watch 通道「靠关闭传信号」的优雅关停（实测：宽限期 2 秒，1 秒的请求正常完成，5 秒的请求在 2 秒后被切断，端口立刻释放）；accept 出错时整个服务停止（ulimit -n 24 复现）；0.10.0 没给 hyper 配计时器，读请求头的超时不生效；catch_unwind 为什么包在每一次 poll 上；rewrite 循环；分发顺序与 404、405、HEAD。
2. 路由表与 layer 链：RouterBuilder::build 把 page、layout、route、layer 编成 Endpoints 和 Routes 两张表；Next 是「剩余 layer 切片加终点」；没有路径的 layer 连 404 也包、有路径的只包匹配上的路由；layout 按路径前缀嵌套；尾斜杠默认 308 重定向；BodyLimit 默认 2 MiB，本身也是一个 layer；建表时的四种 panic。
3. 模块路由与发现：inventory 在链接期收集，module_path!() 决定 URL；_group、kebab-case、segment!、module_param!、catch-all、./ 相对路径；href! 按 Rust 名字反查 URL；展开一个 #[page] 逐段对照；0.10.0 里根模块之外的 handler 会让启动 panic。
4. 请求、响应与错误：FromRequest 与 IntoResponse 同一组类型两用；content/ 下各种内容类型；not_found、redirect、rewrite 都是 Error，靠 downcast 识别；未识别的错误变成 500 且原因被丢掉；流式开始之后的重定向变成一段脚本。
5. tower 互操作与可信代理：TowerRoute 把 axum 应用挂进来、TowerLayer 用一条 mpsc 通道把 tower 中间件和 topcoat 的 layer 链接起来、TowerService 把 topcoat 交给 axum 当 fallback；TrustedProxies 的 networks 与 nearest；为什么压缩在所有 layer 之外。

flowchart TB
  serve["从连接到分发：accept、关停、catch_unwind、rewrite"] --> table["路由表与 layer 链：Endpoints、Routes、Next"]
  module["模块路由与发现：inventory、module_path"] --> table
  table --> resp["请求、响应与错误：FromRequest、IntoResponse、Error"]
  table --> tower["tower 互操作与可信代理"]

src/ 下主要文件的分工（行数含文件内测试）：