Notify the desktop when automatic backup jobs fail

Author: Commanderx-code

STRUCTURE.md

@@ -144,3 +144,13 @@ same information for automation; exit 1 means attention or verification is neede
 Personal backup dates start being recorded after installing this version and
 completing a successful backup. An unknown date is not evidence of a failed backup.
 A personal backup older than 24 hours is flagged for review.
+
+Automatic personal backup and Restic maintenance services use systemd `OnFailure`
+to display a persistent critical desktop notification. The notification includes
+the failed service name and points to `backup-health`; journals remain available
+when no desktop notification session is running. Manual command failures continue
+to report their errors in the terminal.
+
+Captured system files are preserved verbatim, including upstream README files.
+The validator reports broken upstream links inside `system-backup/` without
+failing; broken links in maintained repository documentation still fail checks.

home-manager/modules/backup-automation.nix

@@ -1,4 +1,4 @@
-{ machine, ... }:
+{ machine, pkgs, ... }:
 
 {
   home.file.".local/bin/backup-on-mount" = {
@@ -16,9 +16,18 @@
     executable = true;
   };
 
+  systemd.user.services."backup-failure@" = {
+    Unit.Description = "Notify about backup failure in %i";
+    Service = {
+      Type = "oneshot";
+      ExecStart = "${pkgs.libnotify}/bin/notify-send --urgency=critical --expire-time=0 --app-name=Backups 'Backup service failed' '%i failed. Run backup-health and inspect its journal for details.'";
+    };
+  };
+
   systemd.user.services.backup-on-mount = {
     Unit = {
       Description = "Run Restic backup when the backup drive is mounted";
+      OnFailure = [ "backup-failure@%n.service" ];
       After = [ "graphical-session.target" ];
     };
 
@@ -46,6 +55,7 @@
   systemd.user.services.restic-maintenance = {
     Unit = {
       Description = "Prune old Restic snapshots and verify repository";
+      OnFailure = [ "backup-failure@%n.service" ];
     };
 
     Service = {
@@ -73,6 +83,7 @@
   systemd.user.services.restic-deep-check = {
     Unit = {
       Description = "Deep Restic repository integrity check";
+      OnFailure = [ "backup-failure@%n.service" ];
     };
 
     Service = {

scripts/check

@@ -44,6 +44,9 @@ def main():
             path = unquote(urlsplit(link).path)
             target = ((ROOT / path.lstrip('/')) if path.startswith('/') else (document.parent / path)).resolve()
             if not target.exists():
+                if document.relative_to(ROOT).parts[0] == 'system-backup':
+                    print(f'Upstream snapshot documentation link: {document.relative_to(ROOT)} -> {link}')
+                    continue
                 raise SystemExit(f'Broken link in {document.name}: {link}')
     # A temporary path flake includes new, unstaged files without changing the Git index.
     # Keep configs beside home-manager because modules use ../.. relative sources.