vaultkit 0.1.0__py3-none-any.whl

vaultkit/core/http.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Callable
+import logging
+
+import httpx
+
+from vaultkit.errors.base import ErrorContext
+from vaultkit.errors.exceptions import map_http_error, TransportError
+
+
+@dataclass(frozen=True)
+class HttpConfig:
+    timeout_s: float = 15.0
+    user_agent: str = "vaultkit-python/1.0"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        config: Optional[HttpConfig] = None,
+        retry_fn: Optional[Callable[[Callable[[], httpx.Response]], httpx.Response]] = None,
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.config = config or HttpConfig()
+        self._client = httpx.Client(timeout=self.config.timeout_s)
+        self._retry_fn = retry_fn  # optional retry wrapper
+        self._logger = logger
+
+        self._default_headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": self.config.user_agent,
+        }
+
+    def close(self) -> None:
+        self._client.close()
+
+    # public API
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self._request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json_body: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        return self._request("POST", path, json=json_body)
+
+    # internal
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+
+        if self._logger:
+            self._logger.debug(
+                "[VaultKit] HTTP request",
+                extra={
+                    "method": method,
+                    "path": path,
+                },
+            )
+
+        def send() -> httpx.Response:
+            return self._client.request(
+                method,
+                url,
+                headers=self._default_headers,
+                params=params,
+                json=json,
+            )
+
+        try:
+            res = self._retry_fn(send) if self._retry_fn else send()
+            return self._handle(res, method=method, path=path)
+        except httpx.RequestError as e:
+            if self._logger:
+                self._logger.error(
+                    "[VaultKit] Network error",
+                    extra={
+                        "method": method,
+                        "path": path,
+                        "error": str(e),
+                    },
+                )
+
+            raise TransportError(
+                f"Network error: {e}",
+                context=ErrorContext(raw=str(e)),
+            ) from e
+
+    def _handle(self, res: httpx.Response, *, method: str, path: str) -> Dict[str, Any]:
+        correlation_id = (
+            res.headers.get("x-correlation-id")
+            or res.headers.get("correlation_id")
+        )
+
+        if self._logger:
+            self._logger.debug(
+                "[VaultKit] HTTP response",
+                extra={
+                    "method": method,
+                    "path": path,
+                    "status_code": res.status_code,
+                    "correlation_id": correlation_id,
+                },
+            )
+
+        # success
+        if 200 <= res.status_code < 300:
+            if not res.content:
+                return {}
+
+            try:
+                data = res.json()
+            except Exception as e:
+                if self._logger:
+                    self._logger.error(
+                        "[VaultKit] Invalid JSON response",
+                        extra={
+                            "status_code": res.status_code,
+                            "correlation_id": correlation_id,
+                        },
+                    )
+
+                raise TransportError(
+                    "Invalid JSON response from VaultKit",
+                    context=ErrorContext(
+                        status_code=res.status_code,
+                        correlation_id=correlation_id,
+                        raw=res.text,
+                    ),
+                ) from e
+
+            return data if isinstance(data, dict) else {"data": data}
+
+        # error
+        raw: Any = None
+        msg = f"VaultKit API error ({res.status_code})"
+
+        try:
+            raw = res.json()
+            if isinstance(raw, dict):
+                msg = (
+                    raw.get("error")
+                    or raw.get("message")
+                    or raw.get("detail")
+                    or msg
+                )
+        except Exception:
+            raw = res.text
+
+        if self._logger:
+            self._logger.error(
+                "[VaultKit] API error",
+                extra={
+                    "status_code": res.status_code,
+                    "correlation_id": correlation_id,
+                    "message": msg,
+                },
+            )
+
+        ctx = ErrorContext(
+            status_code=res.status_code,
+            correlation_id=correlation_id,
+            raw=raw,
+        )
+
+        raise map_http_error(res.status_code, msg, context=ctx)

