Memory LRU GC

common/api-review/firestore.api.md

@@ -163,6 +163,9 @@ export { EmulatorMockTokenOptions }
 // @public
 export function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;
 
+// @public
+export function enableMemoryLRUGarbageCollection(firestore: Firestore): Promise<void>;
+
 // @public
 export function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;
 

packages/firestore/src/api.ts

@@ -36,6 +36,7 @@ export {
   initializeFirestore,
   getFirestore,
   enableIndexedDbPersistence,
+  enableMemoryLRUGarbageCollection,
   enableMultiTabIndexedDbPersistence,
   clearIndexedDbPersistence,
   waitForPendingWrites,

packages/firestore/src/api/database.ts

@@ -26,6 +26,7 @@ import { deepEqual, getDefaultEmulatorHostnameAndPort } from '@firebase/util';
 import { User } from '../auth/user';
 import {
   IndexedDbOfflineComponentProvider,
+  LruGcMemoryOfflineComponentProvider,
   MultiTabOfflineComponentProvider,
   OfflineComponentProvider,
   OnlineComponentProvider
@@ -285,6 +286,43 @@ export function configureFirestore(firestore: Firestore): void {
   );
 }
 
+/**
+ * Attempts to enable LRU garbage collection for memory persistence.
+ *
+ * Must be called before any other functions (other than
+ * {@link initializeFirestore}, {@link (getFirestore:1)} or
+ * {@link clearIndexedDbPersistence}.
+ *
+ * By default, any documents that are not part of an active query result or
+ * with no mutation attached to them are removed from memory immediately.
+ *
+ * This function changes the default behavior, to enable a least-recent-used
+ * garbage collector. Documents will be collected when their total size exceeds
+ * `Settings.cacheSizeBytes`, with least recently used documents get removed first.
+ *
+ * @param firestore - The {@link Firestore} instance to enable LRU garbage collection for.
+ * @returns A `Promise` that represents successfully enabling LRU garbage collection.
+ */
+export function enableMemoryLRUGarbageCollection(
+  firestore: Firestore
+): Promise<void> {
+  firestore = cast(firestore, Firestore);
+  verifyNotInitialized(firestore);
+
+  const client = ensureFirestoreConfigured(firestore);
+  const settings = firestore._freezeSettings();
+
+  const onlineComponentProvider = new OnlineComponentProvider();
+  const offlineComponentProvider = new LruGcMemoryOfflineComponentProvider(
+    settings.cacheSizeBytes
+  );
+  return setPersistenceProviders(
+    client,
+    onlineComponentProvider,
+    offlineComponentProvider
+  );
+}
+
 /**
  * Attempts to enable persistent storage, if possible.
  *

packages/firestore/src/core/component_provider.ts

@@ -31,6 +31,7 @@ import { LruParams } from '../local/lru_garbage_collector';
 import { LruScheduler } from '../local/lru_garbage_collector_impl';
 import {
   MemoryEagerDelegate,
+  MemoryLruDelegate,
   MemoryPersistence
 } from '../local/memory_persistence';
 import { Scheduler, Persistence } from '../local/persistence';
@@ -53,6 +54,7 @@ import {
   remoteStoreShutdown
 } from '../remote/remote_store';
 import { JsonProtoSerializer } from '../remote/serializer';
+import { hardAssert } from '../util/assert';
 import { AsyncQueue } from '../util/async_queue';
 import { Code, FirestoreError } from '../util/error';
 
@@ -172,6 +174,37 @@ export class MemoryOfflineComponentProvider
   }
 }
 
+export class LruGcMemoryOfflineComponentProvider extends MemoryOfflineComponentProvider {
+  constructor(protected readonly cacheSizeBytes: number | undefined) {
+    super();
+  }
+
+  createGarbageCollectionScheduler(
+    cfg: ComponentConfiguration,
+    localStore: LocalStore
+  ): Scheduler | null {
+    hardAssert(
+      this.persistence.referenceDelegate instanceof MemoryLruDelegate,
+      'referenceDelegate is expected to be an instance of MemoryLruDelegate.'
+    );
+
+    const garbageCollector =
+      this.persistence.referenceDelegate.garbageCollector;
+    return new LruScheduler(garbageCollector, cfg.asyncQueue, localStore);
+  }
+
+  createPersistence(cfg: ComponentConfiguration): Persistence {
+    const lruParams =
+      this.cacheSizeBytes !== undefined
+        ? LruParams.withCacheSize(this.cacheSizeBytes)
+        : LruParams.DEFAULT;
+    return new MemoryPersistence(
+      p => MemoryLruDelegate.factory(p, lruParams),
+      this.serializer
+    );
+  }
+}
+
 /**
  * Provides all components needed for Firestore with IndexedDB persistence.
  */

packages/firestore/src/local/lru_garbage_collector_impl.ts

@@ -176,7 +176,9 @@ export class LruScheduler implements Scheduler {
   }
 }
 
