Track bundled vendor runtime sources

vendor/ComfyUI/app/assets/api/routes.py

@@ -0,0 +1,816 @@
+import asyncio
+import functools
+import json
+import logging
+import os
+import urllib.parse
+import uuid
+from typing import Any
+
+from aiohttp import web
+from pydantic import ValidationError
+
+import folder_paths
+from app import user_manager
+from app.assets.api import schemas_in, schemas_out
+from app.assets.services import schemas
+from app.assets.api.schemas_in import (
+    AssetValidationError,
+    UploadError,
+)
+from app.assets.helpers import validate_blake3_hash
+from app.assets.api.upload import (
+    delete_temp_file_if_exists,
+    parse_multipart_upload,
+)
+from app.assets.seeder import ScanInProgressError, asset_seeder
+from app.assets.services import (
+    DependencyMissingError,
+    HashMismatchError,
+    apply_tags,
+    asset_exists,
+    create_from_hash,
+    delete_asset_reference,
+    get_asset_detail,
+    list_assets_page,
+    list_tags,
+    remove_tags,
+    resolve_asset_for_download,
+    update_asset_metadata,
+    upload_from_temp_path,
+)
+from app.assets.services.cursor import InvalidCursorError
+from app.assets.services.tagging import list_tag_histogram
+
+ROUTES = web.RouteTableDef()
+USER_MANAGER: user_manager.UserManager | None = None
+_ASSETS_ENABLED = False
+
+
+def _require_assets_feature_enabled(handler):
+    @functools.wraps(handler)
+    async def wrapper(request: web.Request) -> web.Response:
+        if not _ASSETS_ENABLED:
+            return _build_error_response(
+                503,
+                "SERVICE_DISABLED",
+                "Assets system is disabled. Start the server with --enable-assets to use this feature.",
+            )
+        return await handler(request)
+
+    return wrapper
+
+
+# UUID regex (canonical hyphenated form, case-insensitive)
+UUID_RE = r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+
+
+def get_query_dict(request: web.Request) -> dict[str, Any]:
+    """Gets a dictionary of query parameters from the request.
+
+    request.query is a MultiMapping[str], needs to be converted to a dict
+    to be validated by Pydantic.
+    """
+    query_dict = {
+        key: request.query.getall(key)
+        if len(request.query.getall(key)) > 1
+        else request.query.get(key)
+        for key in request.query.keys()
+    }
+    return query_dict
+
+
+# Note to any custom node developers reading this code:
+# The assets system is not yet fully implemented,
+# do not rely on the code in /app/assets remaining the same.
+
+
+def register_assets_routes(
+    app: web.Application,
+    user_manager_instance: user_manager.UserManager | None = None,
+) -> None:
+    global USER_MANAGER, _ASSETS_ENABLED
+    if user_manager_instance is not None:
+        USER_MANAGER = user_manager_instance
+        _ASSETS_ENABLED = True
+    app.add_routes(ROUTES)
+
+
+def disable_assets_routes() -> None:
+    """Disable asset routes at runtime (e.g. after DB init failure)."""
+    global _ASSETS_ENABLED
+    _ASSETS_ENABLED = False
+
+
+def _build_error_response(
+    status: int, code: str, message: str, details: dict | None = None
+) -> web.Response:
+    return web.json_response(
+        {"error": {"code": code, "message": message, "details": details or {}}},
+        status=status,
+    )
+
+
+def _build_validation_error_response(code: str, ve: ValidationError) -> web.Response:
+    errors = json.loads(ve.json())
+    return _build_error_response(400, code, "Validation failed.", {"errors": errors})
+
+
+def _validate_sort_field(requested: str | None) -> str:
+    if not requested:
+        return "created_at"
+    v = requested.lower()
+    if v in {"name", "created_at", "updated_at", "size", "last_access_time"}:
+        return v
+    return "created_at"
+
+
+def _build_preview_url_from_view(tags: list[str], user_metadata: dict[str, Any] | None) -> str | None:
+    """Build a /api/view preview URL from asset tags and user_metadata filename."""
+    if not user_metadata:
+        return None
+    filename = user_metadata.get("filename")
+    if not filename:
+        return None
+
+    if "input" in tags:
+        view_type = "input"
+    elif "output" in tags:
+        view_type = "output"
+    else:
+        return None
+
+    subfolder = ""
+    if "/" in filename:
+        subfolder, filename = filename.rsplit("/", 1)
+
+    encoded_filename = urllib.parse.quote(filename, safe="")
+    url = f"/api/view?type={view_type}&filename={encoded_filename}"
+    if subfolder:
+        url += f"&subfolder={urllib.parse.quote(subfolder, safe='')}"
+    return url
+
+
+def _build_asset_response(result: schemas.AssetDetailResult | schemas.UploadResult) -> schemas_out.Asset:
+    """Build an Asset response from a service result."""
+    if result.ref.preview_id:
+        preview_detail = get_asset_detail(result.ref.preview_id)
+        if preview_detail:
+            preview_url = _build_preview_url_from_view(preview_detail.tags, preview_detail.ref.user_metadata)
+        else:
+            preview_url = None
+    else:
+        preview_url = _build_preview_url_from_view(result.tags, result.ref.user_metadata)
+    asset_content_hash = result.asset.hash if result.asset else None
+    return schemas_out.Asset(
+        id=result.ref.id,
+        name=result.ref.name,
+        hash=asset_content_hash,
+        asset_hash=asset_content_hash,
+        size=int(result.asset.size_bytes) if result.asset else None,
+        mime_type=result.asset.mime_type if result.asset else None,
+        tags=result.tags,
+        preview_url=preview_url,
+        preview_id=result.ref.preview_id,
+        user_metadata=result.ref.user_metadata or {},
+        metadata=result.ref.system_metadata,
+        job_id=result.ref.job_id,
+        prompt_id=result.ref.job_id,  # deprecated alias of job_id, kept for compatibility
+        created_at=result.ref.created_at,
+        updated_at=result.ref.updated_at,
+        last_access_time=result.ref.last_access_time,
+    )
+
+
+@ROUTES.head("/api/assets/hash/{hash}")
+@_require_assets_feature_enabled
+async def head_asset_by_hash(request: web.Request) -> web.Response:
+    hash_str = request.match_info.get("hash", "").strip().lower()
+    try:
+        hash_str = validate_blake3_hash(hash_str)
+    except ValueError:
+        return _build_error_response(
+            400, "INVALID_HASH", "hash must be like 'blake3:<hex>'"
+        )
+    exists = asset_exists(hash_str)
+    return web.Response(status=200 if exists else 404)
+
+
+@ROUTES.get("/api/assets")
+@_require_assets_feature_enabled
+async def list_assets_route(request: web.Request) -> web.Response:
+    """
+    GET request to list assets.
+    """
+    query_dict = get_query_dict(request)
+    try:
+        q = schemas_in.ListAssetsQuery.model_validate(query_dict)
+    except ValidationError as ve:
+        return _build_validation_error_response("INVALID_QUERY", ve)
+
+    sort = _validate_sort_field(q.sort)
+    order_candidate = (q.order or "desc").lower()
+    order = order_candidate if order_candidate in {"asc", "desc"} else "desc"
+
+    try:
+        result = list_assets_page(
+            owner_id=USER_MANAGER.get_request_user_id(request),
+            include_tags=q.include_tags,
+            exclude_tags=q.exclude_tags,
+            name_contains=q.name_contains,
+            metadata_filter=q.metadata_filter,
+            limit=q.limit,
+            offset=q.offset,
+            sort=sort,
+            order=order,
+            after=q.after,
+        )
+    except InvalidCursorError as e:
+        return _build_error_response(400, "INVALID_CURSOR", str(e))
+
+    summaries = [_build_asset_response(item) for item in result.items]
+
+    # has_more semantics differ by mode:
+    #   - cursor mode: a non-empty next_cursor means there are more results.
+    #   - offset mode: derived from total - (offset + page size).
+    if q.after is not None:
+        has_more = result.next_cursor is not None
+    else:
+        has_more = (q.offset + len(summaries)) < result.total
+
+    payload = schemas_out.AssetsList(
+        assets=summaries,
+        total=result.total,
+        has_more=has_more,
+        next_cursor=result.next_cursor,
+    )
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True))
+
+
+@ROUTES.get(f"/api/assets/{{id:{UUID_RE}}}")
+@_require_assets_feature_enabled
+async def get_asset_route(request: web.Request) -> web.Response:
+    """
+    GET request to get an asset's info as JSON.
+    """
+    reference_id = str(uuid.UUID(request.match_info["id"]))
+    try:
+        result = get_asset_detail(
+            reference_id=reference_id,
+            owner_id=USER_MANAGER.get_request_user_id(request),
+        )
+        if not result:
+            return _build_error_response(
+                404,
+                "ASSET_NOT_FOUND",
+                f"AssetReference {reference_id} not found",
+                {"id": reference_id},
+            )
+
+        payload = _build_asset_response(result)
+    except ValueError as e:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", str(e), {"id": reference_id}
+        )
+    except Exception:
+        logging.exception(
+            "get_asset failed for reference_id=%s, owner_id=%s",
+            reference_id,
+            USER_MANAGER.get_request_user_id(request),
+        )
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True), status=200)
+
+
+@ROUTES.get(f"/api/assets/{{id:{UUID_RE}}}/content")
+@_require_assets_feature_enabled
+async def download_asset_content(request: web.Request) -> web.Response:
+    disposition = request.query.get("disposition", "attachment").lower().strip()
+    if disposition not in {"inline", "attachment"}:
+        disposition = "attachment"
+
+    try:
+        result = resolve_asset_for_download(
+            reference_id=str(uuid.UUID(request.match_info["id"])),
+            owner_id=USER_MANAGER.get_request_user_id(request),
+        )
+        abs_path = result.abs_path
+        content_type = result.content_type
+        filename = result.download_name
+    except ValueError as ve:
+        return _build_error_response(404, "ASSET_NOT_FOUND", str(ve))
+    except NotImplementedError as nie:
+        return _build_error_response(501, "BACKEND_UNSUPPORTED", str(nie))
+    except FileNotFoundError:
+        return _build_error_response(
+            404, "FILE_NOT_FOUND", "Underlying file not found on disk."
+        )
+
+    _DANGEROUS_MIME_TYPES = {
+        "text/html", "text/html-sandboxed", "application/xhtml+xml",
+        "text/javascript", "text/css",
+    }
+    if content_type in _DANGEROUS_MIME_TYPES:
+        content_type = "application/octet-stream"
+
+    safe_name = (filename or "").replace("\r", "").replace("\n", "")
+    encoded = urllib.parse.quote(safe_name)
+    cd = f"{disposition}; filename*=UTF-8''{encoded}"
+
+    file_size = os.path.getsize(abs_path)
+    size_mb = file_size / (1024 * 1024)
+    logging.info(
+        "download_asset_content: path=%s, size=%d bytes (%.2f MB), type=%s, name=%s",
+        abs_path,
+        file_size,
+        size_mb,
+        content_type,
+        filename,
+    )
+
+    async def stream_file_chunks():
+        chunk_size = 64 * 1024
+        with open(abs_path, "rb") as f:
+            while True:
+                chunk = f.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+
+    return web.Response(
+        body=stream_file_chunks(),
+        content_type=content_type,
+        headers={
+            "Content-Disposition": cd,
+            "Content-Length": str(file_size),
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+@ROUTES.post("/api/assets/from-hash")
+@_require_assets_feature_enabled
+async def create_asset_from_hash_route(request: web.Request) -> web.Response:
+    try:
+        payload = await request.json()
+        body = schemas_in.CreateFromHashBody.model_validate(payload)
+    except ValidationError as ve:
+        return _build_validation_error_response("INVALID_BODY", ve)
+    except Exception:
+        return _build_error_response(
+            400, "INVALID_JSON", "Request body must be valid JSON."
+        )
+
+    # Derive name from hash if not provided
+    name = body.name
+    if name is None:
+        name = body.hash.split(":", 1)[1] if ":" in body.hash else body.hash
+
+    result = create_from_hash(
+        hash_str=body.hash,
+        name=name,
+        tags=body.tags,
+        user_metadata=body.user_metadata,
+        owner_id=USER_MANAGER.get_request_user_id(request),
+        mime_type=body.mime_type,
+        preview_id=body.preview_id,
+    )
+    if result is None:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", f"Asset content {body.hash} does not exist"
+        )
+
+    asset = _build_asset_response(result)
+    payload_out = schemas_out.AssetCreated(
+        **asset.model_dump(),
+        created_new=result.created_new,
+    )
+    return web.json_response(payload_out.model_dump(mode="json", exclude_none=True), status=201)
+
+
+@ROUTES.post("/api/assets")
+@_require_assets_feature_enabled
+async def upload_asset(request: web.Request) -> web.Response:
+    """Multipart/form-data endpoint for Asset uploads."""
+    try:
+        parsed = await parse_multipart_upload(request, check_hash_exists=asset_exists)
+    except UploadError as e:
+        return _build_error_response(e.status, e.code, e.message)
+
+    owner_id = USER_MANAGER.get_request_user_id(request)
+
+    try:
+        spec = schemas_in.UploadAssetSpec.model_validate(
+            {
+                "tags": parsed.tags_raw,
+                "name": parsed.provided_name,
+                "user_metadata": parsed.user_metadata_raw,
+                "hash": parsed.provided_hash,
+                "mime_type": parsed.provided_mime_type,
+                "preview_id": parsed.provided_preview_id,
+            }
+        )
+    except ValidationError as ve:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        return _build_error_response(
+            400, "INVALID_BODY", f"Validation failed: {ve.json()}"
+        )
+
+    if spec.tags and spec.tags[0] == "models":
+        if (
+            len(spec.tags) < 2
+            or spec.tags[1] not in folder_paths.folder_names_and_paths
+        ):
+            delete_temp_file_if_exists(parsed.tmp_path)
+            category = spec.tags[1] if len(spec.tags) >= 2 else ""
+            return _build_error_response(
+                400, "INVALID_BODY", f"unknown models category '{category}'"
+            )
+
+    try:
+        # Fast path: hash exists, create AssetReference without writing anything
+        if spec.hash and parsed.provided_hash_exists is True:
+            result = create_from_hash(
+                hash_str=spec.hash,
+                name=spec.name or (spec.hash.split(":", 1)[1]),
+                tags=spec.tags,
+                user_metadata=spec.user_metadata or {},
+                owner_id=owner_id,
+                mime_type=spec.mime_type,
+                preview_id=spec.preview_id,
+            )
+            if result is None:
+                delete_temp_file_if_exists(parsed.tmp_path)
+                return _build_error_response(
+                    404, "ASSET_NOT_FOUND", f"Asset content {spec.hash} does not exist"
+                )
+            delete_temp_file_if_exists(parsed.tmp_path)
+        else:
+            # Otherwise, we must have a temp file path to ingest
+            if not parsed.tmp_path or not os.path.exists(parsed.tmp_path):
+                return _build_error_response(
+                    400,
+                    "MISSING_INPUT",
+                    "Provided hash not found and no file uploaded.",
+                )
+
+            result = upload_from_temp_path(
+                temp_path=parsed.tmp_path,
+                name=spec.name,
+                tags=spec.tags,
+                user_metadata=spec.user_metadata or {},
+                client_filename=parsed.file_client_name,
+                owner_id=owner_id,
+                expected_hash=spec.hash,
+                mime_type=spec.mime_type,
+                preview_id=spec.preview_id,
+            )
+    except AssetValidationError as e:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        return _build_error_response(400, e.code, str(e))
+    except ValueError as e:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        return _build_error_response(400, "BAD_REQUEST", str(e))
+    except HashMismatchError as e:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        return _build_error_response(400, "HASH_MISMATCH", str(e))
+    except DependencyMissingError as e:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        return _build_error_response(503, "DEPENDENCY_MISSING", e.message)
+    except Exception:
+        delete_temp_file_if_exists(parsed.tmp_path)
+        logging.exception("upload_asset failed for owner_id=%s", owner_id)
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+
+    asset = _build_asset_response(result)
+    payload_out = schemas_out.AssetCreated(
+        **asset.model_dump(),
+        created_new=result.created_new,
+    )
+    status = 201 if result.created_new else 200
+    return web.json_response(payload_out.model_dump(mode="json", exclude_none=True), status=status)
+
+
+@ROUTES.put(f"/api/assets/{{id:{UUID_RE}}}")
+@_require_assets_feature_enabled
+async def update_asset_route(request: web.Request) -> web.Response:
+    reference_id = str(uuid.UUID(request.match_info["id"]))
+    try:
+        body = schemas_in.UpdateAssetBody.model_validate(await request.json())
+    except ValidationError as ve:
+        return _build_validation_error_response("INVALID_BODY", ve)
+    except Exception:
+        return _build_error_response(
+            400, "INVALID_JSON", "Request body must be valid JSON."
+        )
+
+    try:
+        result = update_asset_metadata(
+            reference_id=reference_id,
+            name=body.name,
+            user_metadata=body.user_metadata,
+            owner_id=USER_MANAGER.get_request_user_id(request),
+            preview_id=body.preview_id,
+        )
+        payload = _build_asset_response(result)
+    except PermissionError as pe:
+        return _build_error_response(403, "FORBIDDEN", str(pe), {"id": reference_id})
+    except ValueError as ve:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", str(ve), {"id": reference_id}
+        )
+    except Exception:
+        logging.exception(
+            "update_asset failed for reference_id=%s, owner_id=%s",
+            reference_id,
+            USER_MANAGER.get_request_user_id(request),
+        )
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True), status=200)
+
+
+@ROUTES.delete(f"/api/assets/{{id:{UUID_RE}}}")
+@_require_assets_feature_enabled
+async def delete_asset_route(request: web.Request) -> web.Response:
+    reference_id = str(uuid.UUID(request.match_info["id"]))
+
+    try:
+        # Deleting an asset is a soft delete of the reference; the underlying
+        # content is preserved (it may be shared with other references).
+        deleted = delete_asset_reference(
+            reference_id=reference_id,
+            owner_id=USER_MANAGER.get_request_user_id(request),
+            delete_content_if_orphan=False,
+        )
+    except Exception:
+        logging.exception(
+            "delete_asset_reference failed for reference_id=%s, owner_id=%s",
+            reference_id,
+            USER_MANAGER.get_request_user_id(request),
+        )
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+
+    if not deleted:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", f"AssetReference {reference_id} not found."
+        )
+    return web.Response(status=204)
+
+
+@ROUTES.get("/api/tags")
+@_require_assets_feature_enabled
+async def get_tags(request: web.Request) -> web.Response:
+    """
+    GET request to list all tags based on query parameters.
+    """
+    query_map = dict(request.rel_url.query)
+
+    try:
+        query = schemas_in.TagsListQuery.model_validate(query_map)
+    except ValidationError as e:
+        return _build_error_response(
+            400,
+            "INVALID_QUERY",
+            "Invalid query parameters",
+            {"errors": json.loads(e.json())},
+        )
+
+    rows, total = list_tags(
+        prefix=query.prefix,
+        limit=query.limit,
+        offset=query.offset,
+        order=query.order,
+        include_zero=query.include_zero,
+        owner_id=USER_MANAGER.get_request_user_id(request),
+    )
+
+    tags = [
+        schemas_out.TagUsage(name=name, count=count)
+        for (name, count) in rows
+    ]
+    payload = schemas_out.TagsList(
+        tags=tags, total=total, has_more=(query.offset + len(tags)) < total
+    )
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True))
+
+
+@ROUTES.post(f"/api/assets/{{id:{UUID_RE}}}/tags")
+@_require_assets_feature_enabled
+async def add_asset_tags(request: web.Request) -> web.Response:
+    reference_id = str(uuid.UUID(request.match_info["id"]))
+    try:
+        json_payload = await request.json()
+        data = schemas_in.TagsAdd.model_validate(json_payload)
+    except ValidationError as ve:
+        return _build_error_response(
+            400,
+            "INVALID_BODY",
+            "Invalid JSON body for tags add.",
+            {"errors": ve.errors()},
+        )
+    except Exception:
+        return _build_error_response(
+            400, "INVALID_JSON", "Request body must be valid JSON."
+        )
+
+    try:
+        result = apply_tags(
+            reference_id=reference_id,
+            tags=data.tags,
+            origin="manual",
+            owner_id=USER_MANAGER.get_request_user_id(request),
+        )
+        payload = schemas_out.TagsAdd(
+            added=result.added,
+            already_present=result.already_present,
+            total_tags=result.total_tags,
+        )
+    except PermissionError as pe:
+        return _build_error_response(403, "FORBIDDEN", str(pe), {"id": reference_id})
+    except ValueError as ve:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", str(ve), {"id": reference_id}
+        )
+    except Exception:
+        logging.exception(
+            "add_tags_to_asset failed for reference_id=%s, owner_id=%s",
+            reference_id,
+            USER_MANAGER.get_request_user_id(request),
+        )
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True), status=200)
+
+
+@ROUTES.delete(f"/api/assets/{{id:{UUID_RE}}}/tags")
+@_require_assets_feature_enabled
+async def delete_asset_tags(request: web.Request) -> web.Response:
+    reference_id = str(uuid.UUID(request.match_info["id"]))
+    try:
+        json_payload = await request.json()
+        data = schemas_in.TagsRemove.model_validate(json_payload)
+    except ValidationError as ve:
+        return _build_error_response(
+            400,
+            "INVALID_BODY",
+            "Invalid JSON body for tags remove.",
+            {"errors": ve.errors()},
+        )
+    except Exception:
+        return _build_error_response(
+            400, "INVALID_JSON", "Request body must be valid JSON."
+        )
+
+    try:
+        result = remove_tags(
+            reference_id=reference_id,
+            tags=data.tags,
+            owner_id=USER_MANAGER.get_request_user_id(request),
+        )
+        payload = schemas_out.TagsRemove(
+            removed=result.removed,
+            not_present=result.not_present,
+            total_tags=result.total_tags,
+        )
+    except PermissionError as pe:
+        return _build_error_response(403, "FORBIDDEN", str(pe), {"id": reference_id})
+    except ValueError as ve:
+        return _build_error_response(
+            404, "ASSET_NOT_FOUND", str(ve), {"id": reference_id}
+        )
+    except Exception:
+        logging.exception(
+            "remove_tags_from_asset failed for reference_id=%s, owner_id=%s",
+            reference_id,
+            USER_MANAGER.get_request_user_id(request),
+        )
+        return _build_error_response(500, "INTERNAL", "Unexpected server error.")
+
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True), status=200)
+
+
+@ROUTES.get("/api/assets/tags/refine")
+@_require_assets_feature_enabled
+async def get_tags_refine(request: web.Request) -> web.Response:
+    """GET request to get tag histogram for filtered assets."""
+    query_dict = get_query_dict(request)
+    try:
+        q = schemas_in.TagsRefineQuery.model_validate(query_dict)
+    except ValidationError as ve:
+        return _build_validation_error_response("INVALID_QUERY", ve)
+
+    tag_counts = list_tag_histogram(
+        owner_id=USER_MANAGER.get_request_user_id(request),
+        include_tags=q.include_tags,
+        exclude_tags=q.exclude_tags,
+        name_contains=q.name_contains,
+        metadata_filter=q.metadata_filter,
+        limit=q.limit,
+    )
+    payload = schemas_out.TagHistogram(tag_counts=tag_counts)
+    return web.json_response(payload.model_dump(mode="json", exclude_none=True), status=200)
+
+
+@ROUTES.post("/api/assets/seed")
+@_require_assets_feature_enabled
+async def seed_assets(request: web.Request) -> web.Response:
+    """Trigger asset seeding for specified roots (models, input, output).
+
+    Query params:
+        wait: If "true", block until scan completes (synchronous behavior for tests)
+
+    Returns:
+        202 Accepted if scan started
+        409 Conflict if scan already running
+        200 OK with final stats if wait=true
+    """
+    try:
+        payload = await request.json()
+        roots = payload.get("roots", ["models", "input", "output"])
+    except Exception:
+        roots = ["models", "input", "output"]
+
+    valid_roots = tuple(r for r in roots if r in ("models", "input", "output"))
+    if not valid_roots:
+        return _build_error_response(400, "INVALID_BODY", "No valid roots specified")
+
+    wait_param = request.query.get("wait", "").lower()
+    should_wait = wait_param in ("true", "1", "yes")
+
+    started = asset_seeder.start(roots=valid_roots)
+    if not started:
+        return web.json_response({"status": "already_running"}, status=409)
+
+    if should_wait:
+        await asyncio.to_thread(asset_seeder.wait)
+        status = asset_seeder.get_status()
+        return web.json_response(
+            {
+                "status": "completed",
+                "progress": {
+                    "scanned": status.progress.scanned if status.progress else 0,
+                    "total": status.progress.total if status.progress else 0,
+                    "created": status.progress.created if status.progress else 0,
+                    "skipped": status.progress.skipped if status.progress else 0,
+                },
+                "errors": status.errors,
+            },
+            status=200,
+        )
+
+    return web.json_response({"status": "started"}, status=202)
+
+
+@ROUTES.get("/api/assets/seed/status")
+@_require_assets_feature_enabled
+async def get_seed_status(request: web.Request) -> web.Response:
+    """Get current scan status and progress."""
+    status = asset_seeder.get_status()
+    return web.json_response(
+        {
+            "state": status.state.value,
+            "progress": {
+                "scanned": status.progress.scanned,
+                "total": status.progress.total,
+                "created": status.progress.created,
+                "skipped": status.progress.skipped,
+            }
+            if status.progress
+            else None,
+            "errors": status.errors,
+        },
+        status=200,
+    )
+
+
+@ROUTES.post("/api/assets/seed/cancel")
+@_require_assets_feature_enabled
+async def cancel_seed(request: web.Request) -> web.Response:
+    """Request cancellation of in-progress scan."""
+    cancelled = asset_seeder.cancel()
+    if cancelled:
+        return web.json_response({"status": "cancelling"}, status=200)
+    return web.json_response({"status": "idle"}, status=200)
+
+
+@ROUTES.post("/api/assets/prune")
+@_require_assets_feature_enabled
+async def mark_missing_assets(request: web.Request) -> web.Response:
+    """Mark assets as missing when outside all known root prefixes.
+
+    This is a non-destructive soft-delete operation. Assets and metadata
+    are preserved, but references are flagged as missing. They can be
+    restored if the file reappears in a future scan.
+
+    Returns:
+        200 OK with count of marked assets
+        409 Conflict if a scan is currently running
+    """
+    try:
+        marked = asset_seeder.mark_missing_outside_prefixes()
+    except ScanInProgressError:
+        return web.json_response(
+            {"status": "scan_running", "marked": 0},
+            status=409,
+        )
+    return web.json_response({"status": "completed", "marked": marked}, status=200)

