arc-tsdb-client 0.1.0__py3-none-any.whl

arc_client/__init__.py

@@ -0,0 +1,38 @@
+"""Arc Python SDK - High-performance client for Arc time-series database."""
+
+from arc_client.async_client import AsyncArcClient
+from arc_client.client import ArcClient
+from arc_client.config import ClientConfig
+from arc_client.exceptions import (
+    ArcAuthenticationError,
+    ArcConnectionError,
+    ArcError,
+    ArcIngestionError,
+    ArcNotFoundError,
+    ArcQueryError,
+    ArcRateLimitError,
+    ArcServerError,
+    ArcValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "ArcClient",
+    "AsyncArcClient",
+    # Config
+    "ClientConfig",
+    # Exceptions
+    "ArcError",
+    "ArcConnectionError",
+    "ArcAuthenticationError",
+    "ArcQueryError",
+    "ArcIngestionError",
+    "ArcValidationError",
+    "ArcNotFoundError",
+    "ArcRateLimitError",
+    "ArcServerError",
+    # Version
+    "__version__",
+]

arc_client/async_client.py

@@ -0,0 +1,179 @@
+"""Asynchronous Arc client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from arc_client.config import ClientConfig
+from arc_client.http.async_http import AsyncHTTPClient
+from arc_client.models.common import HealthResponse
+
+
+class AsyncArcClient:
+    """Asynchronous client for Arc time-series database.
+
+    Example:
+        >>> async with AsyncArcClient(host="localhost", token="my-token") as client:
+        ...     health = await client.health()
+        ...     print(health.status)
+        ...
+        ...     await client.write.write_columnar(
+        ...         measurement="cpu",
+        ...         columns={
+        ...             "time": [1633024800000000, 1633024801000000],
+        ...             "host": ["server01", "server01"],
+        ...             "usage": [45.2, 47.8],
+        ...         },
+        ...     )
+        ...
+        ...     df = await client.query.query_pandas("SELECT * FROM cpu LIMIT 100")
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 8000,
+        token: Optional[str] = None,
+        database: str = "default",
+        timeout: float = 30.0,
+        compression: bool = True,
+        ssl: bool = False,
+        verify_ssl: bool = True,
+    ) -> None:
+        """Initialize the async Arc client.
+
+        Args:
+            host: Arc server hostname.
+            port: Arc server port.
+            token: API token for authentication.
+            database: Default database name.
+            timeout: Request timeout in seconds.
+            compression: Enable gzip compression for writes.
+            ssl: Use HTTPS.
+            verify_ssl: Verify SSL certificates.
+        """
+        self._config = ClientConfig(
+            host=host,
+            port=port,
+            token=token,
+            database=database,
+            timeout=timeout,
+            compression=compression,
+            ssl=ssl,
+            verify_ssl=verify_ssl,
+        )
+        self._http: Optional[AsyncHTTPClient] = None
+
+        # Lazy-initialized sub-clients
+        self._write: Any = None
+        self._query: Any = None
+        self._auth: Any = None
+        self._retention: Any = None
+        self._continuous_queries: Any = None
+        self._delete: Any = None
+
+    def _get_http(self) -> AsyncHTTPClient:
+        """Get or create the HTTP client."""
+        if self._http is None:
+            self._http = AsyncHTTPClient(self._config)
+        return self._http
+
+    @property
+    def config(self) -> ClientConfig:
+        """Get the client configuration."""
+        return self._config
+
+    @property
+    def write(self) -> Any:
+        """Get the async write client for data ingestion."""
+        if self._write is None:
+            from arc_client.ingestion.async_writer import AsyncWriteClient
+
+            self._write = AsyncWriteClient(self._get_http(), self._config)
+        return self._write
+
+    @property
+    def query(self) -> Any:
+        """Get the async query client for SQL queries."""
+        if self._query is None:
+            from arc_client.query.async_executor import AsyncQueryClient
+
+            self._query = AsyncQueryClient(self._get_http(), self._config)
+        return self._query
+
+    @property
+    def auth(self) -> Any:
+        """Get the async auth client for token management."""
+        if self._auth is None:
+            from arc_client.auth.async_manager import AsyncAuthClient
+
+            self._auth = AsyncAuthClient(self._get_http(), self._config)
+        return self._auth
+
+    @property
+    def retention(self) -> Any:
+        """Get the async retention client for policy management."""
+        if self._retention is None:
+            from arc_client.management.async_retention import AsyncRetentionClient
+
+            self._retention = AsyncRetentionClient(self._get_http(), self._config)
+        return self._retention
+
+    @property
+    def continuous_queries(self) -> Any:
+        """Get the async continuous queries client."""
+        if self._continuous_queries is None:
+            from arc_client.management.async_continuous_query import AsyncContinuousQueryClient
+
+            self._continuous_queries = AsyncContinuousQueryClient(self._get_http(), self._config)
+        return self._continuous_queries
+
+    @property
+    def delete(self) -> Any:
+        """Get the async delete client for data deletion."""
+        if self._delete is None:
+            from arc_client.management.async_delete import AsyncDeleteClient
+
+            self._delete = AsyncDeleteClient(self._get_http(), self._config)
+        return self._delete
+
+    async def health(self) -> HealthResponse:
+        """Check server health.
+
+        Returns:
+            HealthResponse with server status.
+
+        Raises:
+            ArcConnectionError: If connection to server fails.
+        """
+        response = await self._get_http().get("/health")
+        return HealthResponse.model_validate(response.json())
+
+    async def ready(self) -> bool:
+        """Check if server is ready to accept requests.
+
+        Returns:
+            True if server is ready, False otherwise.
+        """
+        try:
+            response = await self._get_http().get("/ready")
+            return response.status_code == 200
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        """Close the client and release resources."""
+        if self._http is not None:
+            await self._http.close()
+            self._http = None
+
+    async def __aenter__(self) -> AsyncArcClient:
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncArcClient(host={self._config.host!r}, port={self._config.port})"

