provider_media.py 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148
  1. """``$HERMES_HOME/cache/<kind>/`` materialisation helpers for the image/video
  2. generation provider ABCs.
  3. Several backends return *ephemeral* delivery URLs that expire before a downstream
  4. consumer (Telegram ``send_photo``, browser fetch) can resolve them, so providers
  5. materialise the bytes locally at tool-completion time. Filenames are
  6. ``<prefix>_<YYYYMMDD_HHMMSS>_<uuid8>.<ext>``.
  7. """
  8. from __future__ import annotations
  9. import base64
  10. import datetime
  11. import uuid
  12. from pathlib import Path
  13. from typing import Dict, Optional, Tuple
  14. from urllib.parse import urljoin
  15. # Generated deliverables live in ``cache/generated/<media>/``, OUTSIDE the transient
  16. # inbound caches the gateway housekeeping sweeps (#126445): for base64-returning
  17. # providers the cached file is the ONLY copy of the output.
  18. GENERATED_SUBDIR = "generated"
  19. # Age (hours) past which the gateway sweeps transient media caches; remote sync of the
  20. # unswept ``cache/generated`` tree uses the same window so it stays bounded.
  21. MEDIA_CACHE_MAX_AGE_HOURS = 24
  22. _REDIRECT_STATUS_CODES = {301, 302, 303, 307, 308}
  23. _MAX_SAVE_URL_REDIRECTS = 5
  24. def cache_dir(kind: str) -> Path:
  25. """Return ``$HERMES_HOME/cache/<kind>/``, creating parents as needed."""
  26. from hermes_constants import get_hermes_home
  27. path = get_hermes_home() / "cache" / kind
  28. path.mkdir(parents=True, exist_ok=True)
  29. return path
  30. def cache_path(kind: str, prefix: str, extension: str) -> Path:
  31. ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
  32. short = uuid.uuid4().hex[:8]
  33. return cache_dir(kind) / f"{prefix}_{ts}_{short}.{extension}"
  34. def save_bytes(kind: str, raw: bytes, *, prefix: str, extension: str) -> Path:
  35. """Write raw bytes to the cache and return the absolute path."""
  36. path = cache_path(kind, prefix, extension)
  37. path.write_bytes(raw)
  38. return path
  39. def save_b64(kind: str, b64_data: str, *, prefix: str, extension: str) -> Path:
  40. """Decode base64 data into the cache and return the absolute path."""
  41. return save_bytes(kind, base64.b64decode(b64_data), prefix=prefix, extension=extension)
  42. def save_url(
  43. kind: str, url: str, *, prefix: str, timeout: float, max_bytes: int, chunk_size: int,
  44. content_types: dict[str, str], url_extensions: tuple[str, ...], default_extension: str,
  45. label: str, empty_error: str, headers: Optional[dict[str, str]] = None,
  46. require_known_content_type: bool = False, trusted_origin: bool = False,
  47. ) -> Path:
  48. """Stream-download *url* into the cache with a size cap.
  49. The extension comes from the response ``Content-Type`` (an explicit table —
  50. never inherit a type pointing at HTML/JSON from a degenerate response), then
  51. the URL suffix (some CDNs return ``application/octet-stream``), then
  52. *default_extension*. Raises on any network / HTTP / oversize / empty error so
  53. callers can fall back to the bare URL; a partial file is never left behind.
  54. The URL is provider-supplied, so every hop is validated with
  55. ``tools.url_safety`` before a socket opens (and again at TCP connect by the
  56. guarded transport, closing DNS-rebinding TOCTOU). Caller-supplied *headers*
  57. (e.g. provider auth) go to the first hop only — a redirect target never
  58. receives them.
  59. *trusted_origin* is for callers that built *url* from the operator's own
  60. provider ``base_url`` (not from a provider response): the first hop skips the
  61. private-address class check so a LAN/loopback relay works without
  62. ``security.allow_private_urls``, but the cloud-metadata floor still applies and
  63. every redirect target is re-validated in full.
  64. """
  65. import httpx
  66. from tools.url_safety import create_ssrf_safe_client, is_always_blocked_url, is_safe_url
  67. current_url, hop_headers, trusted_hop = url, headers, trusted_origin
  68. for _ in range(_MAX_SAVE_URL_REDIRECTS + 1):
  69. if trusted_hop:
  70. if is_always_blocked_url(current_url):
  71. raise ValueError(f"{label} URL targets an always-blocked address: {current_url}")
  72. client = httpx.Client(timeout=timeout, follow_redirects=False)
  73. else:
  74. if not is_safe_url(current_url):
  75. raise ValueError(f"{label} URL failed the SSRF safety check: {current_url}")
  76. client = create_ssrf_safe_client(timeout=timeout, follow_redirects=False)
  77. with client:
  78. with client.stream("GET", current_url, headers=hop_headers) as response:
  79. if response.status_code in _REDIRECT_STATUS_CODES:
  80. location = response.headers.get("location")
  81. if not location:
  82. raise ValueError(f"{label} download redirected without a Location: {current_url}")
  83. current_url, hop_headers, trusted_hop = urljoin(current_url, location), None, False
  84. continue
  85. if not response.is_success:
  86. response.read()
  87. response.raise_for_status()
  88. content_type = (response.headers.get("Content-Type") or "").split(";", 1)[0].strip().lower()
  89. extension = content_types.get(content_type)
  90. if require_known_content_type and extension is None:
  91. raise ValueError(
  92. f"{label} download returned unexpected Content-Type {content_type or '(missing)'}"
  93. )
  94. if extension is None:
  95. url_path = current_url.split("?", 1)[0].lower()
  96. extension = next(
  97. ("jpg" if ext == "jpeg" else ext for ext in url_extensions if url_path.endswith(f".{ext}")),
  98. default_extension,
  99. )
  100. path = cache_path(kind, prefix, extension)
  101. bytes_written = 0
  102. with path.open("wb") as fh:
  103. for chunk in response.iter_bytes(chunk_size=chunk_size):
  104. if not chunk:
  105. continue
  106. bytes_written += len(chunk)
  107. if bytes_written > max_bytes:
  108. fh.close()
  109. _unlink_quiet(path)
  110. raise ValueError(
  111. f"{label} at {url} exceeds {max_bytes // (1024 * 1024)}MB cap; refusing to cache."
  112. )
  113. fh.write(chunk)
  114. if bytes_written == 0:
  115. _unlink_quiet(path)
  116. raise ValueError(empty_error.format(url=url))
  117. return path
  118. raise ValueError(f"{label} download exceeded {_MAX_SAVE_URL_REDIRECTS} redirects: {url}")
  119. def _unlink_quiet(path: Path) -> None:
  120. try:
  121. path.unlink()
  122. except OSError:
  123. pass