[Multi-Tab] Making Multi-Tab optional (#980)

Author: schmidt-sebastian

packages/firestore-types/index.d.ts

@@ -57,6 +57,26 @@ export interface Settings {
   timestampsInSnapshots?: boolean;
 }
 
+/**
+ * Settings that can be passed to Firestore.enablePersistence() to configure
+ * Firestore persistence.
+ */
+export interface PersistenceSettings {
+  /**
+   * Whether to synchronize the in-memory state of multiple tabs. Setting this
+   * to 'true' in all open tabs enables shared access to local persistence,
+   * shared execution of queries and latency-compensated local document updates
+   * across all connected instances.
+   *
+   * To enable this mode, `synchronizeTabs:true` needs to be set globally in
+   * all active tabs. If omitted or set to 'false', `enablePersistence()` will
+   * fail in all but the first tab.
+   *
+   * NOTE: This mode is experimental and not yet recommended for production use.
+   */
+  synchronizeTabs?: boolean;
+}
+
 export type LogLevel = 'debug' | 'error' | 'silent';
 
 export function setLogLevel(logLevel: LogLevel): void;
@@ -91,10 +111,11 @@ export class FirebaseFirestore {
    *   * unimplemented: The browser is incompatible with the offline
    *     persistence implementation.
    *
+   * @param settings Optional settings object to configure persistence.
    * @return A promise that represents successfully enabling persistent
    * storage.
    */
-  enablePersistence(): Promise<void>;
+  enablePersistence(settings?: PersistenceSettings): Promise<void>;
 
   /**
    * Gets a `CollectionReference` instance that refers to the collection at

packages/firestore/src/api/database.ts

@@ -98,10 +98,14 @@ import {
 // underscore to discourage their use.
 // tslint:disable:strip-private-property-underscore
 
+// settings() defaults:
 const DEFAULT_HOST = 'firestore.googleapis.com';
 const DEFAULT_SSL = true;
 const DEFAULT_TIMESTAMPS_IN_SNAPSHOTS = false;
 
+// enablePersistence() defaults:
+const DEFAULT_SYNCHRONIZE_TABS = false;
+
 /** Undocumented, private additional settings not exposed in our public API. */
 interface PrivateSettings extends firestore.Settings {
   // Can be a google-auth-library or gapi client.
@@ -198,6 +202,37 @@ class FirestoreConfig {
   persistence: boolean;
 }
 
+/**
+ * Encapsulates the settings that can be used to configure Firestore
+ * persistence.
+ */
+export class PersistenceSettings {
+  /** Whether to enable multi-tab synchronization. */
+  synchronizeTabs: boolean;
+
+  constructor(
+    readonly enabled: boolean,
+    settings?: firestore.PersistenceSettings
+  ) {
+    assert(
+      enabled || !settings,
+      'Can only provide PersistenceSettings with persistence enabled'
+    );
+    settings = settings || {};
+    this.synchronizeTabs = objUtils.defaulted(
+      settings.synchronizeTabs,
+      DEFAULT_SYNCHRONIZE_TABS
+    );
+  }
+
+  isEqual(other: PersistenceSettings): boolean {
+    return (
+      this.enabled === other.enabled &&
+      this.synchronizeTabs === other.synchronizeTabs
+    );
+  }
+}
+
 /**
  * The root reference to the database.
  */
@@ -291,7 +326,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
     return this._firestoreClient.disableNetwork();
   }
 
-  enablePersistence(): Promise<void> {
+  enablePersistence(settings?: firestore.PersistenceSettings): Promise<void> {
     if (this._firestoreClient) {
       throw new FirestoreError(
         Code.FAILED_PRECONDITION,
@@ -301,17 +336,21 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
       );
     }
 
-    return this.configureClient(/* persistence= */ true);
+    return this.configureClient(
+      new PersistenceSettings(/* enabled= */ true, settings)
+    );
   }
 
   ensureClientConfigured(): FirestoreClient {
     if (!this._firestoreClient) {
-      this.configureClient(/* persistence= */ false);
+      this.configureClient(new PersistenceSettings(/* enabled= */ false));
     }
     return this._firestoreClient as FirestoreClient;
   }
 
-  private configureClient(persistence: boolean): Promise<void> {
+  private configureClient(
+    persistenceSettings: PersistenceSettings
+  ): Promise<void> {
     assert(
       !!this._config.settings.host,
       'FirestoreSettings.host cannot be falsey'
@@ -377,7 +416,7 @@ follow these steps, YOUR APP MAY BREAK.`);
       this._config.credentials,
       this._queue
     );
-    return this._firestoreClient.start(persistence);
+    return this._firestoreClient.start(persistenceSettings);
   }
 
   private static databaseIdFromApp(app: FirebaseApp): DatabaseId {

packages/firestore/src/core/firestore_client.ts

@@ -59,6 +59,8 @@ import {
   WebStorageSharedClientState
 } from '../local/shared_client_state';
 import { AutoId } from '../util/misc';
+import { PersistenceSettings } from '../api/database';
+import { assert } from '../util/assert';
 
 const LOG_TAG = 'FirestoreClient';
 
@@ -135,13 +137,14 @@ export class FirestoreClient {
    * fallback succeeds we signal success to the async queue even though the
    * start() itself signals failure.
    *
-   * @param usePersistence Whether or not to attempt to enable persistence.
+   * @param persistenceSettings Settings object to configure offline
+   *     persistence.
    * @returns A deferred result indicating the user-visible result of enabling
    *     offline persistence. This method will reject this if IndexedDB fails to
    *     start for any reason. If usePersistence is false this is
    *     unconditionally resolved.
    */
-  start(usePersistence: boolean): Promise<void> {
+  start(persistenceSettings: PersistenceSettings): Promise<void> {
     // We defer our initialization until we get the current user from
     // setUserChangeListener(). We block the async queue until we got the
     // initial user and the initialization is completed. This will prevent
@@ -164,7 +167,7 @@ export class FirestoreClient {
       if (!initialized) {
         initialized = true;
 
-        this.initializePersistence(usePersistence, persistenceResult, user)
+        this.initializePersistence(persistenceSettings, persistenceResult, user)
           .then(() => this.initializeRest(user))
           .then(initializationDone.resolve, initializationDone.reject);
       } else {
@@ -200,7 +203,7 @@ export class FirestoreClient {
    * platform can't possibly support our implementation then this method rejects
    * the persistenceResult and falls back on memory-only persistence.
    *
-   * @param usePersistence indicates whether or not to use offline persistence
+   * @param persistenceSettings Settings object to configure offline persistence
    * @param persistenceResult A deferred result indicating the user-visible
    *     result of enabling offline persistence. This method will reject this if
    *     IndexedDB fails to start for any reason. If usePersistence is false
@@ -210,12 +213,12 @@ export class FirestoreClient {
    *     succeeded.
    */
   private initializePersistence(
-    usePersistence: boolean,
+    persistenceSettings: PersistenceSettings,
     persistenceResult: Deferred<void>,
     user: User
   ): Promise<void> {
-    if (usePersistence) {
-      return this.startIndexedDbPersistence(user)
+    if (persistenceSettings.enabled) {
+      return this.startIndexedDbPersistence(user, persistenceSettings)
         .then(persistenceResult.resolve)
         .catch(error => {
           // Regardless of whether or not the retry succeeds, from an user
@@ -278,7 +281,15 @@ export class FirestoreClient {
    *
    * @returns A promise indicating success or failure.
    */
-  private startIndexedDbPersistence(user: User): Promise<void> {
+  private startIndexedDbPersistence(
+    user: User,
+    settings: PersistenceSettings
+  ): Promise<void> {
+    assert(
+      settings.enabled,
+      'Should only start IndexedDb persitence with offline persistence enabled.'
+    );
+
     // TODO(http://b/33384523): For now we just disable garbage collection
     // when persistence is enabled.
     this.garbageCollector = new NoOpGarbageCollector();
@@ -291,32 +302,35 @@ export class FirestoreClient {
     });
 
     return Promise.resolve().then(() => {
-      this.persistence = new IndexedDbPersistence(
+      const persistence: IndexedDbPersistence = new IndexedDbPersistence(
         storagePrefix,
         this.clientId,
         this.platform,
         this.asyncQueue,
         serializer
       );
-      if (WebStorageSharedClientState.isAvailable(this.platform)) {
-        this.sharedClientState = new WebStorageSharedClientState(
-          this.asyncQueue,
-          this.platform,
-          storagePrefix,
-          this.clientId,
-          user
+      this.persistence = persistence;
+
+      if (
+        settings.synchronizeTabs &&
+        !WebStorageSharedClientState.isAvailable(this.platform)
+      ) {
+        throw new FirestoreError(
+          Code.UNIMPLEMENTED,
+          'IndexedDB persistence is only available on platforms that support LocalStorage.'
         );
-      } else {
-        if (process.env.USE_MOCK_PERSISTENCE !== 'YES') {
-          throw new FirestoreError(
-            Code.UNIMPLEMENTED,
-            'IndexedDB persistence is only available on platforms that support LocalStorage.'
-          );
-        }
-        debug(LOG_TAG, 'Starting Persistence in test-only non multi-tab mode');
-        this.sharedClientState = new MemorySharedClientState();
       }
-      return this.persistence.start();
+
+      this.sharedClientState = settings.synchronizeTabs
+        ? new WebStorageSharedClientState(
+            this.asyncQueue,
+            this.platform,
+            storagePrefix,
+            this.clientId,
+            user
+          )
+        : new MemorySharedClientState();
+      return persistence.start(settings.synchronizeTabs);
     });
   }
 
@@ -420,11 +434,11 @@ export class FirestoreClient {
     return this.asyncQueue.enqueue(async () => {
       // PORTING NOTE: LocalStore does not need an explicit shutdown on web.
       await this.syncEngine.shutdown();
-      await this.remoteStore.shutdown();
       await this.sharedClientState.shutdown();
       await this.persistence.shutdown(
         options && options.purgePersistenceWithDataLoss
       );
+      await this.remoteStore.shutdown();
 
       // `removeUserChangeListener` must be called after shutting down the
       // RemoteStore as it will prevent the RemoteStore from retrieving