Firestore: Improve persistent cache index auto-creation tests by adding internal testing hooks

Author: dconeybe

.changeset/four-kids-film.md

@@ -0,0 +1,6 @@
+---
+'@firebase/firestore': patch
+'firebase': patch
+---
+
+Internal refactoring to improve testing support of persistent cache index auto-creation.

packages/firestore/externs.json

@@ -31,6 +31,7 @@
     "packages/util/dist/src/environment.d.ts",
     "packages/util/dist/src/compat.d.ts",
     "packages/util/dist/src/obj.d.ts",
+    "packages/firestore/src/api/persistent_cache_index_manager.ts",
     "packages/firestore/src/protos/firestore_bundle_proto.ts",
     "packages/firestore/src/protos/firestore_proto_api.ts",
     "packages/firestore/src/util/error.ts",

packages/firestore/src/api/persistent_cache_index_manager.ts

@@ -18,10 +18,12 @@
 import {
   firestoreClientDeleteAllFieldIndexes,
   firestoreClientSetPersistentCacheIndexAutoCreationEnabled,
-  FirestoreClient
+  FirestoreClient,
+  TestingHooks as FirestoreClientTestingHooks
 } from '../core/firestore_client';
 import { cast } from '../util/input_validation';
 import { logDebug, logWarn } from '../util/log';
+import { testingHooksSpi } from '../util/testing_hooks_spi';
 
 import { ensureFirestoreConfigured, Firestore } from './database';
 
@@ -121,6 +123,8 @@ export function deleteAllPersistentCacheIndexes(
     .catch(error =>
       logWarn('deleting all persistent cache indexes failed', error)
     );
+
+  testingHooksSpi?.notifyPersistentCacheDeleteAllIndexes(promise);
 }
 
 function setPersistentCacheIndexAutoCreationEnabled(
@@ -148,6 +152,8 @@ function setPersistentCacheIndexAutoCreationEnabled(
         error
       )
     );
+
+  testingHooksSpi?.notifyPersistentCacheIndexAutoCreationToggle(promise);
 }
 
 /**
@@ -162,3 +168,25 @@ const persistentCacheIndexManagerByFirestore = new WeakMap<
   Firestore,
   PersistentCacheIndexManager
 >();
+
+/**
+ * Test-only hooks into the SDK for use exclusively by tests.
+ */
+export class TestingHooks {
+  private constructor() {
+    throw new Error('creating instances is not supported');
+  }
+
+  static setIndexAutoCreationSettings(
+    indexManager: PersistentCacheIndexManager,
+    settings: {
+      indexAutoCreationMinCollectionSize?: number;
+      relativeIndexReadCostPerDocument?: number;
+    }
+  ): Promise<void> {
+    return FirestoreClientTestingHooks.setPersistentCacheIndexAutoCreationSettings(
+      indexManager._client,
+      settings
+    );
+  }
+}

packages/firestore/src/core/firestore_client.ts

@@ -23,6 +23,7 @@ import {
   CredentialsProvider
 } from '../api/credentials';
 import { User } from '../auth/user';
+import { IndexType } from '../local/index_manager';
 import { LocalStore } from '../local/local_store';
 import {
   localStoreConfigureFieldIndexes,
@@ -31,7 +32,8 @@ import {
   localStoreGetNamedQuery,
   localStoreHandleUserChange,
   localStoreReadDocument,
-  localStoreSetIndexAutoCreationEnabled
+  localStoreSetIndexAutoCreationEnabled,
+  TestingHooks as LocalStoreTestingHooks
 } from '../local/local_store_impl';
 import { Persistence } from '../local/persistence';
 import { Document } from '../model/document';
@@ -850,3 +852,39 @@ export function firestoreClientDeleteAllFieldIndexes(
     return localStoreDeleteAllFieldIndexes(await getLocalStore(client));
   });
 }
+
+/**
+ * Test-only hooks into the SDK for use exclusively by tests.
+ */
+export class TestingHooks {
+  private constructor() {
+    throw new Error('creating instances is not supported');
+  }
+
+  static getQueryIndexType(
+    client: FirestoreClient,
+    query: Query
+  ): Promise<IndexType> {
+    return client.asyncQueue.enqueue(async () => {
+      const localStore = await getLocalStore(client);
+      return LocalStoreTestingHooks.getQueryIndexType(localStore, query);
+    });
+  }
+
+  static setPersistentCacheIndexAutoCreationSettings(
+    client: FirestoreClient,
+    settings: {
+      indexAutoCreationMinCollectionSize?: number;
+      relativeIndexReadCostPerDocument?: number;
+    }
+  ): Promise<void> {
+    const settingsCopy = { ...settings };
+    return client.asyncQueue.enqueue(async () => {
+      const localStore = await getLocalStore(client);
+      LocalStoreTestingHooks.setIndexAutoCreationSettings(
+        localStore,
+        settingsCopy
+      );
+    });
+  }
+}

