ringo-task-queue 0.1.0.dev0__py3-none-win_amd64.whl

ringo_task_queue/daemon.py

@@ -0,0 +1,507 @@
+"""Lifecycle of the SDK-managed embedded Go daemon (ADR 0003).
+
+The daemon is spawned as an asyncio subprocess in ``embedded`` mode with both
+ownership signals required by the frozen CLI contract: ``--parent-pid`` set to
+the current process and ``--lifecycle-stdin`` with the child's stdin kept
+open for the daemon's whole lifetime. Readiness is a single JSON line on
+stdout carrying the loopback endpoint and protocol version; stderr is
+collected asynchronously into a bounded ring buffer for diagnostics.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import sys
+from collections import deque
+from pathlib import Path
+from typing import Deque, TextIO
+
+from ._version import (
+    PROTOCOL_MAJOR,
+    PROTOCOL_MINOR,
+    SCHEMA_VERSION,
+    daemon_version_for_sdk,
+)
+from .binary import DAEMON_NAME, BinaryMetadata, packaged_binary
+from .errors import ConflictError, IncompatibleVersionError, RingoError
+
+DEFAULT_STARTUP_TIMEOUT = 15.0
+DEFAULT_STOP_TIMEOUT = 10.0
+_STDERR_TAIL_LINES = 200
+_MAX_VERSION_PROBE_OUTPUT = 1024 * 1024
+
+_EXE_NAMES = (
+    ("ringo-task-queue.exe", "ringo-task-queue")
+    if sys.platform == "win32"
+    else (
+        "ringo-task-queue",
+        "ringo-task-queue.exe",
+    )
+)
+
+
+def _resolve_daemon(
+    explicit: str | os.PathLike[str] | None = None,
+) -> tuple[Path, BinaryMetadata | None]:
+    """Resolve a daemon and optional packaged metadata.
+
+    Explicit and environment overrides intentionally win over package
+    resources.  Overrides are development artifacts and therefore have no
+    required manifest; packaged resources are always checksum validated.
+    """
+    if explicit:
+        path = Path(explicit)
+        if not path.is_file() or path.is_symlink():
+            raise RingoError(f"daemon binary is not a regular file: {path}")
+        return path, None
+
+    env = os.environ.get("RINGO_DAEMON_PATH")
+    if env:
+        path = Path(env)
+        if not path.is_file() or path.is_symlink():
+            raise RingoError(f"RINGO_DAEMON_PATH is not a regular file: {path}")
+        return path, None
+
+    # Packaged platform resource (only present in platform wheels).  A
+    # manifest is the marker that this is a platform wheel; malformed or
+    # mismatched package data must fail loudly instead of falling through to a
+    # random development binary.
+    try:
+        from importlib import resources
+
+        package_bin = Path(str(resources.files("ringo_task_queue") / "bin"))
+        if not (package_bin / "manifest.json").is_file():
+            raise FileNotFoundError(package_bin / "manifest.json")
+        return packaged_binary()
+    except (FileNotFoundError, ModuleNotFoundError):
+        pass
+
+    # Development tree: search this file's ancestors for the binary, which
+    # covers both the repo root and ``.tmp/bin`` checkouts.
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        for name in _EXE_NAMES:
+            candidate = parent / name
+            if candidate.is_file():
+                return candidate, None
+        nested = parent / ".tmp" / "bin"
+        for name in _EXE_NAMES:
+            candidate = nested / name
+            if candidate.is_file():
+                return candidate, None
+    raise RingoError(
+        "could not locate the ringo-task-queue daemon binary; pass"
+        " daemon_path=..., set RINGO_DAEMON_PATH, or install a platform wheel"
+    )
+
+
+def resolve_daemon_path(explicit: str | os.PathLike[str] | None = None) -> Path:
+    """Locate and (for packaged resources) verify the daemon binary."""
+    return _resolve_daemon(explicit)[0]
+
+
+async def _read_bounded_probe_stream(
+    stream: asyncio.StreamReader | None,
+) -> bytes:
+    if stream is None:
+        return b""
+    result = bytearray()
+    while chunk := await stream.read(64 * 1024):
+        if len(result) + len(chunk) > _MAX_VERSION_PROBE_OUTPUT:
+            raise IncompatibleVersionError(
+                f"daemon version probe output exceeds {_MAX_VERSION_PROBE_OUTPUT} bytes"
+            )
+        result.extend(chunk)
+    return bytes(result)
+
+
+async def _probe_binary_version(
+    binary: Path, timeout: float, *, allow_legacy: bool = True
+) -> dict[str, object]:
+    """Run the daemon's read-only version contract before spawning it.
+
+    Source-tree development overrides may still use the historical text line.
+    Verified wheel resources must return the release ``version --json`` object.
+    """
+    proc: asyncio.subprocess.Process | None = None
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            str(binary),
+            "version",
+            "--json",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout_task = asyncio.create_task(_read_bounded_probe_stream(proc.stdout))
+        stderr_task = asyncio.create_task(_read_bounded_probe_stream(proc.stderr))
+        stdout, stderr, _ = await asyncio.wait_for(
+            asyncio.gather(stdout_task, stderr_task, proc.wait()), timeout=timeout
+        )
+    except BaseException as exc:
+        if proc is not None and proc.returncode is None:
+            try:
+                proc.kill()
+            except OSError:
+                pass
+            try:
+                await asyncio.shield(asyncio.wait_for(proc.wait(), timeout=5.0))
+            except (asyncio.CancelledError, asyncio.TimeoutError, OSError):
+                pass
+        if isinstance(exc, asyncio.CancelledError):
+            raise
+        if isinstance(exc, (OSError, asyncio.TimeoutError)):
+            raise IncompatibleVersionError(
+                f"cannot probe daemon compatibility at {binary}: {exc}"
+            ) from exc
+        raise
+    if proc.returncode != 0:
+        detail = stderr.decode("utf-8", errors="replace").strip()
+        raise IncompatibleVersionError(
+            f"daemon version probe failed (code {proc.returncode}): {detail}"
+        )
+    try:
+        result = json.loads(stdout.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        if not allow_legacy:
+            raise IncompatibleVersionError(
+                f"packaged daemon version probe returned invalid JSON: {stdout!r}"
+            ) from exc
+        # Development binaries built before the JSON contract may only emit
+        # the documented human-readable line. Preserve source-tree override
+        # compatibility while release wheels fail closed above.
+        legacy = re.fullmatch(
+            r"(?P<name>\S+) (?P<version>\S+) protocol=(?P<major>\d+)\.(?P<minor>\d+) schema=(?P<schema>\d+)(?:.*)",
+            stdout.decode("utf-8", errors="replace").strip(),
+        )
+        if legacy is None:
+            raise IncompatibleVersionError(
+                f"daemon version probe returned invalid JSON: {stdout!r}"
+            ) from exc
+        result = {
+            "name": legacy.group("name"),
+            "version": legacy.group("version"),
+            "protocolMajor": int(legacy.group("major")),
+            "protocolMinor": int(legacy.group("minor")),
+            "schemaVersion": int(legacy.group("schema")),
+        }
+    if not isinstance(result, dict):
+        raise IncompatibleVersionError("daemon version probe returned a non-object")
+    return result
+
+
+class LocalDaemon:
+    """A spawned embedded daemon subprocess owned by this process."""
+
+    def __init__(
+        self,
+        data_dir: str | os.PathLike[str],
+        *,
+        storage: str = "sqlite",
+        postgres_dsn: str | None = None,
+        daemon_path: str | os.PathLike[str] | None = None,
+        startup_timeout: float = DEFAULT_STARTUP_TIMEOUT,
+        stop_timeout: float = DEFAULT_STOP_TIMEOUT,
+    ) -> None:
+        self.data_dir = Path(data_dir)
+        self._storage = storage
+        self._postgres_dsn = postgres_dsn
+        self._daemon_path = daemon_path
+        self._binary_metadata: BinaryMetadata | None = None
+        self._startup_timeout = startup_timeout
+        self._stop_timeout = stop_timeout
+        self._proc: asyncio.subprocess.Process | None = None
+        self._stderr_task: asyncio.Task | None = None
+        self._stderr_tail: Deque[str] = deque(maxlen=_STDERR_TAIL_LINES)
+        self._log_file: TextIO | None = None
+        self.endpoint: str | None = None
+        self.pid: int | None = None
+        self.daemon_version: str | None = None
+
+    @property
+    def is_dead(self) -> bool:
+        proc = self._proc
+        return proc is None or proc.returncode is not None
+
+    @property
+    def stderr_tail(self) -> list[str]:
+        return list(self._stderr_tail)
+
+    async def start(self) -> str:
+        """Spawn the daemon and return its loopback gRPC endpoint."""
+        if self._proc is not None and not self.is_dead:
+            raise RingoError("daemon already started")
+        if self._proc is not None:
+            # A previous daemon died; reap its helpers before respawning.
+            await self._finish_stderr()
+            self._proc = None
+        binary, self._binary_metadata = _resolve_daemon(self._daemon_path)
+        version_info = await _probe_binary_version(
+            binary,
+            self._startup_timeout,
+            allow_legacy=self._binary_metadata is None,
+        )
+        self._validate_version_info(version_info, self._binary_metadata, binary)
+        try:
+            self.data_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise RingoError(
+                f"cannot create data directory {self.data_dir}: {exc}"
+            ) from exc
+
+        command = [
+            str(binary),
+            "embedded",
+            "--data-dir",
+            str(self.data_dir),
+            "--listen",
+            "127.0.0.1:0",
+            "--storage",
+            self._storage,
+            "--parent-pid",
+            str(os.getpid()),
+            "--lifecycle-stdin",
+        ]
+        child_env = None
+        if self._postgres_dsn is not None:
+            child_env = dict(os.environ)
+            child_env["RINGO_POSTGRES_DSN"] = self._postgres_dsn
+        try:
+            self._proc = await asyncio.create_subprocess_exec(
+                *command,
+                env=child_env,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except OSError as exc:
+            raise RingoError(f"failed to spawn daemon {binary}: {exc}") from exc
+
+        try:
+            self._log_file = open(
+                self.data_dir / "ringo-daemon.stderr.log", "a", encoding="utf-8"
+            )
+        except OSError:
+            self._log_file = None
+        self._stderr_task = asyncio.create_task(self._collect_stderr())
+        try:
+            ready = await self._await_ready()
+            endpoint = self._validate_ready(ready)
+            self._validate_binary_compatibility(ready, self._binary_metadata, binary)
+        except BaseException:
+            await self._kill_and_reap()
+            raise
+
+        self.endpoint = endpoint
+        self.pid = ready["pid"]
+        self.daemon_version = ready["version"]
+        return endpoint
+
+    @staticmethod
+    def _validate_ready(ready: object) -> str:
+        """Validate the readiness JSON shape before trusting any field."""
+        if not isinstance(ready, dict):
+            raise RingoError(f"malformed daemon readiness payload: {ready!r}")
+        endpoint = ready.get("endpoint")
+        if not isinstance(endpoint, str) or not endpoint:
+            raise RingoError(f"daemon readiness missing endpoint: {ready!r}")
+        match = re.fullmatch(r"(?:\[([^]]+)\]|([^:]+)):(\d+)", endpoint)
+        host = (match.group(1) or match.group(2)) if match else ""
+        port = int(match.group(3)) if match else 0
+        if host not in ("127.0.0.1", "::1", "localhost") or not 1 <= port <= 65535:
+            raise RingoError(
+                f"embedded daemon must announce a loopback endpoint with a positive port, got {endpoint!r}"
+            )
+        for key in ("pid", "protocolMajor", "protocolMinor", "schemaVersion"):
+            value = ready.get(key)
+            if type(value) is not int or value < 0 or (key == "pid" and value == 0):
+                raise RingoError(
+                    f"daemon readiness field {key!r} is missing or invalid: {ready!r}"
+                )
+        if not isinstance(ready.get("version"), str):
+            raise RingoError(
+                f"daemon readiness field 'version' is missing or not a string: {ready!r}"
+            )
+        return endpoint
+
+    @staticmethod
+    def _validate_version_info(
+        info: dict[str, object], metadata: BinaryMetadata | None, binary: Path
+    ) -> None:
+        if info.get("name") != DAEMON_NAME:
+            raise IncompatibleVersionError(
+                f"unexpected daemon name from {binary}: {info.get('name')!r}"
+            )
+        version = info.get("version")
+        major = info.get("protocolMajor")
+        minor = info.get("protocolMinor")
+        schema = info.get("schemaVersion")
+        if (
+            not isinstance(version, str)
+            or not version
+            or not isinstance(major, int)
+            or not isinstance(minor, int)
+            or not isinstance(schema, int)
+        ):
+            raise IncompatibleVersionError(
+                f"daemon version probe is missing compatibility fields: {info!r}"
+            )
+        expected_version = daemon_version_for_sdk()
+        if version != expected_version:
+            raise IncompatibleVersionError(
+                f"daemon at {binary} reports version {version!r};"
+                f" SDK requires {expected_version!r}"
+            )
+        if major != PROTOCOL_MAJOR or minor != PROTOCOL_MINOR or schema != SCHEMA_VERSION:
+            raise IncompatibleVersionError(
+                f"daemon at {binary} reports protocol {major}.{minor}, schema {schema};"
+                f" SDK requires protocol {PROTOCOL_MAJOR}.{PROTOCOL_MINOR} and schema {SCHEMA_VERSION}"
+            )
+        if metadata is not None and (
+            version != metadata.version
+            or major != metadata.protocol_major
+            or minor != metadata.protocol_minor
+        ):
+            raise IncompatibleVersionError(
+                f"daemon version probe disagrees with manifest for {binary}: {info!r}"
+            )
+
+    @staticmethod
+    def _validate_binary_compatibility(
+        ready: dict, metadata: BinaryMetadata | None, binary: Path
+    ) -> None:
+        """Check readiness against SDK and, when packaged, manifest metadata."""
+        if (
+            ready["protocolMajor"] != PROTOCOL_MAJOR
+            or ready["protocolMinor"] != PROTOCOL_MINOR
+            or ready["schemaVersion"] != SCHEMA_VERSION
+        ):
+            raise IncompatibleVersionError(
+                f"daemon at {binary} speaks protocol {ready['protocolMajor']}.{ready['protocolMinor']}, "
+                f"schema {ready['schemaVersion']}; this SDK requires protocol "
+                f"{PROTOCOL_MAJOR}.{PROTOCOL_MINOR} and schema {SCHEMA_VERSION}"
+            )
+        if metadata is not None:
+            if ready["version"] != metadata.version:
+                raise IncompatibleVersionError(
+                    f"daemon at {binary} reports version {ready['version']!r};"
+                    f" manifest requires {metadata.version!r}"
+                )
+            if (
+                ready["protocolMajor"] != metadata.protocol_major
+                or ready["protocolMinor"] != metadata.protocol_minor
+            ):
+                raise IncompatibleVersionError(
+                    f"daemon at {binary} reports protocol "
+                    f"{ready['protocolMajor']}.{ready['protocolMinor']};"
+                    f" manifest requires {metadata.protocol_major}.{metadata.protocol_minor}"
+                )
+
+    async def _await_ready(self) -> dict:
+        assert self._proc is not None and self._proc.stdout is not None
+        try:
+            line = await asyncio.wait_for(
+                self._proc.stdout.readline(), timeout=self._startup_timeout
+            )
+        except asyncio.TimeoutError as exc:
+            tail = "\n".join(self.stderr_tail[-20:])
+            raise RingoError(
+                f"daemon did not become ready within {self._startup_timeout:.0f}s;"
+                f" stderr tail:\n{tail}"
+            ) from exc
+        if not line:
+            # Process exited before announcing readiness.
+            returncode = await self._proc.wait()
+            if self._stderr_task is not None:
+                await self._stderr_task
+            tail = "\n".join(self.stderr_tail[-20:])
+            message = (
+                f"daemon exited during startup (code {returncode});"
+                f" stderr tail:\n{tail}"
+            )
+            if "conflict:" in tail.lower():
+                raise ConflictError(message)
+            raise RingoError(message)
+        try:
+            return json.loads(line.decode("utf-8", errors="replace"))
+        except ValueError as exc:
+            raise RingoError(f"malformed daemon readiness line: {line!r}") from exc
+
+    async def _collect_stderr(self) -> None:
+        assert self._proc is not None and self._proc.stderr is not None
+        while True:
+            try:
+                line = await self._proc.stderr.readline()
+            except Exception:
+                return
+            if not line:
+                return
+            text = line.decode("utf-8", errors="replace").rstrip("\r\n")
+            self._stderr_tail.append(text)
+            log = self._log_file
+            if log is not None:
+                try:
+                    log.write(text + "\n")
+                    log.flush()
+                except OSError:
+                    pass
+
+    async def stop(self) -> None:
+        """Close the lifecycle pipe and wait for exit, escalating if needed."""
+        proc, self._proc = self._proc, None
+        if proc is None:
+            return
+        if proc.returncode is not None:
+            await self._finish_stderr()
+            return
+        # Closing stdin (the lifecycle pipe) starts the daemon's graceful
+        # shutdown; the daemon owns its own bounded grace period.
+        if proc.stdin is not None:
+            try:
+                proc.stdin.close()
+                await proc.stdin.wait_closed()
+            except (BrokenPipeError, ConnectionResetError, OSError):
+                pass
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=self._stop_timeout)
+        except asyncio.TimeoutError:
+            proc.terminate()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                proc.kill()
+                try:
+                    await asyncio.wait_for(proc.wait(), timeout=5.0)
+                except asyncio.TimeoutError as exc:  # pragma: no cover - OS fault
+                    raise RingoError("daemon did not exit after kill") from exc
+        finally:
+            await self._finish_stderr()
+
+    async def _finish_stderr(self) -> None:
+        task, self._stderr_task = self._stderr_task, None
+        if task is not None:
+            task.cancel()
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):
+                pass
+        log, self._log_file = self._log_file, None
+        if log is not None:
+            try:
+                log.close()
+            except OSError:
+                pass
+
+    async def _kill_and_reap(self) -> None:
+        proc, self._proc = self._proc, None
+        if proc is None:
+            return
+        if proc.returncode is None:
+            proc.kill()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                pass
+        await self._finish_stderr()

ringo_task_queue/errors.py

@@ -0,0 +1,152 @@
+"""Public exception hierarchy for the Ringo Task Queue Python SDK.
+
+All SDK transport failures derive from :class:`RingoError` and carry one of
+the stable public codes from ``docs/contracts/errors.md``. gRPC status
+details (``ringo.v1.ErrorDetail``) are preferred over the coarser gRPC code,
+exactly as the error contract requires.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+import grpc
+from grpc_status import rpc_status
+
+from ._proto.ringo.v1 import queue_pb2
+
+
+class RingoError(Exception):
+    """Base class for every SDK-raised transport/protocol error."""
+
+    #: Stable public code (see docs/contracts/errors.md).
+    code = "INTERNAL"
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        request_id: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        grpc_code: grpc.StatusCode | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request_id = request_id
+        self.metadata = dict(metadata) if metadata else {}
+        self.grpc_code = grpc_code
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{type(self).__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class InvalidArgumentError(RingoError):
+    code = "INVALID_ARGUMENT"
+
+
+class DuplicateError(RingoError):
+    code = "DUPLICATE"
+
+
+class NotFoundError(RingoError):
+    code = "NOT_FOUND"
+
+
+class ConflictError(RingoError):
+    code = "CONFLICT"
+
+
+class LeaseLostError(RingoError):
+    code = "LEASE_LOST"
+
+
+class UnavailableError(RingoError):
+    code = "UNAVAILABLE"
+
+
+class DeadlineExceededError(RingoError):
+    code = "DEADLINE_EXCEEDED"
+
+
+class IncompatibleVersionError(RingoError):
+    code = "INCOMPATIBLE_VERSION"
+
+
+class InternalError(RingoError):
+    code = "INTERNAL"
+
+
+_CODE_TO_ERROR: dict[int, type[RingoError]] = {
+    queue_pb2.ERROR_CODE_INVALID_ARGUMENT: InvalidArgumentError,
+    queue_pb2.ERROR_CODE_DUPLICATE: DuplicateError,
+    queue_pb2.ERROR_CODE_NOT_FOUND: NotFoundError,
+    queue_pb2.ERROR_CODE_CONFLICT: ConflictError,
+    queue_pb2.ERROR_CODE_LEASE_LOST: LeaseLostError,
+    queue_pb2.ERROR_CODE_UNAVAILABLE: UnavailableError,
+    queue_pb2.ERROR_CODE_DEADLINE_EXCEEDED: DeadlineExceededError,
+    queue_pb2.ERROR_CODE_INCOMPATIBLE_VERSION: IncompatibleVersionError,
+    queue_pb2.ERROR_CODE_INTERNAL: InternalError,
+}
+
+# gRPC codes that map unambiguously onto a single public Ringo code. Other
+# gRPC codes raise the base RingoError without inventing a more specific
+# public code (docs/contracts/errors.md).
+_GRPC_FALLBACK: dict[grpc.StatusCode, type[RingoError]] = {
+    grpc.StatusCode.INVALID_ARGUMENT: InvalidArgumentError,
+    grpc.StatusCode.NOT_FOUND: NotFoundError,
+    grpc.StatusCode.ALREADY_EXISTS: DuplicateError,
+    grpc.StatusCode.ABORTED: LeaseLostError,
+    grpc.StatusCode.UNAVAILABLE: UnavailableError,
+    grpc.StatusCode.DEADLINE_EXCEEDED: DeadlineExceededError,
+    grpc.StatusCode.INTERNAL: InternalError,
+}
+
+
+def error_from_detail(detail: queue_pb2.ErrorDetail) -> RingoError:
+    """Build the mapped exception from a ``ringo.v1.ErrorDetail`` message."""
+    cls = _CODE_TO_ERROR.get(detail.code, RingoError)
+    return cls(
+        detail.message,
+        request_id=detail.request_id or None,
+        metadata=detail.metadata,
+    )
+
+
+def map_rpc_error(exc: grpc.aio.AioRpcError) -> RingoError:
+    """Map a gRPC call failure to the stable public exception.
+
+    Prefers the ``ringo.v1.ErrorDetail`` serialized in ``google.rpc.Status``
+    details; falls back to the gRPC code only when details are unavailable.
+    """
+    rich = None
+    try:
+        rich = rpc_status.from_call(exc)
+    except Exception:
+        rich = None
+    if rich is not None:
+        for any_msg in rich.details:
+            if any_msg.Is(queue_pb2.ErrorDetail.DESCRIPTOR):
+                detail = queue_pb2.ErrorDetail()
+                any_msg.Unpack(detail)
+                err = error_from_detail(detail)
+                err.grpc_code = exc.code()
+                return err
+    cls = _GRPC_FALLBACK.get(exc.code(), RingoError)
+    message = exc.details() or str(exc)
+    return cls(message, grpc_code=exc.code())
+
+
+# ---------------------------------------------------------------------------
+# Handler signalling errors (execution outcomes, not transport errors).
+
+
+class RetryTaskError(Exception):
+    """Raise from a handler to retry with an optional per-attempt delay."""
+
+    def __init__(self, message: str = "", *, delay: float | None = None) -> None:
+        super().__init__(message)
+        self.delay = delay
+
+
+class PermanentTaskError(Exception):
+    """Raise from a handler to mark the task permanently failed (DEAD)."""