update_downgrade_guard.py 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. """Refuse an update whose target predates the gateway runtime while a state.db already depends on it.
  2. Releases before the gateway cutover know nothing of the runtime ledgers (``session_admissions`` /
  3. ``worker_executions``, ``ON DELETE RESTRICT``) and stamp the same ``schema_version``, so moving the
  4. code back under a store that holds ledger rows leaves every session with that history undeletable
  5. there. Downgrading is unsupported: the update refuses before anything moves and names the recovery
  6. point that predates the cutover. Read-only throughout; a store or target it cannot read is never a
  7. reason to refuse, and a target that descends from the running commit is a forward update.
  8. """
  9. from __future__ import annotations
  10. import sqlite3
  11. from collections.abc import Callable, Iterable
  12. from contextlib import closing
  13. from pathlib import Path
  14. from typing import Optional
  15. # The runtime ledger DDL: a target whose state-store modules lack it predates the cutover.
  16. _RUNTIME_SCHEMA_MARKER = "CREATE TABLE IF NOT EXISTS session_admissions"
  17. STATE_MODULES = "hermes_state*.py" # git pathspec and fnmatch pattern alike (``*`` crosses ``/`` in both)
  18. _LEDGER_PROBE = ("SELECT EXISTS(SELECT 1 FROM session_admissions) "
  19. "OR EXISTS(SELECT 1 FROM worker_executions)")
  20. _DOCS = "https://hermes-agent.nousresearch.com/docs/getting-started/updating#rolling-back-to-an-older-release"
  21. def _updater_git(git_cmd, root: Path) -> Callable[..., int]:
  22. import subprocess
  23. from hermes_cli.update_custody import run_git
  24. def git(*args: str) -> int:
  25. try:
  26. return run_git(git_cmd, list(args), cwd=str(root), capture_output=True, timeout=120).returncode
  27. except (OSError, subprocess.SubprocessError):
  28. return -1
  29. return git
  30. def defines_runtime(sources: Iterable[str]) -> bool:
  31. """Whether any of a tree's ``STATE_MODULES`` sources defines the runtime ledger. Lazy: stops at
  32. the first match, so a caller reading sources over the network fetches no more than it needs."""
  33. return any(_RUNTIME_SCHEMA_MARKER in source for source in sources)
  34. def target_predates_runtime(git_cmd, root: Path, target_ref: str, *,
  35. git: Optional[Callable[..., int]] = None,
  36. remote: Optional[Callable[[str], Optional[bool]]] = None) -> bool:
  37. """True when ``target_ref`` does not descend from HEAD and none of its ``hermes_state*.py`` files
  38. defines the runtime ledger. The pathspec keeps a blobless partial clone from fetching the whole
  39. tree. Any git failure proves nothing (False). ``git`` runs one git command and returns its exit
  40. code; the update check passes its own read-only probe.
  41. ``remote`` answers the same question for a target whose commit, tree or schema blobs are missing
  42. locally (True, False, or None when it cannot tell). The update check passes one because it never
  43. fetches; the updater stays git-only."""
  44. git = git or _updater_git(git_cmd, root)
  45. if git("merge-base", "--is-ancestor", "HEAD", target_ref) == 0:
  46. return False # forward update: whatever the target's schema, it was written knowing this one
  47. # grep can return 1 for unreadable blobs too: establish completeness before trusting no match.
  48. if git("rev-list", "--objects", "--no-walk", "--sparse", "--missing=error", target_ref, "--", STATE_MODULES) != 0:
  49. return remote is not None and remote(target_ref) is True
  50. # Exit 1 = no match in a complete local schema; 0 = found; anything else is a git error.
  51. result = git("grep", "-q", "-F", _RUNTIME_SCHEMA_MARKER, target_ref, "--", STATE_MODULES)
  52. return result == 1 if result in (0, 1) else remote is not None and remote(target_ref) is True
  53. def _has_ledger_rows(db_path: Path) -> bool:
  54. if not db_path.is_file():
  55. return False
  56. from hermes_state_holders import read_only_db_uri
  57. try:
  58. with closing(sqlite3.connect(read_only_db_uri(db_path), uri=True, timeout=5.0)) as conn:
  59. return bool(conn.execute(_LEDGER_PROBE).fetchone()[0])
  60. except sqlite3.Error:
  61. return False # no ledger tables yet, or unreadable: nothing an older release would trip on
  62. def _pre_runtime_snapshot(home: Path) -> str | None:
  63. """Newest quick snapshot of ``home`` holding a state.db from before the runtime ledger."""
  64. from hermes_cli.backup import _quick_snapshot_root
  65. from hermes_state_holders import read_only_db_uri
  66. root = _quick_snapshot_root(home)
  67. for snap in sorted(root.iterdir(), reverse=True) if root.is_dir() else ():
  68. db = snap / "state.db"
  69. if snap.name.startswith(".") or not db.is_file():
  70. continue
  71. try:
  72. with closing(sqlite3.connect(read_only_db_uri(db), uri=True)) as conn:
  73. if conn.execute("SELECT 1 FROM sqlite_master WHERE name='session_admissions'").fetchone() is None:
  74. return snap.name
  75. except sqlite3.Error:
  76. continue
  77. return None
  78. def _named_profile(home: Path) -> str:
  79. """The ``-p`` name that opens ``home`` (``hermes -p acme update`` passes ``profiles/acme``);
  80. ``""`` for the default root or a custom HERMES_HOME, which bare ``hermes`` opens."""
  81. from hermes_cli.profiles import _PROFILE_ID_RE, _get_profiles_root
  82. parent = _get_profiles_root().resolve()
  83. resolved = home.resolve()
  84. named = resolved.parent == parent and _PROFILE_ID_RE.match(resolved.name) and resolved.name != "default"
  85. return resolved.name if named else ""
  86. def _ledgered_profiles(home: Path | None) -> list[tuple[str, Path]]:
  87. from hermes_cli.backup import _sibling_profile_homes
  88. from hermes_constants import get_hermes_home
  89. home = Path(home or get_hermes_home())
  90. profiles = [(_named_profile(home), home), *_sibling_profile_homes(home)]
  91. return [(name, h) for name, h in profiles if _has_ledger_rows(h / "state.db")]
  92. def would_refuse(root: Path, target_ref: str, home: Path | None = None, *, git: Callable[..., int],
  93. remote: Optional[Callable[[str], Optional[bool]]] = None) -> bool:
  94. """Whether ``hermes update`` would refuse ``target_ref`` here: the update check's read-only twin of
  95. :func:`downgrade_refusal`, so a release the updater refuses is never offered as an update.
  96. The store scan runs first, so ``remote`` is only consulted when some store has runtime history."""
  97. return bool(_ledgered_profiles(home)) and target_predates_runtime(
  98. None, root, target_ref, git=git, remote=remote)
  99. def downgrade_refusal(git_cmd, root: Path, target_ref: str, home: Path | None = None) -> str | None:
  100. """Why the update must not move to ``target_ref``, or ``None``: refuses only a pre-runtime target
  101. while this profile's or a sibling profile's state.db holds runtime ledger rows."""
  102. ledgered = _ledgered_profiles(home)
  103. if not ledgered or not target_predates_runtime(git_cmd, root, target_ref):
  104. return None
  105. lines = [f"✗ Refusing to move this install to {target_ref[:12]}: that release predates the gateway runtime "
  106. "these session stores now use. Downgrading is unsupported.",
  107. *(f" {h / 'state.db'} has gateway runtime history." for _name, h in ledgered),
  108. " The older release could not delete or prune those sessions.",
  109. " To go back anyway: run `hermes gateway stop`, check out the older release with git, then put back "
  110. "each store's copy from before the upgrade:"]
  111. for name, h in ledgered:
  112. snapshot = _pre_runtime_snapshot(h)
  113. hermes = f"hermes -p {name}" if name else "hermes"
  114. lines.append(f" {h}: run `{hermes}` and enter `/snapshot restore {snapshot}`." if snapshot else
  115. f" {h}: no pre-update snapshot predates the upgrade; restore a full backup taken before "
  116. f"it with `{hermes} import <backup.zip>`.")
  117. lines += [" Sessions created since the upgrade are not in that copy.", f" Guide: {_DOCS}"]
  118. return "\n".join(lines)