| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289 |
- """Settles a ZIP ``hermes update`` swap whose owner died: its journal, owner lock and recovery.
- Split out of ``_early_recovery`` (stdlib-only, like it). ``_early_recovery.restore_interrupted_pull``
- imports this only when the journal exists, so the git-marker repair and its published closure
- (``RECOVERY_CLOSURE``) never need it.
- """
- from __future__ import annotations
- import contextlib
- import os
- import re
- import stat
- import sys
- import time
- from pathlib import Path
- from hermes_cli._early_recovery import (
- _CLAIM_HELD_ERRNOS, ZIP_SWAP_JOURNAL, _keep_aside, _lock_fd, _project_root, _pytest_owns_live_checkout,
- write_durable_text)
- # A journal in the install root naming every entry the swap stages/renames and whether it existed
- # before, plus an OS lock its owner holds for the whole stage+swap (the kernel drops it with the
- # owner: liveness without pids or ages).
- _ZIP_STAGING_SUFFIX, _ZIP_OLD_SUFFIX = ".hermes-update-staging", ".hermes-update-old"
- class ZipSwapLock:
- """``zip_swap_owner_lock``'s verdict: truthy only while this process holds the kernel lock.
- ``reason`` names a refusal: ``busy`` (a live owner holds it) or why no lock could be taken at all.
- """
- __slots__ = ("owned", "reason")
- def __init__(self, owned: bool, reason: str = "") -> None:
- self.owned, self.reason = owned, reason
- def __bool__(self) -> bool:
- return self.owned
- @contextlib.contextmanager
- def zip_swap_owner_lock(root: Path, *, wait: float = 0.0):
- """Yields a truthy ``ZipSwapLock`` while this process owns the ZIP swap lock, a falsy one otherwise.
- The lock file is a stable sidecar: never unlinked, so every process locks the same inode (an
- unlink lets a waiter keep the old inode while a newcomer locks a fresh one). No lock, no admission:
- a root where the file cannot be opened or locked refuses with the reason (fail closed)."""
- lock_path = Path(root) / (ZIP_SWAP_JOURNAL + ".lock")
- try:
- fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
- except OSError as exc:
- yield ZipSwapLock(False, f"cannot open the ZIP swap lock {lock_path}: {exc.strerror or exc}")
- return
- try:
- deadline = time.monotonic() + wait
- while True:
- try:
- if sys.platform == "win32":
- import msvcrt
- os.lseek(fd, 0, os.SEEK_SET)
- msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
- else:
- import fcntl
- fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
- break
- except OSError as exc:
- if exc.errno not in _CLAIM_HELD_ERRNOS:
- yield ZipSwapLock(False, f"cannot lock the ZIP swap lock {lock_path}: {exc.strerror or exc}")
- return
- if time.monotonic() >= deadline:
- yield ZipSwapLock(False, "busy")
- return
- time.sleep(0.05)
- try:
- yield ZipSwapLock(True)
- finally:
- _lock_fd(fd, False)
- finally:
- os.close(fd)
- def write_zip_swap_journal(root: Path, phase: str, entries: list, gen: str, temps: dict | None = None) -> None:
- """Publish the swap journal: ``entries`` are ``[name, existed, staged_id, live_id]`` (ids from
- ``zip_entry_identity``, "" while unknown); ``gen`` is the run's random tag (its backup temps);
- ``temps`` maps each backup temp the swap created (its file name) to its ``filling`` identity."""
- import json
- write_durable_text(Path(root) / ZIP_SWAP_JOURNAL, json.dumps(
- {"pid": os.getpid(), "gen": gen, "phase": phase, "entries": entries, "temps": temps or {}}))
- def zip_entry_identity(path, *, filling: bool = False) -> str:
- """The entry's own identity (lstat, never its target); "" when absent or unidentifiable.
- The ZIP journal's provenance: recovery deletes only an entry whose identity it recorded when the
- swap made it (a staging copy, or the live entry its backup links/renames), never a lookalike. A
- non-directory adds size and mtime: a file deleted and recreated often gets the same inode back.
- A directory, or a file still being written (``filling``), is ``dev:ino:type`` only: its own size
- and mtime move while it is being filled."""
- try:
- st = os.lstat(path)
- except OSError:
- return ""
- if not st.st_ino:
- return ""
- base = f"{st.st_dev}:{st.st_ino}:{stat.S_IFMT(st.st_mode):o}"
- return base if filling or stat.S_ISDIR(st.st_mode) else f"{base}:{st.st_size}:{st.st_mtime_ns}"
- def _drop_path(path: Path) -> None:
- if path.is_dir() and not path.is_symlink():
- import shutil
- try:
- shutil.rmtree(path)
- except OSError:
- # A staged copy keeps its source's modes: a read-only directory refuses to give up its
- # entries. These trees are the update's own copies, so make their directories writable and
- # retry. Files keep their modes: a grafted artifact is a hardlink to the LIVE file, and POSIX
- # deletion needs only the parent's write bit. Windows refuses to delete a read-only file, so
- # there only a file no other link shares has its read-only bit cleared.
- rwx = stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR
- os.chmod(path, os.stat(path).st_mode | rwx)
- for dirpath, dirnames, files in os.walk(path):
- for name in dirnames:
- child = os.path.join(dirpath, name)
- if not os.path.islink(child):
- os.chmod(child, os.stat(child).st_mode | rwx)
- for name in files if sys.platform == "win32" else ():
- child = os.path.join(dirpath, name)
- st = os.lstat(child)
- if st.st_nlink == 1 and not stat.S_ISLNK(st.st_mode):
- os.chmod(child, st.st_mode | stat.S_IWUSR)
- shutil.rmtree(path)
- elif path.exists() or path.is_symlink():
- path.unlink()
- def _parse_zip_swap_journal(raw: str) -> tuple[str, str, list[tuple[str, bool, str, str]], dict[str, str]] | None:
- """``(phase, gen, [(entry name, existed, staged_id, live_id)], temps)`` from a journal this code wrote,
- else None. A journal without ``temps`` (an older writer's) vouches for no backup temp."""
- import json
- try:
- data = json.loads(raw)
- except ValueError:
- return None
- if not isinstance(data, dict) or data.get("phase") not in ("staging", "swapping", "committed"):
- return None
- entries, gen = data.get("entries"), data.get("gen")
- if not isinstance(entries, list) or not isinstance(gen, str) or not re.fullmatch(r"[0-9a-f]{12}", gen):
- return None
- if not all(isinstance(e, list) and len(e) == 4 and all(isinstance(v, str) for v in (e[0], e[2], e[3]))
- and isinstance(e[1], bool) and e[0] not in ("", ".", "..") and "/" not in e[0] and "\\" not in e[0]
- for e in entries):
- return None
- temps = data.get("temps", {})
- if not isinstance(temps, dict) or not all(isinstance(v, str) for v in temps.values()):
- return None
- return data["phase"], gen, [(name, existed, staged, live) for name, existed, staged, live in entries], temps
- def _discard_unless_owned(path: Path, identity: str, kept: list[Path]) -> None:
- """Delete ``path`` only when it is provably the entry the swap recorded; anything else (a later
- user file at the suffix, a foreign journal's victim) is renamed aside, never deleted (review Z1)."""
- if not os.path.lexists(path):
- return
- if identity and zip_entry_identity(path) == identity:
- _drop_path(path)
- else:
- kept.append(_keep_aside(path))
- def _settle_zip_entry(root: Path, phase: str, gen: str, entry: tuple[str, bool, str, str], temps: dict[str, str],
- kept: list[Path]) -> bool:
- """Finish or roll back one journaled entry; True when the live tree changed.
- Presence is the ENTRY's (lexists/lstat), never its target's: a dangling symlink backup is the only
- copy of a tracked symlink, not "no backup" (review Z3). Restoring a backup never deletes bytes, so
- it needs no provenance; every deletion does (``_discard_unless_owned``)."""
- name, existed, staged_id, live_id = entry
- here = os.path.lexists
- dst = root / name
- staging, old = Path(f"{dst}{_ZIP_STAGING_SUFFIX}"), Path(f"{dst}{_ZIP_OLD_SUFFIX}")
- changed = False
- if phase == "swapping":
- # Staging finished before this phase, so a backup now is the one the swap made from the old
- # entry: it existed, whatever an older journal recorded.
- existed = existed or here(old)
- if existed and here(old) and not (live_id and zip_entry_identity(dst) == live_id):
- if (old.is_file() and not old.is_symlink() and staged_id and zip_entry_identity(dst) == staged_id
- and not dst.is_dir()):
- os.replace(old, dst) # a file entry never goes missing, not even here
- else:
- _discard_unless_owned(dst, staged_id, kept)
- os.rename(old, dst) # moves a symlink itself, never its target
- changed = True
- elif not existed and here(dst) and not here(staging):
- _discard_unless_owned(dst, staged_id, kept)
- changed = True
- elif existed and not here(dst) and here(old):
- os.rename(old, dst) # the backup is the only copy left
- changed = True
- for leftover, identity in ((staging, staged_id), (old, live_id)):
- _discard_unless_owned(leftover, identity, kept)
- # ``<old>.<gen>.tmp``: a backup copy of the live file killed before its rename (no-hardlink file
- # systems). Neither the tag nor the bytes prove a file there is that copy (F78/F78-R): only the
- # identity the swap journaled the moment it created the temp does. A file system that hands a
- # recreated name its old inode (FAT, where this copy runs) would let that record vouch for a
- # later file too, so the bytes must also be what a killed copy is: a prefix of the live file.
- tmp = Path(f"{old}.{gen}.tmp")
- if _is_killed_backup_copy(tmp, dst, temps.get(tmp.name, "")):
- _drop_path(tmp)
- elif here(tmp):
- kept.append(_keep_aside(tmp))
- return changed
- def _is_killed_backup_copy(tmp: Path, dst: Path, identity: str) -> bool:
- """The identity matches the regular file the swap recorded (type included), so the bytes are readable."""
- return (bool(identity) and zip_entry_identity(tmp, filling=True) == identity
- and dst.is_file() and not dst.is_symlink() and dst.read_bytes().startswith(tmp.read_bytes()))
- def restore_interrupted_zip_swap(project_root: Path | None = None) -> bool:
- """Finish or roll back a ZIP swap whose owner died; True when the tree changed (relaunch).
- ``committed``: every rename landed, only backups remain -> drop them (finish). ``swapping``: put
- each moved-aside entry back and remove entries the swap added (roll back to the old tree, which
- the venv was built for; ``hermes update`` redoes it). ``staging``: nothing live moved -> drop the
- staging copies. Either way no ``*.hermes-update-staging``/``-old`` sibling is left to wedge the
- next run's free-space or dirty-tree checks. A live owner (lock held) is never second-guessed.
- Provenance (review Z1): a sibling or entry is deleted only when its identity is the one the journal
- recorded; anything else is kept aside under a ``.hermes-update-kept`` name and reported.
- """
- root = _project_root() if project_root is None else Path(project_root)
- journal = root / ZIP_SWAP_JOURNAL
- if not journal.is_file() or _pytest_owns_live_checkout(root):
- return False
- with zip_swap_owner_lock(root) as owned:
- if not owned and owned.reason != "busy":
- print(f"⚠ An interrupted ZIP update cannot be settled: {owned.reason}.", file=sys.stderr)
- if not owned or not journal.is_file():
- return False
- try:
- raw = journal.read_text(encoding="utf-8-sig")
- except OSError as exc: # transient (AV, sharing violation): the journal is still the record
- print(f"⚠ Could not read the interrupted ZIP update's journal ({exc}); the next launch retries.",
- file=sys.stderr)
- return False
- parsed = _parse_zip_swap_journal(raw)
- if parsed is None:
- # Never guess which live entry to move, and never retire the only record of a mixed tree.
- print(f"⚠ The interrupted ZIP update's journal {journal} is unreadable or from another version; "
- "it and every `*.hermes-update-old` backup were kept. Put back what each backup replaced "
- "(or reinstall), then delete the journal.", file=sys.stderr)
- return False
- phase, gen, entries, temps = parsed
- changed = False
- failed = False
- kept: list[Path] = []
- for entry in reversed(entries):
- try:
- changed = _settle_zip_entry(root, phase, gen, entry, temps, kept) or changed
- except OSError as exc:
- failed = True
- print(f"⚠ Could not settle {entry[0]} after an interrupted ZIP update: {exc}", file=sys.stderr)
- if kept:
- print("⚠ An interrupted ZIP update's recovery found entries it could not prove were its own and "
- f"kept them aside instead of deleting them: {', '.join(map(str, kept))}. Delete each once "
- "you know it is not yours.", file=sys.stderr)
- # Retire the journal only on a verified terminal state, not an exception-free loop: no sibling
- # (staging copy, backup, backup temp) left that only this journal could still explain.
- siblings = (_ZIP_STAGING_SUFFIX, _ZIP_OLD_SUFFIX, f"{_ZIP_OLD_SUFFIX}.{gen}.tmp")
- unsettled = [e[0] for e in entries if any(os.path.lexists(f"{root / e[0]}{x}") for x in siblings)]
- if failed or unsettled:
- if unsettled and not failed:
- print(f"⚠ The interrupted ZIP update left {', '.join(unsettled)} unsettled; its journal "
- f"{journal} stays and the next launch retries.", file=sys.stderr)
- return changed # the journal stays: the next launch retries
- journal.unlink(missing_ok=True)
- if changed:
- print("⚠ A previous ZIP `hermes update` was interrupted mid-swap; the old install was put back. "
- "`hermes update` updates it again.", file=sys.stderr)
- return changed
|