redblack-python-sdk 0.1.0__py3-none-any.whl

redblack/transport.py

@@ -0,0 +1,606 @@
+"""Synchronous HTTPX transport with conservative auth and retry behavior."""
+
+from __future__ import annotations
+
+import email.utils
+import random
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from datetime import UTC, datetime
+from math import isfinite
+from typing import Any, Protocol, TypeAlias, runtime_checkable
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._version import __version__
+from .auth import TokenProvider
+from .config import RedBlackConfig
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    RequestTimeoutError,
+    TransportError,
+    api_error_from_response,
+    extract_request_id,
+    safe_response_headers,
+)
+from .response import ApiResponse, HttpMetadata
+
+QueryParams: TypeAlias = Any
+RequestHeaders: TypeAlias = Mapping[str, str] | None
+
+_SAFE_READ_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+_PROTECTED_HEADERS = frozenset(
+    {
+        "accept-version",
+        "authorization",
+        "client-id",
+        "cookie",
+        "host",
+        "proxy-authorization",
+        "x-api-key",
+    }
+)
+
+
+@runtime_checkable
+class HttpTransport(Protocol):
+    """Transport interface consumed by the hand-written client layer."""
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: QueryParams = None,
+        headers: RequestHeaders = None,
+        json: Any = None,
+        content: bytes | str | None = None,
+        data: Any = None,
+        expected_statuses: IterableStatus | None = None,
+        authenticated: bool = True,
+        allow_retry: bool | None = None,
+        operation_id: str | None = None,
+        api_version: str | None = None,
+        timeout_budget: float | None = None,
+    ) -> ApiResponse[bytes]:
+        """Send one same-origin API request."""
+        ...
+
+    def close(self) -> None:
+        """Release owned resources."""
+
+
+IterableStatus: TypeAlias = Sequence[int] | set[int] | frozenset[int]
+
+
+class HttpxTransport:
+    """HTTPX-backed, thread-shareable RedBlack request transport."""
+
+    def __init__(
+        self,
+        config: RedBlackConfig,
+        token_provider: TokenProvider | None,
+        *,
+        client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        random_value: Callable[[], float] = random.random,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if token_provider is not None and not callable(getattr(token_provider, "get_token", None)):
+            raise ConfigurationError("token_provider must define get_token()")
+        provider_client_id = (
+            getattr(token_provider, "client_id", None) if token_provider is not None else None
+        )
+        if provider_client_id is not None and provider_client_id != config.client_id:
+            raise ConfigurationError(
+                "token provider client_id does not match the authoritative client_id"
+            )
+
+        self._config = config
+        self._token_provider = token_provider
+        self._sleep = sleep
+        self._random_value = random_value
+        self._monotonic = monotonic
+        self._timeout = httpx.Timeout(
+            connect=config.timeout.connect,
+            read=config.timeout.read,
+            write=config.timeout.write,
+            pool=config.timeout.pool,
+        )
+        self._owns_client = client is None
+        if client is None:
+            client = httpx.Client(
+                timeout=self._timeout,
+                verify=config.verify,
+                proxy=config.proxy,
+                trust_env=config.trust_env,
+                follow_redirects=False,
+                headers={"User-Agent": f"redblack-python-sdk/{__version__}"},
+            )
+        self._client = client
+        self._state_lock = threading.Lock()
+        self._closed = False
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: QueryParams = None,
+        headers: RequestHeaders = None,
+        json: Any = None,
+        content: bytes | str | None = None,
+        data: Any = None,
+        expected_statuses: IterableStatus | None = None,
+        authenticated: bool = True,
+        allow_retry: bool | None = None,
+        operation_id: str | None = None,
+        api_version: str | None = None,
+        timeout_budget: float | None = None,
+    ) -> ApiResponse[bytes]:
+        """Send a RedBlack API request.
+
+        Retries and authentication replay are restricted to safe reads. Passing
+        ``allow_retry=True`` never turns a mutation into a replayable request;
+        it only enables the normal read policy.
+        """
+
+        normalized_method = _validate_method(method)
+        normalized_path = _validate_relative_path(path)
+        normalized_budget = _validate_timeout_budget(timeout_budget)
+        context_path = normalized_path
+        if operation_id is not None:
+            if (
+                not isinstance(operation_id, str)
+                or not operation_id.strip()
+                or any(ord(character) < 32 for character in operation_id)
+            ):
+                raise ConfigurationError("operation_id must be a safe non-empty string")
+            context_path = operation_id
+        supplied_headers = _validate_headers(headers)
+        if sum(value is not None for value in (json, content, data)) > 1:
+            raise ConfigurationError("pass only one of json, content, or data")
+        if not isinstance(authenticated, bool):
+            raise ConfigurationError("authenticated must be a bool")
+        if allow_retry is not None and not isinstance(allow_retry, bool):
+            raise ConfigurationError("allow_retry must be a bool or None")
+        if api_version is not None and (
+            not isinstance(api_version, str)
+            or not api_version.strip()
+            or "\r" in api_version
+            or "\n" in api_version
+        ):
+            raise ConfigurationError("api_version override must be a non-empty header value")
+
+        expected = frozenset(expected_statuses) if expected_statuses is not None else None
+        if expected is not None and (
+            not expected or any(not isinstance(item, int) for item in expected)
+        ):
+            raise ConfigurationError("expected_statuses must contain HTTP status integers")
+
+        with self._state_lock:
+            if self._closed:
+                raise TransportError(
+                    "transport is closed",
+                    method=normalized_method,
+                    path=context_path,
+                )
+
+        retry_reads = normalized_method in _SAFE_READ_METHODS and allow_retry is not False
+        retry_attempt = 1
+        sends = 0
+        auth_replayed = False
+        started = self._monotonic()
+        deadline = None if normalized_budget is None else started + normalized_budget
+        token: str | None = None
+        prepared_token: str | None = None
+
+        while True:
+            self._remaining_budget(
+                deadline,
+                method=normalized_method,
+                path=context_path,
+            )
+            if authenticated:
+                if prepared_token is not None:
+                    token = prepared_token
+                    prepared_token = None
+                else:
+                    try:
+                        token = self._get_token()
+                    except Exception:
+                        self._remaining_budget(
+                            deadline,
+                            method=normalized_method,
+                            path=context_path,
+                        )
+                        raise
+                    self._remaining_budget(
+                        deadline,
+                        method=normalized_method,
+                        path=context_path,
+                    )
+            request_headers = self._common_headers(
+                token=token,
+                authenticated=authenticated,
+                api_version=api_version,
+            )
+            request_headers.update(supplied_headers)
+            request_timeout = self._timeout_for_budget(
+                deadline,
+                method=normalized_method,
+                path=context_path,
+            )
+            sends += 1
+            try:
+                response = self._client.request(
+                    normalized_method,
+                    f"{self._config.base_url}{normalized_path}",
+                    params=params,
+                    headers=request_headers,
+                    json=json,
+                    content=content,
+                    data=data,
+                    timeout=request_timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TimeoutException as exc:
+                if self._budget_expired(deadline):
+                    raise self._timeout_error(
+                        method=normalized_method,
+                        path=context_path,
+                    ) from exc
+                if retry_reads and retry_attempt < self._config.retry.max_attempts:
+                    self._sleep_for_retry(
+                        self._backoff_delay(retry_attempt, None),
+                        deadline,
+                        method=normalized_method,
+                        path=context_path,
+                    )
+                    retry_attempt += 1
+                    continue
+                raise RequestTimeoutError(
+                    "RedBlack API request timed out",
+                    method=normalized_method,
+                    path=context_path,
+                ) from exc
+            except httpx.TransportError as exc:
+                if self._budget_expired(deadline):
+                    raise self._timeout_error(
+                        method=normalized_method,
+                        path=context_path,
+                    ) from exc
+                if retry_reads and retry_attempt < self._config.retry.max_attempts:
+                    self._sleep_for_retry(
+                        self._backoff_delay(retry_attempt, None),
+                        deadline,
+                        method=normalized_method,
+                        path=context_path,
+                    )
+                    retry_attempt += 1
+                    continue
+                raise TransportError(
+                    "RedBlack API request failed before receiving a response",
+                    method=normalized_method,
+                    path=context_path,
+                ) from exc
+
+            self._remaining_budget(
+                deadline,
+                method=normalized_method,
+                path=context_path,
+            )
+            if authenticated and response.status_code == 401:
+                if retry_reads and not auth_replayed:
+                    try:
+                        refreshed = self._refresh_token(token)
+                    except Exception:
+                        self._remaining_budget(
+                            deadline,
+                            method=normalized_method,
+                            path=context_path,
+                        )
+                        raise
+                    self._remaining_budget(
+                        deadline,
+                        method=normalized_method,
+                        path=context_path,
+                    )
+                    if refreshed is not None:
+                        auth_replayed = True
+                        prepared_token = refreshed
+                        continue
+                else:
+                    self._invalidate_token(token)
+                raise api_error_from_response(response, method=normalized_method, path=context_path)
+
+            if authenticated and response.status_code == 403:
+                known_expired = self._token_is_expired(token)
+                if known_expired:
+                    if retry_reads and not auth_replayed:
+                        try:
+                            refreshed = self._refresh_token(token)
+                        except Exception:
+                            self._remaining_budget(
+                                deadline,
+                                method=normalized_method,
+                                path=context_path,
+                            )
+                            raise
+                        self._remaining_budget(
+                            deadline,
+                            method=normalized_method,
+                            path=context_path,
+                        )
+                        if refreshed is not None:
+                            auth_replayed = True
+                            prepared_token = refreshed
+                            continue
+                    else:
+                        self._invalidate_token(token)
+                # A bare 403 is a permission error. It is never proof of expiry.
+                raise api_error_from_response(response, method=normalized_method, path=context_path)
+
+            if (
+                retry_reads
+                and response.status_code in self._config.retry.retry_statuses
+                and retry_attempt < self._config.retry.max_attempts
+            ):
+                self._sleep_for_retry(
+                    self._backoff_delay(retry_attempt, response.headers.get("Retry-After")),
+                    deadline,
+                    method=normalized_method,
+                    path=context_path,
+                )
+                retry_attempt += 1
+                continue
+
+            if response.status_code >= 400 or not _is_expected(response.status_code, expected):
+                raise api_error_from_response(response, method=normalized_method, path=context_path)
+
+            raw = response.content
+            metadata = HttpMetadata(
+                status_code=response.status_code,
+                method=normalized_method,
+                url=str(response.url),
+                headers=safe_response_headers(response.headers),
+                request_id=extract_request_id(response.headers),
+                etag=response.headers.get("ETag"),
+                location=response.headers.get("Location"),
+                attempts=sends,
+                elapsed=self._monotonic() - started,
+            )
+            return ApiResponse(data=raw, http=metadata, raw=raw)
+
+    def close(self) -> None:
+        with self._state_lock:
+            if self._closed:
+                return
+            self._closed = True
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> HttpxTransport:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            "HttpxTransport("
+            f"base_url={self._config.base_url!r}, "
+            f"authenticated={self._token_provider is not None}, "
+            f"owns_client={self._owns_client!r}, closed={self._closed!r})"
+        )
+
+    def _common_headers(
+        self,
+        *,
+        token: str | None,
+        authenticated: bool,
+        api_version: str | None,
+    ) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Accept-Version": api_version or self._config.api_version,
+            "Client-ID": self._config.client_id,
+            "X-Api-Key": self._config.api_key,
+            "User-Agent": f"redblack-python-sdk/{__version__}",
+        }
+        if authenticated:
+            if token is None:
+                raise AuthenticationError("token provider returned no access token")
+            headers["Authorization"] = f"Bearer {token}"
+        return headers
+
+    def _get_token(self, *, force_refresh: bool = False) -> str:
+        if self._token_provider is None:
+            raise AuthenticationError("this request requires a configured token provider")
+        token = self._token_provider.get_token(force_refresh=force_refresh)
+        return self._validate_token(token)
+
+    @staticmethod
+    def _validate_token(token: object) -> str:
+        if not isinstance(token, str) or not token.strip():
+            raise AuthenticationError("token provider returned an invalid access token")
+        if "\r" in token or "\n" in token:
+            raise AuthenticationError("token provider returned an invalid access token")
+        return token
+
+    def _refresh_token(self, failed_token: str | None) -> str | None:
+        """Refresh explicitly and decline a futile same-token replay."""
+
+        refresh_after_failure = getattr(self._token_provider, "refresh_after_failure", None)
+        if callable(refresh_after_failure):
+            refreshed = self._validate_token(refresh_after_failure(failed_token))
+        else:
+            self._invalidate_token(failed_token)
+            refreshed = self._get_token(force_refresh=True)
+        return refreshed if refreshed != failed_token else None
+
+    def _invalidate_token(self, token: str | None) -> None:
+        invalidate = getattr(self._token_provider, "invalidate", None)
+        if callable(invalidate):
+            invalidate(token)
+
+    def _token_is_expired(self, token: str | None) -> bool:
+        checker = getattr(self._token_provider, "is_token_expired", None)
+        return bool(checker(token)) if callable(checker) else False
+
+    def _backoff_delay(self, retry_attempt: int, retry_after: str | None) -> float:
+        if retry_after is not None:
+            parsed = _parse_retry_after(retry_after)
+            if parsed is not None:
+                return parsed
+        ceiling = min(
+            float(self._config.retry.max_delay),
+            float(self._config.retry.base_delay) * (2 ** (retry_attempt - 1)),
+        )
+        random_fraction = max(0.0, min(1.0, float(self._random_value())))
+        return ceiling * random_fraction
+
+    @staticmethod
+    def _timeout_error(*, method: str, path: str) -> RequestTimeoutError:
+        return RequestTimeoutError(
+            "RedBlack API request exhausted its timeout budget",
+            method=method,
+            path=path,
+        )
+
+    def _budget_expired(self, deadline: float | None) -> bool:
+        return deadline is not None and self._monotonic() >= deadline
+
+    def _remaining_budget(
+        self,
+        deadline: float | None,
+        *,
+        method: str,
+        path: str,
+    ) -> float | None:
+        if deadline is None:
+            return None
+        remaining = deadline - self._monotonic()
+        if remaining <= 0:
+            raise self._timeout_error(method=method, path=path)
+        return remaining
+
+    def _timeout_for_budget(
+        self,
+        deadline: float | None,
+        *,
+        method: str,
+        path: str,
+    ) -> httpx.Timeout:
+        remaining = self._remaining_budget(deadline, method=method, path=path)
+        if remaining is None:
+            return self._timeout
+        return httpx.Timeout(
+            connect=min(float(self._config.timeout.connect), remaining),
+            read=min(float(self._config.timeout.read), remaining),
+            write=min(float(self._config.timeout.write), remaining),
+            pool=min(float(self._config.timeout.pool), remaining),
+        )
+
+    def _sleep_for_retry(
+        self,
+        delay: float,
+        deadline: float | None,
+        *,
+        method: str,
+        path: str,
+    ) -> None:
+        remaining = self._remaining_budget(deadline, method=method, path=path)
+        if remaining is None:
+            self._sleep(delay)
+            return
+        bounded_delay = min(delay, remaining)
+        self._sleep(bounded_delay)
+        if delay >= remaining:
+            raise self._timeout_error(method=method, path=path)
+        self._remaining_budget(deadline, method=method, path=path)
+
+
+def _validate_method(method: object) -> str:
+    if not isinstance(method, str) or not method.strip():
+        raise ConfigurationError("HTTP method must be a non-empty string")
+    normalized = method.strip().upper()
+    if not normalized.isalpha():
+        raise ConfigurationError("HTTP method contains invalid characters")
+    return normalized
+
+
+def _validate_timeout_budget(timeout_budget: object) -> float | None:
+    if timeout_budget is None:
+        return None
+    if (
+        isinstance(timeout_budget, bool)
+        or not isinstance(timeout_budget, int | float)
+        or not isfinite(timeout_budget)
+        or timeout_budget < 0
+    ):
+        raise ConfigurationError("timeout_budget must be a finite non-negative number or None")
+    return float(timeout_budget)
+
+
+def _validate_relative_path(path: object) -> str:
+    if not isinstance(path, str) or not path.startswith("/") or path.startswith("//"):
+        raise ConfigurationError("API path must be an absolute-path reference beginning with '/'")
+    if "\\" in path or any(ord(character) < 32 for character in path):
+        raise ConfigurationError("API path contains unsafe characters")
+    split = urlsplit(path)
+    if split.scheme or split.netloc or split.query or split.fragment:
+        raise ConfigurationError("API path must be same-origin and contain no query or fragment")
+    if any(segment in {".", ".."} for segment in split.path.split("/")):
+        raise ConfigurationError("API path must not contain dot segments")
+    return path
+
+
+def _validate_headers(headers: RequestHeaders) -> dict[str, str]:
+    if headers is None:
+        return {}
+    result: dict[str, str] = {}
+    for name, value in headers.items():
+        if not isinstance(name, str) or not isinstance(value, str):
+            raise ConfigurationError("request header names and values must be strings")
+        if name.lower() in _PROTECTED_HEADERS:
+            raise ConfigurationError(f"request header {name!r} is managed by the SDK")
+        if "\r" in name or "\n" in name or "\r" in value or "\n" in value:
+            raise ConfigurationError("request headers must not contain newlines")
+        result[name] = value
+    return result
+
+
+def _is_expected(status_code: int, expected: frozenset[int] | None) -> bool:
+    if expected is None:
+        return 200 <= status_code < 300
+    return status_code in expected
+
+
+def _parse_retry_after(value: str) -> float | None:
+    stripped = value.strip()
+    try:
+        seconds = float(stripped)
+    except ValueError:
+        seconds = -1
+    if seconds >= 0:
+        return seconds
+    try:
+        when = email.utils.parsedate_to_datetime(stripped)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, (when - datetime.now(UTC)).total_seconds())
+
+
+__all__ = [
+    "HttpTransport",
+    "HttpxTransport",
+    "IterableStatus",
+    "QueryParams",
+    "RequestHeaders",
+]