samples: add samples for object retention

README.md

@@ -115,6 +115,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-storage/tre
 | Copy File | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/copyFile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/copyFile.js,samples/README.md) |
 | Copy Old Version Of File. | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/copyOldVersionOfFile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/copyOldVersionOfFile.js,samples/README.md) |
 | Create a Dual-Region Bucket | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createBucketWithDualRegion.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createBucketWithDualRegion.js,samples/README.md) |
+| Create a Bucket with object retention enabled. | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createBucketWithObjectRetention.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createBucketWithObjectRetention.js,samples/README.md) |
 | Create Bucket With Storage Class and Location. | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createBucketWithStorageClassAndLocation.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createBucketWithStorageClassAndLocation.js,samples/README.md) |
 | Create Bucket With Turbo Replication | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createBucketWithTurboReplication.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createBucketWithTurboReplication.js,samples/README.md) |
 | Create New Bucket | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createNewBucket.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createNewBucket.js,samples/README.md) |
@@ -197,6 +198,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-storage/tre
 | Set Autoclass | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setAutoclass.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setAutoclass.js,samples/README.md) |
 | Set Client Endpoint | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setClientEndpoint.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setClientEndpoint.js,samples/README.md) |
 | Set Event Based Hold | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setEventBasedHold.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setEventBasedHold.js,samples/README.md) |
+| Set the object retention policy of a File. | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setObjectRetentionPolicy.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setObjectRetentionPolicy.js,samples/README.md) |
 | Set Public Access Prevention Enforced | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setPublicAccessPreventionEnforced.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setPublicAccessPreventionEnforced.js,samples/README.md) |
 | Set Public Access Prevention Inherited | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setPublicAccessPreventionInherited.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setPublicAccessPreventionInherited.js,samples/README.md) |
 | Set RPO Async Turbo | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setRPOAsyncTurbo.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setRPOAsyncTurbo.js,samples/README.md) |

samples/README.md

