[multica-tsic404]

Closes TSI-4316

Issue: https://multica.tsic.top/issues/TSI-4316

设计依据: tsic/torrentfs-design@5b622b6

设计实现

设计要求	代码落点
03-acceptance AC-72；02-contracts C-10.11、C-5.3.1（stop→start 后种子与缓存保留、二次读命中）	tests/acceptance/tc_container_03.sh:259
03-acceptance AC-73；02-contracts C-10.2、C-10.3、C-10.9（参数透传、默认行为、无效配置与用法退出码）	tests/acceptance/tc_container_04.sh:156
03-acceptance AC-74；02-contracts C-10.9（101）；ADR-012 防叠加与互斥（顺序/同时启动）	tests/acceptance/tc_container_05.sh:205
03-acceptance AC-75；02-contracts C-10.2（环境变量非空/空串/命令行优先级）	tests/acceptance/tc_container_06.sh:151
03-acceptance AC-76；02-contracts C-10.10、C-10.12；ADR-012 陈旧挂载回收与停止宽限	tests/acceptance/tc_container_07.sh:189
03-acceptance AC-77；02-contracts C-10.1、C-4.4（容器形态诊断单流采集与冻结前缀）	tests/acceptance/tc_container_08.sh:106
03-acceptance:4 可执行形态（脚本按用例编号落仓并登记）	tests/acceptance/main.rs:134
01-scope 禁项：不做内核文件系统、不自行实现 BT 协议	未引入（仅新增验收脚本与注册表/CI 登记，无产品代码改动）

验证

• cargo test --locked --test acceptance -- registry_tests：4 passed, 0 failed。
• bash -n 六条脚本通过；git diff --check 通过。
• 容器脚本实跑（docker 29.9.2；rootful，--device /dev/fuse + SYS_ADMIN）：
  • tc_container_03.sh PASS：stop/start 后种子与缓存保留，二次读 0ms，cache hits 0→32、misses 0。
  • tc_container_04.sh PASS：配置/缓存/DB/日志参数生效；无效配置 exit 1 且含原因；用法错误 exit 2。
  • tc_container_05.sh PASS：顺序与同时启动两档下后启动者 exit 101，先启动者仍可列出目录且无 ENOTCONN。
  • tc_container_06.sh PASS：默认路径 32.00 MB 生效；环境变量 64.00 MB 覆盖；空串回落 1.00 GB 默认且不读默认路径；命令行 16.00 MB 优先。
  • tc_container_07.sh SKIP（exit 2）：本执行环境宿主侧 rshared 传播不可用，按自门禁记账；CI 提供 shared host dir 时执行。
  • tc_container_08.sh PASS：非 TTY 单流采集命中冻结前缀 1 次；同形正向对照通过；stdout/stderr 未合并。

Summary by Sourcery

Expand container acceptance coverage for entrypoint behavior, persistence, mount lifecycle, configuration precedence, and diagnostic stream handling.

Enhancements:

• Add six container acceptance cases covering restart state and cache persistence, entrypoint argument and exit-code behavior, mount conflicts, configuration precedence, stale mount recovery, and non-TTY diagnostics.

CI:

• Extend CI syntax validation and rootful container acceptance execution to TC-container-03 through TC-container-08, continuing past capability-based skips.

Tests:

• Register the new container acceptance cases in the acceptance test registry.

[sourcery-ai]

Sorry @multica-tsic404[bot], you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 21 hours and 9 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

This PR completes the container entrypoint acceptance coverage by adding six self-gating, timeout-bounded Docker/FUSE scripts, registering them as executable acceptance cases, and wiring syntax validation and rootful execution into CI; no product code is changed.

Flow diagram for container acceptance coverage

flowchart TD
    Registry[Acceptance registry] --> TC03[TC-container-03: stop/start retention and cache hit]
    Registry --> TC04[TC-container-04: parameters and exit codes]
    Registry --> TC05[TC-container-05: singleton startup exclusion]
    Registry --> TC06[TC-container-06: environment and CLI precedence]
    Registry --> TC07[TC-container-07: stale mount cleanup and grace period]
    Registry --> TC08[TC-container-08: diagnostic stream and frozen prefix]
    TC03 --> Contract[Container entrypoint contracts]
    TC04 --> Contract
    TC05 --> Contract
    TC06 --> Contract
    TC07 --> Contract
    TC08 --> Contract

Loading

File-Level Changes

Change	Details	Files
Adds six executable container acceptance tests covering persistence, entrypoint configuration, mount exclusivity, configuration precedence, stale-mount recovery, and diagnostic stream behavior.	Verifies stop/start persistence of torrent metadata and cached pieces, including cache-hit counters after restart. Exercises CLI parameter passthrough, defaults, invalid configuration handling, and usage exit codes. Tests sequential and concurrent shared-mount conflicts, requiring loser exit code 101 while preserving the winner. Validates mounted default, environment, empty environment, and CLI configuration precedence through observable cache limits. Reproduces SIGKILL-induced ENOTCONN residue, applies host-side recovery, verifies restart, and checks clean normal stop. Captures non-TTY stdout/stderr separately and checks frozen no-seeder diagnostics plus a positive channel control.	tests/acceptance/tc_container_03.sh tests/acceptance/tc_container_04.sh tests/acceptance/tc_container_05.sh tests/acceptance/tc_container_06.sh tests/acceptance/tc_container_07.sh tests/acceptance/tc_container_08.sh
Registers the new acceptance cases and integrates syntax checks and execution into CI.	Adds TC-container-03 through TC-container-08 to the Rust acceptance registry. Runs bash syntax validation for all six scripts. Expands rootful CI execution to all container cases and continues after capability-based skips instead of aborting the job.	tests/acceptance/main.rs .github/workflows/ci.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[tsic404]

