client.py 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219
  1. from __future__ import annotations
  2. from dataclasses import dataclass
  3. import re
  4. from typing import Any, Callable, Mapping, Protocol
  5. from urllib.parse import quote
  6. import requests
  7. from pydantic import ValidationError
  8. from hermes_cli.nous_account import resolve_nous_portal_base_url
  9. from tools.connectors.gateway.errors import (
  10. GatewayAuthError,
  11. GatewayUnavailable,
  12. ToolGatewayError,
  13. parse_gateway_error,
  14. )
  15. from tools.connectors.gateway.wire import ConnectorAccount, ConnectorAccountsResponse, RemovedConnectorAccount
  16. from tools.connectors.portal.errors import InvalidConnectorSlug, PortalConnectorUnavailable, PortalToolsUnavailable
  17. from tools.connectors.portal.wire import (
  18. ConnectorCatalogResponse,
  19. ConnectorPolicyResponse,
  20. ConnectorPolicyWriteResponse,
  21. ConnectorToolsListing,
  22. )
  23. from tools.managed_gateway_auth import read_nous_access_token
  24. from tools.managed_gateway_identity import connector_headers, log_connector_outcome, response_request_id
  25. DEFAULT_TIMEOUT_SECONDS = 30.0
  26. _SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
  27. class Transport(Protocol):
  28. def request(
  29. self,
  30. method: str,
  31. url: str,
  32. *,
  33. headers: dict[str, str] | None = None,
  34. json: dict[str, Any] | None = None,
  35. timeout: float | None = None,
  36. ) -> Any: ...
  37. @dataclass(frozen=True)
  38. class NotModified:
  39. pass
  40. def validate_slug(slug: str) -> None:
  41. if not _SLUG_RE.fullmatch(slug):
  42. raise InvalidConnectorSlug("connector must be a slug")
  43. def _default_transport() -> Transport:
  44. return requests
  45. def _default_endpoint_resolver() -> str:
  46. return resolve_nous_portal_base_url()
  47. def _default_header_provider(_url: str) -> dict[str, str]:
  48. token = read_nous_access_token()
  49. return {"Authorization": f"Bearer {token}"} if isinstance(token, str) and token.strip() else {}
  50. class PortalConnectorClient:
  51. def __init__(
  52. self,
  53. *,
  54. transport: Transport | None = None,
  55. endpoint_resolver: Callable[[], str] | None = None,
  56. header_provider: Callable[[str], dict[str, str]] | None = None,
  57. ) -> None:
  58. self._transport = transport or _default_transport()
  59. self._endpoint_resolver = endpoint_resolver or _default_endpoint_resolver
  60. self._header_provider = header_provider or _default_header_provider
  61. def origin(self) -> str:
  62. return self._endpoint_resolver().rstrip("/")
  63. def require_authentication(self) -> None:
  64. self._authorized_headers(self.origin())
  65. def authorization_token(self) -> str | None:
  66. authorization = self._authorized_headers(self.origin()).get("Authorization")
  67. if not isinstance(authorization, str):
  68. return None
  69. scheme, _, token = authorization.partition(" ")
  70. return token.strip() if scheme.lower() == "bearer" and token.strip() else None
  71. def _authorized_headers(self, url: str, extra: dict[str, str] | None = None) -> dict[str, str]:
  72. headers = {"Accept": "application/json", **(extra or {}), **connector_headers(), **self._header_provider(url)}
  73. if not isinstance(headers.get("Authorization"), str) or not headers["Authorization"].strip():
  74. raise GatewayAuthError("portal authorization required", code="NO_TOKEN", status=401)
  75. return headers
  76. def tools(self, slug: str, *, if_none_match: str | None = None) -> ConnectorToolsListing | NotModified:
  77. validate_slug(slug)
  78. headers = {"If-None-Match": if_none_match} if if_none_match else None
  79. try:
  80. response, status, route = self._request("GET", f"/api/v1/connectors/{slug}/tools", headers=headers)
  81. except ToolGatewayError as exc:
  82. missing_route = isinstance(exc, GatewayUnavailable) and exc.code != "connector_not_found"
  83. if type(exc) is not ToolGatewayError and not missing_route:
  84. raise
  85. raise PortalToolsUnavailable(
  86. "portal tools unavailable",
  87. code=exc.code,
  88. status=exc.status,
  89. request_id=exc.request_id,
  90. retryable=exc.retryable,
  91. ) from exc
  92. if status == 304:
  93. return NotModified()
  94. listing = self._parse(ConnectorToolsListing, response, status, route, PortalToolsUnavailable, "portal tools unavailable")
  95. etag = getattr(response, "headers", {}).get("etag")
  96. return listing.model_copy(update={"etag": etag}) if isinstance(etag, str) and etag else listing
  97. def catalog(self) -> ConnectorCatalogResponse:
  98. response, status, route = self._request("GET", "/api/v1/connectors/catalog")
  99. return self._parse(ConnectorCatalogResponse, response, status, route, PortalConnectorUnavailable, "portal catalog unavailable")
  100. def public_catalog(self) -> ConnectorCatalogResponse:
  101. """The catalog a new guest would get, for a caller with no token yet. Sent without a bearer so
  102. every caller gets the one cached answer."""
  103. response, status, route = self._request("GET", "/api/v1/connectors/catalog/public", public=True)
  104. return self._parse(ConnectorCatalogResponse, response, status, route, PortalConnectorUnavailable, "portal catalog unavailable")
  105. def list_accounts(self) -> list[dict[str, Any]]:
  106. response, status, route = self._request("GET", "/api/v1/connectors/accounts")
  107. inventory = self._parse(ConnectorAccountsResponse, response, status, route, PortalConnectorUnavailable, "portal accounts unavailable")
  108. return [account.model_dump(by_alias=True) for account in inventory.accounts]
  109. def rename_account(self, connection_id: str, alias: str) -> dict[str, Any]:
  110. path = f"/api/v1/connectors/accounts/{quote(connection_id, safe='')}"
  111. response, status, route = self._request("PATCH", path, {"alias": alias})
  112. account = self._parse(ConnectorAccount, response, status, route, PortalConnectorUnavailable, "portal accounts unavailable")
  113. return account.model_dump(by_alias=True)
  114. def delete_account(self, connection_id: str) -> dict[str, Any]:
  115. path = f"/api/v1/connectors/accounts/{quote(connection_id, safe='')}"
  116. response, status, route = self._request("DELETE", path)
  117. removed = self._parse(RemovedConnectorAccount, response, status, route, PortalConnectorUnavailable, "portal accounts unavailable")
  118. return removed.model_dump(by_alias=True)
  119. def policy(self) -> ConnectorPolicyResponse:
  120. response, status, route = self._request("GET", "/api/v1/connectors/policy")
  121. return self._parse(ConnectorPolicyResponse, response, status, route, PortalConnectorUnavailable, "portal policy unavailable")
  122. def set_policy(self, body: dict[str, Any]) -> ConnectorPolicyWriteResponse:
  123. response, status, route = self._request("PUT", "/api/v1/connectors/policy", body)
  124. return self._parse(ConnectorPolicyWriteResponse, response, status, route, PortalConnectorUnavailable, "portal policy unavailable")
  125. def _request(
  126. self,
  127. method: str,
  128. path: str,
  129. body: dict[str, Any] | None = None,
  130. *,
  131. headers: dict[str, str] | None = None,
  132. public: bool = False,
  133. ) -> tuple[Any, int, str]:
  134. """The answer, its status and route key. A failed status is logged and raised here; a 2xx is
  135. logged by ``_parse`` once its body is checked. ``public`` routes get no Authorization."""
  136. url = f"{self.origin()}{path}"
  137. if public:
  138. headers = {"Accept": "application/json", **(headers or {}), **connector_headers()}
  139. else:
  140. headers = self._authorized_headers(url, headers)
  141. try:
  142. response = self._transport.request(method, url, headers=headers, json=body, timeout=DEFAULT_TIMEOUT_SECONDS)
  143. except Exception as exc:
  144. log_connector_outcome(_route_key(path), None, code="TRANSPORT_ERROR")
  145. raise PortalConnectorUnavailable("portal connector metadata unavailable", code="TRANSPORT_ERROR", retryable=True) from exc
  146. status = int(getattr(response, "status_code", 0))
  147. request_id = response_request_id(response)
  148. if not 200 <= status < 300 and status != 304:
  149. error = parse_gateway_error(status, _safe_json(response), getattr(response, "headers", None))
  150. error.request_id = error.request_id or request_id
  151. log_connector_outcome(_route_key(path), status, code=error.code, request_id=error.request_id)
  152. raise error
  153. if status == 304:
  154. log_connector_outcome(_route_key(path), status, request_id=request_id)
  155. return response, status, _route_key(path)
  156. @staticmethod
  157. def _parse(model, response: Any, status: int, route: str, error_type, message: str):
  158. request_id = response_request_id(response)
  159. try:
  160. payload = response.json()
  161. if not isinstance(payload, Mapping):
  162. raise ValueError("response must be an object")
  163. parsed = model.model_validate(payload)
  164. except (AttributeError, TypeError, ValueError, ValidationError) as exc:
  165. log_connector_outcome(route, status, code="INVALID_RESPONSE", request_id=request_id)
  166. raise error_type(message, code="INVALID_RESPONSE", status=status, request_id=request_id) from exc
  167. log_connector_outcome(route, status, request_id=request_id)
  168. return parsed
  169. def _route_key(path: str) -> str:
  170. """``/api/v1/connectors/gmail/tools`` -> ``portal.connectors.tools``: no slugs or ids."""
  171. parts = path.strip("/").split("/")[2:]
  172. named = [part for part in parts if part in _PORTAL_ROUTE_WORDS]
  173. return ".".join(["portal", *named]) or "portal"
  174. _PORTAL_ROUTE_WORDS = frozenset({"connectors", "tools", "catalog", "public", "accounts", "policy"})
  175. def _safe_json(response: Any) -> Any:
  176. try:
  177. return response.json()
  178. except Exception:
  179. return None