14 files changed, 231 insertions, 254 deletions
diff --git a/lib/public/Files/Cache/AbstractCacheEvent.php b/lib/public/Files/Cache/AbstractCacheEvent.php
index 4b2daf6bfc0..b2f01b2e470 100644
--- a/lib/public/Files/Cache/AbstractCacheEvent.php
+++ b/lib/public/Files/Cache/AbstractCacheEvent.php
@@ -3,27 +3,8 @@
 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;
 
diff --git a/lib/public/Files/Cache/CacheEntryInsertedEvent.php b/lib/public/Files/Cache/CacheEntryInsertedEvent.php
index c3aa5f0a598..c3afe0f034f 100644
--- a/lib/public/Files/Cache/CacheEntryInsertedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryInsertedEvent.php
@@ -3,25 +3,8 @@
 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 f4009fde81c..d0f8c47b430 100644
--- a/lib/public/Files/Cache/CacheEntryRemovedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryRemovedEvent.php
@@ -3,25 +3,8 @@
 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 91f4d17cc6a..91dcf5340aa 100644
--- a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php
+++ b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php
@@ -3,25 +3,8 @@
 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 3c2210c964e..18a64cfb36b 100644
--- a/lib/public/Files/Cache/CacheInsertEvent.php
+++ b/lib/public/Files/Cache/CacheInsertEvent.php
@@ -3,25 +3,8 @@
 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 5903d18f965..7c2a290bd1d 100644
--- a/lib/public/Files/Cache/CacheUpdateEvent.php
+++ b/lib/public/Files/Cache/CacheUpdateEvent.php
@@ -3,25 +3,8 @@
 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 37e71f3ac79..cd610b15545 100644
--- a/lib/public/Files/Cache/ICache.php
+++ b/lib/public/Files/Cache/ICache.php
@@ -1,24 +1,9 @@
 <?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;
 
@@ -28,7 +13,7 @@ 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 Nextcloud instance and rescans files and folder when a change is detected
@@ -38,9 +23,24 @@ use OCP\Files\Search\ISearchQuery;
  * @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;
 
 	/**
@@ -219,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
@@ -231,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);
diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php
index e1e8129394c..28e673071fd 100644
--- a/lib/public/Files/Cache/ICacheEntry.php
+++ b/lib/public/Files/Cache/ICacheEntry.php
@@ -1,24 +1,9 @@
 <?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;
 
@@ -28,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';
 
 	/**
@@ -123,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
@@ -172,4 +161,12 @@ interface ICacheEntry extends ArrayAccess {
 	 * @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 87d9a3a3fe4..a5659efd4a6 100644
--- a/lib/public/Files/Cache/ICacheEvent.php
+++ b/lib/public/Files/Cache/ICacheEvent.php
@@ -3,26 +3,8 @@
 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;
 
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 0ff72cd849f..703cba59599 100644
--- a/lib/public/Files/Cache/IPropagator.php
+++ b/lib/public/Files/Cache/IPropagator.php
@@ -1,23 +1,9 @@
 <?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;
 
diff --git a/lib/public/Files/Cache/IScanner.php b/lib/public/Files/Cache/IScanner.php
index 8a45bfa6de7..9b3c283b436 100644
--- a/lib/public/Files/Cache/IScanner.php
+++ b/lib/public/Files/Cache/IScanner.php
@@ -1,24 +1,9 @@
 <?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;
 
@@ -28,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;
 
 	/**
diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php
index 5a776d4be7e..2bc702114b4 100644
--- a/lib/public/Files/Cache/IUpdater.php
+++ b/lib/public/Files/Cache/IUpdater.php
@@ -1,23 +1,9 @@
 <?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;
 
@@ -53,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
@@ -72,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 f70024247d5..62b90f672c6 100644
--- a/lib/public/Files/Cache/IWatcher.php
+++ b/lib/public/Files/Cache/IWatcher.php
@@ -1,24 +1,9 @@
 <?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;
 
@@ -28,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
 
 	/**
@@ -80,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;
 }