Add spec tests for LRU GC

Author: wu-hui

packages/firestore/src/api.ts

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

packages/firestore/src/api/database.ts

@@ -324,27 +324,27 @@ export function enableMemoryLRUGarbageCollection(
 }
 
 /**
- * Attempts to enable persistent storage, if possible. //
- *				//
- * Must be called before any other functions (other than //
- * {@link initializeFirestore}, {@link (getFirestore:1)} or //
- * {@link clearIndexedDbPersistence}. //
- *				//
- * If this fails, `enableIndexedDbPersistence()` will reject the promise it //
- * returns. Note that even after this failure, the {@link Firestore} instance will //
- * remain usable, however offline persistence will be disabled. //
- *				//
- * There are several reasons why this can fail, which can be identified by //
- * the `code` on the error.	//
- *				//
- *   * failed-precondition: The app is already open in another browser tab. //
- *   * unimplemented: The browser is incompatible with the offline //
- *     persistence implementation. //
- *				//
- * @param firestore - The {@link Firestore} instance to enable persistence for. //
- * @param persistenceSettings - Optional settings object to configure //
- * persistence.			//
- * @returns A `Promise` that represents successfully enabling persistent storage. //
+ * Attempts to enable persistent storage, if possible.
+ *
+ * Must be called before any other functions (other than
+ * {@link initializeFirestore}, {@link (getFirestore:1)} or
+ * {@link clearIndexedDbPersistence}.
+ *
+ * If this fails, `enableIndexedDbPersistence()` will reject the promise it
+ * returns. Note that even after this failure, the {@link Firestore} instance will
+ * remain usable, however offline persistence will be disabled.
+ *
+ * There are several reasons why this can fail, which can be identified by
+ * the `code` on the error.
+ *
+ *   * failed-precondition: The app is already open in another browser tab.
+ *   * unimplemented: The browser is incompatible with the offline
+ *     persistence implementation.
+ *
+ * @param firestore - The {@link Firestore} instance to enable persistence for.
+ * @param persistenceSettings - Optional settings object to configure
+ * persistence.
+ * @returns A `Promise` that represents successfully enabling persistent storage.
  */
 export function enableIndexedDbPersistence(
   firestore: Firestore,

packages/firestore/src/core/component_provider.ts

@@ -54,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';
 
@@ -73,7 +74,6 @@ import {
   syncEngineSynchronizeWithChangedDocuments
 } from './sync_engine_impl';
 import { OnlineStateSource } from './types';
-import { hardAssert } from '../util/assert';
 
 export interface ComponentConfiguration {
   asyncQueue: AsyncQueue;

packages/firestore/src/local/lru_garbage_collector_impl.ts

@@ -176,8 +176,10 @@ export class LruScheduler implements Scheduler {
   }
 }
 
-/** Implements the steps for LRU garbage collection. */
-class LruGarbageCollectorImpl implements LruGarbageCollector {
+/**
+ * Implements the steps for LRU garbage collection. Exported for testing purpose only.
+ */
+export class LruGarbageCollectorImpl implements LruGarbageCollector {
   constructor(
     private readonly delegate: LruDelegate,
     readonly params: LruParams

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

@@ -20,6 +20,7 @@ import { Deferred } from '@firebase/util';
 import { expect, use } from 'chai';
 import chaiAsPromised from 'chai-as-promised';
 
+import { LRU_MINIMUM_CACHE_SIZE_BYTES } from '../../../src/local/lru_garbage_collector_impl';
 import { EventsAccumulator } from '../util/events_accumulator';
 import {
   addDoc,
@@ -67,6 +68,7 @@ import {
 } from '../util/firebase_export';
 import {
   apiDescribe,
+  withEnsuredGcTestDb,
   withTestCollection,
   withTestDbsSettings,
   withTestDb,
@@ -1751,4 +1753,22 @@ apiDescribe('Database', (persistence: boolean) => {
       }
     );
   });
+
+  it('Can get document from cache with GC enabled.', () => {
+    const initialData = { key: 'value' };
+    return withEnsuredGcTestDb(
+      persistence,
+      LRU_MINIMUM_CACHE_SIZE_BYTES,
+      async db => {
+        const docRef = doc(collection(db, 'test-collection'));
+        await setDoc(docRef, initialData);
+        return getDoc(docRef).then(doc => {
+          expect(doc.exists()).to.be.true;
+          expect(doc.metadata.fromCache).to.be.false;
+          expect(doc.metadata.hasPendingWrites).to.be.false;
+          expect(doc.data()).to.deep.equal(initialData);
+        });
+      }
+    );
+  });
 });

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

@@ -16,8 +16,10 @@
  */
 
 import { expect } from 'chai';
+import { LRU_MINIMUM_CACHE_SIZE_BYTES } from '../../../src/local/lru_garbage_collector_impl';
 
 import {
+  collection,
   deleteDoc,
   disableNetwork,
   doc,
@@ -34,7 +36,8 @@ import {
   toDataMap,
   apiDescribe,
   withTestCollection,
-  withTestDocAndInitialData
+  withTestDocAndInitialData,
+  withEnsuredGcTestDb
 } from '../util/helpers';
 
 apiDescribe('GetOptions', (persistence: boolean) => {
@@ -68,20 +71,24 @@ 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, () => {});
-      return getDoc(docRef)
-        .then(() => disableNetwork(db))
-        .then(() => getDoc(docRef))
-        .then(doc => {
-          expect(doc.exists()).to.be.true;
-          expect(doc.metadata.fromCache).to.be.true;
-          expect(doc.metadata.hasPendingWrites).to.be.false;
-          expect(doc.data()).to.deep.equal(initialData);
-        });
-    });
+    // Use an instance with Gc turned on.
+    return withEnsuredGcTestDb(
+      persistence,
+      LRU_MINIMUM_CACHE_SIZE_BYTES,
+      async db => {
+        const docRef = doc(collection(db, 'test-collection'));
+        await setDoc(docRef, initialData);
+        return getDoc(docRef)
+          .then(() => disableNetwork(db))
+          .then(() => getDoc(docRef))
+          .then(doc => {
+            expect(doc.exists()).to.be.true;
+            expect(doc.metadata.fromCache).to.be.true;
+            expect(doc.metadata.hasPendingWrites).to.be.false;
+            expect(doc.data()).to.deep.equal(initialData);
+          });
+      }
+    );
   });
 
   it('get collection while offline with default get options', () => {

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,25 @@ export function withTestDb(
   });
 }
 
