bambuddy/backend/app/services/model_providers/makerworld/service.py

"""MakerWorld API service.

Thin async client for MakerWorld's ``/api/v1/design-service/*`` endpoints.
Lets Bambuddy resolve a MakerWorld URL, enumerate plate/profile metadata, and
download the 3MF bundle so users can import and print MakerWorld models
without leaving the app.

The endpoints and header set were reverse-engineered from the
`kloshi-io/makerworld-api-reverse` TypeScript project (Apache-2.0) and
cross-validated against live MakerWorld traffic. Authenticated calls reuse
Bambuddy's existing Bambu Cloud bearer token (same SSO backend — no separate
OAuth flow needed; see ``model_providers/makerworld/auth.py``).

Implements the :class:`ProviderService` interface — the route layer drives it
through ``resolve`` / ``get_download`` / ``download`` so the same flow can be
reused for future providers.

Only interoperability — not affiliated with or endorsed by MakerWorld or
Bambu Lab, and not intended to circumvent any access control.
"""

from __future__ import annotations

import asyncio
import io
import logging
import zipfile
from collections.abc import Awaitable, Callable
from dataclasses import replace
from typing import Any
from urllib.parse import urlparse

import httpx

from backend.app.services.bambu_cloud import is_captcha_challenge, is_expiry_401
from backend.app.services.model_providers.base import (
    ProviderDownload,
    ProviderDownloadInfo,
    ProviderResolvedModel,
    ProviderResourceRef,
    ProviderService,
    ProviderStatus,
)
from backend.app.services.model_providers.makerworld.auth import is_cloud_token_invalid
from backend.app.services.model_providers.makerworld.errors import (
    MakerWorldAuthError,
    MakerWorldForbiddenError,
    MakerWorldNotFoundError,
    MakerWorldUnavailableError,
    MakerWorldUrlError,
)
from backend.app.services.model_providers.makerworld.http import (
    _ALLOWED_DOWNLOAD_SUFFIXES,
    _CLIENT_HEADERS,
    _IMAGE_EXT_TO_MIME,
    _MAX_3MF_BYTES,
    _MAX_THUMBNAIL_BYTES,
    _REFUSED_THUMBNAIL_MIMES,
    MAKERWORLD_API_BASE,
    MAKERWORLD_CDN_HOSTS,
    _download_s3_urllib,
    _extract_upstream_error,
)

logger = logging.getLogger(__name__)

_shared_http_client: httpx.AsyncClient | None = None


def set_shared_http_client(client: httpx.AsyncClient | None) -> None:
    """Register an app-scoped ``httpx.AsyncClient`` for service reuse.

    Same pattern as ``bambu_cloud.set_shared_http_client`` — lets the FastAPI
    lifespan share one connection pool across per-request service instances.
    Must live in the same module as the service class so ``__init__`` reads
    the live value rather than an import-time snapshot.
    """
    global _shared_http_client
    _shared_http_client = client


# Shown whenever Bambu rejects the stored bearer. Bambu's own 401 body is
# ``{"code":4,"error":"Please login.","message":""}`` and we used to forward that
# string verbatim, which surfaced as a "Please login." toast on a UI that was
# simultaneously reporting the user as connected — maximally confusing, and it
# named no page to go to. Say what happened and where to fix it. Bambu Cloud
# sign-in lives on the Profiles page (ProfilesPage.tsx, "Cloud Profiles" tab);
# there is no Settings → Bambu Cloud page, which is what the old fallback text
# told people to look for.
_SIGN_IN_EXPIRED_MESSAGE = (
    "Your Bambu Cloud sign-in has expired. Open the Profiles page and sign in to Bambu Cloud again."
)


def _is_readable_zip(data: bytes) -> bool:
    """Whether ``data`` is a zip whose directory can be read."""
    try:
        with zipfile.ZipFile(io.BytesIO(data)) as archive:
            archive.namelist()
        return True
    except (zipfile.BadZipFile, ValueError, OSError, EOFError):
        return False


