feat(firestore): 16MB docs support

WIP

Adds support for 16MB docs in Firestore.

Changes:
- Increases the gRPC message receive size limit from 4MB to 17MB (16MB
  doc + overhead).
- Implements a workaround for the `CursorWindow` 2MB row read limit for
  reading large docs from local storage. If a row's content is larger
  than 1MB, executes a seperate query that reads the content in chunks
  using `SUBSTR` with a chunk size smaller than the row read limit. This
  is a slow operation for 16MB docs, taking ~200ms in my testing on
  the local emulator.
- Debug logs are now truncated if they exceed 128KB. Formatting proto
  responses with large documents to strings consumed a huge amount of
  memory. In one extreme case, formatting a response containing a doc
  with a field containing 16MB of emojis caused an OOM on emulators.
- Adds tests explicitly for large documents.

Author: dlarocque

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/LargeDocumentTest.java

@@ -0,0 +1,220 @@
+// Copyright 2026 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.
+
+package com.google.firebase.firestore;
+
+import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testFirestore;
+import static com.google.firebase.firestore.testutil.IntegrationTestUtil.waitFor;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+import com.google.android.gms.tasks.Task;
+import java.util.Arrays;
+import org.junit.After;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+@RunWith(AndroidJUnit4.class)
+public class LargeDocumentTest {
+
+  // These tests require a pre-seeded database containing specific large documents.
+  private static final String SEED_COLLECTION = "serverSdkTests";
+  private static final String DOC_15_9MB_UNICODE = "doc_15_9MB_unicode";
+  private static final String COL_LARGE_DOCS = "col_large_docs";
+
+  // Extended timeout required for large document tests due to gRPC flow control
+  // window defaults (64KB), which result in longer read times over the network.
+  private static final int TIMEOUT_MS = 60000;
+
+  @After
+  public void tearDown() {
+    com.google.firebase.firestore.testutil.IntegrationTestUtil.tearDown();
+  }
+
+  private String generateString(int sizeInBytes) {
+    char[] chars = new char[sizeInBytes];
+    Arrays.fill(chars, 'a');
+    return new String(chars);
+  }
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testReadAndCacheLargeUnicodeDocument() {
+    FirebaseFirestore db = testFirestore();
+    DocumentReference docRef = db.collection(SEED_COLLECTION).document(DOC_15_9MB_UNICODE);
+
+    DocumentSnapshot serverSnapshot = waitFor(docRef.get(Source.SERVER));
+    assertTrue(serverSnapshot.exists());
+
+    waitFor(db.disableNetwork());
+
+    DocumentSnapshot cacheSnapshot = waitFor(docRef.get(Source.CACHE));
+    assertTrue(cacheSnapshot.exists());
+
+    assertEquals(serverSnapshot.getData(), cacheSnapshot.getData());
+
+    waitFor(db.enableNetwork());
+  }
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testCacheIntegrityWithMultipleLargeDocuments() {
+    FirebaseFirestore db = testFirestore();
+
+    // Copy existing test environment settings but set a normal cache size
+    // to ensure we don't accidentally trigger async GC during the test.
+    FirebaseFirestoreSettings existingSettings = db.getFirestoreSettings();
+    FirebaseFirestoreSettings settings =
+        new FirebaseFirestoreSettings.Builder(existingSettings)
+            .setLocalCacheSettings(
+                PersistentCacheSettings.newBuilder().setSizeBytes(104857600).build()) // 100MB
+            .build();
+    db.setFirestoreSettings(settings);
+
+    CollectionReference colRef = db.collection(COL_LARGE_DOCS);
+    DocumentReference docA = colRef.document("doc_a");
+    DocumentReference docB = colRef.document("doc_b");
+
+    waitFor(docA.get(Source.SERVER));
+    waitFor(docB.get(Source.SERVER));
+
+    waitFor(db.disableNetwork());
+
+    DocumentSnapshot cacheSnapshotA = waitFor(docA.get(Source.CACHE));
+    DocumentSnapshot cacheSnapshotB = waitFor(docB.get(Source.CACHE));
+
+    assertTrue("docA should exist in cache", cacheSnapshotA.exists());
+    assertTrue("docB should exist in cache", cacheSnapshotB.exists());
+
+    // Sanity check
+    assertTrue(cacheSnapshotA.getData().size() > 0);
+    assertTrue(cacheSnapshotB.getData().size() > 0);
+
+    waitFor(db.enableNetwork());
+  }
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testWatchStreamInitializationAndDiff() throws Exception {
+    FirebaseFirestore db = testFirestore();
+    DocumentReference docRef = db.collection(SEED_COLLECTION).document(DOC_15_9MB_UNICODE);
+
+    // Verify that the initial snapshot of a large document is received successfully
+    // without triggering stream cancellation loops.
+    Task<DocumentSnapshot> firstSnapshotTask = docRef.get(Source.SERVER);
+    DocumentSnapshot firstSnapshot = waitFor(firstSnapshotTask);
+    assertTrue(firstSnapshot.exists());
+
+    // TODO: Enable the differential update assertions below once client SDK write streams
+    // support the 16MB limit.
+    /*
+    Map<String, Object> updateData = new HashMap<>();
+    updateData.put("differential_field", "updated_value");
+    waitFor(docRef.update(updateData));
+
+    // Wait for the snapshot listener to fire a second time to verify stream continuity.
+    */
+  }
+
+  // TODO: Enable this test. Currently it times out after not receiving a response from the backend.
+  /*
+  @Test(timeout = TIMEOUT_MS)
+  public void testOversizedPayloadRejection() {
+    FirebaseFirestore db = testFirestore();
+    DocumentReference docRef = db.collection(SEED_COLLECTION).document("temp_oversized_doc");
+
+    Map<String, Object> data = new HashMap<>();
+    // 16.1MB payload
+    int oversizedPayloadBytes = (16 * 1024 * 1024) + 102400;
+    data.put("largeField", generateString(oversizedPayloadBytes));
+
+    try {
+      waitFor(docRef.set(data));
+      fail("Setting a document exceeding the maximum size limit should fail.");
+    } catch (Exception e) {
+      assertTrue(e.getCause() instanceof FirebaseFirestoreException);
+      FirebaseFirestoreException firestoreException = (FirebaseFirestoreException) e.getCause();
+
+      assertEquals(Code.INVALID_ARGUMENT, firestoreException.getCode());
+    }
+  }
+  */
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testTransactionReadModifyWrite() {
+    FirebaseFirestore db = testFirestore();
+    DocumentReference docRef = db.collection(SEED_COLLECTION).document(DOC_15_9MB_UNICODE);
+
+    Task<Void> transactionTask =
+        db.runTransaction(
+            transaction -> {
+              DocumentSnapshot snapshot = transaction.get(docRef);
+              assertTrue(snapshot.exists());
+
+              transaction.update(docRef, "transaction_timestamp", System.currentTimeMillis());
+              return null;
+            });
+
+    waitFor(transactionTask);
+  }
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testQueryLargeDocuments() {
+    FirebaseFirestore db = testFirestore();
+    CollectionReference colRef = db.collection(COL_LARGE_DOCS);
+
+    Query query = colRef.whereIn(FieldPath.documentId(), Arrays.asList("doc_a", "doc_b"));
+
+    QuerySnapshot serverSnapshot = waitFor(query.get(Source.SERVER));
+    assertEquals(
+        "Query should return exactly 2 large documents from server", 2, serverSnapshot.size());
+
+    waitFor(db.disableNetwork());
+
+    QuerySnapshot cacheSnapshot = waitFor(query.get(Source.CACHE));
+    assertEquals(
+        "Query should return exactly 2 large documents from cache", 2, cacheSnapshot.size());
+
+    assertEquals(
+        "Cached query payload should exactly match server query payload",
+        serverSnapshot.getDocuments().get(0).getData(),
+        cacheSnapshot.getDocuments().get(0).getData());
+
+    waitFor(db.enableNetwork());
+  }
+
+  @Test(timeout = TIMEOUT_MS)
+  public void testQueryLargeDocumentsForcesLocalScan() {
+    FirebaseFirestore db = testFirestore();
+    CollectionReference colRef = db.collection(COL_LARGE_DOCS);
+
+    waitFor(colRef.document("doc_a").get(Source.SERVER));
+    waitFor(colRef.document("doc_b").get(Source.SERVER));
+
+    waitFor(db.disableNetwork());
+
+    Query query = colRef.orderBy(FieldPath.documentId()).limit(2);
+
+    // Execute the query offline
+    QuerySnapshot cacheSnapshot = waitFor(query.get(Source.CACHE));
+
+    assertEquals(
+        "Query should find and return exactly 2 large documents from cache",
+        2,
+        cacheSnapshot.size());
+
+    assertTrue(
+        "Payload should not be empty", cacheSnapshot.getDocuments().get(0).getData().size() > 0);
+
+    waitFor(db.enableNetwork());
+  }
+}

