feat(Storage): support object retention lock

Storage/src/Bucket.php

@@ -267,6 +267,18 @@ public function exists(array $options = [])
      *           Acceptable values include, `"authenticatedRead"`,
      *           `"bucketOwnerFullControl"`, `"bucketOwnerRead"`, `"private"`,
      *           `"projectPrivate"`, and `"publicRead"`.
+     *     @type array $retention Object retention configuration.
+     *     @type string $retention.retainUntilTime The earliest time in RFC3339
+     *           UTC "Zulu" format that the object can be deleted or replaced.
+     *           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 string $retentionExpirationTime The earliest time in
+     *           RFC3339 UTC "Zulu" format that the object can be deleted or
+     *           replaced. This depends on any retention configuration set for
+     *           the object and any retention policy set for the bucket that
+     *           contains the object. This value should normally only be set by
+     *           the back-end API.
      *     @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.

Storage/src/Connection/Rest.php

@@ -431,7 +431,11 @@ private function resolveUploadOptions(array $args)
         }
 
         $args['metadata']['name'] = $args['name'];
+        if (isset($args['retention'])) {
+            $args['metadata']['retention'] = $args['retention'];
+        }
         unset($args['name']);
+        unset($args['retention']);
         $args['contentType'] = $args['metadata']['contentType']
             ?? MimeType::fromFilename($args['metadata']['name']);
 

Storage/src/StorageClient.php

@@ -271,6 +271,10 @@ function (array $bucket) use ($userProject) {
      *           `"projectPrivate"`, and `"publicRead"`.
      *     @type string $predefinedDefaultObjectAcl Apply a predefined set of
      *           default object access controls to this bucket.
+     *     @type bool $enableObjectRetention Whether object retention should
+     *          be enabled on this bucket. For more information, refer to the
+     *          [Object Retention Lock](https://cloud.google.com/storage/docs/object-lock)
+     *          documentation.
      *     @type string $projection Determines which properties to return. May
      *           be either `"full"` or `"noAcl"`. **Defaults to** `"noAcl"`,
      *           unless the bucket resource specifies acl or defaultObjectAcl

Storage/src/StorageObject.php

@@ -224,6 +224,23 @@ public function delete(array $options = [])
      *           Acceptable values include, `"authenticatedRead"`,
      *           `"bucketOwnerFullControl"`, `"bucketOwnerRead"`, `"private"`,
      *           `"projectPrivate"`, and `"publicRead"`.
+     *     @type array $retention Object retention configuration.
+     *     @type string $retention.retainUntilTime The earliest time in RFC3339
+     *           UTC "Zulu" format that the object can be deleted or replaced.
+     *           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 string $retentionExpirationTime The earliest time in
+     *           RFC3339 UTC "Zulu" format that the object can be deleted or
+     *           replaced. This depends on any retention configuration set for
+     *           the object and any retention policy set for the bucket that
+     *           contains the object. This value should normally only be set by
+     *           the back-end API.
+     *     @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
+     *           changes the mode to `Locked`, reduces the `retainUntilTime`, or
+     *           removes the retention configuration from the object.
      *     @type string $projection Determines which properties to return. May
      *           be either 'full' or 'noAcl'.
      *     @type string $fields Selector which will cause the response to only

Storage/tests/System/ManageObjectsTest.php

@@ -84,6 +84,36 @@ public function testListsObjectsWithMatchGlob()
         }
     }
 
+    public function testObjectRetentionLock()
+    {
+        // Test bucket created with object retention enabled
+        $bucket = self::createBucket(self::$client, uniqid('object_retention-'), [
+            'enableObjectRetention' => true
+        ]);
+        $this->assertEquals($bucket->info()['objectRetention']['mode'], 'Enabled');
+
+        // Test create object with object retention enabled
+        $objectName = "object-retention-lock";
+        $expires = (new \DateTime)->add(
+            \DateInterval::createFromDateString('+2 hours')
+        );
+        $object = $bucket->upload(self::DATA, [
+            'name' => $objectName,
+            'retention' => [
+                'mode' => 'Unlocked',
+                'retainUntilTime' => $expires->format(\DateTime::RFC3339)
+            ]
+        ]);
+        $this->assertEquals($object->info()['retention']['mode'], 'Unlocked');
+
+        // Test patch object to disable object retention
+        $object->update([
+            'retention' => [],
+            'overrideUnlockedRetention' => true
+        ]);
+        $this->assertNotContains('retention', $object->info());
+    }
+
     public function testObjectExists()
     {
         $object = self::$bucket->upload(self::DATA, ['name' => uniqid(self::TESTING_PREFIX)]);