uv_cache_health.py 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190
  1. """Find corrupt entries in PM's uv cache.
  2. uv unpacks every wheel into ``<cache>/.tmpXXXX`` and renames the directory
  3. into ``archive-v0/<id>``; it never flushes the file data first. When the
  4. machine stops mid-install (a hosted restart, a power cut), the rename can
  5. survive while the files read back as NUL bytes. uv then reuses that entry on
  6. every later sync and fails at install time with "The wheel is invalid", and
  7. retrying cannot help. These helpers recognise that failure and name the
  8. packages to purge. Deletion goes through ``uv cache clean`` (the caller),
  9. which takes uv's cache lock, so a concurrent sync never loses files mid-read;
  10. the leftover-archive sweep takes that same lock itself.
  11. Stdlib only: the bootstrap runner imports pm.environment on an older system
  12. python.
  13. """
  14. from __future__ import annotations
  15. import os
  16. from pathlib import Path
  17. import re
  18. import shutil
  19. from pm.filesystem import is_junction, lock_fd
  20. # uv's install step names the wheel it was linking from the cache:
  21. # error: Failed to install: lxml-6.1.3-cp314-...whl (lxml==6.1.3)
  22. _FAILED_INSTALL = re.compile(r"failed to install: ([^\s()]+?\.whl)\b", re.IGNORECASE)
  23. # Causes that mean the cached copy itself is unusable. A fetch, resolver or
  24. # disk-full failure never prints these, so it is never mistaken for corruption.
  25. _CORRUPT_CAUSES = (
  26. "the wheel is invalid", # WHEEL/METADATA unreadable, .dist-info missing
  27. "`record` file is invalid", # RECORD unreadable
  28. )
  29. # A cache pointer naming an archive whose files are gone ("No such file or
  30. # directory (os error 2)"; Windows also says "os error 3" for a missing dir).
  31. _MISSING_ARCHIVE = re.compile(r"archive-v0[\\/][^\s`'\"]+.*\(os error [23]\)", re.IGNORECASE)
  32. # PEP 508 project names only: these become `uv cache clean` arguments.
  33. _NAME = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?")
  34. _DIST_INFO = re.compile(r"(?P<name>.+?)-[^-]+\.dist-info")
  35. def normalize(name: str) -> str:
  36. """PEP 503 normal form, the spelling uv's cache uses."""
  37. return re.sub(r"[-_.]+", "-", name).lower()
  38. def _valid(name: str) -> str | None:
  39. return normalize(name) if _NAME.fullmatch(name) else None
  40. def failed_cached_packages(output: str) -> set[str]:
  41. """Packages uv could not install because their cached copy is corrupt.
  42. Empty unless uv failed in its install step AND the cause is one of the
  43. cache-integrity shapes above, so a resolver, network or build failure is
  44. never retried as corruption.
  45. """
  46. text = output or ""
  47. lowered = text.lower()
  48. if not (any(cause in lowered for cause in _CORRUPT_CAUSES) or _MISSING_ARCHIVE.search(text)):
  49. return set()
  50. names = set()
  51. for match in _FAILED_INSTALL.finditer(text):
  52. name = _valid(match.group(1).split("-", 1)[0])
  53. if name:
  54. names.add(name)
  55. return names
  56. _HEAD = 65536
  57. # How long a sweep waits for uv's cache lock before leaving the leftovers for later.
  58. _LOCK_WAIT_SECONDS = 10.0
  59. _WHEEL_VERSION = re.compile(rb"(?im)^wheel-version[ \t]*:")
  60. _FILES = (("WHEEL", _WHEEL_VERSION), ("METADATA", None), ("RECORD", None))
  61. def _stream_damaged(stream, header: re.Pattern | None) -> bool:
  62. """Positive evidence of a torn write: empty, NUL bytes anywhere, or *header* never seen.
  63. The whole file is scanned in bounded chunks: a torn write can keep the
  64. first pages and lose later ones.
  65. """
  66. seen = header is None
  67. carry = b""
  68. empty = True
  69. while chunk := stream.read(_HEAD):
  70. empty = False
  71. if b"\0" in chunk:
  72. return True
  73. if not seen:
  74. window = carry + chunk
  75. seen = bool(header.search(window))
  76. carry = window[-64:]
  77. return empty or not seen
  78. def _damaged(path: Path, header: re.Pattern | None = None) -> bool:
  79. """True only on positive evidence of a torn write (see _stream_damaged).
  80. A missing file is damage. A linked file, or one that cannot be read for
  81. another reason (permissions), proves nothing and counts as healthy: a
  82. false positive would delete an entry uv can still use.
  83. """
  84. try:
  85. if path.is_symlink():
  86. return False
  87. with path.open("rb") as stream:
  88. return _stream_damaged(stream, header)
  89. except FileNotFoundError:
  90. return True
  91. except OSError:
  92. return False
  93. def _dist_name(info: str) -> str | None:
  94. match = _DIST_INFO.fullmatch(info)
  95. return _valid(match.group("name")) if match else None
  96. def _archive_root(cache: Path) -> Path | None:
  97. """``cache/archive-v0`` when it is a real directory inside the cache, else None."""
  98. archive = cache / "archive-v0"
  99. if archive.is_symlink() or is_junction(archive) or not archive.is_dir():
  100. return None
  101. return archive
  102. def corrupt_cache_entries(cache: Path) -> dict[str, list[str]]:
  103. """Unpacked cache entries uv cannot install from, as package -> archive entry names.
  104. Checks the three files uv reads first. An interrupted write leaves them
  105. missing, empty or NUL-filled, and a torn WHEEL loses its Wheel-Version
  106. line. Nothing else counts: unknown layouts, linked or junctioned entries,
  107. linked files and a linked ``archive-v0`` are skipped, never guessed at.
  108. Read-only.
  109. """
  110. found: dict[str, list[str]] = {}
  111. archive = _archive_root(cache)
  112. if archive is None:
  113. return found
  114. try:
  115. buckets = list(archive.iterdir())
  116. except OSError:
  117. return found
  118. for bucket in buckets:
  119. try:
  120. if bucket.is_symlink() or is_junction(bucket) or not bucket.is_dir():
  121. continue
  122. infos = [entry for entry in bucket.iterdir()
  123. if entry.name.endswith(".dist-info") and not entry.is_symlink() and entry.is_dir()]
  124. except OSError:
  125. continue
  126. for info in infos:
  127. name = _dist_name(info.name)
  128. if name and any(_damaged(info / file, header) for file, header in _FILES):
  129. found.setdefault(name, []).append(bucket.name)
  130. return found
  131. def corrupt_cached_packages(cache: Path) -> set[str]:
  132. """Packages with at least one corrupt unpacked cache entry."""
  133. return set(corrupt_cache_entries(cache))
  134. def remove_corrupt_entries(cache: Path, names: set[str]) -> None:
  135. """Delete the corrupt archive entries of *names* that ``uv cache clean`` left behind.
  136. Where uv links a wheel to its archive by symlink (Linux, macOS), clean
  137. drops the link and leaves the archive, which nothing uses again but
  138. ``hermes pm doctor`` would keep reporting. ``uv cache prune`` is not an
  139. option: PM seeds this cache from a bundle copy whose links are real
  140. directories, and prune treats their archives as unreachable, so the next
  141. install fails. On Windows uv's pointer files let clean take the archive.
  142. Holds uv's own cache lock so no uv process is reading an entry while it is
  143. deleted. If uv keeps the lock busy past _LOCK_WAIT_SECONDS the leftovers
  144. stay; they are harmless and ``hermes pm doctor --repair`` takes them.
  145. """
  146. archive = _archive_root(cache)
  147. if not names or os.name == "nt" or archive is None:
  148. return
  149. with open(cache / ".lock", "a+b") as lock:
  150. if not lock_fd(lock.fileno(), wait=True, timeout=_LOCK_WAIT_SECONDS):
  151. return
  152. for package, buckets in corrupt_cache_entries(cache).items():
  153. if package in names:
  154. for bucket in buckets:
  155. shutil.rmtree(archive / bucket, ignore_errors=True)