Full restore goes on where it stopped; SMB recovers from a failed read

The DR test of 1.0.2 over SMB stopped after 392 GiB of 983: the connection to the Storage Box
dropped, and the smbclient extension then returns a string of length -1 for a failed read (it
stores smbc_read()'s -1 in an unsigned length). The read loop counted that as data and went
backwards forever at 100% CPU. Reads over SMB are now checked; a failed one is read again the
usual way over a new connection.

backup:restore:full that runs again (--force) leaves the data files already in place with the
snapshot's size and modification time, as a backup takes them as unchanged, and reads ahead only
what is still missing: after 392 GiB it goes on instead of starting over.

lib/Repository/Repository.php

@@ -224,14 +224,18 @@ final class Repository {
 	 * @param array<string, string>|null $skipped salvage: an array to collect the files that could
 	 *             not be read or decrypted (path => reason), which are then left out instead of
 	 *             stopping the restore; null (default) stops at the first such file
+	 * @param bool $keepUnchanged leave a file that is already in place with the size and
+	 *             modification time of the snapshot, as a backup takes such a file as unchanged:
+	 *             a restore that was stopped and runs again goes on where it was, without reading
+	 *             what it already restored from the location again
 	 */
-	public function restore(string $snapshotId, string $target, string $prefix = '', bool $stripPrefix = false, ?callable $heartbeat = null, ?array &$skipped = null): int {
+	public function restore(string $snapshotId, string $target, string $prefix = '', bool $stripPrefix = false, ?callable $heartbeat = null, ?array &$skipped = null, bool $keepUnchanged = false): int {
 		if ($prefix !== '' && !self::isSafePath(rtrim($prefix, '/'))) {
 			throw new RepositoryException('Invalid path prefix');
 		}
-		$plan = $this->readAhead($snapshotId, $prefix, $target);
+		$plan = $this->readAhead($snapshotId, $prefix, $target, $stripPrefix, $keepUnchanged);
 		try {
-			return $this->restoreEntries($snapshotId, $target, $prefix, $stripPrefix, $heartbeat, $plan, $skipped);
+			return $this->restoreEntries($snapshotId, $target, $prefix, $stripPrefix, $heartbeat, $plan, $skipped, $keepUnchanged);
 		} finally {
 			$plan?->close();
 			if ($plan !== null) {
@@ -245,7 +249,7 @@ final class Repository {
 	 * pass over the snapshot lists the ranges of packs it needs, in order. The spool is a
 	 * folder in the target, which has room for the restore anyway.
 	 */
-	private function readAhead(string $snapshotId, string $prefix, string $target): ?ReadAheadPlan {
+	private function readAhead(string $snapshotId, string $prefix, string $target, bool $stripPrefix, bool $keepUnchanged): ?ReadAheadPlan {
 		if (!$this->backend instanceof IReadsAhead || !$this->backend->canReadAhead()) {
 			return null;
 		}
@@ -260,6 +264,9 @@ final class Repository {
 				if (!self::underPrefix($entry['p'], $prefix)) {
 					continue;
 				}
+				if ($keepUnchanged && self::inPlace(self::destination($target, $entry['p'], $prefix, $stripPrefix), $entry)) {
+					continue;
+				}
 				foreach ($entry['b'] as $id) {
 					try {
 						[$pack, $offset, $length] = $this->index->get($id);
@@ -289,18 +296,19 @@ final class Repository {
 	}
 
 	/** @param array<string, string>|null $skipped see restore() */
-	private function restoreEntries(string $snapshotId, string $target, string $prefix, bool $stripPrefix, ?callable $heartbeat, ?ReadAheadPlan $plan, ?array &$skipped): int {
+	private function restoreEntries(string $snapshotId, string $target, string $prefix, bool $stripPrefix, ?callable $heartbeat, ?ReadAheadPlan $plan, ?array &$skipped, bool $keepUnchanged): int {
 		$count = 0;
 		$cleaned = [];
 		foreach ($this->streamEntries($snapshotId) as $entry) {
 			if (!self::underPrefix($entry['p'], $prefix)) {
 				continue;
 			}
-			$relPath = $entry['p'];
-			if ($stripPrefix && $prefix !== '') {
-				$relPath = $entry['p'] === rtrim($prefix, '/') ? basename($entry['p']) : substr($entry['p'], strlen($prefix));
+			$dest = self::destination($target, $entry['p'], $prefix, $stripPrefix);
+			if ($keepUnchanged && self::inPlace($dest, $entry)) {
+				// below the target as written by an earlier run of this restore (checked then)
+				$count++;
+				continue;
 			}
-			$dest = rtrim($target, '/') . '/' . $relPath;
 			if (!is_dir(dirname($dest))) {
 				mkdir(dirname($dest), 0700, true);
 			}
@@ -358,6 +366,26 @@ final class Repository {
 		return $count;
 	}
 
+	/** Where restore() writes the snapshot path $path. */
+	private static function destination(string $target, string $path, string $prefix, bool $stripPrefix): string {
+		$relPath = $path;
+		if ($stripPrefix && $prefix !== '') {
+			$relPath = $path === rtrim($prefix, '/') ? basename($path) : substr($path, strlen($prefix));
+		}
+		return rtrim($target, '/') . '/' . $relPath;
+	}
+
+	/**
+	 * A regular file (no link) at $dest with the size and modification time of the snapshot
+	 * entry: what a backup takes as unchanged, and what a finished restore of it leaves.
+	 *
+	 * @param array{s: int, m: int, ...} $entry
+	 */
+	private static function inPlace(string $dest, array $entry): bool {
+		clearstatcache(true, $dest);
+		return !is_link($dest) && is_file($dest) && filesize($dest) === $entry['s'] && filemtime($dest) === $entry['m'];
+	}
+
 	/** $prefix is "" (everything) or ends with "/"; the path without that "/" is a file to restore too. */
 	private static function underPrefix(string $path, string $prefix): bool {
 		return $prefix === '' || str_starts_with($path, $prefix) || $path === rtrim($prefix, '/');