Implement a restore command (#13)
* Implement restore command Add a restore subcommand alongside the existing backup command: - curateipsum/restore.py: restore_snapshot() and verify_restored(), reusing fs.scantree/copy_direntry/rm_direntry so metadata handling (mode, ownership, timestamps, symlinks) matches backup exactly. - backup.find_backup(): resolve a snapshot by name or latest. - cli.py: argparse subcommands (backup/restore), with backup implied when no subcommand is given so existing invocations keep working. Restore supports dry-run (creates nothing), partial restore by snapshot-relative path, an overwrite policy (never/always), a destination-inside-snapshot boundary check, and manifest-checksum verification of restored content. It takes the same backups_lock a backup does, since retention could otherwise delete the snapshot being restored out from under it. Closes P1 'Provide a safe restoration workflow' in IMPROVEMENTS.md. * Address Copilot review: symlink-escape boundary check, docstring fix - restore_snapshot() and verify_restored() now canonicalize each destination path and refuse to operate on it if it resolves outside dest_dir - a symlink planted under dest_dir (by another process, or left over from a prior run) could otherwise redirect a write, delete, or read outside the intended destination. - Fixed restore_snapshot()'s docstring: the skipped-paths list reports what would be skipped on dry-run too, it isn't always empty. * Address Copilot suppressed findings: stream plan_restore, restore-specific lock message - plan_restore() is now a generator instead of building a full list in memory, matching fs.scantree()'s streaming style everywhere else in the codebase. - restore CLI logs a restore-specific message on lock-acquire failure, since set_backups_lock()'s own log line talks about a 'previous backup', which read wrong for a restore. * Fix PATH docs: snapshot-relative means source-basename-prefixed README and CLI help examples for restore's PATH argument omitted the source directory's basename, which backup.initiate_backup() always prefixes onto snapshot-relative paths - the given examples would have matched nothing in an actual snapshot. --------- Co-authored-by: Maxim Shulga <maxim.shulga@alludo.com>
This commit is contained in:
snegovandMaxim Shulga authored and 
GitHub committed
1 parent
248204fe41
commit
33dcbe6c58
7 files changed
+799
-41
No files matched your search
@@ -0,0 +1,190 @@
|
||||
"""
|
||||
Module for restoring a backed-up snapshot (or a subset of its paths) to a
|
||||
destination directory.
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
from typing import Iterable, List, Optional, Tuple, Union
|
||||
|
||||
from curateipsum import backup, fs
|
||||
|
||||
_lg = logging.getLogger(__name__)
|
||||
|
||||
OVERWRITE_NEVER = "never"
|
||||
OVERWRITE_ALWAYS = "always"
|
||||
OVERWRITE_POLICIES = (OVERWRITE_NEVER, OVERWRITE_ALWAYS)
|
||||
|
||||
# Snapshot-root entries that are backup bookkeeping, not backed-up data,
|
||||
# and must never be copied out during a restore.
|
||||
_SNAPSHOT_INTERNAL_PREFIXES = (backup.BACKUP_MARKER, backup.DELTA_DIR)
|
||||
|
||||
|
||||
class RestoreError(Exception):
|
||||
"""Raised when a restore could not be completed safely or fully."""
|
||||
|
||||
|
||||
def _is_snapshot_internal(top_name: str) -> bool:
|
||||
return any(top_name.startswith(p) for p in _SNAPSHOT_INTERNAL_PREFIXES)
|
||||
|
||||
|
||||
def _under_any(relpath: str, rel_paths: List[str]) -> bool:
|
||||
return any(relpath == p or relpath.startswith(p + os.sep)
|
||||
for p in rel_paths)
|
||||
|
||||
|
||||
def plan_restore(
|
||||
snapshot_entry: Union[os.DirEntry, fs.PseudoDirEntry],
|
||||
rel_paths: Optional[List[str]] = None,
|
||||
) -> Iterable[Tuple[Union[os.DirEntry, fs.PseudoDirEntry], str]]:
|
||||
"""
|
||||
Yield (entry, relpath) pairs a restore would copy, directories before
|
||||
their contents (fs.scantree's default order, which copy_direntry()
|
||||
depends on so a directory exists before anything is written into it).
|
||||
Skips snapshot-internal bookkeeping entries (backup marker, delta
|
||||
dir). If rel_paths is given, only entries at or under one of those
|
||||
snapshot-relative paths are included.
|
||||
|
||||
A generator rather than a list: fs.scantree() already streams, and a
|
||||
snapshot can hold far more entries than comfortably fit in memory at
|
||||
once.
|
||||
"""
|
||||
for entry in fs.scantree(snapshot_entry.path):
|
||||
relpath = os.path.relpath(entry.path, snapshot_entry.path)
|
||||
top_name = relpath.split(os.sep, 1)[0]
|
||||
if _is_snapshot_internal(top_name):
|
||||
continue
|
||||
if rel_paths is not None and not _under_any(relpath, rel_paths):
|
||||
continue
|
||||
yield entry, relpath
|
||||
|
||||
|
||||
def restore_snapshot(
|
||||
snapshot_entry: Union[os.DirEntry, fs.PseudoDirEntry],
|
||||
dest_dir: str,
|
||||
dry_run: bool = False,
|
||||
overwrite: str = OVERWRITE_NEVER,
|
||||
rel_paths: Optional[List[str]] = None,
|
||||
) -> List[str]:
|
||||
"""
|
||||
Restore a completed snapshot (or a subset of its paths) into dest_dir.
|
||||
|
||||
:param overwrite: "never" (default) leaves any destination path that
|
||||
already exists untouched and reports it as skipped; "always"
|
||||
removes and replaces it.
|
||||
:param rel_paths: restrict the restore to these snapshot-relative
|
||||
paths (and anything nested under them); default restores
|
||||
everything in the snapshot.
|
||||
:return: relative paths that already existed at dest_dir under
|
||||
overwrite="never" - skipped for real, or (on dry_run) reported as
|
||||
what would be skipped.
|
||||
:raises RestoreError: if the snapshot has no manifest, dest_dir is
|
||||
inside the snapshot being restored, a destination path would
|
||||
resolve outside dest_dir (e.g. via a symlinked parent directory),
|
||||
or a copy fails partway through (the destination is left as-is;
|
||||
already-restored paths are not rolled back).
|
||||
"""
|
||||
if overwrite not in OVERWRITE_POLICIES:
|
||||
raise ValueError("Unknown overwrite policy: %r" % overwrite)
|
||||
|
||||
manifest = backup._read_manifest(
|
||||
backup._get_backup_marker(snapshot_entry).path)
|
||||
# A pre-migration (_LEGACY_MANIFEST) marker carries no checksums or
|
||||
# excluded-entries record, but the snapshot data itself is still
|
||||
# restorable - only verify_restored() needs real manifest content.
|
||||
if manifest is None:
|
||||
raise RestoreError(
|
||||
"Cannot restore %s: missing or corrupt manifest"
|
||||
% snapshot_entry.name
|
||||
)
|
||||
|
||||
dest_canon = backup._canonical(dest_dir)
|
||||
snapshot_canon = backup._canonical(snapshot_entry.path)
|
||||
if backup._is_same_or_within(dest_canon, snapshot_canon):
|
||||
raise RestoreError(
|
||||
"Refusing to restore %s into itself (destination %s is inside "
|
||||
"the snapshot)" % (snapshot_entry.name, dest_dir)
|
||||
)
|
||||
|
||||
skipped = []
|
||||
for entry, relpath in plan_restore(snapshot_entry, rel_paths):
|
||||
dst_path = os.path.join(dest_dir, relpath)
|
||||
# A symlink planted under dest_dir (by another process, or left
|
||||
# over from a previous run) could otherwise redirect lexists(),
|
||||
# rm_direntry(), or copy_direntry() below to write, delete, or
|
||||
# read through it, outside dest_dir entirely.
|
||||
dst_canon = backup._canonical(dst_path)
|
||||
if not backup._is_same_or_within(dst_canon, dest_canon):
|
||||
raise RestoreError(
|
||||
"Refusing to restore %s: resolves outside destination "
|
||||
"%s (a parent path component may be a symlink)"
|
||||
% (relpath, dest_dir)
|
||||
)
|
||||
exists = os.path.lexists(dst_path)
|
||||
if exists and overwrite == OVERWRITE_NEVER:
|
||||
_lg.info("Skipping existing %s (overwrite=%s)",
|
||||
relpath, OVERWRITE_NEVER)
|
||||
skipped.append(relpath)
|
||||
continue
|
||||
if dry_run:
|
||||
_lg.info("Would restore %s -> %s", relpath, dst_path)
|
||||
continue
|
||||
if exists:
|
||||
fs.rm_direntry(fs.PseudoDirEntry(dst_path))
|
||||
parent = os.path.dirname(dst_path)
|
||||
if parent and not os.path.isdir(parent):
|
||||
os.makedirs(parent, exist_ok=True)
|
||||
try:
|
||||
fs.copy_direntry(entry, dst_path)
|
||||
except (OSError, fs.BackupCreationError) as err:
|
||||
raise RestoreError(
|
||||
"Failed to restore %s: %s" % (relpath, err)
|
||||
) from err
|
||||
|
||||
return skipped
|
||||
|
||||
|
||||
def verify_restored(
|
||||
snapshot_entry: Union[os.DirEntry, fs.PseudoDirEntry],
|
||||
dest_dir: str,
|
||||
rel_paths: Optional[List[str]] = None,
|
||||
) -> List[str]:
|
||||
"""
|
||||
Verify restored file content at dest_dir against the checksums the
|
||||
snapshot's manifest recorded at backup time. Mirrors
|
||||
backup.verify_snapshot(), but against an arbitrary restore
|
||||
destination rather than the snapshot directory itself.
|
||||
|
||||
:return: relative paths whose restored content doesn't match the
|
||||
recorded checksum, or is missing. Empty means verified OK.
|
||||
:raises RestoreError: if the manifest itself is missing or corrupt.
|
||||
"""
|
||||
manifest = backup._read_manifest(
|
||||
backup._get_backup_marker(snapshot_entry).path)
|
||||
if manifest is None or manifest is backup._LEGACY_MANIFEST:
|
||||
raise RestoreError(
|
||||
"Cannot verify %s: missing, corrupt, or pre-migration manifest"
|
||||
% snapshot_entry.name
|
||||
)
|
||||
|
||||
dest_canon = backup._canonical(dest_dir)
|
||||
mismatches = []
|
||||
for relpath, expected_digest in manifest.get("checksums", {}).items():
|
||||
if rel_paths is not None and not _under_any(relpath, rel_paths):
|
||||
continue
|
||||
full_path = os.path.join(dest_dir, relpath)
|
||||
# Same symlink-escape concern as restore_snapshot(): don't let a
|
||||
# planted symlink under dest_dir make this hash a file outside it.
|
||||
full_canon = backup._canonical(full_path)
|
||||
if not backup._is_same_or_within(full_canon, dest_canon):
|
||||
_lg.error("Refusing to verify %s: resolves outside "
|
||||
"destination %s", relpath, dest_dir)
|
||||
mismatches.append(relpath)
|
||||
continue
|
||||
try:
|
||||
actual_digest = backup._sha256_file(full_path)
|
||||
except OSError:
|
||||
mismatches.append(relpath)
|
||||
continue
|
||||
if actual_digest != expected_digest:
|
||||
mismatches.append(relpath)
|
||||
return mismatches
|
||||
Reference in new issue
Block a user