Add list cache support

src/Database/Database.php

@@ -8353,10 +8353,29 @@ public function purgeCachedCollection(string $collectionId): bool
         }
 
         $this->cache->purge($collectionKey);
+        $this->purgeCachedFindCollection($collectionId);
 
         return true;
     }
 
+    public function purgeCachedFindCollection(string $collectionId): bool
+    {
+        [$findKey] = $this->getFindCacheKeys($collectionId);
+
+        return $this->cache->purge($findKey);
+    }
+
+    /**
+     * @param array<Query> $queries
+     */
+    public function purgeCachedFind(string $collectionId, ?string $key = null, array $queries = [], string $forPermission = Database::PERMISSION_READ): bool
+    {
+        $collection = $this->silent(fn () => $this->getCollection($collectionId));
+        [$findKey, $findField] = $this->getFindCacheKeys($collectionId, $queries, $key, $forPermission, $collection);
+
+        return $this->cache->purge($findKey, $findField);
+    }
+
     /**
      * Cleans a specific document from cache
      * And related document reference in the collection cache.
@@ -8564,6 +8583,70 @@ public function find(string $collection, array $queries = [], string $forPermiss
         return $results;
     }
 
+    /**
+     * Find documents using an explicit TTL-backed cache.
+     *
+     * Results may be stale until the TTL expires or the caller purges the cached
+     * find entry. Use this only for read paths that can tolerate bounded
+     * staleness.
+     *
+     * @param string $collection
+     * @param array<Query> $queries
+     * @param int $ttl
+     * @param string|null $key Optional caller-owned cache variation key
+     * @param string $forPermission
+     * @return array<Document>
+     * @throws DatabaseException
+     * @throws QueryException
+     * @throws TimeoutException
+     * @throws Exception
+     */
+    public function findCached(string $collection, array $queries = [], int $ttl = self::TTL, ?string $key = null, string $forPermission = Database::PERMISSION_READ): array
+    {
+        if ($ttl <= 0) {
+            return $this->find($collection, $queries, $forPermission);
+        }
+
+        $collectionDocument = $this->silent(fn () => $this->getCollection($collection));
+
+        if ($collectionDocument->isEmpty()) {
+            throw new NotFoundException('Collection not found');
+        }
+
+        [$findKey, $findField] = $this->getFindCacheKeys($collectionDocument->getId(), $queries, $key, $forPermission, $collectionDocument);
+
+        try {
+            $cached = $this->cache->load($findKey, $ttl, $findField);
+        } catch (Exception $e) {
+            Console::warning('Warning: Failed to get find result from cache: ' . $e->getMessage());
+            $cached = null;
+        }
+
+        if ($cached !== null && $cached !== false && \is_array($cached)) {
+            $documents = \array_map(
+                fn (array $document): Document => $this->createDocumentInstance($collectionDocument->getId(), $document),
+                $cached
+            );
+
+            $this->trigger(self::EVENT_DOCUMENT_FIND, $documents);
+
+            return $documents;
+        }
+
+        $documents = $this->find($collectionDocument->getId(), $queries, $forPermission);
+
+        try {
+            $this->cache->save($findKey, \array_map(
+                static fn (Document $document): array => $document->getArrayCopy(),
+                $documents
+            ), $findField);
+        } catch (Exception $e) {
+            Console::warning('Failed to save find result to cache: ' . $e->getMessage());
+        }
+
+        return $documents;
+    }
+
     /**
      * Helper method to iterate documents in collection using callback pattern
      * Alterative is
@@ -9445,34 +9528,10 @@ public function getCacheKeys(string $collectionId, ?string $documentId = null, a
             $sortedSelects = $selects;
             \sort($sortedSelects);
 
-            $filterSignatures = [];
-            if ($this->filter) {
-                $disabled = $this->disabledFilters ?? [];
-
-                foreach (self::$filters as $name => $callbacks) {
-                    if (isset($disabled[$name])) {
-                        continue;
-                    }
-                    if (\array_key_exists($name, $this->instanceFilters)) {
-                        continue;
-                    }
-                    $filterSignatures[$name] = $callbacks['signature'];
-                }
-
-                foreach ($this->instanceFilters as $name => $callbacks) {
-                    if (isset($disabled[$name])) {
-                        continue;
-                    }
-                    $filterSignatures[$name] = $callbacks['signature'];
-                }
-
-                \ksort($filterSignatures);
-            }
-
             $payload = \json_encode([
                 'selects' => $sortedSelects,
                 'relationships' => $this->resolveRelationships,
-                'filters' => $filterSignatures,
+                'filters' => $this->getFilterSignatures(),
             ]) ?: '';
             $documentHashKey = $documentKey . ':' . \md5($payload);
         }
@@ -9484,6 +9543,93 @@ public function getCacheKeys(string $collectionId, ?string $documentId = null, a
         ];
     }
 
+    /**
+     * @param string $collectionId
+     * @param array<Query> $queries
+     * @param string|null $key
+     * @param string $forPermission
+     * @param Document|null $collection
+     * @return array{0: string, 1: string}
+     */
+    public function getFindCacheKeys(string $collectionId, array $queries = [], ?string $key = null, string $forPermission = self::PERMISSION_READ, ?Document $collection = null): array
+    {
+        [$collectionKey] = $this->getCacheKeys($collectionId);
+        $findKey = "{$collectionKey}:find";
+
+        $payload = [
+            'version' => 1,
+            'database' => $this->getDatabase(),
+            'schema' => $this->getFindCacheSchemaHash($collection),
+            'key' => $key,
+            'queries' => $key === null ? $this->serializeFindCacheQueries($queries) : null,
+            'authorization' => $this->authorization->getStatus(),
+            'roles' => $this->authorization->getRoles(),
+            'permission' => $forPermission,
+            'relationships' => $this->resolveRelationships,
+            'filters' => $this->getFilterSignatures(),
+        ];
+
+        return [$findKey, \md5(\json_encode($payload) ?: '')];
+    }
+
+    private function getFindCacheSchemaHash(?Document $collection): string
+    {
+        if ($collection === null || $collection->isEmpty()) {
+            return '';
+        }
+
+        return \md5(
+            \json_encode($collection->getAttribute('attributes', []))
+            . \json_encode($collection->getAttribute('indexes', []))
+        );
+    }
+
+    /**
+     * @param array<Query> $queries
+     * @return array<mixed>
+     */
+    private function serializeFindCacheQueries(array $queries): array
+    {
+        return \array_map(
+            static fn (Query $query): array => $query->toArray(),
+            $queries
+        );
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function getFilterSignatures(): array
+    {
+        $filterSignatures = [];
+        if (!$this->filter) {
+            return $filterSignatures;
+        }
+
+        $disabled = $this->disabledFilters ?? [];
+
+        foreach (self::$filters as $name => $callbacks) {
+            if (isset($disabled[$name])) {
+                continue;
+            }
+            if (\array_key_exists($name, $this->instanceFilters)) {
+                continue;
+            }
+            $filterSignatures[$name] = $callbacks['signature'];
+        }
+
+        foreach ($this->instanceFilters as $name => $callbacks) {
+            if (isset($disabled[$name])) {
+                continue;
+            }
+            $filterSignatures[$name] = $callbacks['signature'];
+        }
+
+        \ksort($filterSignatures);
+
+        return $filterSignatures;
+    }
+
     private static function computeCallableSignature(callable $callable): string
     {
         if (\is_string($callable)) {

tests/e2e/Adapter/Scopes/DocumentTests.php

@@ -103,6 +103,42 @@ public function testBigintSequence(): void
         }
     }
 
+    public function testFindCachedReturnsStaleResultUntilPurged(): void
+    {
+        /** @var Database $database */
+        $database = $this->getDatabase();
+
+        $database->createCollection(__FUNCTION__);
+        $database->createAttribute(__FUNCTION__, 'name', Database::VAR_STRING, 255, true);
+
+        $database->createDocument(__FUNCTION__, new Document([
+            '$id' => 'first',
+            '$permissions' => [Permission::read(Role::any())],
+            'name' => 'First',
+        ]));
+
+        $documents = $database->findCached(__FUNCTION__, [Query::orderAsc('name')], ttl: 3600);
+        $this->assertCount(1, $documents);
+        $this->assertSame('first', $documents[0]->getId());
+
+        $database->createDocument(__FUNCTION__, new Document([
+            '$id' => 'second',
+            '$permissions' => [Permission::read(Role::any())],
+            'name' => 'Second',
+        ]));
+
+        $documents = $database->findCached(__FUNCTION__, [Query::orderAsc('name')], ttl: 3600);
+        $this->assertCount(1, $documents);
+        $this->assertSame('first', $documents[0]->getId());
+
+        $database->purgeCachedFindCollection(__FUNCTION__);
+
+        $documents = $database->findCached(__FUNCTION__, [Query::orderAsc('name')], ttl: 3600);
+        $this->assertCount(2, $documents);
+        $this->assertSame('first', $documents[0]->getId());
+        $this->assertSame('second', $documents[1]->getId());
+    }
+
     public function testCreateDocumentWithBigIntType(): void
     {
         /** @var Database $database */

tests/unit/CacheKeyTest.php

@@ -7,18 +7,21 @@
 use Utopia\Cache\Cache;
 use Utopia\Database\Adapter;
 use Utopia\Database\Database;
+use Utopia\Database\Document;
+use Utopia\Database\Query;
 
 class CacheKeyTest extends TestCase
 {
     /**
      * @param array<string, array{encode: callable, decode: callable}> $instanceFilters
      */
-    private function createDatabase(array $instanceFilters = []): Database
+    private function createDatabase(array $instanceFilters = [], string $database = 'test'): Database
     {
         $adapter = $this->createMock(Adapter::class);
         $adapter->method('getSupportForHostname')->willReturn(false);
         $adapter->method('getTenant')->willReturn(null);
         $adapter->method('getNamespace')->willReturn('test');
+        $adapter->method('getDatabase')->willReturn($database);
 
         return new Database($adapter, new Cache(new None()), $instanceFilters);
     }
@@ -131,6 +134,97 @@ public function testFiltersDisabledEntirelyProducesDifferentCacheKey(): void
         $this->assertNotEquals($hashEnabled, $hashDisabled);
     }
 
+    public function testDifferentFindQueriesProduceDifferentCacheKeys(): void
+    {
+        $db = $this->createDatabase();
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::equal('status', ['active'])]);
+        [, $fieldB] = $db->getFindCacheKeys('col', [Query::equal('status', ['paused'])]);
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
+    public function testCallerFindCacheKeyIgnoresQueryVariation(): void
+    {
+        $db = $this->createDatabase();
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::equal('status', ['active'])], 'domain-key');
+        [, $fieldB] = $db->getFindCacheKeys('col', [Query::equal('status', ['paused'])], 'domain-key');
+
+        $this->assertEquals($fieldA, $fieldB);
+    }
+
+    public function testDifferentFindRolesProduceDifferentCacheKeys(): void
+    {
+        $db = $this->createDatabase();
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::limit(10)]);
+
+        $db->getAuthorization()->addRole('user:1');
+        [, $fieldB] = $db->getFindCacheKeys('col', [Query::limit(10)]);
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
+    public function testDifferentFindAuthorizationStatusProducesDifferentCacheKeys(): void
+    {
+        $db = $this->createDatabase();
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::limit(10)]);
+
+        $db->getAuthorization()->disable();
+        [, $fieldB] = $db->getFindCacheKeys('col', [Query::limit(10)]);
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
+    public function testDifferentFindDatabasesProduceDifferentCacheKeys(): void
+    {
+        $dbPlatform = $this->createDatabase(database: 'platform');
+        $dbProject = $this->createDatabase(database: 'project');
+
+        [, $fieldA] = $dbPlatform->getFindCacheKeys('col', [Query::limit(10)]);
+        [, $fieldB] = $dbProject->getFindCacheKeys('col', [Query::limit(10)]);
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
+    public function testDifferentFindSchemasProduceDifferentCacheKeys(): void
+    {
+        $db = $this->createDatabase();
+
+        $collectionA = new Document([
+            '$id' => 'col',
+            'attributes' => [
+                new Document(['$id' => 'name', 'type' => Database::VAR_STRING]),
+            ],
+            'indexes' => [],
+        ]);
+        $collectionB = new Document([
+            '$id' => 'col',
+            'attributes' => [
+                new Document(['$id' => 'name', 'type' => Database::VAR_STRING]),
+                new Document(['$id' => 'status', 'type' => Database::VAR_STRING]),
+            ],
+            'indexes' => [],
+        ]);
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::limit(10)], collection: $collectionA);
+        [, $fieldB] = $db->getFindCacheKeys('col', [Query::limit(10)], collection: $collectionB);
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
+    public function testFindRelationshipModeProducesDifferentCacheKeys(): void
+    {
+        $db = $this->createDatabase();
+
+        [, $fieldA] = $db->getFindCacheKeys('col', [Query::limit(10)]);
+        [, $fieldB] = $db->skipRelationships(fn () => $db->getFindCacheKeys('col', [Query::limit(10)]));
+
+        $this->assertNotEquals($fieldA, $fieldB);
+    }
+
     public function testParseHostname(): void
     {
         $hostname = 'database_db_nyc3_self_hosted_0_0';