basaltic-sdk-python 0.1.1__py3-none-any.whl

basaltic/auth.py

@@ -0,0 +1,231 @@
+"""Cached credentials with thread-safe and asyncio single-flight refresh."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import math
+import threading
+import time
+from collections.abc import Callable
+from typing import Protocol
+
+import httpx
+
+from .config import positive_timeout, validate_token, validate_url
+from .errors import AuthenticationError
+
+
+class TokenProvider(Protocol):
+    def get_token(self) -> str: ...
+
+
+class AsyncTokenProvider(Protocol):
+    async def get_token(self) -> str: ...
+
+
+class StaticToken:
+    def __init__(self, token: str) -> None:
+        self.__token = validate_token(token)
+
+    def get_token(self) -> str:
+        return self.__token
+
+
+class AsyncStaticToken:
+    def __init__(self, token: str) -> None:
+        self.__token = validate_token(token)
+
+    async def get_token(self) -> str:
+        return self.__token
+
+
+def _token_response(status: int, raw: bytes) -> tuple[str, float]:
+    data: object = None
+    try:
+        data = json.loads(raw)
+    except (ValueError, UnicodeDecodeError):
+        pass
+    if status != 200 or not isinstance(data, dict):
+        code = data.get("error", "") if isinstance(data, dict) else ""
+        raise AuthenticationError(
+            status,
+            code if code in ("invalid_client", "invalid_grant", "temporarily_unavailable") else "",
+        )
+    token, lifetime, kind = (
+        data.get("access_token"),
+        data.get("expires_in", 900),
+        data.get("token_type", "Bearer"),
+    )
+    valid = isinstance(token, str) and isinstance(kind, str) and kind.lower() == "bearer"
+    try:
+        seconds = float(lifetime)
+        if not math.isfinite(seconds) or seconds <= 0 or isinstance(lifetime, bool):
+            valid = False
+        if valid and isinstance(token, str):
+            validate_token(token)
+    except (ValueError, TypeError, OverflowError):
+        valid = False
+    if not valid or not isinstance(token, str):
+        raise AuthenticationError(status)
+    return token, seconds - min(300, seconds * 0.1)
+
+
+def _request(key: str, secret: str, url: str, timeout: float) -> httpx.Request:
+    if not key or ":" in key or not secret:
+        raise ValueError("A valid access key ID and secret are required.")
+    encoded = base64.b64encode((key + ":" + secret).encode()).decode()
+    return httpx.Request(
+        "POST",
+        validate_url(url),
+        content=b"grant_type=client_credentials",
+        headers={
+            "Authorization": "Basic " + encoded,
+            "Accept": "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        extensions={"timeout": httpx.Timeout(positive_timeout(timeout)).as_dict()},
+    )
+
+
+class ClientCredentials:
+    def __init__(
+        self,
+        *,
+        access_key_id: str,
+        secret_access_key: str,
+        token_url: str,
+        http_client: httpx.Client,
+        timeout: float = 30,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        # Validate without retaining the prepared request, whose repr may expose headers.
+        _request(access_key_id, secret_access_key, token_url, timeout)
+        self.__key, self.__secret, self.__url = access_key_id, secret_access_key, token_url
+        self._http, self._timeout, self._clock = http_client, timeout, clock
+        self._lock = threading.Lock()
+        self.__cached, self._refresh_at = "", 0.0
+
+    def get_token(self) -> str:
+        with self._lock:
+            if self.__cached and self._clock() < self._refresh_at:
+                return self.__cached
+            now = self._clock()
+            failure: AuthenticationError | None = None
+            response: httpx.Response | None = None
+            try:
+                response = self._http.send(
+                    _request(self.__key, self.__secret, self.__url, self._timeout),
+                    auth=None,
+                    follow_redirects=False,
+                    stream=True,
+                )
+                raw = bytearray()
+                for chunk in response.iter_bytes():
+                    raw.extend(chunk[: 1048577 - len(raw)])
+                    if len(raw) > 1048576:
+                        break
+                if len(raw) > 1048576:
+                    raise AuthenticationError(response.status_code)
+                token, ttl = _token_response(response.status_code, bytes(raw))
+            except (httpx.HTTPError, AuthenticationError) as error:
+                failure = (
+                    AuthenticationError(error.status_code, error.error_code)
+                    if isinstance(error, AuthenticationError)
+                    else AuthenticationError()
+                )
+            finally:
+                if response is not None:
+                    response.close()
+            if failure is not None:
+                raise failure
+            self.__cached, self._refresh_at = token, now + ttl
+            return token
+
+    def invalidate(self, rejected_token: str | None = None) -> None:
+        with self._lock:
+            if rejected_token is None or rejected_token == self.__cached:
+                self.__cached, self._refresh_at = "", 0.0
+
+
+class AsyncClientCredentials:
+    def __init__(
+        self,
+        *,
+        access_key_id: str,
+        secret_access_key: str,
+        token_url: str,
+        http_client: httpx.AsyncClient,
+        timeout: float = 30,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        _request(access_key_id, secret_access_key, token_url, timeout)
+        self.__key, self.__secret, self.__url = access_key_id, secret_access_key, token_url
+        self._http, self._timeout, self._clock = http_client, timeout, clock
+        self.__cached, self._refresh_at = "", 0.0
+        self._pending: asyncio.Task[str] | None = None
+
+    async def get_token(self) -> str:
+        if self.__cached and self._clock() < self._refresh_at:
+            return self.__cached
+        # There is no await between checking and assigning the task; creation is
+        # atomic within the client's event loop. A caller's cancellation is isolated.
+        if self._pending is None:
+            task = asyncio.create_task(self._refresh())
+            self._pending = task
+
+            def done(finished: asyncio.Task[str]) -> None:
+                if self._pending is finished:
+                    self._pending = None
+                if not finished.cancelled():
+                    finished.exception()
+
+            task.add_done_callback(done)
+        return await asyncio.shield(self._pending)
+
+    def invalidate(self, rejected_token: str | None = None) -> None:
+        if rejected_token is None or rejected_token == self.__cached:
+            self.__cached, self._refresh_at = "", 0.0
+
+    async def aclose(self) -> None:
+        if self._pending is not None:
+            pending = self._pending
+            pending.cancel()
+            try:
+                await pending
+            except asyncio.CancelledError:
+                pass
+
+    async def _refresh(self) -> str:
+        now = self._clock()
+        failure: AuthenticationError | None = None
+        response: httpx.Response | None = None
+        try:
+            response = await self._http.send(
+                _request(self.__key, self.__secret, self.__url, self._timeout),
+                auth=None,
+                follow_redirects=False,
+                stream=True,
+            )
+            raw = bytearray()
+            async for chunk in response.aiter_bytes():
+                raw.extend(chunk[: 1048577 - len(raw)])
+                if len(raw) > 1048576:
+                    break
+            if len(raw) > 1048576:
+                raise AuthenticationError(response.status_code)
+            token, ttl = _token_response(response.status_code, bytes(raw))
+        except (httpx.HTTPError, AuthenticationError) as error:
+            failure = (
+                AuthenticationError(error.status_code, error.error_code)
+                if isinstance(error, AuthenticationError)
+                else AuthenticationError()
+            )
+        finally:
+            if response is not None:
+                await response.aclose()
+        if failure is not None:
+            raise failure
+        self.__cached, self._refresh_at = token, now + ttl
+        return token

basaltic/client.py

@@ -0,0 +1,144 @@
+"""Generated service accessors; do not edit."""
+
+from functools import cached_property
+
+from ._client import AsyncClientBase, SyncClientBase
+from .services.audit import AsyncAuditService, AuditService
+from .services.billing import AsyncBillingService, BillingService
+from .services.catalog import AsyncCatalogService, CatalogService
+from .services.certificate import AsyncCertificateService, CertificateService
+from .services.compute import AsyncComputeService, ComputeService
+from .services.dns import AsyncDnsService, DnsService
+from .services.iam import AsyncIamService, IamService
+from .services.kms import AsyncKmsService, KmsService
+from .services.loadbalancer import AsyncLoadbalancerService, LoadbalancerService
+from .services.network import AsyncNetworkService, NetworkService
+from .services.quota import AsyncQuotaService, QuotaService
+from .services.secrets import AsyncSecretsService, SecretsService
+from .services.storage import AsyncStorageService, StorageService
+from .services.telemetry import AsyncTelemetryService, TelemetryService
+from .services.workspace import AsyncWorkspaceService, WorkspaceService
+
+
+class Client(SyncClientBase):
+    @cached_property
+    def audit(self) -> AuditService:
+        return AuditService(self._transport)
+
+    @cached_property
+    def billing(self) -> BillingService:
+        return BillingService(self._transport)
+
+    @cached_property
+    def catalog(self) -> CatalogService:
+        return CatalogService(self._transport)
+
+    @cached_property
+    def certificate(self) -> CertificateService:
+        return CertificateService(self._transport)
+
+    @cached_property
+    def compute(self) -> ComputeService:
+        return ComputeService(self._transport)
+
+    @cached_property
+    def dns(self) -> DnsService:
+        return DnsService(self._transport)
+
+    @cached_property
+    def iam(self) -> IamService:
+        return IamService(self._transport)
+
+    @cached_property
+    def kms(self) -> KmsService:
+        return KmsService(self._transport)
+
+    @cached_property
+    def loadbalancer(self) -> LoadbalancerService:
+        return LoadbalancerService(self._transport)
+
+    @cached_property
+    def network(self) -> NetworkService:
+        return NetworkService(self._transport)
+
+    @cached_property
+    def quota(self) -> QuotaService:
+        return QuotaService(self._transport)
+
+    @cached_property
+    def secrets(self) -> SecretsService:
+        return SecretsService(self._transport)
+
+    @cached_property
+    def storage(self) -> StorageService:
+        return StorageService(self._transport)
+
+    @cached_property
+    def telemetry(self) -> TelemetryService:
+        return TelemetryService(self._transport)
+
+    @cached_property
+    def workspace(self) -> WorkspaceService:
+        return WorkspaceService(self._transport)
+
+
+class AsyncClient(AsyncClientBase):
+    @cached_property
+    def audit(self) -> AsyncAuditService:
+        return AsyncAuditService(self._transport)
+
+    @cached_property
+    def billing(self) -> AsyncBillingService:
+        return AsyncBillingService(self._transport)
+
+    @cached_property
+    def catalog(self) -> AsyncCatalogService:
+        return AsyncCatalogService(self._transport)
+
+    @cached_property
+    def certificate(self) -> AsyncCertificateService:
+        return AsyncCertificateService(self._transport)
+
+    @cached_property
+    def compute(self) -> AsyncComputeService:
+        return AsyncComputeService(self._transport)
+
+    @cached_property
+    def dns(self) -> AsyncDnsService:
+        return AsyncDnsService(self._transport)
+
+    @cached_property
+    def iam(self) -> AsyncIamService:
+        return AsyncIamService(self._transport)
+
+    @cached_property
+    def kms(self) -> AsyncKmsService:
+        return AsyncKmsService(self._transport)
+
+    @cached_property
+    def loadbalancer(self) -> AsyncLoadbalancerService:
+        return AsyncLoadbalancerService(self._transport)
+
+    @cached_property
+    def network(self) -> AsyncNetworkService:
+        return AsyncNetworkService(self._transport)
+
+    @cached_property
+    def quota(self) -> AsyncQuotaService:
+        return AsyncQuotaService(self._transport)
+
+    @cached_property
+    def secrets(self) -> AsyncSecretsService:
+        return AsyncSecretsService(self._transport)
+
+    @cached_property
+    def storage(self) -> AsyncStorageService:
+        return AsyncStorageService(self._transport)
+
+    @cached_property
+    def telemetry(self) -> AsyncTelemetryService:
+        return AsyncTelemetryService(self._transport)
+
+    @cached_property
+    def workspace(self) -> AsyncWorkspaceService:
+        return AsyncWorkspaceService(self._transport)

basaltic/config.py

@@ -0,0 +1,151 @@
+"""Explicit and environment-based configuration shared by all services."""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from .auth import AsyncTokenProvider, TokenProvider
+
+
+def validate_url(value: str) -> str:
+    try:
+        u = urlsplit(value)
+        valid = u.scheme in ("http", "https") and u.hostname and u.port != 0
+    except ValueError:
+        valid = False
+    if (
+        not valid
+        or u.username
+        or u.password
+        or u.query
+        or u.fragment
+        or re.search(r"[\s\x00-\x1f\x7f]", value)
+    ):
+        raise ValueError(
+            "Endpoint must be an absolute HTTP(S) URL without credentials, query or fragment."
+        )
+    return value.rstrip("/")
+
+
+def validate_token(value: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or not value.isascii()
+        or re.search(r"[\s\x00-\x1f\x7f]", value)
+    ):
+        raise ValueError("A nonempty bearer token without whitespace is required.")
+    return value
+
+
+def positive_timeout(value: float) -> float:
+    if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError("timeout must be a finite positive number of seconds.")
+    return value
+
+
+def attempt_count(value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 10:
+        raise ValueError("max_attempts must be an integer between 1 and 10.")
+    return value
+
+
+@dataclass(frozen=True, kw_only=True)
+class RequestOptions:
+    account_id: str | None = None
+    idempotency_key: str | None = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    timeout: float | None = None
+    max_attempts: int | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class Config:
+    access_key_id: str | None = field(default=None, repr=False)
+    secret_access_key: str | None = field(default=None, repr=False)
+    access_token: str | None = field(default=None, repr=False)
+    token_provider: TokenProvider | AsyncTokenProvider | None = field(default=None, repr=False)
+    anonymous: bool = False
+    region: str | None = None
+    account_id: str | None = None
+    domain: str | None = None
+    endpoints: Mapping[str, str] = field(default_factory=dict)
+    token_url: str | None = None
+    read_environment: bool = True
+    timeout: float = 30.0
+    max_attempts: int = 4
+    base_delay: float = 0.2
+    max_delay: float = 20.0
+
+    def __post_init__(self) -> None:
+        env = os.environ if self.read_environment else {}
+        for key in ("region", "account_id", "domain"):
+            if getattr(self, key) is None:
+                object.__setattr__(
+                    self,
+                    key,
+                    env.get("BASALTIC_" + key.upper(), "basaltic.sh" if key == "domain" else ""),
+                )
+        if not re.fullmatch(
+            r"(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?",
+            self.domain or "",
+        ):
+            raise ValueError("Invalid API domain.")
+        endpoints = {
+            k.removeprefix("BASALTIC_ENDPOINT_URL_").lower(): v
+            for k, v in env.items()
+            if k.startswith("BASALTIC_ENDPOINT_URL_") and v
+        }
+        endpoints.update(self.endpoints)
+        endpoints = {key: validate_url(value) for key, value in endpoints.items()}
+        object.__setattr__(self, "endpoints", MappingProxyType(endpoints))
+        explicit_keys = self.access_key_id is not None or self.secret_access_key is not None
+        if self.access_token is None:
+            object.__setattr__(
+                self, "access_token", "" if explicit_keys else env.get("BASALTIC_ACCESS_TOKEN", "")
+            )
+        for key in ("access_key_id", "secret_access_key"):
+            if getattr(self, key) is None:
+                object.__setattr__(self, key, env.get("BASALTIC_" + key.upper(), ""))
+        if (
+            not self.anonymous
+            and not self.token_provider
+            and not self.access_token
+            and not (self.access_key_id and self.secret_access_key)
+        ):
+            raise ValueError(
+                "Configure an access key pair, bearer token, token provider or explicit anonymous access."
+            )
+        if self.access_token:
+            validate_token(self.access_token)
+        positive_timeout(self.timeout)
+        attempt_count(self.max_attempts)
+        if any(not math.isfinite(v) or v < 0 for v in (self.base_delay, self.max_delay)):
+            raise ValueError("Retry delays must be finite and nonnegative.")
+
+    def endpoint(self, service: str, template: str) -> str:
+        if service in self.endpoints:
+            return self.endpoints[service]
+        if "{region}" in template and not re.fullmatch(
+            r"[a-z0-9]+(?:-[a-z0-9]+)*", self.region or ""
+        ):
+            raise ValueError(f"A valid region is required for {service}.")
+        return validate_url(
+            template.replace("basaltic.sh", self.domain or "").replace(
+                "{region}", self.region or ""
+            )
+        )
+
+
+def new_idempotency_key() -> str:
+    """Create once per logical mutation and reuse when retrying that mutation."""
+    return str(uuid4())

basaltic/errors.py

@@ -0,0 +1,73 @@
+"""Structured SDK errors; transport and OAuth failures never retain raw requests."""
+
+import re
+
+
+class BasalticError(Exception):
+    """Base class for SDK failures."""
+
+
+class ProtocolError(BasalticError):
+    pass
+
+
+class TransportError(BasalticError):
+    pass
+
+
+class RequestTimeoutError(TransportError):
+    pass
+
+
+class AuthenticationError(BasalticError):
+    def __init__(self, status_code: int = 0, error_code: str = "") -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(f"Token exchange failed (HTTP {status_code}, code {error_code}).")
+
+
+class AmbiguousReferenceError(BasalticError):
+    def __init__(self) -> None:
+        super().__init__("Reference matches multiple resources; narrow its parent scope.")
+
+
+class ApiError(BasalticError):
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        message: str,
+        request_id: str,
+        operation_id: str,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        self.request_id = request_id
+        self.operation_id = operation_id
+        self.headers = dict(headers or {})
+        super().__init__(f"{operation_id}: {message} (HTTP {status_code}, request {request_id})")
+
+    def is_not_found(self) -> bool:
+        return self.status_code in (404, 410)
+
+    def is_unauthorized(self) -> bool:
+        return self.status_code == 401
+
+    def is_quota_exceeded(self) -> bool:
+        return bool(re.search(r"(?:^|_)(?:QUOTA|LIMIT)_EXCEEDED$", self.error_code))
+
+    def is_access_denied(self) -> bool:
+        return self.status_code == 403 and not self.is_quota_exceeded()
+
+    def is_conflict(self) -> bool:
+        return self.status_code == 409
+
+    def is_invalid_input(self) -> bool:
+        return self.status_code in (400, 422)
+
+    def is_rate_limited(self) -> bool:
+        return self.status_code == 429
+
+    def is_transient(self) -> bool:
+        return self.status_code == 429 or self.status_code >= 500

basaltic/models/__init__.py

@@ -0,0 +1,17 @@
+"""Service-specific typed request and response models."""
+
+from . import audit as audit
+from . import billing as billing
+from . import catalog as catalog
+from . import certificate as certificate
+from . import compute as compute
+from . import dns as dns
+from . import iam as iam
+from . import kms as kms
+from . import loadbalancer as loadbalancer
+from . import network as network
+from . import quota as quota
+from . import secrets as secrets
+from . import storage as storage
+from . import telemetry as telemetry
+from . import workspace as workspace