file_operations_native.py 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  1. """In-process write primitives for the local POSIX backend.
  2. ``write_file`` asked the backend shell three questions per write (pre-write probe, atomic write,
  3. sha256 verification): three ``bash`` spawns, ~100 ms on a warm host before any real work. On the
  4. local POSIX backend the file is on this host, so ``ShellFileOperations`` answers them here instead,
  5. under the same gate as the native read path (``_native_read_enabled``; ``HERMES_NATIVE_FILE_READ=0``
  6. turns both off). Semantics mirror the shell scripts they replace; anything they cannot answer
  7. (a FIFO, a device, an unexpected error) returns None and the caller takes the shell path.
  8. """
  9. from __future__ import annotations
  10. import contextlib
  11. import hashlib
  12. import os
  13. import secrets
  14. import stat
  15. from typing import Optional
  16. _UTF8_BOM = b"\xef\xbb\xbf"
  17. def _open_regular(path: str) -> Optional[int]:
  18. """fd of ``path`` when it is a regular file; None when missing; raises ``_NotRegular`` otherwise.
  19. One lookup with O_NONBLOCK, judged by fstat: a FIFO swapped in never blocks this thread."""
  20. try:
  21. fd = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
  22. except FileNotFoundError:
  23. return None
  24. if not stat.S_ISREG(os.fstat(fd).st_mode):
  25. os.close(fd)
  26. raise _NotRegular(path)
  27. return fd
  28. class _NotRegular(OSError):
  29. pass
  30. def probe(path: str, want_text: bool) -> Optional[tuple[bool, Optional[bytes]]]:
  31. """``(has_bom, body)`` for a write target: ``body`` is the whole file when ``want_text`` else its
  32. first 4 KB (the line-ending sample); ``(False, None)`` when the file is missing; None = ask the shell."""
  33. try:
  34. fd = _open_regular(path)
  35. if fd is None:
  36. return False, None
  37. with open(fd, "rb") as fh:
  38. data = fh.read() if want_text else fh.read(4096)
  39. except OSError:
  40. return None
  41. return data.startswith(_UTF8_BOM), data
  42. def atomic_write(path: str, data: bytes) -> Optional[str]:
  43. """Replace ``path`` with ``data`` atomically; None on success, else an error message.
  44. Same contract as the shell script: a symlink target is written through (the link survives),
  45. parent directories are created, the temp file lives in the target's directory so the rename is
  46. atomic, an existing target's mode is kept and a new one gets the umask default (``O_CREAT`` with
  47. 0o666 applies the process umask itself), and the temp is removed on every failure.
  48. The temp holds its final mode before the first byte lands: an existing target's temp is created
  49. 0o600 and ``fchmod``-ed to the target's mode, so a private file's new contents are never readable
  50. through a wider temp (the shell script's ``mktemp`` 0600 temp gave the same guarantee)."""
  51. target = os.path.realpath(path) if os.path.islink(path) else path
  52. parent = os.path.dirname(target) or "."
  53. try:
  54. os.makedirs(parent, exist_ok=True)
  55. try:
  56. mode: Optional[int] = stat.S_IMODE(os.stat(target).st_mode)
  57. except FileNotFoundError:
  58. mode = None
  59. tmp = os.path.join(parent, f".hermes-tmp.{secrets.token_hex(6)}")
  60. fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0),
  61. 0o666 if mode is None else 0o600)
  62. except OSError as e:
  63. return f"{e.strerror or e}: {e.filename or target}"
  64. try:
  65. if mode is not None:
  66. try:
  67. os.fchmod(fd, mode) # before any content: the bytes never sit in a wider file
  68. except OSError:
  69. pass # best effort, as in the shell script (the temp then stays 0o600)
  70. with open(fd, "wb") as fh:
  71. fh.write(data)
  72. os.replace(tmp, target)
  73. except OSError as e:
  74. with contextlib.suppress(OSError):
  75. os.unlink(tmp)
  76. return f"{e.strerror or e}: {e.filename or target}"
  77. return None
  78. def sha256_of(path: str) -> Optional[str]:
  79. """Hex sha256 of the regular file at ``path``; None when it cannot be read natively."""
  80. try:
  81. fd = _open_regular(path)
  82. if fd is None:
  83. return None
  84. digest = hashlib.sha256()
  85. with open(fd, "rb") as fh:
  86. for chunk in iter(lambda: fh.read(1 << 20), b""):
  87. digest.update(chunk)
  88. except OSError:
  89. return None
  90. return digest.hexdigest()
  91. __all__ = ["atomic_write", "probe", "sha256_of"]