329 lines
17 KiB
Python
329 lines
17 KiB
Python
from __future__ import annotations
|
|
|
|
__lazy_modules__ = ["hashlib", "pathlib", "socket", "typing"]
|
|
|
|
import hashlib
|
|
import os
|
|
import socket
|
|
import sys
|
|
from errno import EPERM, ESRCH
|
|
from pathlib import Path
|
|
from typing import Final
|
|
|
|
#: Every marker format in this package caps the hostname at the RFC 1123 limit and reads a longer one as malformed.
|
|
_HOST_NAME_LIMIT: Final[int] = 253
|
|
#: The bytes those formats carry verbatim: printable non-space ASCII, less the ``?`` reserved for the escape.
|
|
_HOST_NAME_VERBATIM: Final[frozenset[int]] = frozenset(range(0x21, 0x7F)) - {ord("?")}
|
|
#: The characters at the end of an over-long name that carry a digest of the part cut off.
|
|
_HOST_NAME_DIGEST_LEN: Final[int] = 8
|
|
#: The kernel ABI fixes the initial PID namespace's inode (``PID_NS_INIT_INO`` in ``linux/nsfs.h``); every namespace
|
|
#: created later draws one from ``0xF0000000`` up, so this value names the host's own namespace.
|
|
_INITIAL_PID_NAMESPACE: Final[int] = 0xEFFFFFFC
|
|
_NAMESPACE_MARK: Final[str] = "?pidns-"
|
|
|
|
|
|
def host_name() -> str:
|
|
"""
|
|
The hostname recorded alongside an owner, so a marker written on another machine is never probed here.
|
|
|
|
Marker formats here hold the field to printable non-space ASCII, while ``socket.gethostname()`` reports whatever
|
|
the kernel stores: a space, a newline that forges an extra marker line, or a byte no codec encodes, which Python
|
|
hands back as a surrogate. A holder that publishes one raw writes a marker it cannot read back, and loses the lock
|
|
to the first peer that ages it out as malformed. ``?`` is illegal in a hostname, so escaping it along with every
|
|
out-of-grammar byte as ``?<hex>`` leaves a real name untouched and still keeps two hosts apart, which
|
|
:func:`owner_is_stale` relies on to refuse to probe a foreign PID.
|
|
|
|
Linux appends the PID namespace, as Mercurial's lock prefix does. Two containers in one pod share the hostname and
|
|
the boot id but not the PID namespace, so a PID recorded in one names another process, or none, in the other. The
|
|
suffix starts with a ``?`` no escape can produce, so ``a`` in a namespace never reads as a host literally named
|
|
``a?pidns-...``. The initial namespace adds nothing, which keeps a host's name what older releases recorded.
|
|
|
|
An over-long name ends in a digest of the part cut to fit the limit. A bare cut gives every name that shares the
|
|
kept prefix one identity, and :func:`owner_is_stale` would then probe a local PID for another host's holder.
|
|
"""
|
|
name = (
|
|
"".join(
|
|
chr(byte) if byte in _HOST_NAME_VERBATIM else f"?{byte:02x}"
|
|
for byte in socket.gethostname().encode("utf-8", "surrogateescape")
|
|
)
|
|
+ _pid_namespace_suffix()
|
|
)
|
|
if len(name) > _HOST_NAME_LIMIT:
|
|
keep = _HOST_NAME_LIMIT - _HOST_NAME_DIGEST_LEN - 1
|
|
name = f"{name[:keep]}-{hashlib.sha256(name[keep:].encode()).hexdigest()[:_HOST_NAME_DIGEST_LEN]}"
|
|
# An escape is three characters and a kept byte is never '?', so a bare '?' can only mean an empty hostname.
|
|
return name or "?"
|
|
|
|
|
|
def _pid_namespace_suffix() -> str:
|
|
try:
|
|
namespace: Final = Path("/proc/self/ns/pid").stat().st_ino
|
|
except OSError: # only Linux 3.8+ has the file, and a sandbox may hide it; nothing else tells namespaces apart
|
|
return ""
|
|
return "" if namespace == _INITIAL_PID_NAMESPACE else f"{_NAMESPACE_MARK}{namespace:x}"
|
|
|
|
|
|
def owner_is_stale(pid: int, hostname: str, start_token: int | None) -> bool:
|
|
"""
|
|
Whether the recorded owner is provably gone, so reclaiming its marker cannot detach a live holder.
|
|
|
|
Fail closed: return ``True`` only when this process can prove the exact recorded owner is dead. A marker from
|
|
another host cannot be probed; a live PID whose start token still matches, or whose token cannot be read, is the
|
|
holder or is indistinguishable from it; a live PID whose start token differs is a recycled PID, so the process that
|
|
wrote the marker is gone. PostgreSQL, Qt ``QLockFile`` and Mercurial all break a stale lock only on proof of death
|
|
and treat an unreadable or foreign owner as still holding.
|
|
"""
|
|
if hostname != host_name():
|
|
return False
|
|
if process_alive(pid) and (
|
|
start_token is None or (current := process_start_token(pid)) is None or _same_start(current, start_token)
|
|
):
|
|
return False
|
|
# Only a bare hostname can be an older release's, written from a container that shares this host's name.
|
|
return _NAMESPACE_MARK in hostname or not _owner_runs_elsewhere(pid, start_token)
|
|
|
|
|
|
def owner_is_current_process(pid: int, hostname: str, start_token: int | None) -> bool:
|
|
"""
|
|
Whether the recorded owner is this process, so a marker a recycled PID left behind never reads as ours.
|
|
|
|
Fail closed: a recorded start token must match this process's. One that differs was written by an earlier process
|
|
that reused this PID, and when this process cannot read its own token nothing proves the marker is ours. A marker
|
|
without a token falls back to the PID and hostname.
|
|
"""
|
|
if pid != os.getpid() or hostname != host_name():
|
|
return False
|
|
return start_token is None or start_token == process_start_token(pid)
|
|
|
|
|
|
def _same_start(current: int, recorded: int) -> bool:
|
|
# A Linux token carries the boot id in its high 64 bits, or 0 there when the process could not read the boot id.
|
|
# systemd's ProcSubset=pid hides /proc/sys from one unit, so one process may lack the boot id while its peer has
|
|
# it. A missing boot id then proves nothing, and only starttime is compared. Other platforms' tokens fit in the
|
|
# low bits.
|
|
return current == recorded or (0 in {current >> 64, recorded >> 64} and current % 2**64 == recorded % 2**64)
|
|
|
|
|
|
if sys.platform == "win32": # pragma: win32 cover
|
|
import ctypes
|
|
from ctypes import wintypes
|
|
|
|
_KERNEL32: Final[ctypes.WinDLL] = ctypes.WinDLL("kernel32", use_last_error=True)
|
|
_KERNEL32.CloseHandle.argtypes = [wintypes.HANDLE]
|
|
_KERNEL32.CloseHandle.restype = wintypes.BOOL
|
|
_KERNEL32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
|
|
_KERNEL32.OpenProcess.restype = wintypes.HANDLE
|
|
_KERNEL32.GetProcessTimes.argtypes = [
|
|
wintypes.HANDLE,
|
|
ctypes.POINTER(wintypes.FILETIME),
|
|
ctypes.POINTER(wintypes.FILETIME),
|
|
ctypes.POINTER(wintypes.FILETIME),
|
|
ctypes.POINTER(wintypes.FILETIME),
|
|
]
|
|
_KERNEL32.GetProcessTimes.restype = wintypes.BOOL
|
|
|
|
_WIN_SYNCHRONIZE: Final[int] = 0x100000
|
|
_WIN_PROCESS_QUERY_LIMITED_INFORMATION: Final[int] = 0x1000
|
|
_WIN_ERROR_INVALID_PARAMETER: Final[int] = 87
|
|
_WIN_INHERIT_HANDLE: Final[bool] = False
|
|
|
|
def process_alive(pid: int) -> bool:
|
|
"""Whether a process with this PID exists, treating an access denial as proof it does."""
|
|
handle = _KERNEL32.OpenProcess(_WIN_SYNCHRONIZE, _WIN_INHERIT_HANDLE, pid)
|
|
if handle:
|
|
_KERNEL32.CloseHandle(handle)
|
|
return True
|
|
return ctypes.get_last_error() != _WIN_ERROR_INVALID_PARAMETER
|
|
|
|
def process_start_token(pid: int) -> int | None:
|
|
"""The process creation FILETIME as a 100ns tick count, or ``None`` when it cannot be read."""
|
|
handle = _KERNEL32.OpenProcess(_WIN_PROCESS_QUERY_LIMITED_INFORMATION, _WIN_INHERIT_HANDLE, pid)
|
|
if not handle:
|
|
return None
|
|
creation, exit_time, kernel_time, user_time = (wintypes.FILETIME() for _ in range(4))
|
|
try:
|
|
if not _KERNEL32.GetProcessTimes(
|
|
handle,
|
|
ctypes.byref(creation),
|
|
ctypes.byref(exit_time),
|
|
ctypes.byref(kernel_time),
|
|
ctypes.byref(user_time),
|
|
):
|
|
return None # pragma: no cover # win32 GetProcessTimes failure path; not reproducible on a live handle
|
|
finally:
|
|
_KERNEL32.CloseHandle(handle)
|
|
return (creation.dwHighDateTime << 32) | creation.dwLowDateTime
|
|
|
|
else: # pragma: win32 no cover
|
|
|
|
def process_alive(pid: int) -> bool:
|
|
"""Whether a process with this PID exists, treating an access denial (``EPERM``) as proof it does."""
|
|
try:
|
|
os.kill(pid, 0)
|
|
except OSError as error:
|
|
if error.errno == ESRCH:
|
|
return False
|
|
if error.errno == EPERM:
|
|
return True
|
|
raise
|
|
return True
|
|
|
|
if sys.platform in {"linux", "android"}: # pragma: linux cover
|
|
# Termux/Android reports sys.platform == "android" but runs the Linux kernel, so /proc/<pid>/stat and the boot
|
|
# id are the same reliable start-time source; treat it exactly like Linux rather than the tokenless fallback.
|
|
# comm (field 2) is wrapped in parentheses and may itself contain spaces or a ')', so the fixed fields start
|
|
# after the final ')'. starttime is field 22 overall, the twentieth of those trailing fields (index 19).
|
|
_STARTTIME_INDEX: Final[int] = 19
|
|
|
|
def _read_boot_id() -> int:
|
|
# starttime is measured in clock ticks since boot, so on its own it repeats across a reboot. Folding the
|
|
# boot id into the high bits makes the Linux token reboot-safe like the absolute clocks macOS and Windows
|
|
# expose, while staying a single integer so a 3.29 reader still parses the third marker line. 0 when this
|
|
# process cannot read the boot id leaves the bare starttime, which _same_start compares alone.
|
|
try:
|
|
boot_id = Path("/proc/sys/kernel/random/boot_id").read_text(encoding="ascii")
|
|
return int(boot_id.strip().replace("-", ""), 16)
|
|
except (OSError, ValueError):
|
|
return 0
|
|
|
|
_BOOT_ID: Final[int] = _read_boot_id()
|
|
#: ``TIME_NS_INIT_INO`` in ``linux/proc_ns.h``, fixed by the kernel ABI like the initial PID namespace's inode.
|
|
_INITIAL_TIME_NAMESPACE: Final[int] = 0xEFFFFFFA
|
|
|
|
def process_start_token(pid: int) -> int | None:
|
|
"""
|
|
The ``/proc/<pid>/stat`` ``starttime`` folded with the boot id.
|
|
|
|
``None`` when the process is gone, or when this process runs in a time namespace with a boottime offset.
|
|
Since Linux 5.6 the kernel shifts ``starttime`` by the reader's offset, so a value read there differs
|
|
from what a peer outside reads.
|
|
"""
|
|
return _read_start_token(pid) if _starttime_unshifted() else None
|
|
|
|
def _starttime_unshifted() -> bool:
|
|
# setns can move this process into another time namespace, so ask on every read.
|
|
try:
|
|
namespace: Final = Path("/proc/self/ns/time").stat().st_ino
|
|
except FileNotFoundError: # no entry means no time namespaces on this kernel
|
|
return True
|
|
except OSError: # any other failure leaves the namespace unknown, so starttime is not comparable
|
|
return False
|
|
if namespace == _INITIAL_TIME_NAMESPACE:
|
|
return True
|
|
# A container runtime may give each container a time namespace without offsets. timens_offsets describes
|
|
# the namespace this process's children get, its own unless it unshared one since.
|
|
try:
|
|
if Path("/proc/self/ns/time_for_children").stat().st_ino != namespace:
|
|
return False
|
|
offsets: Final = Path("/proc/self/timens_offsets").read_text(encoding="ascii")
|
|
except OSError:
|
|
return False
|
|
# The clock goes by name since Linux 5.8 and by clock id before.
|
|
return any(line.split() in (["boottime", "0", "0"], ["7", "0", "0"]) for line in offsets.splitlines())
|
|
|
|
def _read_start_token(pid: int) -> int | None:
|
|
try:
|
|
data = Path(f"/proc/{pid}/stat").read_bytes()
|
|
except OSError:
|
|
return None
|
|
# psutil identifies a process by the same (pid, starttime) pair; the boot id extends that across reboots.
|
|
fields = data[data.rfind(b")") + 1 :].split()
|
|
if len(fields) <= _STARTTIME_INDEX: # pragma: no cover # a truncated /proc read, never seen in practice
|
|
return None
|
|
try:
|
|
starttime = int(fields[_STARTTIME_INDEX])
|
|
except ValueError: # pragma: no cover # /proc always renders starttime as an integer
|
|
return None
|
|
return (_BOOT_ID << 64) | starttime
|
|
|
|
def _owner_runs_elsewhere(pid: int, start_token: int | None) -> bool:
|
|
"""
|
|
Whether the owner runs in another PID namespace as *pid*.
|
|
|
|
An older release in a container sharing this hostname recorded its in-container PID, which means nothing
|
|
here. Readers without a boottime offset read the same starttime and boot id. A task with the recorded
|
|
start token whose innermost PID is *pid* is therefore the owner; one that started in the same tick is not.
|
|
A reader with an offset cannot compare start tokens, so the innermost PID alone keeps the marker.
|
|
"""
|
|
if start_token is None or (_BOOT_ID and start_token >> 64 not in {0, _BOOT_ID}):
|
|
return False
|
|
unshifted: Final = _starttime_unshifted()
|
|
try:
|
|
with os.scandir("/proc") as entries:
|
|
return any(
|
|
entry.name.isdigit()
|
|
and (task := int(entry.name)) != pid
|
|
and (
|
|
not unshifted
|
|
or ((token := _read_start_token(task)) is not None and _same_start(token, start_token))
|
|
)
|
|
and _innermost_pid(task) == pid
|
|
for entry in entries
|
|
)
|
|
except OSError:
|
|
# A /proc this process cannot list proves nothing either way, which leaves 4.0.12's verdict.
|
|
return False
|
|
|
|
def _innermost_pid(task: int) -> int | None:
|
|
try:
|
|
status: Final = Path(f"/proc/{task}/status").read_bytes()
|
|
except OSError: # pragma: no cover # the task exited between the stat read and this one
|
|
return None
|
|
# The kernel ends a line only with "\n". A task names itself, and its Name line keeps "\r", "\v" and the
|
|
# other separators that a text-mode read and str.splitlines() split at. A name could then forge a line.
|
|
return next(
|
|
(int(line.split()[-1]) for line in status.split(b"\n") if line.startswith(b"NSpid:")),
|
|
None, # kernels before 4.1 record no namespace PIDs
|
|
)
|
|
|
|
elif sys.platform == "darwin": # pragma: darwin cover
|
|
import ctypes
|
|
import struct
|
|
|
|
_LIBC: Final[ctypes.CDLL] = ctypes.CDLL(None, use_errno=True)
|
|
_CTL_KERN: Final[int] = 1
|
|
_KERN_PROC: Final[int] = 14
|
|
_KERN_PROC_PID: Final[int] = 1
|
|
# kinfo_proc opens with kp_proc.p_starttime (a struct timeval) at offset 0: int64 seconds, int32 microseconds.
|
|
# The offset is fixed by the struct chain kinfo_proc -> extern_proc -> p_un, so a read at 0 is not a guess.
|
|
_TIMEVAL_AT_ZERO: Final[str] = "<qi"
|
|
_TIMEVAL_SIZE: Final[int] = struct.calcsize(_TIMEVAL_AT_ZERO)
|
|
|
|
def process_start_token(pid: int) -> int | None:
|
|
"""The process start time in microseconds from ``sysctl(KERN_PROC_PID)``, or ``None`` when it is gone."""
|
|
mib = (ctypes.c_int * 4)(_CTL_KERN, _KERN_PROC, _KERN_PROC_PID, pid)
|
|
length = ctypes.c_size_t(0)
|
|
# The size probe reports the kinfo_proc size for any PID, so the read below, not the probe, tells a live
|
|
# process from a gone one: a gone PID leaves the fetch a zero-length success, so re-check the length after.
|
|
if _LIBC.sysctl(mib, 4, None, ctypes.byref(length), None, 0) != 0:
|
|
return None
|
|
buffer = (ctypes.c_char * length.value)()
|
|
if _LIBC.sysctl(mib, 4, buffer, ctypes.byref(length), None, 0) != 0 or length.value < _TIMEVAL_SIZE:
|
|
return None
|
|
seconds, microseconds = struct.unpack_from(_TIMEVAL_AT_ZERO, buffer.raw, 0)
|
|
return seconds * 1_000_000 + microseconds
|
|
|
|
else: # pragma: no cover # a POSIX platform without a proven start-time source falls back to fail-closed liveness
|
|
|
|
def process_start_token(pid: int) -> int | None:
|
|
"""No proven start-time source, so the owner carries no token and liveness rests on the PID alone."""
|
|
del pid
|
|
return None
|
|
|
|
|
|
if sys.platform not in {"linux", "android"}: # pragma: linux no cover # pragma: android no cover
|
|
|
|
def _owner_runs_elsewhere(pid: int, start_token: int | None) -> bool:
|
|
"""Without Linux PID namespaces, a PID that is gone or recycled leaves its owner nowhere else to run."""
|
|
del pid, start_token
|
|
return False
|
|
|
|
|
|
__all__ = [
|
|
"host_name",
|
|
"owner_is_current_process",
|
|
"owner_is_stale",
|
|
"process_alive",
|
|
"process_start_token",
|
|
]
|