@@ -34,6 +34,7 @@ objects to users via direct download.
   * [Copy File](#copy-file)
   * [Copy Old Version Of File.](#copy-old-version-of-file.)
   * [Create a Dual-Region Bucket](#create-a-dual-region-bucket)
+  * [Create a Bucket with object retention enabled.](#create-a-bucket-with-object-retention-enabled.)
   * [Create Bucket With Storage Class and Location.](#create-bucket-with-storage-class-and-location.)
   * [Create Bucket With Turbo Replication](#create-bucket-with-turbo-replication)
   * [Create New Bucket](#create-new-bucket)
@@ -116,6 +117,7 @@ objects to users via direct download.
   * [Set Autoclass](#set-autoclass)
   * [Set Client Endpoint](#set-client-endpoint)
   * [Set Event Based Hold](#set-event-based-hold)
+  * [Set the object retention policy of a File.](#set-the-object-retention-policy-of-a-file.)
   * [Set Public Access Prevention Enforced](#set-public-access-prevention-enforced)
   * [Set Public Access Prevention Inherited](#set-public-access-prevention-inherited)
   * [Set RPO Async Turbo](#set-rpo-async-turbo)
@@ -441,6 +443,25 @@ __Usage:__
 
 
 
+### Create a Bucket with object retention enabled.
+
+Create a Bucket with object retention enabled.
+
+View the [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/createBucketWithObjectRetention.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/createBucketWithObjectRetention.js,samples/README.md)
+
+__Usage:__
+
+
+`node createBucketWithObjectRetention.js <BUCKET_NAME>`
+
+
+-----
+
+
+
+
 ### Create Bucket With Storage Class and Location.
 
 Create Bucket With Storage Class and Location.
@@ -1879,6 +1900,25 @@ __Usage:__
 
 
 
+### Set the object retention policy of a File.
+
+Set the object retention policy of a File.
+
+View the [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setObjectRetentionPolicy.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/setObjectRetentionPolicy.js,samples/README.md)
+
+__Usage:__
+
+
+`node setObjectRetentionPolicy.js <BUCKET_NAME>`
+
+
+-----
+
+
+
+
 ### Set Public Access Prevention Enforced
 
 View the [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/setPublicAccessPreventionEnforced.js).

samples/createBucketWithObjectRetention.js

@@ -0,0 +1,56 @@
+/**
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// sample-metadata:
+//   title: Create a Bucket with object retention enabled.
+//   description: Create a Bucket with object retention enabled.
+//   usage: node createBucketWithObjectRetention.js <BUCKET_NAME>
+
+function main(bucketName = 'my-bucket') {
+  // [START storage_create_bucket_with_object_retention]
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // The ID of your GCS bucket
+  // const bucketName = 'your-unique-bucket-name';
+
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  // The bucket in the sample below will be created in the project associated with this client.
+  // For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
+  const storage = new Storage();
+
+  async function createBucketWithObjectRetention() {
+    const [bucket] = await storage.createBucket(bucketName, {
+      enableObjectRetention: true,
+    });
+
+    console.log(
+      `Created '${bucket.name}' with object retention enabled setting: ${bucket.metadata.objectRetention.mode}`
+    );
+  }
+
+  createBucketWithObjectRetention().catch(console.error);
+  // [END storage_create_bucket_with_object_retention]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));

samples/setObjectRetentionPolicy.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// sample-metadata:
+//   title: Set the object retention policy of a File.
+//   description: Set the object retention policy of a File.
+//   usage: node setObjectRetentionPolicy.js <BUCKET_NAME>
+
+function main(
+  bucketName = 'my-bucket',
+  destFileName = 'file.txt',
+  contents = 'this is the file content'
+) {
+  // [START storage_set_object_retention_policy]
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // The ID of your GCS bucket
+  // const bucketName = 'your-unique-bucket-name';
+
+  // The new ID for your GCS file
+  // const destFileName = 'your-new-file-name';
+
+  // The content to be uploaded in the GCS file
+  // const contents = 'your file content';
+
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  // The bucket in the sample below will be created in the project associated with this client.
+  // For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
+  const storage = new Storage();
+
+  async function setObjectRetentionPolicy() {
+    // Get a reference to the bucket
+    const myBucket = storage.bucket(bucketName);
+
+    // Create a reference to a file object
+    const file = myBucket.file(destFileName);
+
+    // Save the file data
+    await file.save(contents);
+
+    // Set the retention policy for the file
+    const retentionDate = new Date();
+    retentionDate.setDate(retentionDate.getDate() + 10);
+    const [metadata] = await file.setMetadata({
+      retention: {
+        mode: 'Unlocked',
+        retainUntilTime: retentionDate.toISOString(),
+      },
+    });
+
+    console.log(
+      `Retention policy for file ${file.name} was set to: ${metadata.retention.mode}`
+    );
+
+    // To modify an existing policy on an unlocked file object, pass in the override parameter
+    const newRetentionDate = new Date();
+    retentionDate.setDate(retentionDate.getDate() + 9);
+    [metdata] = await file.setMetadata({
+      retention: {retainUntilTime: newRetentionDate},
+      overrideUnlockedRetention: true,
+    });
+
+    console.log(
+      `Retention policy for file ${file.name} was updated to: ${metadata.retention.retainUntilTime}`
+    );
+  }
+
+  setObjectRetentionPolicy().catch(console.error);
+  // [END storage_set_object_retention_policy]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));

samples/system-test/buckets.test.js

@@ -29,13 +29,15 @@ const bucketNameDualRegion = `${samplesTestBucketPrefix}-b`;
 const bucketNameDualRegionTurbo = `${samplesTestBucketPrefix}-c`;
 const bucketNameWithClassAndLocation = `${samplesTestBucketPrefix}-d`;
 const bucketNameAutoclass = `${samplesTestBucketPrefix}-e`;
+const bucketNameObjectRetention = `${samplesTestBucketPrefix}-f`;
 const defaultKmsKeyName = process.env.GOOGLE_CLOUD_KMS_KEY_ASIA;
 const bucket = storage.bucket(bucketName);
 const bucketWithClassAndLocation = storage.bucket(
   bucketNameWithClassAndLocation
 );
 const dualRegionBucket = storage.bucket(bucketNameDualRegion);
 const dualRegionBucketTurbo = storage.bucket(bucketNameDualRegionTurbo);
+const objectRetentionBucket = storage.bucket(bucketNameObjectRetention);
 
 const PUBLIC_ACCESS_PREVENTION_INHERITED = 'inherited';
 const PUBLIC_ACCESS_PREVENTION_ENFORCED = 'enforced';
@@ -417,3 +419,16 @@ it('should delete a bucket', async () => {
   const [exists] = await bucket.exists();
   assert.strictEqual(exists, false);
 });
+
+it('should create a bucket with object retention enabled', async () => {
+  const output = execSync(
+    `node createBucketWithObjectRetention.js ${bucketNameObjectRetention}`
+  );
+  console.log(output);
+  assert.include(
+    output,
+    `Created '${bucketNameObjectRetention}' with object retention enabled setting: Enabled`
+  );
+  const [metadata] = await objectRetentionBucket.getMetadata();
+  assert.strictEqual(metadata.objectRetention.mode, 'Enabled');
+});

samples/system-test/files.test.js

@@ -30,6 +30,8 @@ const storage = new Storage();
 const cwd = path.join(__dirname, '..');
 const bucketName = generateName();
 const bucket = storage.bucket(bucketName);
+const objectRetentionBucketName = generateName();
+const objectRetentionBucket = storage.bucket(objectRetentionBucketName);
 const fileContents = 'these-are-my-contents';
 const fileName = 'test.txt';
 const memoryFileName = 'testmemory.txt';
@@ -576,6 +578,25 @@ describe('file', () => {
       assert.strictEqual(exists, false);
     });
   });
+
+  describe('Object Retention', () => {
+    before(async () => {
+      await storage.createBucket(objectRetentionBucketName, {
+        enableObjectRetention: true,
+      });
+    });
+
+    it('should create a file with unlocked retention and then override it', async () => {
+      const output = execSync(
+        `node setObjectRetentionPolicy.js ${objectRetentionBucketName} ${fileName} ${fileContent}`
+      );
+      assert.include(output, 'Retention policy for file');
+      const file = objectRetentionBucket.file(fileName);
+      const [metadata] = await file.getMetadata();
+      assert(metadata.retention.retainUntilTime);
+      assert(metadata.retention.mode.toUpperCase(), 'UNLOCKED');
+    });
+  });
 });
 
 function generateName() {