fbuild 1.2.8__py3-none-any.whl

fbuild/daemon/daemon_context.py

@@ -0,0 +1,293 @@
+"""
+Daemon Context - Centralized state management for fbuild daemon.
+
+This module provides the DaemonContext class which encapsulates all daemon state
+that was previously stored in global variables. This improves testability,
+makes dependencies explicit, and eliminates global mutable state.
+"""
+
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from fbuild.daemon.async_client import ClientConnectionManager
+from fbuild.daemon.compilation_queue import CompilationJobQueue
+from fbuild.daemon.configuration_lock import ConfigurationLockManager
+from fbuild.daemon.error_collector import ErrorCollector
+from fbuild.daemon.file_cache import FileCache
+from fbuild.daemon.firmware_ledger import FirmwareLedger
+from fbuild.daemon.lock_manager import ResourceLockManager
+from fbuild.daemon.operation_registry import OperationRegistry
+from fbuild.daemon.port_state_manager import PortStateManager
+from fbuild.daemon.shared_serial import SharedSerialManager
+from fbuild.daemon.status_manager import StatusManager
+from fbuild.daemon.subprocess_manager import SubprocessManager
+
+
+@dataclass
+class DaemonContext:
+    """Centralized context for all daemon state and subsystems.
+
+    This class replaces the 12 global variables in daemon.py with a single
+    context object that can be passed to functions explicitly. This improves:
+    - Testability: Mock the entire context in tests
+    - Clarity: Dependencies are explicit in function signatures
+    - Thread-safety: Locks are properly encapsulated
+    - Lifecycle: Cleanup is centralized in one place
+
+    Attributes:
+        daemon_pid: Process ID of the daemon
+        daemon_started_at: Unix timestamp when daemon was started
+        compilation_queue: Queue for managing parallel compilation jobs
+        operation_registry: Registry for tracking active/completed operations
+        subprocess_manager: Manager for daemon-spawned subprocesses
+        file_cache: Cache for file modification times
+        error_collector: Global error collector for operations
+        lock_manager: Unified resource lock manager for ports and projects
+        port_state_manager: Manager for tracking COM port states
+        status_manager: Manager for daemon status file operations
+        client_manager: Manager for async client connections with heartbeat
+        configuration_lock_manager: Centralized locking for (project, env, port) configs
+        firmware_ledger: Tracks deployed firmware on devices to avoid re-upload
+        shared_serial_manager: Manages shared serial port access for multiple clients
+        operation_in_progress: Flag indicating if any operation is running
+        operation_lock: Lock protecting the operation_in_progress flag
+    """
+
+    # Daemon identity
+    daemon_pid: int
+    daemon_started_at: float
+
+    # Subsystems
+    compilation_queue: CompilationJobQueue
+    operation_registry: OperationRegistry
+    subprocess_manager: SubprocessManager
+    file_cache: FileCache
+    error_collector: ErrorCollector
+    lock_manager: ResourceLockManager
+    port_state_manager: PortStateManager
+    status_manager: StatusManager
+
+    # New managers for centralized locking and shared state (Iteration 1-2)
+    client_manager: ClientConnectionManager
+    configuration_lock_manager: ConfigurationLockManager
+    firmware_ledger: FirmwareLedger
+    shared_serial_manager: SharedSerialManager
+
+    # Operation state
+    operation_in_progress: bool = False
+    operation_lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+def create_daemon_context(
+    daemon_pid: int,
+    daemon_started_at: float,
+    num_workers: int,
+    file_cache_path: Path,
+    status_file_path: Path,
+) -> DaemonContext:
+    """Factory function to create and initialize a DaemonContext.
+
+    This function initializes all daemon subsystems and returns a fully
+    configured DaemonContext ready for use.
+
+    Args:
+        daemon_pid: Process ID of the daemon
+        daemon_started_at: Unix timestamp when daemon started
+        num_workers: Number of compilation worker threads
+        file_cache_path: Path to the file cache JSON file
+        status_file_path: Path to the status file
+
+    Returns:
+        Fully initialized DaemonContext
+
+    Example:
+        >>> import os
+        >>> import time
+        >>> from pathlib import Path
+        >>>
+        >>> context = create_daemon_context(
+        ...     daemon_pid=os.getpid(),
+        ...     daemon_started_at=time.time(),
+        ...     num_workers=4,
+        ...     file_cache_path=Path.home() / ".fbuild" / "daemon" / "file_cache.json",
+        ...     status_file_path=Path.home() / ".fbuild" / "daemon" / "daemon_status.json"
+        ... )
+        >>> # Use context in request handlers
+        >>> process_build_request(request, context)
+    """
+    import logging
+
+    logging.info("Initializing daemon context...")
+
+    # Initialize compilation queue with worker pool
+    compilation_queue = CompilationJobQueue(num_workers=num_workers)
+    compilation_queue.start()
+    logging.info(f"Compilation queue started with {num_workers} workers")
+
+    # Initialize operation registry
+    logging.debug("Creating operation registry (max_history=100)...")
+    operation_registry = OperationRegistry(max_history=100)
+    logging.info("Operation registry initialized")
+
+    # Initialize subprocess manager
+    subprocess_manager = SubprocessManager()
+    logging.info("Subprocess manager initialized")
+
+    # Initialize file cache
+    logging.debug(f"Creating file cache (cache_file={file_cache_path})...")
+    file_cache = FileCache(cache_file=file_cache_path)
+    logging.info("File cache initialized")
+
+    # Initialize error collector
+    error_collector = ErrorCollector()
+    logging.info("Error collector initialized")
+
+    # Initialize lock manager
+    lock_manager = ResourceLockManager()
+    logging.info("Resource lock manager initialized")
+
+    # Initialize port state manager
+    port_state_manager = PortStateManager()
+    logging.info("Port state manager initialized")
+
+    # Initialize status manager (with port state manager and lock manager for status visibility)
+    logging.debug(f"Creating status manager (status_file={status_file_path})...")
+    status_manager = StatusManager(
+        status_file=status_file_path,
+        daemon_pid=daemon_pid,
+        daemon_started_at=daemon_started_at,
+        port_state_manager=port_state_manager,
+        lock_manager=lock_manager,
+    )
+    logging.info("Status manager initialized")
+
+    # Initialize new managers for centralized locking and shared state (Iteration 1-2)
+    client_manager = ClientConnectionManager()
+    logging.info("Client connection manager initialized")
+
+    configuration_lock_manager = ConfigurationLockManager()
+    logging.info("Configuration lock manager initialized")
+
+    firmware_ledger = FirmwareLedger()
+    logging.info(f"Firmware ledger initialized (path={firmware_ledger.ledger_path})")
+
+    shared_serial_manager = SharedSerialManager()
+    logging.info("Shared serial manager initialized")
+
+    # Register cleanup callbacks: when a client disconnects, release their resources
+    def on_client_disconnect(client_id: str) -> None:
+        """Cleanup callback for when a client disconnects."""
+        logging.info(f"Cleaning up resources for disconnected client: {client_id}")
+        # Release all configuration locks held by this client
+        released = configuration_lock_manager.release_all_client_locks(client_id)
+        if released > 0:
+            logging.info(f"Released {released} configuration locks for client {client_id}")
+        # Disconnect from shared serial sessions
+        shared_serial_manager.disconnect_client(client_id)
+
+    client_manager.register_cleanup_callback(on_client_disconnect)
+    logging.info("Client cleanup callback registered")
+
+    # Create context
+    context = DaemonContext(
+        daemon_pid=daemon_pid,
+        daemon_started_at=daemon_started_at,
+        compilation_queue=compilation_queue,
+        operation_registry=operation_registry,
+        subprocess_manager=subprocess_manager,
+        file_cache=file_cache,
+        error_collector=error_collector,
+        lock_manager=lock_manager,
+        port_state_manager=port_state_manager,
+        status_manager=status_manager,
+        client_manager=client_manager,
+        configuration_lock_manager=configuration_lock_manager,
+        firmware_ledger=firmware_ledger,
+        shared_serial_manager=shared_serial_manager,
+    )
+
+    logging.info("✅ Daemon context initialized successfully")
+    return context
+
+
+def cleanup_daemon_context(context: DaemonContext) -> None:
+    """Cleanup and shutdown all daemon subsystems in the context.
+
+    This function should be called during daemon shutdown to ensure all
+    resources are properly released.
+
+    Args:
+        context: The DaemonContext to clean up
+
+    Example:
+        >>> try:
+        ...     run_daemon(context)
+        ... finally:
+        ...     cleanup_daemon_context(context)
+    """
+    import logging
+
+    logging.info("Shutting down daemon context...")
+
+    # Shutdown shared serial manager first (closes all serial ports)
+    if context.shared_serial_manager:
+        try:
+            context.shared_serial_manager.shutdown()
+            logging.info("Shared serial manager shut down")
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during shared serial manager shutdown")
+            raise
+        except Exception as e:
+            logging.error(f"Error shutting down shared serial manager: {e}")
+
+    # Clear all configuration locks
+    if context.configuration_lock_manager:
+        try:
+            cleared = context.configuration_lock_manager.clear_all_locks()
+            logging.info(f"Cleared {cleared} configuration locks during shutdown")
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during configuration lock manager cleanup")
+            raise
+        except Exception as e:
+            logging.error(f"Error clearing configuration locks: {e}")
+
+    # Clear all client connections
+    if context.client_manager:
+        try:
+            cleared = context.client_manager.clear_all_clients()
+            logging.info(f"Cleared {cleared} client connections during shutdown")
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during client manager cleanup")
+            raise
+        except Exception as e:
+            logging.error(f"Error clearing client connections: {e}")
+
+    # Shutdown compilation queue
+    if context.compilation_queue:
+        try:
+            context.compilation_queue.shutdown()
+            logging.info("Compilation queue shut down")
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during compilation queue shutdown")
+            raise
+        except Exception as e:
+            logging.error(f"Error shutting down compilation queue: {e}")
+
+    # Clear all locks during shutdown
+    if context.lock_manager:
+        try:
+            cleared = context.lock_manager.clear_all_locks()
+            logging.info(f"Cleared {cleared} locks during shutdown")
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during lock manager cleanup")
+            raise
+        except Exception as e:
+            logging.error(f"Error clearing locks: {e}")
+
+    # Log cleanup of other subsystems (they don't have explicit shutdown methods)
+    logging.debug("Cleaning up subprocess manager...")
+    logging.debug("Cleaning up error collector...")
+    logging.debug("Firmware ledger persists to disk - no cleanup needed")
+
+    logging.info("✅ Daemon context cleaned up")