packages/firestore/src/local/local_store_impl.ts

@@ -70,7 +70,7 @@ import { BATCHID_UNKNOWN } from '../util/types';
 
 import { BundleCache } from './bundle_cache';
 import { DocumentOverlayCache } from './document_overlay_cache';
-import { IndexManager } from './index_manager';
+import { IndexManager, IndexType } from './index_manager';
 import { IndexedDbMutationQueue } from './indexeddb_mutation_queue';
 import { IndexedDbPersistence } from './indexeddb_persistence';
 import { IndexedDbTargetCache } from './indexeddb_target_cache';
@@ -1572,4 +1572,17 @@ export class TestingHooks {
         settings.relativeIndexReadCostPerDocument;
     }
   }
+
+  static getQueryIndexType(
+    localStore: LocalStore,
+    query: Query
+  ): Promise<IndexType> {
+    const localStoreImpl = debugCast(localStore, LocalStoreImpl);
+    const target = queryToTarget(query);
+    return localStoreImpl.persistence.runTransaction(
+      'local_store_impl TestingHooks getQueryIndexType',
+      'readonly',
+      txn => localStoreImpl.indexManager.getIndexType(txn, target)
+    );
+  }
 }

packages/firestore/src/util/testing_hooks.ts

@@ -15,8 +15,17 @@
  * limitations under the License.
  */
 
+import { ensureFirestoreConfigured, Firestore } from '../api/database';
+import {
+  PersistentCacheIndexManager,
+  TestingHooks as PersistentCacheIndexManagerTestingHooks
+} from '../api/persistent_cache_index_manager';
 import { Unsubscribe } from '../api/reference_impl';
+import { TestingHooks as FirestoreClientTestingHooks } from '../core/firestore_client';
+import { Query } from '../lite-api/reference';
+import { IndexType } from '../local/index_manager';
 
+import { cast } from './input_validation';
 import {
   setTestingHooksSpi,
   ExistenceFilterMismatchInfo,
@@ -54,6 +63,106 @@ export class TestingHooks {
   ): Unsubscribe {
     return TestingHooksSpiImpl.instance.onExistenceFilterMismatch(callback);
   }
+
+  /**
+   * Registers a callback to be notified when
+   * `enablePersistentCacheIndexAutoCreation()` or
+   * `disablePersistentCacheIndexAutoCreation()` is invoked.
+   *
+   * The relative order in which callbacks are notified is unspecified; do not
+   * rely on any particular ordering. If a given callback is registered multiple
+   * times then it will be notified multiple times, once per registration.
+   *
+   * @param callback the callback to invoke when
+   * `enablePersistentCacheIndexAutoCreation()` or
+   * `disablePersistentCacheIndexAutoCreation()` is invoked.
+   *
+   * @return a function that, when called, unregisters the given callback; only
+   * the first invocation of the returned function does anything; all subsequent
+   * invocations do nothing.
+   */
+  static onPersistentCacheIndexAutoCreationToggle(
+    callback: PersistentCacheIndexAutoCreationToggleCallback
+  ): Unsubscribe {
+    return TestingHooksSpiImpl.instance.onPersistentCacheIndexAutoCreationToggle(
+      callback
+    );
+  }
+
+  /**
+   * Registers a callback to be notified when
+   * `deleteAllPersistentCacheIndexes()` is invoked.
+   *
+   * The relative order in which callbacks are notified is unspecified; do not
+   * rely on any particular ordering. If a given callback is registered multiple
+   * times then it will be notified multiple times, once per registration.
+   *
+   * @param callback the callback to invoke when
+   * `deleteAllPersistentCacheIndexes()` is invoked.
+   *
+   * @return a function that, when called, unregisters the given callback; only
+   * the first invocation of the returned function does anything; all subsequent
+   * invocations do nothing.
+   */
+  static onPersistentCacheDeleteAllIndexes(
+    callback: PersistentCacheDeleteAllIndexesCallback
+  ): Unsubscribe {
+    return TestingHooksSpiImpl.instance.onPersistentCacheDeleteAllIndexes(
+      callback
+    );
+  }
+
+  /**
+   * Determines the type of client-side index that will be used when executing the
+   * given query against the local cache.
+   *
+   * @param query The query whose client-side index type to get; it is typed as
+   * `unknown` so that it is usable in the minified, bundled code, but it should
+   * be a `Query` object.
+   */
+  static async getQueryIndexType(
+    query: unknown
+  ): Promise<'full' | 'partial' | 'none'> {
+    const query_ = cast<Query>(query as Query, Query);
+    const firestore = cast(query_.firestore, Firestore);
+    const client = ensureFirestoreConfigured(firestore);
+
+    const indexType = await FirestoreClientTestingHooks.getQueryIndexType(
+      client,
+      query_._query
+    );
+
+    switch (indexType) {
+      case IndexType.NONE:
+        return 'none';
+      case IndexType.PARTIAL:
+        return 'partial';
+      case IndexType.FULL:
+        return 'full';
+      default:
+        throw new Error(`unrecognized IndexType: ${indexType}`);
+    }
+  }
+
+  /**
+   * Sets the persistent cache index auto-creation settings for the given
+   * Firestore instance.
+   *
+   * @return a Promise that is fulfilled when the settings are successfully
+   * applied, or rejected if applying the settings fails.
+   */
+  static setPersistentCacheIndexAutoCreationSettings(
+    indexManager: PersistentCacheIndexManager,
+    settings: {
+      indexAutoCreationMinCollectionSize?: number;
+      relativeIndexReadCostPerDocument?: number;
+    }
+  ): Promise<void> {
+    return PersistentCacheIndexManagerTestingHooks.setIndexAutoCreationSettings(
+      indexManager,
+      settings
+    );
+  }
 }
 
 /**
@@ -68,6 +177,39 @@ export type ExistenceFilterMismatchCallback = (
   info: ExistenceFilterMismatchInfo
 ) => unknown;
 
+/**
+ * The signature of callbacks registered with
+ * `TestingHooks.onPersistentCacheIndexAutoCreationToggle()`.
+ *
+ * The `promise` argument will be fulfilled when the asynchronous work started
+ * by the call to `enablePersistentCacheIndexAutoCreation()` or
+ * `disablePersistentCacheIndexAutoCreation()` completes successfully, or will
+ * be rejected if it fails.
+ *
+ * The return value, if any, is ignored.
+ *
+ * @internal
+ */
+export type PersistentCacheIndexAutoCreationToggleCallback = (
+  promise: Promise<void>
+) => unknown;
+
+/**
+ * The signature of callbacks registered with
+ * `TestingHooks.onPersistentCacheDeleteAllIndexes()`.
+ *
+ * The `promise` argument will be fulfilled when the asynchronous work started
+ * by the call to `deleteAllPersistentCacheIndexes()` completes successfully, or
+ * will be rejected if it fails.
+ *
+ * The return value of the callback, if any, is ignored.
+ *
+ * @internal
+ */
+export type PersistentCacheDeleteAllIndexesCallback = (
+  promise: Promise<void>
+) => unknown;
+
 /**
  * The implementation of `TestingHooksSpi`.
  */
