Files
Shubhankar45 53dbfa976b -
2026-11-13 12:14:55 +00:00

334 lines
12 KiB
Python

"""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,
)