Skip to content

armgit / Soup

Public Imported from GitHub
0

Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.

6.4 KB
Raw Blame
"""Inspect, extract, and read ``.can`` artifacts (v0.26.0 Part E)."""

from __future__ import annotations

import os
import tarfile
from pathlib import Path
from typing import Any

from soup_cli.cans.schema import Manifest
from soup_cli.utils.paths import is_under_cwd
from soup_cli.utils.yaml_limits import MAX_CONFIG_BYTES, load_yaml_limited

#: Largest ``manifest.yaml`` read into memory. A manifest holds a handful of
#: short fields plus at most 64 attestations of <= 1 MiB each, so a real one is
#: far below this.
MAX_MANIFEST_BYTES = 16 * 1024 * 1024
#: Most members ``extract_can`` will write. ``soup can pack`` writes four.
MAX_EXTRACT_MEMBERS = 10_000
#: Largest total declared size of the regular files ``extract_can`` writes.
#: ``soup can pack`` / ``fork`` write only small text members and refuse a can
#: over 100 MB compressed, but a hand-assembled can may carry a GGUF for a
#: ``deploy_targets`` entry (``cans/run.py:_deploy_target``). GGUF weights are
#: already quantised and barely compress, and an 8B model at Q4_K_M is ~4.9 GB,
#: so 8 GiB covers that case with margin while bounding what a small gzip
#: stream can expand to on disk (deflate reaches ~1000:1 on repetitive input).
MAX_EXTRACT_BYTES = 8 * 1024 * 1024 * 1024


def _read_text_member(
    tar: tarfile.TarFile, name: str, max_bytes: int,
) -> str:
    """Return the text of a regular UTF-8 member, size-capped."""
    try:
        member = tar.getmember(name)
    except KeyError as exc:
        raise ValueError(f"can has no member '{name}'") from exc
    if not member.isfile():
        raise ValueError(f"member '{name}' in can is not a regular file")
    if member.size > max_bytes:
        raise ValueError(
            f"member '{name}' in can is too large "
            f"({member.size} > {max_bytes} bytes)"
        )
    extracted = tar.extractfile(member)
    if extracted is None:
        raise ValueError(f"cannot read member '{name}' from can")
    # The header size is not trusted alone: the read itself is bounded.
    raw = extracted.read(max_bytes + 1)
    if len(raw) > max_bytes:
        raise ValueError(
            f"member '{name}' in can is too large (> {max_bytes} bytes)"
        )
    try:
        return raw.decode("utf-8")
    except UnicodeDecodeError as exc:
        raise ValueError(f"member '{name}' in can is not valid UTF-8: {exc}") from exc


def inspect_can(path: str) -> Manifest:
    """Load and validate the manifest from a ``.can`` file.

    Refuses paths outside the current working directory so an ``inspect``
    invocation cannot be coerced into reading arbitrary tarballs.
    """
    can_path = Path(path)
    if not is_under_cwd(can_path):
        raise ValueError(f"can path '{path}' is outside cwd - refusing")
    if not can_path.exists():
        raise FileNotFoundError(f"can not found: {path}")
    with tarfile.open(can_path, mode="r:gz") as tar:
        manifest_text = _read_text_member(tar, "manifest.yaml", MAX_MANIFEST_BYTES)
    data = load_yaml_limited(
        manifest_text, "manifest.yaml", max_bytes=MAX_MANIFEST_BYTES,
    ) or {}
    return Manifest(**data)


def read_config(path: str) -> dict[str, Any]:
    """Return the config dict stored in the can."""
    can_path = Path(path)
    if not is_under_cwd(can_path):
        raise ValueError(f"can path '{path}' is outside cwd - refusing")
    if not can_path.exists():
        raise FileNotFoundError(f"can not found: {path}")
    with tarfile.open(can_path, mode="r:gz") as tar:
        cfg_text = _read_text_member(tar, "config.yaml", MAX_CONFIG_BYTES)
    data = load_yaml_limited(cfg_text, "config.yaml", max_bytes=MAX_CONFIG_BYTES) or {}
    if not isinstance(data, dict):
        raise ValueError("config.yaml must deserialise to a mapping")
    return data


def _safe_extract(tar: tarfile.TarFile, dest: Path) -> None:
    """Extract ``tar`` into ``dest`` without escaping it.

    Uses tarfile's ``filter="data"`` on Python 3.12+. Security-related
    errors from that filter (``FilterError`` / subclasses of ``TarError``)
    are re-raised so malicious archives cannot slip through a fallback.
    On older Python where the filter kwarg is not supported, falls back
    to a manual commonpath + symlink check.
    """
    dest_real = os.path.realpath(str(dest))

    if hasattr(tarfile, "data_filter"):
        try:
            tar.extractall(dest, filter="data")
            return
        except (TypeError, AttributeError):
            # filter="data" not supported on this tarfile build — fall through
            # to manual check. Security-relevant TarError subclasses propagate.
            pass

    for member in tar.getmembers():
        if member.issym() or member.islnk():
            raise ValueError(
                f"symlinks / hardlinks are not allowed in .can files: {member.name}"
            )
        target_path = os.path.realpath(os.path.join(dest_real, member.name))
        try:
            common = os.path.commonpath([dest_real, target_path])
        except ValueError as exc:
            raise ValueError(
                f"tar entry '{member.name}' escapes destination"
            ) from exc
        if common != dest_real:
            raise ValueError(
                f"tar entry '{member.name}' escapes destination"
            )
        tar.extract(member, dest)


def extract_can(path: str, dest_dir: str) -> Path:
    """Extract the can into ``dest_dir`` safely."""
    can_path = Path(path)
    if not can_path.exists():
        raise FileNotFoundError(f"can not found: {path}")
    dest = Path(dest_dir)
    dest.mkdir(parents=True, exist_ok=True)
    with tarfile.open(can_path, mode="r:gz") as tar:
        _check_extract_bounds(tar)
        _safe_extract(tar, dest)
    return dest


def _check_extract_bounds(tar: tarfile.TarFile) -> None:
    """Refuse a can whose member count or total file size is over the limits.

    Runs before anything is written, so a refused can leaves no partial
    output. Iterates lazily so the count stops the header scan early.
    """
    count = 0
    total = 0
    for member in tar:
        count += 1
        if count > MAX_EXTRACT_MEMBERS:
            raise ValueError(
                f"can has too many members (> {MAX_EXTRACT_MEMBERS}); "
                "refusing to extract"
            )
        if member.isfile():
            total += member.size
            if total > MAX_EXTRACT_BYTES:
                raise ValueError(
                    f"can expands to more than {MAX_EXTRACT_BYTES} bytes; "
                    "refusing to extract"
                )