feat: add interface to get only a single node by id instead of all nodes for the id

this should be enough in most(?) cases and makes efficient implementation and caching easier

Signed-off-by: Robin Appelman <robin@icewind.nl>

lib/private/Files/Node/Folder.php

@@ -307,12 +307,16 @@ class Folder extends Node implements \OCP\Files\Folder {
 
 	/**
 	 * @param int $id
-	 * @return \OC\Files\Node\Node[]
+	 * @return \OCP\Files\Node[]
 	 */
 	public function getById($id) {
 		return $this->root->getByIdInPath((int)$id, $this->getPath());
 	}
 
+	public function getFirstNodeById(int $id): ?\OCP\Files\Node {
+		return current($this->getById($id));
+	}
+
 	protected function getAppDataDirectoryName(): string {
 		$instanceId = \OC::$server->getConfig()->getSystemValueString('instanceid');
 		return 'appdata_' . $instanceId;

lib/private/Files/Node/LazyFolder.php

@@ -492,7 +492,11 @@ class LazyFolder implements Folder {
 	 * @inheritDoc
 	 */
 	public function getById($id) {
-		return $this->__call(__FUNCTION__, func_get_args());
+		return $this->getRootFolder()->getByIdInPath((int)$id, $this->getPath());
+	}
+
+	public function getFirstNodeById(int $id): ?\OCP\Files\Node {
+		return $this->getRootFolder()->getFirstNodeByIdInPath($id, $this->getPath());
 	}
 
 	/**

lib/private/Files/Node/LazyRoot.php

@@ -25,6 +25,7 @@ namespace OC\Files\Node;
 use OCP\Files\Cache\ICacheEntry;
 use OCP\Files\IRootFolder;
 use OCP\Files\Mount\IMountPoint;
+use OCP\Files\Node;
 use OCP\Files\Node as INode;
 
 /**
@@ -56,6 +57,10 @@ class LazyRoot extends LazyFolder implements IRootFolder {
 		return $this->__call(__FUNCTION__, func_get_args());
 	}
 
+	public function getFirstNodeByIdInPath(int $id, string $path): ?Node {
+		return $this->__call(__FUNCTION__, func_get_args());
+	}
+
 	public function getNodeFromCacheEntryAndMount(ICacheEntry $cacheEntry, IMountPoint $mountPoint): INode {
 		return $this->getRootFolder()->getNodeFromCacheEntryAndMount($cacheEntry, $mountPoint);
 	}

lib/private/Files/Node/LazyUserFolder.php

@@ -68,18 +68,6 @@ class LazyUserFolder extends LazyFolder {
 		]);
 	}
 
-	public function get($path) {
-		return $this->getRootFolder()->get('/' . $this->user->getUID() . '/files/' . ltrim($path, '/'));
-	}
-
-	/**
-	 * @param int $id
-	 * @return \OCP\Files\Node[]
-	 */
-	public function getById($id) {
-		return $this->getRootFolder()->getByIdInPath((int)$id, $this->getPath());
-	}
-
 	public function getMountPoint() {
 		if ($this->folder !== null) {
 			return $this->folder->getMountPoint();

lib/private/Files/Node/NonExistingFolder.php

@@ -162,6 +162,10 @@ class NonExistingFolder extends Folder {
 		throw new NotFoundException();
 	}
 
+	public function getFirstNodeById(int $id): ?\OCP\Files\Node {
+		throw new NotFoundException();
+	}
+
 	public function getFreeSpace() {
 		throw new NotFoundException();
 	}

lib/private/Files/Node/Root.php

@@ -405,6 +405,10 @@ class Root extends Folder implements IRootFolder {
 		return $this->userMountCache;
 	}
 
+	public function getFirstNodeByIdInPath(int $id, string $path): ?INode {
+		return current($this->getByIdInPath($id, $path));
+	}
+
 	/**
 	 * @param int $id
 	 * @return Node[]

lib/public/Files/Folder.php

@@ -152,17 +152,37 @@ interface Folder extends Node {
 	public function searchBySystemTag(string $tagName, string $userId, int $limit = 0, int $offset = 0);
 
 	/**
-	 * get a file or folder inside the folder by it's internal id
+	 * get a file or folder inside the folder by its internal id
 	 *
 	 * This method could return multiple entries. For example once the file/folder
 	 * is shared or mounted (files_external) to the user multiple times.
 	 *
+	 * Note that the different entries can have different permissions.
+	 *
 	 * @param int $id
 	 * @return \OCP\Files\Node[]
 	 * @since 6.0.0
 	 */
 	public function getById($id);
 
+	/**
+	 * get a file or folder inside the folder by its internal id
+	 *
+	 * Unlike getById, this method only returns a single node even if the user has
+	 * access to the file with the requested id multiple times.
+	 *
+	 * This method provides no guarantee about which of the nodes in returned and the
+	 * returned node might, for example, have less permissions than other nodes for the same file
+	 *
+	 * Apps that require accurate information about the users access to the file should use getById
+	 * instead of pick the correct node out of the result.
+	 *
+	 * @param int $id
+	 * @return Node|null
+	 * @since 29.0.0
+	 */
+	public function getFirstNodeById(int $id): ?Node;
+
 	/**
 	 * Get the amount of free space inside the folder
 	 *

lib/public/Files/IRootFolder.php

@@ -59,6 +59,24 @@ interface IRootFolder extends Folder, Emitter {
 	 */
 	public function getByIdInPath(int $id, string $path);
 
+	/**
+	 * get a file or folder inside the folder by its internal id
+	 *
+	 * Unlike getByIdInPath, this method only returns a single node even if the user has
+	 * access to the file with the requested id multiple times.
+	 *
+	 * This method provides no guarantee about which of the nodes in returned and the
+	 * returned node might, for example, have less permissions than other nodes for the same file
+	 *
+	 * Apps that require accurate information about the users access to the file should use getByIdInPath
+	 * instead of pick the correct node out of the result.
+	 *
+	 * @param int $id
+	 * @return Node|null
+	 * @since 29.0.0
+	 */
+	public function getFirstNodeByIdInPath(int $id, string $path): ?Node;
+
 	/**
 	 * @return IMountPoint[]
 	 *