@@ -77,6 +219,14 @@ class TestingHooksSpiImpl implements TestingHooksSpi {
     ExistenceFilterMismatchCallback
   >();
 
+  private readonly persistentCacheIndexAutoCreationToggleCallbacksById =
+    new Map<Symbol, PersistentCacheIndexAutoCreationToggleCallback>();
+
+  private readonly persistentCacheDeleteAllIndexesCallbacksById = new Map<
+    Symbol,
+    PersistentCacheDeleteAllIndexesCallback
+  >();
+
   private constructor() {}
 
   static get instance(): TestingHooksSpiImpl {
@@ -96,11 +246,50 @@ class TestingHooksSpiImpl implements TestingHooksSpi {
   onExistenceFilterMismatch(
     callback: ExistenceFilterMismatchCallback
   ): Unsubscribe {
-    const id = Symbol();
-    const callbacks = this.existenceFilterMismatchCallbacksById;
-    callbacks.set(id, callback);
-    return () => callbacks.delete(id);
+    return registerCallback(
+      callback,
+      this.existenceFilterMismatchCallbacksById
+    );
   }
+
+  notifyPersistentCacheIndexAutoCreationToggle(promise: Promise<void>): void {
+    this.persistentCacheIndexAutoCreationToggleCallbacksById.forEach(callback =>
+      callback(promise)
+    );
+  }
+
+  onPersistentCacheIndexAutoCreationToggle(
+    callback: PersistentCacheIndexAutoCreationToggleCallback
+  ): Unsubscribe {
+    return registerCallback(
+      callback,
+      this.persistentCacheIndexAutoCreationToggleCallbacksById
+    );
+  }
+
+  notifyPersistentCacheDeleteAllIndexes(promise: Promise<void>): void {
+    this.persistentCacheDeleteAllIndexesCallbacksById.forEach(callback =>
+      callback(promise)
+    );
+  }
+
+  onPersistentCacheDeleteAllIndexes(
+    callback: PersistentCacheDeleteAllIndexesCallback
+  ): Unsubscribe {
+    return registerCallback(
+      callback,
+      this.persistentCacheDeleteAllIndexesCallbacksById
+    );
+  }
+}
+
+function registerCallback<T>(
+  callback: T,
+  callbacks: Map<Symbol, T>
+): Unsubscribe {
+  const id = Symbol();
+  callbacks.set(id, callback);
+  return () => callbacks.delete(id);
 }
 
 let testingHooksSpiImplInstance: TestingHooksSpiImpl | null = null;