-/** Implements the steps for LRU garbage collection. */
+/**
+ * Implements the steps for LRU garbage collection.
+ */
 class LruGarbageCollectorImpl implements LruGarbageCollector {
   constructor(
     private readonly delegate: LruDelegate,

packages/firestore/src/local/memory_persistence.ts

@@ -353,6 +353,13 @@ export class MemoryLruDelegate implements ReferenceDelegate, LruDelegate {
     this.garbageCollector = newLruGarbageCollector(this, lruParams);
   }
 
+  static factory(
+    persistence: MemoryPersistence,
+    lruParams: LruParams | null
+  ): MemoryLruDelegate {
+    return new MemoryLruDelegate(persistence, lruParams!!);
+  }
+
   // No-ops, present so memory persistence doesn't have to care which delegate
   // it has.
   onTransactionStarted(): void {}

packages/firestore/test/integration/api/database.test.ts

@@ -67,13 +67,15 @@ import {
 } from '../util/firebase_export';
 import {
   apiDescribe,
+  withEnsuredLruGcTestDb,
   withTestCollection,
   withTestDbsSettings,
   withTestDb,
   withTestDbs,
   withTestDoc,
   withTestDocAndInitialData,
-  withNamedTestDbsOrSkipUnlessUsingEmulator
+  withNamedTestDbsOrSkipUnlessUsingEmulator,
+  withEnsuredEagerGcTestDb
 } from '../util/helpers';
 import { DEFAULT_SETTINGS, DEFAULT_PROJECT_ID } from '../util/settings';
 
@@ -1751,4 +1753,26 @@ apiDescribe('Database', (persistence: boolean) => {
       }
     );
   });
+
+  it('Cannot get document from cache with eager GC enabled.', () => {
+    const initialData = { key: 'value' };
+    return withEnsuredEagerGcTestDb(async db => {
+      const docRef = doc(collection(db, 'test-collection'));
+      await setDoc(docRef, initialData);
+      await expect(getDocFromCache(docRef)).to.be.rejectedWith('Failed to get');
+    });
+  });
+
+  it('Can get document from cache with Lru GC enabled.', () => {
+    const initialData = { key: 'value' };
+    return withEnsuredLruGcTestDb(persistence, async db => {
+      const docRef = doc(collection(db, 'test-collection'));
+      await setDoc(docRef, initialData);
+      return getDocFromCache(docRef).then(doc => {
+        expect(doc.exists()).to.be.true;
+        expect(doc.metadata.fromCache).to.be.true;
+        expect(doc.data()).to.deep.equal(initialData);
+      });
+    });
+  });
 });

packages/firestore/test/integration/api/get_options.test.ts

