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.

Studio: read each gallery PNG's recipe once while it is unchanged and resolve only symlinked clips (#16355)

Daniel Han649cd1452b74
diff --git a/studio/backend/core/inference/image_gallery.py b/studio/backend/core/inference/image_gallery.py
index 78f1f86e52d..39acf31cab8 100644
--- a/studio/backend/core/inference/image_gallery.py
+++ b/studio/backend/core/inference/image_gallery.py
@@ -14,6 +14,7 @@ import re
import sys
import threading
import uuid
+from collections import OrderedDict
from collections.abc import Callable, Iterable, Iterator
from pathlib import Path
from typing import Any, Optional
@@ -268,21 +269,22 @@ def _record(
flags: Optional[dict[str, dict[str, Any]]] = None,
*,
directory: Optional[Path] = None,
+ mtime: Optional[float] = None,
) -> dict[str, Any]:
if directory is None:
directory = gallery_dir()
# flags are library state, not recipe: they come from the sidecar store, never the PNG chunk
if flags is None:
flags = gallery_flags.read(directory)
+ if mtime is None:
+ mtime = _mtime(directory / f"{image_id}.png")
return {
**meta,
"id": image_id,
"url": f"/api/inference/images/gallery/{image_id}/file",
**gallery_flags.flags_for(flags, image_id),
# The server's own sort key, so a client re-sort agrees with it (created_at can differ).
- "order_at": gallery_flags.order_rank(
- flags, image_id, _mtime(directory / f"{image_id}.png")
- ),
+ "order_at": gallery_flags.order_rank(flags, image_id, mtime),
}
@@ -310,19 +312,7 @@ def image_b64(image_id: str) -> Optional[str]:
_REQUIRED_META = ("prompt", "width", "height", "steps", "guidance", "seed", "created_at")
-def _read_meta(path: Path, *, strict_io: bool = False) -> Optional[dict[str, Any]]:
- from PIL import Image
-
- try:
- with Image.open(path) as im:
- # The chunk is written before IDAT; im.text would decode every pixel to find later chunks.
- raw = im.info.get(_META_KEY) or im.text.get(_META_KEY) # type: ignore[attr-defined]
- except OSError as exc:
- if strict_io and exc.errno not in (None, errno.ENOENT):
- raise
- return None
- except Exception:
- return None
+def _parse_meta(raw: Any) -> Optional[dict[str, Any]]:
if not raw:
return None
try:
@@ -334,6 +324,61 @@ def _read_meta(path: Path, *, strict_io: bool = False) -> Optional[dict[str, Any
return meta
+def _read_chunk(path: Path, *, strict_io: bool = False) -> tuple[Any, bool]:
+ """(raw recipe chunk or None, whether a retry could read something else)."""
+ from PIL import Image
+ try:
+ with Image.open(path) as im:
+ # The chunk is written before IDAT; im.text would decode every pixel to find later chunks.
+ return im.info.get(_META_KEY) or im.text.get(_META_KEY), False # type: ignore[attr-defined]
+ except OSError as exc:
+ if strict_io and exc.errno not in (None, errno.ENOENT):
+ raise
+ return None, True
+ except MemoryError:
+ return None, True
+ except Exception:
+ return None, False
+
+
+def _read_meta(path: Path, *, strict_io: bool = False) -> Optional[dict[str, Any]]:
+ return _parse_meta(_read_chunk(path, strict_io = strict_io)[0])
+
+
+_CHUNK_CACHE_MAX = 8192
+_CHUNK_CACHE_ITEM_MAX = 64 * 1024
+_CHUNK_CACHE_BYTES = 32 * 1024 * 1024
+_chunk_cache: OrderedDict[str, tuple[tuple, Any, int]] = OrderedDict()
+_chunk_cache_bytes = 0
+_chunk_cache_lock = threading.Lock()
+
+
+def _listed_meta(path: Path, info: Optional[os.stat_result]) -> Optional[dict[str, Any]]:
+ """``_read_meta(path)``, reparsed only once the file changed since ``info`` (stat taken before)."""
+ if info is None:
+ return _read_meta(path)
+ # A write moves mtime or ctime and a replace the inode, so a key that agrees means the same bytes.
+ key = (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns)
+ name = str(path)
+ with _chunk_cache_lock:
+ hit = _chunk_cache.get(name)
+ if hit is not None and hit[0] == key:
+ _chunk_cache.move_to_end(name)
+ return _parse_meta(hit[1])
+ raw, transient = _read_chunk(path)
+ size = len(raw) if isinstance(raw, (str, bytes)) else 0
+ if transient or size > _CHUNK_CACHE_ITEM_MAX:
+ return _parse_meta(raw)
+ global _chunk_cache_bytes
+ with _chunk_cache_lock:
+ old = _chunk_cache.pop(name, None)
+ _chunk_cache[name] = (key, raw, size)
+ _chunk_cache_bytes += size - (old[2] if old else 0)
+ while len(_chunk_cache) > _CHUNK_CACHE_MAX or _chunk_cache_bytes > _CHUNK_CACHE_BYTES:
+ _chunk_cache_bytes -= _chunk_cache.popitem(last = False)[1][2]
+ return _parse_meta(raw)
+
+
def owned_image_path(image_id: str) -> Optional[Path]:
"""Returns None unless the PNG is Unsloth-owned, so a guessed id cannot stream a hand-dropped file."""
path = image_path(image_id)
@@ -380,10 +425,20 @@ def list_images(
flags = gallery_flags.read(directory)
# Shelf split and pin sort use file stems before any recipe read, keeping the early break intact.
paths = [p for p in paths if gallery_flags.is_archived(flags, p.stem) == archived]
+ # The sort's stat keys the recipe read, so it must precede it.
+ stats: dict[Path, os.stat_result] = {}
+
+ def mtime(path: Path) -> float:
+ try:
+ stats[path] = info = path.stat()
+ except OSError:
+ return 0.0
+ return info.st_mtime
+
paths.sort(
key = lambda p: (
gallery_flags.pin_rank(flags, p.stem),
- gallery_flags.order_rank(flags, p.stem, _mtime(p)),
+ gallery_flags.order_rank(flags, p.stem, mtime(p)),
),
reverse = True,
)
@@ -391,10 +446,17 @@ def list_images(
want = None if limit is None else offset + limit
records = []
for path in paths:
- meta = _read_meta(path)
+ info = stats.get(path)
+ meta = _listed_meta(path, info)
if meta is None:
continue
- record = _record(path.stem, meta, flags, directory = directory)
+ record = _record(
+ path.stem,
+ meta,
+ flags,
+ directory = directory,
+ mtime = None if info is None else info.st_mtime,
+ )
if valid is not None and not valid(record):
continue
records.append(record)
diff --git a/studio/backend/core/inference/video_gallery.py b/studio/backend/core/inference/video_gallery.py
index fb01de253f9..9cec82e6c9b 100644
--- a/studio/backend/core/inference/video_gallery.py
+++ b/studio/backend/core/inference/video_gallery.py
@@ -8,6 +8,7 @@ from __future__ import annotations
import json
import os
import re
+import stat
import threading
import uuid
from collections.abc import Callable
@@ -191,6 +192,15 @@ def video_path(video_id: str, directory: Optional[Path] = None) -> Optional[Path
if directory is None:
directory = gallery_dir()
path = directory / f"{video_id}.mp4"
+ try:
+ mode = path.lstat().st_mode
+ except OSError:
+ return None
+ # A plain file named by a safe id cannot lead out of the folder; a symlink takes the full check.
+ if stat.S_ISREG(mode):
+ return path
+ if not stat.S_ISLNK(mode):
+ return None
try:
path.resolve().relative_to(directory.resolve())
except ValueError:
diff --git a/studio/backend/tests/test_gallery_listing_reads.py b/studio/backend/tests/test_gallery_listing_reads.py
new file mode 100644
index 00000000000..0fd980cf41b
--- /dev/null
+++ b/studio/backend/tests/test_gallery_listing_reads.py
@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Image listing rereads a PNG chunk only on change; video listing resolves only symlinked clips."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+
+import pytest
+
+import core.inference.image_gallery as images
+import core.inference.video_gallery as videos
+
+PIL = pytest.importorskip("PIL")
+from PIL import Image, PngImagePlugin # noqa: E402
+
+
[email protected](autouse = True)
+def _tmp_gallery(monkeypatch, tmp_path):
+ monkeypatch.setattr(images, "studio_root", lambda: tmp_path)
+ monkeypatch.setattr(videos, "studio_root", lambda: tmp_path)
+ if hasattr(images, "_chunk_cache"):
+ monkeypatch.setattr(images, "_chunk_cache", type(images._chunk_cache)())
+ monkeypatch.setattr(images, "_chunk_cache_bytes", 0)
+
+
+def _meta(**over):
+ base = {
+ "prompt": "a sloth",
+ "width": 16,
+ "height": 16,
+ "steps": 4,
+ "guidance": 0.0,
+ "seed": 7,
+ "created_at": 100.0,
+ }
+ base.update(over)
+ return base
+
+
+def _png(
+ path: Path,
+ meta = None,
+ raw = None,
+) -> None:
+ info = PngImagePlugin.PngInfo()
+ if raw is not None or meta is not None:
+ info.add_text(images._META_KEY, raw if raw is not None else json.dumps(meta))
+ Image.new("RGB", (8, 8), (1, 2, 3)).save(path, format = "PNG", pnginfo = info)
+
+
+def _count_opens(monkeypatch) -> list:
+ opened = []
+ real = Image.open
+
+ def counting(fp, *args, **kwargs):
+ opened.append(fp)
+ return real(fp, *args, **kwargs)
+
+ monkeypatch.setattr(Image, "open", counting)
+ return opened
+
+
+def test_an_unchanged_png_is_parsed_once(monkeypatch):
+ for k in range(3):
+ images.save(Image.new("RGB", (8, 8)), _meta(seed = k))
+ first = images.list_images()
+ opened = _count_opens(monkeypatch)
+ assert images.list_images() == first
+ assert opened == []
+
+
+def test_listed_records_are_fresh_dicts():
+ images.save(Image.new("RGB", (8, 8)), _meta())
+ first = images.list_images()
+ first[0]["prompt"] = "changed"
+ assert images.list_images()[0]["prompt"] == "a sloth"
+
+
+def test_a_rewritten_png_is_read_again_even_at_the_same_mtime():
+ record = images.save(Image.new("RGB", (8, 8)), _meta(prompt = "before"))
+ path = images.gallery_dir() / f"{record['id']}.png"
+ assert images.list_images()[0]["prompt"] == "before"
+ before = path.stat()
+ _png(path, _meta(prompt = "after, longer"))
+ os.utime(path, ns = (before.st_atime_ns, before.st_mtime_ns))
+ assert images.list_images()[0]["prompt"] == "after, longer"
+
+
+def test_a_replaced_png_is_read_again():
+ record = images.save(Image.new("RGB", (8, 8)), _meta(prompt = "before"))
+ path = images.gallery_dir() / f"{record['id']}.png"
+ assert images.list_images()[0]["prompt"] == "before"
+ tmp = path.with_name(".swap.tmp")
+ _png(tmp, _meta(prompt = "after"))
+ os.replace(tmp, path)
+ assert images.list_images()[0]["prompt"] == "after"
+
+
[email protected]("content", ["no chunk", "not json", "missing key", "not a png"])
+def test_a_foreign_png_stays_skipped_until_it_becomes_ours(content):
+ directory = images.gallery_dir()
+ path = directory / "foreign.png"
+ if content == "no chunk":
+ _png(path)
+ elif content == "not json":
+ _png(path, raw = "{oops")
+ elif content == "missing key":
+ _png(path, {k: v for k, v in _meta().items() if k != "seed"})
+ else:
+ path.write_bytes(b"\x89PNG not really")
+ assert images.list_images() == [] and images.list_images() == []
+ _png(path, _meta(prompt = "now ours"))
+ assert [r["prompt"] for r in images.list_images()] == ["now ours"]
+
+
+def test_a_deleted_png_leaves_the_listing():
+ record = images.save(Image.new("RGB", (8, 8)), _meta())
+ assert len(images.list_images()) == 1
+ assert images.delete(record["id"])
+ assert images.list_images() == []
+
+
+def test_the_chunk_cache_is_bounded(monkeypatch):
+ monkeypatch.setattr(images, "_CHUNK_CACHE_MAX", 2)
+ for k in range(5):
+ images.save(Image.new("RGB", (8, 8)), _meta(seed = k))
+ first = images.list_images()
+ assert len(images._chunk_cache) == 2
+ assert images.list_images() == first and len(first) == 5
+
+
+def test_a_huge_chunk_is_read_but_not_kept(monkeypatch):
+ monkeypatch.setattr(images, "_CHUNK_CACHE_ITEM_MAX", 600)
+ images.save(Image.new("RGB", (8, 8)), _meta(prompt = "x" * 1000))
+ images.save(Image.new("RGB", (8, 8)), _meta(prompt = "short"))
+ assert sorted(r["prompt"] for r in images.list_images()) == ["short", "x" * 1000]
+ assert len(images._chunk_cache) == 1
+ assert sorted(r["prompt"] for r in images.list_images()) == ["short", "x" * 1000]
+
+
+def test_the_chunk_cache_holds_a_byte_budget(monkeypatch):
+ monkeypatch.setattr(images, "_CHUNK_CACHE_BYTES", 1000)
+ for k in range(5):
+ images.save(Image.new("RGB", (8, 8)), _meta(prompt = "p" * 300, seed = k))
+ first = images.list_images()
+ assert 0 < len(images._chunk_cache) < 5
+ assert images._chunk_cache_bytes == sum(v[2] for v in images._chunk_cache.values()) <= 1000
+ assert images.list_images() == first and len(first) == 5
+
+
+def test_concurrent_listings_agree(monkeypatch):
+ for k in range(20):
+ images.save(Image.new("RGB", (8, 8)), _meta(seed = k))
+ expected = images.list_images()
+ if hasattr(images, "_chunk_cache"):
+ monkeypatch.setattr(images, "_chunk_cache", type(images._chunk_cache)())
+ monkeypatch.setattr(images, "_chunk_cache_bytes", 0)
+ results, errors = [], []
+
+ def run():
+ try:
+ for _ in range(5):
+ results.append(images.list_images())
+ except Exception as exc: # pragma: no cover - reported below
+ errors.append(exc)
+
+ threads = [threading.Thread(target = run) for _ in range(8)]
+ for t in threads:
+ t.start()
+ for t in threads:
+ t.join()
+ assert errors == [] and all(r == expected for r in results) and len(results) == 40
+
+
+def test_delete_still_raises_on_an_unreadable_png(monkeypatch):
+ record = images.save(Image.new("RGB", (8, 8)), _meta())
+ images.list_images()
+
+ def refuse(*args, **kwargs):
+ raise PermissionError(13, "denied")
+
+ monkeypatch.setattr(Image, "open", refuse)
+ with pytest.raises(PermissionError):
+ images.delete(record["id"])
+
+
+def _clip(directory: Path, video_id: str) -> Path:
+ path = directory / f"{video_id}.mp4"
+ path.write_bytes(b"\x00\x00\x00\x18ftypmp42")
+ return path
+
+
+def test_a_plain_clip_is_found_without_resolving(monkeypatch):
+ directory = videos.gallery_dir()
+ path = _clip(directory, "plain")
+
+ def no_resolve(self, *args, **kwargs):
+ raise AssertionError("resolve() on a plain clip")
+
+ monkeypatch.setattr(Path, "resolve", no_resolve)
+ monkeypatch.setattr(type(path), "resolve", no_resolve)
+ assert videos.video_path("plain") == path
+ assert videos.video_path("plain", directory) == path
+
+
+def test_video_path_misses():
+ directory = videos.gallery_dir()
+ (directory / "folder.mp4").mkdir()
+ assert videos.video_path("folder") is None
+ assert videos.video_path("absent") is None
+ assert videos.video_path("../escape") is None
+ assert videos.video_path("") is None
+
+
+def test_symlinked_clips_still_take_the_full_check(tmp_path):
+ directory = videos.gallery_dir()
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ (outside / "far.mp4").write_bytes(b"x")
+ try:
+ (directory / "escape.mp4").symlink_to(outside / "far.mp4")
+ except (OSError, NotImplementedError):
+ pytest.skip("this account cannot create symlinks")
+ (directory / "inner.bin").write_bytes(b"y")
+ (directory / "inside.mp4").symlink_to(directory / "inner.bin")
+ (directory / "dangling.mp4").symlink_to(directory / "nothing")
+ (directory / "subdir").mkdir()
+ (directory / "todir.mp4").symlink_to(directory / "subdir")
+ assert videos.video_path("escape") is None
+ assert videos.video_path("inside") == directory / "inside.mp4"
+ assert videos.video_path("dangling") is None
+ assert videos.video_path("todir") is None