config_backups.py 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  1. """Point-in-time copies of ``config.yaml``: one directory, one naming scheme, bounded count.
  2. Every writer that wants a "before" copy of the user's config (setup wizard, corrupt-file
  3. snapshot, model migrations) goes through :func:`backup_config`. Copies live in
  4. ``<HERMES_HOME>/backups/config/`` — ``backups/`` is already excluded from full backups, so they
  5. never nest — as ``config.yaml.<reason>.<YYYYMMDD-HHMMSS>``. A copy identical to the newest one
  6. for the same reason is skipped, and only the newest ``keep`` per reason survive, so repeated
  7. ``hermes setup`` runs or a gateway restarting against broken YAML cannot litter the home dir.
  8. """
  9. from __future__ import annotations
  10. import logging
  11. import shutil
  12. import time
  13. from pathlib import Path
  14. from typing import Optional
  15. logger = logging.getLogger(__name__)
  16. BACKUPS_SUBDIR = Path("backups") / "config"
  17. DEFAULT_KEEP = 5
  18. # Names earlier code wrote next to config.yaml (setup wizard, corrupt snapshot, xai migration).
  19. # Moved into the backups dir on first use so they stop accumulating in the home root; hand-named
  20. # copies (``config.yaml.bak-my-note``) are the user's and are never touched.
  21. _LEGACY_SIBLING_GLOBS = ("config.yaml.bak.[0-9]*", "config.yaml.corrupt.*.bak", "config.yaml.bak-pre-migrate-*")
  22. def backups_dir(config_path: Path) -> Path:
  23. return config_path.parent / BACKUPS_SUBDIR
  24. def list_config_backups(config_path: Path, reason: Optional[str] = None) -> list[Path]:
  25. """Existing backups, newest first; filtered to one *reason* when given."""
  26. root = backups_dir(config_path)
  27. if not root.is_dir():
  28. return []
  29. prefix = f"{config_path.name}.{reason}." if reason else f"{config_path.name}."
  30. return sorted((p for p in root.iterdir() if p.is_file() and p.name.startswith(prefix)),
  31. key=lambda p: p.name, reverse=True)
  32. def backup_config(config_path: Path, reason: str, *, keep: int = DEFAULT_KEEP) -> Optional[Path]:
  33. """Copy *config_path* to the backups dir; return the new path, or None when skipped/failed.
  34. Skips when the file is missing/empty, or when the newest backup for *reason* already holds
  35. identical bytes. Never raises: a failed backup must not block the write it precedes.
  36. Skipped entirely for a config backend without file tooling (no local copies, D2).
  37. """
  38. from hermes_cli.config_backend import supports_file_tooling
  39. if not supports_file_tooling():
  40. return None
  41. try:
  42. if not config_path.is_file() or config_path.stat().st_size == 0: # config-reader: ok — file tooling, gated above
  43. return None
  44. root = backups_dir(config_path)
  45. root.mkdir(parents=True, exist_ok=True)
  46. _sweep_legacy_siblings(config_path, root)
  47. existing = list_config_backups(config_path, reason)
  48. # Not filecmp.cmp: its process-wide cache keys on (size, mtime), so an equal-size edit
  49. # within one mtime tick of an earlier comparison is reported identical and never backed up.
  50. if existing and config_path.read_bytes() == existing[0].read_bytes(): # config-reader: ok — file tooling, gated above
  51. return None
  52. dest = root / f"{config_path.name}.{reason}.{time.strftime('%Y%m%d-%H%M%S')}"
  53. if dest.is_symlink() or dest.exists(): # never write through a planted link
  54. return None
  55. shutil.copy2(config_path, dest) # config-reader: ok — file tooling, gated above
  56. for stale in [dest, *existing][keep:]:
  57. stale.unlink(missing_ok=True)
  58. return dest
  59. except OSError as exc:
  60. logger.warning("Could not back up %s (%s): %s", config_path, reason, exc)
  61. return None
  62. def load_newest_good_backup(config_path: Path) -> Optional[dict]:
  63. """Parse the newest ``good`` backup (the file as it was at the last successful load).
  64. Returns the raw mapping, or None when there is no usable copy. Older ``good`` copies are not
  65. tried: a backup that fails to parse means the on-disk copy was damaged after the fact, and
  66. guessing further back would serve a config the user never saw as current.
  67. """
  68. from hermes_cli.config_backend import supports_file_tooling
  69. if not supports_file_tooling():
  70. return None
  71. newest = list_config_backups(config_path, "good")[:1]
  72. if not newest:
  73. return None
  74. try:
  75. from utils import fast_safe_load
  76. with newest[0].open(encoding="utf-8") as f:
  77. data = fast_safe_load(f)
  78. except Exception as exc:
  79. logger.warning("Last-known-good backup %s is unreadable: %s", newest[0], exc)
  80. return None
  81. return data if isinstance(data, dict) else None
  82. def _sweep_legacy_siblings(config_path: Path, root: Path) -> None:
  83. for pattern in _LEGACY_SIBLING_GLOBS:
  84. for old in config_path.parent.glob(pattern):
  85. if not old.is_file() or old.is_symlink():
  86. continue
  87. try:
  88. old.replace(root / old.name)
  89. except OSError as exc:
  90. logger.debug("Could not move legacy backup %s: %s", old, exc)