perf(storage): add write_object upload strategies benchmarking suite

[xlai20]

Summary

Adds an independent benchmarking suite crate storage-benchmark-write-object under src/storage/benchmarks/write_object to evaluate and compare different upload strategies and checksum validation mechanisms for write_object.

This benchmarking suite provides empirical performance and throughput data across various payload sizes to inform the decision on the default write_object behavior for seekable sources (e.g., local files).

Scenarios Evaluated

1. Option A (Option_A_Unbuffered_Baseline):
   • .send_unbuffered()
   • Single continuous HTTP stream; 0 application heap buffer.
   • Checksum computed on the fly and validated client-side upon upload completion.
2. Option B (Option_B_Unbuffered_2Pass):
   • .precompute_checksums().await?.send_unbuffered()
   • Pass 1: Fast local disk scan to compute SIMD CRC32C checksum (populates page cache).
   • Pass 2: Single continuous HTTP PUT stream with x-goog-hash server-side validation header.
   • 0 application heap buffer.
3. Option C (Option_C_Buffered_Chunked):
   • .send_buffered()
   • 1-pass chunked upload using sequential 8 MiB HTTP PUT requests.
   • Server-side validation enforced by attaching checksum to the final chunk.
   • Requires 8 MiB in-memory buffer per upload.

Benchmark Features

• 5 Object Size Tiers: 12 MiB (single-shot multipart), 64 MiB (small resumable / 8 chunks), 512 MiB (medium resumable / 64 chunks), 2 GiB (large resumable / 256 chunks), and 8 GiB (stress resumable / 1,024 chunks).
• Pre-flight Warmup (512 KiB): Executes a one-time global warmup per process to verify authentication, check bucket permissions, and prime the TLS 1.3 connection pool before running measured iterations.
• Physical Disk & Page Cache Control
• Reporting & Orchestration:
  • Real-time terminal summary tables (Mean, P50, P90, P99 latency, and throughput in MiB/s).
  • Optional raw CSV latency and JSON summary persistence via GOOGLE_CLOUD_RUST_BENCHMARKS_STATS_OUTPUT_PATH.
  • run_all.sh driver script to run all 5 tiers sequentially.

Testing

• Unit tests added for CLI parsing and statistical metric calculations.
• Verified workspace compilation, cargo clippy --all-targets -- -D warnings, and cargo fmt.
• Executed full 5-tier benchmark runs on physical SSD storage against live GCS multi-region buckets.

[gemini-code-assist]

Code Review

This pull request introduces a new benchmark suite, storage-benchmark-write-object, to compare GCS write_object upload strategies and checksum modes. Feedback on the implementation highlights two style guide violations in source.rs: the use of blocking std::fs::create_dir_all within an asynchronous function, and the absence of required // SAFETY: comments on unsafe blocks.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.03%. Comparing base (597aa88) to head (da3f6c1).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6611      +/-   ##
==========================================
+ Coverage   97.01%   97.03%   +0.01%     
==========================================
  Files         326      326              
  Lines      107548   107548              
==========================================
+ Hits       104342   104356      +14     
+ Misses       3206     3192      -14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[xlai20]

This is part of the Issue #6461 , a benchmarking effort that is helping the final API definition decision.

For an 8GB file sit on disk,

• Option A (Baseline): 1 continuous PUT stream without upfront hash (client-side validation only).
• Option B (2-Pass Stream): Precompute local hash + 1 continuous PUT stream.
  • Result: +30% P50 latency (-16% throughput) vs Option A.
• Option C (1-Pass Chunked): Sequential 8 MiB in-memory chunked PUTs.
  • Result: +75% P50 latency (-41% throughput) vs Option A.

The executive decision is to turn on Option B to prioritize data integrity over speed; Option B incurs less performance penalty than Option C.

[vsharonlynn]

Approved. With a nit. Thank you!