class MakerWorldService(ProviderService):
    """Per-request MakerWorld API client.

    Mirrors ``BambuCloudService``'s construction pattern so callers can
    instantiate per request, reuse the shared connection pool in production,
    inject a client in tests, and close the client only if they own it.
    """

    def __init__(
        self,
        *,
        client: httpx.AsyncClient | None = None,
        auth_token: str | None = None,
        user: Any | None = None,
        on_auth_failure: Callable[[], Awaitable[None]] | None = None,
        thumbnail_hosts: tuple[str, ...] = MAKERWORLD_CDN_HOSTS,
        download_hosts: tuple[str, ...] = MAKERWORLD_CDN_HOSTS,
    ):
        # Fired when Bambu rejects the stored token (401). MakerWorld runs on the
        # same Bambu Cloud bearer as everything else, so a rejection here means
        # the credential is dead app-wide — see ``build_authenticated_cloud``.
        self._on_auth_failure = on_auth_failure
        self._auth_failure_reported = False
        # SSRF allowlists for the thumbnail proxy and the 3MF download guard.
        # Default to MakerWorld's CDN hosts; ``MakerWorldProvider.build_service``
        # passes ``ModelProvider.thumbnail_hosts()`` / ``download_hosts()`` so
        # the guards are driven by the provider descriptor rather than enforced
        # by coincidence (interface contract on ``ProviderService``).
        self._thumbnail_hosts = tuple(thumbnail_hosts)
        self._download_hosts = tuple(download_hosts)
        if client is not None:
            self._client = client
            self._owns_client = False
        elif _shared_http_client is not None:
            self._client = _shared_http_client
            self._owns_client = False
        else:
            self._client = httpx.AsyncClient(timeout=30.0)
            self._owns_client = True
        self._auth_token = auth_token
        self._user = user

    async def close(self) -> None:
        if self._owns_client:
            await self._client.aclose()

    async def _note_auth_failure(self, response: httpx.Response) -> None:
        """Durably record a dead credential — only for Bambu's genuine expiry 401.

        A MakerWorld 401 without the ``{"code":4,"error":"Please login."}``
        signature is endpoint- or edge-specific noise, not an expired token;
        invalidating on it would sign the user out of the whole cloud
        integration on a single stray rejection (the #2562 follow-up
        regression). Best-effort, once per service instance.
        """
        if not is_expiry_401(response):
            logger.info("MakerWorld returned 401 without the expiry signature — not signing the stored token out")
            return
        if self._on_auth_failure is None or self._auth_failure_reported:
            return
        self._auth_failure_reported = True
        try:
            await self._on_auth_failure()
        except Exception:
            logger.exception("Failed to record Bambu Cloud auth failure from MakerWorld")

    def _headers(self) -> dict[str, str]:
        headers = dict(_CLIENT_HEADERS)
        if self._auth_token:
            headers["Authorization"] = f"Bearer {self._auth_token}"
        return headers

    # ------------------------------------------------------------- interface

    async def get_status(self, db: Any) -> ProviderStatus:
        """Whether the caller can download: needs a stored, non-rejected Bambu
        Cloud token. ``credential_rejected`` is the machine-readable expired
        state; ``auth_error`` names it for humans so the UI can say "your
        sign-in expired" rather than a bare "sign in"."""
        has_token = bool(self._auth_token)
        expired = has_token and await is_cloud_token_invalid(db, self._user)
        return ProviderStatus(
            authenticated=has_token,
            can_download=has_token and not expired,
            auth_error=_SIGN_IN_EXPIRED_MESSAGE if expired else None,
            credential_rejected=expired,
        )

    async def resolve(self, ref: ProviderResourceRef) -> ProviderResolvedModel:
        """Fetch full model metadata + the plate list, merging per-instance
        printer compatibility so the frontend can show "sliced for A1 / also
        compatible with H2D, P1S" before the user picks a plate."""
        model_id = int(ref.external_id)
        design = await self.get_design(model_id)
        instances_envelope = await self.get_design_instances(model_id)

        # MakerWorld's instances payload is ``{"total": N, "hits": [...]}``;
        # normalise the null case to an empty list so the frontend doesn't
        # have to handle null vs [] both ways.
        instances = instances_envelope.get("hits") or []
        if not isinstance(instances, list):
            instances = []

        # /instances/hits omits the per-instance printer compatibility info
        # that /design.instances[].extention.modelInfo carries. Merge it in.
        design_instances = design.get("instances") or []
        if isinstance(design_instances, list):
            compat_by_id = {}
            for di in design_instances:
                if not isinstance(di, dict):
                    continue
                iid = di.get("id")
                if iid is None:
                    continue
                ext = (di.get("extention") or {}).get("modelInfo") or {}
                compat_by_id[iid] = {
                    "compatibility": ext.get("compatibility"),
                    "otherCompatibility": ext.get("otherCompatibility"),
                }
            for inst in instances:
                if not isinstance(inst, dict):
                    continue
                iid = inst.get("id")
                extra = compat_by_id.get(iid)
                if extra:
                    inst["compatibility"] = extra["compatibility"]
                    inst["otherCompatibility"] = extra["otherCompatibility"]

        return ProviderResolvedModel(ref=ref, design=design, instances=instances)

    async def get_download(self, ref: ProviderResourceRef) -> ProviderDownloadInfo:
        """Resolve the signed 3MF download for a specific MakerWorld profile.

        Handles the provider-specific dance: the iot-service endpoint needs
        the *alphanumeric* ``modelId`` (e.g. ``"US2bb73b106683e5"``) from the
        design, not the integer design id, and picks a default profile when
        the caller didn't specify one. Enriches ``ref.sub_id`` with the actual
        profile used so the route can build the per-plate dedupe key.
        """
        model_id = int(ref.external_id)
        design = await self.get_design(model_id)

        alphanumeric_model_id = design.get("modelId")
        if not isinstance(alphanumeric_model_id, str) or not alphanumeric_model_id:
            raise MakerWorldUnavailableError("MakerWorld design metadata missing the modelId field")

        profile_id = int(ref.sub_id) if ref.sub_id else None
        if profile_id is None:
            for instance in design.get("instances") or []:
                pid = instance.get("profileId")
                if isinstance(pid, int) and pid > 0:
                    profile_id = pid
                    break
            if profile_id is None:
                envelope = await self.get_design_instances(model_id)
                for hit in envelope.get("hits") or []:
                    pid = hit.get("profileId")
                    if isinstance(pid, int) and pid > 0:
                        profile_id = pid
                        break
            if profile_id is None:
                raise MakerWorldUnavailableError("MakerWorld returned no instances for this model")

        manifest = await self.get_profile_download(profile_id, alphanumeric_model_id)

        signed_url = manifest.get("url")
        if not signed_url or not isinstance(signed_url, str):
            raise MakerWorldUnavailableError("MakerWorld did not return a download URL")

        # Raw upstream name — the route layer basenames / percent-decodes it
        # as defence-in-depth before persisting.
        raw_name = manifest.get("name")
        suggested_filename = raw_name if isinstance(raw_name, str) and raw_name.strip() else ""

        return ProviderDownloadInfo(
            ref=replace(ref, sub_id=str(profile_id)),
            url=signed_url,
            suggested_filename=suggested_filename,
        )

    async def download(self, info: ProviderDownloadInfo) -> ProviderDownload:
        """Fetch the 3MF bytes for a signed URL, returning ``(bytes, filename)``."""
        file_bytes, download_filename = await self.download_3mf(info.url)
        # A 3MF is a zip. A truncated body or an error page served with 200
        # would otherwise be stored, and kept, as the model's file.
        if not _is_readable_zip(file_bytes):
            raise MakerWorldUnavailableError("MakerWorld sent a file that is not a valid 3MF")
        return ProviderDownload(file_bytes=file_bytes, filename=download_filename)

    # ---------------------------------------------------------------- endpoints

    async def _get_json(self, path: str) -> dict[str, Any]:
        """GET ``{MAKERWORLD_API_BASE}{path}`` returning the decoded JSON body.

        Raises ``MakerWorld{Auth,Forbidden,NotFound,Unavailable}Error`` based
        on status. Retries once on 418 (Cloudflare bot-detection) with a
        short backoff — that flagging is often request-scoped and clears on
        a subsequent call; hammering beyond one retry provokes a stronger
        block, so we stop there and surface a useful error.
        """
        url = f"{MAKERWORLD_API_BASE}{path}"

        for attempt in range(2):
            try:
                response = await self._client.get(url, headers=self._headers(), timeout=30.0)
            except httpx.TimeoutException as exc:
                raise MakerWorldUnavailableError(f"MakerWorld request timed out: {exc}") from exc
            except httpx.HTTPError as exc:
                raise MakerWorldUnavailableError(f"MakerWorld request failed: {exc}") from exc

            if response.status_code == 418 and attempt == 0:
                logger.info("MakerWorld returned 418 for %s; retrying once after backoff", path)
                await asyncio.sleep(1.5)
                continue
            break

        # 401: genuine auth failure — token expired, malformed, not accepted.
        # 403: MakerWorld accepted the token but refuses the specific resource
        # — usually content gating (points-redeemable, purchase-required,
        # region-restricted, early-access). These must surface differently
        # because the UI remedy is completely different: 401 → re-login,
        # 403 → user has to go to MakerWorld and meet the access requirement.
        if response.status_code == 401:
            if self._auth_token:
                # We sent a token and Bambu refused it — the credential is dead,
                # not merely absent. Record that before raising so the rest of the
                # app stops claiming the user is connected.
                await self._note_auth_failure(response)
                raise MakerWorldAuthError(_SIGN_IN_EXPIRED_MESSAGE)
            raise MakerWorldAuthError(f"Signing in to Bambu Cloud is required for {path}")
        if response.status_code == 403:
            upstream = _extract_upstream_error(response)
            raise MakerWorldForbiddenError(
                upstream
                or f"MakerWorld refused access to {path} — the model may require purchase, points redemption, or be region-restricted"
            )
        if response.status_code == 404:
            raise MakerWorldNotFoundError(f"MakerWorld resource not found: {path}")
        if response.status_code == 418:
            # Bambu's anti-abuse layer challenges the source IP with a CAPTCHA
            # (``{"captchaId":"...","error":"We need to confirm..."}``). This is
            # application-level, not Cloudflare-edge, and clears on its own
            # within 1–4 hours of quiet traffic. There's no server-side solve —
            # CAPTCHAs are intentionally unsolvable without a real browser.
            # Surface the upstream message so the user can recognise it and
            # reach for the "Open on MakerWorld" fallback instead of thinking
            # the feature is broken.
            #
            # The same challenge also lands on the Bambu Cloud sign-in endpoint,
            # so the shape test lives in ``bambu_cloud`` and is shared (#2790).
            # It used to be a bare "robot" substring check on the error text,
            # which missed a challenge worded any other way.
            if is_captcha_challenge(response):
                upstream = _extract_upstream_error(response)
                detail = f" ({upstream})" if upstream else ""
                raise MakerWorldUnavailableError(
                    f"MakerWorld is challenging this IP with a CAPTCHA{detail}. "
                    "This usually clears within a few hours. In the meantime, use "
                    "'Open on MakerWorld' below to download the 3MF manually."
                )
            raise MakerWorldUnavailableError(
                f"MakerWorld blocked the request (HTTP 418) for {path}. "
                "Try again in a few minutes, or use 'Open on MakerWorld' to import manually."
            )
        if response.status_code == 429:
            raise MakerWorldUnavailableError(
                f"MakerWorld rate-limited the request (HTTP 429) for {path}. Try again shortly."
            )
        if response.status_code >= 500:
            raise MakerWorldUnavailableError(f"MakerWorld server error (HTTP {response.status_code}) for {path}")
        if response.status_code != 200:
            raise MakerWorldUnavailableError(f"MakerWorld unexpected status {response.status_code} for {path}")

        try:
            data = response.json()
        except ValueError as exc:
            raise MakerWorldUnavailableError(f"MakerWorld returned non-JSON for {path}") from exc

        if not isinstance(data, dict):
            raise MakerWorldUnavailableError(
                f"MakerWorld returned unexpected JSON shape for {path}: {type(data).__name__}"
            )
        return data

    async def get_design(self, model_id: int) -> dict[str, Any]:
        """Fetch full model metadata. Works anonymously.

        Returns the MakerWorld ``design`` object — title, summary, creator,
        license, tags, coverUrl, instances[] with profileId+cover per plate,
        categories, etc.
        """
        return await self._get_json(f"/design/{int(model_id)}")

    async def get_design_instances(self, model_id: int) -> dict[str, Any]:
        """Fetch list of profiles/instances for a model. Works anonymously.

        Returns ``{"total": N, "hits": [{id, profileId, title, cover,
        instanceCreator, instanceFilaments, needAms, ...}, ...]}``.
        """
        return await self._get_json(f"/design/{int(model_id)}/instances")

    async def get_profile(self, profile_id: int) -> dict[str, Any]:
        """Fetch a single profile's summary (designId/modelId/title/cover/
        instanceId). Works anonymously.
        """
        return await self._get_json(f"/profile/{int(profile_id)}")

    async def get_profile_download(self, profile_id: int, model_id: str) -> dict[str, Any]:
        """Fetch the signed 3MF download URL for a specific MakerWorld profile.

        Note on ``model_id`` — this is MakerWorld's internal alphanumeric
        identifier (e.g. ``"US2bb73b106683e5"``), **not** the integer
        ``designId`` that appears in the ``/models/{N}`` URL. Callers must
        fetch the design first (``get_design(design_id)``) and pass the
        ``modelId`` field from the response.


        Returns ``{"url": "https://makerworld.bblmw.com/...?at=<unix>
        &exp=<unix>&key=<hmac>&uid=<int>", ...}``. URL is short-lived (~5
        min); download immediately.

        Hits ``api.bambulab.com/v1/iot-service/api/user/profile/{profileId}
        ?model_id={modelId}`` with the stored Bambu Cloud bearer. This is the
        endpoint Pr0zak/YASTL#51 reverse-engineered — it lives on the
        ``api.bambulab.com`` backend (not Cloudflare-protected
        ``makerworld.com``), accepts the same long-lived bearer users already
        sign in with, and mints the signed CDN URL that the browser would
        otherwise fetch via session cookies. This is the only known non-
        cookie path to a download URL, after ruling out ``/design-service/``
        endpoints on ``makerworld.com`` (cookie-gated) and the now-dead
        ``/instance/{id}/f3mf?type=download`` shape.
        """
        if not self._auth_token:
            raise MakerWorldAuthError("Downloading files from MakerWorld requires a Bambu Cloud login")

        url = f"https://api.bambulab.com/v1/iot-service/api/user/profile/{int(profile_id)}"
        headers = dict(_CLIENT_HEADERS)
        headers["Authorization"] = f"Bearer {self._auth_token}"

        try:
            response = await self._client.get(
                url,
                headers=headers,
                params={"model_id": str(model_id)},
                timeout=30.0,
            )
        except httpx.TimeoutException as exc:
            raise MakerWorldUnavailableError(f"Bambu Lab API request timed out: {exc}") from exc
        except httpx.HTTPError as exc:
            raise MakerWorldUnavailableError(f"Bambu Lab API request failed: {exc}") from exc

        if response.status_code == 401:
            await self._note_auth_failure(response)
            raise MakerWorldAuthError(_SIGN_IN_EXPIRED_MESSAGE)
        if response.status_code == 403:
            upstream = _extract_upstream_error(response)
            raise MakerWorldForbiddenError(upstream or f"Bambu Lab refused access to profile {profile_id}")
        if response.status_code == 404:
            raise MakerWorldNotFoundError(f"MakerWorld profile not found: {profile_id}")
        if response.status_code != 200:
            raise MakerWorldUnavailableError(
                f"Bambu Lab API unexpected status {response.status_code} for profile {profile_id}"
            )

        try:
            data = response.json()
        except ValueError as exc:
            raise MakerWorldUnavailableError(f"Bambu Lab API returned non-JSON for profile {profile_id}") from exc
        if not isinstance(data, dict):
            raise MakerWorldUnavailableError(f"Bambu Lab API returned unexpected JSON shape for profile {profile_id}")
        return data

    async def download_3mf(self, signed_url: str) -> tuple[bytes, str]:
        """Fetch the 3MF bytes from a signed MakerWorld CDN URL.

        Validates that the URL's host is one of the declared download hosts
        (SSRF guard — driven by ``ModelProvider.download_hosts()`` via
        ``build_service``, the symmetric counterpart to the thumbnail
        allowlist) *or* matches ``_ALLOWED_DOWNLOAD_SUFFIXES``, Bambu's S3
        regional endpoints, which are this provider's own signed-URL family
        rather than part of the injectable seam; pattern matches
        ``_spoolman_helpers.assert_safe_spoolman_url``.
        Enforces a 200 MB cap so a single bad response can't exhaust disk.

        Returns ``(file_bytes, suggested_filename)``.
        """
        try:
            parsed = urlparse(signed_url)
        except ValueError as exc:
            raise MakerWorldUrlError(f"Invalid download URL: {exc}") from exc

        host = (parsed.hostname or "").lower()
        is_allowed = host in self._download_hosts or any(host.endswith(suffix) for suffix in _ALLOWED_DOWNLOAD_SUFFIXES)
        if not is_allowed:
            raise MakerWorldUrlError(f"Refusing to download from non-MakerWorld host: {host!r}")

        # Filename fallback from the signed path (before query string)
        path_tail = parsed.path.rsplit("/", 1)[-1] or "model.3mf"

        # Presigned S3 URLs (``s3.<region>.amazonaws.com``) compute the
        # signature over exact query-string bytes. Both httpx and curl_cffi
        # re-serialize the URL through ``urllib.parse.urlencode`` which
        # normalises encodings — breaks the signature and yields HTTP 400
        # ``SignatureDoesNotMatch`` (confirmed, and matches Pr0zak/YASTL#52's
        # analysis). ``urllib.request`` transmits the URL verbatim, so we
        # use it for S3 hosts and keep httpx for MakerWorld's own CDN.
        if host.endswith(".amazonaws.com"):
            return await _download_s3_urllib(signed_url, path_tail)

        # The signed URL's query-string IS the credential — don't send the
        # Bambu Cloud bearer to the CDN too. Strips Authorization/x-bbl-* and
        # keeps only User-Agent, matching what ``_download_s3_urllib`` does.
        cdn_headers = {"User-Agent": _CLIENT_HEADERS["User-Agent"]}
        try:
            async with self._client.stream(
                "GET", signed_url, headers=cdn_headers, timeout=60.0, follow_redirects=False
            ) as response:
                if response.status_code != 200:
                    raise MakerWorldUnavailableError(f"3MF download returned HTTP {response.status_code}")
                chunks: list[bytes] = []
                total = 0
                async for chunk in response.aiter_bytes():
                    total += len(chunk)
                    if total > _MAX_3MF_BYTES:
                        raise MakerWorldUnavailableError(f"3MF exceeds {_MAX_3MF_BYTES // (1024 * 1024)} MB cap")
                    chunks.append(chunk)
                return b"".join(chunks), path_tail
        except httpx.TimeoutException as exc:
            raise MakerWorldUnavailableError(f"3MF download timed out: {exc}") from exc
        except httpx.HTTPError as exc:
            raise MakerWorldUnavailableError(f"3MF download failed: {exc}") from exc

    async def fetch_thumbnail(self, url: str) -> tuple[bytes, str]:
        """Fetch a MakerWorld CDN image (thumbnail / cover / plate preview).

        Used by the ``/makerworld/thumbnail`` proxy so the frontend doesn't
        have to hotlink MakerWorld's CDN directly — avoids loosening the
        SPA's ``img-src`` CSP and keeps users' IP addresses out of
        MakerWorld's access logs.

        Validates that the URL's host is one of the declared thumbnail hosts
        (SSRF guard — symmetric to :meth:`download_3mf`; both allowlists are
        fed from the provider descriptor by ``build_service``). Caps
        payload at 10 MB. Returns ``(bytes, content_type)``; content type
        defaults to ``image/jpeg`` if the upstream didn't set one.
        """
        try:
            parsed = urlparse(url)
        except ValueError as exc:
            raise MakerWorldUrlError(f"Invalid thumbnail URL: {exc}") from exc

        host = (parsed.hostname or "").lower()
        if host not in self._thumbnail_hosts:
            raise MakerWorldUrlError(f"Refusing to fetch thumbnail from non-MakerWorld host: {host!r}")

        # ``follow_redirects=False``: the host allowlist above is only
        # meaningful on the initial URL. A 302 from the CDN to any other host
        # would otherwise be followed transparently (including RFC1918 /
        # metadata endpoints), so we insist upstream resolve the asset
        # directly. A redirect response surfaces as ``MakerWorldUnavailable``
        # below.
        try:
            response = await self._client.get(url, headers=self._headers(), timeout=20.0, follow_redirects=False)
        except httpx.TimeoutException as exc:
            raise MakerWorldUnavailableError(f"Thumbnail request timed out: {exc}") from exc
        except httpx.HTTPError as exc:
            raise MakerWorldUnavailableError(f"Thumbnail request failed: {exc}") from exc

        if response.status_code != 200:
            raise MakerWorldUnavailableError(f"Thumbnail fetch returned HTTP {response.status_code}")

        # MakerWorld's CDN serves real PNG/JPG files with
        # ``Content-Type: application/octet-stream`` (they use
        # ``Content-Disposition: attachment; filename="...png"`` instead). So
        # we can't just trust the header — derive the MIME from the URL's
        # file extension and only fall back to the header if the URL doesn't
        # carry one. Reject text/* / json outright regardless of extension
        # so an upstream error page can't slip through as "image/png".
        upstream_type = response.headers.get("content-type", "").split(";")[0].strip().lower()
        if upstream_type in _REFUSED_THUMBNAIL_MIMES:
            raise MakerWorldUnavailableError(f"Thumbnail upstream returned non-image content-type: {upstream_type!r}")

        path_lower = parsed.path.lower()
        ext_mime: str | None = None
        for ext, mime in _IMAGE_EXT_TO_MIME.items():
            if path_lower.endswith(ext):
                ext_mime = mime
                break

        if upstream_type.startswith("image/"):
            content_type = upstream_type
        elif ext_mime is not None:
            content_type = ext_mime
        else:
            # No image extension and no image/* content-type — can't confidently
            # serve this as an image, so refuse.
            raise MakerWorldUnavailableError(
                f"Thumbnail upstream returned {upstream_type!r} and URL has no image extension"
            )

        payload = response.content
        if len(payload) > _MAX_THUMBNAIL_BYTES:
            raise MakerWorldUnavailableError(f"Thumbnail exceeds {_MAX_THUMBNAIL_BYTES // (1024 * 1024)} MB cap")
        return payload, content_type