perf(async): bound Future size without hot-path allocations

[AptS-1547]

Summary

• move the two archive copy buffers out of the inline async state-machine layout using one reusable Box<[u8]> per copy
• convert the five production no-await helpers, plus the now-synchronous cancel-label wrapper, to ordinary functions
• add archive copy regressions for future size, allocation count/bytes, exact/truncated/oversized input, shutdown, and write failure
• record focused before/after future-size and allocation evidence for archive, chunk upload, and WebDAV

Closes #486.

Design boundaries

• archive work keeps one 64 KiB buffer allocation per complete copy operation and reuses it across the loop
• upload and WebDAV request paths do not gain Box::pin, dynamic future dispatch, or any new per-request allocation
• the repository-wide future-size threshold remains unchanged
• sequential migration futures remain classified separately

Measurements

Baseline: 9b55dbfd18892e09227bfb0ff5de950586071dd5

Future size

Boundary	Before	After
Archive preview copy helper	65,792 B	272 B
Archive extract copy helper	65,792 B	272 B
Extract processing future	67,448 B	10,712 B
Extract task-spec upper future	67,736 B	11,000 B
Preview processing future	67,312 B	< 8,192 B
Preview task-spec upper future	67,600 B	< 8,192 B
Personal chunk-upload route	23,616 B	23,584 B
Team chunk-upload route	23,624 B	23,592 B
WebDAV dispatch	27,280 B	27,280 B

The temporary 8 KiB Clippy threshold was used only to measure the post-change archive callers; it is not committed as repository configuration.

Allocation count and requested bytes

Operation	Before	After	Delta
Archive preview copy	0 / 0 B	1 / 65,536 B	+1 / +65,536 B
Archive extract copy	0 / 0 B	1 / 65,536 B	+1 / +65,536 B
5 MiB offset-staging chunk upload	346 / 2,184,661 B	346 / 2,184,661 B	0 / 0 B
Warm authenticated WebDAV OPTIONS	73 / 34,233 B	73 / 34,233 B	0 / 0 B

Archive allocation regressions use a 128 KiB input, so the copy loops iterate across the 64 KiB buffer more than once while still recording exactly one buffer allocation.

Full methodology and warning classification are recorded in developer-docs/zh-CN/records/issue-486-future-size-evidence.md.

Clippy classification

For the main crate:

• large_futures: 17 -> 9; all eight archive cascade warnings are gone
• unused_async: 8 -> 3; all five production findings are gone
• the remaining large futures are eight measured upload boundaries and one unchanged WebDAV dispatch
• the remaining unused-async findings are debug/test-support refresh-rotation hooks
• four sequential migration warnings are unchanged and remain separate from request/background-copy priorities

Validation

• cargo fmt --all -- --check
• git diff --check
• RUSTC_WRAPPER= cargo clippy -p aster_drive --lib --all-features --message-format=short -- -W clippy::unused_async -W clippy::large_futures
• RUSTC_WRAPPER= cargo test --lib -- --test-threads=1 — 1,559 passed, 1 ignored
• RUSTC_WRAPPER= cargo test --lib services::files::archive::preview::tests -- --test-threads=1 — 18 passed
• RUSTC_WRAPPER= cargo test --lib services::task::archive::extract::staging::tests -- --test-threads=1 — 6 passed
• RUSTC_WRAPPER= cargo test --lib services::files::upload::lifecycle::tests -- --test-threads=1 — 9 passed
• RUSTC_WRAPPER= cargo test --lib services::files::upload::provider_relay::tests -- --test-threads=1 — 14 passed
• RUSTC_WRAPPER= cargo test --lib services::remote::master_binding::tests -- --test-threads=1 — 6 passed
• RUSTC_WRAPPER= cargo test --test files test_chunked_upload_flow -- --test-threads=1 — passed
• RUSTC_WRAPPER= cargo test --test webdav test_webdav_propfind_root -- --test-threads=1 — 2 passed
• cd docs && bun run developer-docs:build — 414 pages built; all internal links valid

Summary by CodeRabbit

• 性能优化

  • 优化归档复制流程，降低 Future 体积并改善内存使用表现。
  • 简化多个文件、上传及远程操作中的同步处理，减少不必要的异步开销。
  • 保持上传取消、文件锁、版本清理及请求校验的既有行为不变。

• 稳定性

  • 完善归档复制过程中的错误传播与边界处理。

• 文档

  • 新增相关性能测量记录及历史归档索引。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a912ef55-e9ab-4eb4-916f-55dedfe80b38

📥 Commits

Reviewing files that changed from the base of the PR and between 9b55dbf and 1404b54.

📒 Files selected for processing (12)

• developer-docs/zh-CN/records/README.md
• developer-docs/zh-CN/records/issue-486-future-size-evidence.md
• src/lib.rs
• src/services/content/version.rs
• src/services/files/archive/preview/mod.rs
• src/services/files/archive/preview/tests.rs
• src/services/files/file/lock.rs
• src/services/files/upload/lifecycle.rs
• src/services/files/upload/provider_relay.rs
• src/services/remote/master_binding.rs
• src/services/task/archive/extract/staging.rs
• src/test_support.rs

---

📝 Walkthrough

Walkthrough

本次变更优化归档复制 Future 的内存布局，新增分配测量与回归测试，并将五类无异步操作的辅助函数改为同步函数。中文开发记录新增 Issue #486 的测量结果、lint 分类和测试范围。

Changes

Future 体积与分配测量

Layer / File(s)	Summary
分配测量与失败写入支持 src/lib.rs, src/test_support.rs	测试构建启用 CountingAllocator，并新增 Future 分配测量和失败写入器。
归档复制缓冲区与回归测试 src/services/files/archive/preview/..., src/services/task/archive/extract/staging.rs	归档复制使用 64 KiB boxed slice。测试覆盖写入错误、Future 大小和单次 64 KiB 分配。
无异步操作辅助函数同步化 src/services/content/version.rs, src/services/files/file/lock.rs, src/services/files/upload/..., src/services/remote/master_binding.rs	版本配置、文件锁、上传生命周期、provider relay 和预签名绑定校验改用同步辅助函数。
测量结果与记录索引 developer-docs/zh-CN/records/...	新增 Issue #486 历史记录，记录 Future 体积、分配、lint 分类和归档复制测试范围。

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• AsterCommunity/AsterDrive#404：分配测量测试直接覆盖相关归档复制路径。
• AsterCommunity/AsterDrive#430：共享上传生命周期和同步解析 UploadSessionKind 的变更。

Suggested labels: Enhancement, Rust, Documentation

Poem

64 KiB 离开栈上，Future 变轻盈，
计数器记录每次分配的回声。
同步辅助函数收起等待，
归档测试守住边界与错误。
lint 清单留下证据，
猫猫，这次数据没有背叛。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.05% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确概括了降低异步 Future 大小且不增加热路径分配这一主要变更。
Description check	✅ Passed	描述包含变更摘要、设计边界、测量数据和完整验证结果，已覆盖模板要求的主要信息。
Linked Issues check	✅ Passed	变更满足 Issue #486 的归档 Future、分配、同步辅助函数、测试、测量和 Clippy 分类要求。
Out of Scope Changes check	✅ Passed	代码、测试和历史测量文档均服务于 Issue #486 的性能优化目标，未发现无关变更。

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/486-bound-future-size

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 88.05970% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/test_support.rs	83.33%	12 Missing ⚠️
src/services/files/upload/provider_relay.rs	0.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!