| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130 |
- """Fetch the public petdex manifest.
- ``https://petdex.dev/api/manifest`` 307-redirects to a JSON document on R2:
- ``{"generatedAt", "total", "pets": [{"slug", "displayName", "kind",
- "submittedBy", "spritesheetUrl", "petJsonUrl", "zipUrl"}, ...]}``.
- Read-only and unauthenticated; no credentials involved.
- """
- from __future__ import annotations
- import logging
- import threading
- import time
- from dataclasses import dataclass
- logger = logging.getLogger(__name__)
- MANIFEST_URL = "https://petdex.dev/api/manifest"
- _DEFAULT_TIMEOUT = 10.0
- # In-process cache for the (large, slow, identical-per-call) manifest: a static
- # CDN object a single session may ask for many times (every gallery open, plus a
- # re-fetch per install/select). A short TTL collapses those into one network hit.
- _MANIFEST_TTL = 300.0
- _cache: tuple[float, list[ManifestEntry]] | None = None
- _prefetch_lock = threading.Lock()
- _prefetching = False
- def clear_cache() -> None:
- """Drop the cached manifest (forces the next fetch to hit the network)."""
- global _cache
- _cache = None
- def _cache_is_warm() -> bool:
- return _cache is not None and time.monotonic() - _cache[0] < _MANIFEST_TTL
- def prefetch(*, timeout: float = _DEFAULT_TIMEOUT) -> None:
- """Warm the manifest cache in a daemon thread — idempotent, never blocks.
- The desktop picker calls this when loading the instant local-only gallery so
- the full catalog is usually cached by the time it's requested.
- """
- global _prefetching
- if _cache_is_warm():
- return
- with _prefetch_lock:
- if _prefetching:
- return
- _prefetching = True
- def _run() -> None:
- global _prefetching
- try:
- fetch_manifest(timeout=timeout)
- except Exception as exc:
- logger.debug("petdex manifest prefetch failed: %s", exc)
- finally:
- _prefetching = False
- threading.Thread(target=_run, name="petdex-prefetch", daemon=True).start()
- @dataclass(frozen=True)
- class ManifestEntry:
- """A single pet's row in the manifest."""
- slug: str
- display_name: str
- kind: str
- submitted_by: str
- spritesheet_url: str
- pet_json_url: str
- zip_url: str
- @classmethod
- def from_dict(cls, data: dict) -> ManifestEntry:
- return cls(
- slug=str(data.get("slug", "")).strip(),
- display_name=str(data.get("displayName", "") or data.get("slug", "")),
- kind=str(data.get("kind", "") or "pet"),
- submitted_by=str(data.get("submittedBy", "") or ""),
- spritesheet_url=str(data.get("spritesheetUrl", "") or ""),
- pet_json_url=str(data.get("petJsonUrl", "") or ""),
- zip_url=str(data.get("zipUrl", "") or ""),
- )
- class ManifestError(RuntimeError):
- """Raised when the manifest can't be fetched or parsed."""
- def fetch_manifest(*, timeout: float = _DEFAULT_TIMEOUT, force: bool = False) -> list[ManifestEntry]:
- """Every approved pet from the public manifest; cached for ``_MANIFEST_TTL`` s unless *force*. Raises :class:`ManifestError`."""
- global _cache
- if not force and _cache_is_warm():
- return _cache[1]
- try:
- import httpx
- except ImportError as exc: # pragma: no cover - httpx is a core dep
- raise ManifestError("httpx is required to fetch the petdex manifest") from exc
- try:
- from tools.url_safety import create_ssrf_safe_client, is_safe_url
- if not is_safe_url(MANIFEST_URL):
- raise ManifestError(f"Pet manifest URL failed the SSRF safety check: {MANIFEST_URL}")
- with create_ssrf_safe_client(timeout=timeout, follow_redirects=True) as client:
- resp = client.get(MANIFEST_URL, headers={"User-Agent": "hermes-agent-petdex"})
- resp.raise_for_status()
- payload = resp.json()
- except Exception as exc:
- raise ManifestError(f"could not fetch petdex manifest: {exc}") from exc
- pets = payload.get("pets") if isinstance(payload, dict) else None
- if not isinstance(pets, list):
- raise ManifestError("petdex manifest had no 'pets' array")
- parsed = (ManifestEntry.from_dict(raw) for raw in pets if isinstance(raw, dict))
- entries = [entry for entry in parsed if entry.slug and entry.spritesheet_url]
- _cache = (time.monotonic(), entries)
- return entries
- def find_entry(slug: str, *, timeout: float = _DEFAULT_TIMEOUT) -> ManifestEntry | None:
- """Return the manifest entry for *slug*, or ``None`` if not listed."""
- slug = slug.strip().lower()
- return next((entry for entry in fetch_manifest(timeout=timeout) if entry.slug.lower() == slug), None)
|