dbara 20260714__py3-none-any.whl

dbara/__init__.py

@@ -0,0 +1 @@
+__version__ = "20260714"

dbara/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from dbara.cli import main
+
+sys.exit(main())

dbara/archive.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from dbara.log import Logger
+
+_GLOB_PATTERNS = (
+    "*_{app}_*.bkup.tar.zst",
+    "*_{app}_*.bkup.tar.tgz",
+    "*_{app}_*.bkup.tar.gz",
+)
+
+_ARCHIVE_DATE_RE = re.compile(r"^(.+)_(\d{8}_\d{6})\.bkup\.tar\.(zst|tgz|gz)$")
+
+
+def backup_ext(compressor: str) -> str:
+    return "zst" if compressor == "zstd" else "tgz"
+
+
+def build_archive_name(
+    app: str,
+    compressor: str,
+    optional_prefix: str = "",
+    hostname: str = "",
+    timestamp: datetime | None = None,
+) -> str:
+    """Return the backup archive filename (no directory component)."""
+    if timestamp is None:
+        timestamp = datetime.now()
+    date_str = timestamp.strftime("%Y%m%d_%H%M%S")
+    prefix_part = f"{optional_prefix}_" if optional_prefix else ""
+    ext = backup_ext(compressor)
+    return f"{hostname}_{prefix_part}{app}_{date_str}.bkup.tar.{ext}"
+
+
+def select_newest_archive(directory: Path, app: str) -> Path | None:
+    """Return the most-recently-modified backup archive for app in directory, or None."""
+    candidates: list[tuple[float, Path]] = []
+    for pattern_tmpl in _GLOB_PATTERNS:
+        for p in directory.glob(pattern_tmpl.format(app=app)):
+            if p.is_file():
+                candidates.append((p.stat().st_mtime, p))
+    if not candidates:
+        return None
+    return max(candidates, key=lambda t: t[0])[1]
+
+
+def prune_old_backups(
+    backup_dir: Path,
+    app: str,
+    keep_last: int,
+    logger: Logger,
+) -> None:
+    """Delete the oldest archives for app, keeping only the last keep_last.
+
+    Also removes associated .sha256sum and .xxh128 checksum sidecar files.
+    No-op when keep_last <= 0.
+    """
+    if keep_last <= 0:
+        return
+    logger.info(f"Pruning old backups for {app!r} (keeping last {keep_last})...")
+    archives: list[tuple[float, Path]] = []
+    for pattern_tmpl in _GLOB_PATTERNS:
+        for p in backup_dir.glob(pattern_tmpl.format(app=app)):
+            if p.is_file():
+                archives.append((p.stat().st_mtime, p))
+    archives.sort(key=lambda t: t[0])  # oldest first
+    count = len(archives)
+    if count <= keep_last:
+        logger.debug(f"Only {count} archive(s) for {app!r}; nothing to prune.")
+        return
+    for _, old in archives[: count - keep_last]:
+        logger.info(f"Pruning old backup: {old}")
+        old.unlink(missing_ok=True)
+        Path(str(old) + ".sha256sum").unlink(missing_ok=True)
+        Path(str(old) + ".xxh128").unlink(missing_ok=True)
+
+
+def list_apps_in_backup_dir(backup_dir: Path) -> list[str]:
+    """Return sorted unique app names inferred from archive filenames in backup_dir.
+
+    Parses the archive naming convention: {hostname}[_{prefix}]{app}_{YYYYMMDD_HHMMSS}.bkup.tar.EXT
+    The app name is the last underscore-delimited segment before the timestamp.
+    App names containing underscores are not supported by this auto-discovery.
+    """
+    if not backup_dir.is_dir():
+        return []
+    apps: set[str] = set()
+    for f in backup_dir.iterdir():
+        if not f.is_file():
+            continue
+        m = _ARCHIVE_DATE_RE.match(f.name)
+        if not m:
+            continue
+        stem = m.group(1)  # e.g. "hostname_prefix_appname"
+        app = stem.rsplit("_", 1)[-1]
+        if app:
+            apps.add(app)
+    return sorted(apps)

