ringo-task-queue 0.1.0.dev5__py3-none-win_amd64.whl → 0.1.0.dev7__py3-none-win_amd64.whl

ringo_task_queue/shared.py

@@ -1,305 +1,307 @@
-"""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 time
-from pathlib import Path
-from typing import 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
-        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
-        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
-        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 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: asyncio.subprocess.Process | 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 = (
-                {"creationflags": subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP}
-                if os.name == "nt" else {"start_new_session": True}
-            )
-            self._launcher = await asyncio.create_subprocess_exec(
-                *command,
-                stdin=asyncio.subprocess.DEVNULL,
-                stdout=asyncio.subprocess.DEVNULL,
-                stderr=asyncio.subprocess.DEVNULL,
-                **detach,
-            )
-        except OSError as exc:
-            raise RingoError(f"failed to spawn shared daemon {binary}: {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"]
+"""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 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 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: asyncio.subprocess.Process | 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]
+                if os.name == "nt" else {"start_new_session": True}
+            )
+            self._launcher = await asyncio.create_subprocess_exec(
+                *command,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+                **detach,
+            )
+        except OSError as exc:
+            raise RingoError(f"failed to spawn shared daemon {binary}: {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"]