feat(storage): implement Object Contexts with advanced filtering and validation

Storage/src/Bucket.php

@@ -274,6 +274,12 @@ public function exists(array $options = [])
      *     @type array $metadata The full list of available options are outlined
      *           at the [JSON API docs](https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request-body).
      *     @type array $metadata.metadata User-provided metadata, in key/value pairs.
+     *     @type array $contexts Object contexts. See at the
+     *           [API docs](https://docs.cloud.google.com/storage/docs/use-object-contexts) for more details.
+     *     @type string $contexts.custom.{key}.createTime The time the context
+     *           was created in RFC 3339 format. **(read only)**
+     *     @type string $contexts.custom.{key}.updateTime The time the context
+     *           was last updated in RFC 3339 format. **(read only)**
      *     @type string $encryptionKey A base64 encoded AES-256 customer-supplied
      *           encryption key. If you would prefer to manage encryption
      *           utilizing the Cloud Key Management Service (KMS) please use the
@@ -294,6 +300,15 @@ public function upload($data, array $options = [])
             throw new \InvalidArgumentException('A name is required when data is of type string or null.');
         }
 
+        if (isset($options['contexts'])) {
+            if (!is_array($options['contexts'])) {
+                throw new \InvalidArgumentException('Object contexts must be an array.');
+            }
+            if (isset($options['contexts']['custom']) && !is_array($options['contexts']['custom'])) {
+                throw new \InvalidArgumentException('Object contexts custom field must be an array.');
+            }
+        }
+
         $encryptionKey = $options['encryptionKey'] ?? null;
         $encryptionKeySHA256 = $options['encryptionKeySHA256'] ?? null;
 
@@ -703,6 +718,9 @@ public function restore($name, $generation, array $options = [])
      *           distinct results. **Defaults to** `false`.
      *     @type string $fields Selector which will cause the response to only
      *           return the specified fields.
+     *     @type string $filter Filter results to include only objects to which the
+     *           specified context is attached. You can filter by the presence,
+     *           absence, or specific value of context keys.
      *     @type string $matchGlob A glob pattern to filter results. The string
      *           value must be UTF-8 encoded. See:
      *           https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob
@@ -712,7 +730,6 @@ public function restore($name, $generation, array $options = [])
     public function objects(array $options = [])
     {
         $resultLimit = $this->pluck('resultLimit', $options, false);
-
         return new ObjectIterator(
             new ObjectPageIterator(
                 function (array $object) {

Storage/src/Connection/Rest.php

@@ -526,6 +526,12 @@ private function resolveUploadOptions(array $args)
             $args['metadata']['retention'] = $args['retention'];
             unset($args['retention']);
         }
+        if (isset($args['contexts'])) {
+            // during object creation context properties are part of the object resource
+            // and should be included in the request body.
+            $args['metadata']['contexts'] = $args['contexts'];
+            unset($args['contexts']);
+        }
         unset($args['name']);
         $args['contentType'] = $args['metadata']['contentType']
             ?? MimeType::fromFilename($args['metadata']['name']);

Storage/src/Connection/ServiceDefinition/storage-v1.json

@@ -1561,6 +1561,41 @@
                     "type": "string",
                     "description": "The modification time of the object metadata in RFC 3339 format. Set initially to object creation time and then updated whenever any metadata of the object changes. This includes changes made by a requester, such as modifying custom metadata, as well as changes made by Cloud Storage on behalf of a requester, such as changing the storage class based on an Object Lifecycle Configuration.",
                     "format": "date-time"
+                },
+                "contexts" : {
+                    "type": "object",
+                    "description": "User-defined or system-defined object contexts. Represented as key-payload pairs, where the key identifies the context and the payload contains the associated value and additional metadata.",
+                    "properties" : {
+                        "custom" : {
+                            "type": "object",
+                            "description": "User-provided object contexts where each entry consists of a unique key and a corresponding payload.",
+                            "additionalProperties": {
+                                "$ref": "ObjectCustomContextPayload",
+                                "description": "A single user-defined object context."
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "ObjectCustomContextPayload": {
+            "id": "ObjectCustomContextPayload",
+            "type": "object",
+            "description": "The payload associated with a user-defined context key.",
+            "properties": {
+                "value": {
+                    "type": "string",
+                    "description": "The value of the object contexts."
+                },
+                "createTime": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The time at which the object contexts was created in RFC 3339 format."
+                },
+                "updateTime": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The time at which the object context was last updated in RFC 3339 format."
                 }
             }
         },
@@ -4865,6 +4900,11 @@
                             "required": true,
                             "location": "path"
                         },
+                        "filter": {
+                            "type": "string",
+                            "description": "Filter results to include only objects to which the specified context is attached. You can filter by the presence, absence, or specific value of context keys.",
+                            "location": "query"
+                        },
                         "delimiter": {
                             "type": "string",
                             "description": "Returns results in a directory-like mode. items will contain only objects whose names, aside from the prefix, do not contain delimiter. Objects whose names, aside from the prefix, contain delimiter will have their name, truncated after the delimiter, returned in prefixes. Duplicate prefixes are omitted.",

Storage/src/StorageObject.php

@@ -231,6 +231,12 @@ public function delete(array $options = [])
      *           This is the retention configuration set for this object.
      *     @type string $retention.mode The mode of the retention configuration,
      *           which can be either `"Unlocked"` or `"Locked"`.
+     *     @type array $contexts Object contexts. See at the
+     *           [API docs](https://docs.cloud.google.com/storage/docs/use-object-contexts) for more details.
+     *     @type string $contexts.custom.{key}.createTime The time the context
+     *           was created in RFC 3339 format. **(read only)**
+     *     @type string $contexts.custom.{key}.updateTime The time the context
+     *           was last updated in RFC 3339 format. **(read only)**
      *     @type bool $overrideUnlockedRetention Applicable for objects that
      *           have an unlocked retention configuration. Required to be set to
      *           `true` if the operation includes a retention property that