vendor/ComfyUI/app/assets/api/schemas_in.py

@@ -0,0 +1,348 @@
+import json
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from app.assets.helpers import validate_blake3_hash
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    conint,
+    field_validator,
+    model_validator,
+)
+
+
+class UploadError(Exception):
+    """Error during upload parsing with HTTP status and code."""
+
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class AssetValidationError(Exception):
+    """Validation error in asset processing (invalid tags, metadata, etc.)."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+@dataclass
+class ParsedUpload:
+    """Result of parsing a multipart upload request."""
+
+    file_present: bool
+    file_written: int
+    file_client_name: str | None
+    tmp_path: str | None
+    tags_raw: list[str]
+    provided_name: str | None
+    user_metadata_raw: str | None
+    provided_hash: str | None
+    provided_hash_exists: bool | None
+    provided_mime_type: str | None = None
+    provided_preview_id: str | None = None
+
+
+class ListAssetsQuery(BaseModel):
+    include_tags: list[str] = Field(default_factory=list)
+    exclude_tags: list[str] = Field(default_factory=list)
+    name_contains: str | None = None
+
+    # Accept either a JSON string (query param) or a dict
+    metadata_filter: dict[str, Any] | None = None
+
+    limit: conint(ge=1, le=500) = 20
+    offset: conint(ge=0) = 0
+    # Opaque keyset cursor. When supplied, `offset` is ignored. Cursor pagination
+    # is supported for sort values `created_at`, `updated_at`, `name`, `size`.
+    # Supplying `after` together with `sort=last_access_time` returns
+    # 400 INVALID_CURSOR; that sort only supports offset/limit.
+    after: str | None = None
+
+    sort: Literal["name", "created_at", "updated_at", "size", "last_access_time"] = (
+        "created_at"
+    )
+    order: Literal["asc", "desc"] = "desc"
+
+    @field_validator("include_tags", "exclude_tags", mode="before")
+    @classmethod
+    def _split_csv_tags(cls, v):
+        # Accept "a,b,c" or ["a","b"] (we are liberal in what we accept)
+        if v is None:
+            return []
+        if isinstance(v, str):
+            return [t.strip() for t in v.split(",") if t.strip()]
+        if isinstance(v, list):
+            out: list[str] = []
+            for item in v:
+                if isinstance(item, str):
+                    out.extend([t.strip() for t in item.split(",") if t.strip()])
+            return out
+        return v
+
+    @field_validator("metadata_filter", mode="before")
+    @classmethod
+    def _parse_metadata_json(cls, v):
+        if v is None or isinstance(v, dict):
+            return v
+        if isinstance(v, str) and v.strip():
+            try:
+                parsed = json.loads(v)
+            except Exception as e:
+                raise ValueError(f"metadata_filter must be JSON: {e}") from e
+            if not isinstance(parsed, dict):
+                raise ValueError("metadata_filter must be a JSON object")
+            return parsed
+        return None
+
+
+class UpdateAssetBody(BaseModel):
+    name: str | None = None
+    user_metadata: dict[str, Any] | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
+
+    @model_validator(mode="after")
+    def _validate_at_least_one_field(self):
+        if all(
+            v is None
+            for v in (self.name, self.user_metadata, self.preview_id)
+        ):
+            raise ValueError(
+                "Provide at least one of: name, user_metadata, preview_id."
+            )
+        return self
+
+
+class CreateFromHashBody(BaseModel):
+    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
+
+    hash: str
+    name: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    user_metadata: dict[str, Any] = Field(default_factory=dict)
+    mime_type: str | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
+
+    @field_validator("hash")
+    @classmethod
+    def _require_blake3(cls, v):
+        return validate_blake3_hash(v or "")
+
+    @field_validator("tags", mode="before")
+    @classmethod
+    def _normalize_tags_field(cls, v):
+        if v is None:
+            return []
+        if isinstance(v, list):
+            out = [str(t).strip().lower() for t in v if str(t).strip()]
+            seen = set()
+            dedup = []
+            for t in out:
+                if t not in seen:
+                    seen.add(t)
+                    dedup.append(t)
+            return dedup
+        if isinstance(v, str):
+            return [t.strip().lower() for t in v.split(",") if t.strip()]
+        return []
+
+
+class TagsRefineQuery(BaseModel):
+    include_tags: list[str] = Field(default_factory=list)
+    exclude_tags: list[str] = Field(default_factory=list)
+    name_contains: str | None = None
+    metadata_filter: dict[str, Any] | None = None
+    limit: conint(ge=1, le=1000) = 100
+
+    @field_validator("include_tags", "exclude_tags", mode="before")
+    @classmethod
+    def _split_csv_tags(cls, v):
+        if v is None:
+            return []
+        if isinstance(v, str):
+            return [t.strip() for t in v.split(",") if t.strip()]
+        if isinstance(v, list):
+            out: list[str] = []
+            for item in v:
+                if isinstance(item, str):
+                    out.extend([t.strip() for t in item.split(",") if t.strip()])
+            return out
+        return v
+
+    @field_validator("metadata_filter", mode="before")
+    @classmethod
+    def _parse_metadata_json(cls, v):
+        if v is None or isinstance(v, dict):
+            return v
+        if isinstance(v, str) and v.strip():
+            try:
+                parsed = json.loads(v)
+            except Exception as e:
+                raise ValueError(f"metadata_filter must be JSON: {e}") from e
+            if not isinstance(parsed, dict):
+                raise ValueError("metadata_filter must be a JSON object")
+            return parsed
+        return None
+
+
+class TagsListQuery(BaseModel):
+    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
+
+    prefix: str | None = Field(None, min_length=1, max_length=256)
+    limit: int = Field(100, ge=1, le=1000)
+    offset: int = Field(0, ge=0, le=10_000_000)
+    order: Literal["count_desc", "name_asc"] = "count_desc"
+    include_zero: bool = True
+
+    @field_validator("prefix")
+    @classmethod
+    def normalize_prefix(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        v = v.strip()
+        return v.lower() or None
+
+
+class TagsAdd(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    tags: list[str] = Field(..., min_length=1)
+
+    @field_validator("tags")
+    @classmethod
+    def normalize_tags(cls, v: list[str]) -> list[str]:
+        out = []
+        for t in v:
+            if not isinstance(t, str):
+                raise TypeError("tags must be strings")
+            tnorm = t.strip().lower()
+            if tnorm:
+                out.append(tnorm)
+        seen = set()
+        deduplicated = []
+        for x in out:
+            if x not in seen:
+                seen.add(x)
+                deduplicated.append(x)
+        return deduplicated
+
+
+class TagsRemove(TagsAdd):
+    pass
+
+
+class UploadAssetSpec(BaseModel):
+    """Upload Asset operation.
+
+    - tags: optional list; if provided, first is root ('models'|'input'|'output');
+            if root == 'models', second must be a valid category
+    - name: display name
+    - user_metadata: arbitrary JSON object (optional)
+    - hash: optional canonical 'blake3:<hex>' for validation / fast-path
+    - mime_type: optional MIME type override
+    - preview_id: optional asset_reference ID for preview
+
+    Files are stored using the content hash as filename stem.
+    """
+
+    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
+
+    tags: list[str] = Field(default_factory=list)
+    name: str | None = Field(default=None, max_length=512, description="Display Name")
+    user_metadata: dict[str, Any] = Field(default_factory=dict)
+    hash: str | None = Field(default=None)
+    mime_type: str | None = Field(default=None)
+    preview_id: str | None = Field(default=None)  # references an asset_reference id
+
+    @field_validator("hash", mode="before")
+    @classmethod
+    def _parse_hash(cls, v):
+        if v is None:
+            return None
+        s = str(v).strip()
+        if not s:
+            return None
+        return validate_blake3_hash(s)
+
+    @field_validator("tags", mode="before")
+    @classmethod
+    def _parse_tags(cls, v):
+        """
+        Accepts a list of strings (possibly multiple form fields),
+        where each string can be:
+          - JSON array (e.g., '["models","loras","foo"]')
+          - comma-separated ('models, loras, foo')
+          - single token ('models')
+        Returns a normalized, deduplicated, ordered list.
+        """
+        items: list[str] = []
+        if v is None:
+            return []
+        if isinstance(v, str):
+            v = [v]
+
+        if isinstance(v, list):
+            for item in v:
+                if item is None:
+                    continue
+                s = str(item).strip()
+                if not s:
+                    continue
+                if s.startswith("["):
+                    try:
+                        arr = json.loads(s)
+                        if isinstance(arr, list):
+                            items.extend(str(x) for x in arr)
+                            continue
+                    except Exception:
+                        pass  # fallback to CSV parse below
+                items.extend([p for p in s.split(",") if p.strip()])
+        else:
+            return []
+
+        # normalize + dedupe
+        norm = []
+        seen = set()
+        for t in items:
+            tnorm = str(t).strip().lower()
+            if tnorm and tnorm not in seen:
+                seen.add(tnorm)
+                norm.append(tnorm)
+        return norm
+
+    @field_validator("user_metadata", mode="before")
+    @classmethod
+    def _parse_metadata_json(cls, v):
+        if v is None or isinstance(v, dict):
+            return v or {}
+        if isinstance(v, str):
+            s = v.strip()
+            if not s:
+                return {}
+            try:
+                parsed = json.loads(s)
+            except Exception as e:
+                raise ValueError(f"user_metadata must be JSON: {e}") from e
+            if not isinstance(parsed, dict):
+                raise ValueError("user_metadata must be a JSON object")
+            return parsed
+        return {}
+
+    @model_validator(mode="after")
+    def _validate_order(self):
+        if not self.tags:
+            raise ValueError("at least one tag is required for uploads")
+        root = self.tags[0]
+        if root not in {"models", "input", "output"}:
+            raise ValueError("first tag must be one of: models, input, output")
+        if root == "models":
+            if len(self.tags) < 2:
+                raise ValueError(
+                    "models uploads require a category tag as the second tag"
+                )
+        return self

vendor/ComfyUI/app/assets/api/schemas_out.py

@@ -0,0 +1,74 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+class Asset(BaseModel):
+    """API view of an asset. Maps to DB ``AssetReference`` joined with its ``Asset`` blob;
+    ``id`` here is the AssetReference id, not the content-addressed Asset id."""
+
+    id: str
+    name: str
+    hash: str | None = None
+    asset_hash: str | None = None
+    size: int | None = None
+    mime_type: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    preview_url: str | None = None
+    preview_id: str | None = None  # references an asset_reference id, not an asset id
+    user_metadata: dict[str, Any] = Field(default_factory=dict)
+    is_immutable: bool = False
+    metadata: dict[str, Any] | None = None
+    job_id: str | None = None
+    prompt_id: str | None = None  # deprecated: use job_id
+    created_at: datetime
+    updated_at: datetime
+    last_access_time: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+    @field_serializer("created_at", "updated_at", "last_access_time")
+    def _serialize_datetime(self, v: datetime | None, _info):
+        return v.isoformat() if v else None
+
+
+class AssetCreated(Asset):
+    created_new: bool
+
+
+class AssetsList(BaseModel):
+    assets: list[Asset]
+    total: int
+    has_more: bool
+    # Opaque cursor for the next page. Omitted when there are no more results.
+    next_cursor: str | None = None
+
+
+class TagUsage(BaseModel):
+    name: str
+    count: int
+
+
+class TagsList(BaseModel):
+    tags: list[TagUsage] = Field(default_factory=list)
+    total: int
+    has_more: bool
+
+
+class TagsAdd(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True)
+    added: list[str] = Field(default_factory=list)
+    already_present: list[str] = Field(default_factory=list)
+    total_tags: list[str] = Field(default_factory=list)
+
+
+class TagsRemove(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True)
+    removed: list[str] = Field(default_factory=list)
+    not_present: list[str] = Field(default_factory=list)
+    total_tags: list[str] = Field(default_factory=list)
+
+
+class TagHistogram(BaseModel):
+    tag_counts: dict[str, int]

vendor/ComfyUI/app/assets/api/upload.py

@@ -0,0 +1,185 @@
+import logging
+import os
+import uuid
+from typing import Callable
+
+from aiohttp import web
+
+import folder_paths
+from app.assets.api.schemas_in import ParsedUpload, UploadError
+from app.assets.helpers import validate_blake3_hash
+
+
+def normalize_and_validate_hash(s: str) -> str:
+    """Validate and normalize a hash string.
+
+    Returns canonical 'blake3:<hex>' or raises UploadError.
+    """
+    try:
+        return validate_blake3_hash(s)
+    except ValueError:
+        raise UploadError(400, "INVALID_HASH", "hash must be like 'blake3:<hex>'")
+
+
+async def parse_multipart_upload(
+    request: web.Request,
+    check_hash_exists: Callable[[str], bool],
+) -> ParsedUpload:
+    """
+    Parse a multipart/form-data upload request.
+
+    Args:
+        request: The aiohttp request
+        check_hash_exists: Callable(hash_str) -> bool to check if a hash exists
+
+    Returns:
+        ParsedUpload with parsed fields and temp file path
+
+    Raises:
+        UploadError: On validation or I/O errors
+    """
+    if not (request.content_type or "").lower().startswith("multipart/"):
+        raise UploadError(
+            415, "UNSUPPORTED_MEDIA_TYPE", "Use multipart/form-data for uploads."
+        )
+
+    reader = await request.multipart()
+
+    file_present = False
+    file_client_name: str | None = None
+    tags_raw: list[str] = []
+    provided_name: str | None = None
+    user_metadata_raw: str | None = None
+    provided_hash: str | None = None
+    provided_hash_exists: bool | None = None
+    provided_mime_type: str | None = None
+    provided_preview_id: str | None = None
+
+    file_written = 0
+    tmp_path: str | None = None
+
+    while True:
+        field = await reader.next()
+        if field is None:
+            break
+
+        fname = getattr(field, "name", "") or ""
+
+        if fname == "hash":
+            try:
+                s = ((await field.text()) or "").strip().lower()
+            except Exception:
+                raise UploadError(
+                    400, "INVALID_HASH", "hash must be like 'blake3:<hex>'"
+                )
+
+            if s:
+                provided_hash = normalize_and_validate_hash(s)
+                try:
+                    provided_hash_exists = check_hash_exists(provided_hash)
+                except Exception as e:
+                    logging.exception(
+                        "check_hash_exists failed for hash=%s: %s", provided_hash, e
+                    )
+                    raise UploadError(
+                        500,
+                        "HASH_CHECK_FAILED",
+                        "Backend error while checking asset hash.",
+                    )
+
+        elif fname == "file":
+            file_present = True
+            file_client_name = (field.filename or "").strip()
+
+            if provided_hash and provided_hash_exists is True:
+                # Hash exists - drain file but don't write to disk
+                try:
+                    while True:
+                        chunk = await field.read_chunk(8 * 1024 * 1024)
+                        if not chunk:
+                            break
+                        file_written += len(chunk)
+                except Exception:
+                    raise UploadError(
+                        500, "UPLOAD_IO_ERROR", "Failed to receive uploaded file."
+                    )
+                continue
+
+            uploads_root = os.path.join(folder_paths.get_temp_directory(), "uploads")
+            unique_dir = os.path.join(uploads_root, uuid.uuid4().hex)
+            os.makedirs(unique_dir, exist_ok=True)
+            tmp_path = os.path.join(unique_dir, ".upload.part")
+
+            try:
+                with open(tmp_path, "wb") as f:
+                    while True:
+                        chunk = await field.read_chunk(8 * 1024 * 1024)
+                        if not chunk:
+                            break
+                        f.write(chunk)
+                        file_written += len(chunk)
+            except Exception:
+                delete_temp_file_if_exists(tmp_path)
+                raise UploadError(
+                    500, "UPLOAD_IO_ERROR", "Failed to receive and store uploaded file."
+                )
+
+        elif fname == "tags":
+            tags_raw.append((await field.text()) or "")
+        elif fname == "name":
+            provided_name = (await field.text()) or None
+        elif fname == "user_metadata":
+            user_metadata_raw = (await field.text()) or None
+        elif fname == "id":
+            raise UploadError(
+                400,
+                "UNSUPPORTED_FIELD",
+                "Client-provided 'id' is not supported. Asset IDs are assigned by the server.",
+            )
+        elif fname == "mime_type":
+            provided_mime_type = ((await field.text()) or "").strip() or None
+        elif fname == "preview_id":
+            provided_preview_id = ((await field.text()) or "").strip() or None
+
+    if not file_present and not (provided_hash and provided_hash_exists):
+        raise UploadError(
+            400, "MISSING_FILE", "Form must include a 'file' part or a known 'hash'."
+        )
+
+    if (
+        file_present
+        and file_written == 0
+        and not (provided_hash and provided_hash_exists)
+    ):
+        delete_temp_file_if_exists(tmp_path)
+        raise UploadError(400, "EMPTY_UPLOAD", "Uploaded file is empty.")
+
+    return ParsedUpload(
+        file_present=file_present,
+        file_written=file_written,
+        file_client_name=file_client_name,
+        tmp_path=tmp_path,
+        tags_raw=tags_raw,
+        provided_name=provided_name,
+        user_metadata_raw=user_metadata_raw,
+        provided_hash=provided_hash,
+        provided_hash_exists=provided_hash_exists,
+        provided_mime_type=provided_mime_type,
+        provided_preview_id=provided_preview_id,
+    )
+
+
+def delete_temp_file_if_exists(tmp_path: str | None) -> None:
+    """Safely remove a temp file and its parent directory if empty."""
+    if tmp_path:
+        try:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+        except OSError as e:
+            logging.debug("Failed to delete temp file %s: %s", tmp_path, e)
+        try:
+            parent = os.path.dirname(tmp_path)
+            if parent and os.path.isdir(parent):
+                os.rmdir(parent)  # only succeeds if empty
+        except OSError:
+            pass