@@ -18,6 +18,7 @@
 import { expect } from 'chai';
 
 import {
+  collection,
   deleteDoc,
   disableNetwork,
   doc,
@@ -34,7 +35,8 @@ import {
   toDataMap,
   apiDescribe,
   withTestCollection,
-  withTestDocAndInitialData
+  withTestDocAndInitialData,
+  withEnsuredLruGcTestDb
 } from '../util/helpers';
 
 apiDescribe('GetOptions', (persistence: boolean) => {
@@ -68,10 +70,10 @@ apiDescribe('GetOptions', (persistence: boolean) => {
 
   it('get document while offline with default get options', () => {
     const initialData = { key: 'value' };
-    return withTestDocAndInitialData(persistence, initialData, (docRef, db) => {
-      // Register a snapshot to force the data to stay in the cache and not be
-      // garbage collected.
-      onSnapshot(docRef, () => {});
+    // Use an instance with Gc turned on.
+    return withEnsuredLruGcTestDb(persistence, async db => {
+      const docRef = doc(collection(db, 'test-collection'));
+      await setDoc(docRef, initialData);
       return getDoc(docRef)
         .then(() => disableNetwork(db))
         .then(() => getDoc(docRef))

packages/firestore/test/integration/util/helpers.ts

@@ -32,7 +32,8 @@ import {
   PrivateSettings,
   SnapshotListenOptions,
   newTestFirestore,
-  newTestApp
+  newTestApp,
+  enableMemoryLRUGarbageCollection
 } from './firebase_export';
 import {
   ALT_PROJECT_ID,
@@ -141,6 +142,38 @@ export function withTestDb(
   });
 }
 
+export function withEnsuredEagerGcTestDb(
+  fn: (db: Firestore) => Promise<void>
+): Promise<void> {
+  return withTestDbsSettings(
+    false,
+    DEFAULT_PROJECT_ID,
+    { ...DEFAULT_SETTINGS, cacheSizeBytes: 1 * 1024 * 1024 },
+    1,
+    async ([db]) => {
+      return fn(db);
+    }
+  );
+}
+
+export function withEnsuredLruGcTestDb(
+  persistence: boolean,
+  fn: (db: Firestore) => Promise<void>
+): Promise<void> {
+  return withTestDbsSettings(
+    persistence,
+    DEFAULT_PROJECT_ID,
+    { ...DEFAULT_SETTINGS, cacheSizeBytes: 1 * 1024 * 1024 },
+    1,
+    async ([db]) => {
+      if (!persistence) {
+        await enableMemoryLRUGarbageCollection(db);
+      }
+      return fn(db);
+    }
+  );
+}
+
 /** Runs provided fn with a db for an alternate project id. */
 export function withAlternateTestDb(
   persistence: boolean,

packages/firestore/test/unit/specs/bundle_spec.test.ts

@@ -178,7 +178,7 @@ describeSpec('Bundles:', ['no-ios'], () => {
         spec()
           // TODO(b/160878667): Figure out what happens when memory eager GC is on
           // a bundle is loaded.
-          .withGCEnabled(false)
+          .ensureManualLruGC()
           .userListens(query1)
           .watchAcksFull(query1, 250, docA)
           .expectEvents(query1, {
@@ -224,7 +224,7 @@ describeSpec('Bundles:', ['no-ios'], () => {
 
       return (
         spec()
-          .withGCEnabled(false)
+          .ensureManualLruGC()
           .userListens(query1)
           .watchAcksFull(query1, 250, docA)
           .expectEvents(query1, {
@@ -260,7 +260,7 @@ describeSpec('Bundles:', ['no-ios'], () => {
 
     return (
       spec()
-        .withGCEnabled(false)
+        .ensureManualLruGC()
         .userListens(query1)
         .watchAcksFull(query1, 250)
         // Backend tells is there is no such doc.

packages/firestore/test/unit/specs/existence_filter_spec.test.ts

@@ -69,7 +69,7 @@ describeSpec('Existence Filters:', [], () => {
     const doc1 = doc('collection/1', 2000, { v: 2 });
     return (
       spec()
-        .withGCEnabled(false)
+        .ensureManualLruGC()
         .userListens(query1)
         .watchAcksFull(query1, 1000, doc1)
         .expectEvents(query1, { added: [doc1] })