dominusnode 1.0.0__py3-none-any.whl

dominusnode/http_client.py

@@ -0,0 +1,435 @@
+"""HTTP client wrappers for sync and async usage.
+
+Handles:
+- User-Agent injection
+- Authorization header from token manager
+- Automatic retry on 429 (once)
+- Status-code-to-exception mapping
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .constants import USER_AGENT
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    DominusNodeError,
+    InsufficientBalanceError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .token_manager import AsyncTokenManager, TokenManager
+
+# Maximum response body size to prevent OOM from oversized API response
+MAX_RESPONSE_BYTES = 10 * 1024 * 1024  # 10MB
+
+
+def _extract_error_message(response: httpx.Response) -> str:
+    """Try to extract an error message from the JSON body.
+
+    All extracted messages are truncated to 500 chars to prevent
+    unbounded error body content from propagating into exception strings.
+    """
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            msg = body.get("error", response.reason_phrase or "Unknown error")
+            return str(msg)[:500]
+    except Exception:
+        pass
+    fallback = response.reason_phrase or f"HTTP {response.status_code}"
+    return str(fallback)[:500]
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP status codes to SDK exceptions."""
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+
+    msg = _extract_error_message(response)
+
+    if status == 400:
+        raise ValidationError(msg)
+    if status == 401:
+        raise AuthenticationError(msg)
+    if status == 402:
+        raise InsufficientBalanceError(msg)
+    if status == 403:
+        raise AuthorizationError(msg)
+    if status == 404:
+        raise NotFoundError(msg)
+    if status == 409:
+        raise ConflictError(msg)
+    if status == 429:
+        retry_after = 60
+        ra_header = response.headers.get("retry-after")
+        if ra_header:
+            try:
+                retry_after = int(ra_header)
+            except ValueError:
+                pass
+        raise RateLimitError(msg, retry_after_seconds=retry_after)
+    if status >= 500:
+        raise ServerError(msg, status_code=status)
+
+    raise DominusNodeError(msg, status_code=status)
+
+
+def _parse_retry_after(response: httpx.Response) -> float:
+    """Parse Retry-After header, defaulting to 1 second."""
+    ra = response.headers.get("retry-after")
+    if ra:
+        try:
+            val = float(ra)
+            # Guard against NaN/Infinity from malformed headers
+            if not (val == val) or val == float("inf"):  # NaN check + infinity check
+                return 1.0
+            return max(val, 0.1)
+        except ValueError:
+            pass
+    return 1.0
+
+
+def _add_jitter(seconds: float) -> float:
+    """Add ±10% jitter to prevent thundering-herd on rate-limited endpoints."""
+    jitter = seconds * 0.2 * (random.random() - 0.5)
+    return max(0.1, seconds + jitter)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync HTTP Client
+# ──────────────────────────────────────────────────────────────────────
+
+
+class SyncHttpClient:
+    """Synchronous HTTP client wrapping httpx.Client."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token_manager: TokenManager,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token_manager = token_manager
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT},
+            follow_redirects=False,  # Prevent HTTPS→HTTP credential leakage
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _build_headers(
+        self, extra: Optional[Dict[str, str]] = None, *, requires_auth: bool = True,
+    ) -> Dict[str, str]:
+        headers: Dict[str, str] = {}
+        # Only attach Authorization header when auth is required.
+        # Public endpoints (slots, waitlist) must not leak credentials.
+        if requires_auth:
+            token = self._token_manager.get_valid_token()
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        requires_auth: bool = True,
+    ) -> httpx.Response:
+        """Execute an HTTP request with auto-retry on 401 (token refresh) and 429."""
+        merged_headers = self._build_headers(headers, requires_auth=requires_auth)
+        try:
+            response = self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                headers=merged_headers,
+            )
+        except httpx.HTTPError as exc:
+            raise NetworkError(str(exc)) from exc
+
+        # Response size limit — check Content-Length header if available
+        content_length = response.headers.get("content-length")
+        if content_length:
+            try:
+                if int(content_length) > MAX_RESPONSE_BYTES:
+                    raise NetworkError(f"Response too large: {content_length} bytes")
+            except ValueError:
+                pass  # Malformed Content-Length header — skip size check
+
+        # Also check actual body size (chunked transfer encoding may omit Content-Length)
+        if len(response.content) > MAX_RESPONSE_BYTES:
+            raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        # Auto-retry once on 401 after force-refreshing the token
+        if response.status_code == 401 and requires_auth and self._token_manager.has_refresh_token:
+            self._token_manager.force_refresh()
+            merged_headers = self._build_headers(headers, requires_auth=requires_auth)
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=merged_headers,
+                )
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+            # Size check on 401-retry response
+            if len(response.content) > MAX_RESPONSE_BYTES:
+                raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        # Auto-retry once on 429
+        if response.status_code == 429:
+            wait = _parse_retry_after(response)
+            time.sleep(_add_jitter(min(wait, 10.0)))  # Cap at 10s + jitter
+            # Rebuild headers to get fresh token in case it expired during wait
+            merged_headers = self._build_headers(headers, requires_auth=requires_auth)
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=merged_headers,
+                )
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+            # Size check on 429-retry response
+            if len(response.content) > MAX_RESPONSE_BYTES:
+                raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        _raise_for_status(response)
+        return response
+
+    def get(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = self.request("GET", path, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def post(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = self.request("POST", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def put(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = self.request("PUT", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def patch(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = self.request("PATCH", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def delete(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = self.request("DELETE", path, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def get_raw(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> httpx.Response:
+        """Return the raw httpx.Response (for CSV export, etc.)."""
+        return self.request("GET", path, params=params, requires_auth=requires_auth)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async HTTP Client
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client wrapping httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token_manager: AsyncTokenManager,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token_manager = token_manager
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT},
+            follow_redirects=False,  # Prevent HTTPS→HTTP credential leakage
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def _build_headers(
+        self, extra: Optional[Dict[str, str]] = None, *, requires_auth: bool = True,
+    ) -> Dict[str, str]:
+        headers: Dict[str, str] = {}
+        # Only attach Authorization header when auth is required.
+        if requires_auth:
+            token = await self._token_manager.get_valid_token()
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        requires_auth: bool = True,
+    ) -> httpx.Response:
+        """Execute an HTTP request with auto-retry on 401 (token refresh) and 429."""
+        merged_headers = await self._build_headers(headers, requires_auth=requires_auth)
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                headers=merged_headers,
+            )
+        except httpx.HTTPError as exc:
+            raise NetworkError(str(exc)) from exc
+
+        # Response size limit — check Content-Length header if available
+        content_length = response.headers.get("content-length")
+        if content_length:
+            try:
+                if int(content_length) > MAX_RESPONSE_BYTES:
+                    raise NetworkError(f"Response too large: {content_length} bytes")
+            except ValueError:
+                pass  # Malformed Content-Length header — skip size check
+
+        # Also check actual body size (chunked transfer encoding may omit Content-Length)
+        if len(response.content) > MAX_RESPONSE_BYTES:
+            raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        # Auto-retry once on 401 after force-refreshing the token
+        if response.status_code == 401 and requires_auth and self._token_manager.has_refresh_token:
+            await self._token_manager.force_refresh()
+            merged_headers = await self._build_headers(headers, requires_auth=requires_auth)
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=merged_headers,
+                )
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+            # Size check on 401-retry response
+            if len(response.content) > MAX_RESPONSE_BYTES:
+                raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        # Auto-retry once on 429
+        if response.status_code == 429:
+            wait = _parse_retry_after(response)
+            await asyncio.sleep(_add_jitter(min(wait, 10.0)))
+            # Rebuild headers to get fresh token in case it expired during wait
+            merged_headers = await self._build_headers(headers, requires_auth=requires_auth)
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=merged_headers,
+                )
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+            # Size check on 429-retry response
+            if len(response.content) > MAX_RESPONSE_BYTES:
+                raise NetworkError(f"Response body too large: {len(response.content)} bytes")
+
+        _raise_for_status(response)
+        return response
+
+    async def get(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = await self.request("GET", path, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    async def post(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = await self.request("POST", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    async def put(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = await self.request("PUT", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    async def patch(
+        self, path: str, *, json: Any = None, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = await self.request("PATCH", path, json=json, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    async def delete(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> Any:
+        resp = await self.request("DELETE", path, params=params, requires_auth=requires_auth)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    async def get_raw(
+        self, path: str, *, params: Optional[Dict[str, Any]] = None, requires_auth: bool = True,
+    ) -> httpx.Response:
+        """Return the raw httpx.Response (for CSV export, etc.)."""
+        return await self.request("GET", path, params=params, requires_auth=requires_auth)

dominusnode/keys.py

@@ -0,0 +1,88 @@
+"""API key management resource."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+from urllib.parse import quote
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import ApiKey, CreatedApiKey
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class KeysResource:
+    """Synchronous API key operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, label: str = "Default") -> CreatedApiKey:
+        """Create a new API key. The raw key is only returned once."""
+        data = self._http.post("/api/keys", json={"label": label})
+        return CreatedApiKey(
+            key=data["key"],
+            id=data["id"],
+            prefix=data["prefix"],
+            label=data["label"],
+            created_at=str(data["created_at"]),
+        )
+
+    def list(self) -> List[ApiKey]:
+        """List all API keys for the current user."""
+        data = self._http.get("/api/keys")
+        return [
+            ApiKey(
+                id=k["id"],
+                prefix=k["prefix"],
+                label=k["label"],
+                created_at=str(k["created_at"]),
+                revoked_at=str(k["revoked_at"]) if k.get("revoked_at") else None,
+            )
+            for k in data.get("keys", [])
+        ]
+
+    def revoke(self, key_id: str) -> None:
+        """Revoke an API key by ID."""
+        self._http.delete(f"/api/keys/{quote(key_id, safe='')}")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncKeysResource:
+    """Asynchronous API key operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, label: str = "Default") -> CreatedApiKey:
+        data = await self._http.post("/api/keys", json={"label": label})
+        return CreatedApiKey(
+            key=data["key"],
+            id=data["id"],
+            prefix=data["prefix"],
+            label=data["label"],
+            created_at=str(data["created_at"]),
+        )
+
+    async def list(self) -> List[ApiKey]:
+        data = await self._http.get("/api/keys")
+        return [
+            ApiKey(
+                id=k["id"],
+                prefix=k["prefix"],
+                label=k["label"],
+                created_at=str(k["created_at"]),
+                revoked_at=str(k["revoked_at"]) if k.get("revoked_at") else None,
+            )
+            for k in data.get("keys", [])
+        ]
+
+    async def revoke(self, key_id: str) -> None:
+        await self._http.delete(f"/api/keys/{quote(key_id, safe='')}")

