Module backup 

Backup planning. Pure functions that take service install state + the user’s backup config and produce typed plans the CLI executes.

What lives here:

• BackupRunPlan: everything the CLI needs to push one service’s data to the configured restic repository.
• BackupRestorePlan: same shape for the reverse operation.
• plan_backup_run / plan_backup_restore: the planners.

What does not live here: spawning the restic subprocess, running hook scripts, or any other side effect. The CLI layer owns those. Keeping the planner pure means it round-trips cleanly in tests against a tempdir without needing restic on the test runner.

Structs

BackupForgetPlan

Instructions for pruning one service’s snapshots to the retention ladder. Built from the configured retention policy; the CLI spawns restic forget (then --prune to reclaim space) scoped to this service’s service:<name> tag, so one service’s policy can’t evict another’s snapshots.

BackupRestorePlan

Instructions for restoring one installed service from a specific restic snapshot.

BackupRunPlan

Concrete instructions for backing up one installed service.

Functions

backup_stops_service

Whether backing up this service stops it. Cold services (the default) take a stop-the-stack snapshot; online services snapshot live. Surfaced to the UI so “Back up now” can warn about the brief downtime.

execute_backup_restore

Run a planned restore end-to-end.

execute_backup_run

Run a planned backup end-to-end.

list_backup_enabled

List installed services that have backup_enabled = true in their metadata. The CLI’s ryra backup manual (no service argument) uses this to iterate every enabled install.

manifest_sha256

Hex SHA256 of the service’s service.toml. Used as the manifest_sha: tag on each snapshot so a future restore can detect version skew between the snapshot and the currently-installed service definition.

parse_env_file

KEY=VALUE lines from a .env file; malformed lines are skipped the same way systemd’s EnvironmentFile= skips them.

plan_backup_restore

Plan a ryra backup restore <service> invocation.

plan_backup_run

Plan a ryra backup manual <service> invocation. Errors loudly when:

plan_mode_prune

Plan a per-mode prune for one service: keep at most keep snapshots tagged mode:<mode> (the daily or weekly cap), dropping the oldest beyond that. Manual snapshots are never pruned, so callers only pass daily/weekly. Returns Ok(None) when keep == 0 (unlimited) rather than running a keep-nothing forget.

restic_backup

Execute a planned backup with restic. Ownership of container-owned bind mounts is the pre-hook’s job (podman unshare chown); by this point every file is readable by the invoking user.

restic_forget

Execute a planned retention sweep, returning (kept, removed) snapshot counts. Runs restic forget --json filtered to the service’s service:<name> tag (so keep rules apply only to that service), parses the keep/remove decision, then runs restic prune SEPARATELY to reclaim space (real runs only, when something was actually removed). Splitting prune out keeps the --json output clean to parse. In a dry run nothing is deleted and removed is the count that WOULD be removed.

restic_restore

Execute a planned restore. Files come back owned by the invoking user; the next container start’s :U re-chowns to the container’s USER. (Running inside podman unshare would preserve snapshot UIDs but fails chowning /home outside the namespace mapping.)

restore_stops_service

Whether restoring this service stops it. A cold restore always stops the stack to wipe + replace its data; an online service stops only if it ships restore hooks (e.g. it pauses the app while re-importing a dump). Surfaced to the UI so the restore confirm can warn about downtime.

run_hook

Run a pre/post backup or restore hook with the service’s .env loaded, mirroring how quadlet ExecStartPre/Post scripts see it.

set_backup_enabled

Enroll or unenroll a service in backups by flipping backup_enabled in its metadata.toml. Returns whether the flag actually changed (false if the service isn’t installed, or was already in that state). This on-disk flag is what list_backup_enabled and a no-argument ryra backup manual read, so it is the single source of truth both the CLI picker and the rpc layer set.