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

basaltic/__init__.py

@@ -0,0 +1,26 @@
+"""Official Basaltic Python SDK."""
+
+from ._common import AsyncBinaryBody as AsyncBinaryBody
+from ._common import BinaryBody as BinaryBody
+from ._common import WebSocketConnection as WebSocketConnection
+from ._version import __version__ as __version__
+from .auth import AsyncClientCredentials as AsyncClientCredentials
+from .auth import AsyncStaticToken as AsyncStaticToken
+from .auth import AsyncTokenProvider as AsyncTokenProvider
+from .auth import ClientCredentials as ClientCredentials
+from .auth import StaticToken as StaticToken
+from .auth import TokenProvider as TokenProvider
+from .client import AsyncClient as AsyncClient
+from .client import Client as Client
+from .config import Config as Config
+from .config import RequestOptions as RequestOptions
+from .config import new_idempotency_key as new_idempotency_key
+from .errors import AmbiguousReferenceError as AmbiguousReferenceError
+from .errors import ApiError as ApiError
+from .errors import AuthenticationError as AuthenticationError
+from .errors import BasalticError as BasalticError
+from .errors import ProtocolError as ProtocolError
+from .errors import RequestTimeoutError as RequestTimeoutError
+from .errors import TransportError as TransportError
+from .response import ApiResponse as ApiResponse
+from .response import Page as Page

basaltic/_client.py

