[Bug]: Files folder-tree API eagerly lists the children of every subfolder at the last requested depth, then discards them (N extra directory listings per request)

从 apps/files/lib/Controller/ApiController.php 中的 ApiController::getChildren() 开始，追踪深度检查与递归调用 getDirectoryListing() 之间的关系。Issue 提出了一个条件变更，并报告该变更在保留响应的同时，避免列出超出请求深度的内容。完成标准是端点只列出其返回的层级，且文件夹树响应保持不变。

⚠️ This issue respects the following points: ⚠️

• This is not a troubleshooting question, general support matter, or webserver/proxy problem, but likely a bug (if unsure, ask the Community Help Forum).
• This issue is not already reported on Github OR solved at the Community Help Forum (I've searched!).
• I'm using a maintained major version of Nextcloud Server and tested against the latest patch level. (Supported major versions and current patch levels).
• I agree to follow Nextcloud's Code of Conduct.
• I've tried my best to provide clear reproduction steps that someone unfamiliar with this bug could use to reproduce it.

Bug description

GET /apps/files/api/v1/folder-tree?path=<folder>&depth=1 (the endpoint behind the "Folder tree" navigation view introduced in Nextcloud 30) is O(N) in directory listings instead of O(1), where N is the number of subfolders of <folder>. Opening a folder that contains 4,140 subfolders takes ~3.0 s in the browser for this single request, while the regular PROPFIND of the same folder takes ~0.3 s.

Root cause: OCA\Files\Controller\ApiController::getChildren() calls $node->getDirectoryListing() for every subfolder before recursing, and the recursion immediately returns [] because $currentDepth >= $depth. The listing of each subfolder is therefore computed (one full directory listing per subfolder) and thrown away:

https://github.com/nextcloud/server/blob/3c5546a1a84230af62c981e9512d977656ee459c/apps/files/lib/Controller/ApiController.php#L260-L285

private function getChildren(array $nodes, int $depth = 1, int $currentDepth = 0, ?string $mimeTypeFilter = null): array {
        if ($currentDepth >= $depth) {
                return [];
        }
        …
        foreach ($nodes as $node) {
                …
                $entry = [
                        'id' => $node->getId(),
                        'basename' => $basename,
                        // line 275: the argument is evaluated eagerly — N listings — even when the callee returns [] at once
                        'children' => $this->getChildren($node->getDirectoryListing($mimeTypeFilter), $depth, $currentDepth + 1),
                ];

The same happens at every depth: with depth=2 (what the client sends when a tree node is expanded, see apps/files/src/views/folderTree.ts → getFolderTreeNodes(path, 2)) the listings of all grandchildren are computed and discarded.

Actual behavior

The endpoint performs 1 + N directory listings (N = number of subfolders). With 4,140 subfolders the request takes ~3 s (browser), the PROPFIND ~0.3 s. The folder tree view is loaded on every navigation into the folder, so this cost is paid on each click.

Measurements

Folder with 4,140 subfolders, PostgreSQL 16, PHP 8.4, local storage, warm cache:

Measurement	Before fix	After fix
Browser, folder-tree?path=…&depth=1&withParents=true (network tab)	~3.0 s	~0.2 s
Server-side harness reproducing getChildren() at depth 1, no HTTP	2.6 s (0.08 s listing + ~2.5 s discarded sub-listings)	0.08 s

Proposed fix

Only list the next level when it will actually be traversed. The response is byte-for-byte identical (the discarded listings never reached the output), so this is a pure performance fix:

--- a/apps/files/lib/Controller/ApiController.php
+++ b/apps/files/lib/Controller/ApiController.php
@@ -272,7 +272,9 @@ class ApiController extends Controller {
                        $entry = [
                                'id' => $node->getId(),
                                'basename' => $basename,
-                               'children' => $this->getChildren($node->getDirectoryListing($mimeTypeFilter), $depth, $currentDepth + 1),
+                               'children' => ($currentDepth + 1 < $depth)
+                                       ? $this->getChildren($node->getDirectoryListing($mimeTypeFilter), $depth, $currentDepth + 1)
+                                       : [],
                        ];
                        $displayName = $node->getName();
                        if ($basename !== $displayName) {

(Equivalent alternative: make getChildren() take the parent Folder and call getDirectoryListing() only after the depth check.) We have been running this one-line change in production since 2026-10-23 without any functional change. Happy to open a PR against master (and backports) if wanted.

Steps to reproduce

1. Create a folder with many subfolders (e.g. 4,000 empty or small subfolders).
2. Enable the folder tree (Files → settings → "Enable folder tree", the default).
3. Open that folder in the Files app and watch GET /index.php/apps/files/api/v1/folder-tree?path=/<folder>&depth=1&withParents=true in the browser's network tab.
4. Compare with the PROPFIND of the same folder.

Expected behavior

With depth=1, the endpoint should perform one directory listing (the folder itself). The response does not contain any grandchild data, so none should be read.

Nextcloud Server version

34

Operating system

Debian/Ubuntu

PHP engine version

PHP 8.4

Web server

Other

Database engine version

PostgreSQL

Is this bug present after an update or on a fresh install?

Fresh Nextcloud Server install

Are you using the Nextcloud Server Encryption module?

Encryption is Disabled

What user-backends are you using?

• Default user-backend (database)
• LDAP/ Active Directory
• SSO - SAML
• Other

Configuration report

List of activated Apps

Nextcloud Signing status

Nextcloud Logs

Additional info

• Nextcloud Server 34.0.3 — and the code is unchanged on master as of 2026-10-24 (3c5546a1a84230af62c981e9512d977656ee459c, line 275) and on stable34 (07b7a0f600708c90ba94ede238818c215536d4bf, line 274). Introduced by #47122 (Nextcloud 30).
• Web server: Caddy 2 (FastCGI to php-fpm), hence "Other" above. Ubuntu 24.04 LTS, PHP 8.4, PostgreSQL 16.
• The regular files list (PROPFIND) of the same folder is not affected: ~0.3 s.
• Because the tree loads on every navigation (depth=1, withParents=true) and on every node expansion (depth=2), the overhead is paid on each click in large trees.
• The frontend-side optimisations of #58273 / #58122 (reuse of the files store) do not remove the server-side cost.