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.
This commit is contained in:
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,221 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
// SPDX-FileCopyrightText: 2026 Dillard Blom
|
||||
// SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
|
||||
namespace OCA\NgBackup\Service;
|
||||
|
||||
use OCA\NgBackup\Db\Target;
|
||||
use OCA\NgBackup\Repository\Repository;
|
||||
use OCP\Files\File;
|
||||
use OCP\Files\Folder;
|
||||
use OCP\Files\IRootFolder;
|
||||
use OCP\Files\NotFoundException;
|
||||
|
||||
/**
|
||||
* Restoring from a snapshot.
|
||||
*
|
||||
* User files (data/<uid>/files/...) are written through the Nextcloud Files API, so the file
|
||||
* cache, versions and trash stay consistent: an overwritten file becomes a version and a
|
||||
* removed file goes to the trash, which makes a restore itself reversible. Every file is
|
||||
* written to a temporary name first and only renamed into place after all its blobs were
|
||||
* decrypted and verified.
|
||||
*
|
||||
* Modes for user files:
|
||||
* - new-folder (default): into "Restored <date>/<same path>", nothing existing is touched
|
||||
* - merge: into the original place, existing files are overwritten (old content kept as a version)
|
||||
* - replace: like merge, and files that are not in the snapshot are moved to the trash
|
||||
*/
|
||||
class RestoreService {
|
||||
public const MODE_NEW_FOLDER = 'new-folder';
|
||||
public const MODE_MERGE = 'merge';
|
||||
public const MODE_REPLACE = 'replace';
|
||||
|
||||
public function __construct(
|
||||
private TargetService $targets,
|
||||
private IRootFolder $root,
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Direct children (files and folders) of a path in a snapshot.
|
||||
*
|
||||
* @return list<array{name:string, type:string, size:int, mtime:int|null, files:int}>
|
||||
*/
|
||||
public function browse(Target $target, string $snapshotId, string $path = ''): array {
|
||||
$prefix = trim($path, '/');
|
||||
$prefix = $prefix === '' ? '' : $prefix . '/';
|
||||
$children = [];
|
||||
foreach ($this->targets->repository($target)->entries($snapshotId) as $e) {
|
||||
if ($prefix !== '' && !str_starts_with($e['p'], $prefix)) {
|
||||
continue;
|
||||
}
|
||||
$rest = substr($e['p'], strlen($prefix));
|
||||
[$name, $more] = array_pad(explode('/', $rest, 2), 2, null);
|
||||
$c = $children[$name] ?? ['name' => $name, 'type' => $more === null ? 'file' : 'dir', 'size' => 0, 'mtime' => null, 'files' => 0];
|
||||
$c['size'] += $e['s'];
|
||||
$c['files']++;
|
||||
if ($more === null) {
|
||||
$c['mtime'] = $e['m'];
|
||||
}
|
||||
$children[$name] = $c;
|
||||
}
|
||||
ksort($children, SORT_STRING);
|
||||
return array_values($children);
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore user files from "data/<uid>/files[/<path>]" into that user's Nextcloud files.
|
||||
*
|
||||
* @return array{restored:int, trashed:int, target:string}
|
||||
*/
|
||||
public function restoreUserFiles(Target $target, string $snapshotId, string $logicalPath, string $mode = self::MODE_NEW_FOLDER, ?callable $progress = null): array {
|
||||
if (!preg_match('#^data/([^/]+)/files(?:/(.*))?$#', trim($logicalPath, '/'), $m)) {
|
||||
throw new \InvalidArgumentException('Expected a path like data/<user>/files/<folder or file>');
|
||||
}
|
||||
[$uid, $rel] = [$m[1], trim($m[2] ?? '', '/')];
|
||||
$userFolder = $this->root->getUserFolder($uid);
|
||||
$repo = $this->targets->repository($target);
|
||||
$source = 'data/' . $uid . '/files' . ($rel === '' ? '' : '/' . $rel);
|
||||
|
||||
$entries = [];
|
||||
$single = false;
|
||||
foreach ($repo->entries($snapshotId) as $e) {
|
||||
if ($e['p'] === $source) {
|
||||
$single = true;
|
||||
$entries[''] = $e;
|
||||
break;
|
||||
}
|
||||
if (str_starts_with($e['p'], $source . '/')) {
|
||||
$entries[substr($e['p'], strlen($source) + 1)] = $e;
|
||||
}
|
||||
}
|
||||
if ($entries === []) {
|
||||
throw new NotFoundException("Nothing at $source in snapshot $snapshotId");
|
||||
}
|
||||
|
||||
// Where to write. new-folder mirrors the path under "Restored <date>" in the user's root.
|
||||
$parentRel = $single ? (dirname($rel) === '.' ? '' : dirname($rel)) : $rel;
|
||||
if ($mode === self::MODE_NEW_FOLDER) {
|
||||
$parentRel = trim('Restored ' . date('Y-m-d H.i') . '/' . $parentRel, '/');
|
||||
} elseif ($mode !== self::MODE_MERGE && $mode !== self::MODE_REPLACE) {
|
||||
throw new \InvalidArgumentException("Unknown mode $mode");
|
||||
}
|
||||
$dest = $this->ensureFolder($userFolder, $parentRel);
|
||||
$names = $single ? [basename($rel) => $entries['']] : $entries;
|
||||
|
||||
$restored = 0;
|
||||
foreach ($names as $relPath => $entry) {
|
||||
$this->writeFile($repo, $dest, (string)$relPath, $entry);
|
||||
$restored++;
|
||||
if ($progress !== null) {
|
||||
$progress($restored, count($names), (string)$relPath);
|
||||
}
|
||||
}
|
||||
|
||||
$trashed = 0;
|
||||
if ($mode === self::MODE_REPLACE && !$single) {
|
||||
$trashed = $this->trashExtras($dest, '', array_flip(array_keys($names)));
|
||||
}
|
||||
return ['restored' => $restored, 'trashed' => $trashed, 'target' => $uid . ':' . $userFolder->getRelativePath($dest->getPath())];
|
||||
}
|
||||
|
||||
/** Raw restore of any snapshot path to a local directory (administrators, disaster recovery). */
|
||||
public function restoreToDirectory(Target $target, string $snapshotId, string $prefix, string $directory): int {
|
||||
if (!is_dir($directory) && !mkdir($directory, 0750, true) && !is_dir($directory)) {
|
||||
throw new \RuntimeException("Cannot create $directory");
|
||||
}
|
||||
return $this->targets->repository($target)->restore($snapshotId, $directory, trim($prefix, '/') === '' ? '' : trim($prefix, '/') . '/');
|
||||
}
|
||||
|
||||
private function writeFile(Repository $repo, Folder $dest, string $relPath, array $entry): void {
|
||||
$dir = dirname($relPath);
|
||||
$folder = $dir === '.' ? $dest : $this->ensureFolder($dest, $dir);
|
||||
$name = basename($relPath);
|
||||
// Stage under a temporary name; only rename into place after every blob was verified.
|
||||
$tmpName = '.' . $name . '.ngb-restore-' . bin2hex(random_bytes(3));
|
||||
$tmp = $folder->newFile($tmpName);
|
||||
try {
|
||||
$out = $tmp->fopen('wb');
|
||||
$written = 0;
|
||||
foreach ($repo->readBlobs($entry['b']) as $data) { // each blob is verified on read
|
||||
if (fwrite($out, $data) !== strlen($data)) {
|
||||
throw new \RuntimeException('Write failed for ' . $relPath);
|
||||
}
|
||||
$written += strlen($data);
|
||||
}
|
||||
if (!fclose($out)) {
|
||||
throw new \RuntimeException('Write failed for ' . $relPath);
|
||||
}
|
||||
if ($written !== $entry['s']) {
|
||||
throw new \RuntimeException("Size mismatch restoring $relPath");
|
||||
}
|
||||
if ($folder->nodeExists($name)) {
|
||||
$existing = $folder->get($name);
|
||||
if (!$existing instanceof File) {
|
||||
throw new \RuntimeException("$relPath exists and is not a file");
|
||||
}
|
||||
// Overwrite through the Files API: the current content becomes a version.
|
||||
$in = $tmp->fopen('rb');
|
||||
$existing->putContent($in);
|
||||
if (is_resource($in)) {
|
||||
fclose($in);
|
||||
}
|
||||
$tmp->delete();
|
||||
$existing->touch($entry['m']);
|
||||
} else {
|
||||
$tmp->move($folder->getPath() . '/' . $name);
|
||||
$folder->get($name)->touch($entry['m']);
|
||||
}
|
||||
} catch (\Throwable $e) {
|
||||
try {
|
||||
$tmp->delete();
|
||||
} catch (\Throwable) {
|
||||
}
|
||||
throw $e;
|
||||
}
|
||||
}
|
||||
|
||||
private function trashExtras(Folder $folder, string $prefix, array $keep): int {
|
||||
$count = 0;
|
||||
foreach ($folder->getDirectoryListing() as $node) {
|
||||
$rel = $prefix === '' ? $node->getName() : $prefix . '/' . $node->getName();
|
||||
if ($node instanceof Folder) {
|
||||
$hasKept = false;
|
||||
foreach (array_keys($keep) as $k) {
|
||||
if (str_starts_with((string)$k, $rel . '/')) {
|
||||
$hasKept = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if ($hasKept) {
|
||||
$count += $this->trashExtras($node, $rel, $keep);
|
||||
} else {
|
||||
$node->delete(); // to the trash
|
||||
$count++;
|
||||
}
|
||||
} elseif (!isset($keep[$rel])) {
|
||||
$node->delete();
|
||||
$count++;
|
||||
}
|
||||
}
|
||||
return $count;
|
||||
}
|
||||
|
||||
private function ensureFolder(Folder $base, string $path): Folder {
|
||||
$path = trim($path, '/');
|
||||
if ($path === '' || $path === '.') {
|
||||
return $base;
|
||||
}
|
||||
if ($base->nodeExists($path)) {
|
||||
$node = $base->get($path);
|
||||
if (!$node instanceof Folder) {
|
||||
throw new \RuntimeException("$path exists and is not a folder");
|
||||
}
|
||||
return $node;
|
||||
}
|
||||
return $base->newFolder($path);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user