deep-freeze-ctl.py

#!/usr/bin/env python3

# deep-freeze-ctl: manage backup configurations and inspect the backup DB.
#
# CRUD over `backup_client_configs` (add/list/show/delete configs, toggle
# active status, manage options and exclusions) plus read-only search over the
# files and archives that have already been backed up. All state lives in the
# local SQLite DB (see db/db.py); this tool never touches S3.

import argparse
import sys

from db import Database, ClientConfig


class FriendlyArgumentParser(argparse.ArgumentParser):
    """ArgumentParser that prints full help (not just usage) on a bad invocation.

    Subparsers created via ``add_parser`` inherit this class automatically, so
    an error in any subcommand prints that subcommand's help before the error.
    """

    def error(self, message):
        self.print_help(sys.stderr)
        self.exit(2, f"\n{self.prog}: error: {message}\n")


def _human_size(n) -> str:
    if n is None:
        return "-"
    n = float(n)
    for unit in ("B", "KB", "MB", "GB", "TB", "PB"):
        if abs(n) < 1024.0:
            return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
        n /= 1024.0
    return f"{n:.1f}EB"


def _print_table(rows, columns):
    """rows: list of dicts, columns: list of (key, header) tuples."""
    if not rows:
        print("(none)")
        return
    widths = {key: len(header) for key, header in columns}
    cells = []
    for row in rows:
        cell = {key: str(row.get(key, "")) for key, _ in columns}
        for key, _ in columns:
            widths[key] = max(widths[key], len(cell[key]))
        cells.append(cell)
    header = "  ".join(header.ljust(widths[key]) for key, header in columns)
    print(header)
    print("  ".join("-" * widths[key] for key, _ in columns))
    for cell in cells:
        print("  ".join(cell[key].ljust(widths[key]) for key, _ in columns))


# -- config add ----------------------------------------------------------

def cmd_config_add(db, args):
    options = {}
    options[ClientConfig.BACKUPS_CROSS_DEVICES] = \
        ClientConfig.YES if args.cross_devices else ClientConfig.NO
    options[ClientConfig.MANUAL_ONLY] = \
        ClientConfig.YES if args.manual_only else ClientConfig.NO
    if args.temp_directory:
        options[ClientConfig.TMP_DIR] = args.temp_directory

    if db.get_client_config(args.client_name, args.backup_root) is not None:
        print(f"Config already exists for ({args.client_name}, {args.backup_root})",
              file=sys.stderr)
        return 1

    config = ClientConfig(args.cloud_provider, args.region, args.aws_profile,
                          args.bucket, args.client_name, args.backup_root,
                          args.key_file, options, None, db)
    config.add_to_database()
    for pattern in (args.exclude or []):
        db.add_config_exclusion(args.client_name, args.backup_root, pattern)
    print(f"Added config for ({args.client_name}, {args.backup_root})")
    return 0


# -- config list ---------------------------------------------------------

def cmd_config_list(db, args):
    status = None if args.all else "active"
    configs = db.list_client_configs(status)
    for c in configs:
        c["files"] = db.count_config_files(c["client_fqdn"], c["backup_root"])
    _print_table(configs, [
        ("client_fqdn", "CLIENT"),
        ("backup_root", "BACKUP ROOT"),
        ("status", "STATUS"),
        ("bucket", "BUCKET"),
        ("region", "REGION"),
        ("files", "FILES"),
    ])
    return 0


# -- config show ---------------------------------------------------------

def cmd_config_show(db, args):
    config = db.get_client_config(args.client_name, args.backup_root)
    if config is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1

    print(f"Client:      {config['client_fqdn']}")
    print(f"Backup root: {config['backup_root']}")
    print(f"Status:      {config['status']}")
    print(f"Cloud:       {config['cloud']}  region={config['region']}  bucket={config['bucket']}")
    print(f"AWS profile: {config['credentials']}")
    print(f"Key file:    {config['key_file_path']}")
    print(f"Files known: {db.count_config_files(args.client_name, args.backup_root)}")

    print("\nOptions:")
    options = db.get_config_options(args.client_name, args.backup_root)
    if options:
        for o in options:
            print(f"  {o['key']} = {o['value']}")
    else:
        print("  (none)")

    print("\nExclusions:")
    exclusions = db.get_config_exclusions(args.client_name, args.backup_root)
    if exclusions:
        for e in exclusions:
            print(f"  {e['pattern']}")
    else:
        print("  (none)")
    return 0


# -- config delete -------------------------------------------------------

def cmd_config_delete(db, args):
    config = db.get_client_config(args.client_name, args.backup_root)
    if config is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1

    if not args.force:
        answer = input(
            f"Delete config ({args.client_name}, {args.backup_root})? "
            "File/archive history is kept. [y/N] ")
        if answer.strip().lower() not in ("y", "yes"):
            print("Aborted")
            return 1

    db.delete_client_config(args.client_name, args.backup_root)
    print(f"Deleted config ({args.client_name}, {args.backup_root})")
    return 0


