fix(LocalStorage): Clear realpath cache on fopen failure and re-try access

Assisted-by: ClaudeCode:claude-opus-5
Signed-off-by: David Dreschner <david.dreschner@nextcloud.com>

Author: DerDreschner

lib/private/Files/Storage/Local.php

@@ -24,6 +24,7 @@
 use OCP\Server;
 use OCP\Util;
 use Psr\Log\LoggerInterface;
+use function fopen;
 
 /**
  * for local filestore, we only have to map the paths
@@ -439,6 +440,30 @@ public function copy(string $source, string $target): bool {
 		}
 	}
 
+	/**
+	 * Invalidate the realpath cache for a path and its parents inside the data directory.
+	 *
+	 * Three narrower variants look equivalent but are not, so do not simplify this
+	 * without running testFopenRecoversFromStaleRealpathCache: naming only $sourcePath
+	 * misses the stale entry, which belongs to a parent; naming only dirname() repairs
+	 * a stale direct parent but not a stale grandparent; and omitting the name discards
+	 * the realpath cache of the entire process, every resolved source file included,
+	 * rather than the handful of entries that can be stale. Parents above the data
+	 * directory cannot change type while the process runs, so the walk stops there.
+	 */
+	private function clearRealpathCache(string $sourcePath): void {
+		$root = rtrim($this->datadir, '/');
+		$path = $sourcePath;
+		while (str_starts_with($path, $root . '/')) {
+			clearstatcache(true, $path);
+			$parent = dirname($path);
+			if ($parent === $path) {
+				return;
+			}
+			$path = $parent;
+		}
+	}
+
 	#[\Override]
 	public function fopen(string $path, string $mode) {
 		$sourcePath = $this->getSourcePath($path);
@@ -450,6 +475,17 @@ public function fopen(string $path, string $mode) {
 			$this->unlink($path);
 		}
 		$result = @fopen($sourcePath, $mode);
+		if ($result === false) {
+			// A path that was a file can turn into a directory in another process. Until
+			// realpath_cache_ttl expires, this process still has it cached as a file, and
+			// because fopen() resolves through that cache, it refuses to look inside and
+			// fails as if the file did not exist. Dropping the stale entries and opening
+			// again is what fixes that. The retry deliberately stays unsuppressed, so the
+			// global error handler reports path and reason when an open really fails. NFS
+			// clients cache the same thing below PHP, out of reach of clearstatcache().
+			$this->clearRealpathCache($sourcePath);
+			$result = fopen($sourcePath, $mode);
+		}
 		umask($oldMask);
 		return $result;
 	}

tests/lib/Files/Storage/LocalTest.php

@@ -164,4 +164,60 @@ public function testMoveNestedJail(): void {
 		$jail3->moveFromStorage($jail2, 'file.txt', 'file.txt');
 		$this->assertTrue($this->instance->file_exists('target/file.txt'));
 	}
+
+	/**
+	 * A path that changes from file to directory in another process leaves a stale
+	 * "not a directory" entry behind in the realpath cache of this process. Opening a
+	 * file below such a path then fails with ENOENT for up to realpath_cache_ttl
+	 * seconds, even though stat() reports the file as present.
+	 *
+	 * The type change has to happen out of process on purpose: PHP drops its own
+	 * realpath cache entry when it is the one calling unlink() and mkdir(), so doing
+	 * it here would leave nothing stale to recover from and the test would pass either
+	 * way. This is what made the file drop integration suite fail intermittently, one
+	 * php -S worker having cached the path while another one turned it into a folder.
+	 */
+	public static function dataStaleRealpathCache(): array {
+		return [
+			// Invalidating only the direct parent passes the first case and fails the
+			// second, so both depths have to stay covered.
+			'stale direct parent' => ['staleName' => 'folder', 'filePath' => 'folder/a.txt'],
+			'stale grandparent' => ['staleName' => 'nickname', 'filePath' => 'nickname/folder/a.txt'],
+		];
+	}
+
+	#[\PHPUnit\Framework\Attributes\DataProvider('dataStaleRealpathCache')]
+	public function testFopenRecoversFromStaleRealpathCache(string $staleName, string $filePath): void {
+		if (!function_exists('exec')) {
+			$this->markTestSkipped('exec() is required to change the path type out of process');
+		}
+
+		$stalePath = $this->tmpDir . $staleName;
+		$file = $this->tmpDir . $filePath;
+
+		// Reading it while it is still a file is what puts the "not a directory" entry
+		// into the realpath cache, so the handle is opened only for that side effect
+		$this->instance->file_put_contents($staleName, 'its a file');
+		$handle = $this->instance->fopen($staleName, 'r');
+		$this->assertIsResource($handle);
+		fclose($handle);
+
+		if ((realpath_cache_get()[$stalePath]['is_dir'] ?? null) !== false) {
+			$this->markTestSkipped('the realpath cache of this setup does not hold the directory flag');
+		}
+
+		exec(
+			'rm -f ' . escapeshellarg($stalePath)
+			. ' && mkdir -p ' . escapeshellarg(dirname($file))
+			. ' && printf abc > ' . escapeshellarg($file),
+			$output,
+			$status
+		);
+		$this->assertSame(0, $status, 'failed to replace the file with a directory');
+
+		$handle = $this->instance->fopen($filePath, 'r');
+		$this->assertIsResource($handle, 'fopen() has to recover from the stale realpath cache entry');
+		$this->assertSame('abc', stream_get_contents($handle));
+		fclose($handle);
+	}
 }