diff --git a/app/init/models.php b/app/init/models.php index cdb2a9b9b6..411f6acc89 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; @@ -254,6 +255,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)); @@ -389,6 +391,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/docs/references/storage/list-folders.md b/docs/references/storage/list-folders.md new file mode 100644 index 0000000000..62d99808f2 --- /dev/null +++ b/docs/references/storage/list-folders.md @@ -0,0 +1 @@ +Get a list of the child folders directly inside a virtual folder in a bucket. Folders are derived from the parent 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 new file mode 100644 index 0000000000..0d67ffef1d --- /dev/null +++ b/src/Appwrite/Platform/Modules/Storage/Http/Buckets/Folders/XList.php @@ -0,0 +1,153 @@ +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('parent', '', 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 $parent, + 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($parent); + $cursor = Folder::normalize($cursor); + + if ($cursor !== '' && (!\str_starts_with($cursor, $parent) || $cursor === $parent)) { + throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, "Folder '{$cursor}' for the 'cursor' value is not inside '{$parent}'."); + } + + $collection = 'bucket_' . $bucket->getSequence(); + $seek = $cursor === '' ? $parent : self::seekPast($cursor); + $folders = []; + + try { + while (\count($folders) < $limit) { + $queries = [ + Query::greaterThan('parent', $seek), + Query::orderAsc('parent'), + Query::limit(1), + ]; + if ($parent !== '') { + $queries[] = Query::startsWith('parent', $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('parent', ''); + $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 `parent` 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. + */ + 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/Response.php b/src/Appwrite/Utopia/Response.php index e6b713d530..8494cb3705 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/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 1de9efd63a..163059be40 100644 --- a/tests/e2e/Services/Storage/StorageBase.php +++ b/tests/e2e/Services/Storage/StorageBase.php @@ -2064,4 +2064,85 @@ trait StorageBase ], $this->getHeaders()), ['parent' => '/photos']); $this->assertEquals(400, $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 $parent) 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'), + 'parent' => $parent, + '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(['parent' => 'photos']); + $this->assertEquals(['photos/2025/', 'photos/2026/'], \array_column($folders, 'key')); + + $folders = $listFolders(['parent' => '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(['parent' => 'missing'])); + + // 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(['parent' => 'photos']), 'key')); + } }