modsmith 0.1.0__py3-none-any.whl

modsmith/loaders/_install_profile.py

@@ -0,0 +1,359 @@
+"""Read Forge and NeoForge installer jars and expand their variables."""
+
+import json
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from ..errors import LoaderError, UnsupportedError
+from ..minecraft import maven_path
+
+
+class _Artifact(BaseModel):
+    """A library's ``downloads.artifact`` object."""
+
+    path: str | None = None
+    url: str | None = None
+    sha1: str | None = None
+    size: int | None = None
+
+
+class _Downloads(BaseModel):
+    """A library's ``downloads`` object."""
+
+    artifact: _Artifact | None = None
+
+
+class Library(BaseModel):
+    """A library listed by an installer.
+
+    Attributes:
+        name: Its Maven coordinate.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    downloads: _Downloads | None = None
+
+    @property
+    def _artifact(self) -> _Artifact:
+        """The download details, or an empty artifact if there are none."""
+        if self.downloads and self.downloads.artifact:
+            return self.downloads.artifact
+        return _Artifact()
+
+    @property
+    def path(self) -> str:
+        """Its path inside the libraries directory."""
+        return self._artifact.path or maven_path(self.name)
+
+    @property
+    def url(self) -> str | None:
+        """Where to download it, or None if it has no URL."""
+        return self._artifact.url or None
+
+    @property
+    def hashes(self) -> dict[str, str]:
+        """Its expected digests keyed by algorithm name."""
+        sha1 = self._artifact.sha1
+        return {"sha1": sha1} if sha1 else {}
+
+    @property
+    def size(self) -> int | None:
+        """Its size in bytes, or None if unknown."""
+        return self._artifact.size or None
+
+
+class Processor(BaseModel):
+    """One step of an install: a jar to run and the files it produces.
+
+    Attributes:
+        jar: The Maven coordinate of the jar to run.
+        classpath: Maven coordinates of the jar's dependencies.
+        args: Command-line arguments, which can contain variables.
+        outputs: Expected SHA-1 digests keyed by output file.
+        sides: The sides it runs on, or None for every side.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    jar: str
+    classpath: list[str] = Field(default_factory=list[str])
+    args: list[str] = Field(default_factory=list[str])
+    outputs: dict[str, str] = Field(default_factory=dict[str, str])
+    sides: list[str] | None = None
+
+    def applies_to(self, side: str) -> bool:
+        """Return whether this step runs on ``side``."""
+        return self.sides is None or side in self.sides
+
+
+class _DataValue(BaseModel):
+    """A variable's value for each side."""
+
+    client: str
+    server: str = ""
+
+
+class InstallProfile(BaseModel):
+    """The ``install_profile.json`` inside a Forge or NeoForge installer.
+
+    Attributes:
+        spec: The profile format version.
+        version: The version id it installs.
+        minecraft: The Minecraft version it targets.
+        json_path: The path of the version JSON inside the installer.
+        libraries: The libraries the processors need.
+        processors: The install steps, in order.
+        data: The variables available to the processors.
+    """
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    spec: int
+    version: str
+    minecraft: str
+    json_path: str = Field(alias="json")
+    libraries: list[Library] = Field(default_factory=list[Library])
+    processors: list[Processor] = Field(default_factory=list[Processor])
+    data: dict[str, _DataValue] = Field(default_factory=dict[str, _DataValue])
+
+    @classmethod
+    def parse(cls, data: dict[str, Any]) -> "InstallProfile":
+        """Validate a decoded profile.
+
+        Args:
+            data: The decoded JSON.
+
+        Returns:
+            The profile.
+
+        Raises:
+            UnsupportedError: The profile is from before Minecraft 1.13.
+        """
+        if "spec" not in data:
+            raise UnsupportedError("Installers before Minecraft 1.13 are not supported")
+        return cls.model_validate(data)
+
+    def client_processors(self) -> list[Processor]:
+        """Return the steps that run on the client."""
+        return [p for p in self.processors if p.applies_to("client")]
+
+
+class InstallerJar:
+    """A downloaded Forge or NeoForge installer, read as an archive.
+
+    Args:
+        path: The installer jar.
+
+    Attributes:
+        path: The installer jar.
+        profile: Its install profile.
+        version_json: Its version JSON.
+
+    Raises:
+        LoaderError: The installer is malformed.
+        UnsupportedError: The installer is older than Minecraft 1.13.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        try:
+            with zipfile.ZipFile(path) as archive:
+                self.profile = InstallProfile.parse(
+                    json.loads(archive.read("install_profile.json"))
+                )
+                self.version_json: dict[str, Any] = json.loads(
+                    archive.read(self.profile.json_path.lstrip("/"))
+                )
+        except (zipfile.BadZipFile, KeyError, ValueError, ValidationError) as e:
+            raise LoaderError(f"Malformed installer {path.name}: {e}") from e
+
+    @property
+    def version_id(self) -> str:
+        """The id declared by the version JSON."""
+        return self.version_json["id"]
+
+    @property
+    def version_libraries(self) -> list[Library]:
+        """The libraries the version JSON lists for the running game."""
+        items = self.version_json.get("libraries", [])
+        return [Library.model_validate(item) for item in items]
+
+    def extract_bundled_libraries(self, libraries_dir: Path) -> None:
+        """Copy the libraries bundled in the installer into ``libraries_dir``.
+
+        Args:
+            libraries_dir: The game's libraries directory.
+        """
+        with zipfile.ZipFile(self.path) as archive:
+            for info in archive.infolist():
+                if info.is_dir() or not info.filename.startswith("maven/"):
+                    continue
+                dest = libraries_dir / info.filename.removeprefix("maven/")
+                if dest.is_file() and dest.stat().st_size == info.file_size:
+                    continue
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(archive.read(info))
+
+    def extract_data_file(self, name: str, dest_dir: Path) -> Path:
+        """Extract a file named by the install profile.
+
+        Args:
+            name: The file's path inside the installer.
+            dest_dir: The directory to extract into.
+
+        Returns:
+            The extracted file.
+
+        Raises:
+            LoaderError: The installer does not contain the file.
+        """
+        relative = name.lstrip("/")
+        dest = dest_dir / relative
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with zipfile.ZipFile(self.path) as archive:
+                dest.write_bytes(archive.read(relative))
+        except KeyError as e:
+            raise LoaderError(f"Installer is missing {name}") from e
+        return dest
+
+
+def replace_tokens(tokens: dict[str, str], value: str) -> str:
+    """Expand ``{NAME}`` and ``'literal'`` as the installer format defines them.
+
+    Args:
+        tokens: The variables.
+        value: The text to expand.
+
+    Returns:
+        The expanded text.
+
+    Raises:
+        LoaderError: The text is malformed or uses an unknown variable.
+    """
+    result: list[str] = []
+    closers = {"{": "}", "'": "'"}
+    index = 0
+
+    def escaped() -> str:
+        nonlocal index
+        if index == len(value):
+            raise LoaderError(f"Bad escape in pattern: {value}")
+        char = value[index]
+        index += 1
+        return char
+
+    while index < len(value):
+        char = value[index]
+        index += 1
+        if char == "\\":
+            result.append(escaped())
+        elif char in closers:
+            key: list[str] = []
+            while True:
+                if index == len(value):
+                    raise LoaderError(f"Unclosed {char} in pattern: {value}")
+                inner = value[index]
+                index += 1
+                if inner == "\\":
+                    key.append(escaped())
+                elif inner == closers[char]:
+                    break
+                else:
+                    key.append(inner)
+            name = "".join(key)
+            if char == "'":
+                result.append(name)
+            elif name in tokens:
+                result.append(tokens[name])
+            else:
+                raise LoaderError(f"Unknown variable {name} in pattern: {value}")
+        else:
+            result.append(char)
+    return "".join(result)
+
+
+class Variables:
+    """The variables available to a processor.
+
+    Args:
+        libraries_dir: The game's libraries directory.
+        tokens: The values keyed by variable name.
+
+    Attributes:
+        libraries_dir: The game's libraries directory.
+        tokens: The values keyed by variable name.
+    """
+
+    def __init__(self, libraries_dir: Path, tokens: dict[str, str]) -> None:
+        self.libraries_dir = libraries_dir
+        self.tokens = tokens
+
+    @classmethod
+    def build(
+        cls,
+        installer: InstallerJar,
+        libraries_dir: Path,
+        root: Path,
+        minecraft_jar: Path,
+        temp_dir: Path,
+    ) -> "Variables":
+        """Build the variables for an install, extracting the files they refer to.
+
+        Args:
+            installer: The installer.
+            libraries_dir: The game's libraries directory.
+            root: The game directory.
+            minecraft_jar: The vanilla client jar.
+            temp_dir: Where to extract data files.
+
+        Returns:
+            The variables.
+
+        Raises:
+            LoaderError: The installer does not contain a file it refers to.
+        """
+        variables = cls(libraries_dir, {})
+        for key, data in installer.profile.data.items():
+            value = data.client
+            if value.startswith("[") and value.endswith("]"):
+                resolved = str(variables.artifact(value))
+            elif value.startswith("'") and value.endswith("'"):
+                resolved = value[1:-1]
+            else:
+                resolved = str(installer.extract_data_file(value, temp_dir))
+            variables.tokens[key] = resolved
+        variables.tokens.update(
+            SIDE="client",
+            MINECRAFT_JAR=str(minecraft_jar),
+            MINECRAFT_VERSION=installer.profile.minecraft,
+            ROOT=str(root),
+            INSTALLER=str(installer.path),
+            LIBRARY_DIR=str(libraries_dir),
+        )
+        return variables
+
+    def artifact(self, bracketed: str) -> Path:
+        """Return the path of a ``[group:artifact:version]`` reference."""
+        return self.libraries_dir / maven_path(bracketed[1:-1])
+
+    def resolve(self, value: str) -> str:
+        """Expand a processor value.
+
+        Args:
+            value: A ``[coordinate]`` reference, or text with variables.
+
+        Returns:
+            The expanded value.
+
+        Raises:
+            LoaderError: The text is malformed or uses an unknown variable.
+        """
+        if value.startswith("[") and value.endswith("]"):
+            return str(self.artifact(value))
+        return replace_tokens(self.tokens, value)

modsmith/loaders/_processors.py

@@ -0,0 +1,223 @@
+"""Run the processors of a Forge or NeoForge installer."""
+
+import logging
+import os
+import subprocess
+import tempfile
+import zipfile
+import zlib
+from pathlib import Path
+
+from ..errors import Cancelled, ProcessorError
+from ..minecraft import maven_path
+from ..net import file_hash
+from ..progress import CancelToken, ProgressCallback, report
+from ._install_profile import Processor, Variables
+
+logger = logging.getLogger(__name__)
+TASK = "processors"
+POLL_SECONDS = 0.2
+
+
+def uses_zlib_ng() -> bool:
+    """Return whether this system's zlib is zlib-ng.
+
+    Its compressed output can differ from stock zlib, so a valid patched jar may
+    not match its published hash.
+    """
+    return "ng" in zlib.ZLIB_RUNTIME_VERSION.lower()
+
+
+def main_class(jar: Path) -> str:
+    """Read a jar's ``Main-Class``.
+
+    Raises:
+        ProcessorError: The jar or its manifest cannot be read, or has no main class.
+    """
+    try:
+        with zipfile.ZipFile(jar) as archive:
+            manifest = archive.read("META-INF/MANIFEST.MF").decode("utf-8")
+    except (OSError, KeyError, zipfile.BadZipFile) as e:
+        raise ProcessorError(f"Cannot read manifest of {jar.name}: {e}") from e
+    for line in manifest.splitlines():
+        if line.startswith("Main-Class:"):
+            return line.split(":", 1)[1].strip()
+    raise ProcessorError(f"{jar.name} has no Main-Class")
+
+
+def resolve_outputs(processor: Processor, variables: Variables) -> dict[Path, str]:
+    """Return a processor's output files and their expected SHA-1."""
+    return {
+        Path(variables.resolve(key)): variables.resolve(value).lower()
+        for key, value in processor.outputs.items()
+    }
+
+
+def outputs_valid(outputs: dict[Path, str]) -> bool:
+    """Return whether every output already exists with the right hash.
+
+    Files with the wrong hash are deleted so the processor can rebuild them. With
+    no declared outputs this is False, because nothing can prove the work is done.
+    """
+    if not outputs:
+        return False
+    valid = True
+    for path, expected in outputs.items():
+        if not path.is_file():
+            valid = False
+        elif file_hash(path) != expected:
+            path.unlink()
+            valid = False
+    return valid
+
+
+def is_valid_jar(path: Path) -> bool:
+    """Return whether a file is a zip archive with intact contents."""
+    try:
+        with zipfile.ZipFile(path) as archive:
+            return archive.testzip() is None
+    except zipfile.BadZipFile:
+        return False
+
+
+def verify_outputs(outputs: dict[Path, str], tolerant: bool) -> None:
+    """Check the files a processor produced.
+
+    Args:
+        outputs: Expected SHA-1 digests keyed by output file.
+        tolerant: Accept a valid jar with a different hash.
+
+    Raises:
+        ProcessorError: A file is missing or wrong. A wrong file is deleted.
+    """
+    for path, expected in outputs.items():
+        if not path.is_file():
+            raise ProcessorError(f"Processor did not produce {path.name}")
+        actual = file_hash(path)
+        if actual == expected:
+            continue
+        if tolerant and path.suffix == ".jar" and is_valid_jar(path):
+            logger.info("Ignoring hash mismatch for %s under zlib-ng", path.name)
+            continue
+        path.unlink()
+        raise ProcessorError(
+            f"Hash mismatch for {path.name}: expected {expected}, got {actual}"
+        )
+
+
+def build_command(
+    processor: Processor, variables: Variables, java: Path, libraries_dir: Path
+) -> list[str]:
+    """Build the command line that runs a processor.
+
+    Args:
+        processor: The processor.
+        variables: The install's variables.
+        java: The Java binary.
+        libraries_dir: The game's libraries directory.
+
+    Returns:
+        The command and its arguments.
+
+    Raises:
+        ProcessorError: The jar or a dependency is missing.
+    """
+    jar = libraries_dir / maven_path(processor.jar)
+    if not jar.is_file():
+        raise ProcessorError(f"Missing processor jar: {jar.name}")
+    classpath = [jar]
+    for coord in processor.classpath:
+        path = libraries_dir / maven_path(coord)
+        if not path.is_file():
+            raise ProcessorError(f"Missing processor dependency: {path.name}")
+        classpath.append(path)
+    return [
+        str(java),
+        "-cp",
+        os.pathsep.join(map(str, classpath)),
+        main_class(jar),
+        *[variables.resolve(arg) for arg in processor.args],
+    ]
+
+
+def execute(
+    command: list[str], cwd: str, cancel: CancelToken | None
+) -> tuple[int, str]:
+    """Run a command and wait for it, stopping it if ``cancel`` is triggered.
+
+    Args:
+        command: The command and its arguments.
+        cwd: The working directory.
+        cancel: Terminates the process.
+
+    Returns:
+        The exit code and the combined output.
+
+    Raises:
+        ProcessorError: The command could not be started.
+        Cancelled: ``cancel`` was triggered.
+    """
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except OSError as e:
+        raise ProcessorError(f"Cannot run {command[0]}: {e}") from e
+    while True:
+        try:
+            output, _ = process.communicate(timeout=POLL_SECONDS)
+            return process.returncode, output or ""
+        except subprocess.TimeoutExpired:
+            if cancel is not None and cancel.cancelled:
+                process.terminate()
+                process.communicate()
+                raise Cancelled("Operation cancelled") from None
+
+
+def run_processors(
+    processors: list[Processor],
+    variables: Variables,
+    java: Path,
+    libraries_dir: Path,
+    progress: ProgressCallback | None = None,
+    cancel: CancelToken | None = None,
+) -> None:
+    """Run processors in order, skipping those whose outputs are already valid.
+
+    Each one runs with a temporary working directory.
+
+    Args:
+        processors: The processors.
+        variables: The install's variables.
+        java: The Java binary.
+        libraries_dir: The game's libraries directory.
+        progress: Receives one update for each step.
+        cancel: Stops the run and terminates the current processor.
+
+    Raises:
+        ProcessorError: A processor failed or produced a wrong file.
+        Cancelled: ``cancel`` was triggered.
+    """
+    tolerant = uses_zlib_ng()
+    total = len(processors)
+    with tempfile.TemporaryDirectory(prefix="modsmith-processor-") as work_dir:
+        for index, processor in enumerate(processors):
+            if cancel is not None:
+                cancel.check()
+            report(progress, TASK, index, total, "step")
+            outputs = resolve_outputs(processor, variables)
+            if outputs_valid(outputs):
+                continue
+            command = build_command(processor, variables, java, libraries_dir)
+            code, output = execute(command, work_dir, cancel)
+            if code != 0:
+                tail = "\n".join(output.splitlines()[-20:])
+                raise ProcessorError(f"{processor.jar} exited with code {code}\n{tail}")
+            verify_outputs(outputs, tolerant)
+    report(progress, TASK, total, total, "step")

modsmith/minecraft/__init__.py

@@ -0,0 +1,15 @@
+"""Game directories, version metadata and vanilla game files."""
+
+from ._game_dir import GameDir, Version
+from ._maven import MavenCoord, maven_path
+from ._remote import VersionInfo, install_version, list_versions
+
+__all__ = [
+    "GameDir",
+    "MavenCoord",
+    "Version",
+    "VersionInfo",
+    "install_version",
+    "list_versions",
+    "maven_path",
+]