455 行
17 KiB
Python
455 行
17 KiB
Python
"""Planning and guarded execution skeleton for ImageStudio asset pack imports."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import hashlib
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
from backend.dto.common import ApiError, ErrorCode
|
|
from backend.services.material_service import MaterialService
|
|
from core.config_service import ConfigService
|
|
from core.identity import RequestContext
|
|
from core.storage import VfsStorage
|
|
|
|
|
|
_MANIFEST_FILENAMES = {"manifest.json", "imagestudio-pack.json", "pack.json"}
|
|
_MANIFEST_FILENAME_PRIORITY = {
|
|
"imagestudio-pack.json": 0,
|
|
"manifest.json": 1,
|
|
"pack.json": 2,
|
|
}
|
|
|
|
|
|
class AssetImportService:
|
|
def __init__(
|
|
self,
|
|
config_service: ConfigService | None = None,
|
|
material_service: MaterialService | None = None,
|
|
):
|
|
self.storage = VfsStorage(config_service)
|
|
self.material_service = material_service
|
|
|
|
def plan_import_pack(
|
|
self,
|
|
package_uri: str,
|
|
*,
|
|
dry_run: bool = True,
|
|
allow_overwrite: bool = False,
|
|
ctx: RequestContext | None = None,
|
|
) -> dict[str, Any]:
|
|
root, relative = self.storage.split_uri(package_uri)
|
|
package_path = self.storage.resolve_uri(package_uri)
|
|
if not package_path.exists():
|
|
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "asset pack not found", {"uri": package_uri})
|
|
|
|
files, total_bytes = _path_file_stats(package_path)
|
|
manifest_candidates = _manifest_candidates(root, relative, package_path)
|
|
manifest_summary = _manifest_summary(package_path, manifest_candidates)
|
|
applied = {"materials": 0, "styles": 0, "material_ids": [], "created": 0, "updated": 0}
|
|
unsupported_features = []
|
|
if manifest_summary["styles"]:
|
|
unsupported_features.append(
|
|
{
|
|
"code": "STYLE_IMPORT_UNSUPPORTED",
|
|
"message": "style entries are not imported by the current asset-pack service",
|
|
"count": manifest_summary["styles"],
|
|
}
|
|
)
|
|
if not dry_run and not manifest_summary["valid"]:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack manifest is invalid",
|
|
{"field": "manifest", "errors": manifest_summary["errors"]},
|
|
)
|
|
if not dry_run and unsupported_features:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack contains unsupported entries",
|
|
{"field": "styles", "unsupported_features": unsupported_features},
|
|
)
|
|
if not dry_run:
|
|
if self.material_service is None or ctx is None:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack import execution is unavailable",
|
|
{"field": "material_service"},
|
|
)
|
|
applied = self._apply_manifest(
|
|
package_uri,
|
|
root,
|
|
relative,
|
|
package_path,
|
|
manifest_candidates[0],
|
|
ctx,
|
|
allow_overwrite=allow_overwrite,
|
|
)
|
|
return {
|
|
"dry_run": dry_run,
|
|
"status": "planned" if dry_run else "applied",
|
|
"package_uri": package_uri,
|
|
"files": files,
|
|
"bytes": total_bytes,
|
|
"manifest_candidates": [item["uri"] for item in manifest_candidates],
|
|
"manifest": manifest_summary,
|
|
"import_enabled": manifest_summary["valid"] and not unsupported_features,
|
|
"execution_enabled": manifest_summary["valid"] and not unsupported_features,
|
|
"unsupported_features": unsupported_features,
|
|
"applied": applied,
|
|
}
|
|
|
|
def _apply_manifest(
|
|
self,
|
|
package_uri: str,
|
|
root: str,
|
|
relative: Path,
|
|
package_path: Path,
|
|
manifest: dict[str, Any],
|
|
ctx: RequestContext,
|
|
*,
|
|
allow_overwrite: bool = False,
|
|
) -> dict[str, Any]:
|
|
payload = _load_manifest_payload(manifest["path"])
|
|
if _list_count(payload.get("styles")):
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"style entries are not supported by asset pack import",
|
|
{"field": "styles"},
|
|
)
|
|
material_ids: list[str] = []
|
|
created_count = 0
|
|
updated_count = 0
|
|
base_relative = relative if package_path.is_dir() else relative.parent
|
|
planned_materials: list[tuple[dict[str, Any], bool]] = []
|
|
planned_material_ids: set[str] = set()
|
|
for index, item in enumerate(payload.get("materials") or []):
|
|
if not isinstance(item, dict):
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack material entries must be objects",
|
|
{"field": f"materials[{index}]"},
|
|
)
|
|
material_payload = _material_payload_from_manifest_item(
|
|
item,
|
|
root=root,
|
|
base_relative=base_relative,
|
|
package_uri=package_uri,
|
|
manifest_uri=manifest["uri"],
|
|
index=index,
|
|
)
|
|
material_id = str(material_payload["material_id"])
|
|
if material_id in planned_material_ids:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack contains duplicate material IDs",
|
|
{"field": f"materials[{index}].material_id", "material_id": material_id},
|
|
)
|
|
planned_material_ids.add(material_id)
|
|
self.storage.ensure_file(material_payload["image_uri"])
|
|
if material_payload.get("thumbnail_uri"):
|
|
self.storage.ensure_file(material_payload["thumbnail_uri"])
|
|
existing = self.material_service.repository.get_material(material_payload["material_id"])
|
|
if existing is not None:
|
|
self.material_service.get_material(material_payload["material_id"])
|
|
self.material_service.validate_material_payload(material_payload, creating=existing is None)
|
|
planned_materials.append((material_payload, existing is None))
|
|
|
|
# An asset pack whose manifest reuses an existing material_id used to
|
|
# silently rewrite that material -- image, tags, category and all --
|
|
# with no confirmation and no way to tell it had happened. Collect every
|
|
# collision first so the caller sees the whole blast radius in one
|
|
# response rather than discovering it one failed import at a time.
|
|
conflicts = [
|
|
str(payload_item["material_id"])
|
|
for payload_item, creating in planned_materials
|
|
if not creating
|
|
]
|
|
if conflicts and not allow_overwrite:
|
|
raise ApiError(
|
|
ErrorCode.VALIDATION_FAILED,
|
|
"asset pack would overwrite existing materials; retry with allow_overwrite=true to replace them",
|
|
{
|
|
"field": "materials",
|
|
"conflicting_material_ids": sorted(conflicts),
|
|
"conflicts": len(conflicts),
|
|
},
|
|
)
|
|
|
|
for material_payload, creating in planned_materials:
|
|
if creating:
|
|
material = self.material_service.create_material(material_payload, ctx)
|
|
created_count += 1
|
|
else:
|
|
material = self.material_service.update_material(material_payload["material_id"], material_payload, ctx)
|
|
updated_count += 1
|
|
material_ids.append(material.material_id)
|
|
return {
|
|
"materials": len(material_ids),
|
|
"styles": 0,
|
|
"material_ids": material_ids,
|
|
"created": created_count,
|
|
"updated": updated_count,
|
|
}
|
|
|
|
|
|
def _manifest_candidates(root: str, relative: Path, package_path: Path) -> list[dict[str, Any]]:
|
|
if package_path.is_file():
|
|
return (
|
|
[{"uri": _storage_uri(root, relative), "path": package_path, "relative": Path(package_path.name)}]
|
|
if package_path.name in _MANIFEST_FILENAMES
|
|
else []
|
|
)
|
|
|
|
candidates: list[dict[str, Any]] = []
|
|
for child in package_path.rglob("*"):
|
|
if child.is_file() and child.name in _MANIFEST_FILENAMES:
|
|
pack_relative = child.relative_to(package_path)
|
|
child_relative = relative / pack_relative
|
|
candidates.append({"uri": _storage_uri(root, child_relative), "path": child, "relative": pack_relative})
|
|
return sorted(candidates, key=_manifest_sort_key)
|
|
|
|
|
|
def _manifest_sort_key(item: dict[str, Any]) -> tuple[int, int, str]:
|
|
relative = item["relative"]
|
|
filename = relative.name
|
|
return (
|
|
len(relative.parts),
|
|
_MANIFEST_FILENAME_PRIORITY.get(filename, 99),
|
|
item["uri"],
|
|
)
|
|
|
|
|
|
def _manifest_summary(package_path: Path, candidates: list[dict[str, Any]]) -> dict[str, Any]:
|
|
if not candidates:
|
|
return {
|
|
"present": False,
|
|
"valid": False,
|
|
"uri": None,
|
|
"name": None,
|
|
"version": None,
|
|
"materials": 0,
|
|
"styles": 0,
|
|
"errors": [{"code": "MANIFEST_MISSING", "message": "asset pack manifest was not found"}],
|
|
}
|
|
|
|
selected = candidates[0]
|
|
try:
|
|
payload = json.loads(selected["path"].read_text(encoding="utf-8"))
|
|
except json.JSONDecodeError as exc:
|
|
return {
|
|
"present": True,
|
|
"valid": False,
|
|
"uri": selected["uri"],
|
|
"name": None,
|
|
"version": None,
|
|
"materials": 0,
|
|
"styles": 0,
|
|
"errors": [{"code": "MANIFEST_INVALID_JSON", "message": exc.msg, "line": exc.lineno}],
|
|
}
|
|
|
|
if not isinstance(payload, dict):
|
|
return {
|
|
"present": True,
|
|
"valid": False,
|
|
"uri": selected["uri"],
|
|
"name": None,
|
|
"version": None,
|
|
"materials": 0,
|
|
"styles": 0,
|
|
"errors": [{"code": "MANIFEST_NOT_OBJECT", "message": "asset pack manifest must be a JSON object"}],
|
|
}
|
|
|
|
errors = _manifest_entry_errors(payload, package_path=package_path, manifest_path=selected["path"])
|
|
return {
|
|
"present": True,
|
|
"valid": not errors,
|
|
"uri": selected["uri"],
|
|
"name": _optional_text(payload.get("name")),
|
|
"version": _optional_text(payload.get("version")),
|
|
"materials": _list_count(payload.get("materials")),
|
|
"styles": _list_count(payload.get("styles")),
|
|
"errors": errors,
|
|
}
|
|
|
|
|
|
def _load_manifest_payload(path: Path) -> dict[str, Any]:
|
|
payload = json.loads(path.read_text(encoding="utf-8"))
|
|
if not isinstance(payload, dict):
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "asset pack manifest must be a JSON object", {"field": "manifest"})
|
|
return payload
|
|
|
|
|
|
def _manifest_entry_errors(payload: dict[str, Any], *, package_path: Path, manifest_path: Path) -> list[dict[str, Any]]:
|
|
errors: list[dict[str, Any]] = []
|
|
materials = payload.get("materials")
|
|
if materials is not None and not isinstance(materials, list):
|
|
errors.append(
|
|
{
|
|
"code": "MATERIALS_NOT_LIST",
|
|
"message": "asset pack materials must be a list",
|
|
"field": "materials",
|
|
}
|
|
)
|
|
return errors
|
|
for index, item in enumerate(materials or []):
|
|
field = f"materials[{index}]"
|
|
if not isinstance(item, dict):
|
|
errors.append(
|
|
{
|
|
"code": "MATERIAL_ENTRY_NOT_OBJECT",
|
|
"message": "asset pack material entries must be objects",
|
|
"field": field,
|
|
}
|
|
)
|
|
continue
|
|
image_value = _optional_text(item.get("image_uri") or item.get("uri") or item.get("image") or item.get("file"))
|
|
if not image_value:
|
|
errors.append(
|
|
{
|
|
"code": "MATERIAL_IMAGE_MISSING",
|
|
"message": "asset pack material entry must include image_uri, uri, image, or file",
|
|
"field": f"{field}.image_uri",
|
|
}
|
|
)
|
|
elif _is_missing_relative_asset(image_value, package_path, manifest_path):
|
|
errors.append(
|
|
{
|
|
"code": "MATERIAL_FILE_MISSING",
|
|
"message": "asset pack material image file was not found",
|
|
"field": f"{field}.image_uri",
|
|
}
|
|
)
|
|
thumbnail_value = _optional_text(item.get("thumbnail_uri") or item.get("thumbnail"))
|
|
if thumbnail_value and _is_missing_relative_asset(thumbnail_value, package_path, manifest_path):
|
|
errors.append(
|
|
{
|
|
"code": "MATERIAL_THUMBNAIL_MISSING",
|
|
"message": "asset pack material thumbnail file was not found",
|
|
"field": f"{field}.thumbnail_uri",
|
|
}
|
|
)
|
|
return errors
|
|
|
|
|
|
def _is_missing_relative_asset(value: str, package_path: Path, manifest_path: Path) -> bool:
|
|
if value.startswith("storage://"):
|
|
return False
|
|
base_path = package_path if package_path.is_dir() else manifest_path.parent
|
|
candidate = (base_path / value).resolve()
|
|
try:
|
|
candidate.relative_to(base_path.resolve())
|
|
except ValueError:
|
|
return True
|
|
return not candidate.is_file()
|
|
|
|
|
|
def _material_payload_from_manifest_item(
|
|
item: dict[str, Any],
|
|
*,
|
|
root: str,
|
|
base_relative: Path,
|
|
package_uri: str,
|
|
manifest_uri: str,
|
|
index: int,
|
|
) -> dict[str, Any]:
|
|
image_uri = _asset_uri(item.get("image_uri") or item.get("uri") or item.get("image") or item.get("file"), root, base_relative)
|
|
if not image_uri:
|
|
raise ApiError(ErrorCode.VALIDATION_FAILED, "material image uri is required", {"field": f"materials[{index}].image_uri"})
|
|
thumbnail_uri = _asset_uri(item.get("thumbnail_uri") or item.get("thumbnail"), root, base_relative)
|
|
display_name = _optional_text(item.get("display_name") or item.get("name") or item.get("title")) or Path(image_uri).stem
|
|
metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
|
|
material_id = _material_id(item, package_uri, manifest_uri, index, image_uri)
|
|
return {
|
|
"material_id": material_id,
|
|
"category_id": _optional_text(item.get("category_id")),
|
|
"display_name": display_name,
|
|
"image_uri": image_uri,
|
|
"thumbnail_uri": thumbnail_uri,
|
|
"prompt": _optional_text(item.get("prompt")),
|
|
"negative_prompt": _optional_text(item.get("negative_prompt")),
|
|
"tags": _normalize_tags(item.get("tags")),
|
|
# An imported pack is an untrusted document: letting its manifest
|
|
# declare "confirmed" would let a pack author skip recognition and human
|
|
# review entirely, landing unvetted material straight in the confirmed
|
|
# library. Only states that still require review are honoured.
|
|
"recognition_status": _importable_recognition_status(item.get("recognition_status")),
|
|
"metadata": {
|
|
**metadata,
|
|
"asset_pack": {
|
|
"package_uri": package_uri,
|
|
"manifest_uri": manifest_uri,
|
|
"index": index,
|
|
},
|
|
},
|
|
}
|
|
|
|
|
|
# Recognition states an imported manifest is allowed to request. "confirmed"
|
|
# and "archived" are review *outcomes* and must be reached through the normal
|
|
# recognise -> confirm flow, not asserted by the pack being imported.
|
|
IMPORTABLE_RECOGNITION_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm"}
|
|
|
|
|
|
def _importable_recognition_status(value: Any) -> str:
|
|
requested = _optional_text(value)
|
|
if requested in IMPORTABLE_RECOGNITION_STATUSES:
|
|
return requested
|
|
return "pending_recognition"
|
|
|
|
|
|
def _asset_uri(value: Any, root: str, base_relative: Path) -> str | None:
|
|
text = _optional_text(value)
|
|
if text is None:
|
|
return None
|
|
if text.startswith("storage://"):
|
|
return text
|
|
return _storage_uri(root, base_relative / text)
|
|
|
|
|
|
def _material_id(item: dict[str, Any], package_uri: str, manifest_uri: str, index: int, image_uri: str) -> str:
|
|
explicit = _optional_text(item.get("material_id") or item.get("id"))
|
|
if explicit:
|
|
return explicit
|
|
digest = hashlib.sha1(f"{package_uri}|{manifest_uri}|{index}|{image_uri}".encode("utf-8")).hexdigest()
|
|
return f"mat_pack_{digest[:24]}"
|
|
|
|
|
|
def _storage_uri(root: str, relative: Path) -> str:
|
|
return f"storage://{root}/{relative.as_posix()}"
|
|
|
|
|
|
def _optional_text(value: Any) -> str | None:
|
|
text = str(value or "").strip()
|
|
return text or None
|
|
|
|
|
|
def _list_count(value: Any) -> int:
|
|
return len(value) if isinstance(value, list) else 0
|
|
|
|
|
|
def _normalize_tags(value: Any) -> list[str]:
|
|
if isinstance(value, str):
|
|
candidates = value.split(",")
|
|
elif isinstance(value, list):
|
|
candidates = value
|
|
else:
|
|
candidates = []
|
|
tags: list[str] = []
|
|
for item in candidates:
|
|
tag = str(item or "").strip()
|
|
if tag and tag not in tags:
|
|
tags.append(tag)
|
|
return tags
|
|
|
|
|
|
def _path_file_stats(path: Path) -> tuple[int, int]:
|
|
if path.is_file():
|
|
return 1, path.stat().st_size
|
|
files = 0
|
|
total = 0
|
|
for child in path.rglob("*"):
|
|
if child.is_file():
|
|
files += 1
|
|
total += child.stat().st_size
|
|
return files, total
|