Use suspend-aware BOOTTIME waits and owned-container cleanup without changing the workload. Reject missing coverage and preserve producer/report failures. Include runtime/helper regressions, constrained build-job support and live exec-guard crash safety. Document the failed live/idle gates without relaxing thresholds or claiming production acceptance.
143 lines
5.3 KiB
Python
143 lines
5.3 KiB
Python
"""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)
|