media.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. """Relay media client — gateway↔connector media plane (Phase 2). EXPERIMENTAL.
  2. The relay wire carries media BY REFERENCE: inbound ``media_urls`` name connector
  3. re-hosts (``{connector}/relay/media/{id}``) and an outbound ``send_media`` op names
  4. a ``source_url`` the connector resolves back to bytes. ``download(url)`` GETs a
  5. re-hosted attachment to a local temp file (vision/file tools consume LOCAL paths,
  6. like every native adapter); ``upload(path)`` POSTs local bytes to ``/relay/media``
  7. and returns the reference for a subsequent ``send_media`` op. Both present the
  8. per-gateway signed bearer the WS upgrade uses; stdlib ``urllib`` in a thread executor.
  9. """
  10. from __future__ import annotations
  11. import asyncio
  12. import email.message
  13. import email.utils
  14. import http.client
  15. import json
  16. import logging
  17. import mimetypes
  18. import os
  19. import tempfile
  20. import urllib.error
  21. import urllib.request
  22. from pathlib import Path
  23. from typing import Optional
  24. from gateway.platforms.event import clean_attachment_filename
  25. from gateway.relay.auth import make_upgrade_token
  26. logger = logging.getLogger(__name__)
  27. # Mirrors the connector's MEDIA_MAX_BYTES (mediaStore.ts): fail fast here
  28. # instead of round-tripping to a connector 413.
  29. MEDIA_MAX_BYTES = 25 * 1024 * 1024
  30. _REQUEST_TIMEOUT_S = 30.0
  31. # Upload retry: the delays BEFORE each extra attempt (3 attempts in all). A transient
  32. # hop failure (an egress proxy's own 403, a reset, a connector store outage) usually
  33. # clears within seconds, and a dropped attachment is worse than a short wait. Worst
  34. # case per file is 3 x _REQUEST_TIMEOUT_S + 7s, well inside cron's per-attachment
  35. # media-send timeout (300s default).
  36. _UPLOAD_RETRY_DELAYS_S = (2.0, 5.0)
  37. # Statuses worth another attempt. The connector itself never answers 403 on
  38. # POST /relay/media (401 bad bearer, 413 too large, 400 client fault, 503 store
  39. # down), so a 403 is an intermediary refusing on its own. 401/400/413/415 are final.
  40. _UPLOAD_RETRY_STATUSES = frozenset({403, 408, 429, 500, 502, 503, 504})
  41. # Discord's CDN (and other public hosts) 403 urllib's default UA, which
  42. # silently killed every CDN pass-through download. Always send a descriptive UA.
  43. _MEDIA_USER_AGENT = "HermesAgent-Relay/1.0 (+https://github.com/NousResearch/hermes-agent)"
  44. def media_base_url(relay_dial_url: str) -> str:
  45. """Map the ``ws(s)://…/relay`` dial URL to the ``http(s)://…`` connector base."""
  46. raw = (relay_dial_url or "").strip().rstrip("/")
  47. if raw.startswith("ws://"):
  48. raw = "http://" + raw[len("ws://") :]
  49. elif raw.startswith("wss://"):
  50. raw = "https://" + raw[len("wss://") :]
  51. raw = raw.removesuffix("/relay")
  52. return raw
  53. class RelayMediaClient:
  54. """Authenticated client for the connector's ``/relay/media`` routes."""
  55. def __init__(self, base_url: str, gateway_id: Optional[str], secret: Optional[str]) -> None:
  56. self._base_url = base_url.rstrip("/")
  57. self._gateway_id = gateway_id or ""
  58. self._secret = secret or ""
  59. @property
  60. def enabled(self) -> bool:
  61. """True when the client can authenticate (per-gateway creds present)."""
  62. return bool(self._base_url and self._gateway_id and self._secret)
  63. def _bearer(self) -> str:
  64. return make_upgrade_token(self._gateway_id, self._secret)
  65. def is_relay_media_url(self, url: str) -> bool:
  66. """Is ``url`` a connector re-host reference (needs our bearer to GET)?"""
  67. return "/relay/media/" in (url or "")
  68. async def upload(
  69. self, file_path: str, *, mime: Optional[str] = None, filename: Optional[str] = None
  70. ) -> Optional[str]:
  71. """POST local file bytes to ``/relay/media``; return the reference URL or None on any failure."""
  72. return (await self.upload_with_error(file_path, mime=mime, filename=filename))[0]
  73. async def upload_with_error(
  74. self, file_path: str, *, mime: Optional[str] = None, filename: Optional[str] = None
  75. ) -> tuple[Optional[str], str]:
  76. """``upload`` that also says why it failed: ``(reference, "")`` or ``(None, reason)``.
  77. Transient failures (transport errors, ``_UPLOAD_RETRY_STATUSES``) are retried
  78. after ``_UPLOAD_RETRY_DELAYS_S``; a final relay answer is not.
  79. """
  80. if not self.enabled:
  81. return None, "relay media client has no credentials"
  82. path = Path(file_path)
  83. try:
  84. data = await asyncio.get_running_loop().run_in_executor(None, path.read_bytes)
  85. except OSError:
  86. logger.warning("relay media upload: cannot read %s", file_path)
  87. return None, "attachment file is unreadable"
  88. if not data or len(data) > MEDIA_MAX_BYTES:
  89. logger.warning(
  90. "relay media upload: %s size %d outside (0, %d]", file_path, len(data), MEDIA_MAX_BYTES
  91. )
  92. return None, f"attachment size {len(data)} outside (0, {MEDIA_MAX_BYTES}]"
  93. content_type = (
  94. mime or mimetypes.guess_type(filename or path.name)[0] or "application/octet-stream"
  95. )
  96. name = (filename or path.name)[:255]
  97. url = f"{self._base_url}/relay/media"
  98. def _post() -> tuple[Optional[str], str, bool]:
  99. """One attempt: ``(reference, failure reason, worth retrying)``."""
  100. bearer = self._bearer() # minted per attempt: never retry with a token that aged during backoff
  101. headers = {
  102. "User-Agent": _MEDIA_USER_AGENT,
  103. "Authorization": f"Bearer {bearer}",
  104. "Content-Type": content_type,
  105. "X-Media-Filename": name,
  106. }
  107. req = urllib.request.Request(url, data=data, headers=headers, method="POST")
  108. try:
  109. with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
  110. media_id = json.loads(resp.read().decode("utf-8")).get("id")
  111. if media_id:
  112. return f"{self._base_url}/relay/media/{media_id}", "", False
  113. return None, "connector answered without a media id", False
  114. except urllib.error.HTTPError as exc:
  115. from gateway.relay.http_diagnostics import describe_http_error, read_error_body
  116. # The exact bearer and secret are scrubbed even if a hop echoes them bare.
  117. described = describe_http_error(exc, read_error_body(exc), secrets=(bearer, self._secret or ""))
  118. return None, described, exc.code in _UPLOAD_RETRY_STATUSES
  119. except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
  120. return None, f"transport error: {getattr(exc, 'reason', None) or exc}", True
  121. except ValueError as exc:
  122. return None, f"unreadable connector response: {exc}", False
  123. loop = asyncio.get_running_loop()
  124. attempts = len(_UPLOAD_RETRY_DELAYS_S) + 1
  125. attempt, reason = 0, ""
  126. while attempt < attempts:
  127. attempt += 1
  128. ref, reason, retryable = await loop.run_in_executor(None, _post)
  129. if ref:
  130. if attempt > 1:
  131. logger.info("relay media upload of %s succeeded on attempt %d", name, attempt)
  132. return ref, ""
  133. if not retryable or attempt == attempts:
  134. break
  135. delay = _UPLOAD_RETRY_DELAYS_S[attempt - 1]
  136. logger.warning(
  137. "relay media upload of %s failed (attempt %d/%d): %s; retrying in %.0fs",
  138. name, attempt, attempts, reason, delay,
  139. )
  140. await asyncio.sleep(delay)
  141. logger.warning("relay media upload of %s failed (attempt %d/%d): %s", name, attempt, attempts, reason)
  142. return None, reason
  143. async def download(self, url: str, *, suggested_name: Optional[str] = None) -> Optional[str]:
  144. """GET an attachment to a local temp file; return its path or None on any failure."""
  145. result = await self.download_with_name(url, suggested_name=suggested_name)
  146. return result[0] if result else None
  147. async def download_with_name(
  148. self, url: str, *, suggested_name: Optional[str] = None
  149. ) -> Optional[tuple[str, str]]:
  150. """GET an attachment to a local temp file; return ``(path, original_name)`` or None.
  151. ``original_name`` is ``suggested_name`` when given, else the response's
  152. ``Content-Disposition`` filename, cleaned for display; ``""`` when neither names it.
  153. The file is always a random ``relay_media_*`` temp name (the name only picks the
  154. extension), so identical names never collide.
  155. The bearer is presented only for connector re-host URLs; public URLs
  156. (e.g. a Discord CDN pass-through) are fetched without it.
  157. """
  158. if not url:
  159. return None
  160. needs_auth = self.is_relay_media_url(url)
  161. if needs_auth and not self.enabled:
  162. return None
  163. headers = {"User-Agent": _MEDIA_USER_AGENT}
  164. if needs_auth:
  165. headers["Authorization"] = f"Bearer {self._bearer()}"
  166. def _get() -> Optional[tuple[str, str]]:
  167. req = urllib.request.Request(url, headers=headers)
  168. try:
  169. with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_S) as resp:
  170. if int(resp.headers.get("Content-Length") or 0) > MEDIA_MAX_BYTES:
  171. logger.warning("relay media download too large: %s", url)
  172. return None
  173. data = resp.read(MEDIA_MAX_BYTES + 1)
  174. if not data or len(data) > MEDIA_MAX_BYTES:
  175. return None
  176. # Extension matters: vision/file tools sniff by extension.
  177. # Prefer suggested/content-disposition name, then mime, then .bin.
  178. name = clean_attachment_filename(suggested_name) or _content_disposition_filename(
  179. resp.headers.get("Content-Disposition") or ""
  180. )
  181. ext = Path(name).suffix if name else ""
  182. if not ext.isascii() or not ext[1:].isalnum() or len(ext) > 16:
  183. ext = ""
  184. if not ext:
  185. mime = (resp.headers.get("Content-Type") or "").split(";")[0]
  186. ext = mimetypes.guess_extension(mime) or ".bin"
  187. fd, tmp_path = tempfile.mkstemp(prefix="relay_media_", suffix=ext)
  188. with os.fdopen(fd, "wb") as fh:
  189. fh.write(data)
  190. return tmp_path, name
  191. except (urllib.error.URLError, ValueError, OSError) as exc:
  192. logger.warning("relay media download failed for %s: %s", url, exc)
  193. return None
  194. return await asyncio.get_running_loop().run_in_executor(None, _get)
  195. def _content_disposition_filename(header: str) -> str:
  196. """The filename a ``Content-Disposition`` header names, cleaned for display; ``""`` if none.
  197. RFC 6266: an RFC 5987 ``filename*`` (``UTF-8''r%C3%A9sum%C3%A9.pdf``) wins over the plain
  198. ``filename``; quoted values and escapes are handled by the stdlib MIME parser."""
  199. if not header:
  200. return ""
  201. msg = email.message.Message()
  202. try:
  203. msg["Content-Disposition"] = header
  204. params = msg.get_params(header="content-disposition") or []
  205. except (ValueError, TypeError, IndexError):
  206. return ""
  207. plain, extended = "", ""
  208. for key, value in params[1:]:
  209. if key.lower() != "filename":
  210. continue
  211. if isinstance(value, tuple):
  212. extended = extended or email.utils.collapse_rfc2231_value(value)
  213. else:
  214. plain = plain or email.utils.unquote(value)
  215. return clean_attachment_filename(extended or plain)
  216. __all__ = ["MEDIA_MAX_BYTES", "RelayMediaClient", "media_base_url"]