14 files changed, 287 insertions, 274 deletions
diff --git a/lib/public/Files/Cache/AbstractCacheEvent.php b/lib/public/Files/Cache/AbstractCacheEvent.php
index 31d31699804..b2f01b2e470 100644
--- a/lib/public/Files/Cache/AbstractCacheEvent.php
+++ b/lib/public/Files/Cache/AbstractCacheEvent.php
@@ -3,29 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl>
- *
- * @author Joas Schilling <coding@schilljs.com>
- * @author Robin Appelman <robin@icewind.nl>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 use OCP\EventDispatcher\Event;
diff --git a/lib/public/Files/Cache/CacheEntryInsertedEvent.php b/lib/public/Files/Cache/CacheEntryInsertedEvent.php
index 5c57103259e..c3afe0f034f 100644
--- a/lib/public/Files/Cache/CacheEntryInsertedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryInsertedEvent.php
@@ -3,27 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl>
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 /**
diff --git a/lib/public/Files/Cache/CacheEntryRemovedEvent.php b/lib/public/Files/Cache/CacheEntryRemovedEvent.php
index 92075e4282b..d0f8c47b430 100644
--- a/lib/public/Files/Cache/CacheEntryRemovedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryRemovedEvent.php
@@ -3,27 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl>
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 /**
diff --git a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php
index 94b1dd7a8b3..91dcf5340aa 100644
--- a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php
@@ -3,27 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl>
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 /**
diff --git a/lib/public/Files/Cache/CacheInsertEvent.php b/lib/public/Files/Cache/CacheInsertEvent.php
index 08ab15f9a2d..18a64cfb36b 100644
--- a/lib/public/Files/Cache/CacheInsertEvent.php
+++ b/lib/public/Files/Cache/CacheInsertEvent.php
@@ -3,27 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl>
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 /**
diff --git a/lib/public/Files/Cache/CacheUpdateEvent.php b/lib/public/Files/Cache/CacheUpdateEvent.php
index 54397045398..7c2a290bd1d 100644
--- a/lib/public/Files/Cache/CacheUpdateEvent.php
+++ b/lib/public/Files/Cache/CacheUpdateEvent.php
@@ -3,27 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl>
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 /**
diff --git a/lib/public/Files/Cache/ICache.php b/lib/public/Files/Cache/ICache.php
index 95ca29c2aa8..cd610b15545 100644
--- a/lib/public/Files/Cache/ICache.php
+++ b/lib/public/Files/Cache/ICache.php
@@ -1,46 +1,46 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
+use OCP\Files\Search\ISearchOperator;
 use OCP\Files\Search\ISearchQuery;
 
 /**
  * Metadata cache for a storage
  *
- * The cache stores the metadata for all files and folders in a storage and is kept up to date trough the following mechanisms:
+ * The cache stores the metadata for all files and folders in a storage and is kept up to date through the following mechanisms:
  *
  * - Scanner: scans the storage and updates the cache where needed
- * - Watcher: checks for changes made to the filesystem outside of the ownCloud instance and rescans files and folder when a change is detected
- * - Updater: listens to changes made to the filesystem inside of the ownCloud instance and updates the cache where needed
+ * - Watcher: checks for changes made to the filesystem outside of the Nextcloud instance and rescans files and folder when a change is detected
+ * - Updater: listens to changes made to the filesystem inside of the Nextcloud instance and updates the cache where needed
  * - ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater
  *
  * @since 9.0.0
  */
 interface ICache {
+	/**
+	 * @since 9.0.0
+	 */
 	public const NOT_FOUND = 0;
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const PARTIAL = 1; //only partial data available, file not cached in the database
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const SHALLOW = 2; //folder in cache, but not all child files are completely scanned
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const COMPLETE = 3;
 
 	/**
@@ -119,7 +119,7 @@ interface ICache {
 	/**
 	 * get the file id for a file
 	 *
-	 * A file id is a numeric id for a file or folder that's unique within an owncloud instance which stays the same for the lifetime of a file
+	 * A file id is a numeric id for a file or folder that's unique within an Nextcloud instance which stays the same for the lifetime of a file
 	 *
 	 * File ids are easiest way for apps to store references to a file since unlike paths they are not affected by renames or sharing
 	 *
@@ -180,6 +180,17 @@ interface ICache {
 	public function moveFromCache(ICache $sourceCache, $sourcePath, $targetPath);
 
 	/**
+	 * Copy a file or folder in the cache
+	 *
+	 * @param ICache $sourceCache
+	 * @param ICacheEntry $sourceEntry
+	 * @param string $targetPath
+	 * @return int fileid of copied entry
+	 * @since 22.0.0
+	 */
+	public function copyFromCache(ICache $sourceCache, ICacheEntry $sourceEntry, string $targetPath): int;
+
+	/**
 	 * Get the scan status of a file
 	 *
 	 * - ICache::NOT_FOUND: File is not in the cache
@@ -208,7 +219,7 @@ interface ICache {
 	 * search for files by mimetype
 	 *
 	 * @param string $mimetype either a full mimetype to search ('text/plain') or only the first part of a mimetype ('image')
-	 *        where it will search for all mimetypes in the group ('image/*')
+	 *                         where it will search for all mimetypes in the group ('image/*')
 	 * @return ICacheEntry[] an array of cache entries where the mimetype matches the search
 	 * @since 9.0.0
 	 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
@@ -220,7 +231,7 @@ interface ICache {
 	 *
 	 * @param ISearchQuery $query
 	 * @return ICacheEntry[]
-	 * @throw \InvalidArgumentException if the cache is unable to perform the query
+	 * @throws \InvalidArgumentException if the cache is unable to perform the query
 	 * @since 12.0.0
 	 */
 	public function searchQuery(ISearchQuery $query);
@@ -232,7 +243,7 @@ interface ICache {
 	 * use the one with the highest id gives the best result with the background scanner, since that is most
 	 * likely the folder where we stopped scanning previously
 	 *
-	 * @return string|bool the path of the folder or false when no folder matched
+	 * @return string|false the path of the folder or false when no folder matched
 	 * @since 9.0.0
 	 */
 	public function getIncomplete();
@@ -254,4 +265,30 @@ interface ICache {
 	 * @since 9.0.0
 	 */
 	public function normalize($path);
+
+	/**
+	 * Get the query expression required to filter files within this storage.
+	 *
+	 * In the most basic case this is just comparing the storage id
+	 * but storage wrappers can add additional expressions to filter down things further
+	 *
+	 * @return ISearchOperator
+	 * @since 22.0.0
+	 */
+	public function getQueryFilterForStorage(): ISearchOperator;
+
+	/**
+	 * Construct a cache entry from a search result row *if* the entry belongs to this storage.
+	 *
+	 * This method will be called for every item in the search results, including results from different storages.
+	 * It's the responsibility of this method to return `null` for all results that don't belong to this storage.
+	 *
+	 * Additionally some implementations might need to further process the resulting entry such as modifying the path
+	 * or permissions of the result.
+	 *
+	 * @param ICacheEntry $rawEntry
+	 * @return ICacheEntry|null
+	 * @since 22.0.0
+	 */
+	public function getCacheEntryFromSearchResult(ICacheEntry $rawEntry): ?ICacheEntry;
 }
diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php
index 7a0e22496e0..28e673071fd 100644
--- a/lib/public/Files/Cache/ICacheEntry.php
+++ b/lib/public/Files/Cache/ICacheEntry.php
@@ -1,26 +1,10 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
 use ArrayAccess;
@@ -29,12 +13,16 @@ use ArrayAccess;
  * meta data for a file or folder
  *
  * @since 9.0.0
+ * @template-extends ArrayAccess<string,mixed>
  *
  * This interface extends \ArrayAccess since v21.0.0, previous versions only
  * implemented it in the private implementation. Hence php would allow using the
  * object as array, while strictly speaking it didn't support this.
  */
 interface ICacheEntry extends ArrayAccess {
+	/**
+	 * @since 9.0.0
+	 */
 	public const DIRECTORY_MIMETYPE = 'httpd/unix-directory';
 
 	/**
@@ -124,8 +112,8 @@ interface ICacheEntry extends ArrayAccess {
 	public function getEtag();
 
 	/**
-	 * Get the permissions for the file stored as bitwise combination of \OCP\PERMISSION_READ, \OCP\PERMISSION_CREATE
-	 * \OCP\PERMISSION_UPDATE, \OCP\PERMISSION_DELETE and \OCP\PERMISSION_SHARE
+	 * Get the permissions for the file stored as bitwise combination of \OCP\Constants::PERMISSION_READ, \OCP\Constants::PERMISSION_CREATE
+	 * \OCP\Constants::PERMISSION_UPDATE, \OCP\Constants::PERMISSION_DELETE and \OCP\Constants::PERMISSION_SHARE
 	 *
 	 * @return int
 	 * @since 9.0.0
@@ -163,4 +151,22 @@ interface ICacheEntry extends ArrayAccess {
 	 * @since 18.0.0
 	 */
 	public function getUploadTime(): ?int;
+
+	/**
+	 * Get the unencrypted size
+	 *
+	 * This might be different from the result of getSize
+	 *
+	 * @return int
+	 * @since 25.0.0
+	 */
+	public function getUnencryptedSize(): int;
+
+	/**
+	 * Get the file id of the parent folder
+	 *
+	 * @return int
+	 * @since 32.0.0
+	 */
+	public function getParentId(): int;
 }
diff --git a/lib/public/Files/Cache/ICacheEvent.php b/lib/public/Files/Cache/ICacheEvent.php
index 56f6f46df1c..a5659efd4a6 100644
--- a/lib/public/Files/Cache/ICacheEvent.php
+++ b/lib/public/Files/Cache/ICacheEvent.php
@@ -3,28 +3,9 @@
 declare(strict_types=1);
 
 /**
- * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl>
- *
- * @author Joas Schilling <coding@schilljs.com>
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license GNU AGPL version 3 or any later version
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- *
+ * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-
 namespace OCP\Files\Cache;
 
 use OCP\Files\Storage\IStorage;
diff --git a/lib/public/Files/Cache/IFileAccess.php b/lib/public/Files/Cache/IFileAccess.php
new file mode 100644
index 00000000000..7a993d81e7a
--- /dev/null
+++ b/lib/public/Files/Cache/IFileAccess.php
@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Cache;
+
+/**
+ * Low level access to the file cache.
+ *
+ * This is intended for use cases where data from the filecache needs to be loaded, but the full filesystem apis are
+ * insufficient or too inefficient for the use-case.
+ *
+ * @since 29.0.0
+ */
+interface IFileAccess {
+	/**
+	 * Get a filecache data by file id from a specific storage.
+	 *
+	 * This is preferred over `getByFileId` when the storage id is known as it
+	 * can be more efficient in some setups.
+	 *
+	 * @param int $fileId
+	 * @param int $storageId
+	 * @return ICacheEntry|null
+	 *
+	 * @since 29.0.0
+	 */
+	public function getByFileIdInStorage(int $fileId, int $storageId): ?ICacheEntry;
+
+	/**
+	 * Get a filecache data by path and storage id.
+	 *
+	 * @param string $path
+	 * @param int $storageId
+	 * @return ICacheEntry|null
+	 *
+	 * @since 29.0.0
+	 */
+	public function getByPathInStorage(string $path, int $storageId): ?ICacheEntry;
+
+	/**
+	 * Get a filecache data by file id.
+	 *
+	 * If the storage id is known then `getByFileIdInStorage` is preferred as it can be more efficient in some setups.
+	 *
+	 * @param int $fileId
+	 * @return ICacheEntry|null
+	 *
+	 * @since 29.0.0
+	 */
+	public function getByFileId(int $fileId): ?ICacheEntry;
+
+	/**
+	 * Get filecache data by file ids.
+	 *
+	 * If the storage id is known then `getByFileIdsInStorage` is preferred as it can be more efficient in some setups.
+	 *
+	 * @param int[] $fileIds
+	 * @return array<int, ICacheEntry>
+	 *
+	 * @since 29.0.0
+	 */
+	public function getByFileIds(array $fileIds): array;
+
+	/**
+	 * Get filecache data by file ids from a specific storage.
+	 *
+	 * This is prefered over `getByFileIds` when the storage id is known as it
+	 * can be more efficient in some setups.
+	 *
+	 * @param int[] $fileIds
+	 * @param int $storageId
+	 * @return array<int, ICacheEntry>
+	 *
+	 * @since 29.0.0
+	 */
+	public function getByFileIdsInStorage(array $fileIds, int $storageId): array;
+
+	/**
+	 * Retrieves files stored in a specific storage that have a specified ancestor in the file hierarchy.
+	 * Allows filtering by mime types, encryption status, and limits the number of results.
+	 *
+	 * @param int $storageId The ID of the storage to search within.
+	 * @param int $folderId The file ID of the ancestor to base the search on.
+	 * @param int $fileIdCursor The last processed file ID. Only files with a higher ID will be included. Defaults to 0.
+	 * @param int $maxResults The maximum number of results to retrieve. If set to 0, all matching files will be retrieved.
+	 * @param list<int> $mimeTypeIds An array of mime types to filter the results. If empty, no mime type filtering will be applied.
+	 * @param bool $endToEndEncrypted Whether to include EndToEndEncrypted files
+	 * @param bool $serverSideEncrypted Whether to include ServerSideEncrypted files
+	 * @return \Generator<ICacheEntry> A generator yielding matching files as cache entries.
+	 * @throws \OCP\DB\Exception
+	 *
+	 * @since 32.0.0
+	 */
+	public function getByAncestorInStorage(int $storageId, int $folderId, int $fileIdCursor = 0, int $maxResults = 100, array $mimeTypeIds = [], bool $endToEndEncrypted = true, bool $serverSideEncrypted = true): \Generator;
+
+	/**
+	 * Retrieves a list of all distinct mounts.
+	 * Allows filtering by specific mount providers.
+	 * Optionally rewrites home directory root paths to avoid cache and trashbin.
+	 *
+	 * @param list<string> $mountProviders An array of mount provider class names to filter. If empty, all providers will be included.
+	 * @param bool $onlyUserFilesMounts Whether to rewrite the root IDs for home directories to only include user files and to only consider mounts with mount points in the user files.
+	 * @return \Generator<array{storage_id: int, root_id: int, overridden_root: int}> A generator yielding mount configurations as an array containing 'storage_id', 'root_id', and 'override_root'.
+	 * @throws \OCP\DB\Exception
+	 *
+	 * @since 32.0.0
+	 */
+	public function getDistinctMounts(array $mountProviders = [], bool $onlyUserFilesMounts = true): \Generator;
+}
diff --git a/lib/public/Files/Cache/IPropagator.php b/lib/public/Files/Cache/IPropagator.php
index e5fb875453d..703cba59599 100644
--- a/lib/public/Files/Cache/IPropagator.php
+++ b/lib/public/Files/Cache/IPropagator.php
@@ -1,25 +1,10 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
 /**
@@ -50,7 +35,8 @@ interface IPropagator {
 	/**
 	 * @param string $internalPath
 	 * @param int $time
+	 * @param int $sizeDifference
 	 * @since 9.0.0
 	 */
-	public function propagateChange($internalPath, $time);
+	public function propagateChange($internalPath, $time, $sizeDifference = 0);
 }
diff --git a/lib/public/Files/Cache/IScanner.php b/lib/public/Files/Cache/IScanner.php
index 3b00fa2af13..9b3c283b436 100644
--- a/lib/public/Files/Cache/IScanner.php
+++ b/lib/public/Files/Cache/IScanner.php
@@ -1,26 +1,10 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
 /**
@@ -29,12 +13,34 @@ namespace OCP\Files\Cache;
  * @since 9.0.0
  */
 interface IScanner {
+	/**
+	 * @since 9.0.0
+	 */
 	public const SCAN_RECURSIVE_INCOMPLETE = 2; // only recursive into not fully scanned folders
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const SCAN_RECURSIVE = true;
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const SCAN_SHALLOW = false;
 
+	/**
+	 * @since 12.0.0
+	 */
 	public const REUSE_NONE = 0;
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const REUSE_ETAG = 1;
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const REUSE_SIZE = 2;
 
 	/**
@@ -45,7 +51,7 @@ interface IScanner {
 	 * @param int $parentId
 	 * @param array | null $cacheData existing data in the cache for the file to be scanned
 	 * @param bool $lock set to false to disable getting an additional read lock during scanning
-	 * @return array an array of metadata of the scanned file
+	 * @return array | null an array of metadata of the scanned file
 	 * @throws \OC\ServerNotAvailableException
 	 * @throws \OCP\Lock\LockedException
 	 * @since 9.0.0
@@ -59,7 +65,7 @@ interface IScanner {
 	 * @param bool $recursive
 	 * @param int $reuse
 	 * @param bool $lock set to false to disable getting an additional read lock during scanning
-	 * @return array an array of the meta data of the scanned file or folder
+	 * @return array | null an array of the meta data of the scanned file or folder
 	 * @since 9.0.0
 	 */
 	public function scan($path, $recursive = self::SCAN_RECURSIVE, $reuse = -1, $lock = true);
diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php
index 7211b52a9d2..2bc702114b4 100644
--- a/lib/public/Files/Cache/IUpdater.php
+++ b/lib/public/Files/Cache/IUpdater.php
@@ -1,25 +1,10 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
 use OCP\Files\Storage\IStorage;
@@ -54,7 +39,7 @@ interface IUpdater {
 	 * @param int $time
 	 * @since 9.0.0
 	 */
-	public function update($path, $time = null);
+	public function update($path, $time = null, ?int $sizeDifference = null);
 
 	/**
 	 * Remove $path from the cache and update the size, etag and mtime of the parent folders
@@ -73,4 +58,11 @@ interface IUpdater {
 	 * @since 9.0.0
 	 */
 	public function renameFromStorage(IStorage $sourceStorage, $source, $target);
+
+	/**
+	 * Copy a file or folder in the cache and update the size, etag and mtime of the parent folders
+	 *
+	 * @since 31.0.0
+	 */
+	public function copyFromStorage(IStorage $sourceStorage, string $source, string $target): void;
 }
diff --git a/lib/public/Files/Cache/IWatcher.php b/lib/public/Files/Cache/IWatcher.php
index 9fc37c9b0ba..62b90f672c6 100644
--- a/lib/public/Files/Cache/IWatcher.php
+++ b/lib/public/Files/Cache/IWatcher.php
@@ -1,26 +1,10 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016, ownCloud, Inc.
- *
- * @author Christoph Wurst <christoph@winzerhof-wurst.at>
- * @author Robin Appelman <robin@icewind.nl>
- *
- * @license AGPL-3.0
- *
- * This code is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License, version 3,
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License, version 3,
- * along with this program. If not, see <http://www.gnu.org/licenses/>
- *
+ * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-only
  */
-
 namespace OCP\Files\Cache;
 
 /**
@@ -29,8 +13,19 @@ namespace OCP\Files\Cache;
  * @since 9.0.0
  */
 interface IWatcher {
+	/**
+	 * @since 9.0.0
+	 */
 	public const CHECK_NEVER = 0; // never check the underlying filesystem for updates
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const CHECK_ONCE = 1; // check the underlying filesystem for updates once every request for each file
+
+	/**
+	 * @since 9.0.0
+	 */
 	public const CHECK_ALWAYS = 2; // always check the underlying filesystem for updates
 
 	/**
@@ -81,4 +76,10 @@ interface IWatcher {
 	 * @since 9.0.0
 	 */
 	public function cleanFolder($path);
+
+	/**
+	 * register a callback to be called whenever the watcher triggers and update
+	 * @since 31.0.0
+	 */
+	public function onUpdate(callable $callback): void;
 }