termix-sdk 0.1.0__py3-none-any.whl

termix_sdk/__init__.py

@@ -0,0 +1,57 @@
+"""Python client SDK for the Termix REST API.
+
+See docs/sdk-plan.md for the full design (this file's public surface grows
+as tools/sdk-gen generates resources on top of the core in this module).
+"""
+
+from ._async_client import AsyncTermixClient
+from ._auth import AsyncPendingTOTP, PendingTOTP
+from ._client import TermixClient
+from ._error import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    DataLockedError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    SessionExpiredError,
+    TermixError,
+    TOTPRequiredError,
+)
+from ._object import TermixObject
+from ._request_options import RequestOptions
+from ._response import SSEEvent, TermixResponse, TermixStreamResponse
+from ._session import SessionHandle, async_ssh_session, ssh_session
+from ._version import SPEC_VERSION, __version__
+
+__all__ = [
+    "__version__",
+    "SPEC_VERSION",
+    "TermixClient",
+    "AsyncTermixClient",
+    "PendingTOTP",
+    "AsyncPendingTOTP",
+    "TermixObject",
+    "TermixResponse",
+    "TermixStreamResponse",
+    "SSEEvent",
+    "RequestOptions",
+    "SessionHandle",
+    "ssh_session",
+    "async_ssh_session",
+    "TermixError",
+    "APIConnectionError",
+    "APIStatusError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "TOTPRequiredError",
+    "SessionExpiredError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "DataLockedError",
+    "ServerError",
+]

termix_sdk/_api_requestor.py

