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

ringo_task_queue/binary.py

@@ -0,0 +1,253 @@
+"""Platform daemon discovery and integrity validation.
+
+Platform wheels contain a manifest beside one or more daemon binaries.  The
+manifest is generated by ``tools/stage_binary.py`` and is deliberately not
+checked into source control with a real executable.  Explicit paths and the
+``RINGO_DAEMON_PATH`` override remain useful for development and are resolved
+before packaged resources.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import stat
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from ._version import PROTOCOL_MAJOR, PROTOCOL_MINOR, SCHEMA_VERSION, daemon_version_for_sdk
+from .errors import RingoError
+
+MANIFEST_NAME = "manifest.json"
+MANIFEST_SCHEMA_VERSION = 1
+DAEMON_NAME = "ringo-task-queue"
+DAEMON_SCHEMA_VERSION = SCHEMA_VERSION
+SUPPORTED_PLATFORMS = frozenset(
+    {
+        "windows-amd64",
+        "linux-amd64",
+        "linux-arm64",
+        "macos-amd64",
+        "macos-arm64",
+    }
+)
+
+
+class BinaryError(RingoError):
+    """Base error for a missing, unsupported, or invalid packaged daemon."""
+
+
+class UnsupportedPlatformError(BinaryError):
+    """The current OS/architecture has no daemon in the wheel."""
+
+
+class BinaryIntegrityError(BinaryError):
+    """A packaged daemon does not match its manifest checksum."""
+
+
+@dataclass(frozen=True)
+class BinaryMetadata:
+    platform: str
+    filename: str
+    sha256: str
+    version: str
+    protocol_major: int
+    protocol_minor: int
+    size: int
+
+
+def platform_key(*, system: str | None = None, machine: str | None = None) -> str:
+    """Return the stable manifest key for an OS and CPU architecture."""
+    system = (system or sys.platform).lower()
+    machine = (machine or platform.machine()).lower().replace("-", "_")
+    if system.startswith("win"):
+        os_name = "windows"
+    elif system.startswith("linux"):
+        os_name = "linux"
+    elif system in {"darwin", "macos"}:
+        os_name = "macos"
+    else:
+        raise UnsupportedPlatformError(f"unsupported operating system: {system}")
+
+    if machine in {"amd64", "x86_64", "x64"}:
+        arch = "amd64"
+    elif machine in {"arm64", "aarch64"} and os_name in {"macos", "linux"}:
+        arch = "arm64"
+    else:
+        raise UnsupportedPlatformError(
+            f"unsupported architecture {machine!r} on {os_name}"
+        )
+    return f"{os_name}-{arch}"
+
+
+def _manifest_from_object(raw: Any) -> dict[str, BinaryMetadata]:
+    """Parse the shared release-artifact manifest contract."""
+    if (
+        not isinstance(raw, dict)
+        or raw.get("manifestVersion") != 1
+        or raw.get("name") != DAEMON_NAME
+        or raw.get("schemaVersion") != DAEMON_SCHEMA_VERSION
+    ):
+        raise BinaryError("invalid daemon manifest schema")
+    artifacts = raw.get("artifacts")
+    if not isinstance(artifacts, list) or not artifacts:
+        raise BinaryError("daemon manifest contains no artifacts")
+    version = raw.get("version")
+    commit = raw.get("buildCommit")
+    build_date = raw.get("buildDate")
+    protocol_major = raw.get("protocolMajor")
+    protocol_minor = raw.get("protocolMinor")
+    if (
+        not isinstance(version, str)
+        or not version
+        or not isinstance(commit, str)
+        or not commit
+        or commit.lower() in {"unknown", "local"}
+        or not isinstance(build_date, str)
+        or not build_date
+        or version != daemon_version_for_sdk()
+        or not isinstance(protocol_major, int)
+        or protocol_major != PROTOCOL_MAJOR
+        or not isinstance(protocol_minor, int)
+        or protocol_minor != PROTOCOL_MINOR
+        or not re.fullmatch(
+            r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})",
+            build_date,
+        )
+    ):
+        raise BinaryError("daemon manifest has invalid compatibility metadata")
+    try:
+        parsed_date = datetime.fromisoformat(build_date.replace("Z", "+00:00"))
+        if parsed_date.tzinfo is None or parsed_date.utcoffset() != timezone.utc.utcoffset(None):
+            raise ValueError
+    except ValueError as exc:
+        raise BinaryError("daemon manifest has invalid buildDate") from exc
+    result: dict[str, BinaryMetadata] = {}
+    for item in artifacts:
+        if not isinstance(item, dict):
+            raise BinaryError("invalid daemon manifest artifact")
+        os_name = item.get("os")
+        arch = item.get("arch")
+        key = f"{os_name}-{'amd64' if arch == 'amd64' else arch}"
+        if os_name == "darwin":
+            key = f"macos-{arch}"
+        elif os_name in {"windows", "linux"}:
+            key = f"{os_name}-{arch}"
+        if key not in SUPPORTED_PLATFORMS:
+            raise BinaryError(f"invalid daemon manifest platform entry: {key!r}")
+        if key in result:
+            raise BinaryError(f"duplicate daemon manifest platform entry: {key!r}")
+        filename = item.get("filename")
+        expected_filename = f"ringo-task-queue-{os_name}-{arch}{'.exe' if os_name == 'windows' else ''}"
+        digest = item.get("sha256")
+        if (
+            not isinstance(filename, str)
+            or filename != expected_filename
+            or "/" in filename
+            or "\\" in filename
+            or Path(filename).name != filename
+            or not isinstance(digest, str)
+            or len(digest) != 64
+            or any(char not in "0123456789abcdef" for char in digest)
+            or not isinstance(item.get("size"), int)
+            or item["size"] <= 0
+            or item["size"] > 512 * 1024**2
+        ):
+            raise BinaryError(f"invalid daemon manifest entry for {key!r}")
+        result[key] = BinaryMetadata(
+            platform=key,
+            filename=filename,
+            sha256=digest,
+            version=version,
+            protocol_major=protocol_major,
+            protocol_minor=protocol_minor,
+            size=item["size"],
+        )
+    return result
+
+
+def load_manifest(directory: Path) -> dict[str, BinaryMetadata]:
+    """Load and validate ``bin/manifest.json`` from an unpacked package."""
+    path = directory / MANIFEST_NAME
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise BinaryError(f"daemon manifest not found: {path}") from None
+    except (OSError, ValueError) as exc:
+        raise BinaryError(f"cannot read daemon manifest {path}: {exc}") from exc
+    return _manifest_from_object(raw)
+
+
+def ensure_executable(path: Path) -> None:
+    """Ensure a Unix-installed daemon retains an executable mode bit."""
+    if os.name == "nt":
+        return
+    try:
+        mode = path.stat().st_mode
+        if not mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+            path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    except OSError as exc:
+        raise BinaryError(f"daemon is not executable: {path}: {exc}") from exc
+
+
+def verify_binary(path: Path, metadata: BinaryMetadata) -> None:
+    """Check a staged daemon's SHA-256 and make it executable on Unix."""
+    try:
+        link_info = path.lstat()
+    except OSError as exc:
+        raise BinaryIntegrityError(f"daemon binary missing: {path}") from exc
+    if path.is_symlink() or not stat.S_ISREG(link_info.st_mode):
+        raise BinaryIntegrityError(f"daemon binary is not a regular file: {path}")
+    digest_state = hashlib.sha256()
+    try:
+        with path.open("rb") as source:
+            opened_info = os.fstat(source.fileno())
+            if not stat.S_ISREG(opened_info.st_mode) or not os.path.samestat(link_info, opened_info):
+                raise BinaryIntegrityError(f"daemon binary changed while opening: {path}")
+            if opened_info.st_size != metadata.size:
+                raise BinaryIntegrityError(
+                    f"daemon size mismatch for {path}: expected {metadata.size}, got {opened_info.st_size}"
+                )
+            read_size = 0
+            while chunk := source.read(min(1024 * 1024, metadata.size - read_size + 1)):
+                read_size += len(chunk)
+                if read_size > metadata.size:
+                    raise BinaryIntegrityError(f"daemon binary grew while reading: {path}")
+                digest_state.update(chunk)
+            if read_size != metadata.size:
+                raise BinaryIntegrityError(f"daemon binary changed while reading: {path}")
+    except BinaryIntegrityError:
+        raise
+    except OSError as exc:
+        raise BinaryIntegrityError(f"cannot read daemon binary: {path}: {exc}") from exc
+    digest = digest_state.hexdigest()
+    if digest != metadata.sha256:
+        raise BinaryIntegrityError(
+            f"daemon SHA-256 mismatch for {path}: expected {metadata.sha256}, got {digest}"
+        )
+    ensure_executable(path)
+
+
+def packaged_binary() -> tuple[Path, BinaryMetadata]:
+    """Resolve and verify the daemon matching the running platform."""
+    key = platform_key()
+    try:
+        package_bin = Path(str(resources.files("ringo_task_queue") / "bin"))
+    except Exception as exc:
+        raise BinaryError(f"cannot access packaged daemon resources: {exc}") from exc
+    entries = load_manifest(package_bin)
+    metadata = entries.get(key)
+    if metadata is None:
+        raise UnsupportedPlatformError(
+            f"wheel has no daemon for platform {key}; available: {', '.join(sorted(entries))}"
+        )
+    path = package_bin / metadata.filename
+    verify_binary(path, metadata)
+    return path, metadata