feat(storage): Support GCS Object Compose - DRAFT

[xlai20]

DRAFT, DO NOT REVIEW YET

This PR introduces the GCS Object Compose feature into the developer-facing handwritten Storage client of the google-cloud-rust SDK.

Key Additions

1. Handwritten Veneer API: Exposes a fluent, premium request builder ComposeObject via Storage::compose_object(bucket, destination).
2. Rich Fluent Builder: Supports source names, optional expected generations, individual source preconditions, destination object metadata overrides (e.g., content type, custom metadata), destination preconditions, and custom retry policies.
3. Extended Mocking Support: Extends stub::Storage trait with compose_object so developers can mock composition in tests.
4. gRPC Transport Implementation: Integrates the gRPC call via self.inner.grpc.execute in transport.rs, with full routing rules, GCP headers, tracing, and observability.
5. Comprehensive Testing: Adds mock unit tests (tests/mocking.rs) and transport layer integration tests (transport.rs) covering success and failure cases.

[gemini-code-assist]

Code Review

This pull request implements the compose_object functionality for the Google Cloud Storage service, enabling the concatenation of multiple source objects into a single composite object. The changes include the addition of the ComposeObject request builder, updates to the Storage client and trait, and the implementation of gRPC transport logic with tracing support. Feedback recommends enhancing the ComposeObject builder by adding a fluent add_metadata method to allow for more ergonomic addition of individual metadata entries.

[gemini-code-assist]

While set_metadata allows replacing the entire metadata map, it is often more idiomatic in builder patterns to provide a fluent method for adding individual metadata entries. This improves usability when the user only needs to set a few custom attributes without constructing a full HashMap themselves.

    /// Adds a custom metadata attribute for the destination composite object.
    pub fn add_metadata<K, V>(mut self, key: K, value: V) -> Self
    where
        K: Into<String>,
        V: Into<String>,
    {
        if let Some(ref mut dest) = self.request.destination {
            dest.metadata.insert(key.into(), value.into());
        }
        self
    }

    /// Sets custom metadata attributes for the destination composite object.
    pub fn set_metadata(mut self, metadata: std::collections::HashMap<String, String>) -> Self {
        if let Some(ref mut dest) = self.request.destination {
            dest.metadata = metadata;
        }
        self
    }

References

1. In code samples and examples, prioritize demonstrating the methods that are most likely to be used by developers in typical scenarios, even if safer alternatives exist.

[codecov]

Codecov Report

❌ Patch coverage is 85.59322% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.83%. Comparing base (98f06d0) to head (d4a6714).

Files with missing lines	Patch %	Lines
src/storage/src/storage/transport.rs	90.27%	14 Missing ⚠️
src/storage/src/storage/compose_object.rs	83.54%	13 Missing ⚠️
src/storage/src/storage/stub.rs	0.00%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5717      +/-   ##
==========================================
- Coverage   97.89%   97.83%   -0.06%     
==========================================
  Files         226      227       +1     
  Lines       55471    55707     +236     
==========================================
+ Hits        54303    54503     +200     
- Misses       1168     1204      +36     

☔ View full report in Codecov by Sentry.
📢 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.

[coryan]

What is the motivation for this? This exists in StorageControl:

https://docs.rs/google-cloud-storage/1.12.0/google_cloud_storage/client/struct.StorageControl.html#method.compose_object

Why are you creating more work for yourself?