update_lock.py 73 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682
  1. """Cross-process mutual exclusion for in-flight Hermes updates.
  2. Two artifacts, one authority each:
  3. * The update marker ``<root hermes home>/.hermes-update-in-progress`` (contract C1, format v2)
  4. is shared with the Tauri updater (``UpdateMarkerGuard`` in
  5. ``apps/bootstrap-installer/src-tauri/src/update.rs``), the Electron gate
  6. (``electron/update-marker.ts``) and the Desktop hand-off scripts. Body::
  7. <pid>\\n<started_at>\\nct:<owner creation time, 3 decimals>\\n[delegate:<pid> ct:<ct>\\n]
  8. An owner is live while its pid is alive and its creation time still matches: never by age
  9. (the 20-minute ceiling only ages out v1 markers, which carry no creation time).
  10. * The checkout lock ``<git common dir>/hermes-update.lock`` (``<install root>/.hermes-update.lock``
  11. for a ZIP install with no ``.git``) — a kernel lock (flock / msvcrt) that ``hermes update``
  12. holds for its whole process tree, so two updates of one checkout started from different
  13. homes exclude each other and a killed updater whose completion child still runs keeps the
  14. checkout locked until that child exits. In the git dir it is never a worktree file: no
  15. ``git status``/autostash sees it, whatever the checked-out tree's ``.gitignore`` says.
  16. """
  17. from __future__ import annotations
  18. import calendar
  19. import errno
  20. import logging
  21. import os
  22. import re
  23. import secrets
  24. import subprocess
  25. import sys
  26. import threading
  27. import time
  28. from contextlib import contextmanager, suppress
  29. from dataclasses import dataclass
  30. from functools import cache
  31. from pathlib import Path
  32. from stat import S_ISREG
  33. logger = logging.getLogger(__name__)
  34. # Applies to v1 markers only (no creation-time line): their pid may have been reused, and a
  35. # ceiling is the only way such a marker self-heals. A v2 owner is live for as long as it runs.
  36. UPDATE_MARKER_MAX_AGE_SECONDS = 20 * 60
  37. # Clock skew allowed between a recorded and a probed process creation time (C1 rule 3).
  38. CREATE_TIME_TOLERANCE_SECONDS = 2.0
  39. # Our own creation time re-probed by the same clock: only the marker's 3-decimal rounding differs,
  40. # while two processes are at least one scheduler tick (10 ms) apart.
  41. _OWN_CREATE_TIME_EPSILON = 0.005
  42. # macOS shells read a creation time from `ps -o lstart` and write it as whole seconds (`ct:N.000`),
  43. # truncated. A whole-second claim inside the second we started in is still our incarnation.
  44. _WHOLE_SECOND_CT = 1.0
  45. # A claim published by create-then-write (filesystems without hard links) is briefly empty; an
  46. # empty marker this young is a claim in flight, not a dead one (contract A3).
  47. EMPTY_MARKER_GRACE_SECONDS = 5.0
  48. MARKER_NAME = ".hermes-update-in-progress"
  49. CHECKOUT_LOCK_NAME = ".hermes-update.lock"
  50. GIT_CHECKOUT_LOCK_NAME = "hermes-update.lock"
  51. # Set by an orchestrating updater (Tauri `hermes-setup --update`) to its own pid before
  52. # spawning `hermes update` as a child stage; the parent holds the marker for its whole run,
  53. # so without this the child would refuse its own parent's lock. Keep in sync with
  54. # update_child_env in apps/bootstrap-installer/src-tauri/src/update.rs.
  55. HANDOFF_PID_ENV = "HERMES_UPDATE_HANDOFF_PID"
  56. # Bound on the parent chain walked by _is_ancestor_pid. Real ancestries are a
  57. # handful of links (init -> desktop -> staged updater -> shim -> us); the cap
  58. # only exists so an unexpected chain can never spin the walk.
  59. _MAX_ANCESTRY_DEPTH = 128
  60. # Exit code meaning "another updater/instance owns this install right now" — the same
  61. # contract as the Windows shim / venv-holder guards in _cmd_update_impl, matched by the
  62. # Tauri updater (UPDATE_EXIT_CONCURRENT in update.rs) to show "Hermes is still running".
  63. UPDATE_EXIT_CONCURRENT = 2
  64. # msvcrt locks a byte range; lock one byte far past the holder record so other processes can
  65. # still read who holds it (a locked range is unreadable to them on Windows).
  66. _WINDOWS_LOCK_OFFSET = 1 << 20
  67. # R5b: the lease bytes just past it. A Windows process that joins its ancestor's lock (it cannot
  68. # inherit it) also locks one lease byte of its own: a completion child the job refused runs
  69. # outside the kill-on-close job and outlives a killed owner, and its lease keeps the checkout
  70. # busy until it exits. Takers and probes treat any held lease as a held lock.
  71. _LEASE_SLOTS = 16
  72. _FILETIME_UNIX_EPOCH = 116444736000000000
  73. def update_marker_path() -> Path:
  74. """Path of the shared update marker: always the profile-tree ROOT home.
  75. A sticky or ``-p`` profile re-homes ``HERMES_HOME`` to ``<root>/profiles/<p>``; the Desktop,
  76. the hand-off scripts and the Tauri updater all look at the root, so a profile-scoped marker
  77. would be one the other owners never see.
  78. """
  79. try:
  80. from hermes_constants import get_default_hermes_root
  81. except ImportError: # a partial tree (an -I -S completion child of a stubbed checkout)
  82. home = Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes")
  83. root = home.parent.parent if home.parent.name == "profiles" else home
  84. return root / MARKER_NAME
  85. return get_default_hermes_root() / MARKER_NAME
  86. def _default_install_root() -> Path:
  87. return Path(__file__).resolve().parents[1]
  88. def _git_common_dir(root: Path) -> Path | None:
  89. """The repository's common git dir, read from disk (no git process: -I -S children).
  90. ``.git`` is the dir itself, or a ``gitdir: <path>`` file (linked worktree, submodule) whose
  91. target may name the shared dir in ``commondir``. ``None`` when ``root`` is no checkout.
  92. """
  93. dot = root / ".git"
  94. try:
  95. if dot.is_dir():
  96. gitdir = dot
  97. elif dot.is_file():
  98. text = dot.read_text(encoding="utf-8-sig").strip()
  99. if not text.startswith("gitdir:"):
  100. return None
  101. gitdir = root / text[len("gitdir:"):].strip() # an absolute target replaces root
  102. else:
  103. return None
  104. common = gitdir / "commondir"
  105. if common.is_file():
  106. gitdir = gitdir / common.read_text(encoding="utf-8-sig").strip()
  107. except OSError:
  108. return None
  109. return Path(os.path.normpath(gitdir))
  110. def checkout_lock_path(install_root: Path | str | None = None) -> Path:
  111. root = Path(install_root or _default_install_root())
  112. common = _git_common_dir(root)
  113. return root / CHECKOUT_LOCK_NAME if common is None else common / GIT_CHECKOUT_LOCK_NAME
  114. def _pid_alive(pid: int) -> bool:
  115. """Use the dependency-free, Windows-safe, zombie-aware probe before PM is available."""
  116. if pid <= 0:
  117. return False
  118. try:
  119. from hermes_cli._early_recovery import _pid_is_running
  120. return _pid_is_running(pid)
  121. except Exception as exc:
  122. logger.debug("Could not probe pid %s: %s", pid, exc)
  123. return False
  124. # --- process creation time ---------------------------------------------------------------
  125. @cache
  126. def _windows_kernel32():
  127. """kernel32 with OpenProcess/GetProcessTimes/CloseHandle typed, built once: update-fence polls
  128. reach it whenever psutil cannot read a marker pid's creation time."""
  129. import ctypes
  130. from ctypes import wintypes
  131. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  132. kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
  133. kernel32.OpenProcess.restype = wintypes.HANDLE
  134. kernel32.GetProcessTimes.argtypes = [wintypes.HANDLE] + [ctypes.POINTER(wintypes.FILETIME)] * 4
  135. kernel32.GetProcessTimes.restype = wintypes.BOOL
  136. kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
  137. kernel32.CloseHandle.restype = wintypes.BOOL
  138. return kernel32
  139. _LOCKFILE_FAIL_IMMEDIATELY = 0x1
  140. @cache
  141. def _windows_lockfile_api():
  142. """kernel32 with LockFileEx/UnlockFileEx typed, plus the OVERLAPPED struct, built once.
  143. Built per call, each fresh struct's ``ctypes.POINTER`` stays in ctypes' pointer-type cache
  144. forever before Python 3.14, so a gateway polling the checkout lock would leak per probe.
  145. """
  146. import ctypes
  147. from ctypes import wintypes
  148. class _Overlapped(ctypes.Structure):
  149. _fields_ = [("Internal", ctypes.c_void_p), ("InternalHigh", ctypes.c_void_p),
  150. ("Offset", wintypes.DWORD), ("OffsetHigh", wintypes.DWORD), ("hEvent", wintypes.HANDLE)]
  151. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  152. kernel32.LockFileEx.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD,
  153. wintypes.DWORD, ctypes.POINTER(_Overlapped)]
  154. kernel32.LockFileEx.restype = wintypes.BOOL
  155. kernel32.UnlockFileEx.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD,
  156. ctypes.POINTER(_Overlapped)]
  157. kernel32.UnlockFileEx.restype = wintypes.BOOL
  158. return kernel32, _Overlapped
  159. def _windows_create_filetime(pid: int) -> int | None:
  160. """GetProcessTimes creation FILETIME (100 ns ticks since 1601) or ``None``."""
  161. import ctypes
  162. from ctypes import wintypes
  163. kernel32 = _windows_kernel32()
  164. handle = kernel32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
  165. if not handle:
  166. return None
  167. try:
  168. times = [wintypes.FILETIME() for _ in range(4)]
  169. if not kernel32.GetProcessTimes(handle, *(ctypes.byref(t) for t in times)):
  170. return None
  171. return (times[0].dwHighDateTime << 32) | times[0].dwLowDateTime
  172. finally:
  173. kernel32.CloseHandle(handle)
  174. def _stdlib_create_time(pid: int) -> float | None:
  175. """Creation time in unix seconds without psutil (``-I -S`` children, early recovery).
  176. Same clock psutil reports: Linux ``starttime / CLK_TCK + btime``, macOS the kernel start
  177. time (``ps -o lstart=`` in UTC, second resolution — inside the 2 s tolerance), Windows the
  178. ``GetProcessTimes`` creation FILETIME.
  179. """
  180. try:
  181. if sys.platform == "win32":
  182. ticks = _windows_create_filetime(pid)
  183. return None if ticks is None else (ticks - _FILETIME_UNIX_EPOCH) / 1e7
  184. if os.path.isdir("/proc"):
  185. with open(f"/proc/{pid}/stat", "rb") as fh:
  186. stat = fh.read()
  187. start_ticks = int(stat[stat.rindex(b")") + 2:].split()[19])
  188. with open("/proc/stat", "rb") as fh:
  189. btime = next(int(line.split()[1]) for line in fh if line.startswith(b"btime "))
  190. return btime + start_ticks / os.sysconf("SC_CLK_TCK")
  191. # UTC wall clock: a local-time lstart is ambiguous in the repeated DST hour.
  192. out = subprocess.run(
  193. ["ps", "-o", "lstart=", "-p", str(pid)], capture_output=True, text=True,
  194. encoding="utf-8", errors="replace", timeout=5, stdin=subprocess.DEVNULL,
  195. env={"PATH": os.environ.get("PATH") or "/bin:/usr/bin", "LC_ALL": "C", "TZ": "UTC0"},
  196. check=False,
  197. ).stdout.strip()
  198. if not out:
  199. return None
  200. return float(calendar.timegm(time.strptime(" ".join(out.split()), "%a %b %d %H:%M:%S %Y")))
  201. except (OSError, ValueError, IndexError, StopIteration, subprocess.SubprocessError, AttributeError):
  202. return None
  203. def process_create_time(pid: int | None = None) -> float | None:
  204. """Creation time of ``pid`` (default: this process) in unix seconds, or ``None``.
  205. psutil when importable — the value ``process_identity._process_create_time`` records —
  206. else the stdlib probe of the same kernel clock, so a marker written by either is
  207. comparable by the other within :data:`CREATE_TIME_TOLERANCE_SECONDS`.
  208. """
  209. target = os.getpid() if pid is None else pid
  210. try:
  211. import psutil
  212. except ImportError:
  213. return _stdlib_create_time(target)
  214. try:
  215. return float(psutil.Process(target).create_time())
  216. except Exception: # health: allow BLE001 -- liveness probe: any psutil failure degrades to the stdlib probe
  217. return _stdlib_create_time(target)
  218. def _own_create_time() -> float | None:
  219. """This process's creation time (cached per pid: a forked child is another process)."""
  220. pid = os.getpid()
  221. if _OWN_CT.get("pid") != pid:
  222. _OWN_CT.update(pid=pid, ct=process_create_time(pid))
  223. return _OWN_CT.get("ct")
  224. _OWN_CT: dict = {}
  225. def _as_ct(recorded) -> float | None:
  226. """A recorded creation time as a float: a number, ``"ct:<s>"`` / ``"<s>"`` text, or None."""
  227. if recorded is None or isinstance(recorded, (int, float)):
  228. return None if recorded is None else float(recorded)
  229. match = _CT_VALUE.fullmatch(str(recorded).strip().removeprefix("ct:"))
  230. return float(match.group(0)) if match else None
  231. def incarnation_live(pid: int, recorded_ct=None) -> bool | None:
  232. """THE one incarnation rule (A7 rule 4) for every Python identity reader (marker, pause record).
  233. An identity is (pid, creation time). ``True``: that process is running. ``False``: no such
  234. process, a different incarnation of the pid, or a claim naming OUR pid that is not us — our
  235. own pid is ours only within :data:`_OWN_CREATE_TIME_EPSILON` of our creation time, and a
  236. claim without a creation time naming our pid is a previous incarnation (a fresh pid
  237. namespace hands a killed update's pid to the next launch) — unless our own creation time is
  238. unreadable: then we write no-ct claims ourselves, so a no-ct claim is ours and a ct one is
  239. not (``marker.rs`` agrees). ``None``: alive but unprovable — no creation time recorded, or
  240. the live one unreadable (Windows denies elevated/other-user pids); each caller applies its
  241. own bound (the marker: the v1 age ceiling, :func:`_identity_live`).
  242. ``recorded_ct`` is a float or the marker spelling ``"ct:<seconds>"``.
  243. """
  244. try:
  245. pid = int(pid)
  246. except (TypeError, ValueError):
  247. return False
  248. return _incarnation(pid, _as_ct(recorded_ct), _real_world())
  249. @dataclass(frozen=True)
  250. class _World:
  251. """What a marker verdict depends on besides the bytes: us, the clock, the process table.
  252. Production uses :func:`_real_world`; the shared corpus injects a table."""
  253. pid: int
  254. ct: float | None
  255. now: float
  256. alive: object # Callable[[int], bool]
  257. ct_of: object # Callable[[int], float | None]
  258. def _real_world() -> _World:
  259. return _World(os.getpid(), _own_create_time(), time.time(), _pid_alive, process_create_time)
  260. def _incarnation(pid: int, recorded: float | None, w: _World) -> bool | None:
  261. """:func:`incarnation_live` against world ``w``."""
  262. if pid <= 0:
  263. return False
  264. if pid == w.pid: # we are alive by definition: only the incarnation is in question
  265. if w.ct is None:
  266. return recorded is None
  267. if recorded is None:
  268. return False
  269. if abs(w.ct - recorded) <= _OWN_CREATE_TIME_EPSILON:
  270. return True
  271. return recorded.is_integer() and 0 <= w.ct - recorded < _WHOLE_SECOND_CT
  272. if not w.alive(pid):
  273. return False
  274. actual = None if recorded is None else w.ct_of(pid)
  275. return None if actual is None else abs(actual - recorded) <= CREATE_TIME_TOLERANCE_SECONDS
  276. def _identity_live(pid: int, create_time: float | None, age: float, world: _World | None = None) -> bool:
  277. """C1 rule 3 + A1 + A7 rule 4 for one (pid, ct) identity of a marker ``age`` seconds old:
  278. :func:`incarnation_live`, where an unprovable identity (a v1 marker, or a creation time we
  279. cannot read) may be a reused pid, so only the legacy age ceiling bounds it."""
  280. verdict = _incarnation(pid, create_time, world or _real_world())
  281. return age <= UPDATE_MARKER_MAX_AGE_SECONDS if verdict is None else verdict
  282. def _identity_line(pid: int | None = None) -> str:
  283. ct = process_create_time(pid)
  284. return "" if ct is None else f"ct:{ct:.3f}"
  285. # --- ancestry ----------------------------------------------------------------------------
  286. def _handoff_pid() -> int | None:
  287. """Pid of the orchestrating updater that spawned us (:data:`HANDOFF_PID_ENV`); malformed
  288. values count as absent so a broken handoff falls back to the normal refusal."""
  289. try:
  290. pid = int(os.environ.get(HANDOFF_PID_ENV, "").strip())
  291. except ValueError:
  292. return None
  293. return pid if pid > 0 else None
  294. @cache
  295. def _windows_toolhelp_api():
  296. """kernel32 with the Toolhelp32 process walk typed, plus PROCESSENTRY32W, built once.
  297. Like :func:`_windows_lockfile_api`: a struct built per call leaves its ``ctypes.POINTER`` in
  298. ctypes' pointer-type cache forever before Python 3.14. A private DLL instance, so the walk's
  299. prototypes always name the struct class returned with them.
  300. """
  301. import ctypes
  302. from ctypes import wintypes
  303. class PROCESSENTRY32W(ctypes.Structure):
  304. _fields_ = [
  305. ("dwSize", wintypes.DWORD), ("cntUsage", wintypes.DWORD),
  306. ("th32ProcessID", wintypes.DWORD), ("th32DefaultHeapID", ctypes.c_size_t),
  307. ("th32ModuleID", wintypes.DWORD), ("cntThreads", wintypes.DWORD),
  308. ("th32ParentProcessID", wintypes.DWORD), ("pcPriClassBase", ctypes.c_long),
  309. ("dwFlags", wintypes.DWORD), ("szExeFile", ctypes.c_wchar * 260),
  310. ]
  311. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  312. kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
  313. kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
  314. for walk in (kernel32.Process32FirstW, kernel32.Process32NextW):
  315. walk.argtypes = [wintypes.HANDLE, ctypes.POINTER(PROCESSENTRY32W)]
  316. walk.restype = wintypes.BOOL
  317. kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
  318. kernel32.CloseHandle.restype = wintypes.BOOL
  319. return kernel32, PROCESSENTRY32W
  320. def _windows_parent_pid(pid: int) -> int | None:
  321. """The parent of ``pid`` from a Toolhelp32 process snapshot (stdlib ctypes).
  322. Windows keeps a dead parent's pid in the snapshot and reuses pids, so, like
  323. psutil, a "parent" created after the child is a recycled pid, not our parent.
  324. """
  325. import ctypes
  326. kernel32, PROCESSENTRY32W = _windows_toolhelp_api()
  327. snapshot = kernel32.CreateToolhelp32Snapshot(0x2, 0) # TH32CS_SNAPPROCESS
  328. if not snapshot or snapshot == ctypes.c_void_p(-1).value:
  329. return None
  330. parent = None
  331. try:
  332. entry = PROCESSENTRY32W()
  333. entry.dwSize = ctypes.sizeof(PROCESSENTRY32W)
  334. found = kernel32.Process32FirstW(snapshot, ctypes.byref(entry))
  335. while found:
  336. if entry.th32ProcessID == pid:
  337. parent = int(entry.th32ParentProcessID)
  338. break
  339. found = kernel32.Process32NextW(snapshot, ctypes.byref(entry))
  340. finally:
  341. kernel32.CloseHandle(snapshot)
  342. if not parent:
  343. return None
  344. parent_created, child_created = _windows_create_filetime(parent), _windows_create_filetime(pid)
  345. if parent_created is not None and child_created is not None and parent_created > child_created:
  346. return None
  347. return parent
  348. def _stdlib_parent_pid(pid: int) -> int | None:
  349. """The parent of ``pid`` without psutil, or ``None`` when unresolvable.
  350. The update-takeover child is spawned ``-I -S -B`` (hermes_cli/_old_updater.py) so
  351. psutil cannot import there — and that grandchild is exactly the process that most
  352. needs the two-hop ancestry walk to adopt the orchestrator's marker. /proc serves
  353. Linux; macOS keeps /proc absent, so shell out to ps once per hop; Windows has
  354. neither, so ask the Toolhelp32 snapshot.
  355. """
  356. if sys.platform == "win32":
  357. try:
  358. return _windows_parent_pid(pid)
  359. except (OSError, AttributeError, ValueError):
  360. return None
  361. try:
  362. if os.path.isdir("/proc"):
  363. with open(f"/proc/{pid}/stat", "rb") as fh:
  364. stat = fh.read()
  365. else:
  366. out = subprocess.run(
  367. ["ps", "-o", "ppid=", "-p", str(pid)],
  368. capture_output=True, text=True, encoding="utf-8", errors="replace", check=True, timeout=5,
  369. stdin=subprocess.DEVNULL,
  370. ).stdout
  371. value = int(out.strip() or -1)
  372. return value if value > 0 else None
  373. except (OSError, ValueError, subprocess.SubprocessError):
  374. return None
  375. # Field 4 (1-indexed) is ppid, but comm may contain spaces/parens: split
  376. # after the closing paren of comm instead of on whitespace.
  377. try:
  378. return int(stat[stat.rindex(b")") + 2:].split()[1])
  379. except (ValueError, IndexError):
  380. return None
  381. def _is_ancestor_pid(pid: int) -> bool:
  382. """True when ``pid`` is a live ancestor of this process.
  383. The orchestrating updater spawns ``hermes update`` as a (grand)child, so a live marker
  384. owned by one of our ancestors can only be the claim we are already running under — an
  385. unrelated concurrent updater is never in our parent chain. This heals the fleet of staged
  386. ``hermes-setup`` binaries that predate the HANDOFF_PID_ENV export and can never send it.
  387. The chain is walked one link at a time and each ancestor is tested as it is
  388. discovered. ``psutil.Process.parents()`` cannot be used here: it builds the
  389. whole chain up to the lowest pid *before* returning, and its per-link
  390. ``parent()`` tolerates only ``NoSuchProcess``. So any process we may not
  391. inspect anywhere above us raises ``AccessDenied`` and discards the
  392. ancestors already collected — including the orchestrator one link down.
  393. That is not exotic: under firejail with ``ptrace_scope=1``, and in hardened
  394. containers, ``/proc/1`` is unreadable, so the GUI update deadlocked against
  395. its own parent on every attempt. Walking incrementally means a failure
  396. *above* the match can no longer hide it.
  397. Never includes our own pid, and any failure encountered before a match
  398. counts as "not an ancestor": an unprovable ancestry must fall back to the
  399. normal refusal.
  400. """
  401. if pid <= 0:
  402. return False
  403. if pid == os.getppid():
  404. return True
  405. try:
  406. import psutil
  407. proc = psutil.Process()
  408. seen = {proc.pid}
  409. for _ in range(_MAX_ANCESTRY_DEPTH):
  410. parent = proc.parent()
  411. if parent is None:
  412. return False
  413. if parent.pid == pid:
  414. return True
  415. if parent.pid in seen:
  416. # Defensive only: psutil's create_time check already rejects a
  417. # reused ppid, so a true cycle should be unreachable.
  418. return False
  419. seen.add(parent.pid)
  420. proc = parent
  421. logger.debug(
  422. "Gave up walking process ancestry for pid %s after %s links",
  423. pid,
  424. _MAX_ANCESTRY_DEPTH,
  425. )
  426. return False
  427. except ImportError:
  428. # -I -S -B takeover child: walk the same chain with stdlib probes.
  429. child = os.getpid()
  430. for _ in range(32):
  431. parent = _stdlib_parent_pid(child)
  432. if parent is None:
  433. return False
  434. if parent == pid:
  435. return True
  436. if parent == child: # pid 1 re-parenting or a kernel loop guard
  437. return False
  438. child = parent
  439. return False
  440. except Exception as exc:
  441. logger.debug("Could not walk process ancestry for pid %s: %s", pid, exc)
  442. return False
  443. def _is_runtime_host(cmdline: list[str]) -> bool:
  444. """A long-lived Hermes host (``gateway run`` / ``serve`` / ``dashboard``), by the canonical
  445. command-line matchers (profile flags, ``hermes_cli/main.py`` paths, inline bootstraps)."""
  446. from gateway.status import looks_like_gateway_command_line
  447. from hermes_cli.update_cmd_windows import _hermes_holder_subcommand
  448. line = " ".join(cmdline)
  449. return looks_like_gateway_command_line(line) or _hermes_holder_subcommand(line) in ("serve", "dashboard")
  450. def _runtime_host_below(holder_pid: int) -> bool:
  451. """True when a Hermes gateway/serve/dashboard sits between us and *holder_pid* (or anywhere
  452. above us when the holder is not reached).
  453. Such a host is relaunched BY an update and outlives its stages; a ``hermes update`` its agent
  454. or ``/update`` starts is an independent update that must not run under the first one's claim
  455. (cli §7 V9). Unreadable command lines count as not-a-host (the legacy adoption stands).
  456. """
  457. try:
  458. import psutil
  459. except ImportError:
  460. return False
  461. try:
  462. proc = psutil.Process().parent()
  463. for _ in range(_MAX_ANCESTRY_DEPTH):
  464. if proc is None or proc.pid == holder_pid:
  465. return False
  466. with suppress(psutil.Error):
  467. if _is_runtime_host(proc.cmdline()):
  468. return True
  469. proc = proc.parent()
  470. except psutil.Error:
  471. return False
  472. return False
  473. # --- the marker --------------------------------------------------------------------------
  474. @dataclass(frozen=True)
  475. class UpdateHolder:
  476. """A confirmed-live update holding the lock, or the reason a claim was refused.
  477. ``held``: the marker's identities are dead but the checkout kernel lock is still held (a
  478. killed updater's completion/build child or git still runs) — the update is NOT over; the
  479. hand-off scripts' ``held`` verdict."""
  480. pid: int
  481. age_seconds: float
  482. reason: str | None = None
  483. held: bool = False
  484. _U32_MAX = 0xFFFFFFFF
  485. _U64_MAX = 0xFFFFFFFFFFFFFFFF
  486. _INT_LINE = re.compile(r"[0-9]+", re.ASCII)
  487. _CT_VALUE = re.compile(r"[0-9]+(?:\.[0-9]+)?", re.ASCII)
  488. _CT_LINE = re.compile(r"ct:([0-9]+(?:\.[0-9]+)?)", re.ASCII)
  489. _DELEGATE_LINE = re.compile(r"delegate:([0-9]+) ct:([0-9]+(?:\.[0-9]+)?)", re.ASCII)
  490. _RUN_LINE = re.compile(r"run:([A-Za-z0-9._-]{1,128})", re.ASCII)
  491. @dataclass(frozen=True)
  492. class _Marker:
  493. raw: bytes
  494. pid: int
  495. started_at: int | None
  496. create_time: float | None
  497. delegate_pid: int | None
  498. delegate_create_time: float | None
  499. in_flight: bool = False # an empty marker younger than EMPTY_MARKER_GRACE_SECONDS
  500. ct_text: str | None = None
  501. delegate_ct_text: str | None = None
  502. runs: tuple[str, ...] = ()
  503. @property
  504. def base(self) -> bytes:
  505. """Lines 1–3 exactly as written (what a delegate keeps byte-identical)."""
  506. return b"".join(self.raw.splitlines(keepends=True)[:3])
  507. @property
  508. def run(self) -> str | None:
  509. return self.runs[0] if self.runs else None
  510. def age(self, world: _World | None = None) -> float:
  511. now = time.time() if world is None else world.now
  512. return now - self.started_at if self.started_at is not None else float("inf")
  513. def owner_live(self, world: _World | None = None) -> bool:
  514. return self.started_at is not None \
  515. and _identity_live(self.pid, self.create_time, self.age(world), world)
  516. def delegate_live(self, world: _World | None = None) -> bool:
  517. return self.delegate_pid is not None and self.started_at is not None \
  518. and _identity_live(self.delegate_pid, self.delegate_create_time, self.age(world), world)
  519. def live_pid(self, world: _World | None = None) -> int | None:
  520. if self.in_flight:
  521. return 0
  522. if self.owner_live(world):
  523. return self.pid
  524. return self.delegate_pid if self.delegate_live(world) else None
  525. def canonical(self, pid: int, ct_text: str | None) -> bytes:
  526. """A rewritten claim (A7 rule 5): ``pid`` owns it from ``started_at`` on; run lines kept."""
  527. body = f"{pid}\n{self.started_at}\n" + (f"ct:{ct_text}\n" if ct_text else "")
  528. return (body + "".join(f"run:{run}\n" for run in self.runs)).encode()
  529. def _bounded_int(text: str, limit: int) -> int | None:
  530. """ASCII digits whose value fits ``limit`` (u32 pid, u64 started_at — Rust's ``parse``), else
  531. None. Leading zeros are fine; the significant digits are counted BEFORE ``int()``, which
  532. refuses past 4300 digits — an oversized field is malformed, never an exception."""
  533. if not _INT_LINE.fullmatch(text):
  534. return None
  535. significant = text.lstrip("0") or "0"
  536. if len(significant) > len(str(limit)):
  537. return None
  538. value = int(significant)
  539. return value if value <= limit else None
  540. def _parse_marker(raw: bytes, *, mtime: float | None = None) -> _Marker:
  541. """Contract A2 + A7 rule 7, identical in every reader (Rust ``marker.rs``, Electron, the
  542. hand-off scripts; ``tests/fixtures/update_marker_corpus.json``): BOM, CRLF and surrounding
  543. spaces/tabs tolerated; line 1 pid (u32) and line 2 started_at (u64) are integers or the marker is
  544. MALFORMED (dead: ``started_at`` None); a bad line 3 makes it v1; lines 4+ are tagged — the
  545. first well-formed ``delegate:<pid> ct:<ct>`` and every ``run:<id>`` — anything else ignored."""
  546. text = raw.decode("utf-8", errors="replace").removeprefix("\ufeff")
  547. lines = [line.removesuffix("\r").strip(" \t") for line in text.split("\n")]
  548. lines += [""] * (3 - len(lines))
  549. pid = _bounded_int(lines[0], _U32_MAX)
  550. started_at = _bounded_int(lines[1], _U64_MAX) if pid is not None else None
  551. pid = -1 if pid is None else pid
  552. ct = _CT_LINE.fullmatch(lines[2])
  553. delegates = ((m, _bounded_int(m.group(1), _U32_MAX)) for m in map(_DELEGATE_LINE.fullmatch, lines[3:]) if m)
  554. delegate, delegate_pid = next(((m, d) for m, d in delegates if d is not None), (None, None))
  555. runs = tuple(m.group(1) for m in map(_RUN_LINE.fullmatch, lines[3:]) if m)
  556. in_flight = not raw and mtime is not None and time.time() - mtime < EMPTY_MARKER_GRACE_SECONDS
  557. return _Marker(
  558. raw=raw, pid=pid, started_at=started_at, create_time=float(ct.group(1)) if ct else None,
  559. delegate_pid=delegate_pid,
  560. delegate_create_time=float(delegate.group(2)) if delegate else None, in_flight=in_flight,
  561. ct_text=ct.group(1) if ct else None, delegate_ct_text=delegate.group(2) if delegate else None,
  562. runs=runs,
  563. )
  564. def judge_marker(raw: bytes, world: _World | None = None) -> tuple[str, int | None, str | None]:
  565. """``(verdict, owner, run)`` of marker bytes — the shared corpus' judge contract.
  566. verdict: ``malformed`` | ``dead`` | ``ours`` (a live identity is this incarnation) | ``live``;
  567. owner: the owner identity if live, else the delegate if live, else None.
  568. """
  569. w = world or _real_world()
  570. marker = _parse_marker(raw)
  571. if marker.started_at is None:
  572. return "malformed", None, None
  573. owner = marker.live_pid(w)
  574. if owner is None:
  575. return "dead", None, marker.run
  576. ours = (marker.pid == w.pid and marker.owner_live(w)) \
  577. or (marker.delegate_pid == w.pid and marker.delegate_live(w))
  578. return ("ours" if ours else "live"), owner, marker.run
  579. def _release_decision(raw: bytes, world: _World | None = None) -> tuple[str, bytes | None]:
  580. """A7 rule 5: what releasing ``world``'s claim does to marker bytes ``raw``.
  581. ``("delete", None)`` | ``("rewrite", new bytes)`` | ``("keep", None)``. The owner (line 1–3
  582. identity is our incarnation) deletes — regardless of delegate lines — unless a live delegate
  583. other than us exists: then that delegate becomes the owner. A delegate (us) drops its line
  584. while the owner lives, else deletes. Anything not naming us is kept.
  585. """
  586. w = world or _real_world()
  587. marker = _parse_marker(raw)
  588. if marker.started_at is None:
  589. return "keep", None
  590. if marker.pid == w.pid and marker.owner_live(w):
  591. if marker.delegate_pid not in (None, w.pid) and marker.delegate_live(w):
  592. return "rewrite", marker.canonical(marker.delegate_pid, marker.delegate_ct_text)
  593. return "delete", None
  594. if marker.delegate_pid == w.pid and marker.delegate_live(w):
  595. if marker.owner_live(w):
  596. return "rewrite", marker.canonical(marker.pid, marker.ct_text)
  597. return "delete", None
  598. return "keep", None
  599. def _read_bytes(path: Path) -> bytes | None:
  600. try:
  601. return path.read_bytes()
  602. except OSError:
  603. return None
  604. def _read_marker(path: Path) -> _Marker | None:
  605. raw = _read_bytes(path)
  606. if raw is None:
  607. return None
  608. mtime = None
  609. if not raw:
  610. with suppress(OSError):
  611. mtime = path.stat().st_mtime
  612. return _parse_marker(raw, mtime=mtime)
  613. def _tmp_sibling(path: Path) -> Path:
  614. return path.with_name(f"{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp")
  615. # Every tmp write of ours publishes or is unlinked well inside this: an older tmp under our own
  616. # pid number is a previous holder's (containers reuse pids every boot), never ours in flight.
  617. OWN_PID_TMP_STALE_SECONDS = 60.0
  618. def _tmp_writer_gone(owner: int | None, entry: Path) -> bool:
  619. if owner is None:
  620. return True # ASCII digits past u32: no process has that pid
  621. if owner != os.getpid():
  622. return not _pid_alive(owner)
  623. return time.time() - entry.stat().st_mtime > OWN_PID_TMP_STALE_SECONDS
  624. def _sweep_dead_tmp_siblings(path: Path) -> None:
  625. """Reclaim ``<marker>.<pid>[.<token>].tmp`` files whose writer died between write and
  626. publish (contract m10): the pid is the first component after the marker name."""
  627. prefix = f"{path.name}."
  628. with suppress(OSError):
  629. for entry in path.parent.iterdir():
  630. name = entry.name
  631. owner = name[len(prefix):].split(".", 1)[0]
  632. if not (name.startswith(prefix) and name.endswith(".tmp") and _INT_LINE.fullmatch(owner)):
  633. continue
  634. with suppress(OSError):
  635. if _tmp_writer_gone(_bounded_int(owner, _U32_MAX), entry):
  636. entry.unlink()
  637. # --- the marker mutex (A7 rule 1) -------------------------------------------------------------
  638. MUTEX_SUFFIX = ".lock"
  639. # Bounded wait for the sidecar: holders never run git/builds/network inside it.
  640. MUTEX_WAIT_SECONDS = 10.0
  641. class MarkerBusy(OSError):
  642. """The marker mutex stayed held past :data:`MUTEX_WAIT_SECONDS`: report busy."""
  643. _MUTEX_HELD = threading.local()
  644. def marker_mutex_path(path: Path) -> Path:
  645. """``<marker>.lock``: the sidecar every marker MUTATION holds a kernel lock on. Never deleted
  646. (deleting it would split the lock across two inodes)."""
  647. return path.with_name(path.name + MUTEX_SUFFIX)
  648. def _windows_open_exclusive(path: Path):
  649. """The Windows sidecar mutex: the file opened with NO sharing (``FileShare.None`` in the
  650. PowerShell scripts, ``share_mode(0)`` in marker.rs). ``None`` = someone else has it open."""
  651. import ctypes
  652. from ctypes import wintypes
  653. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  654. kernel32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p,
  655. wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
  656. kernel32.CreateFileW.restype = wintypes.HANDLE
  657. invalid = ctypes.c_void_p(-1).value
  658. for access, disposition in ((0xC0000000, 4), (0x80000000, 3)): # RW OPEN_ALWAYS; R OPEN_EXISTING
  659. handle = kernel32.CreateFileW(str(path), access, 0, None, disposition, 0x80, None)
  660. if handle and handle != invalid:
  661. return handle
  662. error = ctypes.get_last_error()
  663. if error == 32: # ERROR_SHARING_VIOLATION: held
  664. return None
  665. if error != 5: # anything but access denied: no read-only retry helps
  666. break
  667. raise ctypes.WinError(error)
  668. def _windows_close(handle) -> None:
  669. import ctypes
  670. ctypes.WinDLL("kernel32").CloseHandle(handle)
  671. def _mutex_acquire(path: Path, wait: float):
  672. deadline = time.monotonic() + wait
  673. if sys.platform == "win32":
  674. while True:
  675. handle = _windows_open_exclusive(path)
  676. if handle is not None:
  677. return handle
  678. if time.monotonic() >= deadline:
  679. raise MarkerBusy(f"{path} is held by another update")
  680. time.sleep(0.02)
  681. import fcntl
  682. try:
  683. fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o644)
  684. except PermissionError:
  685. fd = os.open(path, os.O_RDONLY) # flock works on a read-only fd (root-owned sidecar)
  686. try:
  687. while True:
  688. try:
  689. fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
  690. return fd
  691. except BlockingIOError:
  692. if time.monotonic() >= deadline:
  693. raise MarkerBusy(f"{path} is held by another update") from None
  694. time.sleep(0.02)
  695. except BaseException:
  696. os.close(fd)
  697. raise
  698. @contextmanager
  699. def marker_mutex(path: Path, *, wait: float = MUTEX_WAIT_SECONDS):
  700. """Hold the kernel lock on ``<marker>.lock`` (A7 rule 1): read → judge → mutate of the marker
  701. at ``path`` happens entirely inside. Re-entrant per thread; the kernel releases it if we die.
  702. Raises :class:`MarkerBusy` after ``wait`` seconds, ``OSError`` when it cannot be opened."""
  703. key = str(marker_mutex_path(path))
  704. held = getattr(_MUTEX_HELD, "keys", None)
  705. if held is None:
  706. held = _MUTEX_HELD.keys = {}
  707. if held.get(key):
  708. held[key] += 1
  709. try:
  710. yield
  711. finally:
  712. held[key] -= 1
  713. return
  714. handle = _mutex_acquire(Path(key), wait)
  715. held[key] = 1
  716. try:
  717. yield
  718. finally:
  719. held.pop(key, None)
  720. if sys.platform == "win32":
  721. _windows_close(handle)
  722. else:
  723. os.close(handle) # closing the only fd of this open file description drops the flock
  724. def _compare_and_swap(path: Path, expected: bytes, new: bytes) -> bool:
  725. """Atomically replace ``path`` (tmp + ``os.replace``) only while it still holds ``expected``,
  726. under the marker mutex."""
  727. with marker_mutex(path):
  728. if _read_bytes(path) != expected:
  729. return False
  730. tmp = _tmp_sibling(path)
  731. try:
  732. with open(tmp, "wb") as fh:
  733. fh.write(new)
  734. fh.flush()
  735. os.fsync(fh.fileno())
  736. os.replace(tmp, path)
  737. return True
  738. except OSError as exc:
  739. logger.debug("Could not rewrite update marker %s: %s", path, exc)
  740. return False
  741. finally:
  742. with suppress(OSError):
  743. tmp.unlink()
  744. def _live_partners(marker: _Marker) -> list[int]:
  745. """Live identities behind a marker: the owner, then the delegate (``[0]`` for a claim
  746. still being written). A claim naming our own pid counts only at our exact incarnation."""
  747. if marker.in_flight:
  748. return [0]
  749. partners = []
  750. if marker.owner_live():
  751. partners.append(marker.pid)
  752. if marker.delegate_live():
  753. partners.append(marker.delegate_pid)
  754. return partners
  755. def read_live_update(*, path: Path | None = None, install_root: Path | str | None = None) -> UpdateHolder | None:
  756. """Return the live update holding the marker, or ``None``.
  757. Absent, unreadable, malformed and dead-owner all mean "no live update" — unless the
  758. checkout kernel lock of ``install_root`` (default: this checkout) is held: then a killed
  759. updater's tree (its completion, build or git) still runs, the marker is kept, and the
  760. answer is a ``held`` holder (R6; ``marker.sh``/``marker.ps1`` answer ``held`` too). Otherwise
  761. a dead marker is reclaimed — judged again and removed inside the marker mutex, so a claim
  762. published after our first read is never the one deleted. Never raises: a marker that cannot
  763. be judged at all also reads as ``None``. That fails open on the MARKER only; the checkout
  764. kernel lock is the guard, and every caller that acts on ``None`` still consults it
  765. (``update_in_progress`` ORs :func:`checkout_lock_held`; ``UpdateLock.acquire`` /
  766. ``acquire_checkout`` take it), so a live update is never joined or raced through this answer.
  767. """
  768. marker = path or update_marker_path()
  769. try:
  770. # "live" from the locked recheck = a claim replaced our dead snapshot: judge that claim
  771. # rather than answer "clear" (F2) — a marker-only claim has no checkout lease to OR in.
  772. for _attempt in range(2):
  773. parsed = _read_marker(marker)
  774. if parsed is None:
  775. return None
  776. live = parsed.live_pid()
  777. if live is not None:
  778. return UpdateHolder(pid=live, age_seconds=parsed.age() if parsed.started_at is not None else 0.0)
  779. verdict = _reclaim_dead(marker, install_root)
  780. if verdict == "held":
  781. return UpdateHolder(pid=0, held=True,
  782. age_seconds=max(parsed.age(), 0.0) if parsed.started_at is not None else 0.0)
  783. if verdict != "live":
  784. break
  785. except Exception as exc: # health: allow BLE001 -- never raises: fails open on the marker only; the kernel lock guards (doc)
  786. logger.debug("Could not judge update marker %s: %s", marker, exc)
  787. return None
  788. def _reclaim_dead(path: Path, install_root: Path | str | None = None) -> str:
  789. """Remove a dead marker under the mutex: ``reclaimed`` | ``held`` (dead, but the checkout lock
  790. is held, so it is kept) | ``live`` (a claim appeared) | ``absent`` | ``busy``."""
  791. try:
  792. with marker_mutex(path):
  793. current = _read_marker(path)
  794. if current is None:
  795. return "absent"
  796. if current.live_pid() is not None:
  797. return "live"
  798. if checkout_lock_held(install_root):
  799. return "held"
  800. with suppress(FileNotFoundError):
  801. path.unlink()
  802. return "reclaimed"
  803. except OSError as exc: # MarkerBusy included: someone else is deciding right now
  804. logger.debug("Left update marker %s for its current mutator: %s", path, exc)
  805. return "busy"
  806. def legacy_profile_claims(root: Path | None = None) -> list[UpdateHolder]:
  807. """Live claims in pre-root-marker ``<root>/profiles/<p>/.hermes-update-in-progress`` files (R11).
  808. Before the marker moved to the profile-tree root, an update under a named profile claimed
  809. its PROFILE home and never took the checkout lock. During the transition such an update can
  810. still be running: honor it (v1 rules: pid alive, within the legacy age ceiling, never our own
  811. previous incarnation). Read-only: an old updater reclaims its own dead markers.
  812. """
  813. root = update_marker_path().parent if root is None else root
  814. claims = []
  815. with suppress(OSError):
  816. for profile in (root / "profiles").iterdir():
  817. marker = _read_marker(profile / MARKER_NAME)
  818. if marker is None or marker.in_flight:
  819. continue
  820. live = marker.live_pid()
  821. if live:
  822. claims.append(UpdateHolder(pid=live, age_seconds=marker.age()))
  823. return claims
  824. def describe_holder(holder: UpdateHolder | None) -> str:
  825. """One-line, user-facing explanation of who holds the update lock."""
  826. if holder is not None and holder.reason:
  827. return (
  828. f"✗ Cannot lock this install for the update: {holder.reason}.\n"
  829. "\n"
  830. " Updating without the lock could let two updates corrupt the install, or run\n"
  831. " under a Desktop app, gateway or installer that cannot see it. Make that path\n"
  832. " writable (fix its owner or permissions, or remount a read-only filesystem\n"
  833. " read-write), or run `hermes update` as the user that owns the install."
  834. )
  835. minutes, seconds = divmod(int(max(0 if holder is None else holder.age_seconds, 0)), 60)
  836. elapsed = f"{minutes}m {seconds}s" if minutes else f"{seconds}s"
  837. who = f", process {holder.pid}" if holder and holder.pid else ""
  838. if holder is not None and holder.held:
  839. who = "; its owner exited but a process it started still holds the checkout"
  840. return (
  841. f"✗ Another Hermes update is already running (started {elapsed} ago{who}).\n"
  842. "\n"
  843. " Running two at once would corrupt the install. Wait for it to finish\n"
  844. " (watch `hermes logs`), or close the Desktop/dashboard window that\n"
  845. " started it, then run `hermes update` again."
  846. )
  847. # --- the checkout lock -------------------------------------------------------------------
  848. # This process's hold on the checkout lock: {"path", "fd", "owned", "depth"}. "owned" means
  849. # we opened and locked it; otherwise the fd was inherited from the `hermes update` that holds
  850. # it (pass_fds) and belongs to the whole tree — it is never unlocked or closed here.
  851. _HELD: dict | None = None
  852. _JOBS: list = []
  853. def _try_lock(fd: int) -> bool:
  854. """Take the checkout lock without waiting; False when the owner byte or any lease byte is held.
  855. Windows keeps the owner byte locked and only test-locks the lease bytes; POSIX flocks the file.
  856. The held? probe is :func:`_try_shared_lock`.
  857. """
  858. if sys.platform == "win32":
  859. if not _lock_bytes(fd, _WINDOWS_LOCK_OFFSET):
  860. return False
  861. if not _lock_bytes(fd, _WINDOWS_LOCK_OFFSET + 1, _LEASE_SLOTS): # a dead owner's leased child
  862. _unlock(fd)
  863. return False
  864. _unlock(fd, _WINDOWS_LOCK_OFFSET + 1, _LEASE_SLOTS)
  865. return True
  866. import fcntl
  867. try:
  868. fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
  869. except BlockingIOError:
  870. return False
  871. return True
  872. def _try_shared_lock(fd: int) -> bool:
  873. """The held? probe (:func:`checkout_lock_held`): a shared try over the owner byte and every
  874. lease byte. Holders lock exclusively, so it fails only on a holder, and two Python probes never
  875. read each other as one (the marker.sh / marker.ps1 probes still lock exclusively). POSIX drops
  876. the shared lock when the caller closes ``fd``; Windows gives it straight back."""
  877. if sys.platform == "win32":
  878. # msvcrt has no shared mode: LockFileEx without LOCKFILE_EXCLUSIVE_LOCK over the owner byte
  879. # and the 16 lease bytes. Any LockFileEx failure answers held, as the exclusive probe did;
  880. # an OSError (get_osfhandle on a bad fd) reaches checkout_lock_held, which answers free.
  881. import ctypes
  882. import msvcrt
  883. from ctypes import wintypes
  884. kernel32, overlapped = _windows_lockfile_api()
  885. handle = wintypes.HANDLE(msvcrt.get_osfhandle(fd))
  886. span = 1 + _LEASE_SLOTS
  887. if not kernel32.LockFileEx(handle, _LOCKFILE_FAIL_IMMEDIATELY, 0, span, 0,
  888. ctypes.byref(overlapped(Offset=_WINDOWS_LOCK_OFFSET))):
  889. return False
  890. # The result is ignored: the caller closes fd next, which normally releases the lock too.
  891. kernel32.UnlockFileEx(handle, 0, span, 0, ctypes.byref(overlapped(Offset=_WINDOWS_LOCK_OFFSET)))
  892. return True
  893. import fcntl
  894. try:
  895. fcntl.flock(fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
  896. except BlockingIOError:
  897. return False
  898. return True
  899. def _lock_bytes(fd: int, offset: int, count: int = 1) -> bool:
  900. """Windows: lock ``count`` bytes at ``offset`` without waiting (fails if any is held)."""
  901. import msvcrt
  902. os.lseek(fd, offset, os.SEEK_SET)
  903. try:
  904. msvcrt.locking(fd, msvcrt.LK_NBLCK, count)
  905. except OSError:
  906. return False
  907. return True
  908. def _unlock(fd: int, offset: int = _WINDOWS_LOCK_OFFSET, count: int = 1) -> None:
  909. if sys.platform == "win32":
  910. import msvcrt
  911. with suppress(OSError):
  912. os.lseek(fd, offset, os.SEEK_SET)
  913. msvcrt.locking(fd, msvcrt.LK_UNLCK, count)
  914. def _take_lease(fd: int) -> int | None:
  915. """Windows: lock a free lease byte (R5b) on ``fd``; its offset, or None when all are held
  916. (the tree's other joiners hold them: this one still runs inside their custody)."""
  917. for offset in range(_WINDOWS_LOCK_OFFSET + 1, _WINDOWS_LOCK_OFFSET + 1 + _LEASE_SLOTS):
  918. if _lock_bytes(fd, offset):
  919. return offset
  920. return None
  921. def _inherited_lock_fd(path: Path) -> int | None:
  922. """An fd this process inherited that holds the lock on ``path`` (POSIX ``pass_fds``)."""
  923. if sys.platform == "win32":
  924. return None
  925. try:
  926. target = os.stat(path)
  927. fd_dir = "/proc/self/fd" if os.path.isdir("/proc/self/fd") else "/dev/fd"
  928. candidates = [int(name) for name in os.listdir(fd_dir) if name.isdigit()]
  929. except OSError:
  930. return None
  931. import fcntl
  932. for fd in candidates:
  933. try:
  934. # pass_fds clears CLOEXEC in the exec'd child. Local opens (including the
  935. # concurrent status probe) retain it and must never donate their lifetime:
  936. # their owner may close the fd while our update still holds custody.
  937. if not os.get_inheritable(fd):
  938. continue
  939. st = os.fstat(fd)
  940. if (st.st_dev, st.st_ino) != (target.st_dev, target.st_ino):
  941. continue
  942. # Succeeds only when this open file description already holds the lock (or the
  943. # lock is free, in which case taking it on an fd we hold is still correct).
  944. fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
  945. return fd
  946. except OSError:
  947. continue
  948. return None
  949. def _lock_holder(fd_or_path) -> UpdateHolder:
  950. """Who holds the checkout lock, from its holder record. A recorded updater that is gone (its
  951. incarnation is dead) while the lock stays held means a process it started holds it: that is
  952. the ``held`` holder, never the dead pid (the marker reader's wording, R6)."""
  953. raw = _read_bytes(fd_or_path) or b""
  954. parsed = _parse_marker(raw)
  955. age = parsed.age() if parsed.started_at else 0.0
  956. if parsed.pid > 0 and incarnation_live(parsed.pid, parsed.create_time) is False:
  957. return UpdateHolder(pid=0, age_seconds=age, held=True)
  958. return UpdateHolder(pid=max(parsed.pid, 0), age_seconds=age)
  959. def _open_lock_file(path: Path) -> tuple[int | None, object]:
  960. """``(fd, True)`` read-write; ``(fd, False)`` read-only for an existing lock file we may not
  961. write (left root-owned by a ``sudo hermes update``: the kernel lock works on a read-only fd,
  962. contract A5; POSIX only — a Windows owner needs its record); ``(None, reason)`` when neither opens."""
  963. # Never follow a link planted at the name: the holder record is written into this file.
  964. binary = getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
  965. try:
  966. return os.open(path, os.O_RDWR | os.O_CREAT | binary, 0o644), True
  967. except PermissionError as exc:
  968. denied = exc
  969. except OSError as exc:
  970. return None, exc.strerror or exc
  971. try:
  972. return os.open(path, os.O_RDONLY | binary), False
  973. except OSError:
  974. return None, denied.strerror or denied
  975. def _acquire_checkout(install_root: Path) -> UpdateHolder | None:
  976. """Take (or join, when inherited) the checkout lock; the refusal holder, else ``None``."""
  977. global _HELD
  978. path = checkout_lock_path(install_root)
  979. if _HELD is not None and _HELD["path"] == str(path):
  980. _HELD["depth"] += 1
  981. return None
  982. inherited = _inherited_lock_fd(path)
  983. if inherited is not None:
  984. _HELD = {"path": str(path), "fd": inherited, "owned": False, "depth": 1}
  985. return None
  986. fd, writable = _open_lock_file(path)
  987. if fd is None:
  988. return UpdateHolder(pid=0, age_seconds=0.0, reason=f"{path} is not writable ({writable}); the update "
  989. "locks the checkout there, in its git directory, which git must write too")
  990. found = os.fstat(fd)
  991. if not S_ISREG(found.st_mode) or found.st_nlink != 1:
  992. # A hard link (or special file) at the name: truncating it would rewrite data outside
  993. # the install. Refuse; never unlink/recreate it (waiters need one stable inode).
  994. os.close(fd)
  995. return UpdateHolder(pid=0, age_seconds=0.0, reason=f"{path} is not a regular single-link file; delete it")
  996. try:
  997. if not _lock_with_contention_wait(fd, path):
  998. if _held_by_our_windows_ancestor(path):
  999. # Windows has no fd inheritance: the update tree's children run in the lock
  1000. # owner's kill-on-close job (bind_child_to_update_tree) and die with it. One the
  1001. # job refused does not, so every joiner also holds a lease byte (R5b), taken
  1002. # while the owner is seen alive: it never covers a writer after a free lock.
  1003. lease = _take_lease(fd)
  1004. if _held_by_our_windows_ancestor(path):
  1005. _HELD = {"path": str(path), "fd": None, "owned": False, "depth": 1,
  1006. "lease": None if lease is None else (fd, lease)}
  1007. if lease is None:
  1008. os.close(fd)
  1009. return None
  1010. if lease is not None:
  1011. _unlock(fd, lease)
  1012. os.close(fd)
  1013. return _lock_holder(path)
  1014. if writable is not True and sys.platform == "win32":
  1015. # No fd inheritance on Windows: the update tree's children find their owner by
  1016. # this record (_held_by_our_windows_ancestor), so an owner that cannot write it
  1017. # would admit itself and then have its own children refused.
  1018. _unlock(fd)
  1019. os.close(fd)
  1020. return UpdateHolder(pid=0, age_seconds=0.0,
  1021. reason=f"{path} is read-only; delete it or fix its permissions")
  1022. if writable is True:
  1023. record = f"{os.getpid()}\n{int(time.time())}\n{_identity_line()}\n".encode()
  1024. os.lseek(fd, 0, os.SEEK_SET)
  1025. os.ftruncate(fd, 0)
  1026. os.write(fd, record)
  1027. except OSError as exc:
  1028. _unlock(fd)
  1029. os.close(fd)
  1030. return UpdateHolder(pid=0, age_seconds=0.0, reason=f"{path} could not be locked ({exc})")
  1031. _HELD = {"path": str(path), "fd": fd, "owned": True, "depth": 1}
  1032. return None
  1033. # A "held?" probe (marker.sh/marker.ps1 checkout_lock_held exclusively, Python checkout_lock_held
  1034. # shared, which still blocks an exclusive take) holds the lock for microseconds: an updater that
  1035. # collides with one waits this long before "busy" (D17: 257 of 3283 tight-loop acquires failed
  1036. # spuriously with no real holder).
  1037. CHECKOUT_CONTENTION_WAIT_SECONDS = 3.0
  1038. def _lock_with_contention_wait(fd: int, path: Path) -> bool:
  1039. if _try_lock(fd):
  1040. return True
  1041. if _held_by_our_windows_ancestor(path):
  1042. return False # our own update tree holds it and never frees it for us: answer at once
  1043. deadline = time.monotonic() + CHECKOUT_CONTENTION_WAIT_SECONDS
  1044. while time.monotonic() < deadline:
  1045. time.sleep(0.02)
  1046. if _try_lock(fd):
  1047. return True
  1048. return False
  1049. def _held_by_our_windows_ancestor(path: Path) -> bool:
  1050. """Windows: the checkout lock's holder record names a LIVE incarnation of one of our
  1051. ancestors (the ``hermes update`` whose completion/build children we are)."""
  1052. if sys.platform != "win32":
  1053. return False
  1054. record = _parse_marker(_read_bytes(path) or b"")
  1055. if record.started_at is None or record.pid == os.getpid():
  1056. return False
  1057. return incarnation_live(record.pid, record.create_time) is True and _is_ancestor_pid(record.pid)
  1058. def _release_checkout() -> None:
  1059. global _HELD
  1060. if _HELD is None:
  1061. return
  1062. _HELD["depth"] -= 1
  1063. if _HELD["depth"] > 0:
  1064. return
  1065. held, _HELD = _HELD, None
  1066. if held.get("lease"):
  1067. lease_fd, offset = held["lease"]
  1068. _unlock(lease_fd, offset)
  1069. with suppress(OSError):
  1070. os.close(lease_fd)
  1071. if held["owned"]:
  1072. # Close, never LOCK_UN: flock belongs to the open file description, which completion
  1073. # children share through pass_fds. A survivor keeps the checkout locked until it exits.
  1074. _unlock(held["fd"])
  1075. with suppress(OSError):
  1076. os.close(held["fd"])
  1077. def checkout_lock_fds(install_root: Path | str | None = None) -> tuple[int, ...]:
  1078. """Fds a child of the update tree must inherit (``subprocess`` ``pass_fds``) so the
  1079. checkout stays locked while it runs, even after its parent is killed. POSIX only."""
  1080. if sys.platform == "win32":
  1081. return ()
  1082. if _HELD is not None:
  1083. return () if _HELD["fd"] is None else (_HELD["fd"],)
  1084. fd = _inherited_lock_fd(checkout_lock_path(install_root))
  1085. return () if fd is None else (fd,)
  1086. def custody_spawn_kwargs() -> dict:
  1087. """``subprocess`` kwargs that keep a checkout MUTATOR (git, the Node source build) in the
  1088. update tree's custody (R2): POSIX children inherit the held lock fd, so the checkout stays
  1089. locked until the last of them exits even if this process is killed. ``{}`` when this process
  1090. holds no checkout lock, and on Windows (bind the Popen with bind_child_to_update_tree)."""
  1091. if sys.platform == "win32" or _HELD is None or _HELD["fd"] is None:
  1092. return {}
  1093. return {"pass_fds": (_HELD["fd"],)}
  1094. CREATE_SUSPENDED = 0x00000004
  1095. def bind_child_to_update_tree(proc: subprocess.Popen) -> OSError | None:
  1096. """Windows: put an update-tree child in a kill-on-close job owned by this process, so the
  1097. child (and everything it spawns) dies when the lock owner dies and frees the lock.
  1098. Create ``proc`` with :data:`CREATE_SUSPENDED` and resume it after the bind
  1099. (:func:`resume_suspended_child`): it runs no instruction before, so nothing it starts can
  1100. escape the job. The job allows breakaway: a process the tree starts
  1101. with ``CREATE_BREAKAWAY_FROM_JOB`` (the gateways an update restarts or resumes,
  1102. ``gateway_windows._spawn_detached``) leaves it and outlives the update; every other
  1103. descendant stays bound. Not ``SILENT_BREAKAWAY_OK``, which would let every descendant escape.
  1104. POSIX children inherit the lock fd instead (:func:`checkout_lock_fds`). Returns ``None`` when
  1105. bound, else the refusal (logged): the caller runs post-commit work, which must not fail over
  1106. a weaker lock, so it records the refusal and runs the child, which joins the lock holding its
  1107. own lease byte (R5b): the checkout stays busy until it exits, even after the owner's death.
  1108. """
  1109. if sys.platform != "win32":
  1110. return None
  1111. try:
  1112. _bind_to_kill_on_close_job(proc)
  1113. except OSError as exc:
  1114. logger.warning("Could not bind update child %s to the update's job: %s", proc.pid, exc)
  1115. return exc
  1116. return None
  1117. def resume_suspended_child(proc: subprocess.Popen) -> None:
  1118. """Windows: resume a :data:`CREATE_SUSPENDED` child (a no-op for a running one). A failed
  1119. resume kills it and raises ``OSError``."""
  1120. import ctypes
  1121. ntdll = ctypes.WinDLL("ntdll")
  1122. ntdll.NtResumeProcess.argtypes = [ctypes.c_void_p]
  1123. ntdll.NtResumeProcess.restype = ctypes.c_long
  1124. if ntdll.NtResumeProcess(int(proc._handle)) != 0:
  1125. proc.kill()
  1126. raise OSError(f"could not resume update child {proc.pid}")
  1127. def _bind_to_kill_on_close_job(proc: subprocess.Popen) -> None:
  1128. import ctypes
  1129. from ctypes import wintypes
  1130. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  1131. kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
  1132. kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
  1133. if not kernel32.AssignProcessToJobObject(update_tree_job(), int(proc._handle)):
  1134. raise ctypes.WinError(ctypes.get_last_error())
  1135. def update_tree_job() -> int:
  1136. """Windows: this process's kill-on-close job for the update tree (created once, never
  1137. closed: the handle closes when this process dies, killing every process still in it)."""
  1138. if _JOBS:
  1139. return _JOBS[0]
  1140. import ctypes
  1141. from ctypes import wintypes
  1142. class _Basic(ctypes.Structure):
  1143. _fields_ = [("PerProcessUserTimeLimit", ctypes.c_int64), ("PerJobUserTimeLimit", ctypes.c_int64),
  1144. ("LimitFlags", wintypes.DWORD), ("MinimumWorkingSetSize", ctypes.c_size_t),
  1145. ("MaximumWorkingSetSize", ctypes.c_size_t), ("ActiveProcessLimit", wintypes.DWORD),
  1146. ("Affinity", ctypes.c_size_t), ("PriorityClass", wintypes.DWORD),
  1147. ("SchedulingClass", wintypes.DWORD)]
  1148. class _Extended(ctypes.Structure):
  1149. _fields_ = [("BasicLimitInformation", _Basic), ("IoInfo", ctypes.c_ulonglong * 6),
  1150. ("ProcessMemoryLimit", ctypes.c_size_t), ("JobMemoryLimit", ctypes.c_size_t),
  1151. ("PeakProcessMemoryUsed", ctypes.c_size_t), ("PeakJobMemoryUsed", ctypes.c_size_t)]
  1152. kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
  1153. kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
  1154. kernel32.CreateJobObjectW.restype = wintypes.HANDLE
  1155. kernel32.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD]
  1156. kernel32.SetInformationJobObject.restype = wintypes.BOOL
  1157. kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
  1158. job = kernel32.CreateJobObjectW(None, None) # unnamed, non-inheritable: only we hold it
  1159. if not job:
  1160. raise ctypes.WinError(ctypes.get_last_error())
  1161. limits = _Extended()
  1162. # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE | JOB_OBJECT_LIMIT_BREAKAWAY_OK
  1163. limits.BasicLimitInformation.LimitFlags = 0x2000 | 0x0800
  1164. if not kernel32.SetInformationJobObject(job, 9, ctypes.byref(limits), ctypes.sizeof(limits)):
  1165. error = ctypes.get_last_error()
  1166. kernel32.CloseHandle(job)
  1167. raise ctypes.WinError(error)
  1168. _JOBS.append(job) # never closed: the handle closes when this process dies, killing the tree
  1169. return job
  1170. def holds_checkout_lock(install_root: Path | str | None = None) -> bool:
  1171. """True when this process holds (or joined) the checkout lock: it IS the running update."""
  1172. return _HELD is not None and os.path.realpath(_HELD["path"]) == os.path.realpath(checkout_lock_path(install_root))
  1173. def update_in_progress(install_root: Path | str | None = None) -> bool:
  1174. """True while an update owns this install: a LIVE marker or a held checkout lock."""
  1175. return read_live_update(install_root=install_root) is not None or checkout_lock_held(install_root)
  1176. def checkout_lock_held(install_root: Path | str | None = None) -> bool:
  1177. """True while some process (this one included) holds the checkout kernel lock.
  1178. A probe takes a SHARED lock on the owner byte and every lease byte for the microseconds of one
  1179. try and drops it (closing the fd). Holders lock exclusively, so the probe fails only on a real
  1180. holder, while two Python probes never read each other as one (``marker.sh`` / ``marker.ps1``
  1181. still probe exclusively): a client polling ``ensure`` and the gateway it just started both
  1182. probe while a killed update's dead marker is still there. An
  1183. updater acquiring at that instant waits :data:`CHECKOUT_CONTENTION_WAIT_SECONDS` instead of
  1184. failing (R6/D17).
  1185. Only a missing lock file is free. One that exists but cannot be opened answers held, the same
  1186. verdict ``marker.sh`` / ``marker.ps1`` and the Desktop probes give, so no reader admits a
  1187. launch the others would park. A POSIX lock call that fails outright (ENOLCK on NFS without
  1188. lockd, EOPNOTSUPP on some SMB shares) means nothing can hold it: free, so the interrupted-pull
  1189. repair runs unguarded there as designed. On Windows any ``LockFileEx`` failure answers held;
  1190. only a descriptor with no OS handle answers free."""
  1191. if holds_checkout_lock(install_root):
  1192. return True
  1193. path = checkout_lock_path(install_root)
  1194. try:
  1195. fd = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0))
  1196. except FileNotFoundError:
  1197. return False
  1198. except OSError:
  1199. return True
  1200. try:
  1201. return not _try_shared_lock(fd)
  1202. except OSError:
  1203. return False
  1204. finally:
  1205. os.close(fd)
  1206. # --- the lock object ---------------------------------------------------------------------
  1207. def _publish_exclusive(path: Path, body: bytes) -> bool:
  1208. """Contract A3: publish ``body`` at ``path`` only if nothing is there, never as an empty
  1209. file a reader could judge dead. Write a private tmp sibling, then hard-link it into place
  1210. (fails if the marker exists); a filesystem without hard links falls back to an exclusive
  1211. create (readers grant a young empty marker EMPTY_MARKER_GRACE_SECONDS). False = taken."""
  1212. tmp = _tmp_sibling(path)
  1213. try:
  1214. with open(tmp, "xb") as fh:
  1215. fh.write(body)
  1216. fh.flush()
  1217. os.fsync(fh.fileno())
  1218. try:
  1219. os.link(tmp, path)
  1220. return True
  1221. except FileExistsError:
  1222. return False
  1223. except OSError as exc:
  1224. logger.debug("No hard link for the update marker (%s); exclusive create instead", exc)
  1225. finally:
  1226. with suppress(OSError):
  1227. tmp.unlink()
  1228. try:
  1229. fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o644)
  1230. except FileExistsError:
  1231. return False
  1232. made = os.fstat(fd)
  1233. try:
  1234. if os.write(fd, body) != len(body):
  1235. raise OSError(errno.ENOSPC, f"short write publishing {path}")
  1236. os.fsync(fd)
  1237. except BaseException:
  1238. # A torn claim names our live pid, so it would block every updater for as long as we
  1239. # run without our ever having acquired: withdraw the inode WE created — compared under
  1240. # the marker mutex, so a claimant that reclaimed it and published its own keeps that.
  1241. os.close(fd)
  1242. with suppress(OSError), marker_mutex(path):
  1243. now = os.stat(path)
  1244. if (now.st_dev, now.st_ino) == (made.st_dev, made.st_ino):
  1245. path.unlink()
  1246. raise
  1247. os.close(fd)
  1248. return True
  1249. def _marker_unwritable(path: Path, exc: OSError) -> str:
  1250. """Why an unwritable marker location refuses the update, not just that it is unwritable."""
  1251. return (f"{path} is not writable ({exc}); the update records itself there so the Desktop app, "
  1252. "gateways, installers and other updaters wait for it")
  1253. # Per-process claim depth for each marker path: nested UpdateLocks (an update's completion run
  1254. # in-process, venv_sync finishing a tail) share one claim, released by the outermost.
  1255. _CLAIMS: dict[str, int] = {}
  1256. class UpdateLock:
  1257. """Context manager owning the shared update marker (and, with ``install_root``, the
  1258. checkout lock) for this process.
  1259. ``acquired`` is True when we wrote the marker; adopting a live partner's claim (hand-off
  1260. pid, ancestor, or an outer claim of this same process) succeeds with ``acquired`` False.
  1261. ``acquire`` returns False (and sets ``holder``) when another live update owns either lock
  1262. or the lock cannot be created at all — never "proceed unlocked".
  1263. ``install_root`` names the checkout whose kernel lock guards the claim (default: this
  1264. checkout). With ``checkout_first`` (the default, when ``install_root`` is given) ``acquire``
  1265. takes that lock before the marker. ``checkout_first=False`` claims the marker alone — a
  1266. launch that may run under a live update's claim (venv_sync) and takes the checkout lock later,
  1267. only for its own mutation. Either way a dead marker over a checkout lock held by another
  1268. process tree is refused as ``held`` and kept, never reclaimed (R6).
  1269. """
  1270. def __init__(self, *, path: Path | None = None, install_root: Path | str | None = None,
  1271. checkout_first: bool = True) -> None:
  1272. self.path = path or update_marker_path()
  1273. self.install_root = None if install_root is None else Path(install_root)
  1274. self.checkout_first = checkout_first
  1275. self.acquired = False
  1276. self.holder: UpdateHolder | None = None
  1277. self._claimed = False
  1278. self._checkout = False
  1279. def acquire(self) -> bool:
  1280. if self.install_root is not None and self.checkout_first \
  1281. and not self.acquire_checkout(self.install_root):
  1282. return False
  1283. try:
  1284. ok = self._claim_marker()
  1285. except BaseException:
  1286. self._drop_checkout()
  1287. raise
  1288. if not ok:
  1289. self._drop_checkout()
  1290. return False
  1291. key = str(self.path)
  1292. _CLAIMS[key] = _CLAIMS.get(key, 0) + 1
  1293. self._claimed = True
  1294. return True
  1295. def acquire_checkout(self, install_root: Path | str) -> bool:
  1296. """Take (or join) the checkout lock — ACQUIRE custody, never sample it (R2): a caller
  1297. that will mutate the checkout under a marker it adopted or claimed calls this first."""
  1298. if self._checkout:
  1299. return True
  1300. refused = _acquire_checkout(Path(install_root))
  1301. if refused is not None:
  1302. self.holder = refused
  1303. return False
  1304. self._checkout = True
  1305. return True
  1306. def _claim_marker(self) -> bool:
  1307. try:
  1308. self.path.parent.mkdir(parents=True, exist_ok=True)
  1309. except OSError as exc:
  1310. self.holder = UpdateHolder(pid=0, age_seconds=0.0, reason=_marker_unwritable(self.path.parent, exc))
  1311. return False
  1312. _sweep_dead_tmp_siblings(self.path)
  1313. if _CLAIMS.get(str(self.path)) is None:
  1314. legacy = [claim for claim in legacy_profile_claims(self.path.parent)
  1315. if not self._is_partner(claim.pid)]
  1316. if legacy:
  1317. self.holder = legacy[0]
  1318. return False
  1319. body = f"{os.getpid()}\n{int(time.time())}\n{_identity_line()}\n".encode()
  1320. try:
  1321. for _attempt in range(3):
  1322. # A7 rule 2: an exclusive create needs no mutex — it only succeeds on no marker.
  1323. if _publish_exclusive(self.path, body):
  1324. self.acquired = True
  1325. return True
  1326. with marker_mutex(self.path):
  1327. existing = _read_marker(self.path)
  1328. if existing is None:
  1329. continue # vanished between publish and read: retry
  1330. if _live_partners(existing):
  1331. return self._adopt_or_refuse(existing)
  1332. if self._checkout_held_elsewhere():
  1333. # R6: the marker's owner is dead but a process it started (completion,
  1334. # build, git) still holds the checkout. The update is not over: keep
  1335. # its marker and refuse as ``held``.
  1336. self.holder = UpdateHolder(
  1337. pid=0, held=True,
  1338. age_seconds=max(existing.age(), 0.0) if existing.started_at is not None else 0.0)
  1339. return False
  1340. # Dead or malformed, judged under the mutex: reclaim and claim in one hold.
  1341. with suppress(FileNotFoundError):
  1342. self.path.unlink()
  1343. if _publish_exclusive(self.path, body):
  1344. self.acquired = True
  1345. return True
  1346. except MarkerBusy:
  1347. self.holder = UpdateHolder(pid=0, age_seconds=0.0)
  1348. return False
  1349. except OSError as exc:
  1350. self.holder = UpdateHolder(pid=0, age_seconds=0.0, reason=_marker_unwritable(self.path, exc))
  1351. return False
  1352. self.holder = read_live_update(path=self.path, install_root=self.install_root) \
  1353. or UpdateHolder(pid=0, age_seconds=0.0)
  1354. return False
  1355. def _checkout_held_elsewhere(self) -> bool:
  1356. """The checkout lock is held, and not by this process's own update tree (our hold, or
  1357. a lock fd inherited from the update that spawned us — that tree may reclaim)."""
  1358. if self._checkout:
  1359. return False
  1360. path = checkout_lock_path(self.install_root)
  1361. if _HELD is not None and _HELD["path"] == str(path):
  1362. return False
  1363. # Only when held: a free lock is not taken by the inherited-fd lookup below.
  1364. return checkout_lock_held(self.install_root) and _inherited_lock_fd(path) is None
  1365. @staticmethod
  1366. def _is_partner(pid: int) -> bool:
  1367. return pid == os.getpid() or (pid and (pid == _handoff_pid() or _is_ancestor_pid(pid)))
  1368. def _adopt_or_refuse(self, existing: _Marker) -> bool:
  1369. """C1 rule 4: a LIVE claim by us, an ancestor or the hand-off partner is run under.
  1370. Called inside the marker mutex."""
  1371. partners = _live_partners(existing)
  1372. if not any(self._is_partner(p) and (p == os.getpid() or not _runtime_host_below(p)) for p in partners):
  1373. self.holder = UpdateHolder(pid=partners[0], age_seconds=existing.age() if existing.started_at else 0.0)
  1374. return False
  1375. own = _identity_line()
  1376. if os.getpid() not in partners and existing.delegate_pid not in partners \
  1377. and existing.create_time is not None and own:
  1378. # Rule 6: name ourselves as the delegate (line 4) so the claim stays visible if the
  1379. # partner (a hand-off script, the Tauri updater) dies while this update still runs.
  1380. base = existing.base if existing.base.endswith(b"\n") else existing.base + b"\n"
  1381. delegated = base + f"delegate:{os.getpid()} {own}\n".encode() \
  1382. + "".join(f"run:{run}\n" for run in existing.runs).encode()
  1383. _compare_and_swap(self.path, existing.raw, delegated)
  1384. return True
  1385. def _drop_checkout(self) -> None:
  1386. if self._checkout:
  1387. self._checkout = False
  1388. _release_checkout()
  1389. def release(self) -> None:
  1390. """Give back our part of the claim (A7 rule 5), decided under the marker mutex by
  1391. identity, not by the bytes we once wrote: whatever names this incarnation — as owner, or
  1392. as a delegate someone else wrote in (the hand-off script names its child) — is released;
  1393. a live delegate inherits an owner's claim. Only the outermost claim of a process
  1394. releases. Never raises."""
  1395. try:
  1396. if self._claimed:
  1397. key = str(self.path)
  1398. _CLAIMS[key] = _CLAIMS.get(key, 1) - 1
  1399. if _CLAIMS[key] <= 0:
  1400. _CLAIMS.pop(key, None)
  1401. _release_marker(self.path)
  1402. except OSError as exc:
  1403. logger.debug("Could not release update marker %s: %s", self.path, exc)
  1404. finally:
  1405. self.acquired = self._claimed = False
  1406. self._drop_checkout()
  1407. def __enter__(self) -> UpdateLock:
  1408. self.acquire()
  1409. return self
  1410. def __exit__(self, *_exc) -> None:
  1411. self.release()
  1412. def _release_marker(path: Path) -> None:
  1413. with marker_mutex(path):
  1414. raw = _read_bytes(path)
  1415. if raw is None:
  1416. return
  1417. action, new = _release_decision(raw)
  1418. if action == "delete":
  1419. with suppress(FileNotFoundError):
  1420. path.unlink()
  1421. elif action == "rewrite":
  1422. _compare_and_swap(path, raw, new)