cf-runtime 0.1.8__py3-none-any.whl

cf_runtime/managed_tools.py

@@ -0,0 +1,373 @@
+"""Pinned, verified acquisition of the Java and Fuseki runtime tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import platform
+import re
+import shutil
+import stat
+import subprocess
+import tarfile
+import tempfile
+import time
+from typing import Callable, Iterable
+import urllib.parse
+import urllib.request
+import zipfile
+
+from .locking import LifecycleLock
+from .paths import CogniflowHome
+
+MAX_BYTES = 512 * 1024 * 1024
+MAX_FILES = 100_000
+MAX_EXTRACTED = 2 * 1024 * 1024 * 1024
+_REPARSE_POINT = 0x0400
+_VERSION = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+\-]*$")
+
+
+class ManagedToolsError(ValueError):
+    """Expected provisioning failure with a stable machine-readable code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+MANAGED_REQUEST_SCHEMA = "cf.runtime.managed-tools.request.v1"
+MANAGED_RESULT_SCHEMA = "cf.runtime.managed-tools.result.v1"
+
+
+@dataclass(frozen=True, slots=True)
+class Artifact:
+    name: str
+    version: str
+    platform: str
+    architecture: str
+    archive_format: str
+    url: str
+    sha256: str
+    archive_root: str
+    executable: str
+    version_command: tuple[str, ...]
+    version_pattern: str
+    size: int
+
+    def validate(self) -> None:
+        if self.name not in {"java", "fuseki"} or not _VERSION.fullmatch(self.version):
+            raise ManagedToolsError("CATALOG_INVALID", "invalid tool identity or version")
+        if self.archive_format not in {"zip", "tar.gz"} or not self.archive_root or not self.executable:
+            raise ManagedToolsError("CATALOG_INVALID", "invalid archive layout")
+        parsed = urllib.parse.urlparse(self.url)
+        if parsed.scheme not in {"https", "file"} or not parsed.netloc and parsed.scheme == "https":
+            raise ManagedToolsError("CATALOG_INVALID", "artifact URL must be HTTPS or a fixture file URL")
+        if not re.fullmatch(r"[0-9a-f]{64}", self.sha256) or self.size <= 0 or self.size > MAX_BYTES:
+            raise ManagedToolsError("CATALOG_INVALID", "invalid artifact digest or size")
+
+
+def normalized_platform() -> tuple[str, str]:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    if system == "windows" and machine in {"amd64", "x86_64"}:
+        return "windows", "x86_64"
+    if system == "linux" and machine in {"amd64", "x86_64"}:
+        return "linux", "x86_64"
+    raise ManagedToolsError("UNSUPPORTED_PLATFORM", "only Windows/Linux x86_64 are supported")
+
+
+def _artifact(name: str, version: str, plat: str, arch: str, fmt: str, url: str,
+              digest: str, root: str, executable: str, command: tuple[str, ...],
+              pattern: str, size: int) -> Artifact:
+    return Artifact(name, version, plat, arch, fmt, url, digest, root, executable, command, pattern, size)
+
+
+def catalog() -> tuple[Artifact, ...]:
+    java_version = "21.0.10+7"
+    base = "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.10%2B7/"
+    java = {
+        ("windows", "x86_64"): _artifact("java", java_version, "windows", "x86_64", "zip", base + "OpenJDK21U-jdk_x64_windows_hotspot_21.0.10_7.zip", "08cae782814f027f8b159d6b68823f0f87422eb475c1a0ea1abc7a4357aaf11f", "jdk-21.0.10+7", "bin/java.exe", ("-version",), r"21\.0\.10", 204_939_612),
+        ("linux", "x86_64"): _artifact("java", java_version, "linux", "x86_64", "tar.gz", base + "OpenJDK21U-jdk_x64_linux_hotspot_21.0.10_7.tar.gz", "ea3b9bd464d6dd253e9a7accf59f7ccd2a36e4aa69640b7251e3370caef896a4", "jdk-21.0.10+7", "bin/java", ("-version",), r"21\.0\.10", 207_216_881),
+    }
+    fuseki_base = "https://archive.apache.org/dist/jena/binaries/apache-jena-fuseki-6.0.0.zip"
+    fuseki = _artifact("fuseki", "6.0.0", "any", "x86_64", "zip", fuseki_base, "08285d130def0928e4a414e6750a09a2924c74407f395b133e914575c722b7ef", "apache-jena-fuseki-6.0.0", "fuseki-server.jar", ("--version",), r"6\.0\.0", 51_253_805)
+    # The Apache checksum is resolved once from the official release archive.
+    # A missing digest intentionally makes normal provisioning fail closed.
+    return (*java.values(), fuseki)
+
+
+def bind_release_lock(records: object) -> tuple[Artifact, ...]:
+    """Bind release-profile identities to the executable runtime catalog."""
+    if not isinstance(records, list):
+        raise ManagedToolsError("RELEASE_LOCK_INVALID", "managed-tool release lock must be a list")
+    expected = {
+        "fuseki": next(item for item in catalog() if item.name == "fuseki"),
+        "java-linux-x86_64": next(item for item in catalog() if item.name == "java" and item.platform == "linux"),
+        "java-windows-x86_64": next(item for item in catalog() if item.name == "java" and item.platform == "windows"),
+    }
+    if [item.get("name") if isinstance(item, dict) else None for item in records] != sorted(expected):
+        raise ManagedToolsError("RELEASE_LOCK_INVALID", "managed-tool release lock is incomplete")
+    for record in records:
+        if not isinstance(record, dict) or set(record) != {"name", "version", "url", "sha256", "size"}:
+            raise ManagedToolsError("RELEASE_LOCK_INVALID", "managed-tool release lock entry is invalid")
+        spec = expected[record["name"]]
+        actual = {key: record[key] for key in ("version", "url", "sha256", "size")}
+        locked = {"version": spec.version, "url": spec.url, "sha256": spec.sha256, "size": spec.size}
+        if actual != locked:
+            raise ManagedToolsError("RELEASE_LOCK_DIVERGED", f"runtime catalog diverges from release lock for {record['name']}")
+    return tuple(expected[name] for name in sorted(expected))
+
+
+def _safe_relative(value: str) -> PurePosixPath:
+    value = value.replace("\\", "/")
+    path = PurePosixPath(value)
+    if path.is_absolute() or value.startswith(("/", "//")) or re.match(r"^[A-Za-z]:", value) or ".." in path.parts:
+        raise ManagedToolsError("ARCHIVE_UNSAFE", "archive contains an escaping path")
+    if not path.parts or any(not part or part == "." for part in path.parts):
+        raise ManagedToolsError("ARCHIVE_UNSAFE", "archive contains an invalid path")
+    return path
+
+
+def _safe_link_target(member_name: str, linkname: str, expected_root: str) -> PurePosixPath:
+    target = linkname.replace("\\", "/")
+    if target.startswith(("/", "//")) or re.match(r"^[A-Za-z]:", target):
+        raise ManagedToolsError("ARCHIVE_LINK", "symlink escapes archive root")
+    parts = list(PurePosixPath(member_name).parent.parts)
+    for part in PurePosixPath(target).parts:
+        if part in {"", "."}:
+            continue
+        if part == "..":
+            if not parts or parts[-1] == expected_root:
+                raise ManagedToolsError("ARCHIVE_LINK", "symlink escapes archive root")
+            parts.pop()
+        else:
+            parts.append(part)
+    if not parts or parts[0] != expected_root:
+        raise ManagedToolsError("ARCHIVE_LINK", "symlink escapes archive root")
+    return PurePosixPath(*parts)
+
+
+def _exists_without_following(path: Path) -> bool:
+    return os.path.lexists(path)
+
+
+def _is_redirect(path: Path) -> bool:
+    if path.is_symlink():
+        return True
+    if os.name == "nt":
+        try:
+            return bool(os.lstat(path).st_file_attributes & _REPARSE_POINT)
+        except (AttributeError, FileNotFoundError, OSError):
+            return False
+    return False
+
+
+def _validate_names(names: Iterable[str], expected_root: str) -> list[PurePosixPath]:
+    paths = [_safe_relative(name) for name in names]
+    if not paths or any(path.parts[0] != expected_root for path in paths):
+        raise ManagedToolsError("ARCHIVE_ROOT_INVALID", "unexpected archive root")
+    folded: set[str] = set()
+    for path in paths:
+        key = "/".join(path.parts).casefold()
+        if key in folded:
+            raise ManagedToolsError("ARCHIVE_DUPLICATE", "duplicate or case-colliding archive path")
+        folded.add(key)
+    return paths
+
+
+def _validate_zip(archive: Path, spec: Artifact) -> None:
+    with zipfile.ZipFile(archive) as zf:
+        infos = zf.infolist()
+        if len(infos) > MAX_FILES or sum(max(0, i.file_size) for i in infos) > MAX_EXTRACTED:
+            raise ManagedToolsError("ARCHIVE_LIMIT", "archive exceeds extraction limits")
+        _validate_names((i.filename for i in infos), spec.archive_root)
+        for info in infos:
+            mode = (info.external_attr >> 16) & 0o170000
+            if mode in {stat.S_IFLNK, stat.S_IFCHR, stat.S_IFBLK, stat.S_IFIFO, stat.S_IFSOCK}:
+                raise ManagedToolsError("ARCHIVE_LINK", "links and special files are not allowed")
+
+
+def _validate_tar(archive: Path, spec: Artifact) -> None:
+    with tarfile.open(archive, "r:gz") as tf:
+        members = tf.getmembers()
+        if len(members) > MAX_FILES or sum(max(0, m.size) for m in members) > MAX_EXTRACTED:
+            raise ManagedToolsError("ARCHIVE_LIMIT", "archive exceeds extraction limits")
+        _validate_names((m.name for m in members), spec.archive_root)
+        for member in members:
+            if member.issym():
+                _safe_link_target(member.name, member.linkname, spec.archive_root)
+            elif member.islnk() or not (member.isfile() or member.isdir()):
+                raise ManagedToolsError("ARCHIVE_LINK", "hardlinks and special files are not allowed")
+
+
+def _extract(archive: Path, spec: Artifact, destination: Path) -> None:
+    if spec.archive_format == "zip":
+        _validate_zip(archive, spec)
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(destination)
+    else:
+        _validate_tar(archive, spec)
+        with tarfile.open(archive, "r:gz") as tf:
+            tf.extractall(destination, filter="data")
+
+
+def _run(command: list[str], cwd: Path, timeout: float, env: dict[str, str]) -> str:
+    try:
+        result = subprocess.run(command, cwd=cwd, env=env, capture_output=True, text=True,
+                                timeout=timeout, check=False, encoding="utf-8", errors="replace")
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise ManagedToolsError("TOOL_INVALID", "managed tool command failed") from error
+    output = (result.stdout + "\n" + result.stderr)[:16_384]
+    if result.returncode != 0:
+        raise ManagedToolsError("TOOL_INVALID", "managed tool returned a failure")
+    return output
+
+
+class ManagedTools:
+    def __init__(self, home: CogniflowHome, *, artifacts: Iterable[Artifact] | None = None,
+                 opener: Callable[..., object] = urllib.request.urlopen,
+                 lock_timeout: float = 0.0) -> None:
+        self.home = home
+        self.artifacts = tuple(artifacts or catalog())
+        self.opener = opener
+        self.lock_timeout = lock_timeout
+
+    def _find(self, name: str, version: str) -> Artifact:
+        plat, arch = normalized_platform()
+        matches = [a for a in self.artifacts if a.name == name and a.version == version and
+                   (a.platform, a.architecture) in {(plat, arch), ("any", arch)}]
+        if len(matches) != 1:
+            raise ManagedToolsError("ARTIFACT_UNAVAILABLE", f"no exact {name} artifact for {plat}/{arch}")
+        matches[0].validate()
+        return matches[0]
+
+    def _download(self, spec: Artifact) -> Path:
+        cache = self.home.tool_cache
+        cache.mkdir(parents=True, exist_ok=True)
+        suffix = ".zip" if spec.archive_format == "zip" else ".tar.gz"
+        target = cache / f"{spec.name}-{spec.version}-{spec.platform}-{spec.architecture}{suffix}"
+        if target.is_file() and target.stat().st_size == spec.size and _sha256(target) == spec.sha256:
+            return target
+        temporary = cache / f".{target.name}.{os.getpid()}.{time.time_ns()}.part"
+        try:
+            request = urllib.request.Request(spec.url, headers={"User-Agent": "cogniflow-cf-runtime/0.1"})
+            with self.opener(request, timeout=30) as response, temporary.open("wb") as stream:
+                digest = hashlib.sha256()
+                total = 0
+                while True:
+                    chunk = response.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > spec.size or total > MAX_BYTES:
+                        raise ManagedToolsError("DOWNLOAD_TOO_LARGE", "download exceeds catalog size")
+                    digest.update(chunk)
+                    stream.write(chunk)
+                stream.flush(); os.fsync(stream.fileno())
+            if total != spec.size or digest.hexdigest() != spec.sha256:
+                raise ManagedToolsError("CHECKSUM_MISMATCH", "download digest or size does not match catalog")
+            os.replace(temporary, target)
+            return target
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def provision(self, java_version: str, fuseki_version: str) -> dict[str, object]:
+        if not isinstance(java_version, str) or not isinstance(fuseki_version, str):
+            raise ManagedToolsError("INVALID_REQUEST", "tool versions must be strings")
+        java = self._find("java", java_version)
+        fuseki = self._find("fuseki", fuseki_version)
+        with LifecycleLock(self.home.tool_locks, self.lock_timeout):
+            self.home.root.mkdir(parents=True, exist_ok=True)
+            java_root = self.home.java_install(java.version)
+            fuseki_root = self.home.fuseki_install(fuseki.version)
+            java_result = self._install(java, java_root, "java")
+            fuseki_result = self._install(fuseki, fuseki_root, "fuseki")
+        return {"schema": MANAGED_RESULT_SCHEMA,
+                "status": "unchanged" if java_result == fuseki_result == "unchanged" else "ready",
+                "java": self._result(java, java_root, java_root / java.executable, "java"),
+                "fuseki": self._result(fuseki, fuseki_root, fuseki_root / fuseki.executable, "fuseki")}
+
+    def _install(self, spec: Artifact, final: Path, kind: str) -> str:
+        if _exists_without_following(final) and _is_redirect(final):
+            raise ManagedToolsError("FOREIGN_INSTALLATION", f"managed {kind} path is a redirect")
+        marker = final / ".cf-managed.json"
+        if _exists_without_following(final) and not final.is_dir():
+            raise ManagedToolsError("FOREIGN_INSTALLATION", f"managed {kind} path is not a directory")
+        if _exists_without_following(final) and marker.is_file() and not _is_redirect(marker):
+            try:
+                data = json.loads(marker.read_text(encoding="utf-8"))
+                if data == {"name": spec.name, "version": spec.version, "sha256": spec.sha256}:
+                    self._validate_install(final, spec, kind)
+                    return "unchanged"
+            except (OSError, ValueError, json.JSONDecodeError):
+                pass
+        if _exists_without_following(final):
+            raise ManagedToolsError("FOREIGN_INSTALLATION", f"managed {kind} path is not owned by cf_runtime")
+        archive = self._download(spec)
+        staging = final.parent / f".{final.name}.{os.getpid()}.{time.time_ns()}.staging"
+        try:
+            final.parent.mkdir(parents=True, exist_ok=True)
+            staging.mkdir(parents=True)
+            _extract(archive, spec, staging)
+            source = staging / spec.archive_root
+            if not source.is_dir():
+                raise ManagedToolsError("ARCHIVE_ROOT_INVALID", "archive root is not a directory")
+            os.replace(source, staging / "payload")
+            payload = staging / "payload"
+            self._validate_install(payload, spec, kind)
+            (payload / ".cf-managed.json").write_text(json.dumps({"name": spec.name, "version": spec.version, "sha256": spec.sha256}, sort_keys=True) + "\n", encoding="utf-8")
+            os.replace(payload, final)
+            return "ready"
+        finally:
+            shutil.rmtree(staging, ignore_errors=True)
+
+    def _validate_install(self, root: Path, spec: Artifact, kind: str) -> None:
+        candidate = root / spec.executable
+        current = root
+        for part in candidate.relative_to(root).parts:
+            current = current / part
+            if current.is_symlink():
+                raise ManagedToolsError("TOOL_INVALID", f"managed {kind} executable is a symlink")
+        path = candidate.resolve(strict=False)
+        if not path.is_file() or root.resolve() not in path.parents:
+            raise ManagedToolsError("TOOL_INVALID", f"managed {kind} executable is invalid")
+        if kind == "java":
+            env = {k: v for k, v in os.environ.items() if k not in {"JAVA_HOME", "JDK_HOME"}}
+            output = _run([str(path), *spec.version_command], root, 10, env)
+        else:
+            java = self.home.java_install("21.0.10+7") / "bin" / ("java.exe" if os.name == "nt" else "java")
+            if not java.is_file() or java.resolve().is_symlink():
+                raise ManagedToolsError("TOOL_INVALID", "managed Java is required for Fuseki verification")
+            output = _run([str(java), "-jar", str(path), *spec.version_command], root, 10, {})
+        if not re.search(spec.version_pattern, output):
+            raise ManagedToolsError("VERSION_MISMATCH", f"{kind} reported an unexpected version")
+
+    @staticmethod
+    def _result(spec: Artifact, root: Path, executable: Path, kind: str) -> dict[str, object]:
+        lock_record = {
+            "name": spec.name,
+            "version": spec.version,
+            "platform": spec.platform,
+            "architecture": spec.architecture,
+            "archive_format": spec.archive_format,
+            "url": spec.url,
+            "sha256": spec.sha256,
+            "size": spec.size,
+        }
+        lock_digest = "sha256:" + hashlib.sha256(
+            (json.dumps(lock_record, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
+        ).hexdigest()
+        result = {"version": spec.version, "home": str(root), "artifact_sha256": spec.sha256, "lock_record": lock_record, "lock_digest": lock_digest}
+        result["executable" if kind == "java" else "server_artifact"] = str(executable)
+        return result
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()