"""Linux-only, event-driven BOOTTIME deadlines for trusted KPI subprocesses. Python 3.12+; timerfd via libc avoids adding a dependency to the Ubuntu image. Not a sandbox/wake alarm: cancellation is observable on next scheduling after resume. Only callers' own child process groups may be stopped. """ import ctypes import errno import math import os import selectors import signal import subprocess import tempfile import time from contextlib import ExitStack class Timespec(ctypes.Structure): _fields_ = [("seconds", ctypes.c_long), ("nanoseconds", ctypes.c_long)] class Itimerspec(ctypes.Structure): _fields_ = [("interval", Timespec), ("value", Timespec)] def boot(): return time.clock_gettime(time.CLOCK_BOOTTIME) def clocks(): return {"realtime_ns": time.time_ns(), "monotonic_ns": time.monotonic_ns(), "boottime_ns": time.clock_gettime_ns(time.CLOCK_BOOTTIME)} def seconds(value): value = float(value) if not math.isfinite(value) or not 0 < value <= 3600: raise ValueError("duration must be finite, positive and <=3600 seconds") return value def timestamp_value(value): ns = int(value * 1_000_000_000) return Timespec(ns // 1_000_000_000, ns % 1_000_000_000) class Timer: def __init__(self, deadline, interval: float = 0): if ctypes.sizeof(ctypes.c_long) != 8: raise OSError("KPI timer ABI requires Linux with 64-bit long") if not math.isfinite(deadline) or not 0 < deadline <= boot() + 3600 or not math.isfinite(interval) or interval < 0: raise ValueError("invalid absolute BOOTTIME timer") spec = Itimerspec(timestamp_value(interval), timestamp_value(deadline)) libc = ctypes.CDLL(None, use_errno=True) create = libc.timerfd_create create.argtypes = [ctypes.c_int, ctypes.c_int] create.restype = ctypes.c_int arm = libc.timerfd_settime arm.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.POINTER(Itimerspec), ctypes.c_void_p] arm.restype = ctypes.c_int self.fd = create(time.CLOCK_BOOTTIME, os.O_NONBLOCK | os.O_CLOEXEC) if self.fd < 0: raise OSError(ctypes.get_errno(), "timerfd_create") if arm(self.fd, 1, ctypes.byref(spec), None) < 0: # TFD_TIMER_ABSTIME error = ctypes.get_errno() os.close(self.fd) raise OSError(error, "timerfd_settime") def close(self): os.close(self.fd) def until(deadline, process=None, tick=None, interval: float = 2, deadline_is_error=True): """Return child's exit code, or None when a phase timer elapses. No periodic process polling. A pidfd and BOOTTIME timerfds drive epoll. Tick callbacks must themselves be bounded (all KPI CLI calls are). """ if deadline <= boot(): if process is not None and deadline_is_error: raise subprocess.TimeoutExpired(process.args, 0) return None with ExitStack() as stack: selector = stack.enter_context(selectors.DefaultSelector()) timer = Timer(deadline) stack.callback(timer.close) selector.register(timer.fd, selectors.EVENT_READ, "deadline") if process is not None: code = process.poll() if code is not None: return code pidfd = os.pidfd_open(process.pid) stack.callback(os.close, pidfd) selector.register(pidfd, selectors.EVENT_READ, "child") if tick is not None: ticker = Timer(boot() + interval, interval) stack.callback(ticker.close) selector.register(ticker.fd, selectors.EVENT_READ, "tick") while True: events = selector.select() if not events: raise OSError(errno.EINTR, "event wait returned no events") if boot() >= deadline or any(key.data == "deadline" for key, _ in events): if process is not None and deadline_is_error: raise subprocess.TimeoutExpired(process.args, 0) return None if any(key.data == "child" for key, _ in events): assert process is not None return process.wait() # readable pidfd: already exited if tick is not None: for key, _ in events: if key.data == "tick": os.read(key.fd, 8) tick() def stop(process): if process.poll() is None: try: os.killpg(process.pid, signal.SIGKILL) except ProcessLookupError: process.poll() # exit race; collect status below return until(boot() + 2, process) def capture(command, timeout: float = 5): """Small trusted metadata commands only; output is bounded after exit.""" duration = seconds(timeout) with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err: process = subprocess.Popen(command, stdout=out, stderr=err, start_new_session=True) try: code = until(boot() + duration, process) except BaseException: stop(process) raise out.seek(0) err.seek(0) stdout, stderr = out.read(1_048_577), err.read(1_048_577) if len(stdout) > 1_048_576 or len(stderr) > 1_048_576: raise ValueError("metadata output exceeds 1MiB cap") assert code is not None return subprocess.CompletedProcess(command, code, stdout, stderr)