analytics/app/clients/ga_client.py

"""Google Analytics client.

Thin proxy over the GA4 Data API and Admin API. Request/response bodies are
forwarded as-is so callers keep the full flexibility of Google's API; this
module only handles authentication (Bearer token), the base URL, and error
mapping.

Authentication (per chosen model, token wins over service account):
  * If ``X-GA-Access-Token`` was supplied, it is used directly.
  * Otherwise a short-lived access token is minted from the service-account
    JSON via google-auth and cached in-memory (keyed by key id + scope) until
    shortly before it expires. The key material is never written to disk or log.
"""
from __future__ import annotations

import hashlib
import threading
import time
from typing import Any

import httpx
from fastapi.concurrency import run_in_threadpool

from .. import config
from ..credentials import GaCredentials
from ..errors import MissingCredentialsError, UpstreamError
from ..logging_config import get_logger

logger = get_logger(__name__)

# In-memory access-token cache: { cache_key: (token, expiry_epoch_seconds) }.
# Memory only - mirrors the stateless design (no secret ever persisted).
_token_cache: dict[str, tuple[str, float]] = {}
_token_lock = threading.Lock()

# Refresh a minted token this many seconds before its real expiry.
_EXPIRY_SKEW = 60.0


def _mint_token_sync(info: dict, scope: str) -> tuple[str, float]:
    """Mint an OAuth2 access token from a service-account key (blocking)."""
    # Imported lazily so the module imports even if google-auth is missing,
    # and so the dependency is only needed when service-account auth is used.
    from google.auth.transport.requests import Request
    from google.oauth2 import service_account

    try:
        creds = service_account.Credentials.from_service_account_info(
            info, scopes=[scope]
        )
    except (ValueError, KeyError) as exc:
        raise MissingCredentialsError(
            f"X-GA-Credentials is not a usable service-account key: {exc}"
        ) from exc

    try:
        creds.refresh(Request())
    except Exception as exc:  # google.auth.exceptions.RefreshError and friends
        # Surface as upstream auth failure - do NOT log the key material.
        raise UpstreamError(
            f"Failed to obtain Google access token from service account: {exc}",
            status=401,
        ) from exc

    expiry = creds.expiry.timestamp() if creds.expiry else (time.time() + 3600)
    return creds.token, expiry


def _cache_key(info: dict, scope: str) -> str:
    # Identify a key by its private_key_id + client_email + scope. Hashed so the
    # raw identifiers never sit in a dict key we might later log.
    raw = f"{info.get('private_key_id', '')}|{info.get('client_email', '')}|{scope}"
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()


async def _bearer_token(creds: GaCredentials) -> str:
    if creds.access_token:
        return creds.access_token

    if creds.service_account_info is None:
        # get_ga_credentials guarantees one of the two, but be defensive.
        raise MissingCredentialsError(
            "No GA access token and no service-account credentials available."
        )

    scope = config.GA_SCOPE
    key = _cache_key(creds.service_account_info, scope)
    now = time.time()

    with _token_lock:
        cached = _token_cache.get(key)
        if cached and cached[1] - _EXPIRY_SKEW > now:
            return cached[0]

    # Mint outside the lock (network call); google-auth is blocking, so offload
    # it to a thread to avoid stalling the event loop.
    token, expiry = await run_in_threadpool(
        _mint_token_sync, creds.service_account_info, scope
    )
    with _token_lock:
        _token_cache[key] = (token, expiry)
    return token


class GoogleAnalyticsClient:
    """Authenticated HTTP client for the GA4 Data and Admin APIs."""

    def __init__(self, creds: GaCredentials) -> None:
        self._creds = creds

    async def _request(
        self,
        method: str,
        base_url: str,
        path: str,
        *,
        params: dict | None = None,
        json_body: Any | None = None,
    ) -> Any:
        token = await _bearer_token(self._creds)
        headers = {"Authorization": f"Bearer {token}"}
        if self._creds.quota_project:
            headers["x-goog-user-project"] = self._creds.quota_project

        url = f"{base_url}{path}"
        try:
            async with httpx.AsyncClient(
                timeout=config.HTTP_TIMEOUT_SECONDS
            ) as client:
                resp = await client.request(
                    method, url, params=params, json=json_body, headers=headers
                )
        except httpx.TimeoutException as exc:
            raise UpstreamError(
                "Google Analytics request timed out.", status=504
            ) from exc
        except httpx.HTTPError as exc:
            raise UpstreamError(
                f"Google Analytics is unreachable: {exc}", status=502
            ) from exc

        return _parse_google_response(resp)

    # --- Data API -------------------------------------------------------------
    async def data_post(self, path: str, body: Any) -> Any:
        return await self._request(
            "POST", config.GA_DATA_BASE_URL, path, json_body=body
        )

    async def data_get(self, path: str, params: dict | None = None) -> Any:
        return await self._request(
            "GET", config.GA_DATA_BASE_URL, path, params=params
        )

    # --- Admin API ------------------------------------------------------------
    async def admin_get(self, path: str, params: dict | None = None) -> Any:
        return await self._request(
            "GET", config.GA_ADMIN_BASE_URL, path, params=params
        )


def _parse_google_response(resp: httpx.Response) -> Any:
    try:
        payload = resp.json()
    except ValueError:
        payload = {"raw": resp.text}

    if resp.is_success:
        return payload

    # Google returns {"error": {"code", "message", "status", ...}}.
    message = "Google Analytics API error"
    if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
        message = payload["error"].get("message", message)
    raise UpstreamError(
        message,
        status=502 if resp.status_code >= 500 else resp.status_code,
        upstream_status=resp.status_code,
        body=payload,
    )