Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

11.5 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Per-repo partial verdict of the local model listing, kept across requests.

Every writer of what the verdict reads (huggingface_hub, the Studio download worker, a delete)
creates, renames or unlinks a directory entry, so a verdict is kept with stats of: the repo dir,
``snapshots/``, ``blobs/``, ``refs/`` and every snapshot subdir; every file under ``refs/`` and in a
snapshot, and link targets outside ``blobs/`` (rewritable in place); shared-store blobs and their dir;
and a per-scan token over the whole Hub state tree. Nothing is stored on a non-ENOENT stat error, a
too-recent timestamp, a signature moved during compute, an invalidation meanwhile, or a linked
directory. Linux local filesystems that move directory mtimes only; entries expire after a minute.
"""

from __future__ import annotations

import os
import sys
import threading
import time
from collections import OrderedDict
from pathlib import Path
from typing import Callable, Hashable, NamedTuple, Optional

from utils.scan_memo import memoized, scan_memo_active

_MAX_ENTRIES = 4096
# A change inside this window of the signature can share its timestamp (coarse clocks, FAT 2 s).
_RACY_NS = 3_000_000_000
# Bounds a wrong verdict from a transient OSError (EMFILE, EIO) the checks swallow.
_MAX_AGE_NS = 60_000_000_000
_ABSENT_ERRNOS = frozenset({2, 20})  # ENOENT, ENOTDIR
# Local filesystems whose directory mtime moves on every create, rename and unlink in it.
_TRUSTED_FS_TYPES = frozenset(
    {
        "ext2",
        "ext3",
        "ext4",
        "xfs",
        "btrfs",
        "zfs",
        "f2fs",
        "bcachefs",
        "jfs",
        "nilfs2",
        "reiserfs",
        "tmpfs",
        "ramfs",
        "overlay",
    }
)

_lock = threading.Lock()
_entries: "OrderedDict[Hashable, _Entry]" = OrderedDict()
_generation = 0
_last_token: Optional[tuple] = None


class _Unstable(Exception):
    """A stat failed for a reason other than absence; nothing is cached or served."""


class _Entry(NamedTuple):
    verdict: bool
    token: tuple
    dirs: tuple
    files: tuple
    signature: tuple
    stored_ns: int


def enabled() -> bool:
    return sys.platform.startswith("linux")


def _mount_fs_types() -> dict[tuple[int, int], set[str]]:
    types: dict[tuple[int, int], set[str]] = {}
    with open("/proc/self/mountinfo", encoding = "utf-8", errors = "replace") as handle:
        for line in handle:
            fields = line.split()
            try:
                major, minor = fields[2].split(":")
                fs_type = fields[fields.index("-", 6) + 1]
            except (IndexError, ValueError):
                continue
            types.setdefault((int(major), int(minor)), set()).add(fs_type)
    return types


def _trusted_devices(devices: set[int]) -> bool:
    """Whether every device is a mount of a trusted filesystem, read once per scan."""
    try:
        types = memoized(("partial_verdict_mount_types",), _mount_fs_types)
    except (OSError, ValueError):
        return False
    for dev in devices:
        found = types.get((os.major(dev), os.minor(dev)))
        # A device mounted twice with different types, or not listed at all, is not vouched for.
        if not found or len(found) != 1 or not found <= _TRUSTED_FS_TYPES:
            return False
    return True


def _devices(stats) -> set[int]:
    return {s[0] for s in stats if s is not None}


def invalidate() -> None:
    global _generation
    with _lock:
        _generation += 1
        _entries.clear()


def _stat(path: str) -> Optional[tuple]:
    try:
        st = os.stat(path)
    except OSError as exc:
        if exc.errno in _ABSENT_ERRNOS:
            return None
        raise _Unstable from exc
    except ValueError as exc:
        raise _Unstable from exc
    return (st.st_dev, st.st_ino, st.st_mode, st.st_size, st.st_mtime_ns, st.st_ctime_ns)


def _scandir(path: str) -> list:
    try:
        with os.scandir(path) as it:
            return list(it)
    except OSError as exc:
        if exc.errno in _ABSENT_ERRNOS:
            return []
        raise _Unstable from exc


def _newest(stats) -> int:
    return max((max(s[4], s[5]) for s in stats if s is not None), default = 0)


def _compute_token() -> Optional[tuple]:
    from hub.utils import state_dir

    try:
        from utils.hf_cache_settings import get_hf_cache_paths
        configured = os.fspath(get_hf_cache_paths().hub_cache)
    except Exception:
        configured = None
    try:
        root = state_dir.state_root()
        if root is None:
            return None
        items = []
        pending = [os.path.join(os.fspath(root), name) for name in ("manifests", "cancelled")]
        while pending:
            directory = pending.pop()
            items.append((directory, _stat(directory)))
            for entry in _scandir(directory):
                if entry.is_dir(follow_symlinks = False):
                    pending.append(entry.path)
                else:
                    items.append((entry.path, _stat(entry.path)))
        hub_real = os.path.realpath(configured) if configured else None
    except (_Unstable, OSError):
        return None
    items.sort()
    return (os.fspath(root), configured, hub_real, tuple(items))


def scan_token() -> Optional[tuple]:
    """The Hub state token for this scan, taken once; call it before the state is first read."""
    if not enabled() or not scan_memo_active():
        return None
    return memoized(("partial_verdict_token",), _scan_token_uncached)


def _scan_token_uncached() -> Optional[tuple]:
    global _last_token
    start_ns = time.time_ns()
    token = _compute_token()
    if token is None:
        return None
    stats = [stat for _path, stat in token[3]]
    # Too fresh, or untrusted directory mtimes: this scan neither stores nor serves.
    if _newest(stats) > start_ns - _RACY_NS or not _trusted_devices(_devices(stats)):
        return None
    with _lock:
        # Interned, so entries compare by identity.
        if token == _last_token:
            return _last_token
        _last_token = token
        return token


def _walk_repo(repo_dir: str) -> Optional[tuple[tuple, tuple]]:
    """Directories and files whose stats decide the verdict; None when the layout cannot be vouched for."""
    blobs = os.path.join(repo_dir, "blobs")
    snapshots = os.path.join(repo_dir, "snapshots")
    refs = os.path.join(repo_dir, "refs")
    # Snapshot links resolve from where snapshots/ really is, so a linked one points them at blobs this walk would not stat.
    if os.path.islink(snapshots):
        return None
    dirs = [repo_dir, snapshots, blobs, refs]
    files: list[str] = []
    pending = [refs]
    while pending:
        directory = pending.pop()
        for entry in _scandir(directory):
            if entry.is_symlink():
                return None
            if entry.is_dir(follow_symlinks = False):
                dirs.append(entry.path)
                pending.append(entry.path)
            else:
                files.append(entry.path)
    blob_entries: Optional[dict[str, os.DirEntry]] = None
    blobs_real: Optional[str] = None
    linked_blobs: set[str] = set()
    for snapshot in _scandir(snapshots):
        if snapshot.is_symlink():
            return None
        if not snapshot.is_dir(follow_symlinks = False):
            files.append(snapshot.path)
            continue
        dirs.append(snapshot.path)
        pending = [snapshot.path]
        while pending:
            directory = pending.pop()
            for entry in _scandir(directory):
                if entry.is_symlink():
                    try:
                        target = os.readlink(entry.path)
                    except OSError:
                        raise _Unstable from None
                    target = os.path.normpath(os.path.join(directory, target))
                    parent = os.path.dirname(target)
                    if parent == blobs:
                        if blob_entries is None:
                            # One listing answers every link; an absent name is a broken link.
                            blob_entries = {blob.name: blob for blob in _scandir(blobs)}
                        blob = blob_entries.get(os.path.basename(target))
                        if blob is None or blob.path in linked_blobs:
                            continue
                        if blob.is_symlink():
                            # Shared store (<hub>/blobs/<xx>/<xet hash>), sweepable from another repo; resolved from the real blobs/.
                            linked_blobs.add(blob.path)
                            try:
                                shared = os.readlink(blob.path)
                            except OSError:
                                raise _Unstable from None
                            if blobs_real is None:
                                blobs_real = os.path.realpath(blobs)
                            shared = os.path.normpath(os.path.join(blobs_real, shared))
                            if os.path.islink(shared) or os.path.isdir(shared):
                                return None
                            dirs.append(os.path.dirname(shared))
                            files.append(shared)
                        elif blob.is_dir(follow_symlinks = False):
                            return None
                    else:
                        if os.path.islink(target) or os.path.isdir(target):
                            return None
                        dirs.append(parent)
                        files.append(target)
                elif entry.is_dir(follow_symlinks = False):
                    dirs.append(entry.path)
                    pending.append(entry.path)
                else:
                    files.append(entry.path)
    return tuple(dict.fromkeys(dirs)), tuple(dict.fromkeys(files))


def _signature(dirs: tuple, files: tuple) -> tuple:
    return tuple(_stat(p) for p in dirs) + tuple(_stat(p) for p in files)


def cached_verdict(key: Hashable, repo_dir: Path, compute: Callable[[], bool]) -> bool:
    """compute()'s verdict for *repo_dir*, reused while nothing it reads has changed."""
    token = scan_token()
    if token is None:
        return compute()
    repo = os.path.normpath(os.fspath(repo_dir))
    key = (key, repo)
    now = time.time_ns()
    with _lock:
        entry = _entries.get(key)
        generation = _generation
    if entry is not None and entry.token is token and now - entry.stored_ns < _MAX_AGE_NS:
        try:
            if _signature(entry.dirs, entry.files) == entry.signature:
                with _lock:
                    if key in _entries:
                        _entries.move_to_end(key)
                return entry.verdict
        except _Unstable:
            return compute()
    try:
        walked = _walk_repo(repo)
        before = _signature(*walked) if walked is not None else None
    except _Unstable:
        walked = before = None
    verdict = compute()
    if walked is None or before is None or _newest(before) > now - _RACY_NS:
        return verdict
    if not _trusted_devices(_devices(before)):
        return verdict
    try:
        if _signature(*walked) != before:
            return verdict
    except _Unstable:
        return verdict
    with _lock:
        if generation != _generation:
            return verdict
        _entries[key] = _Entry(verdict, token, walked[0], walked[1], before, now)
        _entries.move_to_end(key)
        while len(_entries) > _MAX_ENTRIES:
            _entries.popitem(last = False)
    return verdict