**影响** - 生产档弱密钥守卫从「只比默认值」升级为上游 `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]>
12 KiB
上游测试用例移植台账(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.mdL8)。 ⑩ 在本仓以更强的形式成立:连"单机模式"这种部署档位都解锁不了弱令牌。
③ 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 |
搬法说明 / 不搬的理由(必填) |
尺子管的四件事:
- 每行 8 列、
status合法、reason非空; PORTED行的对位文件存在、登记的用例函数真在那个文件里;OUT-OF-SCOPE行的对位必须为空(-);- 文件级集合相等:台账登记的用例集合 == 对位文件里实际存在的移植用例集合(防少登记 / 多登记)。
🔴 第 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 |
出向通道的降级三档(超时归入「不可达」那一档的细分) |