vaultkit/core/polling.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import time
+import random
+import logging
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from vaultkit.errors.exceptions import QueuedError, PollTimeoutError, NotFoundError
+from vaultkit.models.query_result import QueryResult
+
+_TERMINAL_STATUSES = {"granted", "denied", "pending_approval"}
+_APPROVAL_STATUSES = {"queued", "pending_approval"}
+
+
+@dataclass(frozen=True)
+class PollConfig:
+    interval_s: float = 2.0
+    timeout_s: float = 60.0
+
+    # Approval-specific backoff (long waits expected)
+    approval_backoff_factor: float = 1.5
+    approval_max_interval_s: float = 15.0
+
+    # Jitter percentage (±10% by default)
+    jitter_ratio: float = 0.1
+
+
+def poll_until_done(
+    *,
+    initial: QueryResult,
+    poll_fn: Callable[[str], QueryResult],
+    config: PollConfig,
+    logger: Optional[logging.Logger] = None,
+) -> QueryResult:
+    # If already in a terminal state, return immediately
+    if initial.status in _TERMINAL_STATUSES:
+        if logger:
+            logger.debug(
+                "[VaultKit] Poll skipped (already terminal)",
+                extra={"status": initial.status, "request_id": initial.request_id},
+            )
+        return initial
+
+    if not initial.request_id:
+        raise QueuedError(
+            "Request is queued but no request_id was provided; cannot poll safely."
+        )
+
+    request_id = initial.request_id
+    deadline = time.time() + config.timeout_s
+
+    current = initial
+    interval = config.interval_s
+    attempt = 0
+
+    while time.time() < deadline:
+        attempt += 1
+
+        # Apply jitter to avoid thundering herd issues when many requests are queued
+        jitter = random.uniform(
+            -interval * config.jitter_ratio,
+            interval * config.jitter_ratio,
+        )
+        sleep_time = max(0.0, interval + jitter)
+
+        # Ensure we don't sleep past the deadline
+        remaining = deadline - time.time()
+        if remaining <= 0:
+            break
+
+        if logger:
+            logger.debug(
+                "[VaultKit] Polling request",
+                extra={
+                    "request_id": request_id,
+                    "attempt": attempt,
+                    "interval": round(interval, 2),
+                },
+            )
+
+        time.sleep(min(sleep_time, remaining))
+
+        try:
+            current = poll_fn(request_id)
+        except NotFoundError:
+            # Request disappeared (expired / deleted / invalid)
+            if logger:
+                logger.error(
+                    "[VaultKit] Request not found during polling",
+                    extra={"request_id": request_id},
+                )
+            raise PollTimeoutError(
+                "Request not found while polling",
+                request_id=request_id,
+            )
+
+        if logger:
+            logger.debug(
+                "[VaultKit] Poll result",
+                extra={
+                    "request_id": request_id,
+                    "status": current.status,
+                },
+            )
+
+        # If we've reached a terminal state, return result
+        if current.status in _TERMINAL_STATUSES:
+            if logger:
+                logger.info(
+                    "[VaultKit] Polling complete",
+                    extra={
+                        "request_id": request_id,
+                        "status": current.status,
+                    },
+                )
+            return current
+
+        # Adjust interval based on status
+        if current.status in _APPROVAL_STATUSES:
+            # Slow down polling for approvals
+            interval = min(
+                interval * config.approval_backoff_factor,
+                config.approval_max_interval_s,
+            )
+        else:
+            # Reset to default interval for active processing states
+            interval = config.interval_s
+
+    # Timeout reached
+    if logger:
+        logger.error(
+            "[VaultKit] Polling timed out",
+            extra={"request_id": request_id},
+        )
+
+    raise PollTimeoutError(
+        f"Request still queued after {config.timeout_s:.0f}s",
+        request_id=request_id,
+    )

vaultkit/errors/__init__.py

@@ -0,0 +1,36 @@
+from .base import VaultKitError
+from .exceptions import (
+    ApprovalRequiredError,
+    DeniedError,
+    GrantExpiredError,
+    GrantRevokedError,
+    PolicyBundleRevokedError,
+    PollTimeoutError,
+    QueuedError,
+    ValidationError,
+    TransportError,
+    ServerError,
+    RateLimitError,
+)
+
+__all__ = [
+    # Base
+    "VaultKitError",
+
+    # Domain (core VaultKit behavior)
+    "DeniedError",
+    "ApprovalRequiredError",
+    "QueuedError",
+    "GrantExpiredError",
+    "GrantRevokedError",
+    "PolicyBundleRevokedError",
+    "PollTimeoutError",
+
+    # User / validation
+    "ValidationError",
+
+    # Transport / infra
+    "TransportError",
+    "ServerError",
+    "RateLimitError",
+]

vaultkit/errors/base.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class ErrorContext:
+    status_code: Optional[int] = None
+    request_id: Optional[str] = None
+    correlation_id: Optional[str] = None
+    raw: Optional[Any] = None
+
+
+class VaultKitError(Exception):
+    """Base exception for VaultKit SDK."""
+
+    error_code: str = "vaultkit_error"
+    retryable: bool = False
+
+    def __init__(self, message: str, *, context: Optional[ErrorContext] = None):
+        super().__init__(message)
+        self.message = message
+        self.context = context or ErrorContext()
+
+    def __str__(self) -> str:
+        base = self.message
+        if self.context and self.context.correlation_id:
+            return f"{base} (correlation_id={self.context.correlation_id})"
+        return base

vaultkit/errors/exceptions.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from typing import Optional, Any
+
+from .base import VaultKitError, ErrorContext
+
+
+# generic categories
+
+class ValidationError(VaultKitError):
+    error_code = "validation_error"
+
+
+class AuthError(VaultKitError):
+    error_code = "auth_error"
+
+
+class ForbiddenError(VaultKitError):
+    error_code = "forbidden"
+
+
+class NotFoundError(VaultKitError):
+    error_code = "not_found"
+
+
+class ConflictError(VaultKitError):
+    error_code = "conflict"
+
+
+class RateLimitError(VaultKitError):
+    error_code = "rate_limited"
+    retryable = True
+
+
+class TransportError(VaultKitError):
+    error_code = "transport_error"
+    retryable = True
+
+
+class ServerError(VaultKitError):
+    error_code = "server_error"
+    retryable = True
+
+
+class ClientError(VaultKitError):
+    error_code = "client_error"
+
+
+# domain-specific (VaultKit)
+
+class DeniedError(VaultKitError):
+    """
+    Raised when VaultKit policy denies a request.
+    Do not retry — denial is deterministic.
+    """
+
+    error_code = "policy_denied"
+    retryable = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        policy_id: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.policy_id = policy_id
+
+
+class QueuedError(VaultKitError):
+    """
+    Raised when a request is queued and the caller chose not to poll.
+    """
+
+    error_code = "queued"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.request_id = request_id
+
+
+class ApprovalRequiredError(VaultKitError):
+    """
+    Raised when a request reaches pending_approval after polling.
+    """
+
+    error_code = "approval_required"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.request_id = request_id
+
+
+class GrantExpiredError(VaultKitError):
+    error_code = "grant_expired"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        grant_ref: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.grant_ref = grant_ref
+
+
+class GrantRevokedError(VaultKitError):
+    error_code = "grant_revoked"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        grant_ref: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.grant_ref = grant_ref
+
+
+class PolicyBundleRevokedError(VaultKitError):
+    """
+    Unrecoverable — escalate to a VaultKit administrator.
+    """
+
+    error_code = "policy_bundle_revoked"
+    retryable = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        bundle_checksum: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.bundle_checksum = bundle_checksum
+
+
+class PollTimeoutError(VaultKitError):
+    """
+    Polling exceeded timeout. Request may still be processing.
+    """
+
+    error_code = "poll_timeout"
+    retryable = True  # caller can retry polling
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: Optional[str] = None,
+        context: Optional[ErrorContext] = None,
+    ) -> None:
+        super().__init__(message, context=context)
+        self.request_id = request_id
+
+
+# HTTP mapping
+
+def map_http_error(status_code: int, message: str, *, context: ErrorContext) -> VaultKitError:
+    raw = context.raw if isinstance(context.raw, dict) else {}
+
+    # future-proof: allow backend to send structured error types
+    error_type = raw.get("type") if isinstance(raw, dict) else None
+
+    if status_code == 400:
+        return ValidationError(message, context=context)
+
+    if status_code == 401:
+        return AuthError(message, context=context)
+
+    if status_code == 403:
+        if error_type == "policy_denied":
+            return DeniedError(
+                message,
+                policy_id=raw.get("policy_id"),
+                context=context,
+            )
+        return ForbiddenError(message, context=context)
+
+    if status_code == 404:
+        return NotFoundError(message, context=context)
+
+    if status_code == 409:
+        return ConflictError(message, context=context)
+
+    if status_code == 429:
+        return RateLimitError(message, context=context)
+
+    if 400 <= status_code < 500:
+        return ClientError(message, context=context)
+
+    if 500 <= status_code:
+        return ServerError(message, context=context)
+
+    return VaultKitError(message, context=context)

vaultkit/models/__init__.py

@@ -0,0 +1,11 @@
+from .dataset_info import DatasetInfo
+from .dataset_schema import DatasetSchema
+from .fetch_result import FetchResult
+from .query_result import QueryResult
+
+__all__ = [
+    "QueryResult",
+    "FetchResult",
+    "DatasetInfo",
+    "DatasetSchema",
+]

vaultkit/models/dataset_info.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    dataset: str
+    datasource: str
+    visibility: Optional[str] = None
+    correlation_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data):
+        dataset = data.get("name") or data.get("dataset")
+        datasource = data.get("datasource")
+
+        if not dataset or not datasource:
+            raise ValueError("DatasetInfo requires 'name'/'dataset' and 'datasource'")
+
+        return cls(
+            dataset=dataset,
+            datasource=datasource,
+            visibility=data.get("visibility"),
+            correlation_id=data.get("correlation_id"),
+        )