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

ringo_task_queue/_supervisor_child.py

@@ -0,0 +1,91 @@
+"""Private subprocess bootstrap. Use the public ``supervise`` function."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import os
+import socket
+import sys
+import traceback
+
+from ._supervisor_ipc import Channel
+from ._supervisor_policy import SupervisorPolicy, TaskTimeouts
+from ._supervisor_runtime import ChildRuntime
+
+
+def _load(entrypoint: str):
+    module_name, attribute = entrypoint.split(":", 1)
+    result = importlib.import_module(module_name)
+    for name in attribute.split("."):
+        result = getattr(result, name)
+    if not callable(result):
+        raise TypeError("supervisor entrypoint must be callable")
+    inspect.signature(result).bind()
+    return result
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("This is a private supervisor bootstrap.", file=sys.stderr)
+        return 78
+    # Never pass the local channel capability on a command line or leave it in
+    # the environment inherited by browsers/application subprocesses.
+    port = int(os.environ.pop("RINGO_SUPERVISOR_PORT"))
+    token = os.environ.pop("RINGO_SUPERVISOR_TOKEN")
+    generation = os.environ.pop("RINGO_SUPERVISOR_GENERATION")
+    connection = socket.create_connection(("127.0.0.1", port), timeout=30)
+    connection.settimeout(None)
+    channel = Channel(connection)
+    channel.send({"kind": "hello", "token": token, "generation": generation})
+    config = channel.receive(timeout=30)
+    if (
+        config is None
+        or config.get("kind") != "configure"
+        or config.get("generation") != generation
+    ):
+        channel.close()
+        return 78
+    # The parent has assigned the Job before allowing *any application import*.
+    # Only shared-local's explicit launch path is allowed to break away.
+    if config.get("windows_job"):
+        os.environ["RINGO_SUPERVISOR_JOB"] = "1"
+    else:
+        os.environ.pop("RINGO_SUPERVISOR_JOB", None)
+    runtime = ChildRuntime(
+        channel,
+        SupervisorPolicy._from_wire(config["policy"]),
+        TaskTimeouts._from_wire(config["task_timeouts"]),
+    )
+    runtime.start()
+    ready = False
+    try:
+        try:
+            function = _load(sys.argv[1])
+        except Exception:  # noqa: BLE001 - Arbitrary application imports fail closed.
+            traceback.print_exc()
+            channel.send({"kind": "fatal", "reason": "invalid_entrypoint"})
+            return 78
+        channel.send({"kind": "ready"})
+        ready = True
+        return runtime.invoke(function)
+    except SystemExit as exc:
+        if not ready:
+            channel.send({"kind": "fatal", "reason": "entrypoint_import_exited"})
+            return 78
+        code = exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
+        channel.send({"kind": "entrypoint_done", "exit_code": code})
+        return code
+    except BaseException:  # noqa: BLE001 - Final subprocess/application boundary.
+        traceback.print_exc()
+        try:
+            channel.send({"kind": "entrypoint_failed"})
+        except OSError:
+            pass
+        return 1
+    finally:
+        runtime.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ringo_task_queue/_supervisor_ipc.py

@@ -0,0 +1,81 @@
+"""Private, bounded same-host supervision channel (not a queue protocol)."""
+
+from __future__ import annotations
+
+import json
+import select
+import socket
+import threading
+import time
+from typing import Any
+
+_MAX_FRAME = 256 * 1024
+HEALTH_INTERVAL = 1.0
+_READ_POLL = 0.2
+
+
+class Channel:
+    def __init__(self, connection: socket.socket) -> None:
+        self.socket = connection
+        self._buffer = bytearray()
+        self._write_lock = threading.Lock()
+        self._closed = threading.Event()
+
+    def send(self, message: dict[str, Any]) -> None:
+        data = (
+            json.dumps(message, separators=(",", ":"), allow_nan=False).encode("utf-8")
+            + b"\n"
+        )
+        if len(data) > _MAX_FRAME:
+            raise ValueError("supervisor IPC frame is too large")
+        with self._write_lock:
+            if self._closed.is_set():
+                raise OSError("supervisor IPC channel is closed")
+            self.socket.sendall(data)
+
+    def receive(self, *, timeout: float | None = None) -> dict[str, Any] | None:
+        # Exactly one reader owns this buffer. Avoid socket.makefile(): closing
+        # its BufferedReader from another thread can wait forever for readline's
+        # lock on Windows, even after socket.shutdown(). A raw socket has no
+        # hidden file reference/lock, and polling makes local close bounded.
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while not self._closed.is_set():
+            newline = self._buffer.find(b"\n")
+            if newline >= 0:
+                if newline + 1 > _MAX_FRAME:
+                    raise ValueError("invalid supervisor IPC frame length")
+                data = bytes(self._buffer[:newline])
+                del self._buffer[: newline + 1]
+                value = json.loads(data)
+                if not isinstance(value, dict):
+                    # The value is malformed wire data, not a Python argument.
+                    raise ValueError("supervisor IPC frame must be an object")
+                return value
+            if len(self._buffer) >= _MAX_FRAME:
+                raise ValueError("invalid supervisor IPC frame length")
+            wait = _READ_POLL
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError("supervisor IPC receive timed out")
+                wait = min(wait, remaining)
+            readable, _, _ = select.select([self.socket], [], [], wait)
+            if not readable:
+                continue
+            data = self.socket.recv(min(8192, _MAX_FRAME - len(self._buffer)))
+            if not data:
+                if self._buffer:
+                    raise ValueError("incomplete supervisor IPC frame")
+                return None
+            self._buffer.extend(data)
+        return None
+
+    def close(self) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        try:
+            self.socket.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        self.socket.close()

ringo_task_queue/_supervisor_policy.py

@@ -0,0 +1,182 @@
+"""Validated, immutable configuration for opt-in process supervision."""
+
+from __future__ import annotations
+
+# Declarative policy validation consistently raises ValueError for bad inputs.
+# ruff: noqa: TRY004
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import timedelta
+from types import MappingProxyType
+from typing import Any
+
+
+def _seconds(value: timedelta | None, name: str, *, zero: bool = False) -> float | None:
+    if value is None:
+        return None
+    if not isinstance(value, timedelta):
+        raise ValueError(f"{name} must be a timedelta or None")
+    seconds = value.total_seconds()
+    if not math.isfinite(seconds) or seconds < 0 or (seconds == 0 and not zero):
+        raise ValueError(f"{name} must be {'nonnegative' if zero else 'positive'}")
+    return seconds
+
+
+@dataclass(frozen=True)
+class TaskTimeouts:
+    """Business execution budgets, excluding queueing and terminal receipts.
+
+    ``by_type`` overrides only ``default``; an explicit ``None`` disables that
+    type's execution budget. A Worker-provided object replaces the inherited
+    object in full. Progress monitoring is opt-in and arms only after a real
+    application progress mark; lease renewal is never business progress.
+    """
+
+    default: timedelta | None = None
+    by_type: Mapping[str, timedelta | None] = field(default_factory=dict)
+    progress_timeout: timedelta | None = None
+    cancel_grace: timedelta = timedelta(seconds=5)
+
+    def __post_init__(self) -> None:
+        _seconds(self.default, "default")
+        _seconds(self.progress_timeout, "progress_timeout")
+        _seconds(self.cancel_grace, "cancel_grace", zero=True)
+        if self.cancel_grace is None:
+            raise ValueError("cancel_grace must be a timedelta")
+        if not isinstance(self.by_type, Mapping):
+            raise ValueError("by_type must be a mapping")
+        values = dict(self.by_type)
+        for key, value in values.items():
+            if not isinstance(key, str) or not key:
+                raise ValueError("by_type keys must be nonempty task-type strings")
+            _seconds(value, f"by_type[{key!r}]")
+        object.__setattr__(self, "by_type", MappingProxyType(values))
+
+    def for_type(self, task_type: str) -> timedelta | None:
+        return self.by_type.get(task_type, self.default)
+
+    @property
+    def enabled(self) -> bool:
+        return (
+            self.default is not None
+            or any(value is not None for value in self.by_type.values())
+            or self.progress_timeout is not None
+        )
+
+    def _to_wire(self) -> dict:
+        return {
+            "default": _seconds(self.default, "default"),
+            "by_type": {
+                key: _seconds(value, key) for key, value in self.by_type.items()
+            },
+            "progress_timeout": _seconds(self.progress_timeout, "progress_timeout"),
+            "cancel_grace": _seconds(self.cancel_grace, "cancel_grace", zero=True),
+        }
+
+    @classmethod
+    def _from_wire(cls, value: dict) -> TaskTimeouts:
+        def duration(seconds):
+            return None if seconds is None else timedelta(seconds=seconds)
+
+        return cls(
+            default=duration(value["default"]),
+            by_type={
+                key: duration(seconds) for key, seconds in value["by_type"].items()
+            },
+            progress_timeout=duration(value["progress_timeout"]),
+            cancel_grace=timedelta(seconds=value["cancel_grace"]),
+        )
+
+
+@dataclass(frozen=True)
+class SupervisorPolicy:
+    """Process policy; destructive resource/time thresholds are opt-in.
+
+    RSS is a sampled, approximate sum for the owned process tree, not a kernel
+    hard allocation limit. No-start detection is heuristic under competing
+    consumers, so it only warns unless ``restart_on_stall`` is explicit.
+    Planned recycling neither consumes nor clears the fault-restart budget.
+    """
+
+    recycle_after: timedelta | None = None
+    soft_rss_bytes: int | None = None
+    max_rss_bytes: int | None = None
+    rss_grace: timedelta = timedelta(seconds=30)
+    shutdown_grace: timedelta = timedelta(seconds=30)
+    startup_timeout: timedelta = timedelta(seconds=30)
+    heartbeat_timeout: timedelta | None = None
+    no_start_timeout: timedelta | None = None
+    restart_on_stall: bool = False
+    max_restarts: int = 5
+    restart_window: timedelta = timedelta(minutes=10)
+
+    def __post_init__(self) -> None:
+        for name in ("recycle_after", "heartbeat_timeout", "no_start_timeout"):
+            _seconds(getattr(self, name), name)
+        for name in (
+            "rss_grace",
+            "shutdown_grace",
+            "startup_timeout",
+            "restart_window",
+        ):
+            value = getattr(self, name)
+            if value is None:
+                raise ValueError(f"{name} must be a timedelta")
+            _seconds(value, name, zero=name in ("rss_grace", "shutdown_grace"))
+        for name in ("soft_rss_bytes", "max_rss_bytes"):
+            value = getattr(self, name)
+            if value is not None and (
+                isinstance(value, bool) or not isinstance(value, int) or value <= 0
+            ):
+                raise ValueError(f"{name} must be a positive integer or None")
+        if (
+            self.soft_rss_bytes is not None
+            and self.max_rss_bytes is not None
+            and self.soft_rss_bytes >= self.max_rss_bytes
+        ):
+            raise ValueError("soft_rss_bytes must be smaller than max_rss_bytes")
+        if not isinstance(self.restart_on_stall, bool):
+            raise ValueError("restart_on_stall must be a boolean")
+        if self.restart_on_stall and self.no_start_timeout is None:
+            raise ValueError("restart_on_stall requires no_start_timeout")
+        if (
+            isinstance(self.max_restarts, bool)
+            or not isinstance(self.max_restarts, int)
+            or self.max_restarts < 0
+        ):
+            raise ValueError("max_restarts must be a nonnegative integer")
+
+    def _to_wire(self) -> dict:
+        return {
+            "recycle_after": _seconds(self.recycle_after, "recycle_after"),
+            "soft_rss_bytes": self.soft_rss_bytes,
+            "max_rss_bytes": self.max_rss_bytes,
+            "rss_grace": self.rss_grace.total_seconds(),
+            "shutdown_grace": self.shutdown_grace.total_seconds(),
+            "startup_timeout": self.startup_timeout.total_seconds(),
+            "heartbeat_timeout": _seconds(self.heartbeat_timeout, "heartbeat_timeout"),
+            "no_start_timeout": _seconds(self.no_start_timeout, "no_start_timeout"),
+            "restart_on_stall": self.restart_on_stall,
+            "max_restarts": self.max_restarts,
+            "restart_window": self.restart_window.total_seconds(),
+        }
+
+    @classmethod
+    def _from_wire(cls, value: dict) -> SupervisorPolicy:
+        duration_names = {
+            "recycle_after",
+            "rss_grace",
+            "shutdown_grace",
+            "startup_timeout",
+            "heartbeat_timeout",
+            "no_start_timeout",
+            "restart_window",
+        }
+        arguments: dict[str, Any] = {
+            key: (None if item is None else timedelta(seconds=item))
+            if key in duration_names
+            else item
+            for key, item in value.items()
+        }
+        return cls(**arguments)