# -- config enable / disable ---------------------------------------------

def _set_status(db, args, status):
    if db.get_client_config(args.client_name, args.backup_root) is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1
    db.set_client_config_status(args.client_name, args.backup_root, status)
    print(f"Config ({args.client_name}, {args.backup_root}) is now {status}")
    return 0


def cmd_config_enable(db, args):
    return _set_status(db, args, "active")


def cmd_config_disable(db, args):
    return _set_status(db, args, "inactive")


# -- config set-option / unset-option ------------------------------------

def cmd_config_set_option(db, args):
    if db.get_client_config(args.client_name, args.backup_root) is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1
    db.set_config_option(args.client_name, args.backup_root, args.key, args.value)
    print(f"Set {args.key} = {args.value}")
    return 0


def cmd_config_unset_option(db, args):
    n = db.delete_config_option(args.client_name, args.backup_root, args.key)
    print(f"Removed option {args.key}" if n else f"No such option {args.key}")
    return 0


# -- exclude add / remove / list -----------------------------------------

def cmd_exclude_add(db, args):
    if db.get_client_config(args.client_name, args.backup_root) is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1
    n = db.add_config_exclusion(args.client_name, args.backup_root, args.pattern)
    print(f"Added exclusion {args.pattern!r}" if n else "Exclusion already present")
    return 0


def cmd_exclude_remove(db, args):
    n = db.delete_config_exclusion(args.client_name, args.backup_root, args.pattern)
    print(f"Removed exclusion {args.pattern!r}" if n else "No such exclusion")
    return 0


def cmd_exclude_list(db, args):
    exclusions = db.get_config_exclusions(args.client_name, args.backup_root)
    _print_table(exclusions, [("pattern", "PATTERN")])
    return 0


# -- files search --------------------------------------------------------

def cmd_files_search(db, args):
    rows = db.search_files(args.pattern, args.client_name, args.backup_root, args.status)
    for r in rows:
        r["size_h"] = _human_size(r["size"])
    _print_table(rows, [
        ("file_id", "ID"),
        ("relative_path", "PATH"),
        ("size_h", "SIZE"),
        ("status", "STATUS"),
        ("last_archive_name", "LAST ARCHIVE"),
    ])
    print(f"\n{len(rows)} file(s)")
    return 0


# -- archives search -----------------------------------------------------

def cmd_archives_search(db, args):
    rows = db.search_archives(args.pattern, args.status, args.cloud_provider,
                              args.region, args.bucket)
    total = 0
    for r in rows:
        total += r["total_size"] or 0
        r["total_h"] = _human_size(r["total_size"])
        r["relevant_h"] = _human_size(r["relevant_size"])
    _print_table(rows, [
        ("archive_id", "ID"),
        ("archive_file_name", "ARCHIVE"),
        ("total_h", "TOTAL"),
        ("relevant_h", "RELEVANT"),
        ("status", "STATUS"),
        ("created", "CREATED"),
    ])
    print(f"\n{len(rows)} archive(s), {_human_size(total)} total")
    return 0


# -- archives refresh-candidates -----------------------------------------

def cmd_archives_refresh_candidates(db, args):
    config = db.get_client_config(args.client_name, args.backup_root)
    if config is None:
        print(f"No config for ({args.client_name}, {args.backup_root})", file=sys.stderr)
        return 1

    rows = db.get_archives_to_refresh(config["cloud"], config["region"], config["bucket"],
                                      args.client_name, args.backup_root)
    total = 0
    for r in rows:
        total += r["relevant_bytes"] or 0
        r["total_h"] = _human_size(r["total_size"])
        r["relevant_h"] = _human_size(r["relevant_bytes"])
        r["pct"] = f"{r['relevant_bytes'] * 100 / r['total_size']:.1f}%" if r["total_size"] else "-"
    _print_table(rows, [
        ("archive_id", "ID"),
        ("archive_file_name", "ARCHIVE"),
        ("total_h", "TOTAL"),
        ("relevant_h", "RELEVANT"),
        ("pct", "PCT"),
        ("created", "CREATED"),
    ])
    print(f"\n{len(rows)} candidate(s), {_human_size(total)} relevant bytes to re-upload")
    return 0


