feat(storage): Get/Set Object contexts

[xlai20]

b/434726762. Part 1.

This change defines the data structure of object context, and supports the
get and set of object contexts.

The data structure and naming of object context follows

• the JSON structure defined here;
• The ObjectContexts and ObjectCustomContextPayload proto defined in
  storage.proto here.

More operations on object contexts would be supported in follow-up PRs.

---

This change is 

[gemini-code-assist]

Summary of Changes

Hello @xlai20, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant new feature to the Google Cloud Storage C++ client library: the ability to manage 'Object contexts'. This allows for more detailed and structured custom metadata to be stored alongside objects. The changes encompass the definition of new C++ types to mirror the API's context structure, the integration of these contexts into the existing ObjectMetadata class, and the necessary updates to the serialization and deserialization mechanisms to ensure seamless interaction with the Google Cloud Storage API for context-related operations.

Highlights

• New Feature: Object Contexts: Introduced support for 'Object contexts' in the Google Cloud Storage client library, allowing users to associate custom, structured metadata with objects.
• Data Structures: Added new C++ data structures, ObjectCustomContextPayload and ObjectContexts, to represent the custom context data as defined by the Google Cloud Storage API.
• ObjectMetadata Integration: The ObjectMetadata class has been extended to include an optional ObjectContexts member, along with accessor, mutator, and reset methods (has_contexts, contexts, set_contexts, reset_contexts).
• Serialization and Deserialization: Implemented logic within object_metadata_parser.cc to correctly parse 'contexts' from JSON responses and serialize them back into JSON for API requests (e.g., for compose, update operations).
• Patch Builder Support: Added SetContexts and ResetContexts methods to ObjectMetadataPatchBuilder, enabling partial updates to object contexts.

Changelog

• google/cloud/storage/google_cloud_cpp_storage.bzl
  • Added object_contexts.h to google_cloud_cpp_storage_hdrs.
  • Added object_contexts.cc to google_cloud_cpp_storage_srcs.
• google/cloud/storage/google_cloud_cpp_storage.cmake
  • Included object_contexts.cc and object_contexts.h in the CMake library definition.
• google/cloud/storage/internal/object_metadata_parser.cc
  • Added ParseContexts function to extract object contexts from JSON.
  • Integrated ParseContexts into the ObjectMetadataParser::FromJson sequence.
  • Modified ObjectMetadataJsonForCompose to include object contexts in the JSON output.
  • Modified ObjectMetadataJsonForUpdate to include object contexts in the JSON output.
• google/cloud/storage/object_contexts.cc
  • New file defining stream insertion operators (operator<<) for ObjectCustomContextPayload and ObjectContexts.
• google/cloud/storage/object_contexts.h
  • New file defining ObjectCustomContextPayload struct for individual custom context entries.
  • New file defining ObjectContexts struct to hold a map of custom contexts, including helper methods for has_custom, get_custom, upsert_custom, and delete_custom.
  • Defined equality (operator==) and inequality (operator!=) operators for both new structs.
• google/cloud/storage/object_metadata.cc
  • Updated operator== to compare contexts_ member.
  • Updated operator<< to print contexts_ if present.
  • Added SetContexts and ResetContexts methods to ObjectMetadataPatchBuilder.
• google/cloud/storage/object_metadata.h
  • Included object_contexts.h.
  • Added has_contexts(), contexts(), set_contexts(), and reset_contexts() methods to ObjectMetadata.
  • Added absl::optional<ObjectContexts> contexts_; member to ObjectMetadata.
  • Declared SetContexts and ResetContexts methods in ObjectMetadataPatchBuilder.
• google/cloud/storage/object_metadata_test.cc
  • Modified CreateObjectMetadataForTest to include sample 'contexts' in the test JSON.
  • Added assertions to ObjectMetadataTest.Parse to verify correct parsing of object contexts.
  • Updated JsonForCompose, JsonForCopy, JsonForInsert, JsonForRewrite, and JsonForUpdate tests to expect 'contexts' in the generated JSON.
  • Added new test cases ObjectMetadataTest.SetContexts and ObjectMetadataTest.ResetContexts to verify functionality.
  • Added new test cases ObjectMetadataPatchBuilder.SetContexts and ObjectMetadataPatchBuilder.ResetContexts to verify patch builder functionality.

Activity

• The pull request was opened by xlai20.
• The PR introduces a new feature to add Get/Set/Upsert operations for object contexts.
• The implementation adheres to the JSON structure defined in Google Cloud Storage documentation and the ObjectContexts and ObjectCustomContextPayload proto definitions.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for Object contexts in Google Cloud Storage, including data structures, JSON parsing/serialization, and ObjectMetadata updates. A critical logic error was identified in the ObjectCustomContextPayload equality operator, which could lead to incorrect update_time comparisons and potential unexpected behavior in applications relying on metadata equality checks. Additionally, improvements are suggested for API documentation regarding undefined behavior, addressing code duplication, and refining output formatting in a stream operator.

[codecov]

Codecov Report

❌ Patch coverage is 99.25926% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.97%. Comparing base (14c94b4) to head (7b96752).

Files with missing lines	Patch %	Lines
google/cloud/storage/object_metadata_test.cc	98.14%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main   #15933    +/-   ##
========================================
  Coverage   92.96%   92.97%            
========================================
  Files        2460     2462     +2     
  Lines      228901   229036   +135     
========================================
+ Hits       212791   212938   +147     
+ Misses      16110    16098    -12     

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