restic-profile-cli 0.2.0__py3-none-any.whl

restic_profile/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("restic-profile-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

restic_profile/__main__.py

@@ -0,0 +1,4 @@
+from restic_profile.cli import main
+
+if __name__ == "__main__":
+    main()

restic_profile/cli.py

@@ -0,0 +1,204 @@
+# PYTHON_ARGCOMPLETE_OK
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import argcomplete
+from chaos_utils.logging import setup_logger
+from pydantic import ValidationError
+
+from .config import load_config
+from .runner import WorkflowError, run_profile, run_unlock
+
+logger = setup_logger(__name__)
+
+DEFAULT_CONFIG = Path("/etc/restic-profile/restic-profile.toml")
+
+
+def _load_config_or_exit(config_path: Path):
+    """Return the parsed config or exit with a logged error."""
+    try:
+        return load_config(config_path)
+    except FileNotFoundError as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+    except (ValidationError, ValueError) as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+
+
+def _resolve_profile_or_exit(args: argparse.Namespace):
+    """Return the named profile from *args* or exit with a logged error."""
+    cfg = _load_config_or_exit(args.config)
+
+    if not args.profile_name:
+        raise ValueError("profile_name is required")
+
+    if args.profile_name not in cfg.profiles:
+        logger.error(
+            "Profile %r not found in config %s", args.profile_name, args.config
+        )
+        sys.exit(1)
+
+    return cfg.profiles[args.profile_name]
+
+
+def _profile_type(profile) -> str:
+    """Return a user-facing type label for *profile*."""
+    sub_types = []
+    if profile.backup:
+        sub_types.append("backup")
+    if profile.retention:
+        sub_types.append("retention")
+    return "+".join(sub_types)
+
+
+def _cmd_run(
+    args: argparse.Namespace,
+    *,
+    is_dry_run: bool = False,
+    force_notify: bool = False,
+) -> None:
+    """Run the configured workflow for a named profile."""
+    profile = _resolve_profile_or_exit(args)
+    logger.info("Running configured workflow for profile: %s", args.profile_name)
+
+    try:
+        run_profile(profile, dry_run=is_dry_run, force_notify=force_notify)
+    except (ValueError, WorkflowError) as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+
+
+def _cmd_unlock(args: argparse.Namespace, *, is_dry_run: bool = False) -> None:
+    """Run restic unlock on the named profile's repository."""
+    profile = _resolve_profile_or_exit(args)
+    logger.info("Unlocking repository for profile: %s", args.profile_name)
+
+    try:
+        run_unlock(profile, dry_run=is_dry_run)
+    except (ValueError, WorkflowError) as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+
+
+def _cmd_check(args: argparse.Namespace) -> None:
+    """Validate the TOML config file and print any errors."""
+    _load_config_or_exit(args.config)
+
+    print("Config is valid.")
+
+
+def _cmd_list(args: argparse.Namespace) -> None:
+    """List all profiles with key settings."""
+    cfg = _load_config_or_exit(args.config)
+
+    if not cfg.profiles:
+        print("No profiles configured.")
+        return
+
+    for name, profile in cfg.profiles.items():
+        repo_url = (
+            profile.resolved_repository.repository
+            if profile.resolved_repository
+            else "N/A"
+        )
+        schedule = profile.on_calendar or "manual"
+        print(
+            f"{name}  type={_profile_type(profile)}  "
+            f"schedule={schedule}  repository={repo_url}"
+        )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="restic-profile",
+        description="Run configured restic profile workflows.",
+    )
+
+    parser.add_argument(
+        "profile_name",
+        nargs="?",
+        help="Profile name from config to execute",
+    )
+    action_group = parser.add_mutually_exclusive_group()
+    action_group.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        default=False,
+        help="List all configured profiles",
+    )
+    action_group.add_argument(
+        "-C",
+        "--check",
+        action="store_true",
+        default=False,
+        help="Validate the TOML config file and exit",
+    )
+    action_group.add_argument(
+        "-U",
+        "--unlock",
+        action="store_true",
+        default=False,
+        help="Remove stale restic locks for the named profile",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=DEFAULT_CONFIG,
+        metavar="PATH",
+        help="Path to TOML config file (default: %(default)s)",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        nargs="?",
+        const="all",
+        default=None,
+        choices=["all", "notify"],
+        help="Dry-run mode: 'all' logs actions without executing (no-op), "
+        "'notify' dry-runs everything but sends the success notification for "
+        "real. When -n is used without a value, defaults to 'all'.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point for restic-profile."""
+    parser = _build_parser()
+    argcomplete.autocomplete(parser)
+    args = parser.parse_args(argv)
+
+    if args.profile_name and (args.list or args.check or args.unlock):
+        parser.error(
+            "profile name cannot be combined with --list, --check, or --unlock"
+        )
+
+    if args.list:
+        _cmd_list(args)
+        return
+
+    if args.check:
+        _cmd_check(args)
+        return
+
+    if args.unlock:
+        if not args.profile_name:
+            parser.error("--unlock requires a profile name")
+        _cmd_unlock(args, is_dry_run=args.dry_run == "all")
+        return
+
+    if not args.profile_name:
+        parser.error(
+            "provide a profile name or one of --list/--check/--unlock/--dry-run"
+        )
+
+    if args.dry_run == "notify":
+        _cmd_run(args, is_dry_run=True, force_notify=True)
+    else:
+        _cmd_run(args, is_dry_run=args.dry_run == "all")

restic_profile/config.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Annotated, Literal
+
+from chaos_utils.notify.dingtalk import DingTalkBot
+from chaos_utils.notify.telegram import TelegramBot
+from chaos_utils.notify.wechat import WechatWorkBot
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
+
+
+class HooksConfig(BaseModel):
+    """Per-profile hook commands executed around the backup lifecycle.
+
+    Each hook field is a list of shell command strings (or multi-line scripts).
+    Commands are executed via *shell* so pipelines and shell builtins work as
+    expected.  If any command in a hook phase exits non-zero, that phase is
+    considered failed.
+
+    Lifecycle order::
+
+        prevalidate → (check location) → before → backup → after → success|failure
+
+    If *prevalidate* or *before* fails the backup and *after* hooks are
+    skipped; only the *failure* hooks run.
+    """
+
+    shell: str = "/bin/sh"
+    prevalidate: list[str] = Field(default_factory=list)
+    before: list[str] = Field(default_factory=list)
+    after: list[str] = Field(default_factory=list)
+    failure: list[str] = Field(default_factory=list)
+    success: list[str] = Field(default_factory=list)
+
+
+class _BaseNotifyConfig(BaseModel):
+    """Shared base for per-platform notifier configs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables injected before sending (e.g. HTTP_PROXY).",
+    )
+    top_files_limit: int = Field(
+        default=3,
+        ge=0,
+        description="Max largest files and diff-changed files in success notification.",
+    )
+
+
+class DingTalkNotifyConfig(_BaseNotifyConfig):
+    type: Literal["dingtalk"] = "dingtalk"
+    access_token: str = Field(min_length=1)
+    secret: str = ""
+
+    def build(self) -> DingTalkBot:
+        return DingTalkBot(access_token=self.access_token, secret=self.secret)
+
+
+class TelegramNotifyConfig(_BaseNotifyConfig):
+    type: Literal["telegram"] = "telegram"
+    token: str = Field(min_length=1)
+    chat_id: int | str
+    timeout: float = Field(default=5.0, ge=0.1)
+    send_kwargs: dict[str, object] = Field(
+        default_factory=dict,
+        description="Extra keyword arguments forwarded to send_rich_message / send_message.",
+    )
+
+    def build(self) -> TelegramBot:
+        return TelegramBot(token=self.token, chat_id=self.chat_id, timeout=self.timeout)
+
+
+class WechatWorkNotifyConfig(_BaseNotifyConfig):
+    type: Literal["wechat"] = "wechat"
+    key: str = Field(min_length=1)
+
+    def build(self) -> WechatWorkBot:
+        return WechatWorkBot(key=self.key)
+
+
+NotifierConfig = Annotated[
+    DingTalkNotifyConfig | TelegramNotifyConfig | WechatWorkNotifyConfig,
+    Field(discriminator="type"),
+]
+
+
+class Repository(BaseModel):
+    """A single restic repository definition and credentials."""
+
+    name: str = ""
+    repository: str = ""
+    password: str = ""
+
+    # REST backend auth
+    rest_username: str = ""
+    rest_password: str = ""
+    cacert: str = ""
+
+    # S3-compatible backend credentials
+    aws_default_region: str = ""
+    aws_access_key_id: str = ""
+    aws_secret_access_key: str = ""
+
+    # Google Cloud Storage credentials
+    google_project_id: str = ""
+    google_application_credentials: str = ""
+    google_access_token: str = ""
+
+    env: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("repository")
+    @classmethod
+    def validate_repository(cls, v: str) -> str:
+        if not v:
+            raise ValueError("repository cannot be empty")
+        return v
+
+    @field_validator("password")
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        if not v:
+            raise ValueError("password cannot be empty")
+        return v
+
+
+class BackupConfig(BaseModel):
+    """Configurations specific to backing up data sources."""
+
+    sources: list[str] = Field(default_factory=list)
+    exclude_patterns: list[str] = Field(default_factory=list)
+    exclude_file: str = ""
+    one_file_system: bool = False
+
+
+class RetentionConfig(BaseModel):
+    """Configurations specific to snapshot retention (forget & prune)."""
+
+    keep_last: int = 0
+    keep_hourly: int = 0
+    keep_daily: int = 0
+    keep_weekly: int = 0
+    keep_monthly: int = 0
+    keep_yearly: int = 0
+    prune: bool = False
+    forget_current_host: bool = True
+
+    @property
+    def has_policy(self) -> bool:
+        """True when at least one keep_* retention setting is active (nonzero)."""
+        return any(
+            v > 0
+            for v in [
+                self.keep_last,
+                self.keep_hourly,
+                self.keep_daily,
+                self.keep_weekly,
+                self.keep_monthly,
+                self.keep_yearly,
+            ]
+        )
+
+    @property
+    def has_action(self) -> bool:
+        """True when the retention block has any actionable setting."""
+        return self.has_policy or self.prune
+
+
+class Profile(BaseModel):
+    """A single restic-profile configuration entry."""
+
+    name: str = ""
+    repository_ref: str = ""
+    notify_ref: str = ""
+
+    tag: str = ""  # snapshot tag; defaults to profile name
+    on_calendar: str = ""
+    randomized_delay_sec: str = ""
+
+    # Runtime
+    restic_binary: str = ""
+    no_cache: bool = False
+    retry_lock: str = ""
+    unlock: bool = False
+
+    # Runtime env & hooks
+    env: dict[str, str] = Field(default_factory=dict)
+    hooks: HooksConfig = Field(default_factory=HooksConfig)
+
+    # Sub-task blocks
+    backup: BackupConfig | None = None
+    retention: RetentionConfig | None = None
+
+    # Transient runtime resolved state
+    resolved_repository: Repository | None = None
+    resolved_notifier: NotifierConfig | None = None
+    resolved_template_dir: str = ""
+
+    @model_validator(mode="after")
+    def _validate_and_set_defaults(self) -> "Profile":
+        if not self.tag:
+            self.tag = self.name
+        if not self.backup and not self.retention:
+            raise ValueError(
+                f"Profile {self.name!r}: must configure at least one of 'backup' or 'retention'"
+            )
+        if self.backup and not self.backup.sources:
+            raise ValueError(
+                f"Profile {self.name!r}: backup section configured but 'sources' list is empty"
+            )
+        if self.retention and not self.retention.has_action:
+            raise ValueError(
+                f"Profile {self.name!r}: retention section configured but has no action "
+                "(configure keep_* and/or set prune=true)"
+            )
+        return self
+
+    @property
+    def is_backup(self) -> bool:
+        """True when the profile has a backup block configured."""
+        return self.backup is not None
+
+    @property
+    def is_retention_only(self) -> bool:
+        """True when the profile only has a retention block configured."""
+        return self.backup is None and self.retention is not None
+
+    @property
+    def runs_retention(self) -> bool:
+        """True when the profile executes a retention step."""
+        return self.retention is not None
+
+
+class ResticProfileConfig(BaseModel):
+    """Top-level restic-profile configuration."""
+
+    repositories: dict[str, Repository] = Field(default_factory=dict)
+    profiles: dict[str, Profile] = Field(default_factory=dict)
+    notify: dict[str, NotifierConfig] = Field(default_factory=dict)
+    template_dir: str = ""
+
+
+def load_config(path: Path) -> ResticProfileConfig:
+    """Load and parse the TOML config at *path*.
+
+    Raises
+    ------
+    FileNotFoundError
+        When *path* does not exist.
+    pydantic.ValidationError
+        When the TOML content fails schema validation.
+    """
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    global_section: dict[str, object] = data.get("global", {})
+    global_restic_binary: str = str(global_section.get("restic_binary", ""))
+    global_no_cache: bool = bool(global_section.get("no_cache", False))
+    global_retry_lock: str = str(global_section.get("retry_lock", ""))
+    global_unlock: bool = bool(global_section.get("unlock", False))
+    global_template_dir: str = str(global_section.get("template_dir", ""))
+
+    # Parse repositories
+    repositories_data: dict[str, Repository] = {}
+    for rname, rdata in data.get("repositories", {}).items():
+        entry = dict(rdata)
+        entry.setdefault("name", rname)
+        repositories_data[rname] = Repository.model_validate(entry)
+
+    # Parse notify channels
+    notify_adapter: TypeAdapter[dict[str, NotifierConfig]] = TypeAdapter(
+        dict[str, NotifierConfig]
+    )
+    notify_data: dict[str, NotifierConfig] = {}
+    raw_notify: dict[str, object] = data.get("notify", {})  # type: ignore[assignment]
+    if raw_notify:
+        notify_data = notify_adapter.validate_python(raw_notify)
+
+    # Parse profiles
+    profiles_data: dict[str, Profile] = {}
+    for pname, pdata in data.get("profiles", {}).items():
+        entry = dict(pdata)
+        entry.setdefault("name", pname)
+        if "restic_binary" not in entry:
+            entry["restic_binary"] = global_restic_binary
+        if "no_cache" not in entry:
+            entry["no_cache"] = global_no_cache
+        if not entry.get("retry_lock", ""):
+            entry["retry_lock"] = global_retry_lock
+        if "unlock" not in entry:
+            entry["unlock"] = global_unlock
+
+        profile = Profile.model_validate(entry)
+
+        # Resolve repository reference
+        if not profile.repository_ref:
+            raise ValueError(f"Profile {profile.name!r}: repository_ref is required")
+        if profile.repository_ref not in repositories_data:
+            raise ValueError(
+                f"Profile {profile.name!r}: referenced repository {profile.repository_ref!r} not found"
+            )
+
+        profile.resolved_repository = repositories_data[profile.repository_ref]
+
+        # Resolve notify reference
+        if profile.notify_ref:
+            if profile.notify_ref not in notify_data:
+                raise ValueError(
+                    f"Profile {profile.name!r}: referenced notifier {profile.notify_ref!r} not found"
+                )
+            profile.resolved_notifier = notify_data[profile.notify_ref]
+
+        profile.resolved_template_dir = global_template_dir
+
+        profiles_data[pname] = profile
+
+    return ResticProfileConfig(
+        repositories=repositories_data,
+        profiles=profiles_data,
+        notify=notify_data,
+        template_dir=global_template_dir,
+    )