+export function withEnsuredGcTestDb(
+  persistence: boolean,
+  sizeBytes: number,
+  fn: (db: Firestore) => Promise<void>
+): Promise<void> {
+  return withTestDbsSettings(
+    persistence,
+    DEFAULT_PROJECT_ID,
+    { ...DEFAULT_SETTINGS, cacheSizeBytes: sizeBytes },
+    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)
+          .withEagerGCForMemoryPersistence(false)
           .userListens(query1)
           .watchAcksFull(query1, 250, docA)
           .expectEvents(query1, {
@@ -224,7 +224,7 @@ describeSpec('Bundles:', ['no-ios'], () => {
 
       return (
         spec()
-          .withGCEnabled(false)
+          .withEagerGCForMemoryPersistence(false)
           .userListens(query1)
           .watchAcksFull(query1, 250, docA)
           .expectEvents(query1, {
@@ -260,7 +260,7 @@ describeSpec('Bundles:', ['no-ios'], () => {
 
     return (
       spec()
-        .withGCEnabled(false)
+        .withEagerGCForMemoryPersistence(false)
         .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)
+        .withEagerGCForMemoryPersistence(false)
         .userListens(query1)
         .watchAcksFull(query1, 1000, doc1)
         .expectEvents(query1, { added: [doc1] })

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

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ *
+ * 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.
+ */
+
+import { setLogLevel } from '@firebase/logger';
+import { doc, filter, query } from '../../util/helpers';
+
+import { describeSpec, specTest } from './describe_spec';
+import { spec } from './spec_builder';
+
+describeSpec('Garbage Collection:', [], () => {
+  specTest(
+    'Contents of query are cleared when listen is removed.',
+    ['eager-gc'],
+    'Explicitly tests eager GC behavior',
+    () => {
+      const query1 = query('collection');
+      const docA = doc('collection/a', 1000, { key: 'a' });
+      return (
+        spec()
+          .userListens(query1)
+          .watchAcksFull(query1, 1000, docA)
+          .expectEvents(query1, { added: [docA] })
+          .userUnlistens(query1)
+          // should get no events.
+          .userListens(query1)
+      );
+    }
+  );
+
+  specTest('Contents of query are kept after listen is removed.', [], () => {
+    const query1 = query('collection');
+    const docA = doc('collection/a', 1000, { key: 'a' });
+    return spec()
+      .withEagerGCForMemoryPersistence(false)
+      .userListens(query1)
+      .watchAcksFull(query1, 1000, docA)
+      .expectEvents(query1, { added: [docA] })
+      .userUnlistens(query1)
+      .userListens(query1)
+      .expectListen(query1, { resumeToken: 'resume-token-1000' })
+      .expectEvents(query1, { added: [docA], fromCache: true });
+  });
+
+  specTest(
+    'Contents of query are kept after listen is removed, and GC threshold is not reached',
+    [],
+    () => {
+      const query1 = query('collection');
+      const docA = doc('collection/a', 1000, { key: 'a' });
+      return spec()
+        .withEagerGCForMemoryPersistence(false)
+        .userListens(query1)
+        .watchAcksFull(query1, 1000, docA)
+        .expectEvents(query1, { added: [docA] })
+        .userUnlistens(query1)
+        .triggerLruGC(1000)
+        .userListens(query1)
+        .expectListen(query1, { resumeToken: 'resume-token-1000' })
+        .expectEvents(query1, { added: [docA], fromCache: true });
+    }
+  );
+
+  specTest(
+    'Contents of query are kept after listen is removed, and GC threshold is reached',
+    [],
+    () => {
+      const query1 = query('collection');
+      const docA = doc('collection/a', 1000, { key: 'a' });
+      return (
+        spec()
+          .withEagerGCForMemoryPersistence(false)
+          .userListens(query1)
+          .watchAcksFull(query1, 1000, docA)
+          .expectEvents(query1, { added: [docA] })
+          .userUnlistens(query1)
+          .triggerLruGC(1)
+          .removeExpectedTargetMapping(query1)
+          // should get no events.
+          .userListens(query1)
+      );
+    }
+  );
+
+  specTest(
+    'Contents of active query are kept while inactive results are removed after GC',
+    [],
+    () => {
+      const queryFull = query('collection');
+      const queryA = query('collection', filter('key', '==', 'a'));
+      const docA = doc('collection/a', 1000, { key: 'a' });
+      const docB = doc('collection/b', 1000, { key: 'b' });
+      const docC = doc('collection/c', 1000, { key: 'c' });
+      const docCMutated = doc('collection/c', 1000, {
+        key: 'c',
+        extra: 'extra'
+      }).setHasLocalMutations();
+      const docD = doc('collection/d', 1000, { key: 'd' });
+      return (
+        spec()
+          .withEagerGCForMemoryPersistence(false)
+          .userListens(queryFull)
+          .watchAcksFull(queryFull, 1000, docA, docB, docC, docD)
+          .expectEvents(queryFull, { added: [docA, docB, docC, docD] })
+          .userUnlistens(queryFull)
+          .userListens(queryA)
+          .expectEvents(queryA, { added: [docA], fromCache: true })
+          .watchAcksFull(queryA, 1500, docA)
+          .expectEvents(queryA, { fromCache: false })
+          .userSets('collection/c', { key: 'c', extra: 'extra' })
+          .triggerLruGC(1)
+          .removeExpectedTargetMapping(queryFull)
+          .userUnlistens(queryA)
+          // should get no events.
+          .userListens(queryFull)
+          .expectEvents(queryFull, {
+            added: [docA, docCMutated],
+            hasPendingWrites: true,
+            fromCache: true
+          })
+      );
+    }
+  );
+});