M3: restore files and folders (occ backup:browse, backup:restore)

User files are restored through the Files API so the file cache, versions and trash stay consistent: modes new-folder (default, into 'Restored <date>/<path>'), merge (overwritten files keep their old content as a version) and replace (extra files go to the trash). Each file is staged under a temporary name and moved into place only after all its blobs were verified. Any snapshot path can also be restored raw to a local directory (disaster recovery). Tested on NC34: all three modes restore checksum-identical files, the overwritten content is kept as a version, the extra file is in the trash, no temporary files remain.
2026-10-02 00:58:18 +02:00
parent 05e2c9fe45
commit ebd9737f51
5 changed files with 357 additions and 2 deletions
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Command;
+
+use OCA\NgBackup\Service\RestoreService;
+use OCA\NgBackup\Service\TargetService;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Helper\Table;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Browse extends Command {
+	public function __construct(
+		private TargetService $targets,
+		private RestoreService $restore,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure(): void {
+		$this->setName('backup:browse')
+			->setDescription('Show folders and files in a snapshot')
+			->addArgument('target', InputArgument::REQUIRED, 'Location name or id')
+			->addArgument('snapshot', InputArgument::REQUIRED, 'Snapshot id (see backup:list)')
+			->addArgument('path', InputArgument::OPTIONAL, 'Path in the snapshot, e.g. data/alice/files/Documents', '')
+			->setHelp("Top level: config/ and data/. User files are under data/<user>/files/.\n\nExample:\n  occ backup:browse offsite 537bf7e9... data/alice/files");
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		try {
+			$items = $this->restore->browse($this->targets->get($input->getArgument('target')), $input->getArgument('snapshot'), (string)$input->getArgument('path'));
+		} catch (\Throwable $e) {
+			$output->writeln('<error>' . $e->getMessage() . '</error>');
+			return 1;
+		}
+		if ($items === []) {
+			$output->writeln('Nothing here.');
+			return 0;
+		}
+		$rows = array_map(fn ($i) => [$i['type'] === 'dir' ? $i['name'] . '/' : $i['name'], $this->size($i['size']),
+			$i['type'] === 'dir' ? $i['files'] . ' files' : date('Y-m-d H:i', (int)$i['mtime'])], $items);
+		(new Table($output))->setHeaders(['name', 'size', 'files / modified'])->setRows($rows)->render();
+		return 0;
+	}
+
+	private function size(int $b): string {
+		foreach (['B', 'KiB', 'MiB', 'GiB', 'TiB'] as $u) {
+			if ($b < 1024 || $u === 'TiB') {
+				return $u === 'B' ? "$b B" : sprintf('%.1f %s', $b, $u);
+			}
+			$b /= 1024;
+		}
+		return '';
+	}
+}
@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Command;
+
+use OCA\NgBackup\Service\RestoreService;
+use OCA\NgBackup\Service\TargetService;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Restore extends Command {
+	public function __construct(
+		private TargetService $targets,
+		private RestoreService $restore,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure(): void {
+		$this->setName('backup:restore')
+			->setDescription('Restore files or folders from a snapshot')
+			->addArgument('target', InputArgument::REQUIRED, 'Location name or id')
+			->addArgument('snapshot', InputArgument::REQUIRED, 'Snapshot id (see backup:list)')
+			->addArgument('path', InputArgument::REQUIRED, 'Path in the snapshot (see backup:browse)')
+			->addOption('mode', 'm', InputOption::VALUE_REQUIRED, 'new-folder, merge or replace (user files)', RestoreService::MODE_NEW_FOLDER)
+			->addOption('to-directory', 'd', InputOption::VALUE_REQUIRED, 'Write to this local directory instead (any path, raw files)')
+			->setHelp(<<<'HELP'
+User files (data/<user>/files/...) are restored through Nextcloud, so versions, trash and the
+file cache stay correct. Modes:
+  new-folder  (default) into "Restored <date>/<same path>" in the user's files; nothing existing is touched
+  merge       into the original place; overwritten files keep their old content as a version
+  replace     like merge, and files that are not in the snapshot are moved to the trash
+
+Examples:
+  occ backup:restore offsite 537bf7e9... data/alice/files/Documents
+  occ backup:restore offsite 537bf7e9... data/alice/files/Documents/plan.odt --mode=merge
+  occ backup:restore offsite 537bf7e9... config --to-directory=/root/restored-config
+HELP);
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		try {
+			$target = $this->targets->get($input->getArgument('target'));
+			$snapshot = $input->getArgument('snapshot');
+			$path = $input->getArgument('path');
+			if ($dir = $input->getOption('to-directory')) {
+				$n = $this->restore->restoreToDirectory($target, $snapshot, $path, $dir);
+				$output->writeln("Restored <info>$n</info> files to $dir.");
+				return 0;
+			}
+			$r = $this->restore->restoreUserFiles($target, $snapshot, $path, (string)$input->getOption('mode'),
+				function (int $done, int $total, string $name) use ($output) {
+					if ($output->isVerbose() || $done === $total || $done % 100 === 0) {
+						$output->writeln("  $done/$total $name");
+					}
+				});
+		} catch (\Throwable $e) {
+			$output->writeln('<error>' . $e->getMessage() . '</error>');
+			return 1;
+		}
+		$output->writeln(sprintf('Restored <info>%d</info> files to %s%s.', $r['restored'], $r['target'], $r['trashed'] ? ", moved {$r['trashed']} extra files to the trash" : ''));
+		return 0;
+	}
+}