manifest.py 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130
  1. """Fetch the public petdex manifest.
  2. ``https://petdex.dev/api/manifest`` 307-redirects to a JSON document on R2:
  3. ``{"generatedAt", "total", "pets": [{"slug", "displayName", "kind",
  4. "submittedBy", "spritesheetUrl", "petJsonUrl", "zipUrl"}, ...]}``.
  5. Read-only and unauthenticated; no credentials involved.
  6. """
  7. from __future__ import annotations
  8. import logging
  9. import threading
  10. import time
  11. from dataclasses import dataclass
  12. logger = logging.getLogger(__name__)
  13. MANIFEST_URL = "https://petdex.dev/api/manifest"
  14. _DEFAULT_TIMEOUT = 10.0
  15. # In-process cache for the (large, slow, identical-per-call) manifest: a static
  16. # CDN object a single session may ask for many times (every gallery open, plus a
  17. # re-fetch per install/select). A short TTL collapses those into one network hit.
  18. _MANIFEST_TTL = 300.0
  19. _cache: tuple[float, list[ManifestEntry]] | None = None
  20. _prefetch_lock = threading.Lock()
  21. _prefetching = False
  22. def clear_cache() -> None:
  23. """Drop the cached manifest (forces the next fetch to hit the network)."""
  24. global _cache
  25. _cache = None
  26. def _cache_is_warm() -> bool:
  27. return _cache is not None and time.monotonic() - _cache[0] < _MANIFEST_TTL
  28. def prefetch(*, timeout: float = _DEFAULT_TIMEOUT) -> None:
  29. """Warm the manifest cache in a daemon thread — idempotent, never blocks.
  30. The desktop picker calls this when loading the instant local-only gallery so
  31. the full catalog is usually cached by the time it's requested.
  32. """
  33. global _prefetching
  34. if _cache_is_warm():
  35. return
  36. with _prefetch_lock:
  37. if _prefetching:
  38. return
  39. _prefetching = True
  40. def _run() -> None:
  41. global _prefetching
  42. try:
  43. fetch_manifest(timeout=timeout)
  44. except Exception as exc:
  45. logger.debug("petdex manifest prefetch failed: %s", exc)
  46. finally:
  47. _prefetching = False
  48. threading.Thread(target=_run, name="petdex-prefetch", daemon=True).start()
  49. @dataclass(frozen=True)
  50. class ManifestEntry:
  51. """A single pet's row in the manifest."""
  52. slug: str
  53. display_name: str
  54. kind: str
  55. submitted_by: str
  56. spritesheet_url: str
  57. pet_json_url: str
  58. zip_url: str
  59. @classmethod
  60. def from_dict(cls, data: dict) -> ManifestEntry:
  61. return cls(
  62. slug=str(data.get("slug", "")).strip(),
  63. display_name=str(data.get("displayName", "") or data.get("slug", "")),
  64. kind=str(data.get("kind", "") or "pet"),
  65. submitted_by=str(data.get("submittedBy", "") or ""),
  66. spritesheet_url=str(data.get("spritesheetUrl", "") or ""),
  67. pet_json_url=str(data.get("petJsonUrl", "") or ""),
  68. zip_url=str(data.get("zipUrl", "") or ""),
  69. )
  70. class ManifestError(RuntimeError):
  71. """Raised when the manifest can't be fetched or parsed."""
  72. def fetch_manifest(*, timeout: float = _DEFAULT_TIMEOUT, force: bool = False) -> list[ManifestEntry]:
  73. """Every approved pet from the public manifest; cached for ``_MANIFEST_TTL`` s unless *force*. Raises :class:`ManifestError`."""
  74. global _cache
  75. if not force and _cache_is_warm():
  76. return _cache[1]
  77. try:
  78. import httpx
  79. except ImportError as exc: # pragma: no cover - httpx is a core dep
  80. raise ManifestError("httpx is required to fetch the petdex manifest") from exc
  81. try:
  82. from tools.url_safety import create_ssrf_safe_client, is_safe_url
  83. if not is_safe_url(MANIFEST_URL):
  84. raise ManifestError(f"Pet manifest URL failed the SSRF safety check: {MANIFEST_URL}")
  85. with create_ssrf_safe_client(timeout=timeout, follow_redirects=True) as client:
  86. resp = client.get(MANIFEST_URL, headers={"User-Agent": "hermes-agent-petdex"})
  87. resp.raise_for_status()
  88. payload = resp.json()
  89. except Exception as exc:
  90. raise ManifestError(f"could not fetch petdex manifest: {exc}") from exc
  91. pets = payload.get("pets") if isinstance(payload, dict) else None
  92. if not isinstance(pets, list):
  93. raise ManifestError("petdex manifest had no 'pets' array")
  94. parsed = (ManifestEntry.from_dict(raw) for raw in pets if isinstance(raw, dict))
  95. entries = [entry for entry in parsed if entry.slug and entry.spritesheet_url]
  96. _cache = (time.monotonic(), entries)
  97. return entries
  98. def find_entry(slug: str, *, timeout: float = _DEFAULT_TIMEOUT) -> ManifestEntry | None:
  99. """Return the manifest entry for *slug*, or ``None`` if not listed."""
  100. slug = slug.strip().lower()
  101. return next((entry for entry in fetch_manifest(timeout=timeout) if entry.slug.lower() == slug), None)