telemt-sdk 1.0.0__py3-none-any.whl

telemt/__init__.py

@@ -0,0 +1,34 @@
+"""Asynchronous Python SDK for Telemt."""
+
+from importlib.metadata import version
+
+from . import models
+from .client import TelemtClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    InvalidResponseError,
+    NotFoundError,
+    PermissionDeniedError,
+    RequestTimeoutError,
+    TelemtError,
+    TransportError,
+)
+
+__version__ = version("telemt-sdk")
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConflictError",
+    "InvalidResponseError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RequestTimeoutError",
+    "TelemtClient",
+    "TelemtError",
+    "TransportError",
+    "__version__",
+    "models",
+]

telemt/client.py

@@ -0,0 +1,177 @@
+"""An asynchronous, connection-pooling Telemt Control API client."""
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Self
+
+import httpx
+from pydantic import ValidationError
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    InvalidResponseError,
+    NotFoundError,
+    PermissionDeniedError,
+    RequestTimeoutError,
+    TransportError,
+)
+from .models.base import APIResponse, ErrorEnvelope, RequestModel
+from .models.requests import PatchConfigRequest, PatchUserRequest
+from .resources import (
+    ConfigResource,
+    HealthResource,
+    LimitsResource,
+    RuntimeResource,
+    SecurityResource,
+    StatsResource,
+    SystemResource,
+    UsersResource,
+)
+
+
+class TelemtClient:
+    """Use as an async context manager, or call aclose() explicitly.
+
+    auth_header is the exact Authorization value configured by Telemt.
+    An injected HTTPX client remains owned by the caller.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        auth_header: str | None = None,
+        timeout: float | httpx.Timeout = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        url = httpx.URL(base_url)
+        if url.scheme not in {"http", "https"} or not url.host:
+            raise ValueError("base_url must be an absolute HTTP(S) URL")
+        if url.query or url.fragment or url.userinfo:
+            raise ValueError("base_url must not contain credentials, a query, or a fragment")
+        path = url.path.rstrip("/")
+        if not path.endswith("/v1"):
+            path += "/v1"
+        self._base_url = url.copy_with(path=path + "/")
+        self._headers = {"Accept": "application/json"}
+        if auth_header is not None:
+            self._headers["Authorization"] = auth_header
+        self._timeout = timeout
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        self._closed = False
+        self.health = HealthResource(self)
+        self.system = SystemResource(self)
+        self.users = UsersResource(self)
+        self.config = ConfigResource(self)
+        self.stats = StatsResource(self)
+        self.runtime = RuntimeResource(self)
+        self.security = SecurityResource(self)
+        self.limits = LimitsResource(self)
+
+    async def __aenter__(self) -> Self:
+        if self._closed:
+            raise RuntimeError("TelemtClient is closed")
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close owned connections; safe to call more than once."""
+        if not self._closed:
+            if self._owns_http_client:
+                await self._http.aclose()
+            self._closed = True
+
+    async def _request[T](
+        self,
+        method: str,
+        path: str,
+        response_type: type[APIResponse[T]],
+        *,
+        body: RequestModel | None = None,
+        params: Mapping[str, str | int] | None = None,
+        revision: str | None = None,
+        accepted_statuses: tuple[int, ...] = (200, 201, 202),
+    ) -> APIResponse[T]:
+        if self._closed:
+            raise RuntimeError("TelemtClient is closed")
+        headers = self._headers.copy()
+        if revision is not None:
+            headers["If-Match"] = revision
+        payload = None
+        if body is not None:
+            body = type(body).model_validate(body)
+            headers["Content-Type"] = "application/json"
+            is_patch = isinstance(body, (PatchUserRequest, PatchConfigRequest))
+            payload = body.model_dump(
+                mode="json", exclude_unset=is_patch, exclude_none=not is_patch, by_alias=True
+            )
+        try:
+            url = self._base_url.join(path).copy_with(params=params)
+            request = self._http.build_request(
+                method,
+                url,
+                headers=headers,
+                json=payload,
+                timeout=self._timeout,
+            )
+            # Client defaults must not add query fields or replace exact Telemt authorization.
+            request.url = url
+            response = await self._http.send(request, auth=None, follow_redirects=False)
+        except httpx.TimeoutException as exc:
+            raise RequestTimeoutError("Telemt request timed out") from exc
+        except httpx.RequestError as exc:
+            raise TransportError("Telemt request failed") from exc
+
+        try:
+            envelope = response.json()
+        except ValueError as exc:
+            raise InvalidResponseError(
+                "Telemt returned invalid JSON", status_code=response.status_code
+            ) from exc
+        if not isinstance(envelope, dict) or type(envelope.get("ok")) is not bool:
+            raise InvalidResponseError(
+                "Telemt returned an invalid envelope", status_code=response.status_code
+            )
+        if envelope["ok"] is False:
+            try:
+                error = ErrorEnvelope.model_validate(envelope)
+            except ValidationError as exc:
+                raise InvalidResponseError(
+                    "Telemt returned an invalid error envelope", status_code=response.status_code
+                ) from exc
+            error_type = {
+                401: AuthenticationError,
+                403: PermissionDeniedError,
+                404: NotFoundError,
+                409: ConflictError,
+            }.get(response.status_code, APIError)
+            raise error_type(
+                status_code=response.status_code,
+                code=error.error.code,
+                message=error.error.message,
+                request_id=error.request_id,
+            )
+        if response.status_code not in accepted_statuses:
+            raise APIError(
+                status_code=response.status_code,
+                code="unexpected_http_status",
+                message="Success envelope received with an unexpected HTTP status",
+            )
+        try:
+            parsed = response_type.model_validate_json(response.content)
+            parsed.status_code = response.status_code
+            return parsed
+        except ValidationError as exc:
+            raise InvalidResponseError(
+                "Telemt response does not match the API contract", status_code=response.status_code
+            ) from exc