firebase-firestore/src/main/java/com/google/firebase/firestore/local/SQLiteRemoteDocumentCache.java

@@ -54,6 +54,9 @@ final class SQLiteRemoteDocumentCache implements RemoteDocumentCache {
   /** The number of bind args per collection group in {@link #getAll(String, IndexOffset, int)} */
   @VisibleForTesting static final int BINDS_PER_STATEMENT = 9;
 
+  /** The safe limit for CursorWindow (1 MB). */
+  @VisibleForTesting static int SAFE_CURSOR_LIMIT = 1024 * 1024;
+
   private final SQLitePersistence db;
   private final LocalSerializer serializer;
   private IndexManager indexManager;
@@ -163,7 +166,12 @@ public Map<DocumentKey, MutableDocument> getAll(Iterable<DocumentKey> documentKe
     SQLitePersistence.LongQuery longQuery =
         new SQLitePersistence.LongQuery(
             db,
-            "SELECT contents, read_time_seconds, read_time_nanos, document_type, path "
+            "SELECT "
+                + "CASE WHEN LENGTH(contents) <= "
+                + SAFE_CURSOR_LIMIT
+                + " THEN contents ELSE NULL END, "
+                + "read_time_seconds, read_time_nanos, document_type, path, "
+                + "LENGTH(contents) "
                 + "FROM remote_documents "
                 + "WHERE path IN (",
             bindVars,
@@ -173,7 +181,21 @@ public Map<DocumentKey, MutableDocument> getAll(Iterable<DocumentKey> documentKe
     while (longQuery.hasMoreSubqueries()) {
       longQuery
           .performNextSubquery()
-          .forEach(row -> processRowInBackground(backgroundQueue, results, row, /*filter*/ null));
+          .forEach(
+              row -> {
+                // Attempt to get the payload (NULL if > 1MB)
+                byte[] payload = row.getBlob(0);
+
+                int blobLength = row.getInt(5);
+
+                if (payload == null && blobLength > 0) {
+                  // This is a massive document, fetch it in chunks.
+                  String path = row.getString(4);
+                  payload = fetchMassiveDocumentInChunks(db, path, blobLength, SAFE_CURSOR_LIMIT);
+                }
+
+                processRowInBackground(backgroundQueue, results, row, payload, /*filter*/ null);
+              });
     }
     backgroundQueue.drain();
 
@@ -186,6 +208,46 @@ public Map<DocumentKey, MutableDocument> getAll(Iterable<DocumentKey> documentKe
     }
   }
 
+  /** Fetches a large document in chunks using SQLite's SUBSTR to bypass CursorWindow limits. */
+  @VisibleForTesting
+  byte[] fetchMassiveDocumentInChunks(
+      SQLitePersistence db, String path, int totalLength, int chunkSize) {
+
+    byte[] fullPayload = new byte[totalLength];
+
+    int currentOffset = 1; // SQLite SUBSTR is 1-indexed for offsets
+    int destPos = 0;
+
+    while (currentOffset <= totalLength) {
+      byte[] chunk =
+          db.query("SELECT SUBSTR(contents, ?, ?) FROM remote_documents WHERE path = ?")
+              .binding(currentOffset, chunkSize, path)
+              .firstValue(row -> row.getBlob(0));
+
+      if (chunk != null && chunk.length > 0) {
+        System.arraycopy(chunk, 0, fullPayload, destPos, chunk.length);
+        destPos += chunk.length;
+        currentOffset += chunk.length;
+      } else {
+        throw new IllegalStateException(
+            "Failed to fetch chunk for massive document at path: " + path);
+      }
+    }
+
+    if (destPos != totalLength) {
+      throw new IllegalStateException(
+          "Failed to fetch all chunks for massive document at path: "
+              + path
+              + ". Expected "
+              + totalLength
+              + " bytes, but read "
+              + destPos
+              + " bytes.");
+    }
+
+    return fullPayload;
+  }
+
   @Override
   public Map<DocumentKey, MutableDocument> getAll(
       String collectionGroup, IndexOffset offset, int limit) {
@@ -230,7 +292,12 @@ private Map<DocumentKey, MutableDocument> getAll(
 
     StringBuilder sql =
         repeatSequence(
-            "SELECT contents, read_time_seconds, read_time_nanos, document_type, path "
+            "SELECT "
+                + "CASE WHEN LENGTH(contents) <= "
+                + SAFE_CURSOR_LIMIT
+                + " THEN contents ELSE NULL END, "
+                + "read_time_seconds, read_time_nanos, document_type, path, "
+                + "LENGTH(contents) "
                 + "FROM remote_documents "
                 + "WHERE path >= ? AND path < ? AND path_length = ? "
                 + (tryFilterDocumentType == null
@@ -270,7 +337,19 @@ private Map<DocumentKey, MutableDocument> getAll(
     int cnt =
         db.query(sql.toString())
             .binding(bindVars)
-            .forEach(row -> processRowInBackground(backgroundQueue, results, row, filter));
+            .forEach(
+                row -> {
+                  byte[] payload = row.getBlob(0);
+                  int blobLength = row.getInt(5);
+
+                  if (payload == null && blobLength > 0) {
+                    // Massive document detected, fetch it in chunks
+                    String path = row.getString(4);
+                    payload = fetchMassiveDocumentInChunks(db, path, blobLength, SAFE_CURSOR_LIMIT);
+                  }
+
+                  processRowInBackground(backgroundQueue, results, row, payload, filter);
+                });
     if (context != null) {
       context.incrementDocumentReadCount(cnt);
     }
@@ -298,8 +377,8 @@ private void processRowInBackground(
       BackgroundQueue backgroundQueue,
       Map<DocumentKey, MutableDocument> results,
       Cursor row,
+      byte[] rawDocument,
       @Nullable Function<MutableDocument, Boolean> filter) {
-    byte[] rawDocument = row.getBlob(0);
     int readTimeSeconds = row.getInt(1);
     int readTimeNanos = row.getInt(2);
     boolean documentTypeIsNull = row.isNull(3);