ui_preferences.py 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233
  1. """Machine-level Desktop/Webapp UI preferences (#145213).
  2. One JSON document per machine, beside the ROOT Hermes home (``get_default_hermes_root()``, never a
  3. profile's ``HERMES_HOME``): native Desktop writes it through its preload capability
  4. (``apps/desktop/electron/ui-preferences.ts``) and every browser that opens this machine's Webapp
  5. writes it through ``/api/ui-preferences``. It is deliberately neither per profile nor per gateway
  6. connection; a key that is scoped (``….profile.<name>``) carries its scope in its own name.
  7. Both writers share the on-disk contract, so keep the two in lockstep:
  8. * document ``{"version": 1, "revision": <int>, "values": {<key>: <string>}}``;
  9. * a write merges per key under the ``<store>.lock`` directory lock (``mkdir`` is atomic on every
  10. OS and in Node), bumps ``revision`` and lands by temp file + rename; a ``None`` value deletes;
  11. * ``generation`` names one store's lifetime: a write that finds no readable store (missing, or
  12. corrupt and kept aside as ``<store>.corrupt-<ms>``) starts a new one, and every window rejoins it
  13. (re-imports its own values, then follows it) whatever its revision high-water mark was;
  14. * a ``seed`` write (a client's first contact with a generation) only ADDS the keys the store lacks,
  15. so the client that has data fills a store an empty client created, and nothing is overwritten;
  16. * only a missing file reads as "no store": any other read failure refuses the write
  17. (:class:`PreferencesBusy`) instead of merging over nothing.
  18. Values are opaque strings the renderer already kept in localStorage. Only keys under the Desktop
  19. prefixes are accepted; the renderer's allowlist decides which of those are preferences and keeps
  20. credentials, grants and per-window state out.
  21. """
  22. from __future__ import annotations
  23. import json
  24. import os
  25. import secrets
  26. import shutil
  27. import threading
  28. import time
  29. from contextlib import contextmanager
  30. from pathlib import Path
  31. from typing import Callable, Iterator, Mapping, Optional
  32. from utils import atomic_json_write
  33. STORE_NAME = "ui-preferences.json"
  34. KEY_PREFIXES = ("hermes.desktop.", "hermes-desktop-", "hermes-onboarding-")
  35. MAX_KEY_CHARS = 256
  36. MAX_VALUE_CHARS = 256 * 1024
  37. MAX_KEYS = 512
  38. MAX_TOTAL_CHARS = 2 * 1024 * 1024
  39. _LOCK_WAIT_S = 3.0
  40. _LOCK_STALE_S = 10.0
  41. _LOCK_POLL_S = 0.02
  42. _thread_lock = threading.Lock()
  43. class PreferencesError(ValueError):
  44. """A write the store refuses (bad key, value or size); the route answers 400."""
  45. class PreferencesBusy(RuntimeError):
  46. """Another writer held the store lock past the wait; the route answers 503 and the client
  47. keeps the change pending for its next attempt."""
  48. def store_path(root: Optional[Path] = None) -> Path:
  49. """The machine's preferences file, resolved by the same rule native Desktop applies to its
  50. ``HERMES_HOME`` (``resolveDesktopHermesHome`` + ``uiPreferencesRoot``): a profile home
  51. (``<root>/profiles/<name>``, judged on the path as given, so a symlinked profile directory
  52. still names its root) names its root, any other home is its own root, and that root is then
  53. resolved through symlinks on both sides. Every profile one process serves maps to the same
  54. root, so this read is profile-independent by design (not a launch-profile leak)."""
  55. if root is None:
  56. from hermes_constants import get_hermes_home
  57. home = Path(os.path.abspath(get_hermes_home()))
  58. root = (home.parent.parent if home.parent.name.lower() == "profiles" else home).resolve()
  59. return Path(root) / STORE_NAME
  60. def _sanitize(values: object) -> dict[str, str]:
  61. if not isinstance(values, dict):
  62. return {}
  63. return {k: v for k, v in values.items() if isinstance(k, str) and isinstance(v, str)}
  64. _MISSING = {"exists": False, "revision": 0, "values": {}}
  65. def _read(path: Path) -> tuple[dict, bool]:
  66. """``(snapshot, corrupt)``. A missing file is no store; an unparseable one is no store too
  67. (``corrupt``), so clients re-import into a fresh generation. Any other read failure (EACCES,
  68. EBUSY, EMFILE…) raises :class:`PreferencesBusy`: it says nothing about the content, and
  69. merging over it would drop every key."""
  70. try:
  71. raw = path.read_text(encoding="utf-8-sig")
  72. except FileNotFoundError:
  73. return dict(_MISSING, values={}), False
  74. except OSError as exc:
  75. raise PreferencesBusy(f"preferences store is unreadable: {exc}") from exc
  76. try:
  77. doc = json.loads(raw)
  78. except ValueError:
  79. doc = None
  80. if not isinstance(doc, dict):
  81. return dict(_MISSING, values={}), True
  82. revision = doc.get("revision")
  83. generation = doc.get("generation")
  84. return {
  85. "exists": True,
  86. "revision": revision if isinstance(revision, int) else 0,
  87. "values": _sanitize(doc.get("values")),
  88. "generation": generation if isinstance(generation, str) else "",
  89. }, False
  90. def read_preferences(path: Optional[Path] = None) -> dict:
  91. """``{"exists", "revision", "values"[, "generation"]}`` for the store at *path* (the
  92. machine's by default). Raises :class:`PreferencesBusy` when the file exists but cannot be read."""
  93. return _read(path or store_path())[0]
  94. def _validate(changes: Mapping[str, Optional[str]]) -> None:
  95. for key, value in changes.items():
  96. if not isinstance(key, str) or not key.startswith(KEY_PREFIXES) or len(key) > MAX_KEY_CHARS:
  97. raise PreferencesError(f"unsupported preference key: {key!r}")
  98. if value is not None and (not isinstance(value, str) or len(value) > MAX_VALUE_CHARS):
  99. raise PreferencesError(f"unsupported value for {key}")
  100. def _owner_file(lock_dir: Path) -> Path:
  101. return lock_dir / "owner"
  102. def _release(lock_dir: Path, token: str) -> None:
  103. """Remove the lock only while it is still ours: a lock broken as stale and re-taken by another
  104. writer must not be removed by the writer that lost it."""
  105. if not _owns(lock_dir, token):
  106. return
  107. try:
  108. _owner_file(lock_dir).unlink()
  109. os.rmdir(lock_dir)
  110. except OSError:
  111. pass
  112. def _owns(lock_dir: Path, token: str) -> bool:
  113. try:
  114. return _owner_file(lock_dir).read_text(encoding="utf-8-sig") == token
  115. except OSError:
  116. return False
  117. def _break_if_stale(lock_dir: Path) -> None:
  118. try:
  119. stale = time.time() - lock_dir.stat().st_mtime > _LOCK_STALE_S
  120. except FileNotFoundError:
  121. return
  122. if not stale:
  123. return
  124. # A writer that died holding the lock must not wedge every later write. Writes hold it for
  125. # milliseconds, and the data file itself is only ever replaced whole.
  126. try:
  127. _owner_file(lock_dir).unlink(missing_ok=True)
  128. os.rmdir(lock_dir)
  129. except OSError:
  130. pass
  131. @contextmanager
  132. def _store_lock(path: Path) -> Iterator[Callable[[], bool]]:
  133. """Cross-process lock shared with the Electron writer: the ``<store>.lock`` directory, whose
  134. ``owner`` file names the holder."""
  135. lock_dir = path.with_name(path.name + ".lock")
  136. token = f"{os.getpid()}-{secrets.token_hex(8)}"
  137. deadline = time.monotonic() + _LOCK_WAIT_S
  138. with _thread_lock:
  139. while True:
  140. try:
  141. os.mkdir(lock_dir)
  142. break
  143. except FileExistsError:
  144. _break_if_stale(lock_dir)
  145. if time.monotonic() > deadline:
  146. raise PreferencesBusy("preferences store is busy")
  147. time.sleep(_LOCK_POLL_S)
  148. try:
  149. _owner_file(lock_dir).write_text(token, encoding="utf-8")
  150. yield lambda: _owns(lock_dir, token)
  151. finally:
  152. _release(lock_dir, token)
  153. def _merge(current: Mapping[str, str], changes: Mapping[str, Optional[str]], seed: bool) -> dict[str, str]:
  154. values = dict(current)
  155. for key, value in changes.items():
  156. if seed:
  157. # A client's first contact: fill what the store lacks, never overwrite or delete.
  158. if value is not None:
  159. values.setdefault(key, value)
  160. elif value is None:
  161. values.pop(key, None)
  162. else:
  163. values[key] = value
  164. return values
  165. def write_preferences(changes: Mapping[str, Optional[str]], *, seed: bool = False,
  166. path: Optional[Path] = None) -> dict:
  167. """Merge *changes* per key (``None`` deletes) and return the resulting snapshot.
  168. ``seed=True`` is a client's first contact with this store generation: it only adds the keys
  169. the store lacks (and creates no store from nothing), so a client that has data fills a store
  170. an empty client created and no client's values are overwritten or deleted.
  171. """
  172. _validate(changes)
  173. path = path or store_path()
  174. path.parent.mkdir(parents=True, exist_ok=True)
  175. with _store_lock(path) as still_ours:
  176. current, corrupt = _read(path)
  177. values = _merge(current["values"], changes, seed)
  178. if len(values) > MAX_KEYS or sum(len(k) + len(v) for k, v in values.items()) > MAX_TOTAL_CHARS:
  179. raise PreferencesError("preferences store is full")
  180. if values == current["values"] and (current["exists"] or not values):
  181. return current
  182. revision = current["revision"] + 1
  183. generation = current.get("generation") or secrets.token_hex(8)
  184. if not still_ours():
  185. # Held past the stale limit and broken by another writer: replacing the file now
  186. # could drop the keys that writer merged meanwhile.
  187. raise PreferencesBusy("preferences store lock was taken over")
  188. if corrupt:
  189. # Kept aside, never silently replaced: it may hold preferences worth recovering.
  190. shutil.copy2(path, path.with_name(f"{path.name}.corrupt-{int(time.time() * 1000)}"))
  191. atomic_json_write(path, {"version": 1, "generation": generation, "revision": revision,
  192. "values": values}, mode=0o600)
  193. return {"exists": True, "revision": revision, "values": values, "generation": generation}