规模：8 文件 / +1473 −3，全部是本单载体（tests/acceptance/tc_container_03.sh..tc_container_08.sh）+ tests/acceptance/main.rs 的 SCRIPT_FORM 登记 + .github/workflows/ci.yml 的语法检查与容器验收循环登记，无产品代码改动。

通过维度：

1. 判据对应 — 六条脚本逐条对上 docs/03-acceptance.md:167-172 的 TC 可观察判据与 docs/02-contracts.md C-10.1/C-10.2/C-10.3/C-10.9/C-10.10/C-10.11/C-10.12、C-5.3.1、C-4.4.1、ADR-012（设计锚点 5b622b6）；无「能跑通即通过」的替代判据。
2. 错误类断言查退出码/errno 本身 — 后启动者 101（tc_container_05.sh 顺序档与同时档）、无效配置 1 与用法错误 2（tc_container_04.sh 的 expect_rc）、ENODATA（tc_container_08.sh 读失败断言 No data available，即 ENODATA 的文本面，与 EIO 可区分）、ENOTCONN（tc_container_07.sh 宿主侧 stat）。
3. 自门控 — SKIP 仅出现在能力缺失：docker、/dev/fuse、镜像构建、宿主 rshared 传播、宿主 root 恢复步骤；没有一处通过 SKIP 放宽判定或跳过断言。
4. 执行证据 — CI Docker Build (amd64) 的 Run acceptance container cases 八条全 PASS、零 SKIP（含本机被跳过的 TC-container-07）；注册表四条门禁绿。
5. 安全 — 脚本仅为测具：rm -rf 目标全为 mktemp 自建路径，caller-supplied 宿主目录只卸挂载不删目录；容器仍以 --device /dev/fuse --cap-add SYS_ADMIN --security-opt apparmor=unconfined 运行，与既有 tc_container_01.sh/tc_container_02.sh 同构，未扩大执行面；无未引用变量导致的注入点。

点赞：tc_03 先停 seeder 再重启，用「hits 增 + misses 不变」加读耗时双重判定，堵住「有对端所以能读通」冒充缓存命中；tc_06 先跑默认路径对照（32.00 MB）再判空串场景，排除空值用例空转；tc_08 先做同形正向对照自证通道（stdout/stderr 不合并），再判冻结前缀计数 ≥ 1，并明确把事后重放排除在证据外；tc_05 顺序与同时两档都要求恰好一个赢家且赢家无 ENOTCONN。

其他审查者：无（gh pr view --json reviews 为空，无待承接的 CHANGES_REQUESTED）。

发现：1 条（💭，已就近锚定）。

[tsic404]

复审（388f565..43846c8）：本轮实际 diff 只有 .github/workflows/ci.yml 容器验收作业上方那段理由注释（10 行增 / 5 行删），脚本、注册表与循环逻辑逐字未变（git diff --stat 388f565 origin/multica/TSI-4316 仅该文件）。上轮唯一发现已解决：注释改为 TC-container-01..08 并列出六条覆盖面，且写清了自门禁语义（缺 /dev/fuse、CAP_SYS_ADMIN、共享宿主目录 → exit 2 → 记 SKIP warning 后 continue；其余非零退出使作业失败），与 234-242 行代码一致。

复审复核的维度（均已重新对照，非沿用上轮结论）：

1. 判据对应 — 六脚本仍逐条对上 docs/03-acceptance.md:167-172、docs/02-contracts.md C-10.1/C-10.2/C-10.3/C-10.9/C-10.10/C-10.11/C-10.12、C-5.3.1、C-4.4.1 与 ADR-012（锚点 tsic/torrentfs-design@5b622b6）。
2. 错误类断言 — 101（顺序与同时两档）、无效配置 1 与用法 2、ENODATA（No data available）、ENOTCONN 均查退出码或 errno 文本面。
3. 自门控 — SKIP 仅出现在能力缺失；本轮注释改写没有改变任何脚本的自门控或断言。
4. 执行证据 — head 43846c8 的 Docker Build (amd64) → Run acceptance container cases：01..08 全 PASS、零 SKIP；全量检查在该 head 上全绿。
5. 安全 — 仅测具改动；rm -rf 目标全为自建临时路径，caller-supplied 宿主目录只卸挂载不删目录；容器权限参数与既有 tc_container_01/02.sh 同构。

其他审查者：无新增 review，无待承接的 CHANGES_REQUESTED（上轮即本账号的 REQUEST CHANGES，本轮已随之消解）。

结论：零发现，APPROVE。

说明：本机环境无宿主 rshared 传播，TC-container-07 本机为 SKIP（exit 2，自门禁）；该用例在 CI 上实际执行并通过（SIGKILL residue reproduced as ENOTCONN … normal stop left no residue），故其判据已有执行证据。