telemt/exceptions.py

@@ -0,0 +1,50 @@
+"""Errors exposed by the SDK; cancellation is deliberately never intercepted."""
+
+
+class TelemtError(Exception):
+    """Base class for SDK failures."""
+
+
+class TransportError(TelemtError):
+    """The request could not complete; the original HTTPX error is the cause."""
+
+
+class RequestTimeoutError(TransportError):
+    """The request exceeded its configured HTTP timeout."""
+
+
+class InvalidResponseError(TelemtError):
+    """The server returned an invalid or incompatible API envelope."""
+
+    def __init__(self, message: str, *, status_code: int) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class APIError(TelemtError):
+    """A rejected API request, retaining its machine code and audit request ID."""
+
+    def __init__(
+        self, *, status_code: int, code: str, message: str, request_id: int | None = None
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"HTTP {status_code} [{code}]: {message}")
+
+
+class AuthenticationError(APIError):
+    """Missing or invalid Authorization header (401)."""
+
+
+class PermissionDeniedError(APIError):
+    """The whitelist or read-only policy rejected the request (403)."""
+
+
+class NotFoundError(APIError):
+    """The requested resource does not exist (404)."""
+
+
+class ConflictError(APIError):
+    """A revision, runtime-instance, or operation conflict (409)."""

telemt/models/__init__.py

