nextlabs-sdk 0.2.0__py3-none-any.whl

nextlabs_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""nextlabs-sdk."""
+
+from nextlabs_sdk._auth._cloudaz_auth import CloudAzAuth as CloudAzAuth
+from nextlabs_sdk._auth._pdp_auth import PdpAuth as PdpAuth
+from nextlabs_sdk._auth._static_token_auth import StaticTokenAuth as StaticTokenAuth
+from nextlabs_sdk._auth._token_cache import (
+    CachedToken as CachedToken,
+)
+from nextlabs_sdk._auth._token_cache import (
+    FileTokenCache as FileTokenCache,
+)
+from nextlabs_sdk._auth._token_cache import (
+    NullTokenCache as NullTokenCache,
+)
+from nextlabs_sdk._auth._token_cache import (
+    TokenCache as TokenCache,
+)
+from nextlabs_sdk._cloudaz._async_client import (
+    AsyncCloudAzClient as AsyncCloudAzClient,
+)
+from nextlabs_sdk._cloudaz._client import CloudAzClient as CloudAzClient
+from nextlabs_sdk._config import HttpConfig as HttpConfig
+from nextlabs_sdk._config import RetryConfig as RetryConfig
+from nextlabs_sdk._http_transport import (
+    create_async_http_client as create_async_http_client,
+)
+from nextlabs_sdk._http_transport import (
+    create_http_client as create_http_client,
+)
+from nextlabs_sdk._pagination import AsyncPaginator as AsyncPaginator
+from nextlabs_sdk._pagination import PageResult as PageResult
+from nextlabs_sdk._pagination import SyncPaginator as SyncPaginator
+from nextlabs_sdk._pdp._async_client import AsyncPdpClient as AsyncPdpClient
+from nextlabs_sdk._pdp._client import PdpClient as PdpClient
+from nextlabs_sdk._version import __version__ as __version__

nextlabs_sdk/_auth/__init__.py

@@ -0,0 +1,2 @@
+from nextlabs_sdk._auth._cloudaz_auth import CloudAzAuth as CloudAzAuth
+from nextlabs_sdk._auth._pdp_auth import PdpAuth as PdpAuth

nextlabs_sdk/_auth/_active_account/__init__.py

@@ -0,0 +1,6 @@
+from nextlabs_sdk._auth._active_account._active_account import (
+    ActiveAccount as ActiveAccount,
+)
+from nextlabs_sdk._auth._active_account._active_account_store import (
+    ActiveAccountStore as ActiveAccountStore,
+)

nextlabs_sdk/_auth/_active_account/_active_account.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ActiveAccount:
+    """Identifiers of the cached account currently marked as active."""
+
+    base_url: str
+    username: str
+    client_id: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "base_url": self.base_url,
+            "username": self.username,
+            "client_id": self.client_id,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, object]) -> ActiveAccount:
+        base_url = payload["base_url"]
+        username = payload["username"]
+        client_id = payload["client_id"]
+        if not (
+            isinstance(base_url, str)
+            and isinstance(username, str)
+            and isinstance(client_id, str)
+        ):
+            raise ValueError("ActiveAccount fields must be strings")
+        if not (base_url and username and client_id):
+            raise ValueError("ActiveAccount fields must be non-empty")
+        return cls(base_url=base_url, username=username, client_id=client_id)

nextlabs_sdk/_auth/_active_account/_active_account_store.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from nextlabs_sdk._auth._active_account._active_account import ActiveAccount
+
+_FILE_MODE = 0o600
+_DIR_MODE = 0o700
+_FILENAME = "active_account.json"
+_PACKAGE_DIR = "nextlabs-sdk"
+
+
+def _default_path() -> Path:
+    override = os.environ.get("NEXTLABS_CACHE_DIR")
+    if override:
+        return Path(override) / _FILENAME
+
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg) / _PACKAGE_DIR / _FILENAME
+
+    return Path.home() / ".cache" / _PACKAGE_DIR / _FILENAME
+
+
+class ActiveAccountStore:
+    """JSON-backed pointer to the currently active cached account."""
+
+    def __init__(self, *, path: Path | str | None = None) -> None:
+        self._path = _default_path() if path is None else Path(path)
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def load(self) -> ActiveAccount | None:
+        if not self._path.exists():
+            return None
+        try:
+            with self._path.open("r", encoding="utf-8") as fh:
+                loaded = json.load(fh)
+        except (OSError, json.JSONDecodeError):
+            return None
+        if not isinstance(loaded, dict):
+            return None
+        try:
+            return ActiveAccount.from_dict(loaded)
+        except (KeyError, TypeError, ValueError):
+            return None
+
+    def save(self, account: ActiveAccount) -> None:
+        directory = self._path.parent
+        directory.mkdir(parents=True, exist_ok=True)
+        os.chmod(directory, _DIR_MODE)
+
+        fd, tmp_name = tempfile.mkstemp(
+            prefix=".active-",
+            suffix=".tmp",
+            dir=str(directory),
+        )
+        try:
+            self._atomic_write(fd, tmp_name, account)
+        except Exception:
+            if os.path.exists(tmp_name):
+                os.unlink(tmp_name)
+            raise
+
+    def clear(self) -> None:
+        try:
+            self._path.unlink()
+        except FileNotFoundError:
+            return
+
+    def _atomic_write(
+        self,
+        fd: int,
+        tmp_name: str,
+        account: ActiveAccount,
+    ) -> None:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(account.to_dict(), fh)
+        os.chmod(tmp_name, _FILE_MODE)
+        os.replace(tmp_name, self._path)

nextlabs_sdk/_auth/_cloudaz_auth.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Awaitable, Generator
+from typing import Callable
+
+import httpx
+
+from nextlabs_sdk._auth._refresh_token_policy import RefreshDecision, decide
+from nextlabs_sdk._auth._token_cache._cached_token import CachedToken
+from nextlabs_sdk._auth._token_cache._null_token_cache import NullTokenCache
+from nextlabs_sdk._auth._token_cache._token_cache import TokenCache
+from nextlabs_sdk._json_response import decode_json_object, require_int, require_str
+from nextlabs_sdk._logging import logger
+from nextlabs_sdk.exceptions import AuthenticationError, RefreshTokenExpiredError
+
+_EXPIRY_SAFETY_MARGIN = 60
+_OK_STATUS = 200
+_UNAUTHORIZED_STATUS = 401
+_REDIRECT_MIN_STATUS = 300
+_REDIRECT_MAX_STATUS = 399
+_SPA_FRAGMENT = "#"
+_LOCATION_HEADER = "location"
+_RELOGIN_HINT = "Run `nextlabs auth login` to re-authenticate."
+_SPA_REDIRECT_MSG = (
+    "Server redirected API call to SPA login page "
+    "(Location={location!r}) — access token was rejected. {hint}"
+)
+_HTTP_POST = "POST"
+_FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+_INITIAL_EXPIRY_AT = float(0)
+
+_MSG_LIFETIME_EXCEEDED = "Refresh token lifetime exceeded — re-login required. {hint}"
+_MSG_SERVER_REJECTED = "Refresh token rejected by server — re-login required. {hint}"
+_MSG_NO_CREDS = "No refresh token and no password available. {hint}"
+
+
+def _spa_redirect_location(response: httpx.Response) -> str:
+    for hop in response.history:
+        location = hop.headers.get(_LOCATION_HEADER, "")
+        if _SPA_FRAGMENT in location:
+            return location
+    return response.headers.get(_LOCATION_HEADER, "")
+
+
+def _is_spa_redirect(response: httpx.Response) -> bool:
+    for hop in response.history:
+        if _SPA_FRAGMENT in hop.headers.get(_LOCATION_HEADER, ""):
+            return True
+    status = response.status_code
+    if _REDIRECT_MIN_STATUS <= status <= _REDIRECT_MAX_STATUS:
+        return _SPA_FRAGMENT in response.headers.get(_LOCATION_HEADER, "")
+    return False
+
+
+def _form_headers() -> dict[str, str]:
+    return {"Content-Type": _FORM_CONTENT_TYPE}
+
+
+def _build_password_request(
+    *,
+    token_url: str,
+    username: str,
+    password: str | None,
+    client_id: str,
+) -> httpx.Request:
+    return httpx.Request(
+        method=_HTTP_POST,
+        url=token_url,
+        data={
+            "grant_type": "password",
+            "username": username,
+            "password": password,
+            "client_id": client_id,
+        },
+        headers=_form_headers(),
+    )
+
+
+def _build_refresh_request(
+    *,
+    token_url: str,
+    refresh_token: str,
+    client_id: str,
+) -> httpx.Request:
+    return httpx.Request(
+        method=_HTTP_POST,
+        url=token_url,
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+        },
+        headers=_form_headers(),
+    )
+
+
+def _raise_unless_password_available(
+    *,
+    password: str | None,
+    token_url: str,
+    message: str,
+    exc_cls: type[AuthenticationError],
+    warn: str | None,
+) -> None:
+    if password is not None:
+        return
+    if warn is not None:
+        logger.warning(warn)
+    raise exc_cls(
+        message.format(hint=_RELOGIN_HINT),
+        status_code=None,
+        response_body=None,
+        request_method=_HTTP_POST,
+        request_url=token_url,
+    )
+
+
+def _handle_refresh_failure(
+    *,
+    decision: RefreshDecision,
+    password: str | None,
+    token_url: str,
+) -> None:
+    if decision is RefreshDecision.USE_REFRESH:
+        _raise_unless_password_available(
+            password=password,
+            token_url=token_url,
+            message=_MSG_SERVER_REJECTED,
+            exc_cls=RefreshTokenExpiredError,
+            warn="cloudaz auth: refresh token rejected by server"
+            " and no password available — re-login required",
+        )
+    elif decision is RefreshDecision.KNOWN_EXPIRED:
+        logger.debug("cloudaz auth: refresh skipped (known-expired)")
+        _raise_unless_password_available(
+            password=password,
+            token_url=token_url,
+            message=_MSG_LIFETIME_EXCEEDED,
+            exc_cls=RefreshTokenExpiredError,
+            warn="cloudaz auth: refresh token expired"
+            " and no password available — re-login required",
+        )
+    else:
+        _raise_unless_password_available(
+            password=password,
+            token_url=token_url,
+            message=_MSG_NO_CREDS,
+            exc_cls=AuthenticationError,
+            warn=None,
+        )
+
+
+class CloudAzAuth(httpx.Auth):
+    """OIDC password grant auth for the CloudAz Console API.
+
+    Supports an optional pluggable :class:`TokenCache` backend. Expiry is
+    tracked as absolute UTC epoch seconds so that cached tokens survive
+    process restarts.
+
+    When ``refresh_token_lifetime`` is provided, the SDK records the
+    refresh token's absolute expiry at every successful token
+    acquisition and uses it to short-circuit re-auth once the lifetime
+    has elapsed — skipping a doomed HTTP round-trip and surfacing a
+    :class:`RefreshTokenExpiredError` (or falling back to the password
+    grant when a password is configured).
+    """
+
+    requires_request_body = False
+    requires_response_body = True
+
+    def __init__(
+        self,
+        token_url: str,
+        username: str,
+        password: str | None,
+        client_id: str,
+        *,
+        token_cache: TokenCache | None = None,
+    ) -> None:
+        self._token_url = token_url
+        self._username = username
+        self._password = password
+        self._client_id = client_id
+        self._cache: TokenCache = token_cache or NullTokenCache()
+        self._cache_key = f"{token_url}|{username}|{client_id}"
+        self._lock = threading.Lock()
+        self.refresh_token_lifetime: int | None = None
+
+        self._token: str | None = None
+        self._refresh_token: str | None = None
+        self._refresh_expires_at: float | None = None
+        self._expires_at: float = _INITIAL_EXPIRY_AT
+
+        cached = self._cache.load(self._cache_key)
+        if cached is not None:
+            self._refresh_token = cached.refresh_token
+            self._refresh_expires_at = cached.refresh_expires_at
+            if not cached.is_expired(
+                now=time.time(),
+                safety_margin=_EXPIRY_SAFETY_MARGIN,
+            ):
+                self._token = cached.access_token
+                self._expires_at = cached.expires_at
+
+    def auth_flow(
+        self,
+        request: httpx.Request,
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self._has_valid_token():
+            yield from self._reauthenticate()
+
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        response = yield request
+
+        if response.status_code == _UNAUTHORIZED_STATUS or _is_spa_redirect(response):
+            yield from self._reauthenticate()
+            request.headers["Authorization"] = f"Bearer {self._token}"
+            retried = yield request
+            if _is_spa_redirect(retried):
+                raise AuthenticationError(
+                    _SPA_REDIRECT_MSG.format(
+                        location=_spa_redirect_location(retried),
+                        hint=_RELOGIN_HINT,
+                    ),
+                    status_code=retried.status_code,
+                    response_body=None,
+                    request_method=request.method,
+                    request_url=str(request.url),
+                )
+
+    def ensure_token(
+        self,
+        send: Callable[[httpx.Request], httpx.Response],
+    ) -> None:
+        """Fetch and cache a token synchronously via a provided transport.
+
+        Intended for explicit `authenticate()` flows that need to acquire a
+        token without making a password HTTP call. No-op when a valid token
+        is already available in memory.
+        """
+        if self._has_valid_token():
+            return
+        if self._try_refresh_sync(send):
+            return
+        logger.debug("cloudaz auth: falling back to password grant")
+        response = send(
+            _build_password_request(
+                token_url=self._token_url,
+                username=self._username,
+                password=self._password,
+                client_id=self._client_id,
+            ),
+        )
+        self._parse_token_response(response)
+
+    async def ensure_token_async(
+        self,
+        send: Callable[[httpx.Request], Awaitable[httpx.Response]],
+    ) -> None:
+        """Async counterpart of :meth:`ensure_token`."""
+        if self._has_valid_token():
+            return
+        if await self._try_refresh_async(send):
+            return
+        logger.debug("cloudaz auth: falling back to password grant")
+        response = await send(
+            _build_password_request(
+                token_url=self._token_url,
+                username=self._username,
+                password=self._password,
+                client_id=self._client_id,
+            ),
+        )
+        self._parse_token_response(response)
+
+    def _refresh_decision(self) -> RefreshDecision:
+        if self._refresh_token is None:
+            return RefreshDecision.ABSENT
+        return decide(
+            refresh_token=self._refresh_token,
+            refresh_expires_at=self._refresh_expires_at,
+            now=time.time(),
+        )
+
+    def _has_valid_token(self) -> bool:
+        with self._lock:
+            return self._token is not None and time.time() < self._expires_at
+
+    def _reauthenticate(self) -> Generator[httpx.Request, httpx.Response, None]:
+        decision = self._refresh_decision()
+        if decision is RefreshDecision.USE_REFRESH:
+            logger.debug("cloudaz auth: refresh attempt starting")
+            assert self._refresh_token is not None
+            response = yield _build_refresh_request(
+                token_url=self._token_url,
+                refresh_token=self._refresh_token,
+                client_id=self._client_id,
+            )
+            if response.status_code == _OK_STATUS:
+                self._parse_token_response(response)
+                logger.debug("cloudaz auth: refresh succeeded")
+                return
+            _handle_refresh_failure(
+                decision=decision, password=self._password, token_url=self._token_url
+            )
+        else:
+            _handle_refresh_failure(
+                decision=decision, password=self._password, token_url=self._token_url
+            )
+
+        logger.debug("cloudaz auth: falling back to password grant")
+        response = yield _build_password_request(
+            token_url=self._token_url,
+            username=self._username,
+            password=self._password,
+            client_id=self._client_id,
+        )
+        self._parse_token_response(response)
+
+    def _try_refresh_sync(
+        self,
+        send: Callable[[httpx.Request], httpx.Response],
+    ) -> bool:
+        decision = self._refresh_decision()
+        if decision is RefreshDecision.USE_REFRESH:
+            logger.debug("cloudaz auth: refresh attempt starting")
+            assert self._refresh_token is not None
+            response = send(
+                _build_refresh_request(
+                    token_url=self._token_url,
+                    refresh_token=self._refresh_token,
+                    client_id=self._client_id,
+                ),
+            )
+            if response.status_code == _OK_STATUS:
+                self._parse_token_response(response)
+                logger.debug("cloudaz auth: refresh succeeded")
+                return True
+        _handle_refresh_failure(
+            decision=decision, password=self._password, token_url=self._token_url
+        )
+        return False
+
+    async def _try_refresh_async(
+        self,
+        send: Callable[[httpx.Request], Awaitable[httpx.Response]],
+    ) -> bool:
+        decision = self._refresh_decision()
+        if decision is RefreshDecision.USE_REFRESH:
+            logger.debug("cloudaz auth: refresh attempt starting")
+            assert self._refresh_token is not None
+            response = await send(
+                _build_refresh_request(
+                    token_url=self._token_url,
+                    refresh_token=self._refresh_token,
+                    client_id=self._client_id,
+                ),
+            )
+            if response.status_code == _OK_STATUS:
+                self._parse_token_response(response)
+                logger.debug("cloudaz auth: refresh succeeded")
+                return True
+        _handle_refresh_failure(
+            decision=decision, password=self._password, token_url=self._token_url
+        )
+        return False
+
+    def _parse_token_response(
+        self,
+        response: httpx.Response,
+    ) -> None:
+        if response.status_code != _OK_STATUS:
+            raise AuthenticationError(
+                f"Token acquisition failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+                response_body=response.text,
+                request_method=_HTTP_POST,
+                request_url=self._token_url,
+            )
+
+        body = decode_json_object(
+            response,
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        expires_in = require_int(
+            body,
+            "expires_in",
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        now = time.time()
+        expires_at = now + expires_in - _EXPIRY_SAFETY_MARGIN
+        access_token = require_str(
+            body,
+            "access_token",
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        refresh_token_raw = body.get("refresh_token")
+        refresh_token = (
+            refresh_token_raw
+            if isinstance(refresh_token_raw, str)
+            else self._refresh_token
+        )
+        token_type_raw = body.get("token_type", "bearer")
+        token_type = token_type_raw if isinstance(token_type_raw, str) else "bearer"
+        scope_raw = body.get("scope")
+        scope = scope_raw if isinstance(scope_raw, str) else None
+        refresh_expires_at = (
+            None
+            if self.refresh_token_lifetime is None
+            else now + self.refresh_token_lifetime
+        )
+
+        with self._lock:
+            self._token = access_token
+            self._refresh_token = refresh_token
+            self._expires_at = expires_at
+            self._refresh_expires_at = refresh_expires_at
+
+        self._cache.save(
+            self._cache_key,
+            CachedToken(
+                access_token=access_token,
+                refresh_token=refresh_token,
+                expires_at=expires_at,
+                token_type=token_type,
+                scope=scope,
+                refresh_expires_at=refresh_expires_at,
+            ),
+        )

nextlabs_sdk/_auth/_pdp_auth.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Generator
+
+import httpx
+
+from nextlabs_sdk._json_response import decode_json_object, require_int, require_str
+from nextlabs_sdk.exceptions import AuthenticationError
+
+_EXPIRY_SAFETY_MARGIN = 60
+_OK_STATUS = 200
+_UNAUTHORIZED_STATUS = 401
+
+
+class PdpAuth(httpx.Auth):
+    """OAuth2 client credentials auth for the PDP REST API."""
+
+    requires_request_body = False
+    requires_response_body = True
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+    ) -> None:
+        self._token_url = token_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._token: str | None = None
+        self._token_expiry: float = 0
+        self._lock = threading.Lock()
+
+    def auth_flow(
+        self,
+        request: httpx.Request,
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self._has_valid_token():
+            token_response = yield self._build_token_request()
+            self._parse_token_response(token_response)
+
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        response = yield request
+
+        if response.status_code == _UNAUTHORIZED_STATUS:
+            token_response = yield self._build_token_request()
+            self._parse_token_response(token_response)
+            request.headers["Authorization"] = f"Bearer {self._token}"
+            yield request
+
+    def _has_valid_token(self) -> bool:
+        with self._lock:
+            return self._token is not None and time.monotonic() < self._token_expiry
+
+    def _build_token_request(self) -> httpx.Request:
+        return httpx.Request(
+            method="POST",
+            url=self._token_url,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+            },
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+        )
+
+    def _parse_token_response(
+        self,
+        response: httpx.Response,
+    ) -> None:
+        if response.status_code != _OK_STATUS:
+            raise AuthenticationError(
+                f"Token acquisition failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+                response_body=response.text,
+                request_method="POST",
+                request_url=self._token_url,
+            )
+
+        body = decode_json_object(
+            response,
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        access_token = require_str(
+            body,
+            "access_token",
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        expires_in = require_int(
+            body,
+            "expires_in",
+            error_cls=AuthenticationError,
+            context=" in token response",
+        )
+        with self._lock:
+            self._token = access_token
+            self._token_expiry = time.monotonic() + expires_in - _EXPIRY_SAFETY_MARGIN