@@ -0,0 +1,136 @@
+"""HTTP client lifetime and shared credential configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Self, TypedDict, Unpack, cast
+
+import httpx
+
+from ._transport import AsyncTransport, SyncTransport
+from .auth import (
+    AsyncClientCredentials,
+    AsyncStaticToken,
+    AsyncTokenProvider,
+    ClientCredentials,
+    StaticToken,
+    TokenProvider,
+)
+from .config import Config
+
+
+class ClientOptions(TypedDict, total=False):
+    access_key_id: str
+    secret_access_key: str
+    access_token: str
+    anonymous: bool
+    region: str
+    account_id: str
+    domain: str
+    endpoints: Mapping[str, str]
+    token_url: str
+    read_environment: bool
+    timeout: float
+    max_attempts: int
+    base_delay: float
+    max_delay: float
+
+
+class SyncClientBase:
+    def __init__(
+        self,
+        config: Config | None = None,
+        *,
+        http_client: httpx.Client | None = None,
+        token_provider: TokenProvider | None = None,
+        **options: Unpack[ClientOptions],
+    ) -> None:
+        if config is not None and (options or token_provider is not None):
+            raise ValueError("Pass either Config or configuration keywords.")
+        self.config = config or Config(token_provider=token_provider, **options)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client(trust_env=False)
+        provider = cast(TokenProvider | None, self.config.token_provider)
+        if self.config.anonymous:
+            provider = None
+        elif provider is None:
+            if self.config.access_token:
+                provider = StaticToken(self.config.access_token)
+            else:
+                provider = ClientCredentials(
+                    access_key_id=self.config.access_key_id or "",
+                    secret_access_key=self.config.secret_access_key or "",
+                    token_url=self.config.token_url
+                    or self.config.endpoint("iam", "https://iam.basaltic.sh") + "/v1/oauth/token",
+                    http_client=self._http,
+                    timeout=self.config.timeout,
+                )
+        self._transport = SyncTransport(self.config, self._http, provider)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncClientBase:
+    def __init__(
+        self,
+        config: Config | None = None,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        token_provider: AsyncTokenProvider | None = None,
+        **options: Unpack[ClientOptions],
+    ) -> None:
+        if config is not None and (options or token_provider is not None):
+            raise ValueError("Pass either Config or configuration keywords.")
+        self.config = config or Config(token_provider=token_provider, **options)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient(trust_env=False)
+        provider = cast(AsyncTokenProvider | None, self.config.token_provider)
+        self._owns_provider = False
+        if self.config.anonymous:
+            provider = None
+        elif provider is None:
+            if self.config.access_token:
+                provider = AsyncStaticToken(self.config.access_token)
+            else:
+                provider = AsyncClientCredentials(
+                    access_key_id=self.config.access_key_id or "",
+                    secret_access_key=self.config.secret_access_key or "",
+                    token_url=self.config.token_url
+                    or self.config.endpoint("iam", "https://iam.basaltic.sh") + "/v1/oauth/token",
+                    http_client=self._http,
+                    timeout=self.config.timeout,
+                )
+                self._owns_provider = True
+        self._transport = AsyncTransport(self.config, self._http, provider)
+
+    async def aclose(self) -> None:
+        provider = self._transport.provider
+        if self._owns_provider and isinstance(provider, AsyncClientCredentials):
+            await provider.aclose()
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

basaltic/_common.py

@@ -0,0 +1,284 @@
+"""Shared wire preparation and response decisions for both HTTP drivers."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import time
+from collections.abc import AsyncIterable, Iterable, Mapping
+from dataclasses import dataclass
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, TypeAlias
+from urllib.parse import quote, urlsplit, urlunsplit
+
+import httpx
+
+from ._version import __version__
+from .config import Config, RequestOptions, attempt_count, positive_timeout
+from .errors import ApiError, ProtocolError
+from .response import ApiResponse, Page
+
+BinaryBody: TypeAlias = bytes | bytearray | memoryview | Iterable[bytes]
+AsyncBinaryBody: TypeAlias = bytes | bytearray | memoryview | AsyncIterable[bytes]
+
+
+class Unset:
+    """Distinguishes an omitted optional body from explicit JSON null."""
+
+
+UNSET = Unset()
+
+
+@dataclass(frozen=True)
+class WebSocketConnection:
+    url: str
+    headers: Mapping[str, str]
+
+
+@dataclass(frozen=True)
+class Operation:
+    id: str
+    method: str
+    path: str
+    authenticated: bool
+    requiredQuery: tuple[str, ...] | list[str]
+    requiredHeaders: tuple[str, ...] | list[str]
+    queryEncoding: Mapping[str, Mapping[str, object]]
+    bodyRequired: bool
+    contentType: str
+    accept: str
+    itemsKey: str = ""
+
+
+def encode_query(
+    values: Mapping[str, object], encodings: Mapping[str, Mapping[str, object]] | None = None
+) -> str:
+    def scalar(value: object) -> str:
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, float) and not math.isfinite(value):
+            raise ValueError("Query values must be finite.")
+        if not isinstance(value, (str, int, float)):
+            raise TypeError("Query values must be scalars or lists of scalars.")
+        return str(value)
+
+    pairs: list[str] = []
+    for key, value in values.items():
+        if value is None or isinstance(value, Unset):
+            continue
+        prefix = quote(key, safe="") + "="
+        if isinstance(value, (list, tuple)):
+            items = [scalar(item) for item in value]
+            encoding = (encodings or {}).get(key, {})
+            if encoding.get("explode", True):
+                pairs.extend(prefix + quote(item, safe="") for item in items)
+            else:
+                separator = {"spaceDelimited": " ", "pipeDelimited": "|"}.get(
+                    str(encoding.get("style")), ","
+                )
+                pairs.append(prefix + quote(separator.join(items), safe=""))
+        else:
+            pairs.append(prefix + quote(scalar(value), safe=""))
+    return "&".join(pairs)
+
+
+@dataclass
+class Prepared:
+    operation: Operation
+    url: str
+    headers: dict[str, str]
+    body: Any
+    streaming: bool
+    max_attempts: int
+    timeout: float
+    repeatable: bool
+
+    def request(self, token: str) -> httpx.Request:
+        headers = dict(self.headers)
+        if token:
+            headers["Authorization"] = "Bearer " + token
+        return httpx.Request(
+            self.operation.method,
+            self.url,
+            headers=headers,
+            content=self.body,
+            extensions={"timeout": httpx.Timeout(self.timeout).as_dict()},
+        )
+
+    def websocket(self, token: str) -> WebSocketConnection:
+        headers = dict(self.headers)
+        if token:
+            headers["Authorization"] = "Bearer " + token
+        u = urlsplit(self.url)
+        return WebSocketConnection(
+            urlunsplit(("wss" if u.scheme == "https" else "ws", u.netloc, u.path, u.query, "")),
+            headers,
+        )
+
+
+_RESERVED = {
+    "authorization",
+    "host",
+    "cookie",
+    "content-length",
+    "content-type",
+    "accept",
+    "user-agent",
+    "x-account-id",
+    "idempotency-key",
+}
+
+
+def prepare(
+    config: Config,
+    service: str,
+    endpoint: str,
+    operation: Operation,
+    path: Mapping[str, str],
+    body: object,
+    query: Mapping[str, object] | None,
+    options: RequestOptions | None,
+    *,
+    asynchronous: bool = False,
+) -> Prepared:
+    opts = options or RequestOptions()
+    values = query or {}
+    if operation.bodyRequired and (isinstance(body, Unset) or body is None):
+        raise ValueError(f"{operation.id}: request body is required.")
+    for key in operation.requiredQuery:
+        if values.get(key) is None:
+            raise ValueError(f"{operation.id}: missing required query parameter {key}.")
+
+    def replace(match: re.Match[str]) -> str:
+        value = path.get(match[1], "")
+        if not isinstance(value, str) or value in ("", ".", ".."):
+            raise ValueError(f"{operation.id}: invalid path parameter {match[1]}.")
+        return quote(value, safe="")
+
+    route = re.sub(r"\{([^}]+)\}", replace, operation.path)
+    qs = encode_query(values, operation.queryEncoding)
+    url = config.endpoint(service, endpoint) + route + ("?" + qs if qs else "")
+    headers = httpx.Headers(
+        {"Accept": operation.accept, "User-Agent": f"basaltic-python/{__version__}"}
+    )
+    account = opts.account_id if opts.account_id is not None else config.account_id
+    if account:
+        headers["X-Account-Id"] = account
+    if opts.idempotency_key is not None:
+        if not opts.idempotency_key.strip():
+            raise ValueError("idempotency_key must not be empty.")
+        headers["Idempotency-Key"] = opts.idempotency_key
+    for key, value in opts.headers.items():
+        if key.lower() in _RESERVED:
+            raise ValueError(f"Cannot override managed header {key}.")
+        if re.search(r"[\r\n\x00]", key + value):
+            raise ValueError("Invalid HTTP header.")
+        headers[key] = value
+    for key, value in headers.items():
+        if re.search(r"[\x00-\x1f\x7f]", key + value):
+            raise ValueError("Invalid HTTP header.")
+    for key in operation.requiredHeaders:
+        if not headers.get(key):
+            raise ValueError(f"{operation.id}: missing required header {key}.")
+    content: object = None
+    streaming = False
+    if not isinstance(body, Unset):
+        if operation.contentType == "application/json":
+            content = json.dumps(
+                body, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+            ).encode()
+        elif operation.contentType == "application/x-www-form-urlencoded":
+            if not isinstance(body, Mapping):
+                raise TypeError("Form body must be a mapping.")
+            content = encode_query(body).encode()
+        elif isinstance(body, (bytes, bytearray, memoryview)):
+            content = bytes(body)
+        elif isinstance(body, str):
+            content = body.encode()
+        elif not isinstance(body, Mapping) and isinstance(
+            body, AsyncIterable if asynchronous else Iterable
+        ):
+            content, streaming = body, True
+        else:
+            raise TypeError("Binary body must be bytes or a matching sync/async byte iterable.")
+        if operation.contentType:
+            headers["Content-Type"] = operation.contentType
+    limit = attempt_count(
+        opts.max_attempts if opts.max_attempts is not None else config.max_attempts
+    )
+    return Prepared(
+        operation,
+        url,
+        dict(headers),
+        content,
+        streaming,
+        1 if streaming else limit,
+        positive_timeout(opts.timeout if opts.timeout is not None else config.timeout),
+        operation.method in ("GET", "HEAD", "OPTIONS", "PUT", "DELETE")
+        or opts.idempotency_key is not None,
+    )
+
+
+def backoff(config: Config, attempt: int, random_value: float) -> float:
+    if not math.isfinite(random_value):
+        raise ValueError("Random source must return a finite number.")
+    return min(1, max(0, random_value)) * min(
+        config.max_delay, float(config.base_delay * 2 ** (attempt - 1))
+    )
+
+
+def retry_delay(
+    config: Config, attempt: int, value: str | None, random_value: float, now: float | None = None
+) -> float | None:
+    if not value:
+        return backoff(config, attempt, random_value)
+    parsed = 0.0
+    try:
+        if value.isdigit():
+            parsed = float(value)
+        else:
+            date = parsedate_to_datetime(value)
+            if date.tzinfo is None:
+                date = date.replace(tzinfo=timezone.utc)
+            parsed = date.timestamp() - (time.time() if now is None else now)
+    except (ValueError, OverflowError, TypeError):
+        return backoff(config, attempt, random_value)
+    return max(0, parsed) if parsed <= config.max_delay else None
+
+
+def api_error(response: httpx.Response, raw: bytes, operation_id: str) -> ApiError:
+    data: object = None
+    try:
+        data = json.loads(raw)
+    except (ValueError, UnicodeDecodeError):
+        pass
+    error = data.get("error", {}) if isinstance(data, dict) else {}
+    if not isinstance(error, dict):
+        error = {}
+    code, message, request_id = error.get("code"), error.get("message"), error.get("request_id")
+    return ApiError(
+        response.status_code,
+        code if isinstance(code, str) else "",
+        message if isinstance(message, str) else "Unexpected API response",
+        request_id if isinstance(request_id, str) else response.headers.get("X-Request-Id", ""),
+        operation_id,
+        dict(response.headers),
+    )
+
+
+def decoded(response: httpx.Response, raw: bytes, op: Operation, kind: str) -> object:
+    data: object = None
+    valid = True
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except (ValueError, UnicodeDecodeError):
+        valid = False
+    if not valid or not isinstance(data, (dict, list)):
+        raise ProtocolError(f"{op.id}: expected a JSON object or array.")
+    if kind == "page":
+        page: Page[Any, Any] = Page(data, response, op.itemsKey)
+        _ = page.items
+        return page
+    return ApiResponse(data, response)

