restic-backups 0.1.1__py3-none-any.whl

restic_backups/__init__.py

@@ -0,0 +1 @@
+"""Restic backups CLI."""

restic_backups/cli.py

@@ -0,0 +1,103 @@
+"""Command-line interface for configured restic backups."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+
+from . import config as config_module
+from .errors import BackupError
+from .generic import cli as generic_cli
+from .generic import repository
+from .generic import sops as sops_module
+
+app = typer.Typer(
+    help="Configured backup commands.",
+    no_args_is_help=True,
+)
+app.add_typer(generic_cli.app, name="generic")
+
+
+@app.callback()
+def configure(
+    config_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            envvar=config_module.CONFIG_ENV,
+            dir_okay=False,
+            help=f"YAML configuration file. Env: {config_module.CONFIG_ENV}.",
+        ),
+    ] = None,
+    use_sops: Annotated[
+        bool,
+        typer.Option(
+            "--sops",
+            envvar=sops_module.SOPS_ENV,
+            help=f"Decrypt the configuration with SOPS. Env: {sops_module.SOPS_ENV}.",
+        ),
+    ] = False,
+) -> None:
+    """Configure storage before running a command."""
+    if config_file is not None:
+        os.environ[config_module.CONFIG_ENV] = str(config_file)
+    os.environ[sops_module.SOPS_ENV] = "1" if use_sops else "0"
+
+
+def fail(message: str) -> NoReturn:
+    typer.echo(f"restic-backups: {message}", err=True)
+    raise typer.Exit(1)
+
+
+def validated() -> tuple[
+    dict[str, Any],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    try:
+        return config_module.load_validated()
+    except BackupError as exc:
+        fail(str(exc))
+
+
+@app.command("check-config")
+def check_config_command() -> None:
+    """Validate configuration without contacting remote storage."""
+    validated()
+    typer.echo("config ok")
+
+
+@app.command(
+    "voice-memos",
+    context_settings={
+        "allow_extra_args": True,
+        "ignore_unknown_options": True,
+        "help_option_names": [],
+    },
+)
+def voice_memos_command(context: typer.Context) -> None:
+    """Back up, transcribe, summarise, and diarize macOS Voice Memos."""
+    if "SUMMARIES_DIR" not in os.environ and "--help" not in context.args:
+        _, credentials, stores, backups = validated()
+        try:
+            store, _ = repository.resolve("voice-memos", credentials, stores, backups)
+            path = repository.data_dir("voice-memos", store) / "summaries"
+        except BackupError as exc:
+            fail(str(exc))
+        os.environ["SUMMARIES_DIR"] = str(path)
+
+    from .voice_memos.cli import cli
+
+    cli.main(
+        args=list(context.args),
+        prog_name="restic-backups voice-memos",
+        standalone_mode=True,
+    )
+
+
+if __name__ == "__main__":
+    app()

restic_backups/config.py

@@ -0,0 +1,152 @@
+"""Load and validate backup configuration."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, NoReturn
+
+import yaml
+
+from .errors import BackupError
+from .generic import sops
+
+CONFIG_ENV = "RESTIC_BACKUPS_CONFIG"
+PLACEHOLDER = "CHANGE_ME"
+
+
+class ConfigError(Exception):
+    pass
+
+
+def fail(message: str) -> NoReturn:
+    raise BackupError(message)
+
+
+def config_path() -> Path:
+    value = os.environ.get(CONFIG_ENV)
+    if not value:
+        fail(f"set --config or {CONFIG_ENV}")
+    return Path(value).expanduser()
+
+
+def load_config(path: Path, use_sops: bool) -> dict[str, Any]:
+    if use_sops:
+        return sops.decrypt(path)
+    try:
+        loaded = yaml.safe_load(path.read_text())
+    except FileNotFoundError:
+        fail(f"config file not found: {path}")
+    except OSError as exc:
+        fail(f"could not read {path}: {exc}")
+    except yaml.YAMLError as exc:
+        fail(f"config is not valid YAML: {exc}")
+    if not isinstance(loaded, dict):
+        fail(f"config in {path} must be a mapping")
+    return loaded
+
+
+def required_text(item: dict[str, Any], field: str, owner: str) -> str:
+    value = item.get(field)
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{owner}.{field} must be a non-empty string")
+    return value
+
+
+def indexed(config: dict[str, Any], section: str) -> dict[str, dict[str, Any]]:
+    items = config.get(section)
+    if not isinstance(items, list) or not items:
+        raise ConfigError(f"{section} must be a non-empty list")
+    result: dict[str, dict[str, Any]] = {}
+    for item in items:
+        if not isinstance(item, dict):
+            raise ConfigError(f"{section} entries must be mappings")
+        item_id = required_text(item, "id", section)
+        if item_id in result:
+            raise ConfigError(f"duplicate {section} id '{item_id}'")
+        result[item_id] = item
+    return result
+
+
+def validate(
+    config: dict[str, Any],
+) -> tuple[
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    credentials = indexed(config, "credentials")
+    stores = indexed(config, "restic-stores")
+    backups = indexed(config, "backups")
+
+    for credential_id, credential in credentials.items():
+        for field in ("access-key-id", "secret-access-key"):
+            required_text(credential, field, credential_id)
+
+    for store_id, store in stores.items():
+        credential_id = required_text(store, "credentials-id", store_id)
+        store_credential = credentials.get(credential_id)
+        if store_credential is None:
+            raise ConfigError(
+                f"{store_id} references unknown credentials '{credential_id}'"
+            )
+        if not isinstance(store.get("enabled"), bool):
+            raise ConfigError(f"{store_id}.enabled must be true or false")
+        required = [
+            required_text(store, field, store_id)
+            for field in ("endpoint", "region", "bucket", "key_prefix", "password")
+        ]
+        if store["enabled"] and PLACEHOLDER in required:
+            raise ConfigError(f"{store_id} is enabled but contains placeholders")
+        if store["enabled"] and any(
+            store_credential[field] == PLACEHOLDER
+            for field in ("access-key-id", "secret-access-key")
+        ):
+            raise ConfigError(f"{store_id} uses placeholder credentials")
+
+        archive = store.get("archive")
+        if archive is None:
+            continue
+        if not isinstance(archive, dict):
+            raise ConfigError(f"{store_id}.archive must be a mapping")
+        storage_class = required_text(archive, "storage-class", f"{store_id}.archive")
+        restore = archive.get("restore")
+        if storage_class == "GLACIER_IR":
+            if restore is not None:
+                raise ConfigError(f"{store_id}: GLACIER_IR forbids a restore policy")
+            continue
+        tiers = {
+            "GLACIER": {"Standard", "Bulk", "Expedited"},
+            "DEEP_ARCHIVE": {"Standard", "Bulk"},
+        }.get(storage_class)
+        if tiers is None or not isinstance(restore, dict):
+            raise ConfigError(f"{store_id} has an invalid cold-storage policy")
+        if restore.get("tier") not in tiers:
+            raise ConfigError(f"{store_id} has an invalid retrieval tier")
+        if not isinstance(restore.get("days"), int) or restore["days"] <= 0:
+            raise ConfigError(f"{store_id}.archive.restore.days must be positive")
+        required_text(restore, "timeout", f"{store_id}.archive.restore")
+
+    for backup_id, backup in backups.items():
+        store_id = required_text(backup, "restic-store-id", backup_id)
+        if store_id not in stores:
+            raise ConfigError(
+                f"{backup_id} references unknown restic store '{store_id}'"
+            )
+
+    return credentials, stores, backups
+
+
+def load_validated() -> tuple[
+    dict[str, Any],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    path = config_path()
+    loaded = load_config(path, os.environ.get(sops.SOPS_ENV) == "1")
+    try:
+        credentials, stores, backups = validate(loaded)
+    except ConfigError as exc:
+        fail(f"invalid config in {path}: {exc}")
+    return loaded, credentials, stores, backups

restic_backups/errors.py

@@ -0,0 +1,5 @@
+"""Shared application errors."""
+
+
+class BackupError(Exception):
+    pass

restic_backups/generic/__init__.py

@@ -0,0 +1 @@
+"""Generic restic repository commands."""

restic_backups/generic/cli.py

@@ -0,0 +1,126 @@
+"""CLI for generic configured restic repositories."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Any, NoReturn
+
+import questionary
+import typer
+
+from .. import config
+from ..errors import BackupError
+from . import repository, restic
+
+app = typer.Typer(
+    help="Generic configured restic repository commands.", no_args_is_help=True
+)
+
+
+def fail(message: str) -> NoReturn:
+    typer.echo(f"restic-backups: {message}", err=True)
+    raise typer.Exit(1)
+
+
+def validated() -> tuple[
+    dict[str, Any],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    try:
+        return config.load_validated()
+    except BackupError as exc:
+        fail(str(exc))
+
+
+def choose_backup(
+    backup_id: str | None,
+    stores: dict[str, dict[str, Any]],
+    backups: dict[str, dict[str, Any]],
+) -> str:
+    if backup_id is not None:
+        if backup_id not in backups:
+            fail(f"backup '{backup_id}' not found in {config.config_path()}")
+        return backup_id
+    if not sys.stdin.isatty():
+        fail("--backup is required when stdin is not interactive")
+    choices = [
+        questionary.Choice(
+            f"{item_id}  ({stores[item['restic-store-id']]['endpoint']})",
+            value=item_id,
+        )
+        for item_id, item in backups.items()
+        if stores[item["restic-store-id"]]["enabled"]
+    ]
+    if not choices:
+        fail("no enabled backups are available")
+    selected = questionary.select("Backup:", choices=choices).ask()
+    if selected is None:
+        raise typer.Abort()
+    return str(selected)
+
+
+@app.command("list")
+def list_command() -> None:
+    """List backup IDs and their configured restic stores."""
+    _, _, stores, backups = validated()
+    for backup_id, backup in backups.items():
+        store = stores[backup["restic-store-id"]]
+        state = "enabled" if store["enabled"] else "disabled"
+        typer.echo(f"{backup_id}\t{store['id']}\t{store['endpoint']}\t{state}")
+
+
+@app.command("data-dir")
+def data_dir_command(
+    backup: str | None = typer.Argument(None, help="Backup ID; prompts when omitted."),
+) -> None:
+    """Print the managed local data directory for a backup."""
+    _, credentials, stores, backups = validated()
+    backup_id = choose_backup(backup, stores, backups)
+    try:
+        store, _ = repository.resolve(backup_id, credentials, stores, backups)
+        typer.echo(repository.data_dir(backup_id, store))
+    except BackupError as exc:
+        fail(str(exc))
+
+
+@app.command("init")
+def init_command() -> None:
+    """Initialize every enabled restic store referenced by a backup, once."""
+    _, credentials, stores, backups = validated()
+    seen: set[str] = set()
+    for backup_id, backup in backups.items():
+        store_id = backup["restic-store-id"]
+        if store_id not in seen and stores[store_id]["enabled"]:
+            seen.add(store_id)
+            try:
+                code = restic.command(backup_id, ["init"], credentials, stores, backups)
+            except BackupError as exc:
+                fail(str(exc))
+            if code:
+                raise typer.Exit(code)
+
+
+@app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run_command(
+    context: typer.Context,
+    backup: Annotated[
+        str | None,
+        typer.Option("--backup", "-b", help="Backup ID; prompts when omitted."),
+    ] = None,
+) -> None:
+    """Run restic with all trailing arguments passed through unchanged."""
+    _, credentials, stores, backups = validated()
+    backup_id = choose_backup(backup, stores, backups)
+    if not context.args:
+        fail("a restic command is required after 'run'")
+    try:
+        raise typer.Exit(
+            restic.command(backup_id, list(context.args), credentials, stores, backups)
+        )
+    except BackupError as exc:
+        fail(str(exc))

restic_backups/generic/repository.py

@@ -0,0 +1,41 @@
+"""Resolve configured repositories and managed paths."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, NoReturn
+
+from ..config import config_path
+from ..errors import BackupError
+
+ROOT = Path(__file__).resolve().parents[3]
+
+
+def fail(message: str) -> NoReturn:
+    raise BackupError(message)
+
+
+def resolve(
+    backup_id: str,
+    credentials: dict[str, dict[str, Any]],
+    stores: dict[str, dict[str, Any]],
+    backups: dict[str, dict[str, Any]],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    backup = backups.get(backup_id)
+    if backup is None:
+        fail(f"backup '{backup_id}' not found in {config_path()}")
+    store = stores[backup["restic-store-id"]]
+    if not store["enabled"]:
+        fail(f"restic store '{store['id']}' is disabled")
+    return store, credentials[store["credentials-id"]]
+
+
+def data_dir(backup_id: str, store: dict[str, Any]) -> Path:
+    key_prefix = store["key_prefix"].strip("/")
+    components = [store["id"], store["bucket"], backup_id]
+    if any(not value or value in {".", ".."} or "/" in value for value in components):
+        fail("unsafe managed data path component")
+    parts = key_prefix.split("/")
+    if any(not part or part in {".", ".."} for part in parts):
+        fail("unsafe key prefix for managed data")
+    return ROOT / "data" / components[0] / components[1] / Path(*parts) / backup_id

restic_backups/generic/restic.py

@@ -0,0 +1,92 @@
+"""Execute restic for a configured repository."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from typing import Any, NoReturn
+
+from ..errors import BackupError
+from . import repository
+
+
+def fail(message: str) -> NoReturn:
+    raise BackupError(message)
+
+
+def command(
+    backup_id: str,
+    args: list[str],
+    credentials: dict[str, dict[str, Any]],
+    stores: dict[str, dict[str, Any]],
+    backups: dict[str, dict[str, Any]],
+) -> int:
+    if not args:
+        fail("restic command required")
+    store, credential = repository.resolve(backup_id, credentials, stores, backups)
+
+    env = os.environ.copy()
+    endpoint = store["endpoint"].rstrip("/")
+    key_prefix = store["key_prefix"].strip("/")
+    env.update(
+        AWS_ACCESS_KEY_ID=credential["access-key-id"],
+        AWS_SECRET_ACCESS_KEY=credential["secret-access-key"],
+        AWS_DEFAULT_REGION=store["region"],
+        RESTIC_PASSWORD=store["password"],
+        RESTIC_REPOSITORY=(f"s3:{endpoint}/{store['bucket']}/{key_prefix}"),
+    )
+    options: list[str] = ["-o", f"s3.region={store['region']}"]
+    archive = store.get("archive")
+    if archive is not None:
+        storage_class = archive["storage-class"]
+        options.extend(("-o", f"s3.storage-class={storage_class}"))
+        if storage_class != "GLACIER_IR":
+            if args[0] in {"init", "backup"}:
+                pass
+            elif args[0] in {"check", "copy", "prune", "restore"}:
+                if os.environ.get("ALLOW_ARCHIVE_RETRIEVAL") != "1":
+                    fail(
+                        f"set ALLOW_ARCHIVE_RETRIEVAL=1 to permit {storage_class} retrieval"
+                    )
+                features = {
+                    value
+                    for value in env.get("RESTIC_FEATURES", "").split(",")
+                    if value
+                }
+                features.add("s3-restore")
+                env["RESTIC_FEATURES"] = ",".join(sorted(features))
+                restore = archive["restore"]
+                options.extend(
+                    (
+                        "-o",
+                        "s3.enable-restore=true",
+                        "-o",
+                        f"s3.restore-tier={restore['tier']}",
+                        "-o",
+                        f"s3.restore-days={restore['days']}",
+                        "-o",
+                        f"s3.restore-timeout={restore['timeout']}",
+                    )
+                )
+            else:
+                fail(f"restic command '{args[0]}' is not supported for cold S3 storage")
+
+    try:
+        with tempfile.TemporaryFile(mode="w+") as errors:
+            result = subprocess.run(
+                ["restic", *options, *args], env=env, stderr=errors, check=False
+            )
+            errors.seek(0)
+            error_text = errors.read()
+    except FileNotFoundError:
+        fail("restic is not installed")
+    print(error_text, end="", file=sys.stderr)
+    if "operation not permitted" in error_text.lower():
+        print(
+            "\nrestic was blocked by macOS. Grant the terminal Full Disk Access, "
+            "quit it fully, reopen it, and retry.",
+            file=sys.stderr,
+        )
+    return result.returncode

restic_backups/generic/sops.py

@@ -0,0 +1,30 @@
+"""Decrypt SOPS configuration files."""
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..errors import BackupError
+
+SOPS_ENV = "RESTIC_BACKUPS_SOPS"
+
+
+def decrypt(path: Path) -> dict[str, Any]:
+    try:
+        result = subprocess.run(
+            ["sops", "--decrypt", "--output-type", "json", path],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        config = json.loads(result.stdout)
+    except FileNotFoundError as exc:
+        raise BackupError("sops is not installed") from exc
+    except subprocess.CalledProcessError as exc:
+        raise BackupError(exc.stderr.strip() or f"could not decrypt {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise BackupError(f"decrypted config is not valid JSON: {exc}") from exc
+    if not isinstance(config, dict):
+        raise BackupError(f"config in {path} must be a mapping")
+    return config

restic_backups/voice_memos/__init__.py

@@ -0,0 +1 @@
+"""Voice Memos transcription and diarization tools."""