fbuild/daemon/error_collector.py

@@ -0,0 +1,263 @@
+"""
+Error Collector - Structured error collection for async operations.
+
+This module provides error collection and aggregation for asynchronous build
+operations, replacing simple exception handling with structured error tracking.
+"""
+
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class ErrorSeverity(Enum):
+    """Severity level of a build error."""
+
+    WARNING = "warning"
+    ERROR = "error"
+    FATAL = "fatal"
+
+
+@dataclass
+class BuildError:
+    """Single build error."""
+
+    severity: ErrorSeverity
+    phase: str  # "download", "compile", "link", "upload"
+    file_path: Optional[str]
+    error_message: str
+    stderr: Optional[str] = None
+    stdout: Optional[str] = None
+    timestamp: float = field(default_factory=time.time)
+
+    def format(self) -> str:
+        """Format error as human-readable string.
+
+        Returns:
+            Formatted error message
+        """
+        lines = [f"[{self.severity.value.upper()}] {self.phase}: {self.error_message}"]
+
+        if self.file_path:
+            lines.append(f"  File: {self.file_path}")
+
+        if self.stderr:
+            # Truncate stderr to reasonable length
+            stderr_preview = self.stderr[:500]
+            if len(self.stderr) > 500:
+                stderr_preview += "... (truncated)"
+            lines.append(f"  stderr: {stderr_preview}")
+
+        return "\n".join(lines)
+
+
+class ErrorCollector:
+    """Collects errors during async build operations."""
+
+    def __init__(self, max_errors: int = 100):
+        """Initialize error collector.
+
+        Args:
+            max_errors: Maximum number of errors to collect
+        """
+        self.errors: list[BuildError] = []
+        self.lock = threading.Lock()
+        self.max_errors = max_errors
+
+        logging.debug(f"ErrorCollector initialized (max_errors={max_errors})")
+
+    def add_error(self, error: BuildError) -> None:
+        """Add error to collection.
+
+        Args:
+            error: Build error to add
+        """
+        with self.lock:
+            if len(self.errors) >= self.max_errors:
+                logging.warning(f"ErrorCollector full ({self.max_errors} errors), dropping oldest")
+                self.errors.pop(0)
+
+            self.errors.append(error)
+
+    def get_errors(self, severity: Optional[ErrorSeverity] = None) -> list[BuildError]:
+        """Get all errors, optionally filtered by severity.
+
+        Args:
+            severity: Filter by severity (None = all errors)
+
+        Returns:
+            List of build errors
+        """
+        logging.debug(f"Retrieving errors (severity filter: {severity.value if severity else 'None'})")
+        with self.lock:
+            if severity:
+                filtered = [e for e in self.errors if e.severity == severity]
+                logging.debug(f"Filtered {len(filtered)} errors by severity {severity.value} (total: {len(self.errors)})")
+                return filtered
+            logging.debug(f"Returning all {len(self.errors)} errors")
+            return self.errors.copy()
+
+    def get_errors_by_phase(self, phase: str) -> list[BuildError]:
+        """Get errors for a specific phase.
+
+        Args:
+            phase: Phase to filter by
+
+        Returns:
+            List of build errors for the phase
+        """
+        with self.lock:
+            phase_errors = [e for e in self.errors if e.phase == phase]
+            logging.debug(f"Found {len(phase_errors)} errors in phase '{phase}' (total: {len(self.errors)})")
+            return phase_errors
+
+    def has_fatal_errors(self) -> bool:
+        """Check if any fatal errors occurred.
+
+        Returns:
+            True if fatal errors exist
+        """
+        with self.lock:
+            has_fatal = any(e.severity == ErrorSeverity.FATAL for e in self.errors)
+            fatal_count = sum(1 for e in self.errors if e.severity == ErrorSeverity.FATAL)
+            logging.debug(f"Fatal error check result: {has_fatal} ({fatal_count} fatal errors)")
+            return has_fatal
+
+    def has_errors(self) -> bool:
+        """Check if any errors (non-warning) occurred.
+
+        Returns:
+            True if errors exist
+        """
+        logging.debug("Checking for errors (non-warning)")
+        with self.lock:
+            has_errs = any(e.severity in (ErrorSeverity.ERROR, ErrorSeverity.FATAL) for e in self.errors)
+            error_count = sum(1 for e in self.errors if e.severity in (ErrorSeverity.ERROR, ErrorSeverity.FATAL))
+            logging.debug(f"Error check result: {has_errs} ({error_count} errors or fatal)")
+            return has_errs
+
+    def has_warnings(self) -> bool:
+        """Check if any warnings occurred.
+
+        Returns:
+            True if warnings exist
+        """
+        with self.lock:
+            has_warn = any(e.severity == ErrorSeverity.WARNING for e in self.errors)
+            warning_count = sum(1 for e in self.errors if e.severity == ErrorSeverity.WARNING)
+            logging.debug(f"Warning check result: {has_warn} ({warning_count} warnings)")
+            return has_warn
+
+    def get_error_count(self) -> dict[str, int]:
+        """Get count of errors by severity.
+
+        Returns:
+            Dictionary with counts by severity
+        """
+        with self.lock:
+            counts = {
+                "warnings": sum(1 for e in self.errors if e.severity == ErrorSeverity.WARNING),
+                "errors": sum(1 for e in self.errors if e.severity == ErrorSeverity.ERROR),
+                "fatal": sum(1 for e in self.errors if e.severity == ErrorSeverity.FATAL),
+                "total": len(self.errors),
+            }
+        logging.debug(f"Error counts: {counts['total']} total ({counts['fatal']} fatal, {counts['errors']} errors, {counts['warnings']} warnings)")
+        return counts
+
+    def format_errors(self, max_errors: Optional[int] = None) -> str:
+        """Format all errors as human-readable string.
+
+        Args:
+            max_errors: Maximum number of errors to include (None = all)
+
+        Returns:
+            Formatted error report
+        """
+        logging.debug(f"Formatting errors (max_errors: {max_errors})")
+        with self.lock:
+            if not self.errors:
+                return "No errors"
+
+            errors_to_show = self.errors if max_errors is None else self.errors[:max_errors]
+            logging.debug(f"Formatting {len(errors_to_show)} errors (total: {len(self.errors)})")
+            lines = []
+
+            for err in errors_to_show:
+                lines.append(err.format())
+
+            if max_errors and len(self.errors) > max_errors:
+                lines.append(f"\n... and {len(self.errors) - max_errors} more errors")
+
+            # Add summary
+            counts = self.get_error_count()
+            summary = f"\nSummary: {counts['fatal']} fatal, {counts['errors']} errors, {counts['warnings']} warnings"
+            lines.append(summary)
+
+            formatted = "\n\n".join(lines)
+            logging.debug(f"Error formatting complete: {len(lines)} sections, {len(formatted)} characters")
+            return formatted
+
+    def format_summary(self) -> str:
+        """Format a brief summary of errors.
+
+        Returns:
+            Brief error summary
+        """
+        counts = self.get_error_count()
+        if counts["total"] == 0:
+            return "No errors"
+
+        parts = []
+        if counts["fatal"] > 0:
+            parts.append(f"{counts['fatal']} fatal")
+        if counts["errors"] > 0:
+            parts.append(f"{counts['errors']} errors")
+        if counts["warnings"] > 0:
+            parts.append(f"{counts['warnings']} warnings")
+
+        summary = ", ".join(parts)
+        return summary
+
+    def clear(self) -> None:
+        """Clear all collected errors."""
+        with self.lock:
+            error_count = len(self.errors)
+            self.errors.clear()
+
+        if error_count > 0:
+            logging.info(f"Cleared {error_count} errors")
+
+    def get_first_fatal_error(self) -> Optional[BuildError]:
+        """Get the first fatal error encountered.
+
+        Returns:
+            First fatal error or None
+        """
+        with self.lock:
+            for error in self.errors:
+                if error.severity == ErrorSeverity.FATAL:
+                    return error
+        return None
+
+    def get_compilation_errors(self) -> list[BuildError]:
+        """Get all compilation-phase errors.
+
+        Returns:
+            List of compilation errors
+        """
+        compilation_errors = self.get_errors_by_phase("compile")
+        logging.debug(f"Found {len(compilation_errors)} compilation errors")
+        return compilation_errors
+
+    def get_link_errors(self) -> list[BuildError]:
+        """Get all link-phase errors.
+
+        Returns:
+            List of link errors
+        """
+        link_errors = self.get_errors_by_phase("link")
+        logging.debug(f"Found {len(link_errors)} link errors")
+        return link_errors