Wire together LRU garbage collection (#1392)

Wire together LRU garbage collection

Added a garbage collection process to on-disk persistence that
removes older documents. This is enabled by default, and the SDK will attempt
to periodically clean up older, unused documents once the on-disk cache passes
a threshold size (default: 40 MB).

Author: Greg Soltis

packages/firebase/index.d.ts

@@ -759,6 +759,13 @@ declare namespace firebase.firestore {
    */
   export type UpdateData = { [fieldPath: string]: any };
 
+  /**
+   * Constant used to indicate the LRU garbage collection should be disabled.
+   * Set this value as the `cacheSizeBytes` on the settings passed to the
+   * `Firestore` instance.
+   */
+  export const CACHE_SIZE_UNLIMITED: number;
+
   /** Settings used to configure a `Firestore` instance. */
   export interface Settings {
     /** The hostname to connect to. */
@@ -785,6 +792,17 @@ declare namespace firebase.firestore {
      * use Timestamp now and opt-in to this new behavior as soon as you can.
      */
     timestampsInSnapshots?: boolean;
+
+    /**
+     * An approximate cache size threshold for the on-disk data. If the cache grows beyond this
+     * size, Firestore will start removing data that hasn't been recently used. The size is not a
+     * guarantee that the cache will stay below that size, only that if the cache exceeds the given
+     * size, cleanup will be attempted.
+     *
+     * The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to
+     * CACHE_SIZE_UNLIMITED to disable garbage collection.
+     */
+    cacheSizeBytes?: number;
   }
 
   /**

packages/firestore-types/index.d.ts

@@ -29,6 +29,13 @@ export type DocumentData = { [field: string]: any };
  */
 export type UpdateData = { [fieldPath: string]: any };
 
+/**
+ * Constant used to indicate the LRU garbage collection should be disabled.
+ * Set this value as the `cacheSizeBytes` on the settings passed to the
+ * `Firestore` instance.
+ */
+export const CACHE_SIZE_UNLIMITED: number;
+
 /** Settings used to configure a `Firestore` instance. */
 export interface Settings {
   /** The hostname to connect to. */
@@ -55,6 +62,17 @@ export interface Settings {
    * use Timestamp now and opt-in to this new behavior as soon as you can.
    */
   timestampsInSnapshots?: boolean;
+
+  /**
+   * An approximate cache size threshold for the on-disk data. If the cache grows beyond this
+   * size, Firestore will start removing data that hasn't been recently used. The size is not a
+   * guarantee that the cache will stay below that size, only that if the cache exceeds the given
+   * size, cleanup will be attempted.
+   *
+   * The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to
+   * CACHE_SIZE_UNLIMITED to disable garbage collection.
+   */
+  cacheSizeBytes?: number;
 }
 
 /**

packages/firestore/src/api/database.ts

@@ -20,7 +20,12 @@ import { FirebaseApp } from '@firebase/app-types';
 import { FirebaseService } from '@firebase/app-types/private';
 import { DatabaseId, DatabaseInfo } from '../core/database_info';
 import { ListenOptions } from '../core/event_manager';
-import { FirestoreClient } from '../core/firestore_client';
+import {
+  FirestoreClient,
+  IndexedDbPersistenceSettings,
+  InternalPersistenceSettings,
+  MemoryPersistenceSettings
+} from '../core/firestore_client';
 import {
   Bound,
   Direction,
@@ -32,6 +37,7 @@ import {
 } from '../core/query';
 import { Transaction as InternalTransaction } from '../core/transaction';
 import { ChangeType, ViewSnapshot } from '../core/view_snapshot';
+import { LruParams } from '../local/lru_garbage_collector';
 import { Document, MaybeDocument, NoDocument } from '../model/document';
 import { DocumentKey } from '../model/document_key';
 import {
@@ -102,6 +108,13 @@ const DEFAULT_HOST = 'firestore.googleapis.com';
 const DEFAULT_SSL = true;
 const DEFAULT_TIMESTAMPS_IN_SNAPSHOTS = false;
 
+/**
+ * Constant used to indicate the LRU garbage collection should be disabled.
+ * Set this value as the `cacheSizeBytes` on the settings passed to the
+ * `Firestore` instance.
+ */
+export const CACHE_SIZE_UNLIMITED = LruParams.COLLECTION_DISABLED;
+
 // enablePersistence() defaults:
 const DEFAULT_SYNCHRONIZE_TABS = false;
 
@@ -127,12 +140,14 @@ export interface FirestoreDatabase {
  */
 class FirestoreSettings {
   /** The hostname to connect to. */
-  host: string;
+  readonly host: string;
 
   /** Whether to use SSL when connecting. */
-  ssl: boolean;
+  readonly ssl: boolean;
+
+  readonly timestampsInSnapshots: boolean;
 
-  timestampsInSnapshots: boolean;
+  readonly cacheSizeBytes: number;
 
   // Can be a google-auth-library or gapi client.
   // tslint:disable-next-line:no-any
@@ -159,7 +174,8 @@ class FirestoreSettings {
       'host',
       'ssl',
       'credentials',
-      'timestampsInSnapshots'
+      'timestampsInSnapshots',
+      'cacheSizeBytes'
     ]);
 
     validateNamedOptionalType(
@@ -180,14 +196,39 @@ class FirestoreSettings {
       settings.timestampsInSnapshots,
       DEFAULT_TIMESTAMPS_IN_SNAPSHOTS
     );
+
+    validateNamedOptionalType(
+      'settings',
+      'number',
+      'cacheSizeBytes',
+      settings.cacheSizeBytes
+    );
+    if (settings.cacheSizeBytes === undefined) {
+      this.cacheSizeBytes = LruParams.DEFAULT_CACHE_SIZE_BYTES;
+    } else {
+      if (
+        settings.cacheSizeBytes !== CACHE_SIZE_UNLIMITED &&
+        settings.cacheSizeBytes < LruParams.MINIMUM_CACHE_SIZE_BYTES
+      ) {
+        throw new FirestoreError(
+          Code.INVALID_ARGUMENT,
+          `cacheSizeBytes must be at least ${
+            LruParams.MINIMUM_CACHE_SIZE_BYTES
+          }`
+        );
+      } else {
+        this.cacheSizeBytes = settings.cacheSizeBytes;
+      }
+    }
   }
 
   isEqual(other: FirestoreSettings): boolean {
     return (
       this.host === other.host &&
       this.ssl === other.ssl &&
       this.timestampsInSnapshots === other.timestampsInSnapshots &&
-      this.credentials === other.credentials
+      this.credentials === other.credentials &&
+      this.cacheSizeBytes === other.cacheSizeBytes
     );
   }
 }
@@ -201,38 +242,6 @@ class FirestoreConfig {
   persistence: boolean;
 }
 
-/**
- * Encapsulates the settings that can be used to configure Firestore
- * persistence.
- */
-export class PersistenceSettings {
-  /** Whether to enable multi-tab synchronization. */
-  experimentalTabSynchronization: boolean;
-
-  constructor(
-    readonly enabled: boolean,
-    settings?: firestore.PersistenceSettings
-  ) {
-    assert(
-      enabled || !settings,
-      'Can only provide PersistenceSettings with persistence enabled'
-    );
-    settings = settings || {};
-    this.experimentalTabSynchronization = objUtils.defaulted(
-      settings.experimentalTabSynchronization,
-      DEFAULT_SYNCHRONIZE_TABS
-    );
-  }
-
-  isEqual(other: PersistenceSettings): boolean {
-    return (
-      this.enabled === other.enabled &&
-      this.experimentalTabSynchronization ===
-        other.experimentalTabSynchronization
-    );
-  }
-}
-
 /**
  * The root reference to the database.
  */
@@ -335,23 +344,29 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
           'any other methods on a Firestore object.'
       );
     }
-
     return this.configureClient(
-      new PersistenceSettings(/* enabled= */ true, settings)
+      new IndexedDbPersistenceSettings(
+        this._config.settings.cacheSizeBytes,
+        settings !== undefined &&
+          objUtils.defaulted(
+            settings.experimentalTabSynchronization,
+            DEFAULT_SYNCHRONIZE_TABS
+          )
+      )
     );
   }
 
   ensureClientConfigured(): FirestoreClient {
     if (!this._firestoreClient) {
       // Kick off starting the client but don't actually wait for it.
       // tslint:disable-next-line:no-floating-promises
-      this.configureClient(new PersistenceSettings(/* enabled= */ false));
+      this.configureClient(new MemoryPersistenceSettings());
     }
     return this._firestoreClient as FirestoreClient;
   }
 
   private configureClient(
-    persistenceSettings: PersistenceSettings
+    persistenceSettings: InternalPersistenceSettings
   ): Promise<void> {
     assert(
       !!this._config.settings.host,