prizmkit 1.1.100 → 1.1.101

package/bundled/dev-pipeline/prizmkit_runtime/processes.py

@@ -0,0 +1,373 @@
+"""Process and daemon lifecycle primitives."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ProcessSpec:
+    """Portable process launch specification for runtime porting."""
+
+    command: tuple[str, ...]
+    cwd: Path
+    environment_overrides: Mapping[str, str] = field(default_factory=dict)
+    environment_unsets: tuple[str, ...] = ()
+    stdout_log: Path | None = None
+    stderr_log: Path | None = None
+    pid_file: Path | None = None
+    stdin_text: str | None = None
+    start_new_process_group: bool = True
+
+
+@dataclass(frozen=True)
+class ProcessHandle:
+    """Observed lifecycle state for a described or launched process."""
+
+    pid: int | None
+    spec: ProcessSpec
+    status: str
+    return_code: int | None = None
+    popen: subprocess.Popen[str] | None = field(default=None, compare=False, repr=False)
+
+
+@dataclass(frozen=True)
+class ProcessTerminationResult:
+    """Best-effort process tree termination result."""
+
+    pid: int | None
+    reason: str
+    terminated: bool
+    forced: bool
+    return_code: int | None
+    details: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ProcessRunResult:
+    """Completed process execution result."""
+
+    handle: ProcessHandle
+    stdout: str
+    stderr: str
+    return_code: int | None
+    timed_out: bool
+    termination: ProcessTerminationResult | None = None
+
+
+def _creationflags_for_platform(start_new_process_group: bool) -> int:
+    if os.name != "nt" or not start_new_process_group:
+        return 0
+    flags = 0
+    flags |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    return flags
+
+
+def _preexec_fn_for_platform(start_new_process_group: bool):
+    if os.name == "nt" or not start_new_process_group:
+        return None
+    return os.setsid
+
+
+def _process_env(overrides: Mapping[str, str], unsets: Sequence[str] = ()) -> dict[str, str]:
+    env = dict(os.environ)
+    for key in unsets:
+        env.pop(str(key), None)
+    env.update({str(key): str(value) for key, value in overrides.items()})
+    return env
+
+
+def launch_process(
+    spec: ProcessSpec,
+    *,
+    stdout=subprocess.PIPE,
+    stderr=subprocess.PIPE,
+    stdin=subprocess.PIPE,
+    text: bool = True,
+) -> ProcessHandle:
+    """Launch a child process with POSIX group or Windows process flags."""
+    spec.cwd.mkdir(parents=True, exist_ok=True)
+    process = subprocess.Popen(
+        [str(part) for part in spec.command],
+        cwd=spec.cwd,
+        env=_process_env(spec.environment_overrides, spec.environment_unsets),
+        stdin=stdin,
+        stdout=stdout,
+        stderr=stderr,
+        text=text,
+        preexec_fn=_preexec_fn_for_platform(spec.start_new_process_group),
+        creationflags=_creationflags_for_platform(spec.start_new_process_group),
+    )
+    if spec.pid_file is not None:
+        spec.pid_file.parent.mkdir(parents=True, exist_ok=True)
+        spec.pid_file.write_text(f"{process.pid}\n", encoding="utf-8")
+    return ProcessHandle(pid=process.pid, spec=spec, status="running", popen=process)
+
+
+def is_process_running(handle: ProcessHandle) -> bool:
+    """Return true when the process appears alive."""
+    if handle.popen is not None:
+        return handle.popen.poll() is None
+    if handle.pid is None:
+        return False
+    try:
+        os.kill(handle.pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+def terminate_process_tree(
+    handle: ProcessHandle,
+    reason: str,
+    grace_seconds: float = 10.0,
+) -> ProcessTerminationResult:
+    """Terminate a process tree without relying on shell runtime logic.
+
+    POSIX uses the process group created at launch. Windows uses taskkill-style
+    tree termination when available. Both paths are best effort and safe for
+    tests with short-lived fake processes.
+    """
+    pid = handle.pid
+    if pid is None:
+        return ProcessTerminationResult(pid=None, reason=reason, terminated=False, forced=False, return_code=None)
+
+    details: list[str] = []
+    forced = False
+    process = handle.popen
+
+    if os.name == "nt":
+        completed = subprocess.run(
+            ["taskkill", "/PID", str(pid), "/T", "/F"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+        details.append(f"taskkill_exit={completed.returncode}")
+        forced = True
+    else:
+        try:
+            os.killpg(pid, signal.SIGTERM)
+            details.append("sigterm_process_group")
+        except ProcessLookupError:
+            pass
+        except OSError as exc:
+            details.append(f"sigterm_group_failed={type(exc).__name__}")
+            try:
+                os.kill(pid, signal.SIGTERM)
+                details.append("sigterm_process")
+            except OSError as inner:
+                details.append(f"sigterm_process_failed={type(inner).__name__}")
+
+        deadline = time.monotonic() + max(0.0, grace_seconds)
+        while process is not None and process.poll() is None and time.monotonic() < deadline:
+            time.sleep(0.05)
+        if process is not None and process.poll() is None:
+            forced = True
+            try:
+                os.killpg(pid, signal.SIGKILL)
+                details.append("sigkill_process_group")
+            except ProcessLookupError:
+                pass
+            except OSError as exc:
+                details.append(f"sigkill_group_failed={type(exc).__name__}")
+                try:
+                    os.kill(pid, signal.SIGKILL)
+                    details.append("sigkill_process")
+                except OSError as inner:
+                    details.append(f"sigkill_process_failed={type(inner).__name__}")
+
+    return_code = None
+    if process is not None:
+        try:
+            return_code = process.wait(timeout=max(0.1, grace_seconds))
+        except subprocess.TimeoutExpired:
+            return_code = process.poll()
+    return ProcessTerminationResult(
+        pid=pid,
+        reason=reason,
+        terminated=True,
+        forced=forced,
+        return_code=return_code,
+        details=tuple(details),
+    )
+
+
+def is_pid_running(pid: int | None) -> bool:
+    """Return true when a PID appears alive."""
+    if pid is None or pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    if os.name != "nt":
+        try:
+            waited_pid, _status = os.waitpid(pid, os.WNOHANG)
+        except ChildProcessError:
+            return True
+        except OSError:
+            return True
+        if waited_pid == pid:
+            return False
+    return True
+
+
+def terminate_pid_tree(
+    pid: int | None,
+    reason: str,
+    grace_seconds: float = 10.0,
+) -> ProcessTerminationResult:
+    """Terminate a PID-backed process tree without requiring a live Popen.
+
+    Daemon stop commands reconstruct process state from a PID file, so the
+    original ``subprocess.Popen`` object is not available. POSIX daemons are
+    launched in a process group whose id is the daemon PID; Windows uses the
+    same taskkill-style tree termination strategy as ``terminate_process_tree``.
+    """
+    if pid is None or pid <= 0:
+        return ProcessTerminationResult(pid=pid, reason=reason, terminated=False, forced=False, return_code=None)
+
+    details: list[str] = []
+    forced = False
+    if not is_pid_running(pid):
+        return ProcessTerminationResult(pid=pid, reason=reason, terminated=False, forced=False, return_code=None, details=("not_running",))
+
+    if os.name == "nt":
+        completed = subprocess.run(
+            ["taskkill", "/PID", str(pid), "/T", "/F"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+        details.append(f"taskkill_exit={completed.returncode}")
+        return ProcessTerminationResult(
+            pid=pid,
+            reason=reason,
+            terminated=completed.returncode == 0,
+            forced=True,
+            return_code=None,
+            details=tuple(details),
+        )
+
+    try:
+        os.killpg(pid, signal.SIGTERM)
+        details.append("sigterm_process_group")
+    except ProcessLookupError:
+        pass
+    except OSError as exc:
+        details.append(f"sigterm_group_failed={type(exc).__name__}")
+        try:
+            os.kill(pid, signal.SIGTERM)
+            details.append("sigterm_process")
+        except OSError as inner:
+            details.append(f"sigterm_process_failed={type(inner).__name__}")
+
+    deadline = time.monotonic() + max(0.0, grace_seconds)
+    while is_pid_running(pid) and time.monotonic() < deadline:
+        time.sleep(0.05)
+
+    if is_pid_running(pid):
+        forced = True
+        try:
+            os.killpg(pid, signal.SIGKILL)
+            details.append("sigkill_process_group")
+        except ProcessLookupError:
+            pass
+        except OSError as exc:
+            details.append(f"sigkill_group_failed={type(exc).__name__}")
+            try:
+                os.kill(pid, signal.SIGKILL)
+                details.append("sigkill_process")
+            except OSError as inner:
+                details.append(f"sigkill_process_failed={type(inner).__name__}")
+
+        deadline = time.monotonic() + max(0.0, min(grace_seconds, 2.0))
+        while is_pid_running(pid) and time.monotonic() < deadline:
+            time.sleep(0.05)
+
+    return ProcessTerminationResult(
+        pid=pid,
+        reason=reason,
+        terminated=not is_pid_running(pid),
+        forced=forced,
+        return_code=None,
+        details=tuple(details),
+    )
+
+
+
+def run_process_with_capture(
+    spec: ProcessSpec,
+    *,
+    timeout_seconds: float | None = None,
+    grace_seconds: float = 10.0,
+) -> ProcessRunResult:
+    """Run a process to completion and terminate on total timeout."""
+    handle = launch_process(spec)
+    assert handle.popen is not None
+    try:
+        stdout, stderr = handle.popen.communicate(input=spec.stdin_text, timeout=timeout_seconds)
+        return ProcessRunResult(
+            handle=ProcessHandle(
+                pid=handle.pid,
+                spec=spec,
+                status="completed",
+                return_code=handle.popen.returncode,
+                popen=handle.popen,
+            ),
+            stdout=stdout or "",
+            stderr=stderr or "",
+            return_code=handle.popen.returncode,
+            timed_out=False,
+        )
+    except subprocess.TimeoutExpired:
+        termination = terminate_process_tree(handle, "timeout", grace_seconds=grace_seconds)
+        stdout = ""
+        stderr = ""
+        if handle.popen is not None:
+            try:
+                captured = handle.popen.communicate(timeout=1)
+                stdout = captured[0] or ""
+                stderr = captured[1] or ""
+            except subprocess.TimeoutExpired:
+                pass
+        return ProcessRunResult(
+            handle=ProcessHandle(
+                pid=handle.pid,
+                spec=spec,
+                status="timeout",
+                return_code=termination.return_code,
+                popen=handle.popen,
+            ),
+            stdout=stdout,
+            stderr=stderr,
+            return_code=termination.return_code,
+            timed_out=True,
+            termination=termination,
+        )
+
+
+def platform_termination_strategy() -> tuple[str, ...]:
+    """Expose the structural termination strategy for tests/diagnostics."""
+    if os.name == "nt":
+        return ("CREATE_NEW_PROCESS_GROUP", "taskkill /PID <pid> /T /F")
+    return ("setsid", "killpg(SIGTERM)", "killpg(SIGKILL)")
+
+
+def describe_command(command: Sequence[str]) -> str:
+    """Return a deterministic command description for tests."""
+    return " ".join(str(part) for part in command)