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
+172
-33
@@ -8,18 +8,28 @@ import sys
|
||||
import time
|
||||
from datetime import timedelta
|
||||
|
||||
from curateipsum import backup
|
||||
from curateipsum import backup, restore
|
||||
from curateipsum._version import version
|
||||
|
||||
_lg = logging.getLogger("curateipsum")
|
||||
SUPPORTED_PLATFORMS = ("linux", "darwin")
|
||||
_SUBCOMMANDS = ("backup", "restore")
|
||||
_TOP_LEVEL_FLAGS = ("-h", "--help", "-V", "--version")
|
||||
|
||||
|
||||
def main():
|
||||
formatter = logging.Formatter("{asctime}|{levelname}|{message}", style="{")
|
||||
console_handler = logging.StreamHandler()
|
||||
console_handler.setFormatter(formatter)
|
||||
def _normalize_argv(argv):
|
||||
"""
|
||||
Insert the implicit "backup" subcommand when argv doesn't already
|
||||
start with a known subcommand or a top-level flag (-h/-V), so
|
||||
existing invocations like `cura-te-ipsum -b DIR SRC` keep working
|
||||
unchanged now that `restore` exists alongside `backup`.
|
||||
"""
|
||||
if argv and (argv[0] in _SUBCOMMANDS or argv[0] in _TOP_LEVEL_FLAGS):
|
||||
return argv
|
||||
return ["backup", *argv]
|
||||
|
||||
|
||||
def _build_parser():
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="cura-te-ipsum",
|
||||
description="cura-te-ipsum, my personal backup software.",
|
||||
@@ -27,50 +37,83 @@ def main():
|
||||
parser.add_argument("-V", "--version",
|
||||
action="version",
|
||||
version=f"%(prog)s v{version}")
|
||||
parser.add_argument("-v", "--verbose",
|
||||
|
||||
common = argparse.ArgumentParser(add_help=False)
|
||||
common.add_argument("-v", "--verbose",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="print verbose information")
|
||||
parser.add_argument("-b",
|
||||
common.add_argument("-b",
|
||||
dest="backups_dir",
|
||||
metavar="BACKUPS_DIR",
|
||||
type=str,
|
||||
required=True,
|
||||
help="directory, where all backups will be stored")
|
||||
parser.add_argument("-n", "--dry-run",
|
||||
common.add_argument("-f", "--force",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Do not do create backup")
|
||||
parser.add_argument("-f", "--force",
|
||||
help="Wait for a running backup/restore to finish "
|
||||
"instead of exiting immediately")
|
||||
common.add_argument("-n", "--dry-run",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Wait for previous backup to finish instead of "
|
||||
"exiting immediately if one is still running")
|
||||
parser.add_argument("--external-rsync",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Use external rsync for copying")
|
||||
parser.add_argument("--external-hardlink",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Use cp command for creating hardlink copies")
|
||||
parser.add_argument("sources",
|
||||
nargs="+",
|
||||
metavar="SOURCE",
|
||||
type=str,
|
||||
help="backup source (file/dir/smth else)")
|
||||
args = parser.parse_args()
|
||||
help="show what would be done, without doing it")
|
||||
|
||||
loglevel = logging.DEBUG if args.verbose else logging.INFO
|
||||
logging.basicConfig(level=loglevel, handlers=[console_handler])
|
||||
subparsers = parser.add_subparsers(dest="command", required=True)
|
||||
|
||||
_lg.info("Starting %s: %s", parser.prog, args)
|
||||
backup_parser = subparsers.add_parser(
|
||||
"backup", parents=[common], help="create a new backup")
|
||||
backup_parser.add_argument("--external-rsync",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Use external rsync for copying")
|
||||
backup_parser.add_argument("--external-hardlink",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Use cp command for creating hardlink "
|
||||
"copies")
|
||||
backup_parser.add_argument("sources",
|
||||
nargs="+",
|
||||
metavar="SOURCE",
|
||||
type=str,
|
||||
help="backup source (file/dir/smth else)")
|
||||
|
||||
if sys.platform not in SUPPORTED_PLATFORMS:
|
||||
_lg.error("Not supported platform: %s. Supported platforms: %s",
|
||||
sys.platform, SUPPORTED_PLATFORMS)
|
||||
return 1
|
||||
restore_parser = subparsers.add_parser(
|
||||
"restore", parents=[common], help="restore a backed-up snapshot")
|
||||
restore_parser.add_argument("--snapshot",
|
||||
dest="snapshot_name",
|
||||
metavar="NAME",
|
||||
default=None,
|
||||
help="snapshot to restore, e.g. "
|
||||
"20260101_120000 (default: latest)")
|
||||
restore_parser.add_argument("--overwrite",
|
||||
choices=restore.OVERWRITE_POLICIES,
|
||||
default=restore.OVERWRITE_NEVER,
|
||||
help="what to do when a destination path "
|
||||
"already exists (default: %(default)s)")
|
||||
restore_parser.add_argument("--verify",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="verify restored content against the "
|
||||
"snapshot manifest afterwards")
|
||||
restore_parser.add_argument("dest",
|
||||
metavar="DEST",
|
||||
type=str,
|
||||
help="directory to restore into")
|
||||
restore_parser.add_argument("paths",
|
||||
nargs="*",
|
||||
metavar="PATH",
|
||||
help="restore only these snapshot-relative "
|
||||
"paths - each starts with the source "
|
||||
"directory's basename, e.g. "
|
||||
"'mydir/subdir/file.txt' for a source "
|
||||
"backed up from /home/user/mydir "
|
||||
"(default: restore everything)")
|
||||
|
||||
return parser
|
||||
|
||||
|
||||
def _run_backup(args) -> int:
|
||||
if args.external_rsync and not shutil.which("rsync"):
|
||||
_lg.error("rsync should be installed to use --external-rsync option.")
|
||||
return 1
|
||||
@@ -132,5 +175,101 @@ def main():
|
||||
return exit_code
|
||||
|
||||
|
||||
def _run_restore(args) -> int:
|
||||
backups_dir_abs = os.path.abspath(args.backups_dir)
|
||||
if not os.path.isdir(backups_dir_abs):
|
||||
_lg.error("Backup directory %s does not exist, exiting",
|
||||
args.backups_dir)
|
||||
return 1
|
||||
|
||||
dest_abs = os.path.abspath(args.dest)
|
||||
|
||||
# Locked for the same reason a backup is: retention could otherwise
|
||||
# delete or quarantine the very snapshot this restore is reading from
|
||||
# while it's still in progress. set_backups_lock() already logs why
|
||||
# (e.g. "Previous backup is still in progress") - add restore-specific
|
||||
# context here so a restore failure doesn't read like a backup one.
|
||||
if not backup.set_backups_lock(backups_dir_abs, args.force):
|
||||
_lg.error("Could not acquire the backups lock, restore aborted "
|
||||
"(use --force to wait for it instead)")
|
||||
return 1
|
||||
|
||||
exit_code = 0
|
||||
try:
|
||||
try:
|
||||
snapshot_entry = backup.find_backup(backups_dir_abs,
|
||||
args.snapshot_name)
|
||||
except backup.BackupFailedError as err:
|
||||
_lg.error("%s", err)
|
||||
return 1
|
||||
|
||||
_lg.info("Restoring snapshot %s to %s%s",
|
||||
snapshot_entry.name, args.dest,
|
||||
" (dry-run)" if args.dry_run else "")
|
||||
|
||||
if not args.dry_run:
|
||||
os.makedirs(dest_abs, exist_ok=True)
|
||||
elif not os.path.isdir(dest_abs):
|
||||
_lg.warning("Destination %s does not exist (dry-run, not "
|
||||
"creating it)", args.dest)
|
||||
|
||||
try:
|
||||
skipped = restore.restore_snapshot(
|
||||
snapshot_entry=snapshot_entry,
|
||||
dest_dir=dest_abs,
|
||||
dry_run=args.dry_run,
|
||||
overwrite=args.overwrite,
|
||||
rel_paths=args.paths or None,
|
||||
)
|
||||
except restore.RestoreError as err:
|
||||
_lg.error("Restore failed: %s", err)
|
||||
return 1
|
||||
|
||||
if skipped:
|
||||
_lg.warning("Skipped %d existing path(s) (use --overwrite "
|
||||
"always to replace them): %s",
|
||||
len(skipped), ", ".join(skipped))
|
||||
|
||||
if args.verify and not args.dry_run:
|
||||
mismatches = restore.verify_restored(
|
||||
snapshot_entry=snapshot_entry,
|
||||
dest_dir=dest_abs,
|
||||
rel_paths=args.paths or None,
|
||||
)
|
||||
if mismatches:
|
||||
_lg.error("Verification failed for %d path(s): %s",
|
||||
len(mismatches), ", ".join(mismatches))
|
||||
exit_code = 1
|
||||
else:
|
||||
_lg.info("Verified: restored content matches the manifest")
|
||||
finally:
|
||||
backup.release_backups_lock(backups_dir_abs)
|
||||
|
||||
return exit_code
|
||||
|
||||
|
||||
def main():
|
||||
formatter = logging.Formatter("{asctime}|{levelname}|{message}", style="{")
|
||||
console_handler = logging.StreamHandler()
|
||||
console_handler.setFormatter(formatter)
|
||||
|
||||
parser = _build_parser()
|
||||
args = parser.parse_args(_normalize_argv(sys.argv[1:]))
|
||||
|
||||
loglevel = logging.DEBUG if args.verbose else logging.INFO
|
||||
logging.basicConfig(level=loglevel, handlers=[console_handler])
|
||||
|
||||
_lg.info("Starting %s: %s", parser.prog, args)
|
||||
|
||||
if sys.platform not in SUPPORTED_PLATFORMS:
|
||||
_lg.error("Not supported platform: %s. Supported platforms: %s",
|
||||
sys.platform, SUPPORTED_PLATFORMS)
|
||||
return 1
|
||||
|
||||
if args.command == "restore":
|
||||
return _run_restore(args)
|
||||
return _run_backup(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user