dominus-sdk-python 2.0.0__py3-none-any.whl

dominus/__init__.py

@@ -0,0 +1,47 @@
+"""
+CB Dominus SDK - Ultra-flat async SDK for CareBridge Services
+
+Ultra-Flat API:
+    from dominus import dominus
+
+    # Secrets (root level)
+    value = await dominus.get("DB_URL")
+    await dominus.upsert("KEY", "value")
+
+    # Auth (root level)
+    await dominus.add_user(username="john", password="secret", role_id="...")
+    await dominus.add_scope(slug="read", display_name="Read", tenant_category_id=1)
+    result = await dominus.verify_user_password(username="john", password="secret")
+
+    # SQL data - app schema (root level)
+    tables = await dominus.list_tables()
+    rows = await dominus.query_table("users")
+    await dominus.insert_row("users", {"name": "John"})
+
+    # SQL data - secure schema (secure namespace)
+    rows = await dominus.secure.query_table("patients")
+    await dominus.secure.insert_row("patients", {"mrn": "12345"})
+
+    # Schema DDL - app schema (root level)
+    await dominus.add_table("users", [{"name": "id", "type": "UUID"}])
+
+    # Schema DDL - secure schema (secure namespace)
+    await dominus.secure.add_table("patients", [...])
+
+    # Open DSN
+    dsn = await dominus.open.dsn()
+
+    # Health
+    status = await dominus.health.check()
+
+Backward Compatible String API:
+    result = await dominus("secrets.get", key="DB_URL")
+"""
+from .start import dominus
+from .helpers.core import DominusResponse
+
+__version__ = "0.3.0"
+__all__ = [
+    "dominus",
+    "DominusResponse",
+]

dominus/config/__init__.py

@@ -0,0 +1,24 @@
+"""SDK Configuration"""
+from .endpoints import (
+    SOVEREIGN_URL,
+    ARCHITECT_URL,
+    ORCHESTRATOR_URL,
+    WARDEN_URL,
+    get_service_url,
+    get_architect_url,
+    get_sovereign_url,
+    PROJECT_NUMBER,
+    REGION,
+)
+
+__all__ = [
+    "SOVEREIGN_URL",
+    "ARCHITECT_URL",
+    "ORCHESTRATOR_URL",
+    "WARDEN_URL",
+    "get_service_url",
+    "get_architect_url",
+    "get_sovereign_url",
+    "PROJECT_NUMBER",
+    "REGION",
+]

dominus/config/endpoints.py

@@ -0,0 +1,43 @@
+"""
+Dominus Orchestrator Endpoints
+
+Single backend URL for all services. The SDK now targets dominus-orchestrator
+which consolidates all service functionality.
+
+Usage:
+    from dominus.config.endpoints import BASE_URL
+"""
+
+# Cloud Run configuration
+PROJECT_NUMBER = "775398158805"
+REGION = "us-east4"
+
+# Single orchestrator URL - all services consolidated here
+BASE_URL = f"https://dominus-orchestrator-production-{PROJECT_NUMBER}.{REGION}.run.app"
+
+# Legacy aliases (all point to orchestrator now) - DEPRECATED
+SOVEREIGN_URL = BASE_URL
+ARCHITECT_URL = BASE_URL
+ORCHESTRATOR_URL = BASE_URL
+WARDEN_URL = BASE_URL
+
+
+def get_base_url() -> str:
+    """Get the dominus-orchestrator base URL."""
+    return BASE_URL
+
+
+# DEPRECATED - use get_base_url()
+def get_sovereign_url(environment: str = None) -> str:
+    """Deprecated: Use get_base_url() instead."""
+    return BASE_URL
+
+
+def get_architect_url(environment: str = None) -> str:
+    """Deprecated: Use get_base_url() instead."""
+    return BASE_URL
+
+
+def get_service_url(service: str, environment: str = None) -> str:
+    """Deprecated: Use get_base_url() instead. All services are now consolidated."""
+    return BASE_URL

dominus/errors.py

@@ -0,0 +1,201 @@
+"""
+Dominus SDK Error Classes
+
+Custom exceptions for the Dominus SDK with structured error information.
+"""
+from typing import Any, Dict, Optional
+
+
+class DominusError(Exception):
+    """
+    Base exception for all Dominus SDK errors.
+
+    Provides structured error information including HTTP status codes,
+    error messages, and optional details from the backend.
+
+    Attributes:
+        message: Human-readable error message
+        status_code: HTTP status code (if applicable)
+        details: Additional error details from backend
+        endpoint: The endpoint that was called (if applicable)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+        self.endpoint = endpoint
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"(status {self.status_code})")
+        if self.endpoint:
+            parts.append(f"at {self.endpoint}")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"DominusError(message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"details={self.details!r}, "
+            f"endpoint={self.endpoint!r})"
+        )
+
+
+class AuthenticationError(DominusError):
+    """Raised when authentication fails (invalid token, expired JWT, etc.)."""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        status_code: int = 401,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class AuthorizationError(DominusError):
+    """Raised when authorization fails (insufficient permissions)."""
+
+    def __init__(
+        self,
+        message: str = "Permission denied",
+        status_code: int = 403,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class NotFoundError(DominusError):
+    """Raised when a requested resource is not found."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        status_code: int = 404,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class ValidationError(DominusError):
+    """Raised when request validation fails."""
+
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        status_code: int = 400,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class ConflictError(DominusError):
+    """Raised when there's a conflict (duplicate key, version mismatch, etc.)."""
+
+    def __init__(
+        self,
+        message: str = "Conflict",
+        status_code: int = 409,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class ServiceError(DominusError):
+    """Raised when a backend service error occurs."""
+
+    def __init__(
+        self,
+        message: str = "Service error",
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class ConnectionError(DominusError):
+    """Raised when connection to the backend fails."""
+
+    def __init__(
+        self,
+        message: str = "Connection failed",
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class TimeoutError(DominusError):
+    """Raised when a request times out."""
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+class SecureTableError(DominusError):
+    """Raised when accessing a secure table without providing a reason."""
+
+    def __init__(
+        self,
+        message: str = "Access to secure table requires 'reason' parameter",
+        status_code: int = 403,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint)
+
+
+def raise_for_status(
+    status_code: int,
+    message: str,
+    details: Optional[Dict[str, Any]] = None,
+    endpoint: Optional[str] = None
+) -> None:
+    """
+    Raise appropriate DominusError subclass based on status code.
+
+    Args:
+        status_code: HTTP status code
+        message: Error message
+        details: Optional error details
+        endpoint: Optional endpoint that was called
+
+    Raises:
+        Appropriate DominusError subclass
+    """
+    error_classes = {
+        400: ValidationError,
+        401: AuthenticationError,
+        403: AuthorizationError,
+        404: NotFoundError,
+        409: ConflictError,
+        500: ServiceError,
+        502: ServiceError,
+        503: ServiceError,
+        504: TimeoutError,
+    }
+
+    error_class = error_classes.get(status_code, DominusError)
+    raise error_class(message, status_code, details, endpoint)

dominus/helpers/__init__.py

@@ -0,0 +1,2 @@
+"""Helper modules for CB Dominus SDK - Internal use only"""
+

dominus/helpers/auth.py

@@ -0,0 +1,49 @@
+"""
+Token and URL resolution helpers.
+
+Handles resolution of authentication token and service URLs
+with support for environment variables and hardcoded fallbacks.
+"""
+import os
+from typing import Optional
+
+
+def _resolve_token(hardcoded_token: Optional[str] = None) -> Optional[str]:
+    """
+    Resolve auth token.
+    
+    Priority:
+    1. Environment variable: DOMINUS_TOKEN
+    2. Hardcoded fallback (passed as parameter)
+    
+    Note: When fetching from Infisical via Sovereign, the secret is stored as
+    PROVISION_DOMINUS_TOKEN but should be set as DOMINUS_TOKEN in environment.
+    The PROVISION_ prefix is dropped when setting environment variables.
+    
+    Args:
+        hardcoded_token: Optional hardcoded token for development
+        
+    Returns:
+        Token string or None
+    """
+    token = os.getenv("DOMINUS_TOKEN")
+    if token:
+        return token
+    if hardcoded_token:
+        return hardcoded_token
+    return None
+
+
+def _resolve_sovereign_url(environment: str = None) -> str:
+    """
+    Resolve Sovereign base URL from SDK flat file config.
+
+    Args:
+        environment: Environment override (development, staging, production)
+
+    Returns:
+        Sovereign base URL string
+    """
+    from ..config.endpoints import get_sovereign_url
+    return get_sovereign_url(environment)
+

dominus/helpers/cache.py

@@ -0,0 +1,192 @@
+"""
+Internal cache with automatic encryption and circuit breaker.
+
+NOT exposed to SDK users - internal use only.
+"""
+import time
+import json
+import base64
+import random
+from typing import Dict, Tuple, Optional, Any
+from cryptography.fernet import Fernet
+from hashlib import sha256
+
+
+class CircuitBreaker:
+    """
+    Simple circuit breaker to prevent runaway retries.
+
+    States:
+    - CLOSED: Normal operation, requests pass through
+    - OPEN: Too many failures, requests blocked
+    - HALF_OPEN: Testing if service recovered
+
+    Prevents CPU/quota exhaustion from retry storms.
+    """
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        half_open_max_calls: int = 1
+    ):
+        self._failure_count = 0
+        self._failure_threshold = failure_threshold
+        self._recovery_timeout = recovery_timeout
+        self._half_open_max_calls = half_open_max_calls
+        self._state = self.CLOSED
+        self._last_failure_time: float = 0
+        self._half_open_calls = 0
+
+    @property
+    def state(self) -> str:
+        """Get current state, transitioning OPEN→HALF_OPEN if timeout elapsed."""
+        if self._state == self.OPEN:
+            if time.time() - self._last_failure_time >= self._recovery_timeout:
+                self._state = self.HALF_OPEN
+                self._half_open_calls = 0
+        return self._state
+
+    def can_execute(self) -> bool:
+        """Check if a request can be executed."""
+        state = self.state
+        if state == self.CLOSED:
+            return True
+        if state == self.HALF_OPEN:
+            return self._half_open_calls < self._half_open_max_calls
+        return False  # OPEN
+
+    def record_success(self) -> None:
+        """Record a successful call."""
+        if self._state == self.HALF_OPEN:
+            self._state = self.CLOSED
+        self._failure_count = 0
+        self._half_open_calls = 0
+
+    def record_failure(self) -> None:
+        """Record a failed call."""
+        self._failure_count += 1
+        self._last_failure_time = time.time()
+
+        if self._state == self.HALF_OPEN:
+            # Failed during recovery test, go back to OPEN
+            self._state = self.OPEN
+        elif self._failure_count >= self._failure_threshold:
+            self._state = self.OPEN
+
+    def record_half_open_call(self) -> None:
+        """Record a call attempt in HALF_OPEN state."""
+        self._half_open_calls += 1
+
+
+def exponential_backoff_with_jitter(
+    attempt: int,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    jitter: float = 0.5
+) -> float:
+    """
+    Calculate backoff delay with jitter to prevent thundering herd.
+
+    Args:
+        attempt: Zero-based attempt number
+        base_delay: Base delay in seconds
+        max_delay: Maximum delay cap
+        jitter: Jitter factor (0-1), adds randomness
+
+    Returns:
+        Delay in seconds
+    """
+    delay = min(base_delay * (2 ** attempt), max_delay)
+    jitter_range = delay * jitter
+    return delay + random.uniform(-jitter_range, jitter_range)
+
+
+class DominusCache:
+    """
+    Internal process-local cache with auto-encryption.
+
+    Used by dominus services only:
+    - Validation state
+    - Service URLs
+    - API responses
+
+    NOT accessible by SDK users.
+    """
+
+    def __init__(self, default_ttl: int = 300):
+        self._store: Dict[str, Tuple[bytes, float]] = {}
+        self._default_ttl = default_ttl
+        self._cipher: Optional[Fernet] = None
+
+    def set_encryption_key(self, token: str) -> None:
+        """Initialize encryption using auth token."""
+        if not token:
+            return
+        key = base64.urlsafe_b64encode(sha256(token.encode()).digest())
+        self._cipher = Fernet(key)
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get and decrypt, refresh TTL."""
+        entry = self._store.get(key)
+        if not entry:
+            return None
+
+        encrypted_value, expires_at = entry
+
+        # Check expiry
+        if time.time() >= expires_at:
+            del self._store[key]
+            return None
+
+        # Decrypt
+        if self._cipher:
+            try:
+                decrypted = self._cipher.decrypt(encrypted_value)
+                value = json.loads(decrypted.decode())
+            except Exception:
+                del self._store[key]
+                return None
+        else:
+            value = json.loads(encrypted_value.decode())
+
+        # Touch TTL
+        self._store[key] = (encrypted_value, time.time() + self._default_ttl)
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Encrypt and store."""
+        duration = ttl if ttl is not None else self._default_ttl
+
+        if self._cipher:
+            plaintext = json.dumps(value).encode()
+            encrypted_value = self._cipher.encrypt(plaintext)
+        else:
+            encrypted_value = json.dumps(value).encode()
+
+        self._store[key] = (encrypted_value, time.time() + duration)
+
+    def delete(self, key: str) -> bool:
+        """Delete key."""
+        return bool(self._store.pop(key, None))
+
+    def clear(self) -> int:
+        """Clear all."""
+        count = len(self._store)
+        self._store.clear()
+        return count
+
+
+# Internal singletons - NOT exported to users
+dominus_cache = DominusCache(default_ttl=300)
+
+# Circuit breakers for different services (prevents retry storms)
+sovereign_circuit_breaker = CircuitBreaker(
+    failure_threshold=5,    # Open after 5 consecutive failures
+    recovery_timeout=30.0,  # Try again after 30 seconds
+    half_open_max_calls=1   # Allow 1 test call in half-open state
+)