@@ -0,0 +1,345 @@
+"""Public request and response models for the Telemt Control API."""
+
+from .base import (
+    APIResponse,
+    RequestModel,
+    ResponseModel,
+)
+from .operations import (
+    ReloadAccepted,
+    ReloadStatus,
+    UserQuota,
+    UserQuotaData,
+)
+from .requests import (
+    AllSelector,
+    Carrier,
+    CloseRequest,
+    CreateUserRequest,
+    DrainRequest,
+    DrainTimeout,
+    FilterSelector,
+    Hex32,
+    OperationRef,
+    PatchConfigRequest,
+    PatchUserRequest,
+    QuotaPeriod,
+    RefsSelector,
+    ReloadRequest,
+    RotateSecretRequest,
+    RuntimeInstance,
+    RuntimeInstanceRequest,
+    SessionFilter,
+    SessionQuery,
+    SessionRef,
+    SessionState,
+    UInt64,
+    Username,
+)
+from .responses import (
+    ApiEventRecord,
+    ClassCount,
+    ConfigData,
+    CreateUserResponse,
+    DcEndpointWriters,
+    DcStatus,
+    DcStatusData,
+    DeleteUserResponse,
+    EffectiveLimitsData,
+    EffectiveMiddleProxyLimits,
+    EffectiveTimeoutLimits,
+    EffectiveUpstreamLimits,
+    EffectiveUserIpPolicyLimits,
+    EffectiveUserTcpPolicyLimits,
+    HealthData,
+    HealthReadyData,
+    MeWritersData,
+    MeWritersSummary,
+    MeWriterStatus,
+    MinimalAllData,
+    MinimalAllPayload,
+    MinimalDcPathData,
+    MinimalMeRuntimeData,
+    MinimalQuarantineData,
+    PatchConfigResponse,
+    ResetUserQuotaResponse,
+    RuntimeEdgeConnectionCacheData,
+    RuntimeEdgeConnectionsSummaryData,
+    RuntimeEdgeConnectionsSummaryPayload,
+    RuntimeEdgeConnectionTelemetryData,
+    RuntimeEdgeConnectionTopData,
+    RuntimeEdgeConnectionTotalsData,
+    RuntimeEdgeConnectionUserData,
+    RuntimeEdgeEventsData,
+    RuntimeEdgeEventsPayload,
+    RuntimeEdgeTlsFingerprintRow,
+    RuntimeEdgeTlsFingerprintsData,
+    RuntimeEdgeTlsFingerprintsPayload,
+    RuntimeGatesData,
+    RuntimeInitializationComponentData,
+    RuntimeInitializationData,
+    RuntimeInitializationMeData,
+    RuntimeMePoolStateData,
+    RuntimeMePoolStateGenerationData,
+    RuntimeMePoolStateHardswapData,
+    RuntimeMePoolStatePayload,
+    RuntimeMePoolStateRefillData,
+    RuntimeMePoolStateRefillDcData,
+    RuntimeMePoolStateWriterContourData,
+    RuntimeMePoolStateWriterData,
+    RuntimeMePoolStateWriterHealthData,
+    RuntimeMeQualityCountersData,
+    RuntimeMeQualityData,
+    RuntimeMeQualityDcRttData,
+    RuntimeMeQualityDrainGateData,
+    RuntimeMeQualityFamilyStateData,
+    RuntimeMeQualityPayload,
+    RuntimeMeQualityRouteDropData,
+    RuntimeMeSelftestBndData,
+    RuntimeMeSelftestData,
+    RuntimeMeSelftestIpData,
+    RuntimeMeSelftestIpFamilyData,
+    RuntimeMeSelftestKdfData,
+    RuntimeMeSelftestPayload,
+    RuntimeMeSelftestPidData,
+    RuntimeMeSelftestTimeskewData,
+    RuntimeMeSelftestUpstreamData,
+    RuntimeNatStunData,
+    RuntimeNatStunFlagsData,
+    RuntimeNatStunPayload,
+    RuntimeNatStunReflectionBlockData,
+    RuntimeNatStunReflectionData,
+    RuntimeNatStunServersData,
+    RuntimeUpstreamQualityCountersData,
+    RuntimeUpstreamQualityData,
+    RuntimeUpstreamQualityDcData,
+    RuntimeUpstreamQualityPolicyData,
+    RuntimeUpstreamQualitySummaryData,
+    RuntimeUpstreamQualityUpstreamData,
+    SecurityPostureData,
+    SecurityWhitelistData,
+    SummaryData,
+    SystemInfoData,
+    TlsDomainLink,
+    UpstreamDcStatus,
+    UpstreamsData,
+    UpstreamStatus,
+    UpstreamSummaryData,
+    UserActiveIps,
+    UserInfo,
+    UserLinks,
+    ZeroAllData,
+    ZeroCodeCount,
+    ZeroCoreData,
+    ZeroDesyncData,
+    ZeroMiddleProxyData,
+    ZeroPoolData,
+    ZeroUpstreamData,
+)
+from .web import (
+    ControlOperationStatus,
+    DebugClearData,
+    GoneSessionData,
+    LearningResetData,
+    OperatorDrainStatus,
+    OperatorLifecycleStatus,
+    SessionPage,
+    SessionRow,
+    WebBridgeRecoveryCounter,
+    WebBudgetStatus,
+    WebCapacityResourceStatus,
+    WebCapacityStatus,
+    WebCarrierFailureCounter,
+    WebCarrierLearningCounter,
+    WebCarrierNegotiationStatus,
+    WebCarrierSelectionCounter,
+    WebDebugConfig,
+    WebDebugStatus,
+    WebDecoyFastTrackCounter,
+    WebDecoyFastTrackStatus,
+    WebDecoyUpstreamStatus,
+    WebIngressStatus,
+    WebLearningStatus,
+    WebLifecycleCountersStatus,
+    WebLimitsConfig,
+    WebManagerStatus,
+    WebOutcomeCounter,
+    WebPermitStatus,
+    WebRejectionCounter,
+    WebRuntimeStatus,
+    WebSessionCloseCounter,
+    WebSessionLifecycleObservationCounter,
+    WebSessionStatus,
+    WebSocketStatus,
+    WebStatusData,
+    WebStreamStatus,
+    WebWildcardLimitsConfig,
+)
+
+__all__ = [
+    "APIResponse",
+    "AllSelector",
+    "ApiEventRecord",
+    "Carrier",
+    "ClassCount",
+    "CloseRequest",
+    "ConfigData",
+    "ControlOperationStatus",
+    "CreateUserRequest",
+    "CreateUserResponse",
+    "DcEndpointWriters",
+    "DcStatus",
+    "DcStatusData",
+    "DebugClearData",
+    "DeleteUserResponse",
+    "DrainRequest",
+    "DrainTimeout",
+    "EffectiveLimitsData",
+    "EffectiveMiddleProxyLimits",
+    "EffectiveTimeoutLimits",
+    "EffectiveUpstreamLimits",
+    "EffectiveUserIpPolicyLimits",
+    "EffectiveUserTcpPolicyLimits",
+    "FilterSelector",
+    "GoneSessionData",
+    "HealthData",
+    "HealthReadyData",
+    "Hex32",
+    "LearningResetData",
+    "MeWriterStatus",
+    "MeWritersData",
+    "MeWritersSummary",
+    "MinimalAllData",
+    "MinimalAllPayload",
+    "MinimalDcPathData",
+    "MinimalMeRuntimeData",
+    "MinimalQuarantineData",
+    "OperatorDrainStatus",
+    "OperatorLifecycleStatus",
+    "OperationRef",
+    "PatchConfigRequest",
+    "PatchConfigResponse",
+    "PatchUserRequest",
+    "QuotaPeriod",
+    "RefsSelector",
+    "ReloadAccepted",
+    "ReloadRequest",
+    "ReloadStatus",
+    "RequestModel",
+    "ResetUserQuotaResponse",
+    "ResponseModel",
+    "RotateSecretRequest",
+    "RuntimeEdgeConnectionCacheData",
+    "RuntimeEdgeConnectionTelemetryData",
+    "RuntimeEdgeConnectionTopData",
+    "RuntimeEdgeConnectionTotalsData",
+    "RuntimeEdgeConnectionUserData",
+    "RuntimeEdgeConnectionsSummaryData",
+    "RuntimeEdgeConnectionsSummaryPayload",
+    "RuntimeEdgeEventsData",
+    "RuntimeEdgeEventsPayload",
+    "RuntimeEdgeTlsFingerprintRow",
+    "RuntimeEdgeTlsFingerprintsData",
+    "RuntimeEdgeTlsFingerprintsPayload",
+    "RuntimeGatesData",
+    "RuntimeInitializationComponentData",
+    "RuntimeInitializationData",
+    "RuntimeInitializationMeData",
+    "RuntimeInstance",
+    "RuntimeInstanceRequest",
+    "RuntimeMePoolStateData",
+    "RuntimeMePoolStateGenerationData",
+    "RuntimeMePoolStateHardswapData",
+    "RuntimeMePoolStatePayload",
+    "RuntimeMePoolStateRefillData",
+    "RuntimeMePoolStateRefillDcData",
+    "RuntimeMePoolStateWriterContourData",
+    "RuntimeMePoolStateWriterData",
+    "RuntimeMePoolStateWriterHealthData",
+    "RuntimeMeQualityCountersData",
+    "RuntimeMeQualityData",
+    "RuntimeMeQualityDcRttData",
+    "RuntimeMeQualityDrainGateData",
+    "RuntimeMeQualityFamilyStateData",
+    "RuntimeMeQualityPayload",
+    "RuntimeMeQualityRouteDropData",
+    "RuntimeMeSelftestBndData",
+    "RuntimeMeSelftestData",
+    "RuntimeMeSelftestIpData",
+    "RuntimeMeSelftestIpFamilyData",
+    "RuntimeMeSelftestKdfData",
+    "RuntimeMeSelftestPayload",
+    "RuntimeMeSelftestPidData",
+    "RuntimeMeSelftestTimeskewData",
+    "RuntimeMeSelftestUpstreamData",
+    "RuntimeNatStunData",
+    "RuntimeNatStunFlagsData",
+    "RuntimeNatStunPayload",
+    "RuntimeNatStunReflectionBlockData",
+    "RuntimeNatStunReflectionData",
+    "RuntimeNatStunServersData",
+    "RuntimeUpstreamQualityCountersData",
+    "RuntimeUpstreamQualityData",
+    "RuntimeUpstreamQualityDcData",
+    "RuntimeUpstreamQualityPolicyData",
+    "RuntimeUpstreamQualitySummaryData",
+    "RuntimeUpstreamQualityUpstreamData",
+    "SecurityPostureData",
+    "SecurityWhitelistData",
+    "SessionFilter",
+    "SessionPage",
+    "SessionQuery",
+    "SessionRef",
+    "SessionRow",
+    "SessionState",
+    "SummaryData",
+    "SystemInfoData",
+    "TlsDomainLink",
+    "UInt64",
+    "UpstreamDcStatus",
+    "UpstreamStatus",
+    "UpstreamSummaryData",
+    "UpstreamsData",
+    "UserActiveIps",
+    "UserInfo",
+    "UserLinks",
+    "UserQuota",
+    "UserQuotaData",
+    "Username",
+    "WebBridgeRecoveryCounter",
+    "WebBudgetStatus",
+    "WebCapacityResourceStatus",
+    "WebCapacityStatus",
+    "WebCarrierFailureCounter",
+    "WebCarrierLearningCounter",
+    "WebCarrierNegotiationStatus",
+    "WebCarrierSelectionCounter",
+    "WebDebugConfig",
+    "WebDebugStatus",
+    "WebDecoyFastTrackCounter",
+    "WebDecoyFastTrackStatus",
+    "WebDecoyUpstreamStatus",
+    "WebIngressStatus",
+    "WebLearningStatus",
+    "WebLifecycleCountersStatus",
+    "WebLimitsConfig",
+    "WebManagerStatus",
+    "WebOutcomeCounter",
+    "WebPermitStatus",
+    "WebRejectionCounter",
+    "WebRuntimeStatus",
+    "WebSessionCloseCounter",
+    "WebSessionLifecycleObservationCounter",
+    "WebSessionStatus",
+    "WebSocketStatus",
+    "WebStatusData",
+    "WebStreamStatus",
+    "WebWildcardLimitsConfig",
+    "ZeroAllData",
+    "ZeroCodeCount",
+    "ZeroCoreData",
+    "ZeroDesyncData",
+    "ZeroMiddleProxyData",
+    "ZeroPoolData",
+    "ZeroUpstreamData",
+]

