samples: add preconditions to storage.objects.rewrite, storage.objects.insert, storage.objects.patch, & storage.objects.delete samples

samples/changeFileCSEKToCMEK.js

@@ -23,7 +23,8 @@ function main(
   bucketName = 'my-bucket',
   fileName = 'test.txt',
   encryptionKey = 'my-encription-key',
-  kmsKeyName = 'my-kms-key'
+  kmsKeyName = 'my-kms-key',
+  generationMatchPrecondition = 0
 ) {
   // [START storage_object_csek_to_cmek]
   /**
@@ -49,13 +50,25 @@ function main(
   const storage = new Storage();
 
   async function changeFileCSEKToCMEK() {
+    const rotateEncryptionKeyOptions = {
+      kmsKeyName,
+      // Optional: set a generation-match precondition to avoid potential race
+      // conditions and data corruptions. The request to upload is aborted if the
+      // object's generation number does not match your precondition.
+      preconditionOpts: {
+        ifGenerationMatch: generationMatchPrecondition,
+      },
+    };
+
+    console.log(rotateEncryptionKeyOptions);
+
     await storage
       .bucket(bucketName)
       .file(fileName, {
         encryptionKey: Buffer.from(encryptionKey, 'base64'),
       })
       .rotateEncryptionKey({
-        kmsKeyName,
+        rotateEncryptionKeyOptions,
       });
 
     console.log(

samples/composeFile.js

@@ -23,7 +23,8 @@ function main(
   bucketName = 'my-bucket',
   firstFileName = 'file-one.txt',
   secondFileName = 'file-two.txt',
-  destinationFileName = 'file-one-two.txt'
+  destinationFileName = 'file-one-two.txt',
+  destinationGenerationMatchPrecondition = 0
 ) {
   // [START storage_compose_file]
   /**
@@ -51,7 +52,17 @@ function main(
     const bucket = storage.bucket(bucketName);
     const sources = [firstFileName, secondFileName];
 
-    await bucket.combine(sources, destinationFileName);
+    // Optional:
+    // Set a generation-match precondition to avoid potential race conditions
+    // and data corruptions. The request to upload is aborted if the object's
+    // generation number does not match your precondition. For a destination
+    // object that does not yet exist, set the ifGenerationMatch precondition to 0
+    // If the destination object already exists in your bucket, set instead a
+    // generation-match precondition using its generation number.
+    const combineOptions = {
+      ifGenerationMatch: destinationGenerationMatchPrecondition,
+    };
+    await bucket.combine(sources, destinationFileName, combineOptions);
 
     console.log(
       `New composite file ${destinationFileName} was created by combining ${firstFileName} and ${secondFileName}`

samples/copyFile.js

@@ -24,7 +24,8 @@ function main(
   srcBucketName = 'my-bucket',
   srcFilename = 'test2.txt',
   destBucketName = 'my-bucket',
-  destFileName = 'test3.txt'
+  destFileName = 'test3.txt',
+  destinationGenerationMatchPrecondition = 0
 ) {
   // [START storage_copy_file]
   /**
@@ -49,11 +50,26 @@ function main(
   const storage = new Storage();
 
   async function copyFile() {
+    const copyDestination = storage.bucket(destBucketName).file(destFileName);
+
+    // Optional:
+    // Set a generation-match precondition to avoid potential race conditions
+    // and data corruptions. The request to upload is aborted if the object's
+    // generation number does not match your precondition. For a destination
+    // object that does not yet exist, set the ifGenerationMatch precondition to 0
+    // If the destination object already exists in your bucket, set instead a
+    // generation-match precondition using its generation number.
+    const copyOptions = {
+      preconditionOpts: {
+        ifGenerationMatch: destinationGenerationMatchPrecondition,
+      },
+    };
+
     // Copies the file to the other bucket
     await storage
       .bucket(srcBucketName)
       .file(srcFilename)
-      .copy(storage.bucket(destBucketName).file(destFileName));
+      .copy(copyDestination, copyOptions);
 
     console.log(
       `gs://${srcBucketName}/${srcFilename} copied to gs://${destBucketName}/${destFileName}`

samples/copyOldVersionOfFile.js

@@ -24,7 +24,8 @@ function main(
   srcFilename = 'test2.txt',
   destBucketName = 'my-bucket',
   destFileName = 'test3.txt',
-  generation = 1
+  generation = 1,
+  destinationGenerationMatchPrecondition = 0
 ) {
   // [START storage_copy_file_archived_generation]
   /**
@@ -53,12 +54,26 @@ function main(
 
   async function copyOldVersionOfFile() {
     // Copies the file to the other bucket
+
+    // Optional:
+    // Set a generation-match precondition to avoid potential race conditions
+    // and data corruptions. The request to upload is aborted if the object's
+    // generation number does not match your precondition. For a destination
+    // object that does not yet exist, set the ifGenerationMatch precondition to 0
+    // If the destination object already exists in your bucket, set instead a
+    // generation-match precondition using its generation number.
+    const copyOptions = {
+      preconditionOpts: {
+        ifGenerationMatch: destinationGenerationMatchPrecondition,
+      },
+    };
+
     await storage
       .bucket(srcBucketName)
       .file(srcFilename, {
         generation,
       })
-      .copy(storage.bucket(destBucketName).file(destFileName));
+      .copy(storage.bucket(destBucketName).file(destFileName), copyOptions);
 
     console.log(
       `Generation ${generation} of file ${srcFilename} in bucket ${srcBucketName} was copied to ${destFileName} in bucket ${destBucketName}`

samples/deleteFile.js

@@ -20,7 +20,11 @@
  * at https://cloud.google.com/storage/docs.
  */
 
-function main(bucketName = 'my-bucket', fileName = 'test.txt') {
+function main(
+  bucketName = 'my-bucket',
+  fileName = 'test.txt',
+  generationMatchPrecondition = 0
+) {
   // [START storage_delete_file]
   /**
    * TODO(developer): Uncomment the following lines before running the sample.
@@ -37,8 +41,18 @@ function main(bucketName = 'my-bucket', fileName = 'test.txt') {
   // Creates a client
   const storage = new Storage();
 
+  // Optional:
+  // Set a generation-match precondition to avoid potential race conditions
+  // and data corruptions. The request to upload is aborted if the object's
+  // generation number does not match your precondition. For a destination
+  // object that does not yet exist, set the ifGenerationMatch precondition to 0
+  // If the destination object already exists in your bucket, set instead a
+  // generation-match precondition using its generation number.
+  const deleteOptions = {
+    ifGenerationMatch: generationMatchPrecondition,
+  };
   async function deleteFile() {
-    await storage.bucket(bucketName).file(fileName).delete();
+    await storage.bucket(bucketName).file(fileName).delete(deleteOptions);
 
     console.log(`gs://${bucketName}/${fileName} deleted`);
   }

samples/fileChangeStorageClass.js

@@ -22,7 +22,8 @@
 function main(
   bucketName = 'my-bucket',
   fileName = 'file.txt',
-  storageClass = 'standard'
+  storageClass = 'standard',
+  generationMatchPrecondition = 0
 ) {
   // [START storage_change_file_storage_class]
   // Imports the Google Cloud client library
@@ -46,10 +47,21 @@ function main(
   // const storageClass = 'coldline';
 
   async function fileChangeStorageClass() {
+    // Optional:
+    // Set a generation-match precondition to avoid potential race conditions
+    // and data corruptions. The request to upload is aborted if the object's
+    // generation number does not match your precondition. For a destination
+    // object that does not yet exist, set the ifGenerationMatch precondition to 0
+    // If the destination object already exists in your bucket, set instead a
+    // generation-match precondition using its generation number.
+    const setStorageClassOptions = {
+      ifGenerationMatch: generationMatchPrecondition,
+    };
+
     await storage
       .bucket(bucketName)
       .file(fileName)
-      .setStorageClass(storageClass);
+      .setStorageClass(storageClass, setStorageClassOptions);
 
     console.log(`${fileName} has been set to ${storageClass}`);
   }

samples/fileSetMetadata.js

@@ -19,7 +19,11 @@
 //   description: Set file metadata.
 //   usage: node fileSetMetadata.js <BUCKET_NAME> <FILE_NAME>
 
-function main(bucketName = 'my-bucket', fileName = 'file.txt') {
+function main(
+  bucketName = 'my-bucket',
+  fileName = 'file.txt',
+  generationMatchPrecondition = 0
+) {
   // [START storage_set_metadata]
   // Imports the Google Cloud client library
   const {Storage} = require('@google-cloud/storage');
@@ -37,23 +41,34 @@ function main(bucketName = 'my-bucket', fileName = 'file.txt') {
   // const fileName = 'your-file-name';
 
   async function setFileMetadata() {
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload is aborted if the
+    // object's generation number does not match your precondition.
+    const options = {
+      ifGenerationMatch: generationMatchPrecondition,
+    };
+
     // Set file metadata.
     const [metadata] = await storage
       .bucket(bucketName)
       .file(fileName)
-      .setMetadata({
-        // Predefined metadata for server e.g. 'cacheControl', 'contentDisposition',
-        // 'contentEncoding', 'contentLanguage', 'contentType'
-        contentDisposition: 'attachment; filename*=utf-8\'\'"anotherImage.jpg"',
-        contentType: 'image/jpeg',
+      .setMetadata(
+        {
+          // Predefined metadata for server e.g. 'cacheControl', 'contentDisposition',
+          // 'contentEncoding', 'contentLanguage', 'contentType'
+          contentDisposition:
+            'attachment; filename*=utf-8\'\'"anotherImage.jpg"',
+          contentType: 'image/jpeg',
 
-        // A note or actionable items for user e.g. uniqueId, object description,
-        // or other useful information.
-        metadata: {
-          description: 'file description...',
-          modified: '1900-01-01',
+          // A note or actionable items for user e.g. uniqueId, object description,
+          // or other useful information.
+          metadata: {
+            description: 'file description...',
+            modified: '1900-01-01',
+          },
         },
-      });
+        options
+      );
 
     console.log(
       'Updated metadata for object',

samples/moveFile.js

@@ -23,7 +23,8 @@
 function main(
   bucketName = 'my-bucket',
   srcFileName = 'test.txt',
-  destFileName = 'test2.txt'
+  destFileName = 'test2.txt',
+  destinationGenerationMatchPrecondition = 0
 ) {
   // [START storage_move_file]
   /**
@@ -45,8 +46,24 @@ function main(
   const storage = new Storage();
 
   async function moveFile() {
+    // Optional:
+    // Set a generation-match precondition to avoid potential race conditions
+    // and data corruptions. The request to upload is aborted if the object's
+    // generation number does not match your precondition. For a destination
+    // object that does not yet exist, set the ifGenerationMatch precondition to 0
+    // If the destination object already exists in your bucket, set instead a
+    // generation-match precondition using its generation number.
+    const moveOptions = {
+      preconditionOpts: {
+        ifGenerationMatch: destinationGenerationMatchPrecondition,
+      },
+    };
+
     // Moves the file within the bucket
-    await storage.bucket(bucketName).file(srcFileName).move(destFileName);
+    await storage
+      .bucket(bucketName)
+      .file(srcFileName)
+      .move(destFileName, moveOptions);
 
     console.log(
       `gs://${bucketName}/${srcFileName} moved to gs://${bucketName}/${destFileName}`

samples/releaseEventBasedHold.js

@@ -20,7 +20,11 @@
  * at https://cloud.google.com/storage/docs/bucket-lock
  */
 
-function main(bucketName = 'my-bucket', fileName = 'test.txt') {
+function main(
+  bucketName = 'my-bucket',
+  fileName = 'test.txt',
+  generationMatchPrecondition = 0
+) {
   // [START storage_release_event_based_hold]
   /**
    * TODO(developer): Uncomment the following lines before running the sample.
@@ -38,9 +42,19 @@ function main(bucketName = 'my-bucket', fileName = 'test.txt') {
   const storage = new Storage();
 
   async function releaseEventBasedHold() {
-    await storage.bucket(bucketName).file(fileName).setMetadata({
-      eventBasedHold: false,
-    });
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload is aborted if the
+    // object's generation number does not match your precondition.
+    const options = {
+      ifGenerationMatch: generationMatchPrecondition,
+    };
+
+    await storage.bucket(bucketName).file(fileName).setMetadata(
+      {
+        eventBasedHold: false,
+      },
+      options
+    );
     console.log(`Event-based hold was released for ${fileName}.`);
   }
 

samples/releaseTemporaryHold.js

@@ -20,7 +20,11 @@
  * at https://cloud.google.com/storage/docs/bucket-lock
  */
 
-function main(bucketName = 'my-bucket', fileName = 'test.txt') {
+function main(
+  bucketName = 'my-bucket',
+  fileName = 'test.txt',
+  generationMatchPrecondition = 0
+) {
   // [START storage_release_temporary_hold]
   /**
    * TODO(developer): Uncomment the following lines before running the sample.
@@ -38,9 +42,19 @@ function main(bucketName = 'my-bucket', fileName = 'test.txt') {
   const storage = new Storage();
 
   async function releaseTemporaryHold() {
-    await storage.bucket(bucketName).file(fileName).setMetadata({
-      temporaryHold: false,
-    });
+    // Optional: set a generation-match precondition to avoid potential race
+    // conditions and data corruptions. The request to upload is aborted if the
+    // object's generation number does not match your precondition.
+    const options = {
+      ifGenerationMatch: generationMatchPrecondition,
+    };
+
+    await storage.bucket(bucketName).file(fileName).setMetadata(
+      {
+        temporaryHold: false,
+      },
+      options
+    );
     console.log(`Temporary hold was released for ${fileName}.`);
   }