feat(auth): Add bulk get/delete methods (#365)

This PR allows callers to retrieve a list of users by unique identifier (uid, email, phone, federated provider uid) as well as to delete a list of users.

RELEASE NOTE: Added getUsers() and deleteUsers() APIs for retrieving and deleting user accounts in bulk.

Author: rsgowman

src/main/java/com/google/firebase/auth/DeleteUsersResult.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2020 Google Inc.
+ *
+ * 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.
+ */
+
+package com.google.firebase.auth;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.common.collect.ImmutableList;
+import com.google.firebase.auth.internal.BatchDeleteResponse;
+import com.google.firebase.internal.NonNull;
+import java.util.List;
+
+/**
+ * Represents the result of the {@link FirebaseAuth#deleteUsersAsync(List)} API.
+ */
+public final class DeleteUsersResult {
+
+  private final int successCount;
+  private final List<ErrorInfo> errors;
+
+  DeleteUsersResult(int users, BatchDeleteResponse response) {
+    ImmutableList.Builder<ErrorInfo> errorsBuilder = ImmutableList.builder();
+    List<BatchDeleteResponse.ErrorInfo> responseErrors = response.getErrors();
+    if (responseErrors != null) {
+      checkArgument(users >= responseErrors.size());
+      for (BatchDeleteResponse.ErrorInfo error : responseErrors) {
+        errorsBuilder.add(new ErrorInfo(error.getIndex(), error.getMessage()));
+      }
+    }
+    errors = errorsBuilder.build();
+    successCount = users - errors.size();
+  }
+
+  /**
+   * Returns the number of users that were deleted successfully (possibly zero). Users that did not
+   * exist prior to calling {@link FirebaseAuth#deleteUsersAsync(List)} are considered to be
+   * successfully deleted.
+   */ 
+  public int getSuccessCount() {
+    return successCount;
+  }
+
+  /**
+   * Returns the number of users that failed to be deleted (possibly zero).
+   */
+  public int getFailureCount() {
+    return errors.size();
+  }
+
+  /**
+   * A list of {@link ErrorInfo} instances describing the errors that were encountered during
+   * the deletion. Length of this list is equal to the return value of 
+   * {@link #getFailureCount()}.
+   *
+   * @return A non-null list (possibly empty).
+   */
+  @NonNull
+  public List<ErrorInfo> getErrors() {
+    return errors;
+  }
+}

src/main/java/com/google/firebase/auth/EmailIdentifier.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020 Google Inc.
+ *
+ * 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.
+ */
+
+package com.google.firebase.auth;
+
+import com.google.firebase.auth.internal.GetAccountInfoRequest;
+import com.google.firebase.internal.NonNull;
+
+/**
+ * Used for looking up an account by email.
+ *
+ * @see {FirebaseAuth#getUsers}
+ */
+public final class EmailIdentifier extends UserIdentifier {
+  private final String email;
+
+  public EmailIdentifier(@NonNull String email) {
+    UserRecord.checkEmail(email);
+    this.email = email;
+  }
+
+  @Override
+  public String toString() {
+    return "EmailIdentifier(" + email + ")";
+  }
+
+  @Override
+  void populate(@NonNull GetAccountInfoRequest payload) {
+    payload.addEmail(email);
+  }
+
+  @Override
+  boolean matches(@NonNull UserRecord userRecord) {
+    return email.equals(userRecord.getEmail());
+  }
+}

src/main/java/com/google/firebase/auth/FirebaseAuth.java

@@ -42,8 +42,11 @@
 import com.google.firebase.internal.Nullable;
 
 import java.io.IOException;
+import java.util.Collection;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
@@ -601,7 +604,82 @@ protected UserRecord execute() throws FirebaseAuthException {
   }
 
   /**
-   * Gets a page of users starting from the specified {@code pageToken}. Page size will be
+   * Gets the user data corresponding to the specified identifiers.
+   *
+   * <p>There are no ordering guarantees; in particular, the nth entry in the users result list is
+   * not guaranteed to correspond to the nth entry in the input parameters list.
+   *
+   * <p>A maximum of 100 identifiers may be specified. If more than 100 identifiers are
+   * supplied, this method throws an {@link IllegalArgumentException}.
+   *
+   * @param identifiers The identifiers used to indicate which user records should be returned. Must
+   *     have 100 or fewer entries.
+   * @return The corresponding user records.
+   * @throws IllegalArgumentException If any of the identifiers are invalid or if more than 100
+   *     identifiers are specified.
+   * @throws NullPointerException If the identifiers parameter is null.
+   * @throws FirebaseAuthException If an error occurs while retrieving user data.
+   */
+  public GetUsersResult getUsers(@NonNull Collection<UserIdentifier> identifiers)
+      throws FirebaseAuthException {
+    return getUsersOp(identifiers).call();
+  }
+
+  /**
+   * Gets the user data corresponding to the specified identifiers.
+   *
+   * <p>There are no ordering guarantees; in particular, the nth entry in the users result list is
+   * not guaranteed to correspond to the nth entry in the input parameters list.
+   *
+   * <p>A maximum of 100 identifiers may be specified. If more than 100 identifiers are
+   * supplied, this method throws an {@link IllegalArgumentException}.
+   *
+   * @param identifiers The identifiers used to indicate which user records should be returned.
+   *     Must have 100 or fewer entries.
+   * @return An {@code ApiFuture} that resolves to the corresponding user records.
+   * @throws IllegalArgumentException If any of the identifiers are invalid or if more than 100
+   *     identifiers are specified.
+   * @throws NullPointerException If the identifiers parameter is null.
+   */
+  public ApiFuture<GetUsersResult> getUsersAsync(@NonNull Collection<UserIdentifier> identifiers) {
+    return getUsersOp(identifiers).callAsync(firebaseApp);
+  }
+
+  private CallableOperation<GetUsersResult, FirebaseAuthException> getUsersOp(
+      @NonNull final Collection<UserIdentifier> identifiers) {
+    checkNotDestroyed();
+    checkNotNull(identifiers, "identifiers must not be null");
+    checkArgument(identifiers.size() <= FirebaseUserManager.MAX_GET_ACCOUNTS_BATCH_SIZE,
+        "identifiers parameter must have <= " + FirebaseUserManager.MAX_GET_ACCOUNTS_BATCH_SIZE
+        + " entries.");
+
+    final FirebaseUserManager userManager = getUserManager();
+    return new CallableOperation<GetUsersResult, FirebaseAuthException>() {
+      @Override
+      protected GetUsersResult execute() throws FirebaseAuthException {
+        Set<UserRecord> users = userManager.getAccountInfo(identifiers);
+        Set<UserIdentifier> notFound = new HashSet<>();
+        for (UserIdentifier id : identifiers) {
+          if (!isUserFound(id, users)) {
+            notFound.add(id);
+          }
+        }
+        return new GetUsersResult(users, notFound);
+      }
+    };
+  }
+
+  private boolean isUserFound(UserIdentifier id, Collection<UserRecord> userRecords) {
+    for (UserRecord userRecord : userRecords) {
+      if (id.matches(userRecord)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Gets a page of users starting from the specified {@code pageToken}. Page size is
    * limited to 1000 users.
    *
    * @param pageToken A non-empty page token string, or null to retrieve the first page of users.
@@ -842,8 +920,67 @@ protected Void execute() throws FirebaseAuthException {
   }
 
   /**
-   * Imports the provided list of users into Firebase Auth. At most 1000 users can be imported at a
-   * time. This operation is optimized for bulk imports and will ignore checks on identifier
+   * Deletes the users specified by the given identifiers.
+   *
+   * <p>Deleting a non-existing user does not generate an error (the method is idempotent).
+   * Non-existing users are considered to be successfully deleted and are therefore included in the
+   * DeleteUsersResult.getSuccessCount() value.
+   *
+   * <p>A maximum of 1000 identifiers may be supplied. If more than 1000 identifiers are
+   * supplied, this method throws an {@link IllegalArgumentException}.
+   *
+   * <p>This API has a rate limit of 1 QPS. Exceeding the limit may result in a quota exceeded
+   * error. If you want to delete more than 1000 users, we suggest adding a delay to ensure you
+   * don't exceed this limit.
+   *
+   * @param uids The uids of the users to be deleted. Must have <= 1000 entries.
+   * @return The total number of successful/failed deletions, as well as the array of errors that
+   *     correspond to the failed deletions.
+   * @throw IllegalArgumentException If any of the identifiers are invalid or if more than 1000
+   *     identifiers are specified.
+   * @throws FirebaseAuthException If an error occurs while deleting users.
+   */
+  public DeleteUsersResult deleteUsers(List<String> uids) throws FirebaseAuthException {
+    return deleteUsersOp(uids).call();
+  }
+
+  /**
+   * Similar to {@link #deleteUsers(List)} but performs the operation asynchronously.
+   *
+   * @param uids The uids of the users to be deleted. Must have <= 1000 entries.
+   * @return An {@code ApiFuture} that resolves to the total number of successful/failed
+   *     deletions, as well as the array of errors that correspond to the failed deletions. If an
+   *     error occurs while deleting the user account, the future throws a
+   *     {@link FirebaseAuthException}.
+   * @throw IllegalArgumentException If any of the identifiers are invalid or if more than 1000
+   *     identifiers are specified.
+   */
+  public ApiFuture<DeleteUsersResult> deleteUsersAsync(List<String> uids) {
+    return deleteUsersOp(uids).callAsync(firebaseApp);
+  }
+
+  private CallableOperation<DeleteUsersResult, FirebaseAuthException> deleteUsersOp(
+      final List<String> uids) {
+    checkNotDestroyed();
+    checkNotNull(uids, "uids must not be null");
+    for (String uid : uids) {
+      UserRecord.checkUid(uid);
+    }
+    checkArgument(uids.size() <= FirebaseUserManager.MAX_DELETE_ACCOUNTS_BATCH_SIZE,
+        "uids parameter must have <= " + FirebaseUserManager.MAX_DELETE_ACCOUNTS_BATCH_SIZE
+        + " entries.");
+    final FirebaseUserManager userManager = getUserManager();
+    return new CallableOperation<DeleteUsersResult, FirebaseAuthException>() {
+      @Override
+      protected DeleteUsersResult execute() throws FirebaseAuthException {
+        return userManager.deleteUsers(uids);
+      }
+    };
+  }
+
+  /**
+   * Imports the provided list of users into Firebase Auth. You can import a maximum of 1000 users
+   * at a time.  This operation is optimized for bulk imports and does not check identifier
    * uniqueness which could result in duplications.
    *
    * <p>{@link UserImportOptions} is required to import users with passwords. See

src/main/java/com/google/firebase/auth/FirebaseUserManager.java

@@ -39,9 +39,10 @@
 import com.google.firebase.ImplFirebaseTrampolines;
 import com.google.firebase.auth.UserRecord.CreateRequest;
 import com.google.firebase.auth.UserRecord.UpdateRequest;
+import com.google.firebase.auth.internal.BatchDeleteResponse;
 import com.google.firebase.auth.internal.DownloadAccountResponse;
+import com.google.firebase.auth.internal.GetAccountInfoRequest;
 import com.google.firebase.auth.internal.GetAccountInfoResponse;
-
 import com.google.firebase.auth.internal.HttpErrorResponse;
 import com.google.firebase.auth.internal.UploadAccountResponse;
 import com.google.firebase.internal.ApiClientUtils;
@@ -50,8 +51,11 @@
 import com.google.firebase.internal.SdkUtils;
 
 import java.io.IOException;
+import java.util.Collection;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * FirebaseUserManager provides methods for interacting with the Google Identity Toolkit via its
@@ -86,6 +90,8 @@ class FirebaseUserManager {
       .put("INVALID_DYNAMIC_LINK_DOMAIN", "invalid-dynamic-link-domain")
       .build();
 
+  static final int MAX_GET_ACCOUNTS_BATCH_SIZE = 100;
+  static final int MAX_DELETE_ACCOUNTS_BATCH_SIZE = 1000;
   static final int MAX_LIST_USERS_RESULTS = 1000;
   static final int MAX_IMPORT_USERS = 1000;
 
@@ -171,6 +177,33 @@ UserRecord getUserByPhoneNumber(String phoneNumber) throws FirebaseAuthException
     return new UserRecord(response.getUsers().get(0), jsonFactory);
   }
 
+  Set<UserRecord> getAccountInfo(@NonNull Collection<UserIdentifier> identifiers)
+      throws FirebaseAuthException {
+    if (identifiers.isEmpty()) {
+      return new HashSet<UserRecord>();
+    }
+
+    GetAccountInfoRequest payload = new GetAccountInfoRequest();
+    for (UserIdentifier id : identifiers) {
+      id.populate(payload);
+    }
+
+    GetAccountInfoResponse response = post(
+        "/accounts:lookup", payload, GetAccountInfoResponse.class);
+
+    if (response == null) {
+      throw new FirebaseAuthException(INTERNAL_ERROR, "Failed to parse server response");
+    }
+
+    Set<UserRecord> results = new HashSet<>();
+    if (response.getUsers() != null) {
+      for (GetAccountInfoResponse.User user : response.getUsers()) {
+        results.add(new UserRecord(user, jsonFactory));
+      }
+    }
+    return results;
+  }
+
   String createUser(CreateRequest request) throws FirebaseAuthException {
     GenericJson response = post(
         "/accounts", request.getProperties(), GenericJson.class);
@@ -200,6 +233,23 @@ void deleteUser(String uid) throws FirebaseAuthException {
     }
   }
 
+  /**
+   * @pre uids != null
+   * @pre uids.size() <= MAX_DELETE_ACCOUNTS_BATCH_SIZE
+   */
+  DeleteUsersResult deleteUsers(@NonNull List<String> uids) throws FirebaseAuthException {
+    final Map<String, Object> payload = ImmutableMap.<String, Object>of(
+        "localIds", uids,
+        "force", true);
+    BatchDeleteResponse response = post(
+        "/accounts:batchDelete", payload, BatchDeleteResponse.class);
+    if (response == null) {
+      throw new FirebaseAuthException(INTERNAL_ERROR, "Failed to delete users");
+    }
+
+    return new DeleteUsersResult(uids.size(), response);
+  }
+
   DownloadAccountResponse listUsers(int maxResults, String pageToken) throws FirebaseAuthException {
     ImmutableMap.Builder<String, Object> builder = ImmutableMap.<String, Object>builder()
         .put("maxResults", maxResults);