From dd6989875c7dccef1f4a0c3e198b7305a126e592 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Tue, 21 Jul 2026 15:19:57 +0400 Subject: [PATCH 1/6] Revert "Merge pull request #12818 from appwrite/chore-disable-storage-folder-api" This reverts commit 71f1cb02dfea8c2835ed774f9992b33fc9de41eb, reversing changes made to b7c34ad5ad87f41d681b56e55888e7458e6bc9e5. --- app/init/models.php | 3 + src/Appwrite/Migration/Version/V25.php | 1 + .../Storage/Http/Buckets/Files/Create.php | 10 +- .../Storage/Http/Buckets/Folders/XList.php | 158 ++++++++++ .../Modules/Storage/Services/Http.php | 4 + .../Database/Validator/Queries/Files.php | 1 + src/Appwrite/Utopia/Response.php | 2 + src/Appwrite/Utopia/Response/Model/File.php | 16 + src/Appwrite/Utopia/Response/Model/Folder.php | 53 ++++ tests/e2e/Services/Storage/StorageBase.php | 285 ++++++++++++++++++ .../Storage/StorageCustomClientTest.php | 46 +++ 11 files changed, 577 insertions(+), 2 deletions(-) create mode 100644 src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php create mode 100644 src/Appwrite/Utopia/Response/Model/Folder.php diff --git a/app/init/models.php b/app/init/models.php index 05136566d2..6d4905ac35 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -80,6 +80,7 @@ use Appwrite\Utopia\Response\Model\Error; use Appwrite\Utopia\Response\Model\ErrorDev; use Appwrite\Utopia\Response\Model\Execution; use Appwrite\Utopia\Response\Model\File; +use Appwrite\Utopia\Response\Model\Folder; use Appwrite\Utopia\Response\Model\Framework; use Appwrite\Utopia\Response\Model\FrameworkAdapter; use Appwrite\Utopia\Response\Model\Func; @@ -255,6 +256,7 @@ Response::setModel(new BaseList('Identities List', Response::MODEL_IDENTITY_LIST Response::setModel(new BaseList('Notifications List', Response::MODEL_NOTIFICATION_LIST, 'notifications', Response::MODEL_NOTIFICATION)); Response::setModel(new BaseList('Logs List', Response::MODEL_LOG_LIST, 'logs', Response::MODEL_LOG)); Response::setModel(new BaseList('Files List', Response::MODEL_FILE_LIST, 'files', Response::MODEL_FILE)); +Response::setModel(new BaseList('Folders List', Response::MODEL_FOLDER_LIST, 'folders', Response::MODEL_FOLDER, paging: false)); Response::setModel(new BaseList('Buckets List', Response::MODEL_BUCKET_LIST, 'buckets', Response::MODEL_BUCKET)); Response::setModel(new BaseList('Resource Tokens List', Response::MODEL_RESOURCE_TOKEN_LIST, 'tokens', Response::MODEL_RESOURCE_TOKEN)); Response::setModel(new BaseList('Teams List', Response::MODEL_TEAM_LIST, 'teams', Response::MODEL_TEAM)); @@ -390,6 +392,7 @@ Response::setModel(new JWT()); Response::setModel(new Locale()); Response::setModel(new LocaleCode()); Response::setModel(new File()); +Response::setModel(new Folder()); Response::setModel(new Bucket()); Response::setModel(new ResourceToken()); Response::setModel(new Team()); diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index 3a997c865d..416500a1b6 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -94,4 +94,5 @@ class V25 extends Migration } } } + } diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php index cf934575c0..c50718145b 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Files/Create.php @@ -13,6 +13,7 @@ use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Database\Validator\CustomId; +use Appwrite\Utopia\Database\Validator\Folder; use Appwrite\Utopia\Response; use Utopia\Compression\Algorithms\GZIP; use Utopia\Compression\Algorithms\Zstd; @@ -85,6 +86,7 @@ class Create extends Action ->param('fileId', '', new CustomId(), 'File ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.') ->param('file', [], new File(), 'Binary file. Appwrite SDKs provide helpers to handle file input. [Learn about file input](https://appwrite.io/docs/products/storage/upload-download#input-file).', skipValidation: true) ->param('permissions', null, new Nullable(new Permissions(APP_LIMIT_ARRAY_PARAMS_SIZE, [Database::PERMISSION_READ, Database::PERMISSION_UPDATE, Database::PERMISSION_DELETE, Database::PERMISSION_WRITE])), 'An array of permission strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).', true) + ->param('folder', '', new Folder(), 'Virtual folder to place the file in, for example "photos/2026". Nest folders with `/`. Defaults to the bucket root.', true) ->inject('request') ->inject('response') ->inject('dbForProject') @@ -103,6 +105,7 @@ class Create extends Action string $fileId, mixed $file, ?array $permissions, + string $folder, Request $request, Response $response, Database $dbForProject, @@ -190,6 +193,7 @@ class Create extends Action $contentRange = $request->getHeaderLine('content-range'); $fileId = $fileId === 'unique()' ? ID::unique() : $fileId; + $folder = Folder::normalize($folder); $chunk = 1; $chunks = 1; @@ -261,7 +265,7 @@ class Create extends Action }; try { - $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $path, $permissions, $response, &$completed): void { + $locks($lockKey, 600, function () use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $folder, $path, $permissions, $response, &$completed): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); if (!$file->isEmpty()) { $chunks = $file->getAttribute('chunksTotal', 1); @@ -292,6 +296,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, + 'folder' => $folder, 'path' => $path, 'signature' => '', 'mimeType' => '', @@ -325,7 +330,7 @@ class Create extends Action return; } - $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $path, $permissions, $queueForEvents, $response): void { + $finalizeUpload = function (int $chunksUploaded) use ($authorization, $bucket, &$chunks, $contentRange, $dbForProject, $deviceForFiles, $fileId, $fileName, $fileSize, &$metadata, $mergeUploadMetadata, $folder, $path, $permissions, $queueForEvents, $response): void { $file = $authorization->skip(fn () => $dbForProject->getDocument('bucket_' . $bucket->getSequence(), $fileId)); $uploaded = 0; @@ -428,6 +433,7 @@ class Create extends Action 'bucketId' => $bucket->getId(), 'bucketInternalId' => $bucket->getSequence(), 'name' => $fileName, + 'folder' => $folder, 'path' => $path, 'signature' => $fileHash, 'mimeType' => $mimeType, diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php new file mode 100644 index 0000000000..d44d6eb99f --- /dev/null +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -0,0 +1,158 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/storage/buckets/:bucketId/folders') + ->desc('List folders') + ->groups(['api', 'storage']) + ->label('scope', 'files.read') + ->label('usage.resource', 'bucket/{request.bucketId}') + ->label('resourceType', RESOURCE_TYPE_BUCKETS) + ->label('sdk', new Method( + namespace: 'storage', + group: 'files', + name: 'listFolders', + description: '/docs/references/storage/list-folders.md', + auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_FOLDER_LIST, + ) + ] + )) + ->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) + ->inject('response') + ->inject('dbForProject') + ->inject('authorization') + ->inject('user') + ->callback($this->action(...)); + } + + public function action( + string $bucketId, + string $folder, + int $limit, + string $cursor, + Response $response, + Database $dbForProject, + Authorization $authorization, + User $user + ) { + $bucket = $authorization->skip(fn () => $dbForProject->getDocument('buckets', $bucketId)); + + $isAPIKey = $user->isKey($authorization->getRoles()); + $isPrivilegedUser = $user->isPrivileged($authorization->getRoles()); + + if ($bucket->isEmpty() || (!$bucket->getAttribute('enabled') && !$isAPIKey && !$isPrivilegedUser)) { + throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); + } + + $fileSecurity = $bucket->getAttribute('fileSecurity', false); + $valid = $authorization->isValid(new Input(Database::PERMISSION_READ, $bucket->getRead())); + if (!$fileSecurity && !$valid) { + 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}'."); + } + } + + $collection = 'bucket_' . $bucket->getSequence(); + $seek = $cursor === '' ? $parent : self::seekPast($cursor); + $folders = []; + + try { + while (\count($folders) < $limit) { + $queries = [ + Query::greaterThan('folder', $seek), + Query::orderAsc('folder'), + Query::limit(1), + ]; + if ($parent !== '') { + $queries[] = Query::startsWith('folder', $parent); + } + + if ($fileSecurity && !$valid) { + $results = $dbForProject->find($collection, $queries); + } else { + $results = $authorization->skip(fn () => $dbForProject->find($collection, $queries)); + } + + if (empty($results)) { + break; + } + + $fileParent = $results[0]->getAttribute('folder', ''); + $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; + $key = $parent . $segment . '/'; + + $folders[] = new Document([ + 'key' => $key, + 'name' => $segment, + 'parent' => $parent, + ]); + + $seek = self::seekPast($key); + } + } catch (NotFoundException) { + throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); + } + + $response->dynamic(new Document([ + 'folders' => $folders, + ]), Response::MODEL_FOLDER_LIST); + } + + /** + * Smallest string that sorts after every `folder` value inside the given + * folder: the trailing '/' replaced with the next code point ('0'), so a + * seek jumps past all of the folder's contents in one indexed query. + * Assumes the database orders `folder` values bytewise (binary collation), + * so nothing sorts between '/' (0x2F) and '0' (0x30). + */ + private static function seekPast(string $folder): string + { + return \substr($folder, 0, -1) . \chr(\ord('/') + 1); + } +} diff --git a/src/Appwrite/Platform/Modules/Storage/Services/Http.php b/src/Appwrite/Platform/Modules/Storage/Services/Http.php index 4010918205..dd7b8a900e 100644 --- a/src/Appwrite/Platform/Modules/Storage/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Storage/Services/Http.php @@ -13,6 +13,7 @@ use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Push\Get as GetFileForP use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Update as UpdateFile; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\View\Get as GetFileView; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\XList as ListFiles; +use Appwrite\Platform\Modules\Storage\Http\Buckets\Folders\XList as ListFolders; use Appwrite\Platform\Modules\Storage\Http\Buckets\Get as GetBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\Update as UpdateBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\XList as ListBuckets; @@ -41,5 +42,8 @@ class Http extends Service $this->addAction(GetFileDownload::getName(), new GetFileDownload()); $this->addAction(GetFileView::getName(), new GetFileView()); $this->addAction(GetFileForPush::getName(), new GetFileForPush()); + + // Folders + $this->addAction(ListFolders::getName(), new ListFolders()); } } diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Files.php b/src/Appwrite/Utopia/Database/Validator/Queries/Files.php index 1941eabcdb..4785e12d58 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', + 'folder', 'signature', 'mimeType', 'sizeOriginal', diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 19b5f4d120..6420243472 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -157,6 +157,8 @@ class Response extends SwooleResponse public const MODEL_FILE_LIST = 'fileList'; public const MODEL_BUCKET = 'bucket'; public const MODEL_BUCKET_LIST = 'bucketList'; + public const MODEL_FOLDER = 'folder'; + public const MODEL_FOLDER_LIST = 'folderList'; public const MODEL_RESOURCE_TOKEN = 'resourceToken'; public const MODEL_RESOURCE_TOKEN_LIST = 'resourceTokenList'; diff --git a/src/Appwrite/Utopia/Response/Model/File.php b/src/Appwrite/Utopia/Response/Model/File.php index 61dd496f52..75711d3ea9 100644 --- a/src/Appwrite/Utopia/Response/Model/File.php +++ b/src/Appwrite/Utopia/Response/Model/File.php @@ -49,6 +49,18 @@ class File extends Model 'default' => '', 'example' => 'Pink.png', ]) + ->addRule('folder', [ + 'type' => self::TYPE_STRING, + 'description' => 'Virtual folder containing the file, with a trailing slash. Empty for the bucket root.', + 'default' => '', + 'example' => 'photos/2026/', + ]) + ->addRule('key', [ + 'type' => self::TYPE_STRING, + 'description' => 'Full virtual path of the file: the folder followed by the file name.', + 'default' => '', + 'example' => 'photos/2026/Pink.png', + ]) ->addRule('signature', [ 'type' => self::TYPE_STRING, 'description' => 'File MD5 signature.', @@ -127,6 +139,10 @@ class File extends Model $encryption = !empty($document->getAttribute('openSSLCipher', '')); $document->setAttribute('encryption', $encryption); + $folder = $document->getAttribute('folder') ?? ''; + $document->setAttribute('folder', $folder); + $document->setAttribute('key', $folder . $document->getAttribute('name', '')); + return $document; } } diff --git a/src/Appwrite/Utopia/Response/Model/Folder.php b/src/Appwrite/Utopia/Response/Model/Folder.php new file mode 100644 index 0000000000..10bc40837b --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/Folder.php @@ -0,0 +1,53 @@ +addRule('key', [ + 'type' => self::TYPE_STRING, + 'description' => 'Full folder path, with a trailing slash.', + 'default' => '', + 'example' => 'photos/2026/', + ]) + ->addRule('name', [ + 'type' => self::TYPE_STRING, + 'description' => 'Folder name: the last segment of the path.', + 'default' => '', + 'example' => '2026', + ]) + ->addRule('parent', [ + 'type' => self::TYPE_STRING, + 'description' => 'Parent folder path with a trailing slash. Empty for top-level folders.', + 'default' => '', + 'example' => 'photos/', + ]) + ; + } + + /** + * Get Name + * + * @return string + */ + public function getName(): string + { + return 'Folder'; + } + + /** + * Get Type + * + * @return string + */ + public function getType(): string + { + return Response::MODEL_FOLDER; + } +} diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index c2d90a2543..1c3007a803 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -491,6 +491,120 @@ trait StorageBase $this->assertNotEmpty($webpView['body']); } + public function testCreateBucketFileWithFolder(): 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 Folders', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + Permission::update(Role::any()), + Permission::delete(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + // without trailing slash -- normalized on storage + $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'), + 'folder' => 'photos/2026', + ]); + $this->assertEquals(201, $file['headers']['status-code']); + $this->assertEquals('photos/2026/', $file['body']['folder']); + $this->assertEquals('photos/2026/logo.png', $file['body']['key']); + $this->assertEquals('logo.png', $file['body']['name']); + + // default -- bucket root + $rootFile = $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'), + ]); + $this->assertEquals(201, $rootFile['headers']['status-code']); + $this->assertEquals('', $rootFile['body']['folder']); + $this->assertEquals('logo.png', $rootFile['body']['key']); + + // duplicate keys allowed -- same parent + name, different fileId + $duplicate = $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'), + 'folder' => 'photos/2026', + ]); + $this->assertEquals(201, $duplicate['headers']['status-code']); + $this->assertEquals('photos/2026/logo.png', $duplicate['body']['key']); + $this->assertNotEquals($file['body']['$id'], $duplicate['body']['$id']); + + // invalid values + foreach (['/photos', 'photos//2026', 'photos/../2026', "photos/\x01"] as $invalid) { + $res = $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'), + 'folder' => $invalid, + ]); + $this->assertEquals(400, $res['headers']['status-code']); + } + + // chunked upload -- parent is stored when the document is created + // with the first chunk (pattern from testCreateBucketFile) + $source = __DIR__ . '/../../../resources/disk-a/large-file.mp4'; + $size = \filesize($source); + $chunkSize = 5 * 1024 * 1024; + $handle = @\fopen($source, 'rb'); + $mimeType = \mime_content_type($source); + $counter = 0; + $id = ''; + $chunked = null; + $headers = [ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + ]; + while (!\feof($handle)) { + $curlFile = new CURLFile('data://' . $mimeType . ';base64,' . \base64_encode(@\fread($handle, $chunkSize)), $mimeType, 'large-file.mp4'); + $headers['content-range'] = 'bytes ' . ($counter * $chunkSize) . '-' . \min(((($counter * $chunkSize) + $chunkSize) - 1), $size - 1) . '/' . $size; + if (!empty($id)) { + $headers['x-appwrite-id'] = $id; + } + $chunked = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', \array_merge($headers, $this->getHeaders()), [ + 'fileId' => 'unique()', + 'file' => $curlFile, + 'folder' => 'videos/2026', + ]); + $this->assertNotEmpty($chunked['body']['$id']); + $id = $chunked['body']['$id']; + $counter++; + } + \fclose($handle); + $this->assertEquals(201, $chunked['headers']['status-code']); + $this->assertEquals('videos/2026/', $chunked['body']['folder']); + $this->assertEquals('videos/2026/large-file.mp4', $chunked['body']['key']); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); + } + public function testCreateBucketFileZstdCompression(): void { $bucket = $this->client->call(Client::METHOD_POST, '/storage/buckets', [ @@ -1922,4 +2036,175 @@ trait StorageBase $this->assertGreaterThanOrEqual(0, $bucket['body']['totalSize']); } + public function testListFilesByFolder(): 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 $folder) 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'), + 'folder' => $folder, + '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, canonical form with trailing slash + $exact = $list(['queries' => [Query::equal('folder', ['photos/'])->toString()]]); + $this->assertEquals(1, $exact['total']); + $this->assertEquals('photos/', $exact['files'][0]['folder']); + + // equality is against the stored canonical form -- no normalization on query values + $this->assertEquals(0, $list(['queries' => [Query::equal('folder', ['photos'])->toString()]])['total']); + + // root only + $root = $list(['queries' => [Query::equal('folder', [''])->toString()]]); + $this->assertEquals(1, $root['total']); + $this->assertEquals('', $root['files'][0]['folder']); + + // recursive via prefix + $recursive = $list(['queries' => [Query::startsWith('folder', 'photos/')->toString()]]); + $this->assertEquals(2, $recursive['total']); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); + } + + public function testListFolders(): 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 Folder Listing', + 'fileSecurity' => true, + 'permissions' => [ + Permission::read(Role::any()), + Permission::create(Role::any()), + Permission::delete(Role::any()), + ], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $folder) use ($bucketId): string { + $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'), + 'folder' => $folder, + 'permissions' => [Permission::read(Role::any()), Permission::delete(Role::any())], + ]); + $this->assertEquals(201, $file['headers']['status-code']); + return $file['body']['$id']; + }; + + $upload(''); + $upload('invoices'); + $upload('photos/2025'); + $julyFileId = $upload('photos/2026/july'); + + $listFolders = function (array $params) use ($bucketId): array { + $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->assertEquals(200, $response['headers']['status-code']); + return $response['body']['folders']; + }; + + // top level, alphabetical + $folders = $listFolders([]); + $this->assertCount(2, $folders); + $this->assertEquals(['invoices/', 'photos/'], \array_column($folders, 'key')); + $this->assertEquals(['invoices', 'photos'], \array_column($folders, 'name')); + $this->assertEquals(['', ''], \array_column($folders, 'parent')); + + // nested level -- deep files imply intermediate folders + $folders = $listFolders(['folder' => 'photos']); + $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); + + $folders = $listFolders(['folder' => 'photos/2026']); + $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); + + // pagination + $page = $listFolders(['limit' => 1]); + $this->assertEquals(['invoices/'], \array_column($page, 'key')); + $page = $listFolders(['limit' => 1, 'cursor' => 'invoices/']); + $this->assertEquals(['photos/'], \array_column($page, 'key')); + $page = $listFolders(['limit' => 1, 'cursor' => 'photos/']); + $this->assertCount(0, $page); + + // nonexistent prefix -- empty list, not 404 + $this->assertCount(0, $listFolders(['folder' => 'missing'])); + + // crafted cursors -- must be an immediate child of parent + foreach ([ + ['folder' => 'photos', 'cursor' => 'photos/2026/july'], // grandchild + ['folder' => 'photos', 'cursor' => 'invoices'], // outside parent + ] as $params) { + $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->assertEquals(400, $response['headers']['status-code']); + } + + // implicit lifecycle -- deleting the last file removes the folder chain + $delete = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId . '/files/' . $julyFileId, array_merge([ + 'content-type' => 'application/json', + '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')); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); + } } diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 32c92626d5..778bf6c2f0 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1607,4 +1607,50 @@ final class StorageCustomClientTest extends Scope $this->assertEquals(204, $response['headers']['status-code']); } + public function testListFoldersFileSecurityVisibility(): 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' => 'Folder Visibility', + 'fileSecurity' => true, + 'permissions' => [], + ]); + $this->assertEquals(201, $bucket['headers']['status-code']); + $bucketId = $bucket['body']['$id']; + + $upload = function (string $folder, array $permissions) use ($bucketId): void { + $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', [ + 'content-type' => 'multipart/form-data', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'fileId' => ID::unique(), + 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), + 'folder' => $folder, + 'permissions' => $permissions, + ]); + $this->assertEquals(201, $file['headers']['status-code']); + }; + + $upload('secret', []); + $upload('shared', [Permission::read(Role::any())]); + + $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())); + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertSame(['shared/'], \array_column($response['body']['folders'], 'key')); + + $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(204, $response['headers']['status-code']); + } } From 2aace7405199175b8ed6a5c725385e1dead74ae7 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Tue, 21 Jul 2026 15:20:38 +0400 Subject: [PATCH 2/6] Remove storage folder migration diff --- src/Appwrite/Migration/Version/V25.php | 1 - 1 file changed, 1 deletion(-) diff --git a/src/Appwrite/Migration/Version/V25.php b/src/Appwrite/Migration/Version/V25.php index 416500a1b6..3a997c865d 100644 --- a/src/Appwrite/Migration/Version/V25.php +++ b/src/Appwrite/Migration/Version/V25.php @@ -94,5 +94,4 @@ class V25 extends Migration } } } - } From 0ce8aeed08bf232c1ab3676e2417da6cff7be6cc Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Wed, 22 Jul 2026 12:27:26 +0400 Subject: [PATCH 3/6] Fix folder pagination collation --- .../Storage/Http/Buckets/Folders/XList.php | 18 +++++------------- 1 file changed, 5 insertions(+), 13 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 d44d6eb99f..ca0794fdcf 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -99,7 +99,7 @@ class XList extends Action } $collection = 'bucket_' . $bucket->getSequence(); - $seek = $cursor === '' ? $parent : self::seekPast($cursor); + $seek = $cursor === '' ? $parent : $cursor; $folders = []; try { @@ -109,6 +109,9 @@ class XList extends Action Query::orderAsc('folder'), Query::limit(1), ]; + if ($seek !== $parent) { + $queries[] = Query::notStartsWith('folder', $seek); + } if ($parent !== '') { $queries[] = Query::startsWith('folder', $parent); } @@ -133,7 +136,7 @@ class XList extends Action 'parent' => $parent, ]); - $seek = self::seekPast($key); + $seek = $key; } } catch (NotFoundException) { throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); @@ -144,15 +147,4 @@ class XList extends Action ]), Response::MODEL_FOLDER_LIST); } - /** - * Smallest string that sorts after every `folder` value inside the given - * folder: the trailing '/' replaced with the next code point ('0'), so a - * seek jumps past all of the folder's contents in one indexed query. - * Assumes the database orders `folder` values bytewise (binary collation), - * so nothing sorts between '/' (0x2F) and '0' (0x30). - */ - private static function seekPast(string $folder): string - { - return \substr($folder, 0, -1) . \chr(\ord('/') + 1); - } } From c564cc4a45682377e61e6b82a1d334fd7f86e037 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Wed, 22 Jul 2026 12:32:27 +0400 Subject: [PATCH 4/6] Make folder pagination collation independent --- .../Storage/Http/Buckets/Folders/XList.php | 51 ++++++++++--------- tests/e2e/Services/Storage/StorageBase.php | 13 +++-- 2 files changed, 36 insertions(+), 28 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 ca0794fdcf..da82e308a1 100644 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -99,21 +99,15 @@ class XList extends Action } $collection = 'bucket_' . $bucket->getSequence(); - $seek = $cursor === '' ? $parent : $cursor; $folders = []; + $latest = null; + $batch = 1000; try { - while (\count($folders) < $limit) { - $queries = [ - Query::greaterThan('folder', $seek), - Query::orderAsc('folder'), - Query::limit(1), - ]; - if ($seek !== $parent) { - $queries[] = Query::notStartsWith('folder', $seek); - } - if ($parent !== '') { - $queries[] = Query::startsWith('folder', $parent); + do { + $queries = [Query::limit($batch)]; + if ($latest !== null) { + $queries[] = Query::cursorAfter($latest); } if ($fileSecurity && !$valid) { @@ -126,24 +120,35 @@ class XList extends Action break; } - $fileParent = $results[0]->getAttribute('folder', ''); - $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; - $key = $parent . $segment . '/'; + foreach ($results as $file) { + $fileParent = $file->getAttribute('folder', ''); + if ($fileParent === $parent || !\str_starts_with($fileParent, $parent)) { + continue; + } - $folders[] = new Document([ - 'key' => $key, - 'name' => $segment, - 'parent' => $parent, - ]); + $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; + $key = $parent . $segment . '/'; + if ($cursor !== '' && \strcmp($key, $cursor) <= 0) { + continue; + } - $seek = $key; - } + $folders[$key] = new Document([ + 'key' => $key, + 'name' => $segment, + 'parent' => $parent, + ]); + } + + \ksort($folders, \SORT_STRING); + $folders = \array_slice($folders, 0, $limit, true); + $latest = $results[\array_key_last($results)]; + } while (\count($results) === $batch); } catch (NotFoundException) { throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); } $response->dynamic(new Document([ - 'folders' => $folders, + 'folders' => \array_values($folders), ]), Response::MODEL_FOLDER_LIST); } diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index 1c3007a803..fe35b0cfeb 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2143,6 +2143,7 @@ trait StorageBase $upload(''); $upload('invoices'); + $upload('Photos/2024'); $upload('photos/2025'); $julyFileId = $upload('photos/2026/july'); @@ -2155,12 +2156,12 @@ trait StorageBase return $response['body']['folders']; }; - // top level, alphabetical + // top level, bytewise ordering is stable across database collations $folders = $listFolders([]); - $this->assertCount(2, $folders); - $this->assertEquals(['invoices/', 'photos/'], \array_column($folders, 'key')); - $this->assertEquals(['invoices', 'photos'], \array_column($folders, 'name')); - $this->assertEquals(['', ''], \array_column($folders, 'parent')); + $this->assertCount(3, $folders); + $this->assertEquals(['Photos/', 'invoices/', 'photos/'], \array_column($folders, 'key')); + $this->assertEquals(['Photos', 'invoices', 'photos'], \array_column($folders, 'name')); + $this->assertEquals(['', '', ''], \array_column($folders, 'parent')); // nested level -- deep files imply intermediate folders $folders = $listFolders(['folder' => 'photos']); @@ -2171,6 +2172,8 @@ trait StorageBase // pagination $page = $listFolders(['limit' => 1]); + $this->assertEquals(['Photos/'], \array_column($page, 'key')); + $page = $listFolders(['limit' => 1, 'cursor' => 'Photos/']); $this->assertEquals(['invoices/'], \array_column($page, 'key')); $page = $listFolders(['limit' => 1, 'cursor' => 'invoices/']); $this->assertEquals(['photos/'], \array_column($page, 'key')); From cef8072bdea6d58b5d63ed53d2f9f9879195c7a2 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Jul 2026 15:35:03 +0400 Subject: [PATCH 5/6] 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', From ade4d4940aca1ebad610630fe202655fbbde9404 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Jul 2026 16:02:13 +0400 Subject: [PATCH 6/6] Remove folder listing endpoint --- app/init/models.php | 3 - docs/references/storage/list-folders.md | 1 - .../Storage/Http/Buckets/Folders/XList.php | 186 ------------------ .../Modules/Storage/Services/Http.php | 4 - src/Appwrite/Utopia/Response.php | 2 - src/Appwrite/Utopia/Response/Model/Folder.php | 53 ----- tests/e2e/Services/Storage/StorageBase.php | 105 ---------- .../Storage/StorageCustomClientTest.php | 46 ----- 8 files changed, 400 deletions(-) delete mode 100644 docs/references/storage/list-folders.md delete mode 100644 src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php delete mode 100644 src/Appwrite/Utopia/Response/Model/Folder.php diff --git a/app/init/models.php b/app/init/models.php index 167506f0a6..d3b776b2bd 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -80,7 +80,6 @@ use Appwrite\Utopia\Response\Model\Error; use Appwrite\Utopia\Response\Model\ErrorDev; use Appwrite\Utopia\Response\Model\Execution; use Appwrite\Utopia\Response\Model\File; -use Appwrite\Utopia\Response\Model\Folder; use Appwrite\Utopia\Response\Model\Framework; use Appwrite\Utopia\Response\Model\FrameworkAdapter; use Appwrite\Utopia\Response\Model\Func; @@ -250,7 +249,6 @@ Response::setModel(new BaseList('Identities List', Response::MODEL_IDENTITY_LIST Response::setModel(new BaseList('Notifications List', Response::MODEL_NOTIFICATION_LIST, 'notifications', Response::MODEL_NOTIFICATION)); Response::setModel(new BaseList('Logs List', Response::MODEL_LOG_LIST, 'logs', Response::MODEL_LOG)); Response::setModel(new BaseList('Files List', Response::MODEL_FILE_LIST, 'files', Response::MODEL_FILE)); -Response::setModel(new BaseList('Folders List', Response::MODEL_FOLDER_LIST, 'folders', Response::MODEL_FOLDER, paging: false)); Response::setModel(new BaseList('Buckets List', Response::MODEL_BUCKET_LIST, 'buckets', Response::MODEL_BUCKET)); Response::setModel(new BaseList('Resource Tokens List', Response::MODEL_RESOURCE_TOKEN_LIST, 'tokens', Response::MODEL_RESOURCE_TOKEN)); Response::setModel(new BaseList('Teams List', Response::MODEL_TEAM_LIST, 'teams', Response::MODEL_TEAM)); @@ -388,7 +386,6 @@ Response::setModel(new JWT()); Response::setModel(new Locale()); Response::setModel(new LocaleCode()); Response::setModel(new File()); -Response::setModel(new Folder()); Response::setModel(new Bucket()); Response::setModel(new ResourceToken()); Response::setModel(new Team()); diff --git a/docs/references/storage/list-folders.md b/docs/references/storage/list-folders.md deleted file mode 100644 index 446580b223..0000000000 --- a/docs/references/storage/list-folders.md +++ /dev/null @@ -1 +0,0 @@ -Get a list of the child folders directly inside a virtual folder in a bucket. Folders are derived from the folder paths of existing files: a folder exists while at least one file lives under it, and empty pages mean the listing is complete. diff --git a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php deleted file mode 100644 index 302cebb05c..0000000000 --- a/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php +++ /dev/null @@ -1,186 +0,0 @@ -setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/storage/buckets/:bucketId/folders') - ->desc('List folders') - ->groups(['api', 'storage']) - ->label('scope', 'files.read') - ->label('usage.resource', 'bucket/{request.bucketId}') - ->label('resourceType', RESOURCE_TYPE_BUCKETS) - ->label('sdk', new Method( - namespace: 'storage', - group: 'files', - name: 'listFolders', - 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('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') - ->inject('user') - ->callback($this->action(...)); - } - - public function action( - string $bucketId, - array $queries, - Response $response, - Database $dbForProject, - Authorization $authorization, - User $user - ) { - $bucket = $authorization->skip(fn () => $dbForProject->getDocument('buckets', $bucketId)); - - $isAPIKey = $user->isKey($authorization->getRoles()); - $isPrivilegedUser = $user->isPrivileged($authorization->getRoles()); - - if ($bucket->isEmpty() || (!$bucket->getAttribute('enabled') && !$isAPIKey && !$isPrivilegedUser)) { - throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); - } - - $fileSecurity = $bucket->getAttribute('fileSecurity', false); - $valid = $authorization->isValid(new Input(Database::PERMISSION_READ, $bucket->getRead())); - if (!$fileSecurity && !$valid) { - throw new Exception(Exception::USER_UNAUTHORIZED, $authorization->getDescription()); - } - - 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; - $batch = 1000; - - try { - do { - $batchQueries = [Query::limit($batch)]; - if ($latest !== null) { - $batchQueries[] = Query::cursorAfter($latest); - } - - if ($fileSecurity && !$valid) { - $results = $dbForProject->find($collection, $batchQueries); - } else { - $results = $authorization->skip(fn () => $dbForProject->find($collection, $batchQueries)); - } - - if (empty($results)) { - break; - } - - foreach ($results as $file) { - $fileParent = $file->getAttribute('folder', ''); - if ($fileParent === $parent || !\str_starts_with($fileParent, $parent)) { - continue; - } - - $segment = \explode('/', \substr($fileParent, \strlen($parent)))[0]; - $key = $parent . $segment . '/'; - - $folders[$key] = new Document([ - 'key' => $key, - 'name' => $segment, - 'parent' => $parent, - ]); - } - - \ksort($folders, \SORT_STRING); - $folders = \array_slice($folders, 0, $pageEnd, true); - $latest = $results[\array_key_last($results)]; - } while (\count($results) === $batch); - } catch (NotFoundException) { - throw new Exception(Exception::STORAGE_BUCKET_NOT_FOUND); - } - - $response->dynamic(new Document([ - 'folders' => \array_slice(\array_values($folders), $offset, $limit), - ]), Response::MODEL_FOLDER_LIST); - } - -} diff --git a/src/Appwrite/Platform/Modules/Storage/Services/Http.php b/src/Appwrite/Platform/Modules/Storage/Services/Http.php index dd7b8a900e..4010918205 100644 --- a/src/Appwrite/Platform/Modules/Storage/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Storage/Services/Http.php @@ -13,7 +13,6 @@ use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Push\Get as GetFileForP use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\Update as UpdateFile; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\View\Get as GetFileView; use Appwrite\Platform\Modules\Storage\Http\Buckets\Files\XList as ListFiles; -use Appwrite\Platform\Modules\Storage\Http\Buckets\Folders\XList as ListFolders; use Appwrite\Platform\Modules\Storage\Http\Buckets\Get as GetBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\Update as UpdateBucket; use Appwrite\Platform\Modules\Storage\Http\Buckets\XList as ListBuckets; @@ -42,8 +41,5 @@ class Http extends Service $this->addAction(GetFileDownload::getName(), new GetFileDownload()); $this->addAction(GetFileView::getName(), new GetFileView()); $this->addAction(GetFileForPush::getName(), new GetFileForPush()); - - // Folders - $this->addAction(ListFolders::getName(), new ListFolders()); } } diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 0a47c57423..b5d85efc9e 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -150,8 +150,6 @@ class Response extends SwooleResponse public const MODEL_FILE_LIST = 'fileList'; public const MODEL_BUCKET = 'bucket'; public const MODEL_BUCKET_LIST = 'bucketList'; - public const MODEL_FOLDER = 'folder'; - public const MODEL_FOLDER_LIST = 'folderList'; public const MODEL_RESOURCE_TOKEN = 'resourceToken'; public const MODEL_RESOURCE_TOKEN_LIST = 'resourceTokenList'; diff --git a/src/Appwrite/Utopia/Response/Model/Folder.php b/src/Appwrite/Utopia/Response/Model/Folder.php deleted file mode 100644 index 10bc40837b..0000000000 --- a/src/Appwrite/Utopia/Response/Model/Folder.php +++ /dev/null @@ -1,53 +0,0 @@ -addRule('key', [ - 'type' => self::TYPE_STRING, - 'description' => 'Full folder path, with a trailing slash.', - 'default' => '', - 'example' => 'photos/2026/', - ]) - ->addRule('name', [ - 'type' => self::TYPE_STRING, - 'description' => 'Folder name: the last segment of the path.', - 'default' => '', - 'example' => '2026', - ]) - ->addRule('parent', [ - 'type' => self::TYPE_STRING, - 'description' => 'Parent folder path with a trailing slash. Empty for top-level folders.', - 'default' => '', - 'example' => 'photos/', - ]) - ; - } - - /** - * Get Name - * - * @return string - */ - public function getName(): string - { - return 'Folder'; - } - - /** - * Get Type - * - * @return string - */ - public function getType(): string - { - return Response::MODEL_FOLDER; - } -} diff --git a/tests/e2e/Services/Storage/StorageBase.php b/tests/e2e/Services/Storage/StorageBase.php index c5250221a1..9455673468 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2111,109 +2111,4 @@ trait StorageBase $this->assertEquals(204, $response['headers']['status-code']); } - public function testListFolders(): 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 Folder Listing', - 'fileSecurity' => true, - 'permissions' => [ - Permission::read(Role::any()), - Permission::create(Role::any()), - Permission::delete(Role::any()), - ], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - $upload = function (string $folder) use ($bucketId): string { - $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'), - 'folder' => $folder, - 'permissions' => [Permission::read(Role::any()), Permission::delete(Role::any())], - ]); - $this->assertEquals(201, $file['headers']['status-code']); - return $file['body']['$id']; - }; - - $upload(''); - $upload('invoices'); - $upload('Photos/2024'); - $upload('photos/2025'); - $julyFileId = $upload('photos/2026/july'); - - $listFolders = function (array $params) use ($bucketId): array { - $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->assertEquals(200, $response['headers']['status-code']); - return $response['body']['folders']; - }; - - // top level, bytewise ordering is stable across database collations - $folders = $listFolders([]); - $this->assertCount(3, $folders); - $this->assertEquals(['Photos/', 'invoices/', 'photos/'], \array_column($folders, 'key')); - $this->assertEquals(['Photos', 'invoices', 'photos'], \array_column($folders, 'name')); - $this->assertEquals(['', '', ''], \array_column($folders, 'parent')); - - // nested level -- deep files imply intermediate folders - $folders = $listFolders(['queries' => [Query::equal('folder', ['photos'])->toString()]]); - $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); - - $folders = $listFolders(['queries' => [Query::equal('folder', ['photos/2026'])->toString()]]); - $this->assertEquals(['photos/2026/july/'], \array_column($folders, 'key')); - - // pagination - $page = $listFolders(['queries' => [Query::limit(1)->toString()]]); - $this->assertEquals(['Photos/'], \array_column($page, 'key')); - $page = $listFolders(['queries' => [Query::limit(1)->toString(), Query::offset(1)->toString()]]); - $this->assertEquals(['invoices/'], \array_column($page, 'key')); - $page = $listFolders(['queries' => [Query::limit(1)->toString(), Query::offset(2)->toString()]]); - $this->assertEquals(['photos/'], \array_column($page, 'key')); - $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(['queries' => [Query::equal('folder', ['missing'])->toString()]])); - - // unsupported and malformed queries - foreach ([ - [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()), ['queries' => $queries]); - $this->assertEquals(400, $response['headers']['status-code']); - } - - // implicit lifecycle -- deleting the last file removes the folder chain - $delete = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId . '/files/' . $julyFileId, array_merge([ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders())); - $this->assertEquals(204, $delete['headers']['status-code']); - $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', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } } diff --git a/tests/e2e/Services/Storage/StorageCustomClientTest.php b/tests/e2e/Services/Storage/StorageCustomClientTest.php index 778bf6c2f0..32c92626d5 100644 --- a/tests/e2e/Services/Storage/StorageCustomClientTest.php +++ b/tests/e2e/Services/Storage/StorageCustomClientTest.php @@ -1607,50 +1607,4 @@ final class StorageCustomClientTest extends Scope $this->assertEquals(204, $response['headers']['status-code']); } - public function testListFoldersFileSecurityVisibility(): 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' => 'Folder Visibility', - 'fileSecurity' => true, - 'permissions' => [], - ]); - $this->assertEquals(201, $bucket['headers']['status-code']); - $bucketId = $bucket['body']['$id']; - - $upload = function (string $folder, array $permissions) use ($bucketId): void { - $file = $this->client->call(Client::METHOD_POST, '/storage/buckets/' . $bucketId . '/files', [ - 'content-type' => 'multipart/form-data', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ], [ - 'fileId' => ID::unique(), - 'file' => new CURLFile(realpath(__DIR__ . '/../../../resources/logo.png'), 'image/png', 'logo.png'), - 'folder' => $folder, - 'permissions' => $permissions, - ]); - $this->assertEquals(201, $file['headers']['status-code']); - }; - - $upload('secret', []); - $upload('shared', [Permission::read(Role::any())]); - - $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())); - $this->assertEquals(200, $response['headers']['status-code']); - $this->assertSame(['shared/'], \array_column($response['body']['folders'], 'key')); - - $response = $this->client->call(Client::METHOD_DELETE, '/storage/buckets/' . $bucketId, [ - 'content-type' => 'application/json', - 'x-appwrite-project' => $this->getProject()['$id'], - 'x-appwrite-key' => $this->getProject()['apiKey'], - ]); - $this->assertEquals(204, $response['headers']['status-code']); - } }