mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
Add derived folder listing endpoint for storage buckets
This commit is contained in:
1 parent
4037de3eb5
commit
0e0a5a38e7
7 files changed
+297
No files matched your search
@@ -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());
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,153 @@
|
||||
<?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\Query;
|
||||
use Utopia\Database\Validator\Authorization;
|
||||
use Utopia\Database\Validator\Authorization\Input;
|
||||
use Utopia\Database\Validator\UID;
|
||||
use Utopia\Platform\Action;
|
||||
use Utopia\Platform\Scope\HTTP;
|
||||
use Utopia\Validator\Range;
|
||||
|
||||
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: '/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);
|
||||
}
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
<?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;
|
||||
}
|
||||
}
|
||||
@@ -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'));
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user