xenfra-sdk 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

xenfra_sdk/events.py

@@ -0,0 +1,254 @@
+"""
+Xenfra Events - Structured Event Streaming for Deployment Observability.
+
+This module provides deterministic, JSON-serializable events for tracking
+deployment progress. No AI, no guessing - just structured data.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DeploymentPhase(str, Enum):
+    """Deployment phases mapped to biological metaphors (Zen Dashboard)."""
+    # Phase 1: Setup
+    DNA_ENCODING = "DNA_ENCODING"  # SSH key setup, validation
+    # Phase 2: Asset Generation
+    CELL_BLUEPRINT = "CELL_BLUEPRINT"  # Dockerfile, docker-compose generation
+    # Phase 3: Cloud-init
+    GENESIS_SCRIPT = "GENESIS_SCRIPT"  # Cloud-init script creation
+    # Phase 4: Droplet Creation
+    CELL_BIRTH = "CELL_BIRTH"  # Droplet provisioning
+    # Phase 5: Polling/SSH
+    NEURAL_SYNC = "NEURAL_SYNC"  # Waiting for SSH, polling
+    # Phase 6: Code Upload
+    GENOME_TRANSFER = "GENOME_TRANSFER"  # Git clone or file upload
+    # Phase 6.5: Asset Write
+    MEMBRANE_FORMATION = "MEMBRANE_FORMATION"  # Writing deployment assets
+    # Phase 7: Container Build
+    CELL_REIFY = "CELL_REIFY"  # Docker build and start
+    # Phase 8: Verification
+    VITALS_CHECK = "VITALS_CHECK"  # Health check
+    # Phase 9: Persistence
+    MEMORY_COMMIT = "MEMORY_COMMIT"  # Database persistence
+    # Error states
+    APOPTOSIS = "APOPTOSIS"  # Cleanup on failure
+    NECROSIS = "NECROSIS"  # Unrecoverable failure
+
+
+class EventStatus(str, Enum):
+    """Status of an event within a phase."""
+    STARTED = "started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class BuildEvent(BaseModel):
+    """
+    Structured event for deployment progress tracking.
+
+    100% deterministic - no AI inference, just JSON serialization.
+    """
+    phase: DeploymentPhase
+    status: EventStatus
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    message: str = ""
+    progress_percent: Optional[int] = Field(None, ge=0, le=100)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {
+        "populate_by_name": True,
+        "arbitrary_types_allowed": True
+    }
+
+    def to_sse(self) -> str:
+        """Format as Server-Sent Event."""
+        return f"data: {self.model_dump_json()}\n\n"
+
+
+class WorkerHeartbeat(BaseModel):
+    """
+    Heartbeat signal from a background deployment task.
+
+    If no heartbeat received for 90 seconds, task is considered STALE.
+    """
+    task_id: str
+    deployment_id: int
+    phase: DeploymentPhase
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    is_alive: bool = True
+    last_activity: str = ""
+
+    model_config = {
+        "populate_by_name": True,
+        "arbitrary_types_allowed": True
+    }
+
+
+class DropletHeartbeat(BaseModel):
+    """
+    Heartbeat callback from cloud-init on the droplet.
+
+    Sent via curl when the droplet's network is ready.
+    """
+    droplet_id: int
+    status: str  # "network_ready", "cloud_init_complete", "docker_ready"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    ip_address: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class EventEmitter:
+    """
+    Event emitter for deployment progress tracking.
+
+    Wraps callback functions to emit structured events.
+    """
+
+    def __init__(
+        self,
+        logger: Optional[Callable[[str], None]] = None,
+        event_callback: Optional[Callable[[BuildEvent], None]] = None,
+    ):
+        """
+        Initialize the event emitter.
+
+        Args:
+            logger: Traditional string logger (backward compatibility)
+            event_callback: Structured event callback (for SSE/WebSocket)
+        """
+        self.logger = logger or (lambda msg: None)
+        self.event_callback = event_callback
+        self.events: List[BuildEvent] = []
+        self.current_phase: Optional[DeploymentPhase] = None
+
+    def start(self):
+        """Reset the event emitter for a new trace."""
+        self.events = []
+        self.current_phase = None
+        self.logger("--- Starting Event Stream ---")
+
+    def emit(
+        self,
+        phase: DeploymentPhase,
+        status: EventStatus,
+        message: str = "",
+        progress_percent: Optional[int] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> BuildEvent:
+        """
+        Emit a structured event.
+
+        Args:
+            phase: The deployment phase
+            status: Status within the phase
+            message: Human-readable message
+            progress_percent: Optional progress (0-100)
+            metadata: Additional structured data
+
+        Returns:
+            The emitted BuildEvent
+        """
+        event = BuildEvent(
+            phase=phase,
+            status=status,
+            message=message,
+            progress_percent=progress_percent,
+            metadata=metadata or {},
+        )
+
+        self.events.append(event)
+        self.current_phase = phase
+
+        # Backward compatibility: also log as string
+        self.logger(f"[{phase.value}] {status.value}: {message}")
+
+        # Structured callback
+        if self.event_callback:
+            self.event_callback(event)
+
+        return event
+
+    def start_phase(
+        self,
+        phase: DeploymentPhase,
+        message: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> BuildEvent:
+        """Convenience method to start a phase."""
+        return self.emit(phase, EventStatus.STARTED, message, metadata=metadata)
+
+    def complete_phase(
+        self,
+        phase: DeploymentPhase,
+        message: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> BuildEvent:
+        """Convenience method to complete a phase."""
+        return self.emit(phase, EventStatus.COMPLETED, message, progress_percent=100, metadata=metadata)
+
+    def fail_phase(
+        self,
+        phase: DeploymentPhase,
+        message: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> BuildEvent:
+        """Convenience method to mark a phase as failed."""
+        return self.emit(phase, EventStatus.FAILED, message, metadata=metadata)
+
+    def progress(
+        self,
+        phase: DeploymentPhase,
+        percent: int,
+        message: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> BuildEvent:
+        """Convenience method to report progress within a phase."""
+        return self.emit(phase, EventStatus.IN_PROGRESS, message, progress_percent=percent, metadata=metadata)
+
+    def get_events(self) -> List[BuildEvent]:
+        """Get all emitted events."""
+        return self.events.copy()
+
+    def get_last_event(self) -> Optional[BuildEvent]:
+        """Get the most recent event."""
+        return self.events[-1] if self.events else None
+
+
+# Phase progress mapping (for calculating overall progress)
+PHASE_WEIGHTS = {
+    DeploymentPhase.DNA_ENCODING: 5,
+    DeploymentPhase.CELL_BLUEPRINT: 10,
+    DeploymentPhase.GENESIS_SCRIPT: 5,
+    DeploymentPhase.CELL_BIRTH: 15,
+    DeploymentPhase.NEURAL_SYNC: 20,
+    DeploymentPhase.GENOME_TRANSFER: 15,
+    DeploymentPhase.MEMBRANE_FORMATION: 5,
+    DeploymentPhase.CELL_REIFY: 15,
+    DeploymentPhase.VITALS_CHECK: 5,
+    DeploymentPhase.MEMORY_COMMIT: 5,
+}
+
+
+def calculate_overall_progress(events: List[BuildEvent]) -> int:
+    """
+    Calculate overall deployment progress from events.
+
+    Returns percentage (0-100) based on completed phases.
+    """
+    completed_weight = 0
+    total_weight = sum(PHASE_WEIGHTS.values())
+
+    completed_phases = set()
+    for event in events:
+        if event.status == EventStatus.COMPLETED and event.phase in PHASE_WEIGHTS:
+            completed_phases.add(event.phase)
+
+    for phase in completed_phases:
+        completed_weight += PHASE_WEIGHTS.get(phase, 0)
+
+    return int((completed_weight / total_weight) * 100)

xenfra_sdk/exceptions.py

@@ -17,3 +17,12 @@ class XenfraAPIError(XenfraError):
         self.status_code = status_code
         self.detail = detail
         super().__init__(f"API Error {status_code}: {detail}")
+
+
+class DeploymentError(XenfraError):
+    """Custom exception for deployment failures."""
+
+    def __init__(self, message, stage="Unknown"):
+        self.message = message
+        self.stage = stage
+        super().__init__(f"Deployment failed at stage '{stage}': {message}")

xenfra_sdk/governance.py

@@ -0,0 +1,150 @@
+"""
+Xenfra Governance - Tier-Based Resource Limits.
+
+This module defines deterministic resource limits based on user tier.
+No AI, no guessing - just tier → limits mapping.
+"""
+
+from enum import Enum
+from typing import Dict
+from pydantic import BaseModel
+
+
+class UserTier(str, Enum):
+    """User subscription tiers."""
+    FREE = "FREE"
+    JUNIOR_SRE = "JUNIOR_SRE"
+    SENIOR_SRE = "SENIOR_SRE"
+    PRO = "PRO"  # Alias for JUNIOR_SRE
+    ENTERPRISE = "ENTERPRISE"  # Alias for SENIOR_SRE
+
+
+class ResourceLimits(BaseModel):
+    """Docker cgroups resource limits."""
+    memory: str = "512m"  # Docker memory limit format
+    cpus: float = 0.5  # CPU cores (can be fractional)
+    memory_reserved: str = "128m"  # Minimum guaranteed memory
+    cpus_reserved: float = 0.25  # Minimum guaranteed CPU
+
+
+# Tier-based resource limits - deterministic mapping
+TIER_RESOURCE_LIMITS: Dict[UserTier, ResourceLimits] = {
+    UserTier.FREE: ResourceLimits(
+        memory="512m",
+        cpus=0.5,
+        memory_reserved="128m",
+        cpus_reserved=0.25,
+    ),
+    UserTier.JUNIOR_SRE: ResourceLimits(
+        memory="2g",
+        cpus=1.0,
+        memory_reserved="512m",
+        cpus_reserved=0.5,
+    ),
+    UserTier.SENIOR_SRE: ResourceLimits(
+        memory="4g",
+        cpus=2.0,
+        memory_reserved="1g",
+        cpus_reserved=1.0,
+    ),
+}
+
+# Add aliases for tiers
+TIER_RESOURCE_LIMITS[UserTier.PRO] = TIER_RESOURCE_LIMITS[UserTier.JUNIOR_SRE]
+TIER_RESOURCE_LIMITS[UserTier.ENTERPRISE] = TIER_RESOURCE_LIMITS[UserTier.SENIOR_SRE]
+
+# Tier-based polling intervals (seconds)
+TIER_POLLING_INTERVALS: Dict[UserTier, int] = {
+    UserTier.FREE: 150,
+    UserTier.JUNIOR_SRE: 60,
+    UserTier.SENIOR_SRE: 15,
+}
+TIER_POLLING_INTERVALS[UserTier.PRO] = TIER_POLLING_INTERVALS[UserTier.JUNIOR_SRE]
+TIER_POLLING_INTERVALS[UserTier.ENTERPRISE] = TIER_POLLING_INTERVALS[UserTier.SENIOR_SRE]
+
+# Tier-based node limits
+TIER_NODE_LIMITS: Dict[UserTier, int] = {
+    UserTier.FREE: 1,
+    UserTier.JUNIOR_SRE: 10,
+    UserTier.SENIOR_SRE: 25,
+}
+
+# Tier-based auto-heal limits (concurrent fixes)
+TIER_AUTO_HEAL_LIMITS: Dict[UserTier, int] = {
+    UserTier.FREE: 0,  # Manual fixes only
+    UserTier.JUNIOR_SRE: 3,  # 3 auto-heal loops
+    UserTier.SENIOR_SRE: 10,  # Twin isolation/sandboxing
+}
+
+
+def get_resource_limits(tier: str) -> ResourceLimits:
+    """
+    Get resource limits for a user tier.
+
+    Args:
+        tier: User tier string (FREE, JUNIOR_SRE, SENIOR_SRE)
+
+    Returns:
+        ResourceLimits object with cgroups configuration
+    """
+    try:
+        user_tier = UserTier(tier.upper())
+    except ValueError:
+        # Unknown tier defaults to FREE
+        user_tier = UserTier.FREE
+
+    return TIER_RESOURCE_LIMITS[user_tier]
+
+
+def get_polling_interval(tier: str) -> int:
+    """
+    Get polling interval for a user tier.
+
+    Args:
+        tier: User tier string
+
+    Returns:
+        Polling interval in seconds
+    """
+    try:
+        user_tier = UserTier(tier.upper())
+    except ValueError:
+        user_tier = UserTier.FREE
+
+    return TIER_POLLING_INTERVALS[user_tier]
+
+
+def get_node_limit(tier: str) -> int:
+    """
+    Get maximum nodes allowed for a user tier.
+
+    Args:
+        tier: User tier string
+
+    Returns:
+        Maximum number of nodes
+    """
+    try:
+        user_tier = UserTier(tier.upper())
+    except ValueError:
+        user_tier = UserTier.FREE
+
+    return TIER_NODE_LIMITS[user_tier]
+
+
+def get_auto_heal_limit(tier: str) -> int:
+    """
+    Get auto-heal limit for a user tier.
+
+    Args:
+        tier: User tier string
+
+    Returns:
+        Maximum concurrent auto-heal operations
+    """
+    try:
+        user_tier = UserTier(tier.upper())
+    except ValueError:
+        user_tier = UserTier.FREE
+
+    return TIER_AUTO_HEAL_LIMITS[user_tier]