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,23 @@ public function copy(string $source, string $target): bool {
 		}
 	}
 
+	/**
+	 * The stale entry can belong to any parent, so naming $sourcePath or dirname() alone
+	 * is not enough, while naming nothing would drop the cache of the whole process.
+	 */
+	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 +468,14 @@ public function fopen(string $path, string $mode) {
 			$this->unlink($path);
 		}
 		$result = @fopen($sourcePath, $mode);
+		if ($result === false) {
+			// fopen() resolves through the realpath cache, so a false can just mean this
+			// process still has the path cached as a file after another one turned it into
+			// a directory, for up to realpath_cache_ttl. The retry stays unsuppressed so
+			// the global error handler reports the reason if it fails for real.
+			$this->clearRealpathCache($sourcePath);
+			$result = fopen($sourcePath, $mode);
+		}
 		umask($oldMask);
 		return $result;
 	}

tests/lib/Files/Storage/LocalTest.php

@@ -164,4 +164,51 @@ public function testMoveNestedJail(): void {
 		$jail3->moveFromStorage($jail2, 'file.txt', 'file.txt');
 		$this->assertTrue($this->instance->file_exists('target/file.txt'));
 	}
+
+	/**
+	 * The type change has to happen out of process: PHP drops its own realpath cache
+	 * entry when it is the one calling unlink() and mkdir(), so doing it here would
+	 * leave nothing stale and the test would pass either way.
+	 */
+	public static function dataStaleRealpathCache(): array {
+		return [
+			// invalidating only the direct parent passes the first and fails the second
+			'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;
+
+		// opened only to get the "not a directory" entry into the realpath cache
+		$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);
+	}
 }