From cef8072bdea6d58b5d63ed53d2f9f9879195c7a2 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Jul 2026 15:35:03 +0400 Subject: [PATCH] Use queries for folder listing --- .../Storage/Http/Buckets/Folders/XList.php | 81 +++++++++++++------ src/Appwrite/Utopia/Response/Model/File.php | 1 - tests/e2e/Services/Storage/StorageBase.php | 29 ++++--- 3 files changed, 72 insertions(+), 39 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php index da82e308a1..302cebb05c 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -12,13 +12,17 @@ use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Exception\NotFound as NotFoundException; +use Utopia\Database\Exception\Query as QueryException; use Utopia\Database\Query; use Utopia\Database\Validator\Authorization; use Utopia\Database\Validator\Authorization\Input; +use Utopia\Database\Validator\Queries; +use Utopia\Database\Validator\Query\Filter; +use Utopia\Database\Validator\Query\Limit; +use Utopia\Database\Validator\Query\Offset; use Utopia\Database\Validator\UID; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; -use Utopia\Validator\Range; class XList extends Action { @@ -43,7 +47,9 @@ class XList extends Action namespace: 'storage', group: 'files', name: 'listFolders', - description: '/docs/references/storage/list-folders.md', + description: <<param('bucketId', '', new UID(), 'Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket).') - ->param('folder', '', new Folder(), 'Virtual folder to list the child folders of. Defaults to the bucket root.', true) - ->param('limit', 25, new Range(1, 100), 'Maximum number of folders to return. Must be between 1 and 100. A page shorter than this limit means the listing is complete.', true) - ->param('cursor', '', new Folder(), 'Folder path returned last by a previous page, used to continue the listing.', true) + ->param('queries', [], new Queries([ + new Limit(100), + new Offset(), + new Filter([ + new Document([ + 'key' => 'folder', + 'type' => Database::VAR_STRING, + 'array' => false, + ]), + ], Database::VAR_STRING, 1), + ]), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are equal on the folder attribute, limit, and offset.', true) ->inject('response') ->inject('dbForProject') ->inject('authorization') @@ -65,9 +79,7 @@ class XList extends Action public function action( string $bucketId, - string $folder, - int $limit, - string $cursor, + array $queries, Response $response, Database $dbForProject, Authorization $authorization, @@ -88,16 +100,38 @@ class XList extends Action throw new Exception(Exception::USER_UNAUTHORIZED, $authorization->getDescription()); } - $parent = Folder::normalize($folder); - $cursor = Folder::normalize($cursor); - - if ($cursor !== '') { - $remainder = \substr($cursor, \strlen($parent), -1); - if (!\str_starts_with($cursor, $parent) || $cursor === $parent || \str_contains($remainder, '/')) { - throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, "Folder '{$cursor}' for the 'cursor' value is not an immediate child of '{$parent}'."); - } + try { + $queries = Query::parseQueries($queries); + } catch (QueryException $e) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, $e->getMessage()); } + $grouped = Query::groupByType($queries); + $filters = $grouped['filters']; + if (\count($filters) > 1) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Only one folder filter is allowed.'); + } + + $parent = ''; + if (!empty($filters)) { + $filter = $filters[0]; + if ($filter->getMethod() !== Query::TYPE_EQUAL || $filter->getAttribute() !== 'folder' || \count($filter->getValues()) !== 1) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Only equal queries on the folder attribute are supported.'); + } + + $folder = $filter->getValue(); + $validator = new Folder(); + if (!$validator->isValid($folder)) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, $validator->getDescription()); + } + + $parent = Folder::normalize($folder); + } + + $limit = $grouped['limit'] ?? 25; + $offset = $grouped['offset'] ?? 0; + $pageEnd = $offset > PHP_INT_MAX - $limit ? PHP_INT_MAX : $offset + $limit; + $collection = 'bucket_' . $bucket->getSequence(); $folders = []; $latest = null; @@ -105,15 +139,15 @@ class XList extends Action try { do { - $queries = [Query::limit($batch)]; + $batchQueries = [Query::limit($batch)]; if ($latest !== null) { - $queries[] = Query::cursorAfter($latest); + $batchQueries[] = Query::cursorAfter($latest); } if ($fileSecurity && !$valid) { - $results = $dbForProject->find($collection, $queries); + $results = $dbForProject->find($collection, $batchQueries); } else { - $results = $authorization->skip(fn () => $dbForProject->find($collection, $queries)); + $results = $authorization->skip(fn () => $dbForProject->find($collection, $batchQueries)); } if (empty($results)) { @@ -128,9 +162,6 @@ class XList extends Action $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; $key = $parent . $segment . '/'; - if ($cursor !== '' && \strcmp($key, $cursor) <= 0) { - continue; - } $folders[$key] = new Document([ 'key' => $key, @@ -140,7 +171,7 @@ class XList extends Action } \ksort($folders, \SORT_STRING); - $folders = \array_slice($folders, 0, $limit, true); + $folders = \array_slice($folders, 0, $pageEnd, true); $latest = $results[\array_key_last($results)]; } while (\count($results) === $batch); } catch (NotFoundException) { @@ -148,7 +179,7 @@ class XList extends Action } $response->dynamic(new Document([ - 'folders' => \array_values($folders), + 'folders' => \array_slice(\array_values($folders), $offset, $limit), ]), Response::MODEL_FOLDER_LIST); } diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 75711d3ea9..49c189b311 100644 --- a/src/Appwrite/Utopia/Response/Model/File.php +++ b/src/Appwrite/Utopia/Response/Model/File.php @@ -140,7 +140,6 @@ class File extends Model $document->setAttribute('encryption', $encryption); $folder = $document->getAttribute('folder') ?? ''; - $document->setAttribute('folder', $folder); $document->setAttribute('key', $folder . $document->getAttribute('name', '')); return $document; diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 9c4929ec3e..c5250221a1 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2167,34 +2167,37 @@ trait StorageBase $this->assertEquals(['', '', ''], \array_column($folders, 'parent')); // nested level -- deep files imply intermediate folders - $folders = $listFolders(['folder' => 'photos']); + $folders = $listFolders(['queries' => [Query::equal('folder', ['photos'])->toString()]]); $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); - $folders = $listFolders(['folder' => 'photos/2026']); + $folders = $listFolders(['queries' => [Query::equal('folder', ['photos/2026'])->toString()]]); $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); // pagination - $page = $listFolders(['limit' => 1]); + $page = $listFolders(['queries' => [Query::limit(1)->toString()]]); $this->assertEquals(['Photos/'], \array_column($page, 'key')); - $page = $listFolders(['limit' => 1, 'cursor' => 'Photos/']); + $page = $listFolders(['queries' => [Query::limit(1)->toString(), Query::offset(1)->toString()]]); $this->assertEquals(['invoices/'], \array_column($page, 'key')); - $page = $listFolders(['limit' => 1, 'cursor' => 'invoices/']); + $page = $listFolders(['queries' => [Query::limit(1)->toString(), Query::offset(2)->toString()]]); $this->assertEquals(['photos/'], \array_column($page, 'key')); - $page = $listFolders(['limit' => 1, 'cursor' => 'photos/']); + $page = $listFolders(['queries' => [Query::limit(1)->toString(), Query::offset(3)->toString()]]); $this->assertCount(0, $page); // nonexistent prefix -- empty list, not 404 - $this->assertCount(0, $listFolders(['folder' => 'missing'])); + $this->assertCount(0, $listFolders(['queries' => [Query::equal('folder', ['missing'])->toString()]])); - // crafted cursors -- must be an immediate child of parent + // unsupported and malformed queries foreach ([ - ['folder' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild - ['folder' => 'photos', 'cursor' => 'invoices'], // outside parent - ] as $params) { + [Query::startsWith('folder', 'photos')->toString()], + [Query::equal('name', ['photos'])->toString()], + [Query::equal('folder', ['photos', 'invoices'])->toString()], + [Query::equal('folder', ['photos//2026'])->toString()], + [Query::limit(101)->toString()], + ] as $queries) { $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/folders', array_merge([ 'content-type' => 'application/json', 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), $params); + ], $this->getHeaders()), ['queries' => $queries]); $this->assertEquals(400, $response['headers']['status-code']); } @@ -2204,7 +2207,7 @@ trait StorageBase 'x-appwrite-project' => $this->getProject()['$id'], ], $this->getHeaders())); $this->assertEquals(204, $delete['headers']['status-code']); - $this->assertEquals(['photos/2025/'], \array_column($listFolders(['folder' => 'photos']), 'key')); + $this->assertEquals(['photos/2025/'], \array_column($listFolders(['queries' => [Query::equal('folder', ['photos'])->toString()]]), 'key')); $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ 'content-type' => 'application/json',