microsoft_graph_client.py 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. """Reusable Microsoft Graph REST client helpers."""
  2. from __future__ import annotations
  3. import asyncio
  4. import os
  5. from pathlib import Path
  6. from typing import Any, Awaitable, Callable
  7. import httpx
  8. from agent.retry_utils import parse_retry_after_seconds
  9. from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider, format_graph_error
  10. DEFAULT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0"
  11. Headers = dict[str, str] | None
  12. Params = dict[str, Any] | None
  13. class MicrosoftGraphClientError(RuntimeError):
  14. """Base class for Graph client failures."""
  15. class MicrosoftGraphAPIError(MicrosoftGraphClientError):
  16. """Raised when a Graph API request fails."""
  17. def __init__(self, status_code: int, method: str, url: str, message: str, *,
  18. retry_after_seconds: float | None = None, payload: Any = None) -> None:
  19. self.status_code, self.method, self.url = status_code, method, url
  20. self.retry_after_seconds, self.payload = retry_after_seconds, payload
  21. super().__init__(f"Microsoft Graph API error {status_code} for {method} {url}: {message}")
  22. class MicrosoftGraphClient:
  23. """Minimal async Graph client. Retry policy (JSON requests and streaming downloads
  24. alike): transport errors back off exponentially; 401 clears the token cache and
  25. refetches; 429/5xx honor ``Retry-After``. Each attempt uses a fresh ``AsyncClient``."""
  26. def __init__(self, token_provider: MicrosoftGraphTokenProvider, *,
  27. base_url: str = DEFAULT_GRAPH_BASE_URL, timeout: float = 60.0, max_retries: int = 3,
  28. transport: httpx.AsyncBaseTransport | None = None,
  29. sleep: Callable[[float], Awaitable[None]] | None = None,
  30. user_agent: str = "Hermes-Agent/graph-client") -> None:
  31. self.token_provider, self.base_url, self.timeout = token_provider, base_url.rstrip("/"), timeout
  32. self.max_retries, self.user_agent = max(0, int(max_retries)), user_agent
  33. self._transport, self._sleep = transport, sleep or asyncio.sleep
  34. async def get_json(self, path: str, *, params: Params = None, headers: Headers = None) -> Any:
  35. return self._decode_json(await self._request("GET", path, params=params, headers=headers))
  36. async def post_json(self, path: str, *, json_body: Any | None = None, headers: Headers = None) -> Any:
  37. return self._decode_json(await self._request("POST", path, json_body=json_body, headers=headers))
  38. async def patch_json(self, path: str, *, json_body: Any | None = None, headers: Headers = None) -> Any:
  39. """Decoded body, or ``{}`` for a 204 / bodiless response."""
  40. response = await self._request("PATCH", path, json_body=json_body, headers=headers)
  41. return self._decode_json(response) if response.status_code != 204 and response.content else {}
  42. async def delete(self, path: str, *, headers: Headers = None) -> dict[str, Any]:
  43. """Decoded body, or ``{"deleted": True, "status_code"}`` for a 204 / bodiless response."""
  44. response = await self._request("DELETE", path, headers=headers)
  45. if response.status_code != 204 and response.content:
  46. return self._decode_json(response)
  47. return {"deleted": True, "status_code": response.status_code}
  48. async def collect_paginated(self, path: str, *, params: Params = None, headers: Headers = None) -> list[Any]:
  49. """Follow ``@odata.nextLink`` and concatenate every page's ``value`` list."""
  50. items: list[Any] = []
  51. # Query params go on the first request only; @odata.nextLink already embeds them.
  52. next_url, next_params = self._resolve_url(path), dict(params or {})
  53. while next_url:
  54. payload = self._decode_json(await self._request("GET", next_url, params=next_params or None, headers=headers))
  55. if not isinstance(payload, dict):
  56. raise MicrosoftGraphClientError(
  57. f"Expected paginated Graph response dict, got {type(payload).__name__}.")
  58. if isinstance(payload.get("value"), list):
  59. items.extend(payload["value"])
  60. next_url, next_params = payload.get("@odata.nextLink"), {}
  61. return items
  62. async def download_to_file(self, path: str, destination: str | Path, *, headers: Headers = None,
  63. chunk_size: int = 65536) -> dict[str, Any]:
  64. """Stream a Graph resource to disk chunk-by-chunk (large recordings never
  65. fit in memory); written to ``.part`` and renamed into place only on success."""
  66. url, target = self._resolve_url(path), Path(destination)
  67. target.parent.mkdir(parents=True, exist_ok=True)
  68. tmp_target = target.with_suffix(target.suffix + ".part")
  69. async def perform(client: httpx.AsyncClient, request_headers: dict[str, str]):
  70. try:
  71. async with client.stream("GET", url, headers=request_headers) as response:
  72. if response.status_code >= 400:
  73. await response.aread() # small error body -> meaningful message
  74. return response, None
  75. with tmp_target.open("wb") as handle:
  76. async for chunk in response.aiter_bytes(chunk_size=chunk_size):
  77. if chunk:
  78. handle.write(chunk)
  79. return response, response.headers.get("content-type")
  80. except httpx.HTTPError:
  81. tmp_target.unlink(missing_ok=True)
  82. raise
  83. content_type = await self._with_retries("GET", url, "*/*", None, headers, perform, "download")
  84. os.replace(tmp_target, target)
  85. return {"path": str(target), "size_bytes": target.stat().st_size, "content_type": content_type}
  86. async def _request(self, method: str, path_or_url: str, *, params: Params = None,
  87. json_body: Any | None = None, headers: Headers = None) -> httpx.Response:
  88. url = self._resolve_url(path_or_url)
  89. async def perform(client: httpx.AsyncClient, request_headers: dict[str, str]):
  90. response = await client.request(method, url, params=params, json=json_body, headers=request_headers)
  91. return response, response
  92. return await self._with_retries(method, url, "application/json", json_body, headers, perform, "request")
  93. async def _with_retries(
  94. self, method: str, url: str, accept: str, json_body: Any | None, headers: Headers,
  95. perform: Callable[[httpx.AsyncClient, dict[str, str]], Awaitable[tuple[httpx.Response, Any]]],
  96. kind: str) -> Any:
  97. """Run ``perform`` (-> ``(response, result)``) under the retry policy. ``kind``
  98. only labels transport-failure messages. Raises ``MicrosoftGraphAPIError`` once
  99. retries are exhausted or the status is not retryable; only 401 forces a token refresh."""
  100. last_error: Exception | None = None
  101. for attempt in range(self.max_retries + 1):
  102. token = await self.token_provider.get_access_token(
  103. force_refresh=isinstance(last_error, MicrosoftGraphAPIError) and last_error.status_code == 401)
  104. request_headers = {"Authorization": f"Bearer {token}", "Accept": accept, "User-Agent": self.user_agent,
  105. **({"Content-Type": "application/json"} if json_body is not None else {}),
  106. **(headers or {})}
  107. exhausted = attempt >= self.max_retries
  108. try:
  109. async with httpx.AsyncClient(timeout=httpx.Timeout(self.timeout), transport=self._transport) as client:
  110. response, result = await perform(client, request_headers)
  111. except httpx.HTTPError as exc:
  112. last_error, response = exc, None
  113. if exhausted:
  114. raise MicrosoftGraphClientError(
  115. f"Microsoft Graph {kind} failed for {method} {url}: {exc}") from exc
  116. else:
  117. if response.status_code < 400:
  118. return result
  119. last_error, status = self._build_api_error(method, url, response), response.status_code
  120. if exhausted or not (status in (401, 429) or 500 <= status < 600):
  121. raise last_error
  122. if status == 401:
  123. self.token_provider.clear_cache()
  124. await self._sleep(self._retry_delay(response, attempt))
  125. raise MicrosoftGraphClientError(f"Microsoft Graph {kind} exhausted retries for {method} {url}.")
  126. def _resolve_url(self, path_or_url: str) -> str:
  127. if path_or_url.startswith(("http://", "https://")):
  128. return path_or_url
  129. return f"{self.base_url}{path_or_url if path_or_url.startswith('/') else '/' + path_or_url}"
  130. @staticmethod
  131. def _decode_json(response: httpx.Response) -> Any:
  132. try:
  133. return response.json()
  134. except ValueError as exc:
  135. raise MicrosoftGraphClientError(
  136. "Microsoft Graph response was not valid JSON for "
  137. f"{response.request.method} {response.request.url}") from exc
  138. @staticmethod
  139. def _retry_delay(response: httpx.Response | None, attempt: int) -> float:
  140. retry_after = parse_retry_after_seconds(response.headers) if response is not None else None
  141. return min(8.0, 0.5 * (2 ** attempt)) if retry_after is None else retry_after
  142. @staticmethod
  143. def _build_api_error(method: str, url: str, response: httpx.Response) -> MicrosoftGraphAPIError:
  144. try:
  145. payload: Any = response.json()
  146. except ValueError:
  147. payload = None
  148. detail = format_graph_error(payload.get("error")) if isinstance(payload, dict) else None
  149. return MicrosoftGraphAPIError(
  150. response.status_code, method, url, response.text.strip() or "unknown error" if detail is None else detail,
  151. retry_after_seconds=parse_retry_after_seconds(response.headers), payload=payload)