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

ringo_task_queue/shared.py

@@ -0,0 +1,359 @@
+"""Discovery and lifecycle helpers for opt-in shared local SQLite daemons."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import stat
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Any, cast
+
+from ._version import (
+    PROTOCOL_MAJOR,
+    PROTOCOL_MINOR,
+    SCHEMA_VERSION,
+    daemon_version_for_sdk,
+)
+from .daemon import _probe_binary_version, _resolve_daemon
+from .errors import IncompatibleVersionError, RingoError, UnavailableError
+
+_MAX_STATE_BYTES = 64 * 1024
+_STATE_NAME = "shared-daemon.json"
+_HEX_GENERATION = re.compile(r"^[0-9a-f]{32}$")
+_HEX_TOKEN = re.compile(r"^[0-9a-f]{64}$")
+_ENDPOINT = re.compile(r"^127\.0\.0\.1:(\d+)$")
+
+
+def _pid_alive(pid: int) -> bool:
+    """Probe existence without sending a console control event on Windows."""
+    if pid <= 0:
+        return False
+    if os.name == "nt" and pid > 0xFFFFFFFF:
+        return False
+    if os.name == "nt":
+        import ctypes
+        from ctypes import wintypes
+
+        synchronize = 0x00100000
+        query_limited_information = 0x1000
+        still_active = 259
+        access_denied = 5
+        # Typeshed omits Win32-only attributes on Linux, but this branch only
+        # executes on Windows. Keep the runtime API calls unchanged.
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+        kernel32.OpenProcess.argtypes = (wintypes.DWORD, wintypes.BOOL, wintypes.DWORD)
+        kernel32.OpenProcess.restype = wintypes.HANDLE
+        kernel32.GetExitCodeProcess.argtypes = (wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD))
+        kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+        kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
+        kernel32.CloseHandle.restype = wintypes.BOOL
+        handle = kernel32.OpenProcess(
+            synchronize | query_limited_information, False, pid
+        )
+        if not handle:
+            return ctypes.get_last_error() == access_denied  # type: ignore[attr-defined]
+        try:
+            exit_code = wintypes.DWORD()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+                return False
+            return exit_code.value == still_active
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)  # POSIX only: Windows zero is CTRL_C_EVENT.
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _read_private(path: Path) -> bytes | None:
+    """Read a bounded regular file without following symlinks where supported."""
+    try:
+        if path.is_symlink():
+            return None
+        flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+        fd = os.open(path, flags)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > _MAX_STATE_BYTES:
+                return None
+            if os.name != "nt" and stat.S_IMODE(info.st_mode) != 0o600:
+                return None
+            data = os.read(fd, _MAX_STATE_BYTES + 1)
+        finally:
+            os.close(fd)
+        if len(data) > _MAX_STATE_BYTES:
+            return None
+        return data
+    except (OSError, ValueError):
+        return None
+
+
+def validate_shared_state(value: object) -> dict[str, object] | None:
+    """Validate the daemon's published state before trusting any endpoint/token."""
+    if not isinstance(value, dict):
+        return None
+    required = {
+        "format", "endpoint", "pid", "generation", "token", "version",
+        "protocolMajor", "protocolMinor", "schemaVersion",
+    }
+    if set(value) != required:
+        return None
+    if value["format"] != 1:
+        return None
+    endpoint = value["endpoint"]
+    match = _ENDPOINT.fullmatch(endpoint) if isinstance(endpoint, str) else None
+    if match is None or not 1 <= int(match.group(1)) <= 65535:
+        return None
+    pid = value["pid"]
+    if type(pid) is not int or pid <= 0:
+        return None
+    generation = value["generation"]
+    token = value["token"]
+    if not isinstance(generation, str) or _HEX_GENERATION.fullmatch(generation) is None:
+        return None
+    if not isinstance(token, str) or _HEX_TOKEN.fullmatch(token) is None:
+        return None
+    if value["version"] != daemon_version_for_sdk():
+        return None
+    if value["protocolMajor"] != PROTOCOL_MAJOR or value["protocolMinor"] != PROTOCOL_MINOR:
+        return None
+    if value["schemaVersion"] != SCHEMA_VERSION:
+        return None
+    return value
+
+
+class _DetachedProcess:
+    """Observe a shared child without giving an event loop kill ownership.
+
+    asyncio subprocess transports kill running children when finalized. A
+    shared daemon must instead outlive its launcher's loop, object and process.
+    The daemon reaper retains Popen until natural exit, reaping POSIX zombies
+    without joining the interpreter or its default asyncio executor.
+    """
+
+    def __init__(self, process: subprocess.Popen[bytes]) -> None:
+        self._process = process
+        threading.Thread(
+            target=process.wait,
+            name=f"ringo-shared-reaper-{process.pid}",
+            daemon=True,
+        ).start()
+
+    @classmethod
+    def spawn(cls, command: list[str], **options: Any) -> _DetachedProcess:
+        return cls(subprocess.Popen(command, **options))
+
+    @property
+    def pid(self) -> int:
+        return self._process.pid
+
+    @property
+    def returncode(self) -> int | None:
+        return self._process.poll()
+
+    def kill(self) -> None:
+        # Explicit test/recovery callers still target this exact Popen child.
+        # Neither object finalization nor SharedLocalDaemon.stop calls this.
+        self._process.kill()
+
+    async def wait(self) -> int:
+        while (code := self._process.poll()) is None:
+            await asyncio.sleep(0.05)
+        return code
+
+
+class SharedLocalDaemon:
+    """Discover or start a shared-local daemon without owning its process.
+
+    The Go daemon owns ``daemon.lock`` and publishes ``shared-daemon.json``.
+    This object deliberately never closes stdin, terminates, or kills the child:
+    a shared daemon must outlive any one SDK client.
+    """
+
+    def __init__(
+        self,
+        data_dir: str | os.PathLike[str],
+        *,
+        daemon_path: str | os.PathLike[str] | None = None,
+        startup_timeout: float = 15.0,
+    ) -> None:
+        self.data_dir = Path(data_dir).absolute()
+        self._daemon_path = daemon_path
+        self._startup_timeout = startup_timeout
+        self._launcher: _DetachedProcess | None = None
+        self.endpoint: str | None = None
+        self.token: str | None = None
+        self.generation: str | None = None
+        self.pid: int | None = None
+        self.daemon_version: str | None = None
+        self._rejected_generation: str | None = None
+
+    @property
+    def state_path(self) -> Path:
+        return self.data_dir / _STATE_NAME
+
+    @property
+    def is_dead(self) -> bool:
+        return self.pid is None or not _pid_alive(self.pid)
+
+    def _read_state(self) -> dict[str, object] | None:
+        raw = _read_private(self.state_path)
+        if raw is None:
+            return None
+        try:
+            return validate_shared_state(json.loads(raw.decode("utf-8")))
+        except (UnicodeDecodeError, ValueError):
+            return None
+
+    def _set_state(self, state: dict[str, object]) -> str:
+        self.endpoint = str(state["endpoint"])
+        self.token = str(state["token"])
+        self.generation = str(state["generation"])
+        self.pid = cast(int, state["pid"])
+        self.daemon_version = str(state["version"])
+        return self.endpoint
+
+    def invalidate_current(self) -> None:
+        """Never re-adopt a generation whose authenticated connection failed."""
+        self._rejected_generation = self.generation
+        self.endpoint = None
+        self.pid = None
+        self.token = None
+
+    async def _prepare_directory(self) -> None:
+        """Have the Go binary enforce local file permissions before reading a token."""
+        binary, _ = _resolve_daemon(self._daemon_path)
+        try:
+            process = await asyncio.create_subprocess_exec(
+                str(binary), "shared-local", "--data-dir", str(self.data_dir),
+                "--prepare-dir", stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+            )
+            try:
+                _, stderr = await asyncio.wait_for(
+                    process.communicate(), timeout=max(5.0, self._startup_timeout)
+                )
+            except asyncio.TimeoutError:
+                process.kill()  # targets this child only; never signals a console
+                await process.wait()
+                raise UnavailableError("shared-local directory preparation timed out") from None
+        except OSError as exc:
+            raise RingoError(f"could not verify shared-local directory: {exc}") from exc
+        if process.returncode != 0:
+            raise RingoError(
+                "shared-local directory permissions or discovery are unsafe: "
+                + stderr[:2048].decode("utf-8", errors="replace")
+            )
+
+    async def _launch(self) -> None:
+        binary, metadata = _resolve_daemon(self._daemon_path)
+        info = await _probe_binary_version(
+            binary, self._startup_timeout, allow_legacy=metadata is None
+        )
+        # Match LocalDaemon's release checks without relying on readiness stdout.
+        if info.get("name") != "ringo-task-queue":
+            raise IncompatibleVersionError(f"unexpected daemon name from {binary}")
+        if (
+            info.get("version") != daemon_version_for_sdk()
+            or info.get("protocolMajor") != PROTOCOL_MAJOR
+            or info.get("protocolMinor") != PROTOCOL_MINOR
+            or info.get("schemaVersion") != SCHEMA_VERSION
+        ):
+            raise IncompatibleVersionError(
+                f"daemon at {binary} is incompatible with protocol "
+                f"{PROTOCOL_MAJOR}.{PROTOCOL_MINOR}, schema {SCHEMA_VERSION}"
+            )
+        command = [
+            str(binary), "shared-local", "--data-dir", str(self.data_dir),
+            "--listen", "127.0.0.1:0", "--storage", "sqlite",
+        ]
+        try:
+            # DEVNULL is intentional: no lifecycle stdin and no inherited pipe
+            # can keep either process alive or block after this SDK exits.
+            detach: dict[str, Any] = (
+                {"creationflags": (
+                    subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+                    | (subprocess.CREATE_BREAKAWAY_FROM_JOB  # type: ignore[attr-defined]
+                       if os.environ.get("RINGO_SUPERVISOR_JOB") == "1" else 0)
+                )}
+                if os.name == "nt" else {"start_new_session": True}
+            )
+            # No asyncio transport: its finalizer would kill a still-running
+            # shared daemon when this client/loop is collected or exits.
+            self._launcher = _DetachedProcess.spawn(
+                command,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                close_fds=True,
+                **detach,
+            )
+        except OSError as exc:
+            required = (
+                " (supervisor Job breakaway required; no inherited-Job fallback)"
+                if os.name == "nt" and os.environ.get("RINGO_SUPERVISOR_JOB") == "1" else ""
+            )
+            raise RingoError(f"failed to spawn shared daemon {binary}{required}: {exc}") from exc
+
+    async def _endpoint_reachable(self, endpoint: str) -> bool:
+        try:
+            _host, raw_port = endpoint.rsplit(":", 1)
+            _reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(_host, int(raw_port)), timeout=0.2
+            )
+            writer.close()
+            await writer.wait_closed()
+            return True
+        except (OSError, ValueError, asyncio.TimeoutError):
+            return False
+
+    async def start(self) -> str:
+        """Discover a private endpoint, or boundedly compete to start one writer."""
+        await self._prepare_directory()
+        deadline = time.monotonic() + self._startup_timeout
+        attempts = 0
+        next_attempt = 0.0
+        while time.monotonic() < deadline:
+            state = self._read_state()
+            if state is not None and state["generation"] != self._rejected_generation:
+                # Neither PID nor TCP reachability establishes identity; the
+                # caller must still authenticate AttachLocal and check its ack.
+                if _pid_alive(cast(int, state["pid"])):
+                    endpoint = str(state["endpoint"])
+                    if await self._endpoint_reachable(endpoint):
+                        return self._set_state(state)
+            # Conflict losers wait for the winner instead of spawning ~20
+            # doomed daemon processes per second. A persistent startup fault
+            # has a finite three-attempt budget per call to start().
+            if attempts < 3 and time.monotonic() >= next_attempt and (
+                self._launcher is None or self._launcher.returncode is not None
+            ):
+                attempts += 1
+                await self._launch()
+                next_attempt = time.monotonic() + (0.3 * (2 ** (attempts - 1)))
+            await asyncio.sleep(0.1)
+        # A live/hung lock owner must never be killed or bypassed.
+        raise UnavailableError(
+            f"shared daemon did not publish a usable state within {self._startup_timeout:.1f}s"
+        )
+
+    async def refresh(self) -> str:
+        """Refresh state after generation rotation, or start a replacement."""
+        return await self.start()
+
+    async def stop(self) -> None:
+        """Shared clients never stop the daemon."""
+        return None
+
+
+__all__ = ["SharedLocalDaemon", "validate_shared_state"]