arc_client/auth/__init__.py

@@ -0,0 +1,9 @@
+"""Authentication module for Arc client."""
+
+from arc_client.auth.async_manager import AsyncAuthClient
+from arc_client.auth.manager import AuthClient
+
+__all__ = [
+    "AsyncAuthClient",
+    "AuthClient",
+]

arc_client/auth/async_manager.py

@@ -0,0 +1,174 @@
+"""Asynchronous auth client for Arc."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from arc_client.config import ClientConfig
+from arc_client.exceptions import ArcAuthenticationError, ArcNotFoundError
+from arc_client.http.async_http import AsyncHTTPClient
+from arc_client.models.auth import (
+    CreateTokenResponse,
+    RotateTokenResponse,
+    TokenInfo,
+    TokenListResponse,
+    VerifyResponse,
+)
+
+
+class AsyncAuthClient:
+    """Asynchronous client for authentication and token management."""
+
+    def __init__(self, http: AsyncHTTPClient, config: ClientConfig) -> None:
+        self._http = http
+        self._config = config
+
+    async def verify(self) -> VerifyResponse:
+        """Verify the current token."""
+        if not self._config.token:
+            return VerifyResponse(valid=False, error="No token configured")
+
+        try:
+            response = await self._http.get("/api/v1/auth/verify")
+            data = response.json()
+            return VerifyResponse(**data)
+        except ArcAuthenticationError:
+            return VerifyResponse(valid=False, error="Invalid or expired token")
+        except Exception as e:
+            raise ArcAuthenticationError(f"Token verification failed: {e}") from e
+
+    async def create_token(
+        self,
+        name: str,
+        description: Optional[str] = None,
+        permissions: Optional[list[str]] = None,
+        expires_in: Optional[str] = None,
+    ) -> CreateTokenResponse:
+        """Create a new API token. Requires admin permissions."""
+        payload: dict[str, Any] = {"name": name}
+        if description:
+            payload["description"] = description
+        if permissions:
+            payload["permissions"] = permissions
+        if expires_in:
+            payload["expires_in"] = expires_in
+
+        try:
+            response = await self._http.post("/api/v1/auth/tokens", json=payload)
+            data = response.json()
+            return CreateTokenResponse(**data)
+        except ArcAuthenticationError:
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to create token: {e}") from e
+
+    async def list_tokens(self) -> List[TokenInfo]:
+        """List all tokens. Requires admin permissions."""
+        try:
+            response = await self._http.get("/api/v1/auth/tokens")
+            data = response.json()
+            result = TokenListResponse(**data)
+            if not result.success:
+                raise ArcAuthenticationError(result.error or "Failed to list tokens")
+            return result.tokens
+        except ArcAuthenticationError:
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to list tokens: {e}") from e
+
+    async def get_token(self, token_id: int) -> TokenInfo:
+        """Get token details by ID. Requires admin permissions."""
+        try:
+            response = await self._http.get(f"/api/v1/auth/tokens/{token_id}")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+            return TokenInfo(**data["token"])
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to get token: {e}") from e
+
+    async def update_token(
+        self,
+        token_id: int,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        permissions: Optional[list[str]] = None,
+        expires_in: Optional[str] = None,
+    ) -> None:
+        """Update token properties. Requires admin permissions."""
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if permissions is not None:
+            payload["permissions"] = permissions
+        if expires_in is not None:
+            payload["expires_in"] = expires_in
+
+        try:
+            response = await self._http.patch(f"/api/v1/auth/tokens/{token_id}", json=payload)
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to update token: {e}") from e
+
+    async def delete_token(self, token_id: int) -> None:
+        """Delete a token. Requires admin permissions."""
+        try:
+            response = await self._http.delete(f"/api/v1/auth/tokens/{token_id}")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to delete token: {e}") from e
+
+    async def rotate_token(self, token_id: int) -> str:
+        """Rotate a token and return the new value. Requires admin permissions."""
+        try:
+            response = await self._http.post(f"/api/v1/auth/tokens/{token_id}/rotate")
+            data = response.json()
+            result = RotateTokenResponse(**data)
+            if not result.success:
+                error = result.error or "Unknown error"
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+            if not result.new_token:
+                raise ArcAuthenticationError("No new token returned")
+            return result.new_token
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to rotate token: {e}") from e
+
+    async def revoke_token(self, token_id: int) -> None:
+        """Revoke a token. Requires admin permissions."""
+        try:
+            response = await self._http.post(f"/api/v1/auth/tokens/{token_id}/revoke")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to revoke token: {e}") from e

arc_client/auth/manager.py

@@ -0,0 +1,186 @@
+"""Synchronous auth client for Arc."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from arc_client.config import ClientConfig
+from arc_client.exceptions import ArcAuthenticationError, ArcNotFoundError
+from arc_client.http.sync_http import SyncHTTPClient
+from arc_client.models.auth import (
+    CreateTokenResponse,
+    RotateTokenResponse,
+    TokenInfo,
+    TokenListResponse,
+    VerifyResponse,
+)
+
+
+class AuthClient:
+    """Synchronous client for authentication and token management.
+
+    This client provides methods for verifying tokens and managing API tokens
+    (create, list, update, delete, rotate, revoke).
+
+    Note: Token management operations require admin permissions.
+
+    Example:
+        >>> with ArcClient(host="localhost", token="admin-token") as client:
+        ...     result = client.auth.verify()
+        ...     if result.valid:
+        ...         print(f"Token valid with permissions: {result.permissions}")
+    """
+
+    def __init__(self, http: SyncHTTPClient, config: ClientConfig) -> None:
+        self._http = http
+        self._config = config
+
+    def verify(self) -> VerifyResponse:
+        """Verify the current token."""
+        if not self._config.token:
+            return VerifyResponse(valid=False, error="No token configured")
+
+        try:
+            response = self._http.get("/api/v1/auth/verify")
+            data = response.json()
+            return VerifyResponse(**data)
+        except ArcAuthenticationError:
+            return VerifyResponse(valid=False, error="Invalid or expired token")
+        except Exception as e:
+            raise ArcAuthenticationError(f"Token verification failed: {e}") from e
+
+    def create_token(
+        self,
+        name: str,
+        description: Optional[str] = None,
+        permissions: Optional[list[str]] = None,
+        expires_in: Optional[str] = None,
+    ) -> CreateTokenResponse:
+        """Create a new API token. Requires admin permissions."""
+        payload: dict[str, Any] = {"name": name}
+        if description:
+            payload["description"] = description
+        if permissions:
+            payload["permissions"] = permissions
+        if expires_in:
+            payload["expires_in"] = expires_in
+
+        try:
+            response = self._http.post("/api/v1/auth/tokens", json=payload)
+            data = response.json()
+            return CreateTokenResponse(**data)
+        except ArcAuthenticationError:
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to create token: {e}") from e
+
+    def list_tokens(self) -> List[TokenInfo]:
+        """List all tokens. Requires admin permissions."""
+        try:
+            response = self._http.get("/api/v1/auth/tokens")
+            data = response.json()
+            result = TokenListResponse(**data)
+            if not result.success:
+                raise ArcAuthenticationError(result.error or "Failed to list tokens")
+            return result.tokens
+        except ArcAuthenticationError:
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to list tokens: {e}") from e
+
+    def get_token(self, token_id: int) -> TokenInfo:
+        """Get token details by ID. Requires admin permissions."""
+        try:
+            response = self._http.get(f"/api/v1/auth/tokens/{token_id}")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+            return TokenInfo(**data["token"])
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to get token: {e}") from e
+
+    def update_token(
+        self,
+        token_id: int,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        permissions: Optional[list[str]] = None,
+        expires_in: Optional[str] = None,
+    ) -> None:
+        """Update token properties. Requires admin permissions."""
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if permissions is not None:
+            payload["permissions"] = permissions
+        if expires_in is not None:
+            payload["expires_in"] = expires_in
+
+        try:
+            response = self._http.patch(f"/api/v1/auth/tokens/{token_id}", json=payload)
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to update token: {e}") from e
+
+    def delete_token(self, token_id: int) -> None:
+        """Delete a token. Requires admin permissions."""
+        try:
+            response = self._http.delete(f"/api/v1/auth/tokens/{token_id}")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to delete token: {e}") from e
+
+    def rotate_token(self, token_id: int) -> str:
+        """Rotate a token and return the new value. Requires admin permissions."""
+        try:
+            response = self._http.post(f"/api/v1/auth/tokens/{token_id}/rotate")
+            data = response.json()
+            result = RotateTokenResponse(**data)
+            if not result.success:
+                error = result.error or "Unknown error"
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+            if not result.new_token:
+                raise ArcAuthenticationError("No new token returned")
+            return result.new_token
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to rotate token: {e}") from e
+
+    def revoke_token(self, token_id: int) -> None:
+        """Revoke a token. Requires admin permissions."""
+        try:
+            response = self._http.post(f"/api/v1/auth/tokens/{token_id}/revoke")
+            data = response.json()
+            if not data.get("success", True):
+                error = data.get("error", "Unknown error")
+                if "not found" in error.lower():
+                    raise ArcNotFoundError(f"Token {token_id} not found")
+                raise ArcAuthenticationError(error)
+        except (ArcNotFoundError, ArcAuthenticationError):
+            raise
+        except Exception as e:
+            raise ArcAuthenticationError(f"Failed to revoke token: {e}") from e