@@ -0,0 +1,357 @@
+# Adapted from stripe-python (stripe/_api_requestor.py), MIT License,
+# Copyright (c) 2010-2018 Stripe. See NOTICE for the full license text.
+"""Builds and sends one API call: resolves which service's base URL to hit,
+attaches auth, serializes the body, and turns a non-2xx response into the
+right `TermixError` subclass.
+
+Diverges from stripe's requestor in the ways docs/sdk-plan.md calls out:
+no form-encoding (`_encode.py` doesn't exist here — bodies are plain JSON
+or httpx-native multipart), no idempotency keys, no API-version header,
+and URL resolution goes through `ClientOptions.base_url_for(service)`
+instead of a single fixed API base.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any
+from urllib.parse import urljoin
+
+from . import _util
+from ._client_options import ClientOptions
+from ._error import APIConnectionError, error_for_status
+from ._http_client import (
+    RETRIABLE_STATUS_CODES,
+    AsyncHTTPClient,
+    AsyncHTTPXClient,
+    HTTPClient,
+    HTTPXClient,
+    ShouldRetry,
+)
+from ._request_options import RequestOptions, request_headers
+from ._response import SSEEvent, TermixResponse, TermixStreamResponse
+from ._sse import aiter_sse_events, iter_sse_events
+
+USER_AGENT = "termix-sdk-python"
+
+
+def _should_retry(method: str) -> ShouldRetry:
+    """GET/HEAD are safe to retry on a retryable status too; other verbs
+    only retry on a connection failure (the request never reached the
+    server, so nothing has happened yet) — retrying a POST after a
+    completed-but-slow-to-answer request could double an action like
+    `POST /fleets/{id}/execute`.
+    """
+    method = method.upper()
+
+    def predicate(_num_retries: int, status: int | None, _headers: Mapping[str, str]) -> bool:
+        if status is None:
+            return True  # connection failure: always safe to retry
+        if method in ("GET", "HEAD"):
+            return status in RETRIABLE_STATUS_CODES
+        return False
+
+    return predicate
+
+
+class APIRequestor:
+    def __init__(self, options: ClientOptions, http_client: HTTPClient | None = None) -> None:
+        self._options = options
+        self._http_client = http_client or HTTPXClient(
+            verify=options.verify, timeout=options.timeout
+        )
+
+    def close(self) -> None:
+        self._http_client.close()
+
+    def _url_for(self, service: str | None, path: str) -> str:
+        base = self._options.base_url_for(service)
+        return urljoin(base + "/", path.lstrip("/"))
+
+    def _headers(self, options: RequestOptions | None) -> dict:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        bearer_token = self._options.bearer_token
+        if bearer_token is not None:
+            headers["Authorization"] = f"Bearer {bearer_token}"
+        headers.update(self._options.default_headers)
+        headers.update(request_headers(options))
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        files: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> TermixResponse | None:
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        timeout = (options or {}).get("timeout", self._options.timeout)
+        max_retries = (options or {}).get("max_network_retries", self._options.max_network_retries)
+
+        _util.log_debug("Sending request", method=method, url=url)
+        content, status_code, resp_headers = self._http_client.request_with_retries(
+            method,
+            url,
+            headers=headers,
+            params=query,
+            json=json_body if files is None else None,
+            data=json_body if files is not None else None,
+            files=files,
+            timeout=timeout,
+            max_retries=max_retries,
+            should_retry=_should_retry(method),
+        )
+        return self._interpret_response(status_code, content, resp_headers)
+
+    def request_stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        options: RequestOptions | None = None,
+    ) -> TermixStreamResponse:
+        """For `application/octet-stream` responses (file downloads). Never
+        retried — see `HTTPClient.request_stream`.
+        """
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        timeout = (options or {}).get("timeout", self._options.timeout)
+
+        iterator, status_code, resp_headers = self._http_client.request_stream(
+            method, url, headers=headers, params=query, json=json_body, timeout=timeout
+        )
+        if status_code >= 400:
+            body = b"".join(iterator)
+            self._interpret_response(status_code, body, resp_headers)  # raises
+        return TermixStreamResponse(iterator, status_code, resp_headers)
+
+    def request_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        options: RequestOptions | None = None,
+    ) -> Iterator[SSEEvent]:
+        """For the 3 `text/event-stream` endpoints (docs/sdk-plan.md
+        section 6, item 2 / `_sse.py`). Never retried, same as
+        `request_stream` — a partially-streamed connection can't be
+        safely replayed.
+        """
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        headers["Accept"] = "text/event-stream"
+        timeout = (options or {}).get("timeout", self._options.timeout)
+
+        iterator, status_code, resp_headers = self._http_client.request_stream(
+            method, url, headers=headers, params=query, json=json_body, timeout=timeout
+        )
+        if status_code >= 400:
+            body = b"".join(iterator)
+            self._interpret_response(status_code, body, resp_headers)  # raises
+        return iter_sse_events(iterator)
+
+    def _interpret_response(
+        self,
+        status_code: int,
+        content: bytes,
+        headers: Mapping[str, str],
+    ) -> TermixResponse | None:
+        if status_code == 204 or not content:
+            if status_code >= 400:
+                self._raise_for_status(status_code, {}, content, headers)
+            return None
+
+        content_type = headers.get("content-type", "")
+        if "application/json" not in content_type:
+            # A handful of endpoints (e.g. RSS/health text, some error
+            # fallbacks) answer without a JSON content-type even on success.
+            # We still try to parse — Termix's own error middleware always
+            # sends JSON regardless of what a route declares — and fall
+            # back to the raw text if that fails.
+            try:
+                data = _json.loads(content)
+            except ValueError:
+                if status_code >= 400:
+                    self._raise_for_status(status_code, {}, content, headers)
+                return TermixResponse(content, None, status_code, headers)
+        else:
+            try:
+                data = _json.loads(content)
+            except ValueError as exc:
+                raise APIConnectionError(
+                    f"Termix returned a response with an "
+                    f"application/json content-type that wasn't valid "
+                    f"JSON: {exc}"
+                ) from exc
+
+        if status_code >= 400:
+            body = data if isinstance(data, dict) else {}
+            self._raise_for_status(status_code, body, content, headers)
+
+        return TermixResponse(content, data, status_code, headers)
+
+    def _raise_for_status(
+        self,
+        status_code: int,
+        body: dict,
+        raw_content: bytes,
+        headers: Mapping[str, str],
+    ) -> None:
+        message = body.get("error") if isinstance(body.get("error"), str) else None
+        if message is None:
+            message = f"Termix API returned status {status_code} with no error message"
+        code = body.get("code") if isinstance(body.get("code"), str) else None
+        raise error_for_status(
+            status_code,
+            message=message,
+            code=code,
+            body=body,
+            http_body=raw_content.decode("utf-8", errors="replace") if raw_content else None,
+            headers=dict(headers),
+        )
+
+
+class AsyncAPIRequestor:
+    """Async mirror of `APIRequestor`, used by `AsyncTermixClient`. Response
+    interpretation and error-raising are pure functions of
+    (status, content, headers) with nothing async about them, so they're
+    delegated to a plain `APIRequestor` instance instead of duplicating
+    that logic.
+    """
+
+    def __init__(self, options: ClientOptions, http_client: AsyncHTTPClient | None = None) -> None:
+        self._http_client = http_client or AsyncHTTPXClient(
+            verify=options.verify, timeout=options.timeout
+        )
+        self._sync_delegate = APIRequestor(options, http_client=_NullHTTPClient())
+
+    @property
+    def _options(self) -> ClientOptions:
+        # `self._sync_delegate._options` is the single source of truth —
+        # `_auth.py` swaps in a freshly-authenticated ClientOptions after
+        # login/TOTP by assigning `requestor._options = ...`, and that has
+        # to reach `_headers()`/`_url_for()` below, which read through the
+        # delegate. A plain instance attribute here would silently keep
+        # pointing at the pre-login (anonymous) options instead.
+        return self._sync_delegate._options
+
+    @_options.setter
+    def _options(self, value: ClientOptions) -> None:
+        self._sync_delegate._options = value
+
+    async def close(self) -> None:
+        await self._http_client.close()
+
+    def _url_for(self, service: str | None, path: str) -> str:
+        return self._sync_delegate._url_for(service, path)
+
+    def _headers(self, options: RequestOptions | None) -> dict:
+        return self._sync_delegate._headers(options)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        files: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> TermixResponse | None:
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        timeout = (options or {}).get("timeout", self._options.timeout)
+        max_retries = (options or {}).get("max_network_retries", self._options.max_network_retries)
+
+        _util.log_debug("Sending request", method=method, url=url)
+        content, status_code, resp_headers = await self._http_client.request_with_retries(
+            method,
+            url,
+            headers=headers,
+            params=query,
+            json=json_body if files is None else None,
+            data=json_body if files is not None else None,
+            files=files,
+            timeout=timeout,
+            max_retries=max_retries,
+            should_retry=_should_retry(method),
+        )
+        return self._sync_delegate._interpret_response(status_code, content, resp_headers)
+
+    async def request_stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        options: RequestOptions | None = None,
+    ):
+        from ._response import AsyncTermixStreamResponse
+
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        timeout = (options or {}).get("timeout", self._options.timeout)
+
+        aiterator, status_code, resp_headers = await self._http_client.request_stream(
+            method, url, headers=headers, params=query, json=json_body, timeout=timeout
+        )
+        if status_code >= 400:
+            chunks = [chunk async for chunk in aiterator]
+            body = b"".join(chunks)
+            self._sync_delegate._interpret_response(status_code, body, resp_headers)  # raises
+        return AsyncTermixStreamResponse(aiterator, status_code, resp_headers)
+
+    async def request_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        options: RequestOptions | None = None,
+    ) -> AsyncIterator[SSEEvent]:
+        """Async mirror of `APIRequestor.request_sse()` — see its docstring."""
+        url = self._url_for(service, path)
+        headers = self._headers(options)
+        headers["Accept"] = "text/event-stream"
+        timeout = (options or {}).get("timeout", self._options.timeout)
+
+        aiterator, status_code, resp_headers = await self._http_client.request_stream(
+            method, url, headers=headers, params=query, json=json_body, timeout=timeout
+        )
+        if status_code >= 400:
+            chunks = [chunk async for chunk in aiterator]
+            body = b"".join(chunks)
+            self._sync_delegate._interpret_response(status_code, body, resp_headers)  # raises
+        return aiter_sse_events(aiterator)
+
+
+class _NullHTTPClient(HTTPClient):
+    """Never used to actually send anything — `AsyncAPIRequestor` only
+    borrows `APIRequestor`'s pure response-parsing methods, never its
+    `request`/`request_with_retries`. Keeping `APIRequestor.__init__` from
+    constructing a real (sync) `HTTPXClient` here avoids opening a second,
+    unused connection pool per `AsyncTermixClient`.
+    """
+
+    def __init__(self) -> None:  # no super().__init__: nothing needs verify/timeout
+        pass

termix_sdk/_async_client.py

@@ -0,0 +1,217 @@
+# Adapted from stripe-python (stripe/_stripe_client.py), MIT License,
+# Copyright (c) 2010-2018 Stripe. See NOTICE for the full license text.
+"""AsyncTermixClient: the async entry point, kept as its own class rather
+than `x_async()` methods on `TermixClient` (docs/sdk-plan.md section 2,
+item 7). See `_client.py` for the sync twin this mirrors line for line.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from ._api_requestor import AsyncAPIRequestor
+from ._client_options import ClientOptions
+from ._http_client import AsyncHTTPClient
+from ._request_options import RequestOptions
+from ._response import TermixResponse
+
+# --- generated resource imports start ---
+
+from .resources import ai as _ai
+from .resources import alerts as _alerts
+from .resources import api_keys as _api_keys
+from .resources import audit as _audit
+from .resources import automations as _automations
+from .resources import credentials as _credentials
+from .resources import dashboard as _dashboard
+from .resources import database as _database
+from .resources import docker as _docker
+from .resources import encryption as _encryption
+from .resources import file_manager as _file_manager
+from .resources import fleets as _fleets
+from .resources import guacamole as _guacamole
+from .resources import homepage as _homepage
+from .resources import host_file_manager as _host_file_manager
+from .resources import hosts as _hosts
+from .resources import instance_settings as _instance_settings
+from .resources import metrics as _metrics
+from .resources import network_topology as _network_topology
+from .resources import open_tabs as _open_tabs
+from .resources import preferences as _preferences
+from .resources import proxmox as _proxmox
+from .resources import proxmox_stats as _proxmox_stats
+from .resources import rbac as _rbac
+from .resources import session_logs as _session_logs
+from .resources import session_sharing as _session_sharing
+from .resources import snippets as _snippets
+from .resources import sso as _sso
+from .resources import sync as _sync
+from .resources import system as _system
+from .resources import tailscale as _tailscale
+from .resources import terminal as _terminal
+from .resources import termix_id as _termix_id
+from .resources import tmux as _tmux
+from .resources import tunnel as _tunnel
+from .resources import tunnel_presets as _tunnel_presets
+from .resources import user_admin as _user_admin
+from .resources import users as _users
+from .resources import vault as _vault
+from .resources import webauthn as _webauthn
+from .resources import workspaces as _workspaces
+
+# --- generated resource imports end ---
+
+if TYPE_CHECKING:
+    from ._auth import AsyncPendingTOTP
+
+
+class AsyncTermixClient:
+    """
+    Example:
+        >>> client = AsyncTermixClient(base_url="https://termix.example.com", api_key="tmx_...")
+        >>> await client.request("GET", "/health")
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        jwt: str | None = None,
+        service_urls: dict[str, str] | None = None,
+        timeout: float = 30.0,
+        verify: bool = True,
+        max_network_retries: int = 2,
+        default_headers: dict[str, str] | None = None,
+        _http_client: AsyncHTTPClient | None = None,
+    ) -> None:
+        self._options = ClientOptions(
+            base_url=base_url,
+            service_urls=service_urls,
+            api_key=api_key,
+            jwt=jwt,
+            timeout=timeout,
+            verify=verify,
+            max_network_retries=max_network_retries,
+            default_headers=default_headers,
+        )
+        self._requestor = AsyncAPIRequestor(self._options, http_client=_http_client)
+
+        # --- generated resource attributes start ---
+
+        self.ai = _ai.AsyncAiService(self._requestor)
+        self.alerts = _alerts.AsyncAlertsService(self._requestor)
+        self.api_keys = _api_keys.AsyncApiKeysService(self._requestor)
+        self.audit = _audit.AsyncAuditService(self._requestor)
+        self.automations = _automations.AsyncAutomationsService(self._requestor)
+        self.credentials = _credentials.AsyncCredentialsService(self._requestor)
+        self.dashboard = _dashboard.AsyncDashboardService(self._requestor)
+        self.database = _database.AsyncDatabaseService(self._requestor)
+        self.docker = _docker.AsyncDockerService(self._requestor)
+        self.encryption = _encryption.AsyncEncryptionService(self._requestor)
+        self.file_manager = _file_manager.AsyncFileManagerService(self._requestor)
+        self.fleets = _fleets.AsyncFleetsService(self._requestor)
+        self.guacamole = _guacamole.AsyncGuacamoleService(self._requestor)
+        self.homepage = _homepage.AsyncHomepageService(self._requestor)
+        self.host_file_manager = _host_file_manager.AsyncHostFileManagerService(self._requestor)
+        self.hosts = _hosts.AsyncHostsService(self._requestor)
+        self.instance_settings = _instance_settings.AsyncInstanceSettingsService(self._requestor)
+        self.metrics = _metrics.AsyncMetricsService(self._requestor)
+        self.network_topology = _network_topology.AsyncNetworkTopologyService(self._requestor)
+        self.open_tabs = _open_tabs.AsyncOpenTabsService(self._requestor)
+        self.preferences = _preferences.AsyncPreferencesService(self._requestor)
+        self.proxmox = _proxmox.AsyncProxmoxService(self._requestor)
+        self.proxmox_stats = _proxmox_stats.AsyncProxmoxStatsService(self._requestor)
+        self.rbac = _rbac.AsyncRbacService(self._requestor)
+        self.session_logs = _session_logs.AsyncSessionLogsService(self._requestor)
+        self.session_sharing = _session_sharing.AsyncSessionSharingService(self._requestor)
+        self.snippets = _snippets.AsyncSnippetsService(self._requestor)
+        self.sso = _sso.AsyncSsoService(self._requestor)
+        self.sync = _sync.AsyncSyncService(self._requestor)
+        self.system = _system.AsyncSystemService(self._requestor)
+        self.tailscale = _tailscale.AsyncTailscaleService(self._requestor)
+        self.terminal = _terminal.AsyncTerminalService(self._requestor)
+        self.termix_id = _termix_id.AsyncTermixIdService(self._requestor)
+        self.tmux = _tmux.AsyncTmuxService(self._requestor)
+        self.tunnel = _tunnel.AsyncTunnelService(self._requestor)
+        self.tunnel_presets = _tunnel_presets.AsyncTunnelPresetsService(self._requestor)
+        self.user_admin = _user_admin.AsyncUserAdminService(self._requestor)
+        self.users = _users.AsyncUsersService(self._requestor)
+        self.vault = _vault.AsyncVaultService(self._requestor)
+        self.webauthn = _webauthn.AsyncWebauthnService(self._requestor)
+        self.workspaces = _workspaces.AsyncWorkspacesService(self._requestor)
+
+        # --- generated resource attributes end ---
+
+    @classmethod
+    def _with_options(
+        cls, options: ClientOptions, requestor: AsyncAPIRequestor
+    ) -> AsyncTermixClient:
+        instance = cls.__new__(cls)
+        instance._options = options
+        instance._requestor = requestor
+        return instance
+
+    @classmethod
+    async def login(
+        cls,
+        *,
+        base_url: str,
+        username: str,
+        password: str,
+        remember_me: bool = False,
+        service_urls: dict[str, str] | None = None,
+        timeout: float = 30.0,
+        verify: bool = True,
+        max_network_retries: int = 2,
+        default_headers: dict[str, str] | None = None,
+        _http_client: AsyncHTTPClient | None = None,
+    ) -> AsyncTermixClient | AsyncPendingTOTP:
+        """Async mirror of `TermixClient.login()` — see its docstring and
+        `_auth.py`.
+        """
+        from ._auth import login_async
+
+        return await login_async(
+            base_url=base_url,
+            username=username,
+            password=password,
+            remember_me=remember_me,
+            service_urls=service_urls,
+            timeout=timeout,
+            verify=verify,
+            max_network_retries=max_network_retries,
+            default_headers=default_headers,
+            _http_client=_http_client,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str | None = None,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        files: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> TermixResponse | None:
+        return await self._requestor.request(
+            method,
+            path,
+            service=service,
+            query=query,
+            json_body=json_body,
+            files=files,
+            options=options,
+        )
+
+    async def close(self) -> None:
+        await self._requestor.close()
+
+    async def __aenter__(self) -> AsyncTermixClient:
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()