"""Resolve generation reference images into provider-ready inputs.""" from __future__ import annotations import base64 import binascii import re from typing import Any, Protocol from urllib.parse import urlsplit from backend.dto.common import ApiError, ErrorCode from backend.services.image_service import ImageService from backend.services.material_catalog_resolver import is_trusted_advanced_metadata from core.storage import VfsStorage from core.text_utils import optional_text as _optional_text MAX_REFERENCE_IMAGE_BYTES = 25 * 1024 * 1024 MAX_REFERENCE_IMAGE_TOTAL_BYTES = 50 * 1024 * 1024 MAX_REFERENCE_IMAGES = 16 _SUPPORTED_IMAGE_MIMES = {"image/png", "image/jpeg", "image/gif", "image/webp"} _DATA_IMAGE_RE = re.compile(r"^data:([^;,]+)(?:;[^,]*)?;base64,(.*)$", re.IGNORECASE | re.DOTALL) class MaterialResolver(Protocol): def get_material(self, material_id: str) -> Any | None: ... class GenerationReferenceService: def __init__( self, image_service: ImageService, storage: VfsStorage, material_resolver: MaterialResolver | None = None, ): self.image_service = image_service self.storage = storage self.material_resolver = material_resolver def resolve(self, workflow_id: str, payload: dict[str, Any]) -> tuple[str, ...]: resolved: list[str] = [] seen: set[str] = set() image_cache: dict[str, Any] = {} storage_cache: dict[str, tuple[str, int]] = {} total_bytes = 0 for value, source, force_image_id in _reference_candidates(payload): prepared, canonical_key, byte_count = self._resolve_candidate( workflow_id, value, source=source, force_image_id=force_image_id, image_cache=image_cache, storage_cache=storage_cache, ) total_bytes = _append_reference( resolved, seen, prepared, canonical_key, byte_count, total_bytes, source, ) if self.material_resolver is not None: for material_id, source in _material_reference_candidates(payload): for prepared, canonical_key, byte_count in self._resolve_material_references( material_id, source=source, storage_cache=storage_cache, ): total_bytes = _append_reference( resolved, seen, prepared, canonical_key, byte_count, total_bytes, source, ) return tuple(resolved) def _resolve_material_references( self, material_id: str, *, source: str, storage_cache: dict[str, tuple[str, int]], ) -> list[tuple[str, str, int]]: material = self.material_resolver.get_material(material_id) if self.material_resolver else None if material is None: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "reference material does not exist", {"material_id": material_id, "source": source}, ) if str(material.recognition_status or "").strip() != "confirmed": raise ApiError( ErrorCode.VALIDATION_FAILED, "reference material is not confirmed", { "material_id": material_id, "recognition_status": material.recognition_status, "source": source, }, ) metadata = material.metadata if isinstance(getattr(material, "metadata", None), dict) else {} if is_trusted_advanced_metadata(metadata) and isinstance(metadata.get("style_set"), dict): # Quick/direct generation consumes the verified style capsule as # text. Source images are deliberately withheld to avoid leaking # sample characters, clothing, composition or scenery. return [] image_uri = _optional_text(material.image_uri) if not image_uri: raise ApiError( ErrorCode.VALIDATION_FAILED, "confirmed reference material has no image", {"material_id": material_id, "source": source}, ) # Detailed persisted rounds expand trusted style representatives only # after the concrete route capabilities are known. return [self._prepare_uri(image_uri, source=source, storage_cache=storage_cache)] def _resolve_candidate( self, workflow_id: str, value: Any, *, source: str, force_image_id: bool, image_cache: dict[str, Any], storage_cache: dict[str, tuple[str, int]], ) -> tuple[str, str, int]: if isinstance(value, dict): image_id = _optional_text(value.get("image_id")) if image_id: return self._resolve_image_id( workflow_id, image_id, source=source, image_cache=image_cache, storage_cache=storage_cache, ) for key in ("image_uri", "url", "data_url", "input_image"): reference = _optional_text(value.get(key)) if reference: return self._prepare_uri(reference, source=source, storage_cache=storage_cache) raise ApiError( ErrorCode.VALIDATION_FAILED, "reference image object must include image_id or image_uri", {"source": source}, ) reference = _optional_text(value) if not reference: raise ApiError( ErrorCode.VALIDATION_FAILED, "reference image cannot be empty", {"source": source}, ) if force_image_id or not _is_reference_uri(reference): return self._resolve_image_id( workflow_id, reference, source=source, image_cache=image_cache, storage_cache=storage_cache, ) return self._prepare_uri(reference, source=source, storage_cache=storage_cache) def _resolve_image_id( self, workflow_id: str, image_id: str, *, source: str, image_cache: dict[str, Any], storage_cache: dict[str, tuple[str, int]], ) -> tuple[str, str, int]: image = image_cache.get(image_id) if image is None: try: image = self.image_service.get_image(image_id) except ApiError as exc: if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND: raise raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "reference image does not exist", {"image_id": image_id, "source": source}, ) from exc image_cache[image_id] = image if image.workflow_id != workflow_id: raise ApiError( ErrorCode.VALIDATION_FAILED, "reference image does not belong to this workflow", { "image_id": image_id, "workflow_id": workflow_id, "image_workflow_id": image.workflow_id, "source": source, }, ) return self._prepare_uri(image.image_uri, source=source, storage_cache=storage_cache) def _prepare_uri( self, reference: str, *, source: str, storage_cache: dict[str, tuple[str, int]], ) -> tuple[str, str, int]: if reference.startswith("storage://"): cached = storage_cache.get(reference) if cached is None: try: path = self.storage.ensure_file(reference) size = path.stat().st_size if size > MAX_REFERENCE_IMAGE_BYTES: raise _image_too_large(reference, size, source) body = path.read_bytes() except ApiError as exc: if exc.error_code != ErrorCode.MEDIA_NOT_FOUND: raise raise ApiError( ErrorCode.MEDIA_NOT_FOUND, "reference image file does not exist", {"uri": reference, "source": source}, ) from exc except OSError as exc: raise ApiError( ErrorCode.MEDIA_NOT_FOUND, "reference image file could not be read", {"uri": reference, "source": source}, ) from exc if len(body) > MAX_REFERENCE_IMAGE_BYTES: raise _image_too_large(reference, len(body), source) mime = _detect_image_mime(body) if mime is None: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "reference image is not a supported PNG, JPEG, GIF, or WebP image", {"uri": reference, "source": source}, ) cached = (f"data:{mime};base64,{base64.b64encode(body).decode('ascii')}", len(body)) storage_cache[reference] = cached return cached[0], f"storage:{reference}", cached[1] if reference.lower().startswith("data:"): byte_count = _validate_data_image_url(reference, source=source) return reference, f"data:{reference}", byte_count parsed = urlsplit(reference) if parsed.scheme.lower() in {"http", "https"} and parsed.hostname: return reference, f"url:{reference}", 0 raise ApiError( ErrorCode.VALIDATION_FAILED, "reference image must be an image ID, storage URI, HTTP(S) URL, or image data URL", {"reference": reference, "source": source}, ) def _reference_candidates(payload: dict[str, Any]) -> list[tuple[Any, str, bool]]: candidates: list[tuple[Any, str, bool]] = [] for key in ("input_images", "image"): for index, value in enumerate(_ordered_values(payload.get(key))): candidates.append((value, f"{key}[{index}]", False)) dependency_context = payload.get("dependency_context") if not isinstance(dependency_context, dict): dependency_context = {} for index, value in enumerate(_ordered_values(dependency_context.get("selected_image_ids"))): candidates.append((value, f"dependency_context.selected_image_ids[{index}]", True)) metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {} for prefix, value in ( ("selected_draft_image_ids", payload.get("selected_draft_image_ids")), ("metadata.selected_draft_image_ids", metadata.get("selected_draft_image_ids")), ("dependency_context.selected_draft_image_ids", dependency_context.get("selected_draft_image_ids")), ): for index, image_id in enumerate(_ordered_values(value)): candidates.append((image_id, f"{prefix}[{index}]", True)) injection_template = ( dependency_context.get("injection_template") if isinstance(dependency_context.get("injection_template"), dict) else {} ) for index, image_id in enumerate(_ordered_values(injection_template.get("selected_draft_image_ids"))): candidates.append( ( image_id, f"dependency_context.injection_template.selected_draft_image_ids[{index}]", True, ) ) for prefix, value in ( ("stage_inputs", payload.get("stage_inputs")), ("metadata.stage_inputs", metadata.get("stage_inputs")), ("dependency_context.stage_inputs", dependency_context.get("stage_inputs")), ("dependency_context.injection_template.stage_inputs", injection_template.get("stage_inputs")), ): for index, reference in enumerate(_stage_input_references(value)): candidates.append((reference, f"{prefix}[{index}]", False)) return candidates def _material_reference_candidates(payload: dict[str, Any]) -> list[tuple[str, str]]: dependency_context = payload.get("dependency_context") if not isinstance(dependency_context, dict): return [] bindings = dependency_context.get("material_bindings") if not isinstance(bindings, dict): return [] candidates: list[tuple[str, str]] = [] generation_params = bindings.get("generation_params") if isinstance(generation_params, dict): for index, material_id in enumerate(_ordered_values(generation_params.get("reference_material_ids"))): text = _optional_text(material_id) if text: candidates.append( (text, f"dependency_context.material_bindings.generation_params.reference_material_ids[{index}]") ) active_bindings = bindings.get("active_bindings") if isinstance(active_bindings, list): for index, binding in enumerate(active_bindings): if not isinstance(binding, dict): continue material = binding.get("material") if isinstance(binding.get("material"), dict) else {} material_id = _optional_text(material.get("material_id") or binding.get("material_id")) if material_id: candidates.append( (material_id, f"dependency_context.material_bindings.active_bindings[{index}].material_id") ) result: list[tuple[str, str]] = [] seen: set[str] = set() for material_id, source in candidates: if material_id not in seen: result.append((material_id, source)) seen.add(material_id) return result def _append_reference( resolved: list[str], seen: set[str], prepared: str, canonical_key: str, byte_count: int, total_bytes: int, source: str, ) -> int: if canonical_key in seen: return total_bytes if len(resolved) >= MAX_REFERENCE_IMAGES: raise ApiError( ErrorCode.VALIDATION_FAILED, "too many reference images", {"max_reference_images": MAX_REFERENCE_IMAGES, "source": source}, ) if total_bytes + byte_count > MAX_REFERENCE_IMAGE_TOTAL_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "reference images exceed the total size limit", {"max_total_bytes": MAX_REFERENCE_IMAGE_TOTAL_BYTES, "source": source}, ) resolved.append(prepared) seen.add(canonical_key) return total_bytes + byte_count def _ordered_values(value: Any) -> list[Any]: values = list(value) if isinstance(value, (list, tuple)) else ([] if value is None else [value]) return [item for item in values if not isinstance(item, str) or item.strip()] def _stage_input_references(value: Any) -> list[Any]: if value is None: return [] if isinstance(value, str): return [value] if value.strip() else [] if isinstance(value, (list, tuple)): return [reference for item in value for reference in _stage_input_references(item)] if not isinstance(value, dict): return [] if any(_optional_text(value.get(key)) for key in ("image_id", "image_uri", "url", "data_url")): return [value] return [ reference for item in value.values() if isinstance(item, (dict, list, tuple)) for reference in _stage_input_references(item) ] def _validate_data_image_url(value: str, *, source: str) -> int: match = _DATA_IMAGE_RE.fullmatch(value) if match is None: raise ApiError( ErrorCode.VALIDATION_FAILED, "reference data URL must contain a base64-encoded image", {"source": source}, ) declared_mime = match.group(1).strip().lower() if declared_mime == "image/jpg": declared_mime = "image/jpeg" if declared_mime not in _SUPPORTED_IMAGE_MIMES: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "reference data URL uses an unsupported image type", {"mime": declared_mime, "source": source}, ) encoded = re.sub(r"\s+", "", match.group(2)) if len(encoded) > ((MAX_REFERENCE_IMAGE_BYTES + 2) // 3) * 4: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "reference data URL exceeds the size limit", {"max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, ) try: body = base64.b64decode(encoded, validate=True) except (binascii.Error, ValueError) as exc: raise ApiError( ErrorCode.VALIDATION_FAILED, "reference data URL contains invalid base64", {"source": source}, ) from exc if len(body) > MAX_REFERENCE_IMAGE_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "reference data URL exceeds the size limit", {"bytes": len(body), "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, ) detected_mime = _detect_image_mime(body) if detected_mime is None: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "reference data URL does not contain a supported image", {"source": source}, ) if detected_mime != declared_mime: raise ApiError( ErrorCode.VALIDATION_FAILED, "reference data URL MIME type does not match its image payload", {"declared_mime": declared_mime, "detected_mime": detected_mime, "source": source}, ) return len(body) def _detect_image_mime(body: bytes) -> str | None: if body.startswith(b"\x89PNG\r\n\x1a\n"): return "image/png" if body.startswith(b"\xff\xd8\xff"): return "image/jpeg" if body.startswith((b"GIF87a", b"GIF89a")): return "image/gif" if len(body) >= 12 and body.startswith(b"RIFF") and body[8:12] == b"WEBP": return "image/webp" return None def _image_too_large(uri: str, size: int, source: str) -> ApiError: return ApiError( ErrorCode.UPLOAD_TOO_LARGE, "reference image exceeds the size limit", {"uri": uri, "bytes": size, "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, ) def _is_reference_uri(value: str) -> bool: return value.lower().startswith(("storage://", "data:", "http://", "https://"))