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

12 KiB
Raw Blame History

上游测试用例移植台账(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. 怎么复跑

# ① 对位用例(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 出向通道的降级三档(超时归入「不可达」那一档的细分)