From 4037de3eb5c7ccbb345bc37e1aeca00dbc42e496 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 6 Jul 2026 20:21:48 +0400 Subject: [PATCH] Add parent filter to list files and whitelist parent queries --- .../Storage/Http/Buckets/Files/XList.php | 11 +++ .../Database/Validator/Queries/Files.php | 1 + tests/e2e/Services/Storage/StorageBase.php | 67 +++++++++++++++++++ 3 files changed, 79 insertions(+) diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php index de61ea5910..93ade4bb32 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/XList.php @@ -7,6 +7,7 @@ use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; +use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Database\Validator\Queries\Files; use Appwrite\Utopia\Response; use Utopia\Database\Database; @@ -22,6 +23,7 @@ use Utopia\Database\Validator\UID; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Boolean; +use Utopia\Validator\Nullable; use Utopia\Validator\Text; class XList extends Action @@ -60,6 +62,7 @@ class XList extends Action ->param('queries', [], new Files(), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' queries are allowed, each ' . APP_LIMIT_ARRAY_ELEMENT_SIZE . ' characters long. You may filter on the following attributes: ' . implode(', ', Files::ALLOWED_ATTRIBUTES), true) ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) ->param('total', true, new Boolean(true), 'When set to false, the total count returned will be 0 and will not be calculated.', true) + ->param('parent', null, new Nullable(new Folder()), 'Filter results to files directly inside this virtual folder. Pass an empty string for the bucket root. Returns files from all folders when omitted.', true) ->inject('response') ->inject('dbForProject') ->inject('mode') @@ -73,6 +76,7 @@ class XList extends Action array $queries, string $search, bool $includeTotal, + ?string $parent, Response $response, Database $dbForProject, string $mode, @@ -104,6 +108,13 @@ class XList extends Action $queries[] = Query::search('search', $search); } + if (!\is_null($parent)) { + $parent = Folder::normalize($parent); + $queries[] = $parent === '' + ? Query::or([Query::equal('parent', ['']), Query::isNull('parent')]) + : Query::equal('parent', [$parent]); + } + $cursor = Query::getCursorQueries($queries, false); $cursor = \reset($cursor); diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index 1941eabcdb..da3f12d266 100644 --- a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php +++ b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php @@ -6,6 +6,7 @@ class Files extends Base { public const ALLOWED_ATTRIBUTES = [ 'name', + 'parent', 'signature', 'mimeType', 'sizeOriginal', diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index f90a967148..1de9efd63a 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -1997,4 +1997,71 @@ trait StorageBase /* will always be 0 in tests because the worker runs hourly! */ $this->assertGreaterThanOrEqual(0, $bucket['body']['totalSize']); } + + public function testListFilesByParent(): void + { + $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'bucketId' => ID::unique(), + 'name' => 'Test Bucket Parent Filter', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $parent) use ($bucketId): void { + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'parent' => $parent, + 'permissions' => [Permission::read(Role::any())], + ]); + $this->assertEquals(201, $file['headers']['status-code']); + }; + + $upload(''); + $upload('photos'); + $upload('photos/2026'); + + $list = function (array $params) use ($bucketId): array { + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), $params); + $this->assertEquals(200, $response['headers']['status-code']); + return $response['body']; + }; + + // no filter -- all files + $this->assertEquals(3, $list([])['total']); + + // exact match -- immediate children only + $this->assertEquals(1, $list(['parent' => 'photos'])['total']); + $this->assertEquals('photos/', $list(['parent' => 'photos'])['files'][0]['parent']); + + // root only + $this->assertEquals(1, $list(['parent' => ''])['total']); + $this->assertEquals('', $list(['parent' => ''])['files'][0]['parent']); + + // recursive via queries + $recursive = $list(['queries' => [Query::startsWith('parent', 'photos/')->toString()]]); + $this->assertEquals(2, $recursive['total']); + + // invalid parent + $response = $this->client->call(Client::METHOD_GET, '/storage/buckets/' . $bucketId . '/files', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), ['parent' => '/photos']); + $this->assertEquals(400, $response['headers']['status-code']); + } }