telemt/models/base.py

@@ -0,0 +1,39 @@
+"""Shared model configuration and HTTP response metadata."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ResponseModel(BaseModel):
+    """Typed API data; preserve new server fields for forward compatibility."""
+
+    model_config = ConfigDict(extra="allow", strict=True, hide_input_in_errors=True)
+
+
+class APIResponse[T](ResponseModel):
+    """One response and its own revision, safe to use with concurrent requests."""
+
+    ok: Literal[True]
+    data: T
+    revision: str
+    status_code: int = 200
+
+
+class RequestModel(BaseModel):
+    """Reject unknown inputs and keep omitted fields distinct from explicit null."""
+
+    model_config = ConfigDict(
+        extra="forbid", strict=True, revalidate_instances="always", hide_input_in_errors=True
+    )
+
+
+class ErrorDetail(ResponseModel):
+    code: str
+    message: str
+
+
+class ErrorEnvelope(ResponseModel):
+    ok: Literal[False]
+    error: ErrorDetail
+    request_id: int

telemt/models/operations.py

@@ -0,0 +1,39 @@
+"""Reload and quota contracts."""
+
+from pydantic import Field
+
+from .base import ResponseModel
+
+
+class ReloadAccepted(ResponseModel):
+    reload_id: int
+    target_generation: int
+    config_revision: str
+    state: str
+    mode: str
+    failure_policy: str
+
+
+class ReloadStatus(ReloadAccepted):
+    requested_at_epoch_secs: int
+    started_at_epoch_secs: int | None = None
+    finished_at_epoch_secs: int | None = None
+    deferred_process_fields: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    error: str | None = None
+
+
+class UserQuota(ResponseModel):
+    username: str
+    data_quota_bytes: int
+    used_bytes: int
+    last_reset_epoch_secs: int
+    quota_period: str | None = None
+    active_quota_period: str | None = None
+    quota_period_start_epoch_secs: int | None = None
+    quota_next_reset_epoch_secs: int | None = None
+    quota_schedule_state: str
+
+
+class UserQuotaData(ResponseModel):
+    users: list[UserQuota]