ShadowsocksX-NG/docs/design/http-latency-phases.md

# HTTP 延迟分阶段测量

本文件记录 2026-10-15 确认的实现规格。当前行为以代码、GLOSSARY.md 和 ADR 为准。

## 测量契约

- 仅正式测速使用手写 HTTP/1.1；接受 HTTP/1.0 响应。不支持 HTTPS 测速。
- 主数值从开始连接隔离代理的本地 HTTP 入口，到收完最终响应头。
- 2xx 成功，不跟随重定向，不等待响应体；保留配置失效、冷却、历史和结果过期语义。
- 每节点一个隔离 sslocal，节点之间串行；不改变正式运行配置或系统代理。
- 准备阶段通过同一节点的系统 HTTPS 查询 DoH。Google 失败后尝试 Cloudflare；A/AAAA 查询共用每解析器 3 秒绝对时限。
- 每批重新解析，不复用跨轮次 DNS 缓存；IP 字面量目标跳过 DoH。
- 去重后最多测试 2 个 IPv4、2 个 IPv6 候选，逐个执行最多 3 秒的 HTTP 请求；固定完整响应头最快的成功 IP，保留原 Host 与路径、查询参数。
- 同一进程下连续正式采样 3 次，每次新建本地 TCP 连接，时限各 5 秒；至少 2 次成功才返回成功样本中位数，2 个样本取算术平均。
- 准备总上限 30 秒，启动子阶段上限 10 秒；所有准备步骤受剩余总预算约束。

## 观测与日志

一个测量 module 通过一个 interface 返回总结果与阶段记录。调用方不操作 DNS、socket 或 HTTP 解析状态。测试覆盖测量 interface、现有 ServerConnectivity 调度 seam 和 HTTP 请求 seam。

应用内诊断日志记录：启动；每次 DoH（含解析器和回退）；候选与选定 IP；每次正式样本；本地 TCP、发送、等待首字节、首字节到完整响应头的耗时；结果和失败阶段。时间戳使用单调时钟测量。数值有测量标识与样本编号。未到达阶段无数值，不伪造 0。

不记录 URL、域名、查询 token、凭据、原始错误或插件参数。目标 IP 只出现在显式诊断日志查看/复制，安全诊断报告不导出这些事件。

DoH 时间包含整次代理查询，不称为纯 DNS 耗时。远程 TCP、代理服务器域名解析与插件握手不可独立观测，归入代理请求的混合耗时。发送完成表示本地写入完成，不证明远端收到。

## 证据与验收

- 固定 IP 的代理请求保留原 Host，IPv4/IPv6 URL 和查询编码正确。
- 分片/临时响应头、失败状态、大小限制、超时、取消、无响应体等待通过受控代理验证。
- 准备回退、候选限制、最快成功地址、固定地址采样、中位数和失败阈值通过测量 interface 验证。
- DoH 必须经过指定本地代理，拒绝不可信 TLS 和重定向，不回落直连；解析失败不启动正式采样。
- 调度串行、失效结果抑制、进程所有权、清理与取消保留验证。
- 全量 hostless 测试、构建与真实 sslocal 进程 smoke 分别报告。不把它们当作远程互通或手机端一致性的证明。