Remove folder listing endpoint

This commit is contained in:
Torsten Dittmann committed 2026-07-27 16:02:13 +04:00
1 parent d8c2dc0bef
commit ade4d4940a
8 files changed
-400

No files matched your search

-3
View File
@@ -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());
-1
View File
@@ -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.
@@ -1,186 +0,0 @@
<?php
namespace Appwrite\Platform\Modules\Storage\Http\Buckets\Folders;
use Appwrite\Extend\Exception;
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\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;
class XList extends Action
{
use HTTP;
public static function getName()
{
return 'listFolders';
}
public function __construct()
{
$this
->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: <<<EOT
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.
EOT,
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('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);
}
}
@@ -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());
}
}
-2
View File
@@ -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';
@@ -1,53 +0,0 @@
<?php
namespace Appwrite\Utopia\Response\Model;
use Appwrite\Utopia\Response;
use Appwrite\Utopia\Response\Model;
class Folder extends Model
{
public function __construct()
{
$this
->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;
}
}
-105
View File
@@ -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']);
}
}
@@ -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']);
}
}