feat(storage): implement V4 Signed Policy Documents

[xlai20]

Description

This PR introduces support for generating V4 Signed Policy Documents (PostPolicyV4Builder), bringing the Rust SDK into feature parity with other official GCS SDKs for POST form object uploads.

Design Doc: go/rust-sdk-feature-v4-signed-policy-document-implementation_plan

Key Additions

• PostPolicyV4Builder API: A fluent builder API to configure URL styles, exact-match fields, starts-with prefix conditions, and content-length-range limits.
• Strict JSON Serialization: Implemented exact-byte character escaping using UTF-16 surrogate pairs (\uXXXX) to guarantee flawless Base64 JSON encoding, satisfying GCS's stringent signature validation requirements.

Testing & Validation

• Manual Validation: I have manually run the added generate_signed_post_policy_v4 sample code against a real Cloud Storage bucket and verified the upload worked correctly.
• Conformance Tests Passed: Integrated with the official v4_signatures.json test harness, successfully passing 100% (11/11) of the postPolicyV4Tests (covering Path Style, Virtual Hosted Style, Bucket Bound Hostnames, and Unicode conditions).
• Cross-Language Parity Check: Verified that $key condition formulation and the maximum 7-day expiration bounds behave identically to the official Go and C++ SDKs.
• Integration Tests: Added signed_post_policies_v4 in tests/storage/src/lib.rs which dynamically constructs a policy and performs a live upload using a reqwest multipart form. It ran successfully against a real Cloud bucket.

[gemini-code-assist]

Code Review

This pull request implements support for GCS V4 Signed Policy Documents (POST Object Forms) by introducing PostPolicyV4Builder and PostPolicyV4Result, along with associated examples, integration tests, and conformance tests. Key feedback includes addressing a bug where custom endpoints with ports lose their port number during URL resolution, automatically prepending $ to starts-with fields, validating expiration limits and content length ranges, avoiding an unnecessary clone of client_email, and switching from HashMap to BTreeMap for deterministic field ordering.

[codecov]

Codecov Report

❌ Patch coverage is 91.46341% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.80%. Comparing base (a9f9f4d) to head (ec49624).

Files with missing lines	Patch %	Lines
src/storage/src/storage/post_policy.rs	91.46%	35 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5914      +/-   ##
==========================================
- Coverage   97.84%   97.80%   -0.05%     
==========================================
  Files         239      240       +1     
  Lines       60282    60692     +410     
==========================================
+ Hits        58985    59361     +376     
- Misses       1297     1331      +34     

☔ 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]

@joshuatants I've made 9 more commits since your review, to address your concerns and also further improved the code. These are the changes after your review:

• API Simplifications:
  • Removed with_scheme() and with_bucket_bound_hostname() methods from PostPolicyV4Builder.
  • Unified endpoint processing logic in a new resolve_endpoint() helper that standardizes the http/https prefix before resolving the host.
• Bucket Name Validation: Added check_bucket_name() to strictly enforce that the provided bucket name must begin with the "projects/_/buckets/" prefix.
• System Keys Protection: Extended the protected system_keys check to include "x-goog-signature" and "policy", guaranteeing that user-supplied malicious or conflicting fields are ignored in favor of the system-generated defaults.
• Documentation & Doc Tests: Added comprehensive Rustdoc examples (/// # Example) and doc tests covering how to use PostPolicyV4Builder and each of its builder configuration methods.
• Test Updates:
  • Updated existing tests to accommodate the "projects/_/buckets/" prefix requirement and the unified endpoint behavior.
  • Added a new post_policy_v4_custom_fields edge-case test to verify that custom system fields correctly drop/override conflicting user-supplied configurations while preserving standard custom fields (e.g., x-goog-meta-*).
• Example Script Updates: Modified the example generate_signed_post_policy_v4.rs to format the bucket string properly with "projects/_/buckets/" and included an extra "x-goog-meta-test" metadata field demo.

[dbolduc]

can you imagine this thing growing?

If so, tag the struct as #[non_exhaustive]

[xlai20]

Done. Tagged the struct as #[non_exhaustive]. Thanks for pointing this out.

We can't predict if there'll be product evolution in the future; for backward compatibility, tagging this public data structure to prevent user doing exhaustive pattern matching is a safer way.