update_channel.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383
  1. """Per-install update-channel records.
  2. Channel storage — per install, never home-global::
  3. update:
  4. installs:
  5. a4f3b2c1d0e9f8a7: # install id (sha16 of the
  6. path: /home/u/.hermes/hermes-agent # canonical install root)
  7. channel: canary
  8. One config.yaml serves many installs (host + docker gateway + desktop all
  9. bind-mount one ``~/.hermes``), so a home-global ``update.channel`` key is
  10. UNSAFE and does not exist: setting canary for a dev checkout must not
  11. flip the desktop app's feed. The id is sha16 of the canonical
  12. install-root PATH — the same key that names the ``installs/<sha16>/``
  13. state folder (``boot_bootstrap._install_key``; a byte-identical helper is
  14. inlined below until that module lands). Path-derived on purpose: an
  15. electron-updater update replaces the artifact (new stamp bytes) at the
  16. same path, and the channel opt-in must survive that.
  17. * Written by ``hermes update --set-channel <x>`` from inside an install
  18. (it knows its own id — the user never types a sha).
  19. * Shown by ``hermes update --install-id`` and the desktop About page.
  20. * Source installs select an R2 channel name, or use an explicit branch override.
  21. Unconfigured official checkouts track ``stable``; forks and mirrors keep ``main``.
  22. Bundles derive their channel from their baked identity, never these records.
  23. ``external`` installs have no configurable channel; the steward owns updates.
  24. Pure-stdlib leaf module (plus hermes-internal imports done lazily): the
  25. installers and boot paths read it before the full config machinery loads.
  26. """
  27. from __future__ import annotations
  28. from pm.environments import install_key, installs_root
  29. from hermes_cli.release_channels import validate_name
  30. from contextlib import contextmanager
  31. import logging
  32. import os
  33. import re
  34. from pathlib import Path
  35. from typing import Any, Optional
  36. from pm.paths import install_root
  37. logger = logging.getLogger(__name__)
  38. CHANNEL_MAIN = "main"
  39. CHANNEL_STABLE = "stable"
  40. CHANNEL_CANARY = "canary"
  41. # A canary source identity: the exact stable version plus a full UTC build
  42. # timestamp in SemVer build metadata. Build metadata is precedence-invisible,
  43. # so channel movement comes only from the R2 head, never version comparison.
  44. # THIS is the single authority; producers and consumers import it rather than
  45. # re-typing the shape.
  46. _CANARY_TAG_RE = re.compile(
  47. r"^v(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)"
  48. r"\+canary\.20\d{6}T\d{6}Z$"
  49. )
  50. # A stable release tag: v<major>.<minor>.<patch>, no suffix. The major is
  51. # capped at three digits so the historical CalVer tags (v2026.7.20) can never
  52. # pass as SemVer and reach a stable feed, Docker publish, or the source
  53. # updater. THIS is the single authority for the stable shape; every stable
  54. # selector imports it rather than re-typing the rule.
  55. STABLE_TAG_RE = re.compile(r"^v(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$")
  56. def is_canary_tag(tag: Any) -> bool:
  57. """True for a canonical canary source identity."""
  58. if not isinstance(tag, str):
  59. return False
  60. value = tag.strip()
  61. return bool(_CANARY_TAG_RE.fullmatch(value))
  62. def canary_timestamp(tag: Any) -> str | None:
  63. """Return the UTC receipt stamp from a canonical canary tag."""
  64. if not is_canary_tag(tag):
  65. return None
  66. return tag.strip().split("+canary.", 1)[1]
  67. def canary_tag_for_date(version: str, date_utc: str) -> str:
  68. """Return ``v<stable>+canary.<full UTC timestamp>``.
  69. The stable core is unchanged. The suffix is build metadata, so the source
  70. identity compares equal to the stable and only the R2 channel head moves a
  71. canary subscriber.
  72. """
  73. core = version.removeprefix("v")
  74. if not STABLE_TAG_RE.fullmatch("v" + core):
  75. raise ValueError(f"invalid stable version for canary: {version!r}")
  76. if not re.fullmatch(r"20\d{6}T\d{6}Z", date_utc):
  77. raise ValueError(f"invalid canary UTC timestamp: {date_utc!r}")
  78. return f"v{core}+canary.{date_utc}"
  79. def install_id(project_root: Optional[Path] = None) -> str:
  80. """The sha16 id of the install at ``project_root`` (default: this one).
  81. Same identity as the ``installs/<sha16>/`` state folder key.
  82. """
  83. if project_root is None:
  84. project_root = install_root()
  85. return install_key(Path(project_root))
  86. def _read_stamp(root: Path) -> dict:
  87. """The install stamp of ``root``, or ``{}`` (tolerant, like steward.py)."""
  88. from hermes_cli.steward import read_install_stamp
  89. return read_install_stamp(root)
  90. def _install_records(config: Optional[dict]) -> dict:
  91. if not isinstance(config, dict):
  92. return {}
  93. update_cfg = config.get("update")
  94. if not isinstance(update_cfg, dict):
  95. return {}
  96. installs = update_cfg.get("installs")
  97. return installs if isinstance(installs, dict) else {}
  98. def channel_record(config: Optional[dict], project_root: Optional[Path] = None) -> dict:
  99. """This install's ``{path, channel}`` record from config, or ``{}``."""
  100. record = _install_records(config).get(install_id(project_root))
  101. return record if isinstance(record, dict) else {}
  102. def _package_channel(stamp: dict) -> bool:
  103. return stamp.get("payload") in ("bundled", "light", "runtime") or stamp.get("updateMechanism") in (
  104. "electron-updater", "app-installer", "microsoft-store"
  105. )
  106. def default_channel(project_root: Optional[Path] = None) -> str:
  107. """The channel an unconfigured install tracks.
  108. A source checkout of the official repository follows the latest published
  109. stable release. Forks, mirrors and checkout-less trees keep following main.
  110. ``electron-updater`` and ``app-installer`` bundles report their artifact
  111. channel: a canary artifact tracks canary, every other bundle
  112. tracks stable. The stamp's ``tag`` is the authority, the same fact
  113. apps/desktop/product-identity.cjs keys the published feed name on — so
  114. the feed a canary artifact asks for and the feed it was published to
  115. can never disagree. Deriving stable here instead would send a fresh
  116. canary install to look for its ``canary.yml`` feed file under the
  117. newest STABLE release, where that file does not exist (404), leaving
  118. the install unable to update at all.
  119. """
  120. root = Path(project_root) if project_root is not None else install_root()
  121. stamp = _read_stamp(root)
  122. if not _package_channel(stamp):
  123. return CHANNEL_STABLE if _tracks_official_origin(root) else CHANNEL_MAIN
  124. if stamp.get("source") == "channel-build":
  125. request = stamp.get("channelBuild")
  126. if not isinstance(request, dict):
  127. raise ValueError("Channel bundle has no baked subscription")
  128. return validate_name(request.get("channel"))
  129. return CHANNEL_CANARY if is_canary_tag(stamp.get("tag")) else CHANNEL_STABLE
  130. def _tracks_official_origin(root: Path) -> bool:
  131. """True when ``root`` is a git checkout whose ``remote.origin.url`` is the official repo.
  132. Read from the git config file (no git process: the banner and boot paths call this).
  133. Forks, mirrors and local-path origins publish no official releases.
  134. """
  135. from hermes_cli.source_releases import _GITHUB_ORIGIN, OFFICIAL_REPOSITORY
  136. from hermes_cli.update_lock import _git_common_dir
  137. common = _git_common_dir(root)
  138. try:
  139. lines = (common / "config").read_text(encoding="utf-8-sig").splitlines() if common else []
  140. except OSError:
  141. return False
  142. in_origin = False
  143. for line in lines:
  144. text = line.strip()
  145. if text.startswith("["):
  146. in_origin = text == '[remote "origin"]'
  147. elif in_origin and text.partition("=")[0].strip() == "url":
  148. match = _GITHUB_ORIGIN.fullmatch(text.partition("=")[2].strip())
  149. return bool(match) and match[1].lower() == OFFICIAL_REPOSITORY.lower()
  150. return False
  151. def rides_default_channel(record: dict, channel: str, project_root: Optional[Path] = None) -> bool:
  152. """True when no channel was ever persisted (``record``) and ``channel`` is the default.
  153. Such an install never consented to a release switch, so it only moves forward: a
  154. checkout already newer than the latest release waits for the next one. A transient
  155. ``--channel`` naming the default (the Desktop passes the channel its check reported)
  156. is still the default; only ``--set-channel`` consents to a downgrade.
  157. """
  158. return record.get("channel") is None and channel == default_channel(project_root)
  159. def resolve_update_channel(
  160. config: Optional[dict] = None,
  161. project_root: Optional[Path] = None,
  162. ) -> str:
  163. """Source records select releases or main; package tags fix bundle identity."""
  164. root = Path(project_root) if project_root is not None else install_root()
  165. if _package_channel(_read_stamp(root)):
  166. return default_channel(root)
  167. configured: Any = channel_record(config, root).get("channel")
  168. if configured is not None:
  169. return validate_name(configured)
  170. return default_channel(root)
  171. def set_install_channel(
  172. channel: str,
  173. project_root: Optional[Path] = None,
  174. ) -> str:
  175. """Persist ``channel`` for THIS install in config.yaml. Returns the id.
  176. Refuses when the update source belongs to the OS or package owner,
  177. including Microsoft Store, rather than this configuration.
  178. Raises ``ValueError`` for an invalid channel or an OS-owned install.
  179. """
  180. from hermes_cli.update_contract import COMMIT_BUILD_UPDATE_MESSAGE, is_commit_build
  181. root = Path(project_root) if project_root is not None else install_root()
  182. if is_commit_build(root):
  183. raise ValueError(COMMIT_BUILD_UPDATE_MESSAGE)
  184. channel = validate_name(channel)
  185. stamp = _read_stamp(root)
  186. if _package_channel(stamp) or stamp.get("updateMechanism") == "external":
  187. distribution = stamp.get("distribution") or "an external steward"
  188. raise ValueError(
  189. f"channels don't apply here; updates are owned by {distribution}"
  190. )
  191. sha16 = install_id(root)
  192. _write_channel_record(sha16, str(root), channel)
  193. return sha16
  194. def handle_metadata_args(args, project_root: Path) -> bool:
  195. """Handle metadata-only update commands before any update side effect."""
  196. if getattr(args, "install_id", False):
  197. print(install_id(project_root))
  198. return True
  199. channel = getattr(args, "set_channel", None)
  200. if channel is None:
  201. return False
  202. try:
  203. key = set_install_channel(channel, project_root)
  204. except ValueError as exc:
  205. print(str(exc))
  206. raise SystemExit(2) from exc
  207. print(f"Update channel for {key}: {channel}")
  208. if channel == CHANNEL_CANARY:
  209. print("Canary builds can write forward-incompatible state. Back up your data before switching.")
  210. elif channel == CHANNEL_STABLE:
  211. print("Switching to an older stable release may not read state written by canary. Back up your data first.")
  212. return True
  213. @contextmanager
  214. def _channel_write_lock(config_path: Path):
  215. """Serialize channel selection and retirement across CLI processes."""
  216. from hermes_cli.config import _CONFIG_LOCK
  217. config_path.parent.mkdir(parents=True, exist_ok=True)
  218. with _CONFIG_LOCK, config_path.with_suffix(".channels.lock").open("a+b") as lock:
  219. if os.name == "nt":
  220. import msvcrt
  221. lock.write(b"\0")
  222. lock.flush()
  223. lock.seek(0)
  224. msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)
  225. else:
  226. import fcntl
  227. fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
  228. try:
  229. yield
  230. finally:
  231. if os.name == "nt":
  232. lock.seek(0)
  233. msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)
  234. else:
  235. fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
  236. def adopt_retired_channel(request: dict) -> bool:
  237. """After verified completion, adopt only an unchanged persistent subscription."""
  238. retirement = request.get("channel_retirement")
  239. if retirement is None:
  240. return False
  241. return _write_channel_record(
  242. install_id(Path(request["source"])), request["source"],
  243. validate_name(retirement["destination"]),
  244. expected=retirement["original"], config_path=Path(request["home"]) / "config.yaml")
  245. def _write_channel_record(sha16: str, path: str, channel: str, *,
  246. expected: dict | None = None, config_path: Path | None = None) -> bool:
  247. from hermes_cli.config import get_config_path
  248. config_path = config_path if config_path is not None else get_config_path()
  249. with _channel_write_lock(config_path):
  250. return _write_channel_record_locked(sha16, path, channel, expected, config_path)
  251. def _write_channel_record_locked(sha16: str, path: str, channel: str,
  252. expected: dict | None, config_path: Path) -> bool:
  253. """Write ``update.installs.<sha16>`` into config.yaml, preserving the rest.
  254. Persists through the shared comment-preserving atomic writer
  255. (:func:`utils.atomic_roundtrip_yaml_update` — the same ruamel round-trip
  256. path ``hermes config set`` uses), fail-closed via
  257. :func:`hermes_cli.config.require_readable_config_before_write`. Malformed
  258. ``update`` / ``update.installs`` values are refused, never replaced —
  259. the dotted writer would otherwise turn a scalar into a mapping and
  260. destroy whatever the user had there.
  261. """
  262. from hermes_cli.config_backend import write_config_key
  263. from hermes_cli.config import require_readable_config_before_write
  264. existing = require_readable_config_before_write(config_path)
  265. update_cfg = existing.get("update")
  266. if update_cfg is not None and not isinstance(update_cfg, dict):
  267. raise ValueError("config key 'update' is not a mapping")
  268. installs = update_cfg.get("installs") if isinstance(update_cfg, dict) else None
  269. if installs is not None and not isinstance(installs, dict):
  270. raise ValueError("config key 'update.installs' is not a mapping")
  271. record = installs.get(sha16) if isinstance(installs, dict) else None
  272. if expected is not None and (record or {}) != expected:
  273. return False
  274. new_record = dict(record) if isinstance(record, dict) else {}
  275. new_record["path"] = path # DATA, for humans + doctor GC
  276. new_record["channel"] = channel
  277. write_config_key(config_path, f"update.installs.{sha16}", new_record)
  278. return True
  279. def stale_channel_records(config: Optional[dict]) -> list[tuple[str, dict, str]]:
  280. """Doctor's staleness triad over ``update.installs``.
  281. Returns ``(sha16, record, reason)`` where reason is one of:
  282. * ``"replaced"`` — the recorded path exists but the install there keys
  283. to a DIFFERENT sha16 (the tree moved / was recreated elsewhere and a
  284. new record claimed it; this one is a leftover).
  285. * ``"missing"`` — nothing at the recorded path: offer GC (keep-on-doubt).
  286. * ``"unclaimed"`` — the sha16 matches no live install record
  287. (``installs/<sha16>/install.json``): offer GC.
  288. """
  289. stale: list[tuple[str, dict, str]] = []
  290. for sha16, record in _install_records(config).items():
  291. if not isinstance(record, dict):
  292. continue
  293. recorded_path = record.get("path")
  294. if not isinstance(recorded_path, str) or not recorded_path:
  295. # No path fact — fall through to the live-record check only.
  296. recorded_path = None
  297. if recorded_path is not None:
  298. path = Path(recorded_path)
  299. if not path.exists():
  300. stale.append((sha16, record, "missing"))
  301. continue
  302. if install_key(path) != sha16:
  303. stale.append((sha16, record, "replaced"))
  304. continue
  305. # Cross-check against the live install-state records: a channel
  306. # record whose sha16 has no installs/<sha16>/install.json was
  307. # either hand-written or its install never booted post-record.
  308. try:
  309. if not (installs_root() / sha16 / "install.json").is_file():
  310. stale.append((sha16, record, "unclaimed"))
  311. except Exception as exc:
  312. logger.debug("installs root unavailable: %s", exc)
  313. return stale