basaltic/_transport.py

@@ -0,0 +1,196 @@
+"""HTTP drivers. Shared preparation keeps synchronous and asyncio semantics aligned."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+import httpx
+
+from ._common import UNSET, Operation, api_error, backoff, decoded, prepare, retry_delay
+from .auth import AsyncTokenProvider, TokenProvider
+from .config import Config, RequestOptions, validate_token
+from .errors import RequestTimeoutError, TransportError
+
+
+class SyncTransport:
+    def __init__(self, config: Config, http: httpx.Client, provider: TokenProvider | None) -> None:
+        self.config, self.http, self.provider = config, http, provider
+        self.sleep: Callable[[float], None] = time.sleep
+        self.random: Callable[[], float] = random.random
+
+    def _token(self, authenticated: bool) -> str:
+        if not authenticated:
+            return ""
+        if self.provider is None:
+            raise ValueError("Anonymous access cannot call an authenticated operation.")
+        return validate_token(self.provider.get_token())
+
+    def request(
+        self,
+        service: str,
+        endpoint: str,
+        op: Operation,
+        kind: str,
+        path: Mapping[str, str],
+        body: object = UNSET,
+        query: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        prepared = prepare(self.config, service, endpoint, op, path, body, query, options)
+        if kind == "websocket":
+            return prepared.websocket(self._token(op.authenticated))
+        refreshed = False
+        for attempt in range(1, prepared.max_attempts + 1):
+            response: httpx.Response | None = None
+            returned_stream = False
+            delay: float | None = None
+            failure: TransportError | None = None
+            try:
+                token = self._token(op.authenticated)
+                response = self.http.send(
+                    prepared.request(token), auth=None, stream=True, follow_redirects=False
+                )
+                if response.is_success:
+                    if kind == "binary":
+                        returned_stream = True
+                        return response
+                    if kind == "discard":
+                        return None
+                    return decoded(response, response.read(), op, kind)
+                invalidate = getattr(self.provider, "invalidate", None)
+                if (
+                    response.status_code == 401
+                    and op.authenticated
+                    and not refreshed
+                    and attempt < prepared.max_attempts
+                    and callable(invalidate)
+                ):
+                    invalidate(token)
+                    refreshed, delay = True, 0.0
+                elif (
+                    prepared.repeatable
+                    and attempt < prepared.max_attempts
+                    and response.status_code in (429, 500, 502, 503, 504)
+                ):
+                    delay = retry_delay(
+                        self.config, attempt, response.headers.get("Retry-After"), self.random()
+                    )
+                if delay is None:
+                    raw = bytearray()
+                    for chunk in response.iter_bytes():
+                        raw.extend(chunk[: 1048576 - len(raw)])
+                        if len(raw) >= 1048576:
+                            break
+                    raise api_error(response, bytes(raw), op.id)
+            except httpx.HTTPError as error:
+                failure = (
+                    RequestTimeoutError(f"{op.id}: HTTP timeout.")
+                    if isinstance(error, httpx.TimeoutException)
+                    else TransportError(f"{op.id}: HTTP transport failed.")
+                )
+            finally:
+                if response is not None and not returned_stream:
+                    response.close()
+            # Raise outside the HTTP exception handler so no credential-bearing
+            # request or exception survives through __context__ or __cause__.
+            if failure is not None:
+                if not prepared.repeatable or attempt == prepared.max_attempts:
+                    raise failure
+                delay = backoff(self.config, attempt, self.random())
+            self.sleep(delay or 0.0)
+        raise TransportError("Request attempts exhausted.")
+
+
+class AsyncTransport:
+    def __init__(
+        self, config: Config, http: httpx.AsyncClient, provider: AsyncTokenProvider | None
+    ) -> None:
+        self.config, self.http, self.provider = config, http, provider
+        self.sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
+        self.random: Callable[[], float] = random.random
+
+    async def _token(self, authenticated: bool) -> str:
+        if not authenticated:
+            return ""
+        if self.provider is None:
+            raise ValueError("Anonymous access cannot call an authenticated operation.")
+        return validate_token(await self.provider.get_token())
+
+    async def request(
+        self,
+        service: str,
+        endpoint: str,
+        op: Operation,
+        kind: str,
+        path: Mapping[str, str],
+        body: object = UNSET,
+        query: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        prepared = prepare(
+            self.config, service, endpoint, op, path, body, query, options, asynchronous=True
+        )
+        if kind == "websocket":
+            return prepared.websocket(await self._token(op.authenticated))
+        refreshed = False
+        for attempt in range(1, prepared.max_attempts + 1):
+            response: httpx.Response | None = None
+            returned_stream = False
+            delay: float | None = None
+            failure: TransportError | None = None
+            try:
+                token = await self._token(op.authenticated)
+                response = await self.http.send(
+                    prepared.request(token), auth=None, stream=True, follow_redirects=False
+                )
+                if response.is_success:
+                    if kind == "binary":
+                        returned_stream = True
+                        return response
+                    if kind == "discard":
+                        return None
+                    return decoded(response, await response.aread(), op, kind)
+                invalidate = getattr(self.provider, "invalidate", None)
+                if (
+                    response.status_code == 401
+                    and op.authenticated
+                    and not refreshed
+                    and attempt < prepared.max_attempts
+                    and callable(invalidate)
+                ):
+                    invalidate(token)
+                    refreshed, delay = True, 0.0
+                elif (
+                    prepared.repeatable
+                    and attempt < prepared.max_attempts
+                    and response.status_code in (429, 500, 502, 503, 504)
+                ):
+                    delay = retry_delay(
+                        self.config, attempt, response.headers.get("Retry-After"), self.random()
+                    )
+                if delay is None:
+                    raw = bytearray()
+                    async for chunk in response.aiter_bytes():
+                        raw.extend(chunk[: 1048576 - len(raw)])
+                        if len(raw) >= 1048576:
+                            break
+                    raise api_error(response, bytes(raw), op.id)
+            except httpx.HTTPError as error:
+                failure = (
+                    RequestTimeoutError(f"{op.id}: HTTP timeout.")
+                    if isinstance(error, httpx.TimeoutException)
+                    else TransportError(f"{op.id}: HTTP transport failed.")
+                )
+            finally:
+                if response is not None and not returned_stream:
+                    await response.aclose()
+            if failure is not None:
+                if not prepared.repeatable or attempt == prepared.max_attempts:
+                    raise failure
+                delay = backoff(self.config, attempt, self.random())
+            await self.sleep(delay or 0.0)
+        raise TransportError("Request attempts exhausted.")

basaltic/_version.py

@@ -0,0 +1,3 @@
+"""Basaltic SDK version."""
+
+__version__ = "0.1.1"