ringo-task-queue 0.1.0.dev8__py3-none-macosx_13_0_x86_64.whl

ringo_task_queue/_supervisor_process.py

@@ -0,0 +1,562 @@
+"""Private, synchronous resource ownership for the supervisor's gated child.
+
+The caller MUST keep the child bootstrap blocked until construction succeeds.
+Windows launchers must also use CREATE_SUSPENDED and call resume_root() after
+assignment, so venv redirectors cannot start an uncontained base interpreter.
+Windows owns an unnamed, non-inheritable Job; all ordinary descendants inherit
+it, even after the root exits. Explicit CREATE_BREAKAWAY_FROM_JOB is permitted
+for the shared daemon, but silent breakaway is deliberately NOT enabled.
+
+POSIX callers must use Popen(start_new_session=True). A process group/session
+and psutil creation-time identities are tracked, not process names or a cached
+PID alone. This is not a cgroup: an unobserved child can escape via setsid() or
+setpgid(). Observed escapees remain tracked. If all identity anchors disappear
+before descendants are observed, ownership cannot safely be distinguished from
+PGID reuse; operations fail closed instead of signalling an unrelated group.
+
+No child is launched here, and kill() does not perform a graceful STOP/wait.
+Call wait_empty() before close(); a closed object cannot verify termination.
+Only the POSIX backend imports the optional psutil dependency, lazily.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import math
+import os
+import signal
+import time
+from ctypes import wintypes
+from typing import Any
+
+from .errors import RingoError
+
+_JOB_OBJECT_LIMIT_BREAKAWAY_OK = 0x00000800
+_JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+_JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
+_JOB_OBJECT_BASIC_PROCESS_ID_LIST = 3
+_ERROR_MORE_DATA = 234
+_ERROR_INVALID_PARAMETER = 87
+_STILL_ACTIVE = 259
+
+
+class _IoCounters(ctypes.Structure):
+    _fields_ = [
+        (name, ctypes.c_uint64)
+        for name in (
+            "ReadOperationCount",
+            "WriteOperationCount",
+            "OtherOperationCount",
+            "ReadTransferCount",
+            "WriteTransferCount",
+            "OtherTransferCount",
+        )
+    ]
+
+
+class _JobBasicLimitInformation(ctypes.Structure):
+    _fields_ = [
+        ("PerProcessUserTimeLimit", ctypes.c_int64),
+        ("PerJobUserTimeLimit", ctypes.c_int64),
+        ("LimitFlags", ctypes.c_uint32),
+        ("MinimumWorkingSetSize", ctypes.c_size_t),
+        ("MaximumWorkingSetSize", ctypes.c_size_t),
+        ("ActiveProcessLimit", ctypes.c_uint32),
+        ("Affinity", ctypes.c_size_t),
+        ("PriorityClass", ctypes.c_uint32),
+        ("SchedulingClass", ctypes.c_uint32),
+    ]
+
+
+class _JobExtendedLimitInformation(ctypes.Structure):
+    _fields_ = [
+        ("BasicLimitInformation", _JobBasicLimitInformation),
+        ("IoInfo", _IoCounters),
+        ("ProcessMemoryLimit", ctypes.c_size_t),
+        ("JobMemoryLimit", ctypes.c_size_t),
+        ("PeakProcessMemoryUsed", ctypes.c_size_t),
+        ("PeakJobMemoryUsed", ctypes.c_size_t),
+    ]
+
+
+class _JobProcessListHeader(ctypes.Structure):
+    _fields_ = [
+        ("NumberOfAssignedProcesses", ctypes.c_uint32),
+        ("NumberOfProcessIdsInList", ctypes.c_uint32),
+    ]
+
+
+class _ProcessMemoryCounters(ctypes.Structure):
+    _fields_ = [
+        ("cb", ctypes.c_uint32),
+        ("PageFaultCount", ctypes.c_uint32),
+        *[
+            (name, ctypes.c_size_t)
+            for name in (
+                "PeakWorkingSetSize",
+                "WorkingSetSize",
+                "QuotaPeakPagedPoolUsage",
+                "QuotaPagedPoolUsage",
+                "QuotaPeakNonPagedPoolUsage",
+                "QuotaNonPagedPoolUsage",
+                "PagefileUsage",
+                "PeakPagefileUsage",
+            )
+        ],
+    ]
+
+
+def _win_error(operation: str) -> RingoError:
+    error = ctypes.get_last_error()  # type: ignore[attr-defined]
+    detail = ctypes.WinError(error)  # type: ignore[attr-defined]
+    return RingoError(f"supervisor {operation} failed: {detail}")
+
+
+class _WindowsJob:
+    def __init__(self, pid: int) -> None:
+        # Explicit pointer-sized return types are essential on 64-bit Windows.
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+        self._api: Any = kernel32
+        kernel32.CreateJobObjectW.argtypes = (ctypes.c_void_p, wintypes.LPCWSTR)
+        kernel32.CreateJobObjectW.restype = wintypes.HANDLE
+        kernel32.SetHandleInformation.argtypes = (
+            wintypes.HANDLE,
+            wintypes.DWORD,
+            wintypes.DWORD,
+        )
+        kernel32.SetHandleInformation.restype = wintypes.BOOL
+        kernel32.SetInformationJobObject.argtypes = (
+            wintypes.HANDLE,
+            ctypes.c_int,
+            ctypes.c_void_p,
+            wintypes.DWORD,
+        )
+        kernel32.SetInformationJobObject.restype = wintypes.BOOL
+        kernel32.QueryInformationJobObject.argtypes = (
+            wintypes.HANDLE,
+            ctypes.c_int,
+            ctypes.c_void_p,
+            wintypes.DWORD,
+            ctypes.POINTER(wintypes.DWORD),
+        )
+        kernel32.QueryInformationJobObject.restype = wintypes.BOOL
+        kernel32.OpenProcess.argtypes = (wintypes.DWORD, wintypes.BOOL, wintypes.DWORD)
+        kernel32.OpenProcess.restype = wintypes.HANDLE
+        kernel32.AssignProcessToJobObject.argtypes = (wintypes.HANDLE, wintypes.HANDLE)
+        kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
+        kernel32.IsProcessInJob.argtypes = (
+            wintypes.HANDLE,
+            wintypes.HANDLE,
+            ctypes.POINTER(wintypes.BOOL),
+        )
+        kernel32.IsProcessInJob.restype = wintypes.BOOL
+        kernel32.GetExitCodeProcess.argtypes = (
+            wintypes.HANDLE,
+            ctypes.POINTER(wintypes.DWORD),
+        )
+        kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+        kernel32.WaitForSingleObject.argtypes = (wintypes.HANDLE, wintypes.DWORD)
+        kernel32.WaitForSingleObject.restype = wintypes.DWORD
+        kernel32.K32GetProcessMemoryInfo.argtypes = (
+            wintypes.HANDLE,
+            ctypes.POINTER(_ProcessMemoryCounters),
+            wintypes.DWORD,
+        )
+        kernel32.K32GetProcessMemoryInfo.restype = wintypes.BOOL
+        kernel32.TerminateJobObject.argtypes = (wintypes.HANDLE, wintypes.UINT)
+        kernel32.TerminateJobObject.restype = wintypes.BOOL
+        kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
+        kernel32.CloseHandle.restype = wintypes.BOOL
+
+        self._root_handle: int | None = None
+        self._resume_attempted = False
+        self._handle: int | None = kernel32.CreateJobObjectW(None, None)
+        if not self._handle:
+            raise _win_error("CreateJobObjectW")
+        try:
+            if not kernel32.SetHandleInformation(self._handle, 1, 0):
+                raise _win_error("SetHandleInformation(non-inheritable Job)")
+            limits = _JobExtendedLimitInformation()
+            limits.BasicLimitInformation.LimitFlags = (
+                _JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE | _JOB_OBJECT_LIMIT_BREAKAWAY_OK
+            )
+            if not kernel32.SetInformationJobObject(
+                self._handle,
+                _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION,
+                ctypes.byref(limits),
+                ctypes.sizeof(limits),
+            ):
+                raise _win_error("SetInformationJobObject")
+            # Retain the exact non-inheritable root object, not a PID to reopen
+            # later. Assignment needs SET_QUOTA/TERMINATE; resume additionally
+            # needs SUSPEND_RESUME, membership inspection and SYNCHRONIZE.
+            self._root_handle = kernel32.OpenProcess(
+                0x0100 | 0x0001 | 0x0800 | 0x1000 | 0x00100000,
+                False,
+                pid,
+            )
+            if not self._root_handle:
+                self._root_handle = None
+                raise _win_error("OpenProcess(assign child)")
+            if not kernel32.AssignProcessToJobObject(self._handle, self._root_handle):
+                raise _win_error("AssignProcessToJobObject (no unguarded fallback)")
+        except BaseException:
+            self.close()
+            raise
+
+    def _open_handle(self) -> int:
+        if self._handle is None:
+            raise RingoError("supervisor ProcessTree is closed")
+        return self._handle
+
+    def resume_root(self) -> None:
+        job = self._open_handle()
+        process = self._root_handle
+        if process is None:
+            raise RingoError("supervisor root process handle is closed")
+        if self._resume_attempted:
+            raise RingoError("supervisor root resume was already attempted")
+        self._resume_attempted = True
+        belongs = wintypes.BOOL()
+        if not self._api.IsProcessInJob(process, job, ctypes.byref(belongs)):
+            raise _win_error("IsProcessInJob(before root resume)")
+        if not belongs.value:
+            raise RingoError("supervisor root is not in the owned Job; refusing resume")
+        result = self._api.WaitForSingleObject(process, 0)
+        if result == 0xFFFFFFFF:
+            raise _win_error("WaitForSingleObject(before root resume)")
+        if result != 258:  # WAIT_TIMEOUT: the owned process is still alive
+            raise RingoError("supervisor root exited before resume")
+        try:
+            native = ctypes.WinDLL("ntdll", use_last_error=True)  # type: ignore[attr-defined]
+            resume = native.NtResumeProcess
+            resume.argtypes = (wintypes.HANDLE,)
+            resume.restype = wintypes.LONG  # signed 32-bit NTSTATUS, not BOOL
+        except (OSError, AttributeError) as exc:
+            raise RingoError(
+                "supervisor NtResumeProcess unavailable; no resume fallback"
+            ) from exc
+        status = int(resume(process))
+        if status != 0:
+            raise RingoError(
+                f"supervisor NtResumeProcess failed: NTSTATUS 0x{status & 0xFFFFFFFF:08X}; "
+                "no resume fallback"
+            )
+
+    def _pids(self) -> list[int]:
+        handle = self._open_handle()
+        capacity = 16
+        header_size = ctypes.sizeof(_JobProcessListHeader)
+        for _ in range(12):
+            size = header_size + capacity * ctypes.sizeof(ctypes.c_size_t)
+            buffer = ctypes.create_string_buffer(size)
+            ok = self._api.QueryInformationJobObject(
+                handle,
+                _JOB_OBJECT_BASIC_PROCESS_ID_LIST,
+                buffer,
+                size,
+                None,
+            )
+            header = _JobProcessListHeader.from_buffer(buffer)
+            if ok:
+                count = int(header.NumberOfProcessIdsInList)
+                if count > capacity or count < int(header.NumberOfAssignedProcesses):
+                    capacity = max(capacity * 2, int(header.NumberOfAssignedProcesses))
+                    continue
+                pids = (ctypes.c_size_t * count).from_buffer(buffer, header_size)
+                return [int(pid) for pid in pids]
+            if ctypes.get_last_error() != _ERROR_MORE_DATA:  # type: ignore[attr-defined]
+                raise _win_error("QueryInformationJobObject(process list)")
+            capacity = max(capacity * 2, int(header.NumberOfAssignedProcesses))
+        raise RingoError("supervisor Job process list did not stabilize")
+
+    def memory_bytes(self) -> int:
+        handle = self._open_handle()
+        total = 0
+        for pid in self._pids():
+            # A Job list snapshot can race exit/PID reuse. Read only a handle
+            # still belonging to THIS Job; never infer membership via parents.
+            process = self._api.OpenProcess(0x0400 | 0x0010, False, pid)
+            if not process:
+                if ctypes.get_last_error() == _ERROR_INVALID_PARAMETER:  # type: ignore[attr-defined]
+                    continue  # exited between the snapshot and OpenProcess
+                raise _win_error("OpenProcess(read Job member RSS)")
+            try:
+                belongs = wintypes.BOOL()
+                if not self._api.IsProcessInJob(process, handle, ctypes.byref(belongs)):
+                    raise _win_error("IsProcessInJob")
+                if not belongs.value:
+                    continue  # reused PID outside our Job
+                counters = _ProcessMemoryCounters()
+                counters.cb = ctypes.sizeof(counters)
+                if not self._api.K32GetProcessMemoryInfo(
+                    process,
+                    ctypes.byref(counters),
+                    ctypes.sizeof(counters),
+                ):
+                    exit_code = wintypes.DWORD()
+                    if (
+                        self._api.GetExitCodeProcess(process, ctypes.byref(exit_code))
+                        and exit_code.value != _STILL_ACTIVE
+                    ):
+                        continue
+                    raise _win_error("GetProcessMemoryInfo(Job member RSS)")
+                total += int(counters.WorkingSetSize)
+            finally:
+                self._api.CloseHandle(process)
+        return total
+
+    def kill(self) -> None:
+        if not self._api.TerminateJobObject(self._open_handle(), 1):
+            raise _win_error("TerminateJobObject")
+
+    def is_empty(self) -> bool:
+        return not self._pids()
+
+    def close(self) -> None:
+        error: RingoError | None = None
+        if self._handle is not None:
+            if self._api.CloseHandle(self._handle):
+                self._handle = None
+            else:
+                error = _win_error("CloseHandle(Job)")
+        if self._root_handle is not None:
+            if self._api.CloseHandle(self._root_handle):
+                self._root_handle = None
+            elif error is None:
+                error = _win_error("CloseHandle(root process)")
+        if error is not None:
+            raise error
+
+
+class _PosixGroup:
+    def __init__(self, pid: int) -> None:
+        try:
+            import psutil
+        except ImportError as exc:
+            raise RingoError(
+                "POSIX supervisor requires the optional ringo-task-queue[supervisor] extra"
+            ) from exc
+        self._ps: Any = psutil
+        self._pgid = pid
+        self._sid = pid
+        self._closed = False
+        self._empty = False
+        try:
+            root = psutil.Process(pid)
+            self._root_created = root.create_time()
+            # These APIs are POSIX-only; the backend is never created on Windows.
+            if os.getpgid(pid) != pid or os.getsid(pid) != pid:  # type: ignore[attr-defined]
+                raise RingoError(
+                    "supervisor child must be started with start_new_session=True"
+                )
+            if not root.is_running():
+                raise RingoError("supervisor child exited before process group capture")
+        except (psutil.Error, OSError) as exc:
+            raise RingoError(
+                f"could not capture supervisor process group: {exc}"
+            ) from exc
+        self._known: dict[int, Any] = {pid: root}
+
+    def _alive(self, process: Any) -> bool:
+        try:
+            # psutil guards signals and is_running() with creation time, not
+            # just kill(pid, 0). Zombies cannot execute or retain descendants.
+            return bool(
+                process.is_running() and process.status() != self._ps.STATUS_ZOMBIE
+            )
+        except (self._ps.NoSuchProcess, self._ps.ZombieProcess):
+            return False
+        except self._ps.Error as exc:
+            raise RingoError(
+                f"could not verify supervisor member identity: {exc}"
+            ) from exc
+
+    def _members(self) -> list[Any]:
+        if self._closed:
+            raise RingoError("supervisor ProcessTree is closed")
+        if self._empty:
+            return []
+        alive = {pid: proc for pid, proc in self._known.items() if self._alive(proc)}
+        anchors = set(alive)
+        candidates: dict[int, Any] = {}
+        # Inspect group/session membership, NOT the current root's children():
+        # reparented members must survive root exit in our ownership model.
+        for pid in self._ps.pids():
+            try:
+                if (
+                    os.getpgid(pid) != self._pgid  # type: ignore[attr-defined]
+                    or os.getsid(pid) != self._sid  # type: ignore[attr-defined]
+                ):
+                    continue
+                process = self._ps.Process(pid)
+                created = process.create_time()
+                if (
+                    os.getpgid(pid) != self._pgid  # type: ignore[attr-defined]
+                    or os.getsid(pid) != self._sid  # type: ignore[attr-defined]
+                ):
+                    continue
+                # Reject a recycled group leader even if our old group was
+                # never observed empty. Do not adopt its unrelated children.
+                if pid == self._pgid and created != self._root_created:
+                    raise RingoError("supervisor process group identity was reused")
+                if created < self._root_created or not self._alive(process):
+                    continue
+                candidates[pid] = process
+            except (ProcessLookupError, self._ps.NoSuchProcess, self._ps.ZombieProcess):
+                continue
+            except (OSError, self._ps.Error) as exc:
+                raise RingoError(
+                    f"could not inspect supervisor process group: {exc}"
+                ) from exc
+        # An anchor must still be the same live identity, not just a PID found
+        # in an earlier snapshot. Without one, a PGID alone proves nothing.
+        anchored = any(
+            pid in candidates
+            and alive[pid].create_time() == candidates[pid].create_time()
+            and self._alive(alive[pid])
+            for pid in anchors
+        )
+        if candidates and not anchored:
+            raise RingoError(
+                "supervisor process group lost its verified identity anchors"
+            )
+        alive.update(candidates)
+        self._known = alive
+        if not alive:
+            self._empty = True  # never re-adopt a subsequently recycled PGID
+        return list(alive.values())
+
+    def memory_bytes(self) -> int:
+        total = 0
+        for process in self._members():
+            try:
+                rss = int(process.memory_info().rss)
+                if self._alive(process):
+                    total += rss
+            except (self._ps.NoSuchProcess, self._ps.ZombieProcess):
+                continue
+            except self._ps.Error as exc:
+                raise RingoError(
+                    f"could not read supervisor member RSS: {exc}"
+                ) from exc
+        return total
+
+    def kill(self) -> None:
+        # Freeze verified identities first, then discover forks made during
+        # enumeration before killing. Never send a raw signal to a reused PGID.
+        stopped: dict[tuple[int, float], Any] = {}
+        try:
+            for _ in range(32):
+                members = self._members()
+                new = [p for p in members if (p.pid, p.create_time()) not in stopped]
+                for process in new:
+                    try:
+                        process.send_signal(signal.SIGSTOP)  # type: ignore[attr-defined]
+                        stopped[(process.pid, process.create_time())] = process
+                    except (self._ps.NoSuchProcess, self._ps.ZombieProcess):
+                        continue
+                    except self._ps.Error as exc:
+                        raise RingoError(
+                            f"could not stop supervisor member for kill: {exc}"
+                        ) from exc
+                # SIGSTOP delivery is asynchronous. A stable PID snapshot alone
+                # is insufficient: verify quiescence before the final rescan.
+                quiescent = True
+                for process in members:
+                    try:
+                        if self._alive(process) and process.status() not in (
+                            self._ps.STATUS_STOPPED,
+                            self._ps.STATUS_TRACING_STOP,
+                        ):
+                            quiescent = False
+                    except (self._ps.NoSuchProcess, self._ps.ZombieProcess):
+                        continue
+                    except self._ps.Error as exc:
+                        raise RingoError(
+                            f"could not verify stopped supervisor member: {exc}"
+                        ) from exc
+                if not new and quiescent:
+                    break
+                time.sleep(0.005)
+            else:
+                raise RingoError(
+                    "supervisor process group did not quiesce during forced cleanup"
+                )
+        finally:
+            # Even when enumeration/permission checks fail, do not leave the
+            # identities we already stopped permanently suspended.
+            error: Exception | None = None
+            for process in stopped.values():
+                try:
+                    process.kill()  # psutil checks creation time before signalling
+                except (self._ps.NoSuchProcess, self._ps.ZombieProcess):
+                    continue
+                except self._ps.Error as exc:
+                    try:
+                        process.send_signal(signal.SIGCONT)  # type: ignore[attr-defined]
+                    except self._ps.Error:
+                        pass
+                    error = RingoError(f"could not kill supervisor member: {exc}")
+            if error is not None:
+                raise error
+
+    def is_empty(self) -> bool:
+        return not self._members()
+
+    def close(self) -> None:
+        self._closed = True
+        self._known.clear()
+
+
+class ProcessTree:
+    """Own resources of an already-created, entrypoint-gated business child.
+
+    ``memory_bytes`` sums RSS (shared pages may be counted more than once).
+    Access/inspection failures raise RingoError, never a fabricated zero/empty.
+    ``close`` is idempotent; on Windows closing the last Job handle also kills
+    members. On POSIX the caller must explicitly kill/wait before close.
+    """
+
+    def __init__(self, pid: int) -> None:
+        if type(pid) is not int or pid <= 0 or pid == os.getpid():
+            raise RingoError("supervisor ProcessTree requires a positive child PID")
+        if os.name == "nt":
+            if pid > 0xFFFFFFFF:
+                raise RingoError("supervisor child PID exceeds the Windows DWORD range")
+            self._backend: _WindowsJob | _PosixGroup = _WindowsJob(pid)
+        else:
+            self._backend = _PosixGroup(pid)
+
+    def resume_root(self) -> None:
+        """Resume an initially suspended Windows root once; a no-op on POSIX.
+
+        The caller must create it with CREATE_SUSPENDED. Any failure requires
+        ordinary kill/wait/close cleanup, never a second or unguarded resume.
+        """
+        if isinstance(self._backend, _WindowsJob):
+            self._backend.resume_root()
+
+    def memory_bytes(self) -> int:
+        return self._backend.memory_bytes()
+
+    def kill(self) -> None:
+        self._backend.kill()
+
+    def wait_empty(self, timeout: float) -> bool:
+        if not math.isfinite(timeout) or timeout < 0:
+            raise ValueError("timeout must be finite and non-negative")
+        deadline = time.monotonic() + timeout
+        while True:
+            if self._backend.is_empty():
+                return True
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return False
+            time.sleep(min(0.025, remaining))
+
+    def close(self) -> None:
+        self._backend.close()
+
+
+__all__ = ["ProcessTree"]