Add cached find helpers

Author: premtsd-code

src/Database/Database.php

@@ -8564,6 +8564,75 @@ public function find(string $collection, array $queries = [], string $forPermiss
         return $results;
     }
 
+    /**
+     * Find documents through a cache-aside lookup.
+     *
+     * The caller owns authorization context. Use Authorization::skip() around
+     * this method for internal reads that should bypass request-user roles.
+     *
+     * @param string $collection
+     * @param array<Query> $queries
+     * @param string|null $namespace
+     * @param array<string> $roles
+     * @param string $forPermission
+     * @return array<Document>
+     * @throws DatabaseException
+     * @throws QueryException
+     * @throws TimeoutException
+     * @throws Exception
+     */
+    public function cachedFind(
+        string $collection,
+        array $queries = [],
+        ?string $namespace = null,
+        array $roles = [],
+        string $forPermission = Database::PERMISSION_READ,
+    ): array {
+        $collectionDocument = $this->silent(fn () => $this->getCollection($collection));
+
+        if ($collectionDocument->isEmpty()) {
+            throw new NotFoundException('Collection not found');
+        }
+
+        $payload = $this->withCache(
+            key: $this->getFindCacheKey($collection, $namespace),
+            callback: fn (): array => \array_map(
+                static fn (Document $document): array => $document->getArrayCopy(),
+                $this->find($collection, $queries, $forPermission),
+            ),
+            hash: $this->getFindCacheField($collectionDocument, $queries, $roles, 'documents'),
+        );
+
+        if (!\is_array($payload)) {
+            return [];
+        }
+
+        $documents = [];
+        foreach ($payload as $document) {
+            if (!\is_array($document)) {
+                continue;
+            }
+
+            $documents[] = $this->createDocumentInstance($collection, $document);
+        }
+
+        return $documents;
+    }
+
+    /**
+     * Purge all cached find entries for a collection namespace.
+     *
+     * @param string $collection
+     * @param string|null $namespace
+     * @return bool
+     */
+    public function purgeCachedFind(string $collection, ?string $namespace = null): bool
+    {
+        return $this->cache->purge(
+            $this->getFindCacheKey($collection, $namespace)
+        );
+    }
+
     /**
      * Execute a callback behind a cache-aside lookup.
      *

tests/unit/ListCacheTest.php

@@ -7,6 +7,10 @@
 use Utopia\Cache\Cache;
 use Utopia\Database\Adapter\Memory as DatabaseMemory;
 use Utopia\Database\Database;
+use Utopia\Database\Document;
+use Utopia\Database\Helpers\Permission;
+use Utopia\Database\Helpers\Role;
+use Utopia\Database\Query;
 
 class ListCacheTest extends TestCase
 {
@@ -182,6 +186,101 @@ function () use (&$callbackCalls): string {
         $this->assertSame('fresh', $value);
         $this->assertSame(2, $callbackCalls);
     }
+
+    public function testCachedFindUsesCacheUntilPurged(): void
+    {
+        $cache = new HashMemoryCache();
+        $database = $this->createDatabase($cache);
+        $database->createCollection('wafRules', [
+            new Document([
+                '$id' => 'projectId',
+                'type' => Database::VAR_STRING,
+                'size' => 255,
+                'required' => false,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ]),
+        ], permissions: [
+            Permission::read(Role::any()),
+            Permission::create(Role::any()),
+        ]);
+
+        $database->createDocument('wafRules', new Document([
+            '$id' => 'rule-a',
+            'projectId' => 'project-a',
+        ]));
+
+        $queries = [
+            Query::equal('projectId', ['project-a']),
+            Query::limit(25),
+        ];
+
+        $first = $database->cachedFind('wafRules', $queries, '_39', ['waf']);
+        $this->assertCount(1, $first);
+        $this->assertSame('rule-a', $first[0]->getId());
+
+        $database->createDocument('wafRules', new Document([
+            '$id' => 'rule-b',
+            'projectId' => 'project-a',
+        ]));
+
+        $cached = $database->cachedFind('wafRules', $queries, '_39', ['waf']);
+        $this->assertCount(1, $cached);
+        $this->assertSame('rule-a', $cached[0]->getId());
+
+        $this->assertTrue($database->purgeCachedFind('wafRules', '_39'));
+
+        $fresh = $database->cachedFind('wafRules', $queries, '_39', ['waf']);
+        $this->assertCount(2, $fresh);
+        $this->assertSame(['rule-a', 'rule-b'], \array_map(
+            static fn (Document $document): string => $document->getId(),
+            $fresh,
+        ));
+    }
+
+    public function testCachedFindSeparatesEntriesByRoles(): void
+    {
+        $cache = new HashMemoryCache();
+        $database = $this->createDatabase($cache);
+        $database->createCollection('wafRules', [
+            new Document([
+                '$id' => 'projectId',
+                'type' => Database::VAR_STRING,
+                'size' => 255,
+                'required' => false,
+                'signed' => true,
+                'array' => false,
+                'filters' => [],
+            ]),
+        ], permissions: [
+            Permission::read(Role::any()),
+            Permission::create(Role::any()),
+        ]);
+
+        $database->createDocument('wafRules', new Document([
+            '$id' => 'rule-a',
+            'projectId' => 'project-a',
+        ]));
+
+        $queries = [
+            Query::equal('projectId', ['project-a']),
+            Query::limit(25),
+        ];
+
+        $database->cachedFind('wafRules', $queries, '_39', ['waf']);
+
+        $database->createDocument('wafRules', new Document([
+            '$id' => 'rule-b',
+            'projectId' => 'project-a',
+        ]));
+
+        $cached = $database->cachedFind('wafRules', $queries, '_39', ['waf']);
+        $this->assertCount(1, $cached);
+
+        $roleSeparated = $database->cachedFind('wafRules', $queries, '_39', ['manager']);
+        $this->assertCount(2, $roleSeparated);
+    }
 }
 
 class HashMemoryCache implements Adapter