def build_parser():
    parser = FriendlyArgumentParser(
        prog="deep-freeze-ctl",
        description="Manage deep-freeze backup configurations and inspect the backup DB")
    sub = parser.add_subparsers(dest="command", required=True)

    def add_target(p):
        p.add_argument("--client-name", required=True, help="Client FQDN of the config")
        p.add_argument("--backup-root", required=True, help="Backup root directory of the config")

    # config ...
    config = sub.add_parser("config", help="Manage backup configurations")
    config_sub = config.add_subparsers(dest="subcommand", required=True)

    p_add = config_sub.add_parser("add", help="Add a new backup configuration")
    p_add.add_argument("--cloud-provider", default="aws")
    p_add.add_argument("--region", default="eu-north-1")
    p_add.add_argument("--aws-profile", required=True, help="AWS profile used for upload")
    p_add.add_argument("--bucket", required=True)
    p_add.add_argument("--client-name", required=True)
    p_add.add_argument("--backup-root", required=True)
    p_add.add_argument("--key-file", required=True, help="Path to the symmetric encryption key")
    p_add.add_argument("--cross-devices", action=argparse.BooleanOptionalAction, default=True)
    p_add.add_argument("--manual-only", action=argparse.BooleanOptionalAction, default=False)
    p_add.add_argument("--temp-directory", default=None, help="Directory for building archives")
    p_add.add_argument("--exclude", action="append", metavar="REGEX",
                       help="Exclusion pattern (repeatable)")
    p_add.set_defaults(func=cmd_config_add)

    p_list = config_sub.add_parser("list", help="List backup configurations")
    p_list.add_argument("--all", action="store_true", help="Include inactive configs")
    p_list.set_defaults(func=cmd_config_list)

    p_show = config_sub.add_parser("show", help="Show one config with options and exclusions")
    add_target(p_show)
    p_show.set_defaults(func=cmd_config_show)

    p_del = config_sub.add_parser("delete", help="Delete a config (keeps backup history)")
    add_target(p_del)
    p_del.add_argument("--force", action="store_true", help="Skip confirmation")
    p_del.set_defaults(func=cmd_config_delete)

    p_en = config_sub.add_parser("enable", help="Mark a config active")
    add_target(p_en)
    p_en.set_defaults(func=cmd_config_enable)

    p_dis = config_sub.add_parser("disable", help="Mark a config inactive")
    add_target(p_dis)
    p_dis.set_defaults(func=cmd_config_disable)

    p_so = config_sub.add_parser("set-option", help="Set a config option")
    add_target(p_so)
    p_so.add_argument("--key", required=True)
    p_so.add_argument("--value", required=True)
    p_so.set_defaults(func=cmd_config_set_option)

    p_uo = config_sub.add_parser("unset-option", help="Remove a config option")
    add_target(p_uo)
    p_uo.add_argument("--key", required=True)
    p_uo.set_defaults(func=cmd_config_unset_option)

    # exclude ...
    exclude = sub.add_parser("exclude", help="Manage a config's exclusion patterns")
    exclude_sub = exclude.add_subparsers(dest="subcommand", required=True)

    p_ea = exclude_sub.add_parser("add", help="Add an exclusion pattern")
    add_target(p_ea)
    p_ea.add_argument("--pattern", required=True, help="Python regex (fullmatch against /path)")
    p_ea.set_defaults(func=cmd_exclude_add)

    p_er = exclude_sub.add_parser("remove", help="Remove an exclusion pattern")
    add_target(p_er)
    p_er.add_argument("--pattern", required=True)
    p_er.set_defaults(func=cmd_exclude_remove)

    p_el = exclude_sub.add_parser("list", help="List exclusion patterns")
    add_target(p_el)
    p_el.set_defaults(func=cmd_exclude_list)

    # files ...
    files = sub.add_parser("files", help="Search backed-up files")
    files_sub = files.add_subparsers(dest="subcommand", required=True)
    p_fs = files_sub.add_parser("search", help="Search files in the DB")
    p_fs.add_argument("--pattern", help="SQL LIKE pattern on relative_path (e.g. %%.jpg)")
    p_fs.add_argument("--client-name", help="Filter by client FQDN")
    p_fs.add_argument("--backup-root", help="Filter by backup root")
    p_fs.add_argument("--status", choices=["present", "absent"], help="Filter by status")
    p_fs.set_defaults(func=cmd_files_search)

    # archives ...
    archives = sub.add_parser("archives", help="Search uploaded archives")
    archives_sub = archives.add_subparsers(dest="subcommand", required=True)
    p_as = archives_sub.add_parser("search", help="Search archives in the DB")
    p_as.add_argument("--pattern", help="SQL LIKE pattern on archive_file_name")
    p_as.add_argument("--status",
                      choices=["pending_upload", "uploaded", "pending_deletion", "deleted"],
                      help="Filter by status")
    p_as.add_argument("--cloud-provider", dest="cloud_provider", help="Filter by cloud")
    p_as.add_argument("--region", help="Filter by region")
    p_as.add_argument("--bucket", help="Filter by bucket")
    p_as.set_defaults(func=cmd_archives_search)

    p_arc = archives_sub.add_parser("refresh-candidates",
                                    help="List archives eligible for refresh, most eligible first")
    add_target(p_arc)
    p_arc.set_defaults(func=cmd_archives_refresh_candidates)

    return parser


if __name__ == "__main__":
    args = build_parser().parse_args()
    db = Database()
    sys.exit(args.func(db, args))