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

redblack/config.py

@@ -0,0 +1,576 @@
+"""Explicit, secret-safe configuration for the RedBlack SDK."""
+
+from __future__ import annotations
+
+import os
+import ssl
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from math import isfinite
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit, urlunsplit
+
+from ._version import SUPPORTED_API_VERSION
+from .errors import ConfigurationError
+
+if TYPE_CHECKING:
+    import httpx
+
+    from .auth import TokenProvider
+
+_UNSET = object()
+
+
+class Environment(str, Enum):
+    """A named RedBlack deployment.
+
+    No environment is selected implicitly. In particular, production is never
+    a default.
+    """
+
+    UAT = "uat"
+    PRODUCTION = "production"
+
+
+_ENVIRONMENT_URLS: dict[Environment, str] = {
+    Environment.UAT: "https://api.uat.rbrebal.com",
+    Environment.PRODUCTION: "https://api.rbrebal.com",
+}
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class PasswordCredentials:
+    """Credentials for RedBlack's documented OAuth password grant."""
+
+    client_secret: str
+    username: str
+    password: str
+
+    def __post_init__(self) -> None:
+        _require_nonempty_secret(self.client_secret, "client_secret")
+        _require_nonempty_secret(self.username, "username")
+        _require_nonempty_secret(self.password, "password")
+
+    def __repr__(self) -> str:
+        return (
+            "PasswordCredentials(client_secret=<redacted>, "
+            "username=<redacted>, password=<redacted>)"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TimeoutConfig:
+    """Per-phase HTTP timeout values, in seconds."""
+
+    connect: float = 10.0
+    read: float = 30.0
+    write: float = 30.0
+    pool: float = 10.0
+
+    def __post_init__(self) -> None:
+        for name in ("connect", "read", "write", "pool"):
+            value = getattr(self, name)
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, int | float)
+                or not isfinite(value)
+                or value <= 0
+            ):
+                raise ConfigurationError(f"{name} timeout must be a positive number")
+
+
+@dataclass(frozen=True, slots=True)
+class RetryConfig:
+    """Conservative retry settings for safe reads.
+
+    ``max_attempts`` includes the initial request. Mutating methods are never
+    retried by the built-in transport.
+    """
+
+    max_attempts: int = 3
+    base_delay: float = 0.5
+    max_delay: float = 8.0
+    retry_statuses: frozenset[int] = field(
+        default_factory=lambda: frozenset({429, 500, 502, 503, 504})
+    )
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.max_attempts, bool)
+            or not isinstance(self.max_attempts, int)
+            or self.max_attempts < 1
+        ):
+            raise ConfigurationError("retry max_attempts must be at least 1")
+        if (
+            isinstance(self.base_delay, bool)
+            or not isinstance(self.base_delay, int | float)
+            or not isfinite(self.base_delay)
+            or self.base_delay < 0
+        ):
+            raise ConfigurationError("retry base_delay must be a non-negative number")
+        if (
+            isinstance(self.max_delay, bool)
+            or not isinstance(self.max_delay, int | float)
+            or not isfinite(self.max_delay)
+            or self.max_delay < self.base_delay
+        ):
+            raise ConfigurationError("retry max_delay must be at least base_delay")
+        invalid = [
+            status
+            for status in self.retry_statuses
+            if isinstance(status, bool) or not isinstance(status, int) or not 100 <= status <= 599
+        ]
+        if invalid:
+            raise ConfigurationError("retry_statuses must contain valid HTTP status codes")
+
+
+VerifyValue = bool | str | ssl.SSLContext
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class RedBlackConfig:
+    """Resolved configuration used by authentication and HTTP transport.
+
+    Constructing this class reads neither process variables nor files. Use
+    :meth:`from_env` or :meth:`from_dotenv` when that behavior is wanted.
+    """
+
+    environment: Environment | str
+    api_key: str
+    client_id: str
+    api_version: str = SUPPORTED_API_VERSION
+    credentials: PasswordCredentials | None = None
+    access_token: str | None = None
+    base_url: str | None = None
+    timeout: TimeoutConfig = field(default_factory=TimeoutConfig)
+    retry: RetryConfig = field(default_factory=RetryConfig)
+    verify: VerifyValue = True
+    proxy: str | None = None
+    trust_env: bool = False
+    allow_insecure_transport: bool = False
+    allow_unsupported_api_version: bool = False
+
+    def __post_init__(self) -> None:
+        environment = _coerce_environment(self.environment)
+        object.__setattr__(self, "environment", environment)
+
+        _require_header_value(self.api_key, "api_key")
+        _require_header_value(self.client_id, "client_id")
+        if not isinstance(self.api_version, str) or not self.api_version.strip():
+            raise ConfigurationError("api_version must be a non-empty string")
+        if "\r" in self.api_version or "\n" in self.api_version:
+            raise ConfigurationError("api_version must not contain newlines")
+        if self.api_version != SUPPORTED_API_VERSION and not self.allow_unsupported_api_version:
+            raise ConfigurationError(
+                f"typed models support API {SUPPORTED_API_VERSION}; "
+                "set allow_unsupported_api_version=True for an explicit raw-mode override"
+            )
+
+        custom_base_url = self.base_url is not None
+        resolved_url = self.base_url or _ENVIRONMENT_URLS[environment]
+        normalized_url = _validate_base_url(
+            resolved_url,
+            custom=custom_base_url,
+            allow_insecure=self.allow_insecure_transport,
+        )
+        object.__setattr__(self, "base_url", normalized_url)
+
+        if not isinstance(self.timeout, TimeoutConfig):
+            raise ConfigurationError("timeout must be a TimeoutConfig")
+        if not isinstance(self.retry, RetryConfig):
+            raise ConfigurationError("retry must be a RetryConfig")
+        if not isinstance(self.trust_env, bool):
+            raise ConfigurationError("trust_env must be a bool")
+        if not isinstance(self.allow_insecure_transport, bool):
+            raise ConfigurationError("allow_insecure_transport must be a bool")
+        if not isinstance(self.allow_unsupported_api_version, bool):
+            raise ConfigurationError("allow_unsupported_api_version must be a bool")
+
+        if self.verify is False and (not self.allow_insecure_transport or not custom_base_url):
+            raise ConfigurationError(
+                "TLS verification can be disabled only for an explicit custom test URL "
+                "with allow_insecure_transport=True"
+            )
+        if not isinstance(self.verify, bool | str | ssl.SSLContext):
+            raise ConfigurationError("verify must be a bool, CA path, or SSLContext")
+        if isinstance(self.verify, str) and not self.verify.strip():
+            raise ConfigurationError("verify CA path must not be empty")
+
+        if self.proxy is not None:
+            _validate_proxy(self.proxy)
+
+        if self.credentials is not None and not isinstance(self.credentials, PasswordCredentials):
+            raise ConfigurationError("credentials must be PasswordCredentials")
+        if self.access_token is not None:
+            _require_header_value(self.access_token, "access_token")
+        if self.credentials is not None and self.access_token is not None:
+            raise ConfigurationError(
+                "authentication is ambiguous: choose credentials or access_token, not both"
+            )
+
+    @property
+    def auth_mode(self) -> str | None:
+        """Return the configured built-in authentication mode, if any."""
+
+        if self.credentials is not None:
+            return "password"
+        if self.access_token is not None:
+            return "static"
+        return None
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        environ: Mapping[str, str] | None = None,
+        require_auth: bool = True,
+        **overrides: Any,
+    ) -> RedBlackConfig:
+        """Resolve configuration from explicit values, then process variables.
+
+        This method never reads a dotenv file. ``environ`` exists for testing
+        and embedding; when omitted, a snapshot of :data:`os.environ` is used.
+        """
+
+        process_values = dict(os.environ if environ is None else environ)
+        return cls._from_sources(
+            process_values=process_values,
+            dotenv_values={},
+            overrides=overrides,
+            require_auth=require_auth,
+        )
+
+    @classmethod
+    def from_dotenv(
+        cls,
+        path: str | os.PathLike[str] | None = None,
+        *,
+        search_start: str | os.PathLike[str] | None = None,
+        environ: Mapping[str, str] | None = None,
+        require_auth: bool = True,
+        **overrides: Any,
+    ) -> RedBlackConfig:
+        """Resolve explicit values, process variables, then one bounded dotenv.
+
+        When ``path`` is omitted, discovery never walks beyond the nearest
+        ``pyproject.toml`` or ``.git`` project boundary.
+        """
+
+        dotenv_path = (
+            _explicit_dotenv_path(path)
+            if path is not None
+            else _discover_project_dotenv(search_start)
+        )
+        file_values = _read_dotenv(dotenv_path) if dotenv_path is not None else {}
+        process_values = dict(os.environ if environ is None else environ)
+        return cls._from_sources(
+            process_values=process_values,
+            dotenv_values=file_values,
+            overrides=overrides,
+            require_auth=require_auth,
+        )
+
+    @classmethod
+    def _from_sources(
+        cls,
+        *,
+        process_values: Mapping[str, str],
+        dotenv_values: Mapping[str, str | None],
+        overrides: Mapping[str, Any],
+        require_auth: bool,
+    ) -> RedBlackConfig:
+        if not isinstance(require_auth, bool):
+            raise ConfigurationError("require_auth must be a bool")
+        remaining = dict(overrides)
+        allowed = {
+            "environment",
+            "api_key",
+            "client_id",
+            "api_version",
+            "credentials",
+            "client_secret",
+            "username",
+            "password",
+            "access_token",
+            "base_url",
+            "timeout",
+            "retry",
+            "verify",
+            "proxy",
+            "trust_env",
+            "allow_insecure_transport",
+            "allow_unsupported_api_version",
+        }
+        unknown = sorted(set(remaining) - allowed)
+        if unknown:
+            raise ConfigurationError(f"unknown configuration argument(s): {', '.join(unknown)}")
+
+        def resolve(field_name: str, variable_name: str, default: Any = _UNSET) -> Any:
+            if field_name in remaining:
+                return remaining.pop(field_name)
+            if variable_name in process_values:
+                return process_values[variable_name]
+            if variable_name in dotenv_values:
+                return dotenv_values[variable_name]
+            if default is not _UNSET:
+                return default
+            raise ConfigurationError(f"missing required setting {variable_name}")
+
+        environment = resolve("environment", "REDBLACK_ENVIRONMENT")
+        api_key = resolve("api_key", "REDBLACK_API_KEY")
+        client_id = resolve("client_id", "REDBLACK_CLIENT_ID")
+        api_version = resolve("api_version", "REDBLACK_API_VERSION", SUPPORTED_API_VERSION)
+        access_token = resolve("access_token", "REDBLACK_ACCESS_TOKEN", None)
+
+        explicit_credentials = remaining.pop("credentials", _UNSET)
+        if explicit_credentials is not _UNSET:
+            if any(name in remaining for name in ("client_secret", "username", "password")):
+                raise ConfigurationError(
+                    "pass credentials or individual password-grant fields, not both"
+                )
+            credentials = explicit_credentials
+        else:
+            client_secret = resolve("client_secret", "REDBLACK_CLIENT_SECRET", None)
+            username = resolve("username", "REDBLACK_USERNAME", None)
+            password = resolve("password", "REDBLACK_PASSWORD", None)
+            password_values = (client_secret, username, password)
+            if any(value is not None for value in password_values):
+                missing = [
+                    name
+                    for name, value in zip(
+                        ("REDBLACK_CLIENT_SECRET", "REDBLACK_USERNAME", "REDBLACK_PASSWORD"),
+                        password_values,
+                        strict=True,
+                    )
+                    if value is None
+                ]
+                if missing:
+                    raise ConfigurationError(
+                        "incomplete password-grant settings; missing " + ", ".join(missing)
+                    )
+                credentials = PasswordCredentials(
+                    client_secret=client_secret,
+                    username=username,
+                    password=password,
+                )
+            else:
+                credentials = None
+
+        keyword_defaults: dict[str, Any] = {
+            "base_url": None,
+            "timeout": TimeoutConfig(),
+            "retry": RetryConfig(),
+            "verify": True,
+            "proxy": None,
+            "trust_env": False,
+            "allow_insecure_transport": False,
+            "allow_unsupported_api_version": False,
+        }
+        keyword_values = {
+            name: remaining.pop(name, default) for name, default in keyword_defaults.items()
+        }
+        if remaining:
+            # Defensive: the allowlist and extraction above should make this unreachable.
+            raise ConfigurationError(
+                f"unhandled configuration argument(s): {', '.join(sorted(remaining))}"
+            )
+
+        config = cls(
+            environment=environment,
+            api_key=api_key,
+            client_id=client_id,
+            api_version=api_version,
+            credentials=credentials,
+            access_token=access_token,
+            **keyword_values,
+        )
+        if require_auth and config.auth_mode is None:
+            raise ConfigurationError(
+                "missing authentication: configure REDBLACK_ACCESS_TOKEN or all of "
+                "REDBLACK_CLIENT_SECRET, REDBLACK_USERNAME, and REDBLACK_PASSWORD"
+            )
+        return config
+
+    def build_token_provider(self, *, http_client: httpx.Client | None = None) -> TokenProvider:
+        """Build the configured built-in token provider.
+
+        Applications using a custom provider should construct it themselves
+        and leave ``credentials`` and ``access_token`` unset.
+        """
+
+        from .auth import PasswordGrantTokenProvider, StaticTokenProvider
+
+        if self.access_token is not None:
+            return StaticTokenProvider(self.access_token, client_id=self.client_id)
+        if self.credentials is not None:
+            return PasswordGrantTokenProvider(self, self.credentials, client=http_client)
+        raise ConfigurationError(
+            "no built-in authentication mode is configured; provide a token provider"
+        )
+
+    def __repr__(self) -> str:
+        return (
+            "RedBlackConfig("
+            f"environment={self.environment!r}, "
+            f"api_version={self.api_version!r}, "
+            f"base_url={self.base_url!r}, "
+            "api_key=<redacted>, client_id=<redacted>, "
+            f"auth_mode={self.auth_mode!r}, "
+            f"timeout={self.timeout!r}, retry={self.retry!r}, "
+            f"verify={_safe_verify_repr(self.verify)}, proxy={_safe_proxy_repr(self.proxy)}, "
+            f"trust_env={self.trust_env!r})"
+        )
+
+
+def _coerce_environment(value: Environment | str) -> Environment:
+    if isinstance(value, Environment):
+        return value
+    if isinstance(value, str):
+        try:
+            return Environment(value.strip().lower())
+        except ValueError:
+            pass
+    raise ConfigurationError("environment must be explicitly set to 'uat' or 'production'")
+
+
+def _require_nonempty_secret(value: object, field_name: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError(f"{field_name} must be a non-empty string")
+
+
+def _require_header_value(value: object, field_name: str) -> None:
+    _require_nonempty_secret(value, field_name)
+    if isinstance(value, str) and ("\r" in value or "\n" in value):
+        raise ConfigurationError(f"{field_name} must not contain newlines")
+
+
+def _validate_base_url(value: object, *, custom: bool, allow_insecure: bool) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError("base_url must be a non-empty URL")
+    if any(ord(character) < 32 for character in value):
+        raise ConfigurationError("base_url must not contain control characters")
+    try:
+        split = urlsplit(value.strip())
+        _ = split.port
+    except ValueError as exc:
+        raise ConfigurationError("base_url is malformed") from exc
+    if split.username is not None or split.password is not None:
+        raise ConfigurationError("base_url must not contain user information")
+    if not split.hostname or split.query or split.fragment:
+        raise ConfigurationError("base_url must have a host and no query or fragment")
+    if split.scheme != "https":
+        local_hosts = {"localhost", "127.0.0.1", "::1"}
+        if not (
+            custom
+            and allow_insecure
+            and split.scheme == "http"
+            and split.hostname.lower() in local_hosts
+        ):
+            raise ConfigurationError(
+                "base_url must use HTTPS; insecure HTTP is limited to an explicit "
+                "localhost test URL"
+            )
+    normalized_path = split.path.rstrip("/")
+    return urlunsplit((split.scheme, split.netloc, normalized_path, "", ""))
+
+
+def _validate_proxy(value: object) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError("proxy must be a non-empty URL")
+    try:
+        split = urlsplit(value)
+        _ = split.port
+    except ValueError as exc:
+        raise ConfigurationError("proxy URL is malformed") from exc
+    if split.scheme not in {"http", "https"} or not split.hostname:
+        raise ConfigurationError("proxy must be an HTTP or HTTPS URL")
+
+
+def _safe_proxy_repr(proxy: str | None) -> str:
+    if proxy is None:
+        return "None"
+    split = urlsplit(proxy)
+    safe = urlunsplit((split.scheme, split.hostname or "", split.path, "", ""))
+    return repr(safe)
+
+
+def _safe_verify_repr(verify: VerifyValue) -> str:
+    if isinstance(verify, ssl.SSLContext):
+        return "<SSLContext>"
+    return repr(verify)
+
+
+def _explicit_dotenv_path(path: str | os.PathLike[str]) -> Path:
+    resolved = Path(path).expanduser().resolve()
+    if not resolved.is_file():
+        raise ConfigurationError(f"dotenv file does not exist: {resolved}")
+    return resolved
+
+
+def _discover_project_dotenv(
+    search_start: str | os.PathLike[str] | None,
+) -> Path | None:
+    start = Path.cwd() if search_start is None else Path(search_start).expanduser()
+    try:
+        start = start.resolve(strict=True)
+    except FileNotFoundError as exc:
+        raise ConfigurationError(f"dotenv search_start does not exist: {start}") from exc
+    if start.is_file():
+        start = start.parent
+
+    ancestors = (start, *start.parents)
+    boundary: Path | None = None
+    for candidate in ancestors:
+        if (candidate / "pyproject.toml").exists() or (candidate / ".git").exists():
+            boundary = candidate
+            break
+
+    if boundary is None:
+        candidate = start / ".env"
+        return (
+            _resolve_discovered_dotenv(candidate, boundary=start) if candidate.is_file() else None
+        )
+
+    for candidate_dir in ancestors:
+        candidate = candidate_dir / ".env"
+        if candidate.is_file():
+            return _resolve_discovered_dotenv(candidate, boundary=boundary)
+        if candidate_dir == boundary:
+            break
+    return None
+
+
+def _resolve_discovered_dotenv(candidate: Path, *, boundary: Path) -> Path:
+    """Resolve a discovered dotenv without allowing a symlink outside its project."""
+
+    resolved = candidate.resolve(strict=True)
+    try:
+        resolved.relative_to(boundary)
+    except ValueError as exc:
+        raise ConfigurationError(
+            f"discovered dotenv file escapes the project boundary: {candidate}"
+        ) from exc
+    return resolved
+
+
+def _read_dotenv(path: Path) -> dict[str, str | None]:
+    try:
+        from dotenv import dotenv_values
+    except ImportError as exc:  # pragma: no cover - declared runtime dependency
+        raise ConfigurationError("python-dotenv is required to use from_dotenv()") from exc
+    try:
+        return dict(dotenv_values(dotenv_path=path, encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise ConfigurationError(f"could not parse dotenv file: {path}") from exc
+
+
+__all__ = [
+    "Environment",
+    "PasswordCredentials",
+    "RedBlackConfig",
+    "RetryConfig",
+    "TimeoutConfig",
+    "VerifyValue",
+]