"""Image validation, watermarking and thumbnail generation (Pillow). Pipeline for every admin upload: read_upload() -> size limit, extension allow-list, real content sniffing, pixel limit process_image() -> save untouched original, save watermarked copy, save WEBP thumbnail All files get server-generated UUID names; client filenames are only stored as metadata. """ from __future__ import annotations import io import logging import os import uuid import warnings from dataclasses import dataclass from functools import lru_cache from pathlib import Path, PurePosixPath from fastapi import UploadFile, status from PIL import Image, ImageFilter, ImageOps, ImageStat, UnidentifiedImageError from app.core.config import settings logger = logging.getLogger(__name__) ORIGINALS = "originals" WATERMARKED = "watermarked" THUMBNAILS = "thumbnails" # Pillow format -> (allowed extensions, canonical extension, mime type) SUPPORTED_FORMATS: dict[str, tuple[set[str], str, str]] = { "JPEG": ({".jpg", ".jpeg"}, ".jpg", "image/jpeg"), "PNG": ({".png"}, ".png", "image/png"), "WEBP": ({".webp"}, ".webp", "image/webp"), } ALLOWED_EXTENSIONS = set().union(*(exts for exts, _, _ in SUPPORTED_FORMATS.values())) Image.MAX_IMAGE_PIXELS = settings.MAX_IMAGE_PIXELS class ImageValidationError(Exception): def __init__(self, message: str, status_code: int = status.HTTP_400_BAD_REQUEST): super().__init__(message) self.message = message self.status_code = status_code class WatermarkUnavailableError(Exception): """Raised when the official logo file is missing or unreadable.""" @dataclass(frozen=True) class ValidatedUpload: data: bytes original_filename: str pil_format: str # JPEG | PNG | WEBP @dataclass(frozen=True) class StoredImage: original_path: str watermarked_path: str thumbnail_path: str mime_type: str file_size: int width: int height: int # --------------------------------------------------------------------------- validation def _sanitise_display_name(name: str | None) -> str: """Keep only a safe basename for display; never used to build a path.""" base = PurePosixPath((name or "").replace("\\", "/")).name base = "".join(ch for ch in base if ch.isprintable()).strip() return base[:255] or "upload" async def read_upload(upload: UploadFile) -> ValidatedUpload: display_name = _sanitise_display_name(upload.filename) ext = os.path.splitext(display_name)[1].lower() if ext not in ALLOWED_EXTENSIONS: raise ImageValidationError( f"'{display_name}': unsupported file type. Allowed: JPG, JPEG, PNG, WEBP.", status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, ) limit = settings.max_upload_bytes chunks: list[bytes] = [] total = 0 while chunk := await upload.read(1024 * 1024): total += len(chunk) if total > limit: raise ImageValidationError( f"'{display_name}': file is larger than {settings.MAX_UPLOAD_SIZE_MB} MB.", status.HTTP_413_CONTENT_TOO_LARGE, ) chunks.append(chunk) data = b"".join(chunks) if not data: raise ImageValidationError(f"'{display_name}': file is empty.") pil_format = _sniff_image(data, display_name) allowed_exts = SUPPORTED_FORMATS[pil_format][0] if ext not in allowed_exts: raise ImageValidationError( f"'{display_name}': file extension does not match its content ({pil_format}).", status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, ) return ValidatedUpload(data=data, original_filename=display_name, pil_format=pil_format) def _sniff_image(data: bytes, display_name: str) -> str: """Identify the real format from file content and fully decode it once.""" try: with warnings.catch_warnings(): warnings.simplefilter("error", Image.DecompressionBombWarning) with Image.open(io.BytesIO(data)) as img: fmt = img.format if fmt not in SUPPORTED_FORMATS: raise ImageValidationError( f"'{display_name}': unsupported image format.", status.HTTP_415_UNSUPPORTED_MEDIA_TYPE, ) if getattr(img, "n_frames", 1) > 1: raise ImageValidationError(f"'{display_name}': animated images are not supported.") img.verify() # structural check with Image.open(io.BytesIO(data)) as img: img.load() # full decode catches truncated / corrupt pixel data except ImageValidationError: raise except (Image.DecompressionBombError, Image.DecompressionBombWarning): raise ImageValidationError( f"'{display_name}': image dimensions are too large.", status.HTTP_413_CONTENT_TOO_LARGE, ) from None except (UnidentifiedImageError, OSError, SyntaxError, ValueError): raise ImageValidationError(f"'{display_name}': file is not a valid image.") from None return fmt # --------------------------------------------------------------------------- watermark @lru_cache(maxsize=4) def _load_logo_cached(path: str, mtime: float) -> Image.Image: with Image.open(path) as logo: logo.load() return logo.convert("RGBA") def load_logo() -> Image.Image: path = Path(settings.WATERMARK_LOGO_PATH) try: return _load_logo_cached(str(path), path.stat().st_mtime) except FileNotFoundError: raise WatermarkUnavailableError( f"Watermark logo not found at {path}. Add the official Saura Shakti logo (transparent PNG)." ) from None except (UnidentifiedImageError, OSError) as exc: raise WatermarkUnavailableError(f"Watermark logo at {path} is not a readable image: {exc}") from None def _luminance(img: Image.Image, mask: Image.Image | None = None) -> float: """Mean perceived brightness 0..255 (optionally weighted by a mask).""" stat = ImageStat.Stat(img.convert("L"), mask) return stat.mean[0] if stat.count[0] else 127.0 def apply_watermark(image: Image.Image, logo: Image.Image) -> Image.Image: """Composite the logo bottom-right. Returns a new RGBA image of identical size.""" base = image.convert("RGBA") W, H = base.size short_side = min(W, H) # --- proportional sizing (aspect ratio always preserved) --- target_w = W * settings.WATERMARK_WIDTH_RATIO target_w = max(settings.WATERMARK_MIN_WIDTH, min(settings.WATERMARK_MAX_WIDTH, target_w)) target_w = min(target_w, W * 0.5) # never dominate small images target_w = min(target_w, logo.width) # never upscale the logo (keeps it crisp) scale = target_w / logo.width if logo.height * scale > H * 0.3: # very tall logos: limit by height instead scale = (H * 0.3) / logo.height lw, lh = max(1, round(logo.width * scale)), max(1, round(logo.height * scale)) mark = logo.resize((lw, lh), Image.Resampling.LANCZOS) margin = max(8, round(short_side * settings.WATERMARK_MARGIN_RATIO)) x, y = W - margin - lw, H - margin - lh x, y = max(0, x), max(0, y) # --- adaptive contrast halo: visible on both bright and dark photos --- logo_alpha = mark.getchannel("A") region = base.crop((x, y, x + lw, y + lh)) region_lum = _luminance(region) logo_lum = _luminance(mark, logo_alpha) halo_rgb = (0, 0, 0) if logo_lum >= 128 else (255, 255, 255) contrast = abs(region_lum - logo_lum) / 255.0 halo_opacity = min(0.7, settings.WATERMARK_SHADOW_OPACITY + (1 - contrast) * 0.3) pad = max(2, round(lw * 0.04)) blur = max(1.5, lw * 0.02) halo_mask = Image.new("L", (lw + 2 * pad, lh + 2 * pad), 0) halo_mask.paste(logo_alpha, (pad, pad)) halo_mask = halo_mask.filter(ImageFilter.MaxFilter(3)).filter(ImageFilter.GaussianBlur(blur)) halo_mask = halo_mask.point(lambda a: round(a * halo_opacity)) halo = Image.new("RGBA", halo_mask.size, (*halo_rgb, 0)) halo.putalpha(halo_mask) # --- apply logo transparency --- mark.putalpha(logo_alpha.point(lambda a: round(a * settings.WATERMARK_OPACITY))) overlay = Image.new("RGBA", base.size, (0, 0, 0, 0)) overlay.alpha_composite(halo, (max(0, x - pad), max(0, y - pad)), (max(0, pad - x), max(0, pad - y))) overlay.alpha_composite(mark, (x, y)) return Image.alpha_composite(base, overlay) # --------------------------------------------------------------------------- storage def _upload_root() -> Path: return Path(settings.UPLOAD_DIR).resolve() def ensure_upload_dirs() -> None: for sub in (ORIGINALS, WATERMARKED, THUMBNAILS): (_upload_root() / sub).mkdir(parents=True, exist_ok=True) def _write_atomic(rel_path: str, writer) -> None: dest = _upload_root() / rel_path tmp = dest.with_name(f".{dest.name}.tmp") try: with open(tmp, "wb") as fh: writer(fh) os.replace(tmp, dest) finally: tmp.unlink(missing_ok=True) def resolve_media_path(rel_path: str) -> Path: """Resolve a stored relative path, refusing anything outside UPLOAD_DIR.""" root = _upload_root() full = (root / rel_path).resolve() if not full.is_relative_to(root) or full == root: raise ValueError(f"Refusing path outside upload dir: {rel_path!r}") return full def delete_media_files(*rel_paths: str | None) -> None: for rel in rel_paths: if not rel: continue try: resolve_media_path(rel).unlink(missing_ok=True) except (ValueError, OSError) as exc: # log, never fail the request on cleanup logger.warning("Could not delete media file %s: %s", rel, exc) def media_url(rel_path: str | None) -> str | None: if not rel_path: return None return f"{settings.MEDIA_BASE_URL.rstrip('/')}/{rel_path}" def _encode(img: Image.Image, pil_format: str, has_alpha: bool, icc: bytes | None, fh) -> None: extra = {"icc_profile": icc} if icc else {} if pil_format == "JPEG": img.convert("RGB").save(fh, "JPEG", quality=92, optimize=True, progressive=True, **extra) elif pil_format == "PNG": (img if has_alpha else img.convert("RGB")).save(fh, "PNG", compress_level=6, **extra) else: # WEBP (img if has_alpha else img.convert("RGB")).save(fh, "WEBP", quality=92, method=4, **extra) def process_image(upload: ValidatedUpload) -> StoredImage: """CPU-bound: call via run_in_threadpool. Cleans up its own files on failure.""" logo = load_logo() # fail fast before writing anything ensure_upload_dirs() _, ext, mime = SUPPORTED_FORMATS[upload.pil_format] stem = uuid.uuid4().hex original_rel = f"{ORIGINALS}/{stem}{ext}" watermarked_rel = f"{WATERMARKED}/{stem}{ext}" thumbnail_rel = f"{THUMBNAILS}/{stem}.webp" written: list[str] = [] try: # 1. untouched original (private, never served publicly) _write_atomic(original_rel, lambda fh: fh.write(upload.data)) written.append(original_rel) with Image.open(io.BytesIO(upload.data)) as src: icc = src.info.get("icc_profile") img = ImageOps.exif_transpose(src) # honour camera orientation has_alpha = img.mode in ("RGBA", "LA", "PA") or ( img.mode == "P" and "transparency" in img.info ) if img.mode not in ("RGB", "RGBA"): img = img.convert("RGBA" if has_alpha else "RGB") # 2. watermarked full-size copy (EXIF dropped: avoids leaking GPS data) marked = apply_watermark(img, logo) width, height = marked.size _write_atomic( watermarked_rel, lambda fh: _encode(marked, upload.pil_format, has_alpha, icc, fh) ) written.append(watermarked_rel) # 3. thumbnail derived from the watermarked image thumb = marked.copy() thumb.thumbnail( (settings.THUMBNAIL_MAX_SIZE, settings.THUMBNAIL_MAX_SIZE), Image.Resampling.LANCZOS ) if not has_alpha: thumb = thumb.convert("RGB") _write_atomic(thumbnail_rel, lambda fh: thumb.save(fh, "WEBP", quality=82, method=4)) written.append(thumbnail_rel) except Exception: delete_media_files(*written) raise return StoredImage( original_path=original_rel, watermarked_path=watermarked_rel, thumbnail_path=thumbnail_rel, mime_type=mime, file_size=len(upload.data), width=width, height=height, )