feat: Add feature for copying backups

src/backup.ts

@@ -37,6 +37,15 @@ import {
 } from './cluster';
 import {CallOptions, LROperation, Operation, ServiceError} from 'google-gax';
 import {Instance} from './instance';
+import {ClusterUtils} from './utils/cluster';
+
+export type CopyBackupResponse = GenericBackupPromise<Operation>;
+export type CopyBackupCallback = GenericBackupCallback<Operation>;
+export interface CopyBackupConfig extends ModifiableBackupFields {
+  cluster: Cluster;
+  gaxOptions?: CallOptions;
+  id: string;
+}
 
 type IEmpty = google.protobuf.IEmpty;
 export type IBackup = google.bigtable.admin.v2.IBackup;
@@ -59,6 +68,7 @@ export interface GenericBackupCallback<T> {
     apiResponse?: T | null
   ): void;
 }
+export type GenericBackupPromise<T> = [Backup, T];
 
 export type DeleteBackupCallback = (
   err: ServiceError | null,
@@ -243,6 +253,50 @@ Please use the format 'my-backup' or '${cluster.name}/backups/my-backup'.`);
     });
   }
 
+  /**
+   * When this backup object represents a backup that has already been created,
+   * copy will copy this created backup to the location and with the settings
+   * specified by the config parameter. After running this function the original
+   * backup will exist as well as a second backup matching the parameters given
+   * by the config argument.
+   *
+   * @param {CopyBackupConfig} [config] The config that specifies all of the
+   * information about the destination backup which is the new backup that gets
+   * created as a result of calling copy.
+   * @param {CopyBackupCallback} [callback] The callback function that passes an
+   * error or results back to the user.
+   */
+  copy(config: CopyBackupConfig, callback: CopyBackupCallback): void;
+  copy(config: CopyBackupConfig): Promise<CopyBackupResponse>;
+  copy(
+    config: CopyBackupConfig,
+    callback?: CopyBackupCallback
+  ): void | Promise<CopyBackupResponse> {
+    const reqOpts = {
+      parent: config.cluster.name,
+      backupId: config.id,
+      sourceBackup: `${this.cluster.name}/backups/${this.id}`,
+      expireTime: config?.expireTime,
+    };
+    ClusterUtils.formatBackupExpiryTime(reqOpts);
+    this.bigtable.request(
+      {
+        client: 'BigtableTableAdminClient',
+        method: 'copyBackup',
+        reqOpts,
+        gaxOpts: config.gaxOptions,
+      },
+      (err, ...args) => {
+        if (err) {
+          callback!(err, undefined, ...args);
+          return;
+        }
+        // Second argument is a backup for the new backup id
+        callback!(null, config.cluster.backup(config.id), ...args);
+      }
+    );
+  }
+
   create(config: CreateBackupConfig, callback?: CreateBackupCallback): void;
   create(config: CreateBackupConfig): Promise<CreateBackupResponse>;
   /**

src/cluster.ts

@@ -314,11 +314,7 @@ Please use the format 'my-cluster' or '${instance.name}/clusters/my-cluster'.`);
       },
     };
 
-    if (reqOpts.backup.expireTime instanceof Date) {
-      reqOpts.backup.expireTime = new PreciseDate(
-        reqOpts.backup.expireTime
-      ).toStruct();
-    }
+    ClusterUtils.formatBackupExpiryTime(reqOpts.backup);
 
     delete reqOpts.backup.table;
     delete reqOpts.backup.gaxOptions;

src/utils/cluster.ts

@@ -20,6 +20,8 @@ import {
   SetClusterMetadataOptions,
 } from '../cluster';
 import {google} from '../../protos/protos';
+import {ModifiableBackupFields} from '../backup';
+import {PreciseDate} from '@google-cloud/precise-date';
 
 export class ClusterUtils {
   static noConfigError =
@@ -163,4 +165,10 @@ export class ClusterUtils {
       updateMask: {paths: this.getUpdateMask(metadata)},
     };
   }
+
+  static formatBackupExpiryTime(backup: ModifiableBackupFields) {
+    if (backup.expireTime instanceof Date) {
+      backup.expireTime = new PreciseDate(backup.expireTime).toStruct();
+    }
+  }
 }

system-test/bigtable.ts

@@ -18,8 +18,15 @@ import * as assert from 'assert';
 import {beforeEach, afterEach, describe, it, before, after} from 'mocha';
 import Q from 'p-queue';
 
-import {Backup, Bigtable, Instance} from '../src';
+import {
+  Backup,
+  BackupTimestamp,
+  Bigtable,
+  Instance,
+  InstanceOptions,
+} from '../src';
 import {AppProfile} from '../src/app-profile.js';
+import {CopyBackupConfig} from '../src/backup.js';
 import {Cluster} from '../src/cluster.js';
 import {Family} from '../src/family.js';
 import {Row} from '../src/row.js';
@@ -1414,6 +1421,269 @@ describe('Bigtable', () => {
 
       Object.keys(policy).forEach(key => assert(key in updatedPolicy));
     });
+    describe('copying backups', () => {
+      const sourceExpireTimeMilliseconds =
+        PreciseDate.now() + (8 + 300) * 60 * 60 * 1000;
+      const sourceExpireTime = new PreciseDate(sourceExpireTimeMilliseconds);
+      const copyExpireTimeMilliseconds =
+        PreciseDate.now() + (8 + 600) * 60 * 60 * 1000;
+      const copyExpireTime = new PreciseDate(copyExpireTimeMilliseconds);
+
+      /*
+        This function checks that when a backup is copied using the provided
+        config that a new backup is created on the instance.
+       */
+      async function testCopyBackup(
+        backup: Backup,
+        config: CopyBackupConfig,
+        instance: Instance
+      ) {
+        // Get a list of backup ids before the copy
+        const [backupsBeforeCopy] = await instance.getBackups();
+        const backupIdsBeforeCopy = backupsBeforeCopy.map(backup => backup.id);
+        // Copy the backup
+        const [newBackup, operation] = await backup.copy(config);
+        assert.strictEqual(config.id, newBackup.id);
+        await operation.promise();
+        const id = config.id;
+        const backupPath = `${config.cluster.name}/backups/${id}`;
+        {
+          // Ensure that the backup specified by the config and id match the backup name for the operation returned by the server.
+          // the split/map/join functions replace the project name with the {{projectId}} string
+          assert(operation);
+          assert(operation.metadata);
+          assert.strictEqual(
+            operation.metadata.name
+              .split('/')
+              .map((item, index) => (index === 1 ? '{{projectId}}' : item))
+              .join('/'),
+            backupPath
+              .split('/')
+              .map((item, index) => (index === 1 ? '{{projectId}}' : item))
+              .join('/')
+          );
+        }
+        // Check that there is now one more backup
+        const [backupsAfterCopy] = await instance.getBackups();
+        const newBackups = backupsAfterCopy.filter(
+          backup => !backupIdsBeforeCopy.includes(backup.id)
+        );
+        assert.strictEqual(newBackups.length, 1);
+        const [fetchedNewBackup] = newBackups;
+        // Ensure the fetched backup matches the config
+        assert.strictEqual(fetchedNewBackup.id, id);
+        assert.strictEqual(fetchedNewBackup.name, backupPath);
+        // Delete the copied backup
+        await config.cluster.backup(fetchedNewBackup.id).delete();
+      }
+
+      describe('should create backup of a table and copy it in the same cluster', async () => {
+        async function testWithExpiryTimes(
+          sourceTestExpireTime: BackupTimestamp,
+          copyTestExpireTime: BackupTimestamp
+        ) {
+          const [backup, op] = await TABLE.createBackup(generateId('backup'), {
+            expireTime: sourceTestExpireTime,
+          });
+          {
+            await op.promise();
+            // Check expiry time for running operation.
+            await backup.getMetadata();
+            assert.deepStrictEqual(backup.expireDate, sourceExpireTime);
+          }
+          await testCopyBackup(
+            backup,
+            {
+              cluster: backup.cluster,
+              id: generateId('backup'),
+              expireTime: copyTestExpireTime,
+            },
+            INSTANCE
+          );
+        }
+        it('should copy to the same cluster with precise date expiry times', async () => {
+          await testWithExpiryTimes(sourceExpireTime, copyExpireTime);
+        });
+        it('should copy to the same cluster with timestamp expiry times', async () => {
+          // Calling toStruct converts times to a timestamp object.
+          // For example: sourceExpireTime.toStruct() = {seconds: 1706659851, nanos: 981000000}
+          await testWithExpiryTimes(
+            sourceExpireTime.toStruct(),
+            copyExpireTime.toStruct()
+          );
+        });
+        it('should copy to the same cluster with date expiry times', async () => {
+          await testWithExpiryTimes(
+            new Date(sourceExpireTimeMilliseconds),
+            new Date(copyExpireTimeMilliseconds)
+          );
+        });
+      });
+      it('should create backup of a table and copy it on another cluster of another instance', async () => {
+        const [backup, op] = await TABLE.createBackup(generateId('backup'), {
+          expireTime: sourceExpireTime,
+        });
+        {
+          await op.promise();
+          // Check the expiry time.
+          await backup.getMetadata();
+          assert.deepStrictEqual(backup.expireDate, sourceExpireTime);
+        }
+        // Create another instance
+        const instance = bigtable.instance(generateId('instance'));
+        const destinationClusterId = generateId('cluster');
+        {
+          // Create production instance with given options
+          const instanceOptions: InstanceOptions = {
+            clusters: [
+              {
+                id: destinationClusterId,
+                nodes: 3,
+                location: 'us-central1-f',
+                storage: 'ssd',
+              },
+            ],
+            labels: {'prod-label': 'prod-label'},
+            type: 'production',
+          };
+          const [, operation] = await instance.create(instanceOptions);
+          await operation.promise();
+        }
+        // Create the copy and test the copied backup
+        await testCopyBackup(
+          backup,
+          {
+            cluster: new Cluster(instance, destinationClusterId),
+            id: generateId('backup'),
+            expireTime: copyExpireTime,
+          },
+          instance
+        );
+        await instance.delete();
+      });
+      it('should create backup of a table and copy it on another cluster of the same instance', async () => {
+        const [backup, op] = await TABLE.createBackup(generateId('backup'), {
+          expireTime: sourceExpireTime,
+        });
+        {
+          await op.promise();
+          // Check the expiry time.
+          await backup.getMetadata();
+          assert.deepStrictEqual(backup.expireDate, sourceExpireTime);
+        }
+        const destinationClusterId = generateId('cluster');
+        {
+          // Create destination cluster with given options
+          const [, operation] = await INSTANCE.cluster(
+            destinationClusterId
+          ).create({
+            location: 'us-central1-b',
+            nodes: 3,
+          });
+          await operation.promise();
+        }
+        // Create the copy and test the copied backup
+        await testCopyBackup(
+          backup,
+          {
+            cluster: new Cluster(INSTANCE, destinationClusterId),
+            id: generateId('backup'),
+            expireTime: copyExpireTime,
+          },
+          INSTANCE
+        );
+      });
+      it('should create backup of a table and copy it on another project', async () => {
+        const [backup, op] = await TABLE.createBackup(generateId('backup'), {
+          expireTime: sourceExpireTime,
+        });
+        {
+          await op.promise();
+          // Check the expiry time.
+          await backup.getMetadata();
+          assert.deepStrictEqual(backup.expireDate, sourceExpireTime);
+        }
+        // Create client, instance, cluster for second project
+        const bigtableSecondaryProject = new Bigtable(
+          process.env.GCLOUD_PROJECT2
+            ? {projectId: process.env.GCLOUD_PROJECT2}
+            : {}
+        );
+        const secondInstance = bigtableSecondaryProject.instance(
+          generateId('instance')
+        );
+        const destinationClusterId = generateId('cluster');
+        {
+          // Create production instance with given options
+          const instanceOptions: InstanceOptions = {
+            clusters: [
+              {
+                id: destinationClusterId,
+                nodes: 3,
+                location: 'us-central1-f',
+                storage: 'ssd',
+              },
+            ],
+            labels: {'prod-label': 'prod-label'},
+            type: 'production',
+          };
+          const [, operation] = await secondInstance.create(instanceOptions);
+          await operation.promise();
+        }
+        // Create the copy and test the copied backup
+        await testCopyBackup(
+          backup,
+          {
+            cluster: new Cluster(secondInstance, destinationClusterId),
+            id: generateId('backup'),
+            expireTime: copyExpireTime,
+          },
+          secondInstance
+        );
+        await secondInstance.delete();
+      });
+      it('should restore a copied backup', async () => {
+        const backupId = generateId('backup');
+        const table = INSTANCE.table('old-table');
+        {
+          // Create a table and insert data into it.
+          await table.create();
+          await table.createFamily('follows');
+          await table.insert([
+            {
+              key: 'some-data-to-copy-key',
+              data: {
+                follows: {
+                  copyData: 'data-to-copy',
+                },
+              },
+            },
+          ]);
+        }
+        // Create the backup
+        const [backup, createBackupOperation] = await table.createBackup(
+          backupId,
+          {
+            expireTime: sourceExpireTime,
+          }
+        );
+        await createBackupOperation.promise();
+        // Copy the backup
+        const config = {
+          cluster: backup.cluster,
+          id: generateId('backup'),
+          expireTime: copyExpireTime,
+        };
+        const [newBackup, copyOperation] = await backup.copy(config);
+        await copyOperation.promise();
+        // Restore a table from the copied backup
+        const [newTable, restoreOperation] =
+          await newBackup.restore('new-table');
+        await restoreOperation.promise();
+        const rows = await newTable.getRows();
+        assert.deepStrictEqual(rows[0][0].id, 'some-data-to-copy-key');
+      });
+    });
   });
 });