dbara/checksum.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+from dbara.log import Logger
+from dbara.runner import CommandRunner
+
+
+def hash_program(fast_hash: bool, runner: CommandRunner) -> str:
+    """Return 'xxh128sum' if fast_hash is enabled and the tool is available, else 'sha256sum'."""
+    if fast_hash and runner.tool_available("xxh128sum"):
+        return "xxh128sum"
+    return "sha256sum"
+
+
+def checksum_suffix(program: str) -> str:
+    return "xxh128" if program == "xxh128sum" else "sha256sum"
+
+
+def create_checksum_file(
+    app: str,
+    backup_path: Path,
+    base_dir: Path,
+    runner: CommandRunner,
+    logger: Logger,
+    fast_hash: bool,
+) -> Path:
+    """Generate a checksum file for all files under base_dir/app.
+
+    The file is named {backup_path}.sha256sum or {backup_path}.xxh128 and uses
+    the same format as sha256sum/xxh128sum so it can be verified externally.
+    """
+    import shlex
+
+    hasher = hash_program(fast_hash, runner)
+    suffix = checksum_suffix(hasher)
+    out_path = Path(str(backup_path) + f".{suffix}")
+    logger.info(f"Generating {hasher} checksums -> {out_path.name}")
+    # Pipe find → xargs → hasher, with output redirect — requires a shell for the pipeline.
+    # All dynamic values are shlex-quoted; none come from user input at this point.
+    shell_cmd = (
+        f"find {shlex.quote(app)} -type f -print0 "
+        f"| xargs -0 {shlex.quote(hasher)} "
+        f"> {shlex.quote(str(out_path))}"
+    )
+    runner.run_io_niced(["bash", "-c", shell_cmd], cwd=base_dir)
+    return out_path
+
+
+def verify_checksum_file(
+    base_dir: Path,
+    checksum_file: Path,
+    runner: CommandRunner,
+    logger: Logger,
+    fast_hash: bool,
+) -> bool:
+    """Verify checksum_file from base_dir.
+
+    Manifest lines are app-prefixed relative paths (see create_checksum_file),
+    so base_dir must be the directory CONTAINING the restored app directory.
+
+    Returns True if all checksums pass (or file missing — non-fatal).
+    Returns False and logs warnings on any mismatch.
+    """
+    if not checksum_file.is_file():
+        logger.warn(f"Checksum file {checksum_file} missing, skipping verification.")
+        return True
+
+    hasher = hash_program(fast_hash, runner)
+    logger.info(f"Verifying checksums with {hasher}...")
+    result = runner.run(
+        [hasher, "-c", str(checksum_file)],
+        cwd=base_dir,
+        capture_output=True,
+        check=False,
+    )
+    failed = False
+    for line in (result.stdout + result.stderr).splitlines():
+        if "FAILED" in line or "No such file" in line:
+            logger.warn(f"Checksum issue: {line}")
+            failed = True
+    return not failed
+
+
+def signature_of_dir(directory: Path) -> str:
+    """Pure-Python change-detection signature.
+
+    Walks directory, collects (relative_path, size, mtime_ns) for every file
+    sorted by path, then returns a hex SHA-256 digest. Fully unit-testable
+    without subprocess.
+
+    NOTE: Incompatible with the bash version's .sig files (which used
+    find -printf | xxh128sum). On first Python run, every app will appear
+    changed and receive one unconditional backup — safe by design.
+    """
+    h = hashlib.sha256()
+    entries: list[tuple[str, int, int]] = []
+    for dirpath, _dirs, filenames in os.walk(directory):
+        for fname in filenames:
+            full = Path(dirpath) / fname
+            try:
+                st = full.stat()
+            except OSError:
+                continue
+            rel = str(full.relative_to(directory))
+            entries.append((rel, st.st_size, st.st_mtime_ns))
+    for rel, size, mtime_ns in sorted(entries):
+        h.update(f"{rel}\x00{size}\x00{mtime_ns}\n".encode())
+    return h.hexdigest()