dominusnode/plans.py

@@ -0,0 +1,93 @@
+"""Plans resource -- list plans, get/change user plan."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .types import Plan, UserPlanInfo, UserPlanUsage
+
+
+def _parse_plan(p: dict) -> Plan:
+    return Plan(
+        id=p["id"],
+        name=p["name"],
+        price_per_gb_cents=p["pricePerGbCents"],
+        price_per_gb_usd=p["pricePerGbUsd"],
+        monthly_bandwidth_bytes=p.get("monthlyBandwidthBytes", 0),
+        monthly_bandwidth_gb=p.get("monthlyBandwidthGB"),
+        is_default=p.get("isDefault", False),
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────
+
+
+class PlansResource:
+    """Synchronous plans operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Plan]:
+        """List all available plans."""
+        data = self._http.get("/api/plans")
+        return [_parse_plan(p) for p in data.get("plans", [])]
+
+    def get_user_plan(self) -> UserPlanInfo:
+        """Get the current user's plan and monthly usage."""
+        data = self._http.get("/api/plans/user/plan")
+        plan = _parse_plan(data["plan"])
+        u = data["usage"]
+        usage = UserPlanUsage(
+            monthly_usage_bytes=u["monthlyUsageBytes"],
+            monthly_usage_gb=u["monthlyUsageGB"],
+            limit_bytes=u["limitBytes"],
+            limit_gb=u.get("limitGB"),
+            percent_used=u.get("percentUsed"),
+        )
+        return UserPlanInfo(plan=plan, usage=usage)
+
+    def change_plan(self, plan_id: str) -> Plan:
+        """Change the current user's plan.
+
+        Args:
+            plan_id: The plan ID to switch to (e.g. 'payg', 'vol100', 'vol1tb').
+        """
+        data = self._http.put("/api/plans/user/plan", json={"planId": plan_id})
+        return _parse_plan(data["plan"])
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────
+
+
+class AsyncPlansResource:
+    """Asynchronous plans operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self) -> List[Plan]:
+        data = await self._http.get("/api/plans")
+        return [_parse_plan(p) for p in data.get("plans", [])]
+
+    async def get_user_plan(self) -> UserPlanInfo:
+        data = await self._http.get("/api/plans/user/plan")
+        plan = _parse_plan(data["plan"])
+        u = data["usage"]
+        usage = UserPlanUsage(
+            monthly_usage_bytes=u["monthlyUsageBytes"],
+            monthly_usage_gb=u["monthlyUsageGB"],
+            limit_bytes=u["limitBytes"],
+            limit_gb=u.get("limitGB"),
+            percent_used=u.get("percentUsed"),
+        )
+        return UserPlanInfo(plan=plan, usage=usage)
+
+    async def change_plan(self, plan_id: str) -> Plan:
+        data = await self._http.put("/api/plans/user/plan", json={"planId": plan_id})
+        return _parse_plan(data["plan"])