hermes_state_lockguard.py 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197
  1. """Hold a state.db writer's WAL-mode file locks in a form a stray ``close()`` cannot cancel.
  2. SQLite protects a live WAL generation with two POSIX advisory locks: a SHARED lock on the main
  3. file's lock range and a shared lock on the DMS byte of ``state.db-shm``. A sibling process may
  4. checkpoint and unlink ``-wal``/``-shm`` at its close only after taking both EXCLUSIVE. POSIX locks
  5. are per process, so any ``open()``/``close()`` of those two files inside the holder — a raw probe,
  6. a plugin, a tool reading ``~/.hermes`` — cancels both (sqlite.org/howtocorrupt.html §2.2) and the
  7. next foreign close strands the holder on a deleted generation (``DeletedWalGenerationError``).
  8. This module adds the same two ranges as *open file description* locks (``F_OFD_SETLK``) on the
  9. descriptors SQLite itself holds. OFD locks belong to the description, not the process: a stray
  10. ``close()`` elsewhere cannot cancel them, they die with the connection's own descriptor (nothing
  11. extra to track or retire), and they conflict with a foreign EXCLUSIVE exactly like SQLite's own,
  12. so the sibling's close-time unlink is refused while a guarded handle is open. The guard is
  13. lifted before the handle's own close so a true last close still ends the generation normally;
  14. lifting it first re-takes SQLite's own POSIX locks on the same ranges, so the handle is never
  15. unlocked while its connection is still open. No-op on Windows and on runtimes without OFD locks.
  16. Ownership model: the guard is a property of the *descriptor*, and a descriptor number is
  17. reusable. Each ``hold()`` therefore locks every matching descriptor unconditionally (an OFD
  18. re-lock on an already-locked description is idempotent) and ``release()`` unlocks only while
  19. another handle in this process still needs the range — tracked by handle count per INODE, not
  20. per fd, so a recycled fd number can never be mistaken for a surviving lock.
  21. """
  22. from __future__ import annotations
  23. import logging
  24. import os
  25. import struct
  26. import sys
  27. import threading
  28. from typing import Dict, Optional, Set, Tuple
  29. logger = logging.getLogger("hermes_state")
  30. # SQLite's unix VFS lock geometry (os_unix.c): the SHARED range on the main file and the
  31. # deadman-switch byte of the -shm file.
  32. _PENDING_BYTE = 0x40000000
  33. _SHARED_FIRST = _PENDING_BYTE + 2
  34. _SHARED_SIZE = 510
  35. _SHM_DMS_BYTE = 128
  36. # Windows has no POSIX advisory locks, and the module promises to be a no-op there. Gate on the
  37. # platform FIRST: some Windows installs have a third-party module importable as `fcntl` (stock
  38. # CPython for Windows ships none), and letting the import decide would arm the guard on a
  39. # lookalike. Off Windows a partial module is equally fatal at import time — every importer of
  40. # hermes_state dies before supported() can say "no" (#118026) — so tolerate a missing attribute
  41. # the same way as a missing module and fall back to the no-op.
  42. if os.name == "nt":
  43. fcntl = None # type: ignore[assignment]
  44. _F_OFD_SETLK: Optional[int] = None
  45. _F_RDLCK = _F_UNLCK = _SEEK_SET = _F_SETLK = 0
  46. else:
  47. try:
  48. import fcntl
  49. # CPython exports F_OFD_SETLK only from 3.12. The kernel ABI values are stable: 37 on every
  50. # Linux arch (asm-generic/fcntl.h), 90 on XNU (bsd/sys/fcntl.h, documented in fcntl(2)).
  51. _F_OFD_SETLK = getattr(
  52. fcntl, "F_OFD_SETLK", {"linux": 37, "darwin": 90}.get(sys.platform.rstrip("0123456789")))
  53. _F_RDLCK, _F_UNLCK, _SEEK_SET = fcntl.F_RDLCK, fcntl.F_UNLCK, os.SEEK_SET
  54. _F_SETLK = fcntl.F_SETLK
  55. # The constants alone do not make the guard usable: _ofd_lock() calls fcntl.fcntl(), so a
  56. # module that has the constants but no callable would pass supported() and then raise
  57. # from the first hold(). Probe the whole capability here, not just the symbols.
  58. if not callable(getattr(fcntl, "fcntl", None)):
  59. raise ImportError("fcntl module has no fcntl() callable")
  60. except (ImportError, AttributeError):
  61. fcntl = None # type: ignore[assignment]
  62. _F_OFD_SETLK = None
  63. _F_RDLCK = _F_UNLCK = _SEEK_SET = _F_SETLK = 0
  64. # struct flock differs per libc: glibc/musl put type+whence first, Darwin/BSD last.
  65. _FLOCK_FORMAT = "@qqihh" if sys.platform == "darwin" or "bsd" in sys.platform else "@hhqqi"
  66. Identity = tuple[int, int]
  67. Held = dict[Identity, tuple[int, int]] # inode this handle guards -> its (start, length) range
  68. # Handles per guarded inode in this process. Several SessionDB handles on one file share the
  69. # same descriptors' locks (hold() locks every matching descriptor), so the LAST handle unlocks.
  70. _LOCK = threading.Lock()
  71. _HANDLES: dict[Identity, int] = {}
  72. def supported() -> bool:
  73. return _F_OFD_SETLK is not None
  74. def _flock(lock_type: int, start: int, length: int) -> bytes:
  75. if _FLOCK_FORMAT == "@qqihh":
  76. return struct.pack(_FLOCK_FORMAT, start, length, 0, lock_type, _SEEK_SET)
  77. return struct.pack(_FLOCK_FORMAT, lock_type, _SEEK_SET, start, length, 0)
  78. def _ofd_lock(fd: int, lock_type: int, start: int, length: int, *, cmd: Optional[int] = None) -> bool:
  79. """Apply a non-blocking OFD lock (a process-owned POSIX one with ``cmd=_F_SETLK``); False when
  80. the range is held EXCLUSIVE elsewhere."""
  81. assert fcntl is not None and _F_OFD_SETLK is not None
  82. try:
  83. fcntl.fcntl(fd, _F_OFD_SETLK if cmd is None else cmd, _flock(lock_type, start, length))
  84. except BlockingIOError:
  85. return False
  86. return True
  87. def _identity(path: str) -> Optional[Identity]:
  88. try:
  89. st = os.stat(path)
  90. except OSError:
  91. return None
  92. return (st.st_dev, st.st_ino)
  93. def _own_fds_for(identities: set[Identity]):
  94. """Yield ``(fd, identity)`` for every descriptor of this process on one of *identities*
  95. (SQLite's own connection descriptors; the cached header-probe fd too, harmless)."""
  96. for fd_dir in ("/proc/self/fd", "/dev/fd"):
  97. try:
  98. names = os.listdir(fd_dir)
  99. except OSError:
  100. continue
  101. for name in names:
  102. if not name.isdigit():
  103. continue
  104. fd = int(name)
  105. try:
  106. st = os.fstat(fd)
  107. except OSError:
  108. continue
  109. ident = (st.st_dev, st.st_ino)
  110. if ident in identities:
  111. yield fd, ident
  112. return
  113. def _guard_ranges(db_path) -> Held:
  114. base = os.fspath(db_path)
  115. ranges: Held = {}
  116. for path, rng in ((base, (_SHARED_FIRST, _SHARED_SIZE)), (base + "-shm", (_SHM_DMS_BYTE, 1))):
  117. ident = _identity(path)
  118. if ident is not None:
  119. ranges[ident] = rng
  120. return ranges
  121. def hold(db_path, held: Optional[Held] = None) -> Held:
  122. """Lock the guard ranges on every descriptor this process has open on ``state.db`` and its
  123. ``-shm``. Returns the record :func:`release` needs; pass it back to extend an existing one
  124. (a ``-shm`` minted after open, a reopened connection). Idempotent per handle: an inode already
  125. in *held* is re-locked (cheap, covers a new descriptor) without a second handle count."""
  126. held = {} if held is None else held
  127. if not supported():
  128. return held
  129. ranges = _guard_ranges(db_path)
  130. try:
  131. with _LOCK:
  132. for fd, ident in _own_fds_for(set(ranges)):
  133. start, length = ranges[ident]
  134. if _ofd_lock(fd, _F_RDLCK, start, length) and ident not in held:
  135. held[ident] = ranges[ident]
  136. _HANDLES[ident] = _HANDLES.get(ident, 0) + 1
  137. except OSError:
  138. logger.debug("WAL lock guard unavailable for %s", os.fspath(db_path), exc_info=True)
  139. return held
  140. def release(held: Held) -> None:
  141. """Drop this handle's claim. The last handle on an inode unlocks the range on every descriptor
  142. still referencing it. Call BEFORE the handle's own close so SQLite's close-time reset sees only
  143. real holders: a sibling process's intact locks still refuse the unlink, and a true last close
  144. ends the generation, so a later ``state.db`` replace never pairs with a stale WAL.
  145. The OFD copy is swapped back for the POSIX lock SQLite believes it still holds (a stray close
  146. cancelled the real one): unlocked outright, the still-open connection would let a sibling's
  147. close take EXCLUSIVE and unlink ``-wal``/``-shm`` under it before its own close runs. SQLite's
  148. close upgrades or drops that process-owned lock itself, so a true last close is unaffected."""
  149. if not supported() or not held:
  150. return
  151. with _LOCK:
  152. to_unlock: Held = {}
  153. for ident, rng in held.items():
  154. remaining = _HANDLES.get(ident, 1) - 1
  155. if remaining > 0:
  156. _HANDLES[ident] = remaining
  157. else:
  158. _HANDLES.pop(ident, None)
  159. to_unlock[ident] = rng
  160. held.clear()
  161. if not to_unlock:
  162. return
  163. try:
  164. for fd, ident in _own_fds_for(set(to_unlock)):
  165. start, length = to_unlock[ident]
  166. _ofd_lock(fd, _F_RDLCK, start, length, cmd=_F_SETLK) # never refused: our OFD lock excludes writers
  167. _ofd_lock(fd, _F_UNLCK, start, length)
  168. except OSError:
  169. pass