Files
tdc-rs/docs/UPSTREAM-TEST-PARITY.md
T
adminandClaude Code 1a0fdbf879 feat(upstream-parity): 移植上游测试用例 —— 29 条对位用例 + 第五把尺子
**影响**
- 生产档弱密钥守卫从「只比默认值」升级为上游 `ProdGuard` 的**六条判据**(纯函数),
  弱令牌用「默认值加后缀」绕过、弱标记词、长度下限三类都拦得住;`CIPHER_KEY`(协议共享值)**不受管**。
- 出向 TDS 超时**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS`),
  且**只有 cause 链里真有超时**才改写文案 ⇒ 连接被拒 / DNS 失败不再被误报成「超时」(排查方向不被带偏)。
- 上游 15 个测试类全部**登记在册**:3 个已移植(29 条对位用例)、12 个判定超范围(逐条记理由)。
- 新增第五把尺子 `scripts/check-upstream-tests.sh`:台账 ⇄ 代码 ⇄ 上游测试类集合三向对账,
  上游新增测试类而台账没登记 ⇒ **红**(不靠"记得看"防漂移)。
- 回归网:`cargo test` 246 → **278**(+32),其余四把尺子与引用自检**全绿**。

**改动**
- `src/platform/guard.rs`(新):上游 `ProdGuard.violations` 的纯函数移植(弱值清单 / 弱标记词整体词匹配 / `MIN_LEN=12` / 逐条点名)。
- `src/platform/config.rs`:`check_secret_guard` 改走守卫判据;新增 `guard_values`(只放本部署真有的键)
  与出向超时两项配置(非法值回落默认,不让连接器起不来)。
- `src/tdc/client/tds.rs`:新增 `cause_chain_has_timeout` / `timeout_text_or_null`(cause 链遍历**有界** `depth<16`),
  `TdsClient::with_timeouts` 接受超时。
- `tests/upstream_guard_parity.rs`(新 · 19 条)+ `tests/upstream_tds_timeout_parity.rs`(新 · 10 条)。
- `scripts/upstream-test-ledger.tsv`(台账真源)+ `scripts/upstream-test-census.py`(上游测试类普查/对账)
  + `scripts/check-upstream-tests.sh`(第五把尺子)。
- 文档:`docs/UPSTREAM-TEST-PARITY.md`(新)+ `docs/known-limitations.md` L8 + `docs/decisions.md` D22/D23
  + `CLAUDE.md` 同步(尺子表 / 目录树 / 命令速查 / 实现细节 22–23 / 坑位表)。

**设计**
- 上游 hop 1 的「反射读 socket 工厂」**抄不了**(`reqwest::Client` 不暴露超时 getter)⇒ 改用**行为级**判别
  (同一延迟 TCP 服务器:短超时⇒超时错、长超时⇒成功)⇒ 结论等价且更强(真跑 socket 层)。
- 上游 `*SelfTest.java` **surefire 不跑**(无统一入口)⇒ 判据落成 `cargo test` 常规用例(纯函数 ⇒ 可离线断言)。
- 超范围判定原则:**本仓没有对应功能 ⇒ 不搬**(硬搬只会是假绿);「机制」已覆盖的(P2P 那条)按机制记账。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 09:04:08 +08:00

182 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 上游测试用例移植台账(UPSTREAM-TEST-PARITY)
> 🔴 **本文件回答一个问题**:上游 TDC / TDS / ssw-common 里**有哪些测试用例**,我们在 tdc-rs 上**搬了哪些、没搬哪些、为什么**。
>
> **机器可复算的版本**在 `scripts/upstream-test-ledger.tsv`(台账 · 唯一真源);
> **自检**在 `scripts/check-upstream-tests.sh`(第五把尺子)。
> 本文件是**人读版**(背景 + 逐类说明 + 复跑命令)。
---
## 1. 为什么要做这件事
上游的测试用例**没有统一入口**:
| 上游形态 | 谁跑 | 本仓对位 |
|---|---|---|
| `*Test.java`(带 `@Test`) | Maven **surefire**(`mvn test`) | `cargo test`(集成测试) |
| `*SelfTest.java`(纯 `main`) | **surefire 不跑** ⇒ 上游自己靠 `tools/run-java-selftests.sh` 人工跑(退出码 0 = 过、**4 = UNVERIFIED ≠ 过**) | `cargo test`(`tests/upstream_*.rs`) |
⇒ 「上游有哪些用例、我们搬没搬」这件事**光靠肉眼看仓库是答不出来的** ⇒ 必须有一份
**可复算的清单 + 一把对账的尺子**,否则上游新增一个类而我们没看见 ⇒ **静默漂移**。
**普查结果**:上游 TDC + TDS + ssw-common 共 **15 个测试类**(6 个 JUnit + 9 个 SelfTest)
⇒ 本仓 **3 个已移植**(29 条对位用例)、**12 个判定为超范围**(逐条记理由 ⇒ `docs/known-limitations.md` L8)。
---
## 2. 逐类台账
### 2.1 已移植(3 类 · 29 条对位用例)
| 上游类 | 仓库 | 形态 | 上游断言 | 本仓对位 |
|---|---|---|---|---|
| `ssw.common.guard.ProdGuardSelfTest` | ssw-common | SelfTest | 10 | `tests/upstream_guard_parity.rs`(**12** 条) |
| `ssw.tds.controller.SswProdRuntimeGuardSelfTest` | TDS | SelfTest | 12 | `tests/upstream_guard_parity.rs`(**7** 条 / 10 条中可搬的部分) |
| `ssw.tdc.client.ProviderInvokeTimeoutsSelfTest` | TDC | SelfTest | 11 | `tests/upstream_tds_timeout_parity.rs`(**10** 条) |
> 本仓 12 + 7 + 10 = **29 条**对位用例,全部落在 `cargo test` 里(离线、秒级、无外部依赖)。
#### ① `ProdGuardSelfTest` ⇒ 生产档弱密钥守卫
**上游真源**:`boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/guard/ProdGuardSelfTest.java`
(判据本体 `.../src/main/java/ssw/common/guard/ProdGuard.java`)
上游 `ProdGuard.violations(map)` 的**六条判据**(缺一条即空检查 ⇒ 逐条照抄):
| # | 判据 | 本仓落点 | 对位用例 |
|---|---|---|---|
| ① | 键**不在** map 里 ⇒ **跳过**(不判本应用没有的键) | `src/platform/guard.rs:137` | `prod_guard_absent_key_is_not_falsely_blocked` |
| ② | 值为 null / 空白 ⇒ 违规 | `:147` | `prod_guard_blank_value_is_named` / `runtime_guard_prod_with_null_token_violates_without_panic` |
| ③ | 值**精确等于**已知弱值 ⇒ 违规 | `:152` | `prod_guard_exact_weak_value_is_blocked` / `prod_guard_default_weak_values_are_still_blocked` |
| ④ | 值**含**已知弱值 ⇒ 违规(**反绕过**) | `:158` | `prod_guard_default_value_with_suffix_is_blocked` |
| ⑤ | 值命中**弱标记词** ⇒ 违规 | `:166` | `prod_guard_weak_marker_word_is_blocked` / `prod_guard_weak_marker_is_whole_word_only` |
| ⑥ | 长度 < 12 ⇒ 违规 | `:174` | `prod_guard_min_len_is_enforced` / `prod_guard_too_short_value_is_blocked` |
| — | **强值必放行**(防"守卫恒红") | — | `prod_guard_strong_values_are_all_allowed` |
| — | 报错**点名**违规键 | `src/platform/guard.rs:188` | `prod_guard_violation_message_names_the_key` |
| — | 协议共享值**不受管**(上游 chg_0020) | `src/platform/guard.rs:29` | `prod_guard_cipher_key_is_not_guarded` |
**🔴 键名映射**(上游一个令牌两个方向通用 ⇒ 本仓拆成两个 ⇒ **两个都受管**):
| 上游 `GUARDED` 键 | 本仓 | 说明 |
|---|---|---|
| `ssw.internal-token` | `SSW_INTERNAL_TOKEN` | 入向(`X-Internal-Token` 闸门) |
| `tds-report.password` | `SSW_TDS_INTERNAL_TOKEN` | 出向(对端 internal 通道) |
| `ssw.dataset.pepper` / `oauth.login.jwtSecretKey` / `tdc-delivery.password` / `spring.datasource.password` | — | 本仓**无对应配置项** ⇒ 判据①跳过 |
| ~~`security.security-key`~~ | — | 上游 chg_0020 **已移出**(协议共享值,必须发给浏览器)⇒ 本仓 `CIPHER_KEY` **同样不受管** |
**🔴 判据④ 存在的理由**:只比精确值时,把默认值后面加一个字符(`ssw-internal-token-e2e1`)
就能绕过守卫 ⇒ 那是"改了但没真改" ⇒ 上游专门有这条,本仓照抄。
#### ② `SswProdRuntimeGuardSelfTest` ⇒ 生产档运行时闸门
**上游真源**:`boot/ssw-tds/ssw-tds-controller/src/test/java/ssw/tds/controller/SswProdRuntimeGuardSelfTest.java`
上游 `SswProdRuntimeGuard.evaluate(prod, codeDev, testEnv, token)` 是**纯函数** ⇒ 本仓的对位物同样是纯函数
(`Config::check_secret_guard()` + `Config::guard_values()`,不读进程全局 env)。
| 上游条 | 断言 | 本仓对位 |
|---|---|---|
| ① | 非 prod ⇒ 一律不违规 | `runtime_guard_non_prod_never_violates` |
| ② | prod + 门户验证码通道的 codeDev | 🚫 **超范围**(本仓无门户验证码通道) |
| ③ | prod + 令牌为空 ⇒ 违规并点名 | `runtime_guard_prod_with_empty_token_violates` |
| ④ | prod + 令牌为 null ⇒ 违规、不抛异常 | `runtime_guard_prod_with_null_token_violates_without_panic` |
| ⑤ | prod + 仓库默认弱值 ⇒ 违规 | `runtime_guard_prod_with_default_token_violates` |
| ⑥ | prod + 全强值 ⇒ 放行 | `runtime_guard_prod_with_strong_token_passes` |
| ⑦ | **判别性**(只翻 prod 一位 ⇒ 结论必须翻转) | `runtime_guard_is_discriminable_on_the_prod_switch` |
| ⑧ | 未声明测试环境 ⇒ 不放行 | 🚫 **超范围**(门户验证码通道) |
| ⑨ | 已声明测试环境 ⇒ 只放行验证码、**不放行**内部令牌 | 🚫 **超范围**(门户验证码通道) |
| ⑩ | **任何部署档位都解锁不了弱令牌** | `runtime_guard_no_deployment_flag_unlocks_a_weak_token` |
> ②⑧⑨ 三条都属**门户验证码通道**(`ssw.portal.code-dev`)⇒ 本仓**没有该通道**
> ⇒ 记 `OUT-OF-SCOPE-PART`(见 `docs/known-limitations.md` L8)。
> ⑩ 在本仓以**更强的形式**成立:连"单机模式"这种部署档位都解锁不了弱令牌。
#### ③ `ProviderInvokeTimeoutsSelfTest` ⇒ 出向超时的两跳判据
**上游真源**:`boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/ProviderInvokeTimeoutsSelfTest.java`
| 跳 | 上游判据 | 本仓对位 | 手法差异 |
|---|---|---|---|
| ① | 注入的超时值**真的落进 socket 工厂**(反射读 `SimpleClientHttpRequestFactory`)+ 判别性 | `hop1_injected_timeout_actually_reaches_the_socket_layer` / `hop1_changing_the_injected_value_changes_the_client` | 🔴 **行为级替代反射**:Rust 的 `reqwest::Client` **不暴露**超时 getter ⇒ 改用「短超时 ⇒ 超时错 / 长超时 ⇒ 成功」(同一个延迟 TCP 服务器)⇒ 结论**等价且更强**(真跑 socket 层,不是读字段) |
| ② | **只有** cause 链里有 `SocketTimeoutException` 才改写文案;`ConnectException` / `UnknownHostException` / 无 cause ⇒ **不改写**;多层包装仍须命中;cause 链**有界**(`depth < 16`) | `hop2_read_timeout_is_rewritten_and_names_current_values` / `hop2_connect_timeout_is_rewritten` / `hop2_connection_refused_is_not_rewritten` / `hop2_dns_failure_is_not_rewritten` / `hop2_no_cause_is_not_rewritten` / `hop2_multilevel_wrapped_cause_is_still_detected` / `hop2_cause_chain_walk_is_bounded` / `hop2_end_to_end_connection_refused_stays_unreachable` | 照抄(`src/tdc/client/tds.rs:74` 的 `cause_chain_has_timeout` + `:112` 的 `timeout_text_or_null`) |
> 🔴 判据②的**反例**(连接被拒 / DNS 失败 **不得**说成"超时")在本仓是**实机**验证的:
> `hop2_end_to_end_connection_refused_stays_unreachable` 真打一个没人监听的端口 ⇒ 文案必须是「TDS 不可达」。
### 2.2 判定为超范围(12 类)
逐条理由在 `scripts/upstream-test-ledger.tsv` 的 `reason` 列,汇总见 `docs/known-limitations.md` **L8**。
分类:
| 类别 | 类 | 为什么超范围 |
|---|---|---|
| 隐私计算执行面 | `ExecNfsSupportTest` / `NaxPodSupportTest` / `NaxExecRenderTest` / `K8sSandboxClientRenderTest` | 依赖 **Nax 引擎 + K8s 拓扑**(NFS 通道 / Pod 模板渲染)⇒ 本仓明确不做(`CLAUDE.md`「明确不在本仓库范围」) |
| P2P 传输 | `P2pTransferTimeoutsSelfTest` | 判据对象是 **P2P 出向客户端** ⇒ 本仓无 P2P 通道;**机制**本身已由 `ProviderInvokeTimeoutsSelfTest` 那条覆盖 |
| MaxKey SSO | `MaxkeyRegisterPrecheckSelfTest` / `MaxkeyAppRegistrarLogicSelfTest` / `MaxkeyMgtClientLiveSelfTest` | 本仓**不实现 MaxKey SSO**(`/Auth/SsoConfig` 恒 `enabled:false`,见 L2);第三条还是**实机**打真 MaxKey |
| CA 签发 | `CertSignerStrictSelfTest` | 软 PKI / CA 签发由上游 **scard 安全平面**承担 ⇒ 本仓不做 |
| 守门告警表 | `GuardAlertTypeSelfTest` | 告警表在 **TDS 侧** ⇒ 本仓无对应表 |
| IP 白名单 | `IpWhitelistUtilTest` | 本仓**没有**该功能(入向只认内部令牌 + 会话令牌) |
| LLM 客户端 | `SswLLMClientTest` | 本仓**没有** LLM 客户端 |
---
## 3. 怎么复跑
```bash
# ① 对位用例(29 条,秒级、离线)
cargo test --test upstream_guard_parity --test upstream_tds_timeout_parity
# ② 第五把尺子:台账自检 + 与上游普查对账
bash scripts/check-upstream-tests.sh
# ③ 只看台账不判红(排障)
bash scripts/check-upstream-tests.sh --report
# ④ 重新普查上游测试类(上游克隆不在场 ⇒ 自动跳过该侧校验,不判红)
python3 scripts/upstream-test-census.py
python3 scripts/upstream-test-census.py --check
# ⑤ 上游克隆路径可覆盖
UPSTREAM_TDC_CLONE=/tmp/sswtdc-probe UPSTREAM_TDS_CLONE=/tmp/sswtds-probe \
bash scripts/check-upstream-tests.sh
```
🔴 **上游克隆不在场不判红**(只跳过「上游有、台账无」与「上游文件存在」两项)——
台账里登记的类**仍然**按台账校验(PORTED 行必须真有对位用例)。
---
## 4. 台账格式(`scripts/upstream-test-ledger.tsv`,制表符分隔)
| 列 | 含义 |
|---|---|
| 1 `upstream_class` | 上游全限定类名 |
| 2 `upstream_repo` | `TDC` / `TDS` / `COMMON`(ssw-common 两侧都有 ⇒ 记 `COMMON`) |
| 3 `upstream_file` | 相对**克隆根目录**的路径 |
| 4 `kind` | `JUNIT`(surefire 跑) / `SELFTEST`(纯 main,**surefire 不跑**) |
| 5 `assertions` | 上游断言条数(`-` = 未逐条计数) |
| 6 `tdc_counterpart` | 本仓对位:`文件::fn1+fn2+…`(`-` = 无对位) |
| 7 `status` | `PORTED` / `OUT-OF-SCOPE` |
| 8 `reason` | 搬法说明 / 不搬的理由(**必填**) |
**尺子管的四件事**:
1. 每行 8 列、`status` 合法、`reason` 非空;
2. `PORTED` 行的对位文件**存在**、登记的用例函数**真在**那个文件里;
3. `OUT-OF-SCOPE` 行的对位必须为空(`-`);
4. **文件级集合相等**:台账登记的用例集合 == 对位文件里实际存在的移植用例集合(防少登记 / 多登记)。
🔴 第 4 条靠**前缀约定**识别"移植用例":`upstream_` / `hop1_` / `hop2_` / `runtime_guard_` / `prod_guard_`
⇒ 辅助函数(`spawn_delayed_server` 之类)不会被误计。
---
## 5. 相关文档
| 文档 | 讲什么 |
|---|---|
| `docs/decisions.md` **D22 / D23** | 守卫语义升级为上游六条判据;出向超时外置到 env + cause 链分类 |
| `docs/known-limitations.md` **L8** | 12 个超范围的上游测试类 + 3 条门户验证码相关的未搬断言 |
| `docs/TDC-TDS-CONTRACT.md` | 出向通道的降级三档(超时归入「不可达」那一档的**细分**) |