config_read_errors.py 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166
  1. """What Hermes does when an existing ``config.yaml`` cannot be read or parsed.
  2. Readers fail open (``{}`` / defaults / last-known-good) so a broken file never takes the process
  3. down; this module makes that fallback loud (one warning per file signature, a ``corrupt`` backup),
  4. remembers the failure for :func:`get_active_config_parse_failure`, and marks every fallback as a
  5. :class:`FailedConfigRead` so the writers refuse to persist it.
  6. """
  7. from __future__ import annotations
  8. import logging
  9. import sys
  10. from pathlib import Path
  11. from typing import Any, Optional
  12. logger = logging.getLogger(__name__)
  13. # (config_path, mtime_ns, size) tuples already warned about, so concurrent CLI/gateway
  14. # loads of a broken config.yaml don't spam stderr. A changed file (new mtime) warns again.
  15. _CONFIG_PARSE_WARNED: set = set()
  16. # path -> (mtime_ns, size, error message) of active parse failures. Written by
  17. # _warn_config_parse_failure() (the single funnel for every load-path parse failure) and
  18. # probed by get_active_config_parse_failure() so provider auto-resolution can refuse to
  19. # adopt a paid provider from env keys while the user's REAL config is unreadable.
  20. _CONFIG_PARSE_FAILURES: dict = {}
  21. _PARSE_FAILURE_FALLBACK_MSG = {
  22. "last-known-good": "Hermes is running on the settings it loaded before the edit until it is fixed, so recent changes are not applied.",
  23. "last-known-good-backup": "Hermes is running on your last good settings until it is fixed, so recent changes are not applied.",
  24. "refuse-write": "Nothing was written, so the existing file is preserved."}
  25. _PARSE_FAILURE_DEFAULTS_MSG = (
  26. "Hermes is running on default settings until it is fixed, so none of your saved settings are applied.")
  27. _PARSE_FAILURE_REPAIR_MSG = "Open it with `hermes config edit`, fix {where}, then run `hermes config check`."
  28. _FIX_PERMS = "Fix the file permissions or move it aside first."
  29. _FIX_YAML = (
  30. "Fix it with `hermes config edit` and check with `hermes config check`, or copy the newest good "
  31. "file from {backups} over config.yaml.")
  32. def _yaml_error_location(exc: Exception) -> str:
  33. """``"line 12"`` from a PyYAML problem mark (1-based), else ``""``."""
  34. mark = getattr(exc, "problem_mark", None) or getattr(exc, "context_mark", None)
  35. line = getattr(mark, "line", None)
  36. return f"line {line + 1}" if isinstance(line, int) else ""
  37. def _yaml_error_details(exc: Exception) -> str:
  38. """Single-line ``Details:`` text: the PyYAML problem, or the exception's first line."""
  39. problem = getattr(exc, "problem", None)
  40. text = f"{problem}" if problem else str(exc).strip()
  41. return " ".join(text.split())
  42. def format_config_parse_failure(config_path: Path, exc: Exception, *, fallback: str = "defaults") -> str:
  43. """User copy for an unparseable config.yaml: what happened, what Hermes is doing, how to fix.
  44. Only the problem line/column is printed; the raw PyYAML text goes to a ``Details:`` line."""
  45. where = _yaml_error_location(exc)
  46. at = f" at {where}" if where else ""
  47. fallback_msg = _PARSE_FAILURE_FALLBACK_MSG.get(fallback, _PARSE_FAILURE_DEFAULTS_MSG)
  48. if isinstance(exc, OSError): # the file is intact; EMFILE/EIO/sharing violation, not a YAML problem
  49. return f"Your settings file ({config_path}) could not be read. {fallback_msg} {_read_error_fix(exc)}"
  50. repair = _PARSE_FAILURE_REPAIR_MSG.format(where=where or "the problem")
  51. return f"Your settings file ({config_path}) has a formatting error{at}. {fallback_msg} {repair}"
  52. def _warn_config_parse_failure(
  53. config_path: Path, exc: Exception, *, fallback: str = "defaults") -> None:
  54. """Surface a config.yaml parse failure to log and stderr (once per file signature).
  55. Silent fallback to ``DEFAULT_CONFIG`` drops every user override, so this must be loud.
  56. ``fallback`` selects the message wording: ``"defaults"`` (fresh process, nothing else to serve) or
  57. ``"last-known-good"`` (in-process retention of the previously loaded config — see the codex#31188 port
  58. in ``hermes_cli.config._load_config_impl``).
  59. """
  60. try:
  61. from hermes_cli.config_backend import config_version
  62. sig = config_version(config_path)
  63. key = (str(config_path), *sig)
  64. _CONFIG_PARSE_FAILURES[str(config_path)] = (*_failure_version(config_path), str(exc))
  65. except OSError:
  66. key = (str(config_path), 0, 0, 0, 0)
  67. if key in _CONFIG_PARSE_WARNED:
  68. return
  69. _CONFIG_PARSE_WARNED.add(key)
  70. from hermes_cli.config_backups import backup_config
  71. # A read error leaves an intact file behind: no "corrupt" copy of a good file.
  72. backup_path = None if isinstance(exc, OSError) else backup_config(config_path, "corrupt")
  73. msg = format_config_parse_failure(config_path, exc, fallback=fallback)
  74. if backup_path is not None:
  75. msg += f" A copy of the broken file was saved to {backup_path}."
  76. logger.warning("%s Details: %s", msg, _yaml_error_details(exc))
  77. try:
  78. sys.stderr.write(f"⚠️ hermes config: {msg}\n Details: {_yaml_error_details(exc)}\n")
  79. sys.stderr.flush()
  80. except Exception:
  81. pass
  82. def _failure_version(path: Path) -> tuple:
  83. """What a parse-failure record is matched on: ``file_cache_version`` hashed even once settled,
  84. because the record is compared long after it was taken and a same-tick same-size fix must clear
  85. it. An unreadable file (the OSError failures) gets its stat signature and the error's name."""
  86. from utils import file_cache_version
  87. try:
  88. return file_cache_version(path, always_digest=True)
  89. except OSError:
  90. from hermes_cli.config_backend import config_version
  91. return (*config_version(path), None)
  92. def get_active_config_parse_failure() -> Optional[str]:
  93. """Return the recorded parse error while the ACTIVE config.yaml is still byte-identical
  94. (``file_cache_version`` with its content digest) to the file that failed to parse; else None."""
  95. from hermes_cli.config import get_config_path
  96. try:
  97. record = _CONFIG_PARSE_FAILURES[str(path := get_config_path())]
  98. sig = _failure_version(path)
  99. return record[len(sig)] if sig == record[:len(sig)] else None
  100. except Exception:
  101. return None
  102. class FailedConfigRead(dict):
  103. """The fail-open fallback a config reader serves when an existing config.yaml could not be read
  104. or parsed (``{}``, defaults or last-known-good). Readers use it like any dict; ``save_config`` /
  105. ``atomic_config_write`` refuse to persist it. The writer merges by deletion, so saving a fallback
  106. after one transient EMFILE/EIO replaced the whole file with the fallback plus the caller's edit.
  107. A dict subclass so the refusal survives the load→mutate→save round trip at every call site."""
  108. def __init__(self, data: Any = (), *, error: BaseException):
  109. super().__init__(data)
  110. self.read_error = error
  111. def _read_error_fix(exc: OSError) -> str:
  112. return _FIX_PERMS if isinstance(exc, PermissionError) else (
  113. "Try again; run `hermes config check` if it keeps failing.")
  114. def _refuse_failed_read(config_path: Path, data: Any) -> None:
  115. """Refuse to save a fallback; only a read error is worth retrying, bad YAML needs an edit."""
  116. if not isinstance(data, FailedConfigRead):
  117. return
  118. exc = data.read_error
  119. if isinstance(exc, OSError):
  120. raise _refuse_overwrite(config_path, "could not be read", exc, _read_error_fix(exc))
  121. if isinstance(exc, SystemExit): # ConfigBackendUnavailable: the config backend could not serve it
  122. raise RuntimeError(f"The config could not be read, so this change was not saved: {exc.code}")
  123. raise _refuse_overwrite(
  124. config_path, "has a formatting error", exc, _FIX_YAML.format(backups=_backups_dir_display()))
  125. def _refuse_overwrite(config_path: Path, reason: str, exc: Exception, fix: str) -> RuntimeError:
  126. """Error for a write that must not replace an existing config.yaml. Plain lead + ``Details:``."""
  127. where = _yaml_error_location(exc)
  128. at = f" ({where})" if where else ""
  129. return RuntimeError(
  130. f"Your settings file ({config_path}) {reason}{at}, so this change was not saved. {fix} "
  131. f"Details: {_yaml_error_details(exc)}")
  132. def _backups_dir_display() -> str:
  133. from hermes_constants import display_hermes_home
  134. return f"{display_hermes_home()}/backups/config/"