feat: Firestore managed bulk delete (#8974)

* WIP: Adding firestore:bulk-delete command.

* Did clean ups. Manual testing works as expected.

* Fixes and add tests.

* fix test suite name

* Address feedback (1).

* address feedback (2).

* address feedback (3).

* rename bulk-delete to bulkdelete.

* Address feedback and add changelog.

* Add the requireAuth back for spec tests.

Author: ehsannas

CHANGELOG.md

@@ -1,3 +1,5 @@
+- Added `firestore:bulkdelete` which initiates a Firestore managed bulk delete operation (#8974)
+- Added `firestore:operations:*` commands to list, describe, and cancel long-running operations (#8982)
 - `firebase emulator:start` use a default project `demo-no-project` if no project can be found. (#9072)
 - `firebase init dataconnect` also supports bootstrapping flutter template. (#9084)
 - Fixed a vulnerability in `unzip` util where files could be written outside of the expected output directory.

src/commands/firestore-bulkdelete.spec.ts

@@ -0,0 +1,95 @@
+import * as sinon from "sinon";
+import { expect } from "chai";
+import { Command } from "../command";
+import { command as firestoreBulkDelete } from "./firestore-bulkdelete";
+import * as fsi from "../firestore/api";
+import { FirebaseError } from "../error";
+import * as requireAuthModule from "../requireAuth";
+import { BulkDeleteDocumentsResponse } from "../firestore/api-types";
+
+describe("firestore:bulkdelete", () => {
+  const PROJECT = "test-project";
+  const DATABASE = "test-database";
+  const COLLECTION_IDS = ["collection1", "collection2"];
+
+  let command: Command;
+  let firestoreApiStub: sinon.SinonStubbedInstance<fsi.FirestoreApi>;
+  let requireAuthStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    command = firestoreBulkDelete;
+    firestoreApiStub = sinon.createStubInstance(fsi.FirestoreApi);
+    requireAuthStub = sinon.stub(requireAuthModule, "requireAuth");
+    sinon.stub(fsi, "FirestoreApi").returns(firestoreApiStub);
+    requireAuthStub.resolves("[email protected]");
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  const mockResponse = (name: string): BulkDeleteDocumentsResponse => {
+    return {
+      name,
+    };
+  };
+
+  it("should throw an error if collection-ids is not provided", async () => {
+    const options = {
+      project: PROJECT,
+    };
+
+    await expect(command.runner()(options)).to.be.rejectedWith(
+      FirebaseError,
+      "Missing required flag --collection-ids=[comma separated list of collection groups]",
+    );
+  });
+
+  it("should call bulkDeleteDocuments with the correct parameters", async () => {
+    const options = {
+      project: PROJECT,
+      collectionIds: COLLECTION_IDS.join(","),
+      force: true,
+      json: true,
+    };
+    const expectedResponse = mockResponse("test-operation");
+    firestoreApiStub.bulkDeleteDocuments.resolves(expectedResponse);
+
+    const result = await command.runner()(options);
+
+    expect(result).to.deep.equal(expectedResponse);
+    expect(
+      firestoreApiStub.bulkDeleteDocuments.calledOnceWith(PROJECT, "(default)", COLLECTION_IDS),
+    ).to.be.true;
+  });
+
+  it("should call bulkDeleteDocuments with the correct database", async () => {
+    const options = {
+      project: PROJECT,
+      database: DATABASE,
+      collectionIds: COLLECTION_IDS.join(","),
+      force: true,
+      json: true,
+    };
+    const expectedResponse = mockResponse("test-operation");
+    firestoreApiStub.bulkDeleteDocuments.resolves(expectedResponse);
+
+    const result = await command.runner()(options);
+
+    expect(result).to.deep.equal(expectedResponse);
+    expect(firestoreApiStub.bulkDeleteDocuments.calledOnceWith(PROJECT, DATABASE, COLLECTION_IDS))
+      .to.be.true;
+  });
+
+  it("should throw an error if the API call fails", async () => {
+    const options = {
+      project: PROJECT,
+      collectionIds: COLLECTION_IDS.join(","),
+      force: true,
+    };
+    const apiError = new Error("API Error");
+    firestoreApiStub.bulkDeleteDocuments.rejects(apiError);
+
+    await expect(command.runner()(options)).to.be.rejectedWith(apiError);
+  });
+});

src/commands/firestore-bulkdelete.ts

@@ -0,0 +1,96 @@
+import { Command } from "../command";
+import * as fsi from "../firestore/api";
+import { logger } from "../logger";
+import { requirePermissions } from "../requirePermissions";
+import { Emulators } from "../emulator/types";
+import { warnEmulatorNotSupported } from "../emulator/commandUtils";
+import { FirestoreOptions } from "../firestore/options";
+import { confirm } from "../prompt";
+import * as utils from "../utils";
+import * as clc from "colorette";
+import { logBullet, logLabeledError, logSuccess } from "../utils";
+import { FirebaseError } from "../error";
+
+function confirmationMessage(
+  options: FirestoreOptions,
+  databaseId: string,
+  collectionIds: string[],
+): string {
+  const root = `projects/${options.project}/databases/${databaseId}/documents`;
+  return (
+    "You are about to delete all documents in the following collection groups: " +
+    clc.cyan(collectionIds.map((item) => `"${item}"`).join(", ")) +
+    " in " +
+    clc.cyan(`"${root}"`) +
+    ". Are you sure?"
+  );
+}
+
+export const command = new Command("firestore:bulkdelete")
+  .description("managed bulk delete service to delete data from one or more collection groups")
+  .option(
+    "--database <databaseName>",
+    'Database ID for database to delete from. "(default)" if none is provided.',
+  )
+  .option(
+    "--collection-ids <collectionIds>",
+    "A comma-separated list of collection group IDs to delete. Deletes all documents in the specified collection groups.",
+  )
+  .before(requirePermissions, ["datastore.databases.bulkDeleteDocuments"])
+  .before(warnEmulatorNotSupported, Emulators.FIRESTORE)
+  .action(async (options: FirestoreOptions) => {
+    if (!options.collectionIds) {
+      throw new FirebaseError(
+        "Missing required flag --collection-ids=[comma separated list of collection groups]",
+      );
+    }
+    let collectionIds: string[] = [];
+    try {
+      collectionIds = (options.collectionIds as string)
+        .split(",")
+        .filter((id: string) => id.trim() !== "");
+    } catch (e) {
+      throw new FirebaseError(
+        "The value for --collection-ids must a list of comma separated collection group names",
+      );
+    }
+
+    if (collectionIds.length === 0) {
+      throw new FirebaseError("Must specify at least one collection ID in --collection-ids.");
+    }
+
+    const databaseId = options.database || "(default)";
+
+    const api = new fsi.FirestoreApi();
+
+    const confirmed = await confirm({
+      message: confirmationMessage(options, databaseId, collectionIds),
+      default: false,
+      force: options.force,
+      nonInteractive: options.nonInteractive,
+    });
+    if (!confirmed) {
+      return utils.reject("Command aborted.", { exit: 1 });
+    }
+
+    const op = await api.bulkDeleteDocuments(options.project, databaseId, collectionIds);
+
+    if (options.json) {
+      logger.info(JSON.stringify(op, undefined, 2));
+    } else {
+      if (op.name) {
+        logSuccess(`Successfully started bulk delete operation.`);
+        logBullet(`Operation name: ` + clc.cyan(op.name));
+        // TODO: Update this message to 'firebase firestore:operations:describe' command once it's implemented.
+        logBullet(
+          "You can monitor the operation's progress using the " +
+            clc.cyan(`gcloud firestore operations describe`) +
+            ` command.`,
+        );
+      } else {
+        logLabeledError(`Bulk Delete:`, `Failed to start a bulk delete operation.`);
+      }
+    }
+
+    return op;
+  });

src/commands/index.ts

@@ -101,6 +101,7 @@ export function load(client: any): any {
   client.ext.dev.usage = loadCommand("ext-dev-usage");
   client.firestore = {};
   client.firestore.delete = loadCommand("firestore-delete");
+  client.firestore.bulkDelete = loadCommand("firestore-bulkdelete");
   client.firestore.indexes = loadCommand("firestore-indexes-list");
   client.firestore.locations = loadCommand("firestore-locations");
   client.firestore.operations = {};

src/firestore/api-types.ts

@@ -183,6 +183,19 @@ export interface DatabaseResp {
   databaseEdition?: DatabaseEdition;
 }
 
+export interface BulkDeleteDocumentsRequest {
+  // Database to operate. Should be of the form:
+  // `projects/{project_id}/databases/{database_id}`.
+  name: string;
+  // IDs of the collection groups to delete. Unspecified means *all* collection groups.
+  // Each collection group in this list must be unique.
+  collectionIds?: string[];
+}
+
+export type BulkDeleteDocumentsResponse = {
+  name?: string;
+};
+
 export interface Operation {
   name: string;
   done: boolean;

src/firestore/api.ts

@@ -835,6 +835,32 @@ export class FirestoreApi {
     return database;
   }
 
+  /**
+   * Bulk delete documents from a Firestore database.
+   * @param project the Firebase project id.
+   * @param databaseId the id of the Firestore Database.
+   * @param collectionIds the collection IDs to delete.
+   */
+  async bulkDeleteDocuments(
+    project: string,
+    databaseId: string,
+    collectionIds: string[],
+  ): Promise<types.BulkDeleteDocumentsResponse> {
+    const name = `/projects/${project}/databases/${databaseId}`;
+    const url = `${name}:bulkDeleteDocuments`;
+    const payload: types.BulkDeleteDocumentsRequest = {
+      name,
+      collectionIds,
+    };
+    const res = await this.apiClient.post<
+      types.BulkDeleteDocumentsRequest,
+      types.BulkDeleteDocumentsResponse
+    >(url, payload);
+    return {
+      name: res.body?.name,
+    };
+  }
+
   /**
    * Restore a Firestore Database from a backup.
    * @param project the Firebase project id.