Function maybe_resize_image

src/utils/image_processor.py:242–350

Resize/compress ``buf`` so it fits within IMAGE_TARGET_RAW_SIZE and IMAGE_MAX_WIDTH/HEIGHT. Returns the (possibly unchanged) buffer with media type and dimensions. On a hard Pillow failure (corrupt image), raises ``ImageProcessingError`` so the caller can decide whether to fall back

(
    buf: bytes,
    original_size: int,
    format_hint: str | None = None,
)

# ---------------------------------------------------------------------------

def maybe_resize_image(
    buf: bytes,
    original_size: int,
    format_hint: str | None = None,
) -> ResizeResult:
    """Resize/compress ``buf`` so it fits within IMAGE_TARGET_RAW_SIZE and
    IMAGE_MAX_WIDTH/HEIGHT.

    Returns the (possibly unchanged) buffer with media type and dimensions.
    On a hard Pillow failure (corrupt image), raises ``ImageProcessingError``
    so the caller can decide whether to fall back to the raw bytes.

    Mirrors TS imageResizer.ts:169-433.
    """
    Image, UnidentifiedImageError = _pil()

    try:
        img = Image.open(io.BytesIO(buf))
        img.load()  # force decode now so we surface errors here
    except UnidentifiedImageError as e:
        _log_image_event("resize_failed", reason="unidentified", original_size=original_size)
        raise ImageProcessingError(f"Could not decode image: {e}") from e
    except Exception as e:
        _log_image_event("resize_failed", reason="open_error", error=str(e), original_size=original_size)
        raise ImageProcessingError(f"Could not open image: {e}") from e

    orig_w, orig_h = img.size
    media_type = _pil_format_to_media_type(img.format, format_hint or "image/png")

    # Fast path: already within envelope, no work needed.
    if (
        original_size <= IMAGE_TARGET_RAW_SIZE
        and orig_w <= IMAGE_MAX_WIDTH
        and orig_h <= IMAGE_MAX_HEIGHT
    ):
        return ResizeResult(
            data=buf,
            media_type=media_type,
            dimensions=ImageDimensions(
                original_width=orig_w,
                original_height=orig_h,
                display_width=orig_w,
                display_height=orig_h,
            ),
        )

    # Resize to fit IMAGE_MAX_WIDTH × IMAGE_MAX_HEIGHT, preserving aspect.
    resized_img, new_w, new_h = _resize_to_envelope(img, IMAGE_MAX_WIDTH, IMAGE_MAX_HEIGHT)

    # First encoding attempt at the original media type.
    try:
        encoded = _encode_image(resized_img, media_type)
    except Exception as e:
        _log_image_event("resize_failed", reason="encode_error", error=str(e))
        raise ImageProcessingError(f"Could not encode image: {e}") from e

    # If the resized+encoded version fits, ship it.
    if len(encoded) <= IMAGE_TARGET_RAW_SIZE: