clairic / clairic_runtime /embedded.py
areneau's picture
Add complete Clairic Transformers package
f65336d verified
Raw History Blame Contribute Delete
5.42 kB
"""Validation for embedded request images.
Callers translate ``EmbeddedImageError`` into their own validation error type.
The strict mode verifies the complete raster with Pillow; the signature mode
intentionally accepts header-only images for backends that validate only magic
bytes before forwarding the image to another service.
"""
from __future__ import annotations
import base64
import binascii
import io
import re
from collections.abc import Iterable
MAX_IMAGES = 4
MAX_IMAGE_BYTES = 4 * 1024 * 1024
MAX_IMAGES_BYTES = 8 * 1024 * 1024
_STRICT_DATA_URI = re.compile(
r"^data:(image/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/]*={0,2})$", re.IGNORECASE
)
_DATA_URL = re.compile(r"^data:([^;,]+);base64,(.*)$", re.DOTALL)
_FORMATS = {"image/png": "PNG", "image/jpeg": "JPEG", "image/webp": "WEBP"}
class EmbeddedImageError(ValueError):
"""A request-image failure, with a stable code for the serving layer."""
def __init__(self, code: str, message: str) -> None:
super().__init__(message)
self.code = code
def normalize_embedded_image(
value: object,
*,
strict: bool = False,
max_image_bytes: int = MAX_IMAGE_BYTES,
max_pixels: int = 16_000_000,
) -> dict[str, str]:
"""Normalize a data URL or exact ``{content_type, base64}`` object.
``strict=True`` verifies restricted data-URI syntax and complete raster data
with Pillow, including the dimension limit. The default checks image
signatures and accepts a more permissive data-URL syntax.
"""
if isinstance(value, str):
matched = (_STRICT_DATA_URI if strict else _DATA_URL).fullmatch(value)
if matched is None:
label = "URI" if strict else "URL"
raise EmbeddedImageError(
"invalid_image", f"image must be an embedded base64 data {label}"
)
value = {"content_type": matched.group(1), "base64": matched.group(2)}
if type(value) is not dict or set(value) != {"content_type", "base64"}:
raise EmbeddedImageError("invalid_image", "image object has invalid fields")
content_type = value["content_type"]
encoded = value["base64"]
if type(content_type) is not str or type(encoded) is not str:
raise EmbeddedImageError("invalid_image", "image fields must be strings")
canonical_type = content_type.lower().replace("image/jpg", "image/jpeg")
if canonical_type not in _FORMATS:
raise EmbeddedImageError("invalid_image", "image content type is not supported")
try:
decoded = base64.b64decode(encoded, validate=True)
except (binascii.Error, ValueError) as error:
raise EmbeddedImageError(
"invalid_image", "image base64 is malformed"
) from error
if not decoded:
raise EmbeddedImageError("invalid_image", "image payload is empty")
if len(decoded) > max_image_bytes:
raise EmbeddedImageError(
"image_too_large", "image exceeds the decoded byte limit"
)
if strict:
_verify_raster(decoded, _FORMATS[canonical_type], max_pixels=max_pixels)
elif not _has_image_signature(canonical_type, decoded):
raise EmbeddedImageError(
"invalid_image", "image payload does not match its content type"
)
return {
"content_type": canonical_type,
"base64": base64.b64encode(decoded).decode("ascii"),
}
def _verify_raster(data: bytes, expected_format: str, *, max_pixels: int) -> None:
from PIL import Image, UnidentifiedImageError
try:
with Image.open(io.BytesIO(data)) as image:
if image.format != expected_format:
raise EmbeddedImageError(
"invalid_image", "image payload does not match its content type"
)
if image.width * image.height > max_pixels:
raise EmbeddedImageError(
"invalid_image", "image dimensions are too large"
)
image.verify()
except EmbeddedImageError:
raise
except (
UnidentifiedImageError,
OSError,
ValueError,
Image.DecompressionBombError,
) as error:
raise EmbeddedImageError("invalid_image", "image payload is invalid") from error
def _has_image_signature(content_type: str, data: bytes) -> bool:
if content_type == "image/png":
return data.startswith(b"\x89PNG\r\n\x1a\n")
if content_type == "image/jpeg":
return data.startswith(b"\xff\xd8\xff")
return len(data) >= 12 and data.startswith(b"RIFF") and data[8:12] == b"WEBP"
def decoded_base64_size(encoded: str) -> int:
"""Size of already validated, canonical base64 without decoding again."""
return len(encoded) * 3 // 4 - (len(encoded) - len(encoded.rstrip("=")))
def validate_image_count(value: object, *, max_images: int = MAX_IMAGES) -> object:
if not isinstance(value, (list, tuple)):
raise EmbeddedImageError("invalid_image", "images must be an array")
if len(value) > max_images:
raise EmbeddedImageError(
"too_many_images", "request exceeds the image count limit"
)
return value
def validate_total_image_bytes(
sizes: Iterable[int], *, max_bytes: int = MAX_IMAGES_BYTES
) -> None:
if sum(sizes) > max_bytes:
raise EmbeddedImageError(
"images_too_large", "images exceed the aggregate decoded byte limit"
)