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

redblack/_version.py

@@ -0,0 +1,4 @@
+"""Package and contract version constants."""
+
+__version__ = "0.1.0"
+SUPPORTED_API_VERSION = "2026.3.0"

redblack/auth.py

@@ -0,0 +1,352 @@
+"""Thread-safe in-memory authentication for the RedBlack API."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from math import isfinite
+from typing import Protocol, runtime_checkable
+
+import httpx
+
+from ._version import __version__
+from .config import PasswordCredentials, RedBlackConfig
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    extract_request_id,
+)
+
+_DOCUMENTED_TOKEN_LIFETIME = 8 * 60 * 60
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """Minimal custom token-provider contract.
+
+    Built-in providers additionally expose ``invalidate`` and
+    ``is_token_expired``. The transport checks those capabilities without
+    requiring custom providers to implement them.
+    """
+
+    def get_token(self, *, force_refresh: bool = False) -> str:
+        """Return a usable bearer token."""
+        ...
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class StaticTokenProvider:
+    """Return a caller-managed token without persisting or refreshing it."""
+
+    access_token: str
+    client_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.access_token, str) or not self.access_token.strip():
+            raise ConfigurationError("access_token must be a non-empty string")
+        if "\r" in self.access_token or "\n" in self.access_token:
+            raise ConfigurationError("access_token must not contain newlines")
+        if self.client_id is not None and (
+            not isinstance(self.client_id, str) or not self.client_id.strip()
+        ):
+            raise ConfigurationError("client_id must be a non-empty string when provided")
+
+    def get_token(self, *, force_refresh: bool = False) -> str:
+        del force_refresh
+        return self.access_token
+
+    def invalidate(self, token: str | None = None) -> None:
+        """Do nothing: lifecycle of a static token belongs to the caller."""
+
+        del token
+
+    def is_token_expired(self, token: str | None = None) -> bool:
+        del token
+        return False
+
+    def __repr__(self) -> str:
+        return (
+            "StaticTokenProvider(access_token=<redacted>, "
+            f"client_id={'<redacted>' if self.client_id is not None else None})"
+        )
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class _CachedToken:
+    value: str = field(repr=False)
+    expires_at: float
+    refresh_at: float
+
+
+class PasswordGrantTokenProvider:
+    """Acquire and cache RedBlack password-grant tokens in memory.
+
+    The acquisition lock is deliberately held for the HTTP exchange. That
+    makes refresh single-flight: concurrent callers wait for and reuse the one
+    newly acquired token instead of consuming RedBlack's five-token allowance.
+    """
+
+    def __init__(
+        self,
+        config: RedBlackConfig,
+        credentials: PasswordCredentials | None = None,
+        *,
+        client: httpx.Client | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        refresh_margin: float = 300.0,
+        fallback_lifetime: float = _DOCUMENTED_TOKEN_LIFETIME,
+    ) -> None:
+        resolved_credentials = credentials or config.credentials
+        if resolved_credentials is None:
+            raise ConfigurationError("PasswordGrantTokenProvider requires PasswordCredentials")
+        if not isinstance(resolved_credentials, PasswordCredentials):
+            raise ConfigurationError("credentials must be PasswordCredentials")
+        if (
+            isinstance(refresh_margin, bool)
+            or not isinstance(refresh_margin, int | float)
+            or not isfinite(refresh_margin)
+            or refresh_margin < 0
+        ):
+            raise ConfigurationError("refresh_margin must be non-negative")
+        if (
+            isinstance(fallback_lifetime, bool)
+            or not isinstance(fallback_lifetime, int | float)
+            or not isfinite(fallback_lifetime)
+            or fallback_lifetime <= 0
+        ):
+            raise ConfigurationError("fallback_lifetime must be positive")
+
+        self._config = config
+        self._credentials = resolved_credentials
+        self._clock = clock
+        self._refresh_margin = float(refresh_margin)
+        self._fallback_lifetime = float(fallback_lifetime)
+        self._lock = threading.Lock()
+        self._cached: _CachedToken | None = None
+        self._closed = False
+        self._owns_client = client is None
+        self._timeout = httpx.Timeout(
+            connect=config.timeout.connect,
+            read=config.timeout.read,
+            write=config.timeout.write,
+            pool=config.timeout.pool,
+        )
+        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
+
+    @property
+    def client_id(self) -> str:
+        """The same authoritative client ID used by resource headers."""
+
+        return self._config.client_id
+
+    def get_token(self, *, force_refresh: bool = False) -> str:
+        """Return a cached token or acquire exactly one replacement."""
+
+        now = self._clock()
+        cached = self._cached
+        if not force_refresh and cached is not None and now < cached.refresh_at:
+            return cached.value
+
+        with self._lock:
+            if self._closed:
+                raise AuthenticationError("token provider is closed")
+            now = self._clock()
+            cached = self._cached
+            if not force_refresh and cached is not None and now < cached.refresh_at:
+                return cached.value
+            replacement = self._request_token(now)
+            self._cached = replacement
+            return replacement.value
+
+    def invalidate(self, token: str | None = None) -> None:
+        """Invalidate only the token that failed, preserving a newer refresh."""
+
+        with self._lock:
+            if self._cached is not None and (token is None or self._cached.value == token):
+                self._cached = None
+
+    def refresh_after_failure(self, failed_token: str | None) -> str:
+        """Refresh once unless another caller already replaced the failed token."""
+
+        with self._lock:
+            if self._closed:
+                raise AuthenticationError("token provider is closed")
+            now = self._clock()
+            cached = self._cached
+            if (
+                failed_token is not None
+                and cached is not None
+                and cached.value != failed_token
+                and now < cached.refresh_at
+            ):
+                return cached.value
+            replacement = self._request_token(now)
+            self._cached = replacement
+            return replacement.value
+
+    def is_token_expired(self, token: str | None = None) -> bool:
+        """Return known local expiry, not a guess based only on HTTP 403."""
+
+        cached = self._cached
+        if cached is None or (token is not None and cached.value != token):
+            return False
+        return self._clock() >= cached.expires_at
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self._cached = None
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> PasswordGrantTokenProvider:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            "PasswordGrantTokenProvider("
+            "client_id=<redacted>, credentials=<redacted>, "
+            f"has_cached_token={self._cached is not None}, closed={self._closed})"
+        )
+
+    def _request_token(self, now: float) -> _CachedToken:
+        url = f"{self._config.base_url}/auth/v1/token"
+        headers = {
+            "Accept-Version": self._config.api_version,
+            "X-Api-Key": self._config.api_key,
+            "Accept": "application/json",
+        }
+        form = {
+            "client_id": self._config.client_id,
+            "client_secret": self._credentials.client_secret,
+            "username": self._credentials.username,
+            "password": self._credentials.password,
+            "grant_type": "password",
+            "scope": "openid",
+        }
+        secrets = (
+            self._config.api_key,
+            self._config.client_id,
+            self._credentials.client_secret,
+            self._credentials.username,
+            self._credentials.password,
+        )
+        try:
+            response = self._client.post(
+                url,
+                headers=headers,
+                data=form,
+                timeout=self._timeout,
+                follow_redirects=False,
+            )
+        except httpx.TimeoutException as exc:
+            raise AuthenticationError("RedBlack token request timed out", secrets=secrets) from exc
+        except httpx.TransportError as exc:
+            raise AuthenticationError(
+                "RedBlack token request failed before receiving a response",
+                secrets=secrets,
+            ) from exc
+
+        if response.status_code != 200:
+            error, description = _oauth_error_fields(response)
+            raise AuthenticationError(
+                "RedBlack rejected the token request",
+                error=error,
+                error_description=description,
+                status_code=response.status_code,
+                request_id=extract_request_id(response.headers),
+                secrets=secrets,
+            )
+
+        try:
+            payload = response.json()
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise AuthenticationError(
+                "RedBlack token response was not valid JSON",
+                status_code=response.status_code,
+                request_id=extract_request_id(response.headers),
+            ) from exc
+        if not isinstance(payload, Mapping):
+            raise AuthenticationError(
+                "RedBlack token response must be a JSON object",
+                status_code=response.status_code,
+                request_id=extract_request_id(response.headers),
+            )
+        token = payload.get("access_token")
+        if not isinstance(token, str) or not token.strip():
+            raise AuthenticationError(
+                "RedBlack token response did not contain a usable access_token",
+                status_code=response.status_code,
+                request_id=extract_request_id(response.headers),
+            )
+
+        lifetime = _parse_expires_in(payload.get("expires_in"), self._fallback_lifetime)
+        # A short-lived test token should not become instantly stale merely
+        # because the normal eight-hour safety margin is larger than its life.
+        effective_margin = min(self._refresh_margin, lifetime * 0.5)
+        expires_at = now + lifetime
+        return _CachedToken(
+            value=token,
+            expires_at=expires_at,
+            refresh_at=expires_at - effective_margin,
+        )
+
+
+def _oauth_error_fields(response: httpx.Response) -> tuple[str | None, str | None]:
+    try:
+        payload = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None, None
+    if not isinstance(payload, Mapping):
+        return None, None
+    error = payload.get("error")
+    description = payload.get("error_description")
+    return (
+        error if isinstance(error, str) else None,
+        description if isinstance(description, str) else None,
+    )
+
+
+def _parse_expires_in(value: object, fallback: float) -> float:
+    if isinstance(value, bool):
+        return fallback
+    if (
+        isinstance(value, int | float)
+        and not isinstance(value, bool)
+        and isfinite(value)
+        and value > 0
+    ):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            parsed = float(value)
+        except ValueError:
+            return fallback
+        if isfinite(parsed) and parsed > 0:
+            return parsed
+    return fallback
+
+
+__all__ = [
+    "PasswordCredentials",
+    "PasswordGrantTokenProvider",
+    "StaticTokenProvider",
+    "TokenProvider",
+]