astrbot_plugin_imagestudio/core/storage.py

296 行
10 KiB
Python

2026-07-05 09:14:32 +08:00
"""VFS storage helpers."""
from __future__ import annotations
2026-07-05 21:46:07 +08:00
import shutil
2026-07-05 09:14:32 +08:00
from dataclasses import dataclass
2026-07-06 03:18:33 +08:00
from datetime import datetime, timezone
2026-07-05 09:14:32 +08:00
from pathlib import Path
from typing import Any
from backend.dto.common import ApiError, ErrorCode
from core.config_service import ConfigService, ImageStudioConfig
from core.runtime_paths import (
EXTERNAL_ROOTS_ENV_VAR,
external_storage_roots_allowed,
resolve_data_path,
)
2026-07-05 09:14:32 +08:00
@dataclass(frozen=True)
class VfsEntry:
root: str
uri_prefix: str
exists: bool
writable: bool
bytes: int
def to_dict(self) -> dict[str, Any]:
return {
"root": self.root,
"uri_prefix": self.uri_prefix,
"exists": self.exists,
"writable": self.writable,
"bytes": self.bytes,
}
class VfsStorage:
def __init__(self, config_service: ConfigService | None = None):
self.config_service = config_service or ConfigService()
def status(self) -> dict[str, Any]:
roots = [self._entry(root, path) for root, path in self._root_paths().items()]
return {
"roots": [entry.to_dict() for entry in roots],
"total_bytes": sum(entry.bytes for entry in roots),
}
def migration_plan(
self,
source_uri: str,
target_uri: str,
*,
dry_run: bool = True,
allow_overwrite: bool = False,
) -> dict[str, Any]:
2026-07-05 18:54:05 +08:00
source_path = self.resolve_uri(source_uri)
target_path = self.resolve_uri(target_uri)
2026-07-05 18:54:05 +08:00
if not source_path.exists():
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "source media not found", {"uri": source_uri})
files, total_bytes = _path_file_stats(source_path)
2026-07-05 21:46:07 +08:00
will_overwrite = target_path.exists()
if not dry_run:
# ``will_overwrite`` used to be reported and then ignored, so a
# non-dry-run migrate silently clobbered whatever sat at the target
# (``shutil.copy2`` overwrites without asking). Require the caller
# to acknowledge the overwrite explicitly.
if will_overwrite and not allow_overwrite:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"target already exists; retry with allow_overwrite=true to replace it",
{"target_uri": target_uri, "will_overwrite": True},
)
2026-07-05 21:46:07 +08:00
_copy_path(source_path, target_path)
2026-07-05 18:54:05 +08:00
return {
2026-07-05 21:46:07 +08:00
"dry_run": dry_run,
"status": "planned" if dry_run else "completed",
2026-07-05 18:54:05 +08:00
"source_uri": source_uri,
"target_uri": target_uri,
"files": files,
"bytes": total_bytes,
2026-07-05 21:46:07 +08:00
"will_overwrite": will_overwrite,
"execution_enabled": True,
2026-07-05 18:54:05 +08:00
}
2026-07-06 03:18:33 +08:00
def index_files(self, *, root: str | None = None, limit: int = 500) -> dict[str, Any]:
roots = self._root_paths()
if root and root not in roots:
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"root": root})
selected_roots = [root] if root else sorted(roots)
normalized_limit = min(max(int(limit or 500), 1), 5000)
items: list[dict[str, Any]] = []
total = 0
for root_name in selected_roots:
root_path = resolve_data_path(roots[root_name]).resolve()
2026-07-06 03:18:33 +08:00
if not root_path.exists():
continue
for path in sorted(root_path.rglob("*")):
if not path.is_file():
continue
total += 1
if len(items) >= normalized_limit:
continue
relative = path.relative_to(root_path).as_posix()
items.append(
{
"root": root_name,
"uri": f"storage://{root_name}/{relative}",
"bytes": path.stat().st_size,
"modified_at": datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).isoformat(),
}
)
return {
"root": root,
"limit": normalized_limit,
"total": total,
"truncated": total > len(items),
"items": items,
}
2026-07-05 09:14:32 +08:00
def resolve_uri(self, uri: str) -> Path:
root, relative = self.split_uri(uri)
root_path = self._root_paths().get(root)
if root_path is None:
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"uri": uri, "root": root})
resolved_root = resolve_data_path(root_path).resolve()
2026-07-05 09:14:32 +08:00
resolved_path = (resolved_root / relative).resolve()
if resolved_path != resolved_root and resolved_root not in resolved_path.parents:
raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri})
return resolved_path
def ensure_file(self, uri: str) -> Path:
path = self.resolve_uri(uri)
if not path.exists() or not path.is_file():
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "media file not found", {"uri": uri})
return path
def split_uri(self, uri: str) -> tuple[str, Path]:
if not uri.startswith("storage://"):
raise ApiError(ErrorCode.VALIDATION_FAILED, "uri must use storage://", {"field": "uri"})
rest = uri[len("storage://") :]
if "/" not in rest:
raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri})
root, relative = rest.split("/", 1)
if not root or not relative:
raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri})
relative_path = Path(relative)
if relative_path.is_absolute() or ".." in relative_path.parts:
raise ApiError(ErrorCode.FORBIDDEN, "storage uri contains an unsafe path", {"uri": uri})
return root, relative_path
def _entry(self, root: str, path: str) -> VfsEntry:
resolved = resolve_data_path(path)
2026-07-05 09:14:32 +08:00
return VfsEntry(
root=root,
uri_prefix=f"storage://{root}/",
exists=resolved.exists(),
writable=_is_writable(resolved),
bytes=_directory_size(resolved),
)
def _root_paths(self) -> dict[str, str]:
config = self.config_service.load()
roots = _storage_roots(config)
assert_storage_roots_contained(roots)
return roots
def assert_storage_roots_contained(roots: dict[str, str]) -> None:
"""Refuse storage roots that are too broad to be a sandbox boundary.
``VfsStorage.resolve_uri`` guarantees a URI cannot escape *its own root* —
which is worth nothing when the root itself is ``/`` or ``C:\\``. Pointing
a root at a filesystem anchor or a system directory turns ``media/index``
and ``media/sign`` into a host-wide file browser.
Deliberately narrower than "must live under the data root": mounting
storage on a dedicated external volume is a legitimate deployment (and how
the test-suite isolates fixtures). The write path
(``SettingsService.validate``) is where containment is enforced, because
that is the attacker-reachable surface; this is defence in depth against a
config that arrived some other way.
"""
if external_storage_roots_allowed():
return
unsafe = sorted(name for name, path in roots.items() if _is_overbroad_root(path))
if unsafe:
raise ApiError(
ErrorCode.FORBIDDEN,
"storage root escapes the runtime data root",
{
"roots": unsafe,
"hint": (
"point the root at a dedicated directory, or set "
f"{EXTERNAL_ROOTS_ENV_VAR}=1 to allow an external mount"
),
},
)
# Directories that can never be a dedicated media root. Matching is done on the
# resolved path so ``data/../..`` style traversal collapses first.
_SYSTEM_ROOTS = (
"/etc",
"/root",
"/boot",
"/proc",
"/sys",
"/dev",
"/var",
"/usr",
"/bin",
"/sbin",
"c:/windows",
"c:/program files",
"c:/program files (x86)",
)
def _is_overbroad_root(path: str) -> bool:
try:
resolved = resolve_data_path(path).resolve()
except OSError:
return False
# A filesystem anchor ("/", "C:\\") is its own parent.
if resolved.parent == resolved:
return True
normalized = resolved.as_posix().rstrip("/").lower()
return any(
normalized == system or normalized.startswith(f"{system}/")
for system in _SYSTEM_ROOTS
)
2026-07-05 09:14:32 +08:00
def _storage_roots(config: ImageStudioConfig) -> dict[str, str]:
return {
"images": config.storage.images_path,
"thumbnails": config.storage.thumbnails_path,
"materials": config.storage.materials_path,
"advanced_materials": config.storage.advanced_materials_path,
2026-07-05 09:14:32 +08:00
"styles": config.storage.styles_path,
"archives": config.storage.archives_path,
"temp": config.storage.temp_path,
}
def _directory_size(path: Path) -> int:
if not path.exists():
return 0
total = 0
for child in path.rglob("*"):
if child.is_file():
total += child.stat().st_size
return total
2026-07-05 18:54:05 +08:00
def _path_file_stats(path: Path) -> tuple[int, int]:
if path.is_file():
return 1, path.stat().st_size
if path.is_dir():
files = 0
total = 0
for child in path.rglob("*"):
if child.is_file():
files += 1
total += child.stat().st_size
return files, total
return 0, 0
2026-07-05 21:46:07 +08:00
def _copy_path(source_path: Path, target_path: Path) -> None:
if source_path.is_file():
target_path.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(source_path, target_path)
return
source_root = source_path.resolve()
target_root = target_path.resolve()
if target_root == source_root or source_root in target_root.parents:
raise ApiError(ErrorCode.FORBIDDEN, "target path cannot be inside source directory")
target_root.mkdir(parents=True, exist_ok=True)
for child in source_root.rglob("*"):
if not child.is_file():
continue
relative = child.relative_to(source_root)
destination = target_root / relative
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(child, destination)
2026-07-05 09:14:32 +08:00
def _is_writable(path: Path) -> bool:
target = path if path.exists() else path.parent
return target.exists() and target.is_dir()