dbara/cli.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from dbara import __version__
+from dbara.config import Config
+from dbara.docker_ops import DockerClient
+from dbara.engine import BackupEngine, RestoreEngine
+from dbara.log import Logger
+from dbara.runner import CommandRunner
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="dbara",
+        description="Docker Backup and Restore Application",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  Backup one app:
+    dbara -m backup -a jellyfin -d /srv/apps -b /srv/backups -p prod -v
+
+  Backup all apps, keep last 7 archives each:
+    dbara -m backup -d /srv/apps -b /srv/backups -A --keep-last 7
+
+  Restore latest backup for one app:
+    dbara -m restore -a jellyfin -d /srv/apps -b /srv/backups -r /srv/apps -o 1000:1000
+
+Hooks:
+  Place executable scripts at: HOOKS_DIR/<app>/{pre-backup,post-backup,pre-restore,post-restore}
+""",
+    )
+
+    # Required
+    req = p.add_argument_group("required")
+    req.add_argument(
+        "-m", "--mode", required=True, choices=["backup", "restore"], help="Operation mode"
+    )
+    req.add_argument(
+        "-d", "--app-folder-dir", required=True, type=Path,
+        help="Parent directory containing per-app folders",
+    )
+    req.add_argument(
+        "-b", "--backup-dest-dir", required=True, type=Path,
+        help="Backup destination (directory for backup; file or directory for restore)",
+    )
+
+    # Common
+    com = p.add_argument_group("common options")
+    com.add_argument("-a", "--app-name", default="", help="Single app name")
+    com.add_argument(
+        "--apps", nargs="+", metavar="APP", default=None,
+        help="Restore a specific list of apps (restore mode only)",
+    )
+    com.add_argument(
+        "-A", "--all-apps", action="store_true",
+        help="Backup/restore all apps (backup: scans --app-folder-dir; restore: scans --backup-dest-dir)",  # noqa: E501
+    )
+    com.add_argument("-r", "--restore-dest-dir", type=Path, default=None)
+    com.add_argument(
+        "-o", "--owner-group", default="",
+        help="Set ownership after restore as user:group (overrides --ownership-map)",
+    )
+    com.add_argument("-p", "--optional-prefix", default="", help="Prefix in backup filename")
+    com.add_argument(
+        "-x", "--remove-after-backup", action="store_true",
+        help="Remove app directory after successful backup (archive integrity verified first)",
+    )
+    com.add_argument(
+        "-s", "--no-start-container", action="store_true",
+        help="Do NOT start the container after the operation completes",
+    )
+    com.add_argument(
+        "-f", "--force", action="store_true",
+        help="Force backup even when no changes are detected",
+    )
+    com.add_argument("--strict", action="store_true", help="Treat warnings as fatal errors")
+    com.add_argument(
+        "--skip-checksum", action="store_true", help="Skip checksum generation/verification"
+    )
+    com.add_argument(
+        "-v", "--verbose", action="count", default=0,
+        help="-v enables debug output; -vv additionally writes a logfile",
+    )
+
+    # Performance / behaviour
+    perf = p.add_argument_group("performance / behaviour")
+    perf.add_argument("--compress", choices=["zstd", "gzip"], default="zstd")
+    perf.add_argument(
+        "--zstd-opts", default="-T0 -3", help='Options forwarded to zstd (default: "-T0 -3")'
+    )
+    perf.add_argument(
+        "--fast-hash", action=argparse.BooleanOptionalAction, default=True,
+        help="Use xxh128sum when available (default: enabled)",
+    )
+    perf.add_argument(
+        "--io-nice", action=argparse.BooleanOptionalAction, default=True,
+        help="Wrap heavy operations with ionice+nice (default: enabled)",
+    )
+    perf.add_argument(
+        "--keep-last", type=int, default=0, metavar="N",
+        help="Keep last N backups per app and prune older ones (0 = disabled)",
+    )
+    perf.add_argument(
+        "--state-dir", type=Path, default=Path("/var/lib/app-backup/state"),
+        help="Directory for change-detection state files",
+    )
+    perf.add_argument(
+        "--hooks-dir", type=Path, default=Path("/etc/app-backup/hooks"),
+        help="Root directory for per-app hook scripts",
+    )
+    perf.add_argument(
+        "--lock-dir", type=Path, default=Path("/var/lock"),
+        help="Directory for per-app lock files (default: /var/lock)",
+    )
+    perf.add_argument("--ownership-map", type=Path, default=None, dest="ownership_map_file")
+    perf.add_argument("--stop-timeout", type=int, default=30, metavar="SEC")
+    perf.add_argument("--retry-max", type=int, default=5, metavar="N")
+    perf.add_argument("--retry-base-sleep", type=int, default=2, metavar="SEC")
+    perf.add_argument(
+        "--logfile", type=Path, default=Path("/var/log/app-backup-restore.log"),
+        help="Log file path (written when -vv is used)",
+    )
+
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _build_config(args: argparse.Namespace) -> Config:
+    return Config(
+        mode=args.mode,
+        app_name=args.app_name,
+        app_names=args.apps or [],
+        app_folder_dir=args.app_folder_dir,
+        backup_dest_dir=args.backup_dest_dir,
+        restore_dest_dir=args.restore_dest_dir,
+        remove_after_backup=args.remove_after_backup,
+        start_container=not args.no_start_container,
+        all_apps=args.all_apps,
+        force=args.force,
+        strict=args.strict,
+        skip_checksum=args.skip_checksum,
+        compressor=args.compress,
+        zstd_opts=args.zstd_opts,
+        fast_hash=args.fast_hash,
+        io_nice=args.io_nice,
+        keep_last=args.keep_last,
+        state_dir=args.state_dir,
+        hooks_dir=args.hooks_dir,
+        lock_dir=args.lock_dir,
+        ownership_map_file=args.ownership_map_file,
+        owner_group=args.owner_group,
+        optional_prefix=args.optional_prefix,
+        stop_timeout=args.stop_timeout,
+        retry_max=args.retry_max,
+        retry_base_sleep=args.retry_base_sleep,
+        verbosity=args.verbose,
+        logfile=args.logfile,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    try:
+        config = _build_config(args)
+        config.validate()
+    except ValueError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+
+    # Initialise logger
+    logfile: Path | None = config.logfile if config.verbosity >= 2 else None
+    if logfile is not None:
+        logfile.parent.mkdir(parents=True, exist_ok=True)
+    logger = Logger(verbosity=config.verbosity, strict=config.strict, logfile=logfile)
+
+    # Prerequisites
+    if not shutil.which("docker"):
+        logger.fatal("Docker is not installed or not in PATH.")
+    if config.compressor == "zstd" and not shutil.which("zstd"):
+        logger.warn("zstd not found; please install it for best performance.")
+    if not shutil.which("xxh128sum"):
+        logger.warn("xxh128sum not found; falling back to sha256sum for checksums.")
+
+    # Shared dependencies
+    try:
+        config.state_dir.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        logger.fatal(
+            f"Cannot create state directory {config.state_dir}: permission denied. "
+            f"Run with sudo or use --state-dir to specify a writable location."
+        )
+    runner = CommandRunner(config=config, logger=logger)
+    docker = DockerClient(
+        runner=runner,
+        logger=logger,
+        stop_timeout=config.stop_timeout,
+        start_container=config.start_container,
+    )
+
+    # Dispatch
+    if config.mode == "backup":
+        engine = BackupEngine(config=config, runner=runner, docker=docker, logger=logger)
+        if config.all_apps:
+            engine.backup_all_apps()
+        else:
+            # Match backup_all_apps: only restart containers that were running
+            # before the backup, so a deliberately stopped container stays stopped.
+            was_running = docker.container_exists(config.app_name) and docker.container_running(
+                config.app_name
+            )
+            docker.stop(config.app_name)
+            engine.backup_single_app(config.app_name)
+            if was_running:
+                docker.start(config.app_name)
+    else:
+        engine_r = RestoreEngine(config=config, runner=runner, docker=docker, logger=logger)
+        if config.all_apps:
+            engine_r.restore_all_apps()
+        elif config.app_names:
+            engine_r.restore_apps(config.app_names)
+        else:
+            engine_r.restore_app()
+
+    logger.info("✅ Script completed successfully!")
+    logger.print_summary()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dbara/config.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    mode: str
+    app_name: str
+    app_folder_dir: Path
+    backup_dest_dir: Path
+    restore_dest_dir: Path | None
+    remove_after_backup: bool
+    start_container: bool
+    all_apps: bool
+    force: bool
+    strict: bool
+    skip_checksum: bool
+    compressor: str
+    zstd_opts: str
+    fast_hash: bool
+    io_nice: bool
+    keep_last: int
+    state_dir: Path
+    hooks_dir: Path
+    lock_dir: Path
+    ownership_map_file: Path | None
+    owner_group: str
+    optional_prefix: str
+    stop_timeout: int
+    retry_max: int
+    retry_base_sleep: int
+    verbosity: int
+    logfile: Path
+    app_names: list[str] = field(default_factory=list)
+
+    def validate(self) -> None:
+        if self.mode not in ("backup", "restore"):
+            raise ValueError(f"Invalid mode {self.mode!r}. Must be 'backup' or 'restore'.")
+        if self.compressor not in ("zstd", "gzip"):
+            raise ValueError(f"Invalid compressor {self.compressor!r}. Must be 'zstd' or 'gzip'.")
+        if self.keep_last < 0:
+            raise ValueError(f"--keep-last must be >= 0, got {self.keep_last}.")
+        if self.stop_timeout <= 0:
+            raise ValueError(f"--stop-timeout must be > 0, got {self.stop_timeout}.")
+        if self.retry_max < 1:
+            raise ValueError(f"--retry-max must be >= 1, got {self.retry_max}.")
+        if self.retry_base_sleep < 1:
+            raise ValueError(f"--retry-base-sleep must be >= 1, got {self.retry_base_sleep}.")
+        if self.mode == "restore":
+            has_app = bool(self.app_name or self.app_names or self.all_apps)
+            if not has_app:
+                raise ValueError(
+                    "Restore mode requires --app-name (-a), --apps, or --all-apps (-A)."
+                )
+            if self.restore_dest_dir is None:
+                raise ValueError("Restore mode requires --restore-dest-dir (-r).")
+        if self.mode == "backup" and not self.all_apps and not self.app_name:
+            raise ValueError("Backup mode requires --app-name (-a) unless --all-apps is set.")
+
+
+def parse_ownership_map(map_file: Path, app: str) -> str | None:
+    """Return 'user:group' for app from an ownership map file, or None if not found."""
+    for line in map_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        if key.strip() == app and val.strip():
+            return val.strip()
+    return None

dbara/docker_ops.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dbara.log import Logger
+from dbara.runner import CommandRunner
+
+
+class DockerClient:
+    def __init__(
+        self,
+        runner: CommandRunner,
+        logger: Logger,
+        stop_timeout: int,
+        start_container: bool,
+    ) -> None:
+        self._runner = runner
+        self._logger = logger
+        self._stop_timeout = stop_timeout
+        self._start_container = start_container
+
+    def container_exists(self, name: str) -> bool:
+        result = self._runner.run(
+            ["docker", "ps", "-a", "-q", "--filter", f"name=^/{name}$"],
+            capture_output=True,
+        )
+        return bool(result.stdout.strip())
+
+    def container_running(self, name: str) -> bool:
+        result = self._runner.run(
+            ["docker", "ps", "-q", "--filter", f"name=^/{name}$"],
+            capture_output=True,
+        )
+        return bool(result.stdout.strip())
+
+    def stop(self, name: str) -> None:
+        if not self.container_exists(name):
+            self._logger.info(f"No container named {name!r} exists; skipping stop.")
+            return
+        if not self.container_running(name):
+            self._logger.info(f"Container {name!r} exists but is not running; nothing to stop.")
+            return
+        self._logger.info(f"Stopping container {name!r} (timeout {self._stop_timeout}s)...")
+        self._runner.run_with_retry(["docker", "stop", "-t", str(self._stop_timeout), name])
+
+    def start(self, name: str) -> None:
+        if not self._start_container:
+            self._logger.info("Start container disabled by user.")
+            return
+        if not self.container_exists(name):
+            self._logger.info(f"No container named {name!r} exists; skipping start.")
+            return
+        if self.container_running(name):
+            self._logger.info(f"Container {name!r} already running; no start needed.")
+            return
+        self._logger.info(f"Starting container {name!r}...")
+        